agent-memory-mcp

Persistent, per-project architectural memory, SQLite FTS5 search, file-anchored invariants, and anti-loop dead-end tracking for AI coding agents.

Works with Google Antigravity, Claude Code, Cursor, Windsurf, Cline, and any MCP-compatible environment.

⚡ The Problem

AI coding agents suffer from session amnesia and debugging loops:

1. When a chat session terminates or context is compacted, the agent forgets project patterns, architectural decisions, and setup instructions.

2. When encountering errors, agents often repeatedly attempt the same failing fix because past failure context is lost.

3. Most memory tools require heavy external services (Docker, Python, remote vector databases) or pollute project git roots with flat markdown files that cause merge conflicts.

Related MCP server: @renzynx/memory-mcp

✨ Features

• 🚀 Zero External Database Setup: Built directly on Node.js 22.5+/24+ native node:sqlite in WAL mode. No Docker, no Python, no native compilation dependencies.

• 🔍 Ranked Full-Text Search (FTS5): Weighted BM25 search across titles, summaries, tags, and files with contextual snippets and Porter stemming.

• 🛡️ Anti-Loop Dead-End Registry: Dedicated tools (record_dead_end / check_dead_ends) to record failed debugging attempts so future agents never repeat known bugs.

• 📌 Code-Anchored Context & Staleness Detection: Links notes to specific workspace files; warns the agent if referenced code was modified on disk after the memory was saved.

• 🧹 Clean Git Hygiene: Stores per-project SQLite databases centrally in ~/.ag-memory-mcp/stores/, keeping your repository working tree 100% clean.

• 🔄 Zero-Data-Loss JIT Migration: Automatically detects, validates, and migrates legacy .ag-memory.json files on first project open, creating verified backup archives.

• ⚡ Sub-25ms Startup & Low RAM: Cold starts in milliseconds with ~35MB RAM footprint, suitable for synchronous startup hooks.

🏗️ Architecture

flowchart LR
    subgraph Clients["AI Clients & Editors"]
        AG["Google Antigravity"]
        CC["Claude Code"]
        CU["Cursor / Windsurf"]
    end

    subgraph MCP["agent-memory-mcp Engine"]
        Server["MCP Server (JSON-RPC)"]
        Hook["SessionStart Hook"]
        Migrator["Zero-Loss JIT Migrator"]
    end

    subgraph Storage["Central Data Vault (~/.ag-memory-mcp)"]
        DB[("project-*.db<br/>(SQLite WAL + FTS5)")]
        Index["projects_index.json"]
        Backups["backups/"]
    end

    Clients <-->|"stdio"| Server
    AG -.->|"SessionStart"| Hook
    Server --> Migrator
    Migrator --> Backups
    Server <--> DB
    Server <--> Index

🚀 Quickstart

1. Claude Code

Add to your Claude Code configuration with one command:

claude mcp add agent-memory-mcp -- npx -y agent-memory-mcp

2. Cursor / Windsurf / Cline

Add to your mcpServers configuration (e.g. ~/.cursor/mcp.json or cline settings):

{
  "mcpServers": {
    "agent-memory-mcp": {
      "command": "npx",
      "args": ["-y", "agent-memory-mcp"]
    }
  }
}

3. Google Antigravity (Plugin Bundle)

Install the plugin into your Antigravity plugins directory (~/.gemini/config/plugins/agent-memory/):

git clone https://github.com/msking18/agent-memory-mcp.git ~/.gemini/config/plugins/agent-memory

Restart Antigravity. The plugin enables zero-turn SessionStart context hydration and scoped agent rules automatically.

🛠️ MCP Tools (10 Tools)

📦 MCP Resources

• memory://projects: Exposes a read-only JSON registry of all workspaces tracked by agent-memory-mcp on your machine.

📋 Recommended Agent Rule Template

Add this rule to your agent's system prompt or AGENTS.md / CLAUDE.md:

### Rule: Persistent Project Memory & Anti-Looping
1. Startup: When starting work on a workspace, call `check_memory_status` with the absolute project directory.
2. Bootstrap: If UNINITIALIZED, explore the codebase and save 3 foundational nodes atomically via `save_project_memory`:
   - "Tech Stack & Ecosystem" (slug: "tech-stack", category: "architecture")
   - "Project Structure & Architecture" (slug: "project-structure", category: "architecture")
   - "Build & Run Instructions" (slug: "build-run", category: "architecture")
3. Before Editing Shared Utilities: Call `get_file_memories` with the file paths about to be edited.
4. Error Anti-Looping: Before retrying a failed test, build, or terminal command, call `check_dead_ends`. If a fix fails, record it via `record_dead_end`.
5. Session Log: At the end of a major task, log changes via `save_project_memory` (category: "session", tags: ["changelog"]).

🧪 Testing

Run the automated test suite across SQLite transactions, FTS5 queries, JIT migrations, and stdio JSON-RPC:

npm test

📄 License

MIT © Manveer Singh Kahlon