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) and Effective Discourse Guide.

🏛️ 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

# 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

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

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`)

{
  "mcpServers": {
    "mcp-memory": {
      "command": "C:\\Users\\reazul.ashraf\\.gemini\\antigravity-cli\\mcp\\mcp-memory\\mcp-memory.exe",
      "args": []
    }
  }
}

README.md Unescape Escape

mcp-memory

Overview