mcp-memory/README.md

mcp-memory

A high-performance, persistent Knowledge Graph and Context daemon for Antigravity, implementing the Model Context Protocol (MCP).

Overview

mcp-memory acts as the persistent "brain" for agy CLI agents. It tracks entities, relations, background tasks, engineering debt, architectural decisions, and error fixes across sessions.

To eliminate heavy Cross-OS I/O penalties when using WSL and Windows simultaneously, mcp-memory operates using a Dual-Transport Leader/Stub Architecture:

• The Server (mcp-memory-server): Runs natively on the Windows host. It binds to 0.0.0.0:3000, serving standard stdio to the primary Windows agy instance while simultaneously hosting an Axum HTTP and WebSocket server for secondary clients.
• The Stub (mcp-memory-stub): An ultra-lightweight proxy binary. WSL agy instances run this native Linux stub, which transparently pipes stdio JSON-RPC traffic over the network to the Windows HTTP server (http://127.0.0.1:3000), completely bypassing WSL NTFS mounts. It features full MPSC queue buffering and a WebSocket reconnect handshake (notifications/tools/list_changed) so that tools automatically refresh seamlessly without disconnecting the CLI if the background server restarts.

Note for Users & LLMs: Please read the Strategic Guidelines and Effective Discourse Guide to learn how to perfectly trigger this server's advanced MCP tools.

---

Casing & Naming Standards

To prevent graph fragmentation and ensure optimal LLM tokenization and retrieval:

• Entity Types (entity_type): Standardized as PascalCase (e.g. DatabaseTable, McpTool, ArchitectureComponent, File).
• Relation Types (relation_type): Standardized as snake_case (e.g. depends_on, calls, implements, uses).
• Field Keys & Attributes: Standardized as snake_case (e.g. file_path, git_commit, created_at).

Note: The server automatically normalizes and migrates incoming types to these canonical conventions on every read and write operation.

---

---

🛠️ Consolidated Smart MCP Tools

The server consolidates granular single-purpose tools into 12 concise, action-oriented smart domain handlers with zero prefix clutter:

• tasks: Complete task lifecycle management (add, update, delete, list, set_criteria, verify).
• milestones: Milestone tracking (add, update, list).
• sticky_notes: Ephemeral scratchpad notes with TTL (add, read, delete, clear).
• handoff_memos: Cross-session handoff notes (leave, read, clear).
• pinned_files: Working set file focus management (pin, unpin, list).
• context_workspaces: Workspace context state snapshots (save, load, list, delete, diff).
• pr_checklist: Pre-commit and PR checklist management (add, get, clear).
• snippets: Reusable code snippet vault with BM25+Vector search (store, search, delete, tag).
• decisions: Architectural Decision Records (ADRs) (log, query, delete).
• tech_debt: Engineering technical debt backlog (log, resolve, list).
• environment: Infrastructure & tool fingerprints tracking (update_fingerprint, read_fingerprint, log_requirement, register, get_details).
• clipboard: Cross-OS clipboard management (read, write, toggle_watch).

---

Key Features & Capabilities

🕸️ Multi-Hop Subgraph Expansion (get_subgraph)

Performs a Breadth-First Search (BFS) around a target root entity node up to a specified depth (N hops), returning all connected sub-entities and relationships in a single call.

⚡ Automated Error Fix Auto-Matcher (suggest_error_fix)

Compares build and test stack traces against historical error resolutions using dense vector embeddings and signature matching, returning past solutions, modified files, and git commits.

💾 Memory State Checkpoints & Rollbacks (checkpoint_state / restore_state)

Saves point-in-time snapshots of graph entities, active tasks, and tech debt backlogs before risky operations, enabling seamless state restoration.

📊 Token Budgeting & RRF Search

• Token Budgeting: Supports summary_level (compact | detailed | full) and max_tokens parameters on tasks (list) and tech_debt (list).
• Hybrid RRF Search: omni_search combines Tantivy BM25 keyword matching with Dense Vector embeddings using Reciprocal Rank Fusion.
• Session Delta Resource (memory://session/delta): Delivers recent session changes in a compact context resource.

🏷️ Domain Tagging for Code Snippets (snippets)

Supports categorization tags (tags: Vec<String>) on code snippets for category-filtered searches and domain organization.

🧹 Self-Healing Graph Sweeper (sweep_graph_health)

Audits entity nodes for orphans and calculates name similarity to surface near-duplicate merge recommendations or auto-prune stale nodes.

🔗 Causal Lineage & Provenance Tracker (query_lineage)

Traces the full causal chain linking tasks, ADRs, audit ledger entries, git commits, and error fixes for any query.

🎯 Topological Unblocked Task Resolver (get_next_actionable_tasks)

Evaluates task dependency graphs and returns unblocked, ready-to-run tasks for subagent execution.

🧠 Chain-of-Thought & Diagnostic Hypothesis Memory (log_hypothesis / query_hypotheses)

Records structured diagnostic hypotheses, test evidence, and verification statuses to preserve reasoning across sessions.

🔀 Context Workspace Diffing (context_workspaces)

Computes structured diffs of pinned files and active task IDs between two saved context workspaces.

🔒 Resilient Storage & Serde Parameter Tolerances

• Atomic Store Write Locks: Retains write guards during both in-memory updates and redb database serialization to eliminate lock-release TOCTOU race conditions.
• Database Quarantine Protection: Automatically flags corrupted database keys during deserialization (is_corrupted = true) to prevent corrupt states from being overwritten with empty defaults on subsequent writes.
• Serde Relation Parameter Aliases: create_relations accepts flexible aliases (source / target / relationType / type) so LLMs never encounter parameter validation errors.
• Pre-cached Embedding Search: Reuses pre-computed snippet embeddings (snippet.embedding), bypassing ONNX inference latency during in-memory semantic searches.

📡 Real-time WebSocket Memory Sync (ws://127.0.0.1:3000/ws)

Broadcasting event pipeline streams real-time graph, task, and activity mutations directly to the Brain Monitor UI.

---

Quick Start & Usage

1. Windows Installation (The Server & Stub)

To enforce strict process safety and eliminate file locks on Windows, the build, deploy, and execution lifecycle are entirely decoupled in the justfile.

The Golden Rule: You must gracefully stop the server before deploying a new binary. Deploy recipes only copy files; they do not kill processes.

The easiest way to manage this end-to-end (Stop -> Build -> Deploy -> Start) is using the chaining commands:

# For the main server:
just all-server-win

# For the lightweight stubs/nvim servers:
just all-stub-win
just all-nvim-win

If you want to perform these steps manually, follow this exact order:

just stop         # 1. Gracefully shut down the background server (TCP 3000)
just build-win    # 2. Compile the binaries
just deploy-win   # 3. Move the executables into ~/.local/bin/
just start        # 4. Spawns the daemon completely detached in the background
just verify       # 5. Hits the /ping endpoint to ensure liveness

Auto-Start Configuration: To ensure the background server is always available, add this to your PowerShell profile:

if ($host.Name -eq 'ConsoleHost' -and -not (Get-Process mcp-memory-server -ErrorAction SilentlyContinue)) { 
    Start-Process -FilePath "C:\Users\reazul.ashraf\.local\bin\mcp-memory-server.exe" -WindowStyle Hidden -ErrorAction SilentlyContinue 
}

Shutting Down & Managing:

just start
just stop
just restart

2. Config Setup (mcp_config.json)

Update your ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "memory": {
      "command": "C:\\Users\\reazul.ashraf\\.local\\bin\\mcp-memory-stub.exe",
      "args": []
    }
  }
}

---

Brain Monitor Dashboard

The server hosts a live, real-time SPA dashboard called the Brain Monitor.

To view the dashboard, open your browser at: http://127.0.0.1:3000/

Dashboard Features:

• Interactive Knowledge Graph: Physics-simulated network graph with node-type coloring, drag-and-drop, and Inspector Panel.
• Kanban Board: Track active Tasks and trigger status transitions directly from the browser.
• Clipboard Inspector: Review OS-level clipboard image captures via /api/clipboard/capture.
• Live WebSocket Telemetry: Real-time UI updates triggered by server state changes.

---

High-Performance Concurrency & Resilience Guarantees

• Async Channel Backpressure (push_async): Store::modify_async uses DbWriteQueue::push_async with tx.send(task).await backpressure to guarantee database write persistence under heavy async write loads without dropping write transactions.
• Atomic Search Index Swaps: MemoryState::rebuild_index constructs and populates a new MemoryIndex instance in isolation before performing an atomic pointer swap (*self.search_index.write().await = new_idx), eliminating transient empty search result windows.
• SIMD-Friendly Single-Pass Cosine Similarity: cosine_similarity calculates dot product and Euclidean norm squares in a single linear pass over float vectors, enabling SIMD compiler auto-vectorization.
• Safe Stream Decoding on Log Tails: Log tail operations (get_recent_logs) read raw bytes and decode using lossy UTF-8 conversion (String::from_utf8_lossy) to ensure resilience when seeking across multi-byte UTF-8 boundaries.
• Serde Parameter & Enum Tolerance: All action enums (StickyNoteAction, SnippetSearchMode, Relation) support case-insensitive variants and field aliases (source/from, target/to, relationType/relation_type) to ensure seamless execution when LLMs pass varied string formatting.