mcp-simple-memory

Persistent memory for Claude Code. One command setup. Zero external databases.

Claude Code forgets everything between sessions. This MCP server gives it a local SQLite memory that persists across sessions - with optional semantic search powered by Gemini embeddings.

Features

• Zero external dependencies - SQLite via WASM (sql.js). No Python, no Docker, no ChromaDB
• Cross-platform - Works on Windows, macOS, and Linux
• One command setup - npx mcp-simple-memory init and restart Claude Code
• Keyword + semantic search - Auto-switches between SQLite LIKE queries and Gemini vector search
• Tags & projects - Organize memories by project, type, and custom tags
• Markdown import - Bulk import existing docs, notes, or session logs
• ~600 lines - Small, auditable codebase. No magic

Quick Start

npx mcp-simple-memory init

Restart Claude Code. You now have 7 tools: mem_save, mem_search, mem_get, mem_list, mem_update, mem_delete, mem_tags.

Add Semantic Search (Optional)

Get a free Gemini API key (1500 requests/day free tier), then edit .mcp.json:

{
  "mcpServers": {
    "mcp-simple-memory": {
      "command": "npx",
      "args": ["-y", "mcp-simple-memory", "serve"],
      "env": {
        "GEMINI_API_KEY": "your-key-here"
      }
    }
  }
}

Without a key, keyword search works fine. With a key, vector search kicks in automatically when keyword results are sparse.

Use Cases

Session memory - Save summaries at the end of each session, pick up where you left off next time:

mem_save({ text: "Migrated auth from JWT to OAuth2. Tests passing.", type: "session_summary", project: "my-app" })

Technical decisions - Remember why you chose X over Y:

mem_save({ text: "Chose Postgres over MongoDB because we need transactions for payment flow", type: "decision", tags: ["database", "payments"] })

Error solutions - Never debug the same issue twice:

mem_save({ text: "CORS error on /api/upload fixed by adding credentials: 'include'", type: "error", tags: ["cors", "api"] })

Cross-session search - Find anything from previous sessions:

mem_search({ query: "authentication", tag: "api" })

Tools Reference

mem_save

Save a memory with optional tags.

mem_search

Search by keyword, meaning, tag, or type.

mem_get

Fetch full details by ID.

mem_list

List recent memories with optional filters.

mem_update

Update an existing memory.

mem_delete

Delete memories by IDs. Also removes embeddings and tags.

mem_tags

List all tags with usage counts.

How It Works

mem_save({ text: "Fixed auth bug", tags: ["bug"] })
    |
    v
SQLite (keyword index + optional Gemini embedding + tags)
    |
    v
mem_search({ query: "authentication problem" })
    -> keyword match OR vector similarity

1. Keyword Search - SQLite LIKE queries. Fast, zero-config, always available.
2. Gemini Embeddings (optional) - 3072-dim vectors for semantic similarity. Finds "authentication" when you searched "login issue".
3. Auto mode - Keyword first. If < 3 results, falls back to vector search.
4. Tags - Lightweight categorization. Normalized to lowercase.

Import Existing Knowledge

Already have notes, docs, or session logs? Import them:

# Import a single markdown file
npx mcp-simple-memory import CLAUDE.md --project my-app --tags setup

# Import all .md files in a directory
npx mcp-simple-memory import ./docs --tags documentation

# Preview without saving
npx mcp-simple-memory import ./notes --dry-run

# With embeddings (auto-generates during import)
GEMINI_API_KEY=your-key npx mcp-simple-memory import memory.md

Files are split by headings (#, ##, ###) into individual memories.

Database Stats

npx mcp-simple-memory stats

mcp-simple-memory stats
  DB: ~/.mcp-simple-memory/memory.db

  Memories:   42
  Embeddings: 42/42 (100%)
  Tags:       15 unique

  Projects:
    my-app: 30
    default: 12

Use with CLAUDE.md

Add to your project's CLAUDE.md for automatic session continuity:

## Session Memory
- On session start: `mem_search` for recent session summaries
- During work: `mem_save` important decisions (type: "decision")
- On session end: `mem_save` a summary (type: "session_summary")

Data Storage

All data stays local on your machine:

• Database: ~/.mcp-simple-memory/memory.db
• Override: set MCP_MEMORY_DIR environment variable

Comparison with Other Memory MCPs

Upgrading

Just update - the database schema migrates automatically. Existing memories are preserved.

License

MIT