173 lines
10 KiB
Markdown
173 lines
10 KiB
Markdown
# 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](./instructions.md) and [Effective Discourse Guide](./EFFECTIVE_DISCOURSE.md) 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:
|
|
```powershell
|
|
# 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:
|
|
```powershell
|
|
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:
|
|
```powershell
|
|
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:**
|
|
```powershell
|
|
just start
|
|
just stop
|
|
just restart
|
|
```
|
|
|
|
### 2. Config Setup (`mcp_config.json`)
|
|
|
|
Update your `~/.gemini/config/mcp_config.json`:
|
|
```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.
|