SMG Claude Memory MCP

Persistent, searchable project memory for Claude Code. Each project has its own brain — decisions, rules, architecture notes, sprint goals — all stored locally in a vector database and automatically loaded every time you start a new session.

What problem does this solve? Claude forgets everything between sessions. You end up re-explaining the same things over and over, rules get missed, past decisions get lost when your context window fills up, and switching machines means starting from scratch. This MCP gives Claude a real memory — one that survives restarts, context overflows, and team handoffs.

---

In Plain English

What does this project actually do?

It gives Claude permanent memory per project. Think of it as a separate brain for each of your projects.

When you’re working on something, you make decisions (“we chose PostgreSQL”), set rules (“always run tests before commits”), and plan sprints. Normally, all of that is forgotten when a new session starts, or gets scattered across .md files that Claude has to re-read every time.

With this MCP:

• When you make a decision → Claude stores it automatically
• When you ask about something → Claude searches memory first, then answers
• When you start a new session → All the important stuff loads automatically
• When you set a rule (“always do X”) → Claude won’t forget it again

Three things users should understand

1. Semantic search — Ask “what database did we pick?” and it finds the PostgreSQL decision, even if you never typed “PostgreSQL” in your query. It searches by meaning, not keywords.

2. Project isolation — Every project has its own separate memory database. Memories from project-A never leak into project-B.

3. Team collaboration — You can move a project’s memory into the project folder, commit it to git, and your teammates get the same memory after git pull.

The technical one-liner

“An MCP server for Claude Code that stores per-project memory in local DuckDB with vector embeddings. It remembers decisions, rules, and sprint notes, retrieves them via semantic search, and auto-loads full context at session start — so Claude never forgets anything.”

What you’ll feel day-to-day

• You won’t need to re-explain your project’s decisions every session
• Rules you’ve set stick — Claude can’t skip them (enforced by hooks)
• Context window overflows don’t lose important info (it’s in the DB)
• Switching machines? git pull + one command, and Claude picks up exactly where you left off
• Onboarding a teammate’s Claude? Same thing — they get your whole project memory instantly

---

FAQ — Common Questions, Clear Answers

Q: When I run make_portable, does it move ALL projects’ memory to git, or just the one I’m working on?

Just the one project. Other projects are never touched.

Each project has its own separate .duckdb file:

~/.memory-mcp/
├── registry.duckdb              ← List of projects (name + path)
└── projects/
    ├── my-app.duckdb            ← ONLY my-app's memory
    ├── smg-analytics.duckdb     ← ONLY smg-analytics's memory
    └── other-project.duckdb     ← ONLY other-project's memory

When you run:

/smg-memory portable /Users/you/projects/smg-analytics

What happens:

1. Copies ~/.memory-mcp/projects/smg-analytics.duckdb → /Users/you/projects/smg-analytics/.memory-mcp.duckdb
2. Moves the original to ~/.memory-mcp/backups/ (kept as safety net)
3. Updates the registry so this project now uses the new location

The other projects stay right where they are. Their memory is never exposed in this repo’s git history.

When you git add .memory-mcp.duckdb and push, you’re only sharing that specific project’s memory. Teammates who pull it only get that project’s memory — not a window into all your other work.

Q: Will my memories from one project contaminate another project?

No. Strict isolation. Each project’s .duckdb is its own DuckDB database. Searches, rules, sessions — everything is scoped to one project at a time.

Q: What happens if my context window fills up mid-session?

You won’t lose anything. Memories live in the DB, not in the context window. When you start a new session, memory_session_start auto-loads:

• All mandatory rules (guaranteed, cached, never approximated)
• All forbidden rules
• Last session’s summary
• Active sprint goals
• Recent decisions (last 7 days)

Anything older is one semantic search away.

Q: Do I need to manually store every memory?

No. When a session is active, Claude auto-stores:

• Decisions you make (“we decided to use X”, “going with Y”)
• Rules you set (“always do X”, “never do Y”)
• Feedback (“don’t do that again”, “keep doing that”)
• Architecture choices

You can also explicitly use /smg-memory store when you want control.

Q: Does anything leave my machine?

No. Everything is local:

• DuckDB database on your disk
• Embeddings generated locally by sentence-transformers (CPU, no GPU needed)
• No API keys, no cloud services, no telemetry

The only network call is the one-time ~80MB download of the embedding model from Hugging Face.

Q: Can my teammate who doesn’t have this MCP still read the memories?

Yes. Run /smg-memory export and it creates a .memory/ directory with human-readable Markdown files. Anyone can read, edit, or review them directly. You can sync changes back with /smg-memory import.

---

How It Works — The Flow

Three interaction patterns. In all of them, you talk to Claude normally — the MCP works behind the scenes.

The Cast

Before the flows, a quick clarification — these are different things:

The embedding model is NOT an LLM. It doesn’t “understand” — it just converts text to numbers so that similar meanings produce similar vectors. That’s why it’s small and fast.

---

Flow 1: You ask a question

“What was our caching strategy?”

sequenceDiagram
    actor You
    participant Claude
    participant MCP as Memory MCP
    participant Embed as Embedding Model
    participant DB as DuckDB

    You->>Claude: "What was our caching strategy?"
    Claude->>MCP: memory_search("caching strategy")
    MCP->>Embed: encode(query)
    Embed-->>MCP: [384-dim vector]
    MCP->>DB: vector similarity search (cosine)
    DB-->>MCP: top-N matching memories
    MCP-->>Claude: [Redis for cache, decisions, ...]
    Claude-->>You: "We chose Redis for session caching because..."

What happened: Claude triggered a vector search. The query became a vector. DuckDB found memories with similar vectors (same meaning). Claude composed the answer from those memories.

---

Flow 2: You make a decision

“Let’s use Redis for caching.”

sequenceDiagram
    actor You
    participant Claude
    participant Hook as UserPrompt Hook
    participant MCP as Memory MCP
    participant Embed as Embedding Model
    participant DB as DuckDB

    You->>Claude: "Let's use Redis for caching"
    Hook->>Claude: detects decision pattern
    Claude->>MCP: memory_store(decision, "Use Redis", content)
    MCP->>Embed: encode(title + content)
    Embed-->>MCP: [384-dim vector]
    MCP->>MCP: generate summary, extract entities, compute TTL
    MCP->>DB: INSERT memory + vector + metadata
    DB-->>MCP: stored
    MCP-->>Claude: {id, summary, entities, expires_at}
    Claude-->>You: "Noted — Redis caching decision saved."

What happened: The UserPromptSubmit hook noticed a decision pattern. Claude auto-stored it. MCP generated a summary, extracted entities (like “Redis”), computed a TTL (365 days for decisions), and wrote everything to DuckDB along with the vector.

---

Flow 3: You start a new conversation

“Hi, let’s continue.”

sequenceDiagram
    actor You
    participant Claude
    participant Hook as SessionStart Hook
    participant MCP as Memory MCP
    participant DB as DuckDB

    You->>Claude: "Hi, let's continue"
    Hook->>Claude: enforces memory_session_start
    Claude->>MCP: memory_session_start(project)
    MCP->>DB: auto-close orphaned sessions
    MCP->>DB: SELECT mandatory_rules, forbidden_rules
    MCP->>DB: SELECT last session summary
    MCP->>DB: SELECT active sprint goals
    MCP->>DB: SELECT recent decisions (last 7 days)
    DB-->>MCP: full context bundle
    MCP-->>Claude: {rules, last_summary, sprint, decisions}
    Claude-->>You: "Hi! Last session we chose Redis. Auth module is next."

What happened: The hook forced Claude to call memory_session_start. MCP pulled everything important in one batch — rules, last session summary, active sprint, recent decisions — and Claude started the conversation already knowing the project’s state.

---

High-Level View

graph LR
    User[You]  Claude[Claude LLM]
    Claude  MCP[Memory MCP Server]
    MCP --> Embed[Embedding Model~80MB local]
    MCP --> DB[(DuckDBper-project)]
    DB --> HNSW[HNSW Vector Index]
    Hooks[Hooks] -.->|enforce session_start,detect decisions| Claude

    style User fill:#e1f5e1
    style Claude fill:#fff4e1
    style MCP fill:#e1e8ff
    style Embed fill:#ffe1f0
    style DB fill:#f0e1ff

Everything runs locally on your machine. No cloud, no API keys, no telemetry.

---

Multilingual Support

The Default: English-Only

Out of the box, this MCP uses all-MiniLM-L6-v2 — a small, fast, English-only embedding model:

• Size: ~80MB on disk, ~90MB RAM
• Speed: ~14k sentences/sec on CPU
• Languages: English only
• Quality: Excellent for English

What this means in practice:

✅ "which database did we choose?" → finds the PostgreSQL decision (English content)
❌ "hangi veritabanını seçtik?"    → may return 0 results (Turkish query, English content)

If your memories are in English, the default works great. If you or your team write in other languages, you need the multilingual model.

Switching to Multilingual

If you want to ask questions or store memories in non-English languages, switch to the multilingual model:

/smg-memory model multilingual

This will:

1. Show you the impact (disk, RAM, memories to re-embed)
2. Ask for confirmation
3. Download the multilingual model (~470MB, one-time)
4. Re-embed all your existing memories with the new model
5. Persist the choice (survives restarts)

After switching, you can search and store in any of these 50+ languages:

Cross-Lingual Superpower

The multilingual model is cross-lingual — you can store memories in one language and search in another:

Store (English):  "We chose PostgreSQL for JSON support and reliability"
Search (Turkish): "hangi veritabanını kullanıyoruz?" → finds the PostgreSQL decision ✅
Search (Japanese): "どのデータベースを使っていますか?" → finds it too ✅

Comparison

Switching Back

Want to go back to English-only?

/smg-memory model english

Same two-step confirmation, re-embeds all memories back.

Check Current Model

/smg-memory model

Shows which model is active and presents both options with their trade-offs.

---

Why Not Just Use MEMORY.md?

Claude Code’s built-in memory has real limitations:

---

Features

---

Quick Install

git clone https://github.com/serkansmg/smg-claude-memory-mcp.git
cd smg-claude-memory-mcp
chmod +x install.sh
./install.sh

This will:

1. Install uv if not present
2. Install all Python dependencies in an isolated venv (no system pollution)
3. Download the embedding model (~80MB, one-time)
4. Configure Claude Code MCP automatically

Then restart Claude Code.

Manual Install

uv sync
uv run memory-mcp-setup

Or add to Claude Code manually (.mcp.json or ~/.claude.json):

{
  "mcpServers": {
    "memory": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/smg-claude-memory-mcp", "memory-mcp"]
    }
  }
}

---

Quick Start

# 1. Create a project (one-time)
/smg-memory init my-app "My Application"

# 2. Start a session (beginning of each conversation)
/smg-memory start

# 3. Store memories (or let Claude auto-detect from conversation)
/smg-memory store decision "Use PostgreSQL" "Chose PostgreSQL for JSON support"
/smg-memory store mandatory_rules "Always Test" "Run pytest before every commit"

# 4. Search
/smg-memory search "database choice"

# 5. End session
/smg-memory end "Implemented auth module, chose JWT tokens"

---

Usage

Project Management

# Create new project (auto-activates)
/smg-memory init my-app "My Application"

# Attach existing project directory
/smg-memory attach /path/to/my-app

# Set active project (no need to pass project= to every command)
/smg-memory use my-app

# List all projects
/smg-memory projects

Session Lifecycle

# Start session — loads rules, last session summary, sprint goals, recent decisions
/smg-memory start

# End session with summary
/smg-memory end "Completed user auth, decided on JWT, next: API rate limiting"

Memory Operations

# Store (project is optional — uses active project)
/smg-memory store decision "Redis for Cache" "Using Redis for session and API caching"
/smg-memory store architecture "Event-Driven" "Adopted event-driven architecture with RabbitMQ"
/smg-memory store mandatory_rules "PR Reviews" "All PRs require at least one review"

# Semantic search
/smg-memory search "caching strategy"
/smg-memory search "deployment pipeline"

# List by category
/smg-memory list decisions
/smg-memory list mandatory_rules

# Get rules
/smg-memory rules

# View change history
/smg-memory history 

Team Collaboration

Option A: Share via Git (portable DB)

# Developer 1: Move DB to project directory
/smg-memory portable /path/to/project
# Add to .gitignore: *.duckdb.wal
git add .memory-mcp.duckdb
git commit -m "add project memory"
git push

# Developer 2: After git pull
/smg-memory sync /path/to/project
# Ready! All memories from Developer 1 are available.

Option B: Export for non-MCP users

# Export to human-readable .md files
/smg-memory export /path/to/project

# Creates:
# .memory/
#   MEMORY_INDEX.md          <- Master index
#   README.md                <- Format docs
#   decision/
#     use-postgresql.md      <- Individual memories
#   mandatory_rules/
#     always-test.md
#   architecture/
#     event-driven.md

# Non-MCP users can read and edit these files directly.

# Import changes back
/smg-memory import /path/to/project

Automatic Memory (No Commands Needed)

When a session is active, Claude automatically:

• Stores decisions when you make architectural or technical choices
• Stores rules when you say “always do X” or “never do Y”
• Searches memory when you ask about past decisions
• Checks rules before significant operations

---

Memory Categories

---

MCP Tools Reference

---

Architecture

~/.memory-mcp/
  registry.duckdb              # Project registry (list of all projects)
  projects/
    my-app.duckdb              # Per-project vector DB (ONLY my-app's memory)
    api-backend.duckdb         # Per-project vector DB (ONLY api-backend's memory)
  backups/                     # Automatic backups before destructive operations

# Or portable (DB lives in the project dir, shared via git):
my-app/
  .memory-mcp.duckdb           # This project's memory (in git)
  .memory/                     # Optional: human-readable .md export

Internal architecture (for contributors):

┌───────────────────────────────────────────────┐
│  server.py — FastMCP tool bindings (thin)     │
├───────────────────────────────────────────────┤
│  services/ — business logic                   │
│    MemoryService, SearchService, SessionService,
│    RulesService, ProjectService, PortableService,
│    ExportImportService, ModelService          │
├───────────────────────────────────────────────┤
│  repositories/ — SQL, centralized             │
│    MemoryRepository, ProjectRepository,       │
│    SessionRepository, ProvenanceRepository    │
├───────────────────────────────────────────────┤
│  db/ — connection, schema                     │
└───────────────────────────────────────────────┘

Stack: FastMCP + DuckDB (VSS/HNSW) + sentence-transformers + Pydantic v2

---

Requirements

• Python 3.11+
• macOS or Linux (Apple Silicon fully supported)
• ~80MB disk for the English embedding model (~470MB for multilingual)
• ~90MB RAM for the English model loaded (~500MB for multilingual)

---

Development

uv sync --all-extras
uv run pytest -v

Current test coverage: 98 tests — 34 repository unit tests, 35 service unit tests, 29 integration tests.

---

License

MIT