memory-mcp

Local-first MCP server that gives Claude (or any MCP client) long-term memory over past dev sessions. Session metadata is embedded and stored in Postgres/pgvector; semantic search returns cheap metadata hits, and only the sessions you judge relevant get their full content resolved and loaded.

Runs entirely on your machine: local Postgres via Docker, local embedding model via @huggingface/transformers. No external API calls, no data leaves the box.

How it works

Three MCP tools, mirrored 1:1 by MemoryStore (src/core/memoryStore.ts):

The intended flow: search_sessions first (cheap, metadata-only) → the agent decides which hits matter → get_session_files only for those → read the resolved paths last. This keeps token spend proportional to relevance instead of reading every candidate up front.

This project pairs naturally with a "write a session summary to a file" workflow (e.g. a /session-summary command that writes to an Obsidian vault) — index_session is called after the summary file is written, with sessionPath pointing at it. Sample commands for exactly this are included — see Commands below.

Architecture

• src/server.ts — registers the three MCP tools against a MemoryStore, transport-agnostic.

• src/core/memoryStore.ts — execution layer: SQL + embedding calls, independent of transport.

• src/transport/stdio.ts — stdio transport (the only one wired up today).

• src/embeddings/ — embedding provider abstraction; workerEmbeddingProvider.ts runs the model (@huggingface/transformers, default Xenova/bge-small-en-v1.5) in a worker thread so embedding doesn't block the main event loop.

• src/db/ — Postgres client, connection pooling, and schema.sql (pgvector table + HNSW index).

• src/scripts/ — one-off setup scripts (downloadModel.ts, registerMcp.ts).

Related MCP server: AIVectorMemory

Setup

Prerequisites: Node >= 20, pnpm, Docker.

pnpm setup

This runs, in order: pnpm install → start Postgres via Docker (db:up) → download the embedding model locally → tsc build → register the server with the Claude CLI (claude mcp add, prompts for global vs. project scope).

Each step can also be run individually:

pnpm install
pnpm db:up          # docker compose up -d --wait
pnpm model:download  # caches the embedding model into .models/
pnpm build           # tsc + copy schema.sql into dist/
pnpm mcp:register    # claude mcp add memory-mcp -> node dist/index.js

mcp:register detects an existing registration and offers to reconfigure it; pass --global or --local to skip the interactive prompt.

pnpm setup then asks a final question — "Register commands?" — see below.

Commands

templates/commands/ ships two sample Claude Code slash commands, generalized for any user:

Both templates reference the vault directory as __VAULT_DIR__ — wherever you want session notes written (an Obsidian vault, a plain folder, anything readable/writable).

Run pnpm commands:register (or answer "yes" at the end of pnpm setup) to install them:

1. Prompts for the vault directory (defaults to ~/Documents/obsidian/Claude) and substitutes it for every __VAULT_DIR__ in the templates.

2. Writes the rendered files to $CLAUDE_CONFIG_DIR/commands/ if CLAUDE_CONFIG_DIR is set, otherwise ~/.claude/commands/ — the same resolution order the claude CLI itself uses (see mcp:register above).

3. Asks before overwriting a command file that already exists at the destination.

Re-run pnpm commands:register any time to update an existing install or point it at a different vault directory.

Migrating pre-existing sessions (opt-in, manual)

If you already have a vault of session notes written before memory-mcp existed (or before /session-summary started calling index_session), templates/commands/session-migrate.md backfills them. It's deliberately not installed by commands:register or pnpm setup — it's a one-off maintenance operation, not part of the standard install:

cp templates/commands/session-migrate.md "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/"

Then run /session-migrate and give it the vault directory when asked. It reads each note, extracts the structured fields (date, branch, tags, decisions, files touched), writes a proper summary, and calls index_session — capped at 100 notes per run, since indexing requires reading and summarizing every note in full and the token cost stops being trivial past that. It tracks what it's already indexed in <vault>/.memory-mcp-migrated.json, so re-running only picks up notes added since the last pass.

Configuration

Copy .env.example to .env to override defaults:

The schema (src/db/schema.sql) is applied automatically on server startup (ensureSchema) — no separate migration step.

Development

pnpm dev         # tsx watch src/index.ts
pnpm typecheck   # tsc --noEmit
pnpm db:logs     # docker compose logs -f postgres
pnpm db:down     # docker compose down

The server speaks MCP over stdio (src/index.ts → startStdioTransport), so pnpm dev alone won't do much interactively — point an MCP client (e.g. Claude Code via mcp:register) at it, or drive MemoryStore directly for testing.