136 lines
6.8 KiB
Markdown
136 lines
6.8 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.*
|
|
|
|
---
|
|
|
|
## 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 `list_active_tasks` and `list_tech_debt`.
|
|
* **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 (`tag_snippet`)
|
|
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 (`diff_context_workspaces`)
|
|
Computes structured diffs of pinned files and active task IDs between two saved context workspaces.
|
|
|
|
### 📡 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.
|