Riz Ashraf
3b08f45618
- Document all 53 MCP tools, 9 passive MCP resources, and 5 workflow prompts - Document 100% ADR implementation status and automated post-commit reconciliation engine - Update and deploy agent-rules (mcp_memory_workflow.md) to Windows and WSL - Fix dashboard live ADR tab refresh and Cache-Control headers - Synchronize instructions.md across root, server embedded, Windows, and WSL MCP configs
177 lines
11 KiB
Markdown
177 lines
11 KiB
Markdown
# mcp-memory
|
||
|
||
A high-performance, persistent Knowledge Graph, Code Intelligence, and Context daemon for Antigravity, implementing the Model Context Protocol (MCP).
|
||
|
||
## Overview
|
||
|
||
`mcp-memory` acts as the persistent "brain" for `agy` CLI agents and autonomous subagents. It tracks graph entities, relations, background tasks, milestones, engineering debt, architectural decisions, code modifications, terminal activity, and compiler error fixes across sessions.
|
||
|
||
To eliminate cross-OS I/O penalties when developing across 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 Axum HTTP, WebSocket, and Zero-Latency UDP endpoints for secondary clients and UI dashboards.
|
||
* **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 local network to the Windows HTTP server (`http://127.0.0.1:3000`), completely bypassing WSL NTFS cross-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 in-depth strategy, casing standards, and tool semantics, please refer to the [Strategic Guidelines (`instructions.md`)](./instructions.md) and [Effective Discourse Guide](./EFFECTIVE_DISCOURSE.md).
|
||
|
||
---
|
||
|
||
## 🏛️ Architecture Status: 100% ADR Implementation
|
||
|
||
All 25 Architectural Decision Records (**ADR-0080 through ADR-0104**) are **100% implemented, verified, and reconciled** in the persistent store:
|
||
* **ADR-0080 – ADR-0093**: Enterprise persistence, AST intelligence, vector embeddings, cross-OS dual transports, and headless Neovim RPC.
|
||
* **ADR-0094 – ADR-0101**: Zero-subprocess security invariants, pure native Rust clipboard (`arboard`), and bounded telemetry buffers.
|
||
* **ADR-0102**: Dynamic Fastembed micro-batching with 16k character budget ceiling.
|
||
* **ADR-0103**: Real-time Tantivy search reader auto-reloading upon background index commits.
|
||
* **ADR-0104**: Automated Git post-commit ADR & Task status reconciliation engine (`scripts/git-reconcile.py`).
|
||
|
||
---
|
||
|
||
## 📡 Passive MCP Context Resources (`resources/list`)
|
||
|
||
Agents can passively read these 9 MCP resources for instant zero-turn context without incurring tool call latency:
|
||
|
||
| Resource URI | Resource Name | Description & Usage |
|
||
|:---|:---|:---|
|
||
| `memory://graph/entities` | Graph Entities | All nodes and entities currently stored in the knowledge graph. |
|
||
| `memory://graph/relations` | Graph Relations | All relationship edges between entities in the knowledge graph. |
|
||
| `memory://tasks/active` | Active Tasks | List of all currently pending or uncompleted tasks. |
|
||
| `memory://decisions/active` | Active ADR Decisions | All accepted Architectural Decision Records (ADRs). |
|
||
| `memory://tech_debt/unresolved` | Unresolved Tech Debt | All currently open engineering debt items. |
|
||
| `memory://session/delta` | Session Delta | Code modifications, commits, active tasks, and notes created in the last 2 hours. |
|
||
| `memory://terminal/recent` | Terminal History | Recent terminal commands, shell interpreters (`pwsh`, `bash`, `nu`), working dirs, and exit codes. |
|
||
| `memory://activity/recent` | Recent Activity | Real-time IDE, editor, and developer activity logs. |
|
||
| `memory://milestones` | Milestones | Project milestones, deliverables, target dates, and status. |
|
||
|
||
---
|
||
|
||
## ⚡ MCP Workflow Prompts (`prompts/list`)
|
||
|
||
The server registers 5 high-signal workflow prompts:
|
||
* **`context_warmup`**: Warm up session context by reading active tasks, recent deltas, and the git worktree.
|
||
* **`analyze_tech_debt`**: Inspect open technical debt items and generate a prioritized remediation plan.
|
||
* **`summarize_architecture`**: Synthesize active ADRs and knowledge graph entities into an architectural overview.
|
||
* **`handoff_routine`**: Invoke the `DevOpsSRE` subagent at session end to generate a standup report and leave a handoff memo.
|
||
* **`archive_routine`**: Compress older session summaries into dense milestone retrospectives.
|
||
|
||
---
|
||
|
||
## 🛠️ Complete MCP Tool Suite (53 Tools)
|
||
|
||
The server exposes 53 tools categorized into 7 functional domains:
|
||
|
||
### 1. Consolidated Smart Primary Tools (11 Domain Handlers)
|
||
* **`tasks`**: Complete task lifecycle management (`add`, `update`, `delete`, `list`, `set_criteria`, `verify`).
|
||
* **`milestones`**: Project milestone tracking (`add`, `update`, `list`).
|
||
* **`handoff_memos`**: Cross-session scratchpad and handoff memos (`leave`, `read`, `clear`).
|
||
* **`snippets`**: Reusable code snippet vault with hybrid BM25 + dense vector search (`store`, `search`, `delete`, `tag`).
|
||
* **`decisions`**: Architectural Decision Records (ADRs) (`log`, `update`, `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`**: Pure native Rust OS clipboard interface (`read`, `write`).
|
||
* **`hypotheses`**: Diagnostic hypothesis memory for root cause analysis (`log`, `query`).
|
||
* **`agent_signals`**: Real-time inter-agent signal bus (`broadcast`, `query`).
|
||
* **`process_logs`**: Process and daemon log management (`watch`, `get`, `clear`).
|
||
|
||
### 2. Knowledge Graph Core (18 Tools)
|
||
* `create_entities`, `create_relations`, `add_observations`, `delete_entities`, `delete_relations`, `delete_observations`
|
||
* `read_graph`, `search_nodes`, `open_nodes`, `visualize_graph`, `condense_entity`, `merge_entities`, `find_orphans`
|
||
* `get_subgraph` (BFS $N$-hop neighborhood expansion)
|
||
* `sweep_graph_health` (orphan detection, name similarity, automated merge recommendations)
|
||
* `resolve_stale_symbols` (workspace AST cross-referencing to eliminate stale graph nodes)
|
||
* `summarize_subgraph` (concise subgraph synthesis)
|
||
* `query_graph_path` (BFS shortest path finding)
|
||
|
||
### 3. AST & Code Intelligence (8 Tools)
|
||
* `read_file_skeleton`: Tree-sitter AST structural outline without implementation bodies.
|
||
* `replace_ast_node`: Precise structural code replacement preserving comments and formatting.
|
||
* `find_symbol_references`: Cross-file symbol reference lookup across snippets and disk source code.
|
||
* `get_callers`: Call site and caller identification across the codebase.
|
||
* `analyze_impact`: Blast-radius impact analysis of modifying a symbol or file.
|
||
* `read_directory_architecture`: Recursive directory structure analysis capped at depth 10.
|
||
* `semantic_code_search`: Dense vector semantic code search over indexed source code.
|
||
* `manage_subagent_namespace`: Isolated memory namespaces for concurrent subagent workflows.
|
||
|
||
### 4. Meta, Audit & Intelligence (15 Tools)
|
||
* `decisions`, `tech_debt`, `log_error_fix`, `search_error_fixes`, `log_code_change`, `query_recent_changes`
|
||
* `omni_search` (Reciprocal Rank Fusion hybrid BM25 + Vector search)
|
||
* `get_project_health` (high-level system health dashboard)
|
||
* `manage_checkpoint` (snapshot freeze and rollback)
|
||
* `query_lineage` (causal lineage linking tasks, ADRs, commits, and error fixes)
|
||
* `get_next_actionable_tasks` (topological unblocked task resolver)
|
||
* `hypotheses`, `get_preflight_context`, `agent_signals`, `auto_session_checkpoint`
|
||
|
||
### 5. Task & Milestone Management (2 Tools)
|
||
* `tasks`, `milestones`
|
||
|
||
### 6. Notes, Handoffs & Reporting (4 Tools)
|
||
* `handoff_memos`, `add_session_summary`, `generate_standup_report`, `promote_to_entity`
|
||
|
||
### 7. Git & Worktree Context (2 Tools)
|
||
* `get_active_worktree_context`, `query_git_diffs`
|
||
|
||
---
|
||
|
||
## 🖥️ Brain Monitor Web UI (`http://127.0.0.1:3000/`)
|
||
|
||
The server hosts a live, reactive Single Page Application (SPA) dashboard:
|
||
* **Interactive Knowledge Graph:** Physics-simulated network graph with node-type coloring, drag-and-drop, and Inspector Panel.
|
||
* **Universal Search & Filtering:** Instant debounced search across all tabs with keyboard shortcut (`/`) to jump to the active tab's search bar.
|
||
* **Dynamic Pagination:** Configurable page sizes (`10`, `25`, `50`, `100`, `All`) preserving UI responsiveness across large datasets.
|
||
* **Descending ADR Ordering:** ADRs are automatically sorted with newest IDs first (e.g., ADR-0104, ADR-0103) on Page 1.
|
||
* **Live SSE & WebSocket Telemetry:** Real-time updates without manual browser refresh, wired to all domain mutations.
|
||
* **Kanban Board & Audit Ledger:** Direct task state transitions and chronological code change logs.
|
||
|
||
---
|
||
|
||
## 🔒 Security & Concurrency Invariants
|
||
|
||
* **Zero Subprocess Policy**: Native system handlers (`clipboard`, `ast`, `search`, `db`) use pure native Rust crates (`arboard`, `tree-sitter`, `tantivy`, `psycopg`). Invoking external shell interpreters (`powershell.exe`, `wl-paste`, `xclip`, `cmd.exe`) is strictly prohibited.
|
||
* **Automated Post-Commit Reconciliation**: `scripts/git-reconcile.py` (installed via `just install-git-hooks`) reconciles referenced ADR and Task statuses immediately upon commit.
|
||
* **Atomic Store Write Lock Minimization**: Releases write lock immediately following in-memory mutation, serializing JSON payloads under read guards to prevent blocking concurrent readers.
|
||
* **Async Mutex Deadlock Elimination**: Converted all shared state and Neovim locks to `tokio::sync::Mutex` to prevent worker thread pool starvation.
|
||
* **Zero-Latency UDP Telemetry**: Bypasses disk I/O thrashing for high-frequency editor telemetry using deduplicated UDP streams (`MCP_UDP_PORT1`, `MCP_UDP_PORT2`).
|
||
|
||
---
|
||
|
||
## 🚀 Quick Start & Lifecycle Management
|
||
|
||
### 1. Build and Deploy
|
||
```powershell
|
||
# Build and deploy everything across Windows and WSL
|
||
just all
|
||
|
||
# Or deploy Windows server with graceful staged hot-swap
|
||
just all-server-win
|
||
|
||
# Install Git post-commit reconciliation hook
|
||
just install-git-hooks
|
||
```
|
||
|
||
### 2. Service Management
|
||
```powershell
|
||
just start # Start background server on port 3000
|
||
just stop # Gracefully shut down server
|
||
just restart # Graceful restart with health check verification
|
||
just verify # Verify deployment health
|
||
just version # Check running API version and CLI version
|
||
```
|
||
|
||
### 3. Testing & Parity
|
||
```powershell
|
||
just test # Run fast parallel tests via cargo-nextest & type-check UI
|
||
just test-config # Verify eagerTools configuration parity
|
||
just test-ui # Verify dashboard UI endpoint and HTML integrity
|
||
```
|
||
|
||
### 4. Agent Configuration (`mcp_config.json`)
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"mcp-memory": {
|
||
"command": "C:\\Users\\reazul.ashraf\\.gemini\\antigravity-cli\\mcp\\mcp-memory\\mcp-memory.exe",
|
||
"args": []
|
||
}
|
||
}
|
||
}
|
||
```
|