Give Claude a Long-Term Memory

Every conversation with Claude starts from zero. You explain your project, your stack, your decisions — and next session, it's all gone. You're back to square one.

Memory Vault's MCP integration fixes that. Four tools that Claude can use mid-conversation to store and retrieve memories. No copy-pasting context, no system prompts with walls of text. Claude just remembers.

What MCP is

The Model Context Protocol is how Claude connects to external tools. You register a server, Claude discovers the tools it exposes, and uses them when relevant. The server communicates over stdio — no HTTP, no ports, no authentication layer. It's a local process that Claude talks to directly.

Memory Vault runs as an MCP server with four tools:

recall — search your memories with hybrid search (vector + full-text + RRF merging). Supports filtering by space, date, and result limits. Query enrichment generates variations automatically for better recall.

remember — store a new memory. The text gets embedded, auto-classified (decision, lesson, preference, pattern, or fact), and assigned an importance score. Exact duplicates are detected and rejected.

forget — soft-delete a memory by chunk ID. The chunk stays in the database but is excluded from future searches. Recoverable if needed.

memory_status — check system health: database connection, chunk counts per space, embedding model info, query statistics.

Plus two resources (memory://spaces and memory://stats) for listing spaces and viewing statistics.

How it works in practice

You're working on a project. You make a decision — say, "we're using PostgreSQL for everything, no Redis cache." You tell Claude to remember it.

Claude calls remember with the text. Memory Vault embeds it, classifies it as a "decision" (importance: 0.8), stores it in the database.

Next week, different session, you're discussing caching. Claude calls recall with "caching strategy" and gets back your earlier decision with the reasoning. No re-explanation needed.

This compounds. Over weeks and months, the memory builds up: architecture decisions, coding conventions, lessons learned, project context. Every session starts with context instead of a blank slate.

Setup — two minutes

You need Memory Vault running (either via Docker or manual install) and a .mcp.json config file.

If you're using Docker

git clone https://github.com/MihaiBuilds/memory-vault.git
cd memory-vault
docker compose up -d

Configure Claude Code

Create a .mcp.json in your project directory:

{
  "mcpServers": {
    "memory-vault": {
      "command": "python",
      "args": ["-m", "src.mcp"],
      "cwd": "/path/to/memory-vault",
      "env": {
        "PYTHONPATH": "/path/to/memory-vault",
        "DB_HOST": "localhost",
        "DB_PORT": "5432",
        "DB_NAME": "memory_vault",
        "DB_USER": "memory_vault",
        "DB_PASSWORD": "memory_vault"
      }
    }
  }
}

Replace /path/to/memory-vault with your actual path. If you're using Docker, make sure port 5432 is exposed (it is by default in the compose file).

Claude Desktop uses the same config format — add it in Settings, Developer, Edit Config.

Verify

Open a new Claude Code session and ask:

"Use memory_status to check the memory system."

Claude will call the tool and report back: database status, chunk counts, embedding model. If it works, you're done.

Technical decisions

Stdio transport, not HTTP. MCP supports both, but stdio is simpler for a local tool. No CORS, no port conflicts, no authentication. The server starts as a subprocess and communicates through stdin/stdout. When Claude exits, the server exits.

Auto-classification. When you store a memory, it gets classified by keyword heuristics: decisions ("decided", "going with", "locked"), lessons ("learned", "mistake", "never again"), preferences ("always use", "convention"), patterns ("architecture", "approach"). This sets the importance score — decisions at 0.8, facts at 0.5. Simple, fast, no LLM call needed.

Soft-delete for forget. Forgetting doesn't delete the row. It sets importance to 0 and adds a forgotten: true flag in metadata. The chunk drops out of search results but stays in the database. If you need it back, it's recoverable. Hard deletes are irreversible; soft deletes are forgiving.

No dedup or conflict detection in the free tier. My personal system has SHA-256 exact-match dedup and cosine similarity near-dupe detection, plus conflict detection that finds contradicting memories. Those are complex features that belong in the PRO tier. The free version does basic hash-based duplicate rejection — if you store the exact same text twice, it catches it. Good enough for most users.

What's next

Milestone 5 is the web dashboard — a React app for searching, browsing, and ingesting memories through a visual interface instead of the CLI. After that, the REST API (M6) and knowledge graph (M7).

The repo: github.com/MihaiBuilds/memory-vault