# 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": []
    }
  }
}
```