memory-mcp

Persistent memory MCP server for Claude Code. Store, search, and retrieve memories across sessions using hybrid vector + keyword search powered by SQLite, FTS5, and sqlite-vec.

Features

• Hybrid search — 70% vector similarity + 30% BM25 keyword matching
• Local embeddings — Ollama (required, local, free)
• Persistent storage — SQLite database survives across sessions
• Token-aware context — Retrieve memories fitted within a token budget
• File watching — Auto-index markdown and code files on change
• LRU embedding cache — 10k entries, SHA256-keyed dedup

Setup

git clone https://github.com/AyubMoh1/memory-mcp.git
cd memory-mcp
npm install
npm run build

Register with Claude Code

Add to ~/.claude/config.json:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/memory-mcp/dist/index.js"]
    }
  }
}

Tools

Tool	Description
memory_store	Store a memory with category, tags, and importance
memory_search	Hybrid vector + keyword search
memory_list	List recent memories with filters
memory_delete	Delete a memory by ID
memory_get_context	Token-budgeted context retrieval for a topic
memory_get_stats	Storage statistics

Resources

Resource	URI	Description
Stats	memory://stats	JSON storage statistics
Recent	memory://recent	Last 20 memories

Configuration

All configuration is via environment variables:

Variable	Default	Description
MEMORY_DB_PATH	~/.memory-mcp/memory.db	Database file location
MEMORY_WATCH_PATHS	(empty)	Comma-separated file paths to auto-index
OLLAMA_URL	http://127.0.0.1:11434	Ollama server URL
DEBUG	—	Enable debug logging

Embeddings

Ollama is required. The server will fail to start without a running Ollama instance and an embedding model installed.

ollama serve                    # Start Ollama
ollama pull nomic-embed-text    # Install embedding model

Architecture

src/
├── index.ts              # Entry point: MCP server + stdio transport
├── storage/
│   ├── types.ts          # MemoryChunk, SearchResult, StorageBackend
│   └── database.ts       # SQLite + FTS5 + sqlite-vec
├── embeddings/
│   ├── providers.ts      # Ollama embedding provider
│   ├── cache.ts          # LRU embedding cache
│   └── detect.ts         # Detect Ollama + embedding model
├── sync/
│   ├── file-watcher.ts   # chokidar with debouncing
│   └── chunker.ts        # Split files by headers/paragraphs
├── tools/                # MCP tool handlers
├── resources/            # MCP resource handlers
└── utils/                # Logger, ID gen, token estimation

License

MIT