# 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.

### 📡 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.