memory-mcp

# Memory MCP A Model Context Protocol (MCP) server that gives AI coding agents persistent, evolving knowledge about a codebase. Instead of starting cold every session, agents can store and retrieve observations about architecture, conventions, gotchas, and recent work context. ## Tools | Tool | Description | |------|-------------| | `memory_context` | Session start AND pre-task lookup. Call with no args for user + preferences + stale nudges; call with `context` for task-specific knowledge | | `memory_query` | Structured search with brief/standard/full detail levels and AND/OR/NOT filter syntax. Scope defaults to `"*"` (all topics) | | `memory_store` | Store a knowledge entry with dedup detection, preference surfacing, lobe auto-detection, and a review-required gate for likely-ephemeral content | | `memory_correct` | Correct, update, or delete an existing entry (suggests storing as preference) | | `memory_bootstrap` | First-use scan to seed knowledge from repo structure, README, and build files | > **Hidden tools** (still callable, not in the catalog — agents learn about them from hints/errors): > `memory_list_lobes` (lobe paths and stats), `memory_stats` (entry counts, freshness, storage), `memory_diagnose` (server health, crash history, recovery steps) ## Knowledge Topics | Topic | Purpose | Global? | Expires? | Default Trust | |-------|---------|---------|----------|---------------| | `user` | Personal info (name, role, communication style) | Yes | Never | `user` | | `preferences` | Corrections, opinions, coding rules | Yes | Never | `user` | | `gotchas` | Pitfalls and known issues | No | Never | `user` | | `architecture` | System design, patterns, module structure | No | 30 days | `agent-inferred` | | `conventions` | Code style, naming, patterns | No | 30 days | `agent-inferred` | | `modules/<name>` | Per-module knowledge | No | 30 days | `agent-inferred` | | `recent-work` | Current task context (branch-scoped) | No | 30 days | `agent-inferred` | **Global topics** (`user`, `preferences`) are stored in a shared global store at `~/.memory-mcp/global/` and are accessible from all lobes. This means your identity and coding preferences follow you across every repository without duplication. ### Smart Surfacing - **Dedup detection**: When you store an entry, the response shows similar existing entries in the same topic (>35% keyword overlap) with consolidation instructions - **Preference surfacing**: Storing a non-preference entry shows relevant preferences that might conflict - **Ephemeral review gate**: Likely-ephemeral content is blocked before persistence by default. Re-run `memory_store(..., durabilityDecision: "store-anyway")` only when you intentionally want to keep it. - **Piggyback hints**: `memory_correct` suggests storing corrections as reusable preferences - **`memory_context`**: Describe your task in natural language and get ranked results across all topics with topic-based boosting (preferences 1.8x, gotchas 1.5x) ### Smart Filter Syntax `memory_query` supports a filter mini-language for precise searches: | Syntax | Meaning | Example | |--------|---------|---------| | `A B` | AND (both required) | `reducer sealed` | | `A\|B` | OR (either matches) | `MVI\|MVVM` | | `-A` | NOT (exclude) | `-deprecated` | | combined | Mix freely | `kotlin sealed\|swift protocol -deprecated` | Filters use stemmed matching, so `reducers` matches `reducer` and `exceptions` matches `exception`. ## Quick Start ```bash # Install dependencies npm install # Build npm run build # Run tests npm test ``` ## Configuration ### Config File (Recommended) Create a `memory-config.json` file next to the memory MCP server: ```json { "lobes": { "workspace-mcp": { "root": "$HOME/git/personal/workspace-mcp", "budgetMB": 2 }, "workrail": { "root": "$HOME/git/personal/workrail", "budgetMB": 2 } } } ``` > **Note:** `memoryDir` is optional. When omitted, storage auto-detects to `.git/memory/` for git repos. **What's a "lobe"?** Each repository gets its own memory lobe -- a dedicated knowledge scope. Think of it like brain regions: the "workrail lobe" stores knowledge about workrail, the "workspace-mcp lobe" stores knowledge about workspace-mcp. **Benefits:** - Portable (`$HOME` and `~` expansion works across machines) - Discoverable (use `memory_list_lobes` to see what's configured) - Easy to extend (just add a new lobe entry) ### Environment Variables (Fallback) If no `memory-config.json` is found, the server falls back to environment variables: | Variable | Default | Description | |----------|---------|-------------| | `MEMORY_MCP_WORKSPACES` | -- | JSON mapping workspace names to repo paths (multi-repo mode) | | `MEMORY_MCP_REPO_ROOT` | `process.cwd()` | Fallback: single-repo path (if `WORKSPACES` not set) | | `MEMORY_MCP_DIR` | *(auto-detect)* | Override storage dir (relative to repo root, or absolute). Disables git-native auto-detection. | | `MEMORY_MCP_BUDGET` | `2097152` (2MB) | Storage budget per workspace in bytes | ### Adding a New Lobe 1. **Edit `memory-config.json`** (create if it doesn't exist) 2. **Add lobe entry:** ```json { "my-project": { "root": "$HOME/git/my-project", "budgetMB": 2 } } ``` 3. **Restart the memory MCP server** 4. **Verify:** Use `memory_list_lobes` to confirm it loaded The agent will see the new lobe in tool descriptions and can immediately use it with `memory_store(lobe: "my-project", ...)`. ## MCP Client Registration With `memory-config.json` (recommended): ```json { "mcpServers": { "memory": { "command": "node", "args": ["/path/to/memory-mcp/dist/index.js"] } } } ``` The server reads `memory-config.json` automatically -- no env vars needed. ### Environment Variable Mode ```json { "mcpServers": { "memory": { "command": "node", "args": ["/path/to/memory-mcp/dist/index.js"], "env": { "MEMORY_MCP_WORKSPACES": "{\"android\":\"/path/to/android\",\"ios\":\"/path/to/ios\"}" } } } } ``` ## Storage Location Knowledge is stored as human-readable Markdown files -- **one file per entry**. The storage location is **auto-detected** with the following priority: 1. **Explicit `memoryDir` config** -- if set in `memory-config.json` or `MEMORY_MCP_DIR`, uses that path 2. **Git-native** (default) -- `<git-common-dir>/memory/` using `git rev-parse --git-common-dir`. This ensures: - **Invisible to git** -- `.git/` contents are never tracked, no `.gitignore` needed - **Shared across worktrees** -- all worktrees of the same repo share one memory store - **Worktree/submodule safe** -- resolves to the common `.git/` directory regardless 3. **Central fallback** -- `~/.memory-mcp/<lobe-name>/` for non-git directories Use `memory_stats` or `memory_list_lobes` to see where memory is stored for each lobe. ### File Structure Each entry gets its own file. Recent-work entries are scoped by branch. ``` .git/memory/ architecture/ arch-e8d4f012.md # One entry per file conventions/ conv-a1b2c3d4.md gotchas/ gotcha-7k3m9p2q.md recent-work/ main/ # Branch-scoped recent-f5e6d7c8.md feature-messaging-refactor/ # Sanitized branch name recent-9i0j1k2l.md modules/ messaging/ mod-4d5e6f7g.md ~/.memory-mcp/global/ # Global store (shared across all lobes) user/ user-3f7a2b1c.md # Personal info preferences/ pref-5c9b7e3d.md # Coding opinions & corrections ``` ### Concurrency Safety Each entry is its own file with a random hex ID. Two MCP processes (e.g., Firebender + Cursor) writing different entries to the same repo **never conflict** -- they write to different files. The store reloads from disk before every read to pick up changes from other processes. ### Branch-Scoped Recent Work Recent-work entries are automatically tagged with the current git branch and stored in a branch-named subdirectory. `memory_query` filters recent-work to the current branch by default. Use `branch: "*"` to see recent-work from all branches. ### Entry Format ```markdown # Build System & Language - **id**: arch-3f7a2b1c - **topic**: architecture - **confidence**: 0.70 - **trust**: agent-inferred - **created**: 2026-02-18T12:00:00.000Z - **lastAccessed**: 2026-02-18T12:00:00.000Z Detected: Node.js/TypeScript project (npm) ``` ## Trust Levels | Level | Confidence | Meaning | |-------|-----------|---------| | `user` | 1.0 | Human-provided or human-corrected knowledge | | `agent-confirmed` | 0.85 | Agent-observed and verified against code | | `agent-inferred` | 0.70 | Agent-observed, not yet verified | ## Resilience The server uses a **degradation ladder** to stay useful even when things go wrong: - **Running** -- all lobes healthy, full functionality - **Degraded** -- some lobes failed to initialize but healthy ones continue working. Failed lobes report specific recovery steps via `memory_diagnose`. - **Safe Mode** -- all lobes failed. Only `memory_diagnose` and `memory_list_lobes` work, giving you enough information to fix the problem. **Crash journaling**: On uncaught exceptions, the server writes a structured crash report to `~/.memory-mcp/crashes/` before exiting. The next startup surfaces the crash in `memory_context()` (briefing mode) with recovery steps. Use `memory_diagnose(showCrashHistory: true)` to see the full history. ### Argument Normalization Agents frequently guess wrong parameter names. The server silently resolves common aliases to avoid wasted round-trips: | Alias | Resolves to | |-------|-------------| | `key`, `name` | `title` | | `value`, `body`, `text` | `content` | | `query`, `search` | `filter` | | `workspace`, `repo` | `lobe` | Wildcard scope aliases (`all`, `everything`, `global`, `project`) resolve to `*`. ## Architecture ``` types.ts Domain types (discriminated unions, parse functions) store.ts MarkdownMemoryStore (CRUD, search, bootstrap, briefing) text-analyzer.ts Keyword extraction, stemming, similarity (stateless) normalize.ts Argument alias resolution (pure) formatters.ts Response formatters for tool handlers (pure) config.ts 3-tier config loading (file > env > default) git-service.ts Git operations boundary (injectable for testing) crash-journal.ts Crash report lifecycle (build, write, read, format) index.ts MCP server, tool handlers, startup, migration ``` ## Design See `ideas/codebase-memory-mcp-design-thinking.md` for the full design thinking document with 67 ideas, 5 concept packages, pre-mortem analysis, and test plan.