RemembrallMCP

Persistent knowledge memory and code intelligence for AI agents. Rust core, Postgres + pgvector, MCP protocol.

The problem: AI coding agents are stateless. Every session starts from zero - no memory of past decisions, no understanding of how the codebase fits together, no way to know what breaks when you change something.

The solution: RemembrallMCP gives agents two things most memory tools don't:

1. Persistent Memory - Decisions, patterns, and organizational knowledge that survive between sessions. Hybrid semantic + full-text search finds relevant context instantly.

2. Code Dependency Graph - A live map of your codebase built with tree-sitter. Functions, classes, imports, and call relationships across 8 languages. Ask "what breaks if I change this?" and get an answer in milliseconds - before the agent touches anything.

remembrall_recall("authentication middleware patterns")
-> 3 relevant memories from past sessions

remembrall_index("/path/to/project", "myapp")
-> Builds dependency graph: 847 symbols, 1,203 relationships

remembrall_impact("AuthMiddleware", direction="upstream")
-> 12 files depend on AuthMiddleware (with confidence scores)

remembrall_store("Switched from JWT to session tokens because...")
-> Decision stored for future sessions

Why the code graph matters

Without RemembrallMCP, agents explore your codebase from scratch every session. Claude Code spawns Explore agents, Codex reads dozens of files, Cursor greps through directories - all burning tokens and time just to understand what calls what. A single "find all callers of this function" task can cost thousands of tokens across multiple tool calls.

With RemembrallMCP, that same query is a single remembrall_impact call that returns in <1ms with zero exploration tokens. The dependency graph is already built and waiting.

| | Without RemembrallMCP | With RemembrallMCP | |---|---|---| | "What calls UserService?" | Agent greps, reads 8-15 files, spawns sub-agents | remembrall_impact - 1 call, <1ms | | "Where is auth middleware defined?" | Agent globs, reads matches, filters | remembrall_lookup_symbol - 1 call, <1ms | | "What did we decide about caching?" | Agent has no context, asks you | remembrall_recall - 1 call, ~25ms | | Typical exploration cost | 5,000-20,000 tokens per question | ~200 tokens (tool call + response) |

The savings scale with codebase size. On a small project, an agent can grep and read its way through. On a 500-file monorepo, that exploration becomes the bottleneck - agents hit context limits, spawn multiple sub-agents, or miss cross-module dependencies entirely. RemembrallMCP's graph queries stay under 10ms regardless of project size because the structure is pre-indexed in Postgres, not discovered at runtime.

This is the difference between an agent that explores your codebase every time and one that already understands it.

Benchmarks

RemembrallMCP is currently benchmarked on two surfaces:

• Agent productivity on code tasks - Tested on pallets/click v8.1.7 (594 symbols, 1,589 relationships). Five identical coding tasks run with and without RemembrallMCP. Full report.
• Memory recall quality - Local recall harness run against 31 ground-truth queries covering search quality, filtering, edge cases, ranking, and latency.

| Metric | Without RemembrallMCP | With RemembrallMCP | Delta | |--------|----------------------|---------------------|-------| | Total tool calls (5 tasks) | 112 | 5 | -95.5% | | Estimated tokens | ~56,000 | ~1,000 | -98.2% | | Avg tool calls per question | 22.4 | 1.0 | -95.5% |

The savings compound on larger codebases. Click is ~90 files - on a 500+ file monorepo, agents without RemembrallMCP need proportionally more exploration calls, while graph queries stay under 10ms regardless of size.

| Memory Recall Metric | Result | |---|---| | Queries passed | 31 / 31 | | Recall@5 | 0.917 | | Precision@5 | 0.619 | | MRR | 0.908 | | p95 latency | 14ms |

Run the benchmarks yourself: see benchmarks/ for the harness and task definitions.

For the broader benchmark strategy across memory retrieval, long-horizon memory, code graph correctness, and agent productivity, see docs/benchmark-roadmap.md.

Requirements

• Docker (for the easiest setup) or PostgreSQL 16 with pgvector
• For GitHub ingestion: GitHub CLI (gh) installed and authenticated

Quick Start

Option 1: Docker Compose (easiest)

git clone https://github.com/cdnsteve/remembrallmcp.git
cd remembrallmcp

# Start Postgres + initialize schema + download embedding model
docker compose up -d

# Verify it's running
docker compose exec remembrall remembrall status

That's it. Postgres with pgvector, the schema, and the embedding model are all set up automatically. The database and model cache persist across restarts.

To run the MCP server:

docker compose run --rm remembrall

Option 2: Download prebuilt binary

# macOS (Apple Silicon)
curl -fsSL https://github.com/cdnsteve/remembrallmcp/releases/latest/download/remembrall-aarch64-apple-darwin.tar.gz | tar xz
sudo mv remembrall /usr/local/bin/

# Linux (x86_64)
curl -fsSL https://github.com/cdnsteve/remembrallmcp/releases/latest/download/remembrall-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv remembrall /usr/local/bin/

# Initialize (sets up Postgres via Docker, creates schema, downloads model)
remembrall init

Option 3: Build from source (requires Rust 1.94+)

cargo build -p remembrall-server --release
# Binary is at target/release/remembrall

remembrall init

Connect to your MCP client

Codex

Codex uses the same MCP server definition format. Register the server as remembrall and point it at either the installed binary or your local release build.

If remembrall is installed in PATH:

{
  "mcpServers": {
    "remembrall": {
      "command": "remembrall"
    }
  }
}

If running from a local source checkout:

{
  "mcpServers": {
    "remembrall": {
      "command": "/path/to/remembrallmcp/target/release/remembrall",
      "env": {
        "DATABASE_URL": "postgres://postgres:postgres@localhost:5450/remembrall"
      }
    }
  }
}

If using Docker Compose from Codex:

{
  "mcpServers": {
    "remembrall": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/remembrallmcp/docker-compose.yml", "run", "--rm", "-T", "remembrall"]
    }
  }
}

Restart Codex after adding the server so it reconnects and loads the tools.

Claude Code, Cursor, and other MCP clients

Add to your project's .mcp.json (works with Claude Code, Cursor, and any MCP-compatible client).

If using a prebuilt binary or built from source:

{
  "mcpServers": {
    "remembrall": {
      "command": "remembrall"
    }
  }
}

If using Docker Compose:

{
  "mcpServers": {
    "remembrall": {
      "command": "docker",
      "args": ["compose", "-f", "/path/to/remembrallmcp/docker-compose.yml", "run", "--rm", "-T", "remembrall"]
    }
  }
}

If running from source (not installed to PATH):

{
  "mcpServers": {
    "remembrall": {
      "command": "/path/to/remembrallmcp/target/release/remembrall",
      "env": {
        "DATABASE_URL": "postgres://postgres:postgres@localhost:5450/remembrall"
      }
    }
  }
}

Restart your MCP client. All 9 tools will be available automatically.

Try it

> "Store a memory: We chose Postgres over MongoDB because our query patterns
   are relational. Type: decision, tags: database, architecture"

> "Recall what we know about database decisions"

> "Index this project and show me the impact of changing UserService"

MCP Tools

Memory

| Tool | Description | |------|-------------| | remembrall_recall | Search memories - hybrid semantic + full-text with RRF fusion | | remembrall_store | Store decisions, patterns, knowledge with vector embeddings | | remembrall_update | Update an existing memory (content, summary, tags, or importance) | | remembrall_delete | Remove a memory by UUID | | remembrall_ingest_github | Bulk-import merged PR descriptions from a GitHub repo | | remembrall_ingest_docs | Scan a directory for markdown files and ingest them as memories |

Code Intelligence

| Tool | Description | |------|-------------| | remembrall_index | Parse a project directory into a dependency graph (8 languages) | | remembrall_impact | Blast radius analysis - "what breaks if I change this?" | | remembrall_lookup_symbol | Find where a function or class is defined across the project |

Supported Languages

| Language | Extensions | Quality Score | |----------|-----------|---------------| | Python | .py | A (94.1) | | Java | .java | A (92.6) | | JavaScript | .js, .jsx | A (92.0) | | Rust | .rs | A (91.0) | | Go | .go | A (90.7) | | Ruby | .rb | B (87.9) | | TypeScript | .ts, .tsx | B (84.3) | | Kotlin | .kt, .kts | B (82.9) |

Scores measured against real open-source projects (Click, Gson, Axios, bat, Cobra, Sidekiq, Hono, Exposed) using automated ground truth tests.

Cold Start

A new RemembrallMCP instance has no knowledge. Use the ingestion tools to bootstrap from existing project history.

From GitHub PR history:

> remembrall_ingest_github repo="myorg/myrepo" limit=100

Fetches merged PRs via gh, digests titles and bodies into memories, and tags them by project. PRs with less than 50 characters of body are skipped. Deduplication by content fingerprint prevents re-ingestion on repeat runs.

From markdown docs:

> remembrall_ingest_docs path="/path/to/project"

Walks the directory tree, finds all .md files, splits them by H2 section headers, and stores each section as a searchable memory. Skips node_modules, .git, target, and similar directories. Good for README, ARCHITECTURE, ADRs, and any written docs.

Run both once per project. After ingestion, remembrall_recall has immediate context.

Architecture

Source Code                   Organizational Knowledge
    |                                 |
    v                                 v
Tree-sitter Parsers           Ingestion Pipeline
(8 languages)                 (GitHub PRs, Markdown docs)
    |                                 |
    v                                 v
+--------------------------------------------------+
|              Postgres + pgvector                  |
|                                                   |
|  memories (text + embeddings + metadata)          |
|  symbols (functions, classes, methods)            |
|  relationships (calls, imports, inherits)         |
+--------------------------------------------------+
                          |
                    MCP Server (stdio)
                          |
              Any MCP-compatible AI agent

• Parsing: tree-sitter (Rust bindings, no Python in the pipeline)
• Embeddings: fastembed (all-MiniLM-L6-v2, 384-dim, in-process ONNX Runtime)
• Search: Hybrid RRF (semantic cosine similarity + full-text tsvector)
• Graph queries: Recursive CTEs with cycle detection and confidence decay
• Transport: stdio via rmcp

CLI Commands

| Command | Description | |---------|-------------| | remembrall init | Set up database, schema, and embedding model | | remembrall serve | Run the MCP server (default when no subcommand given) | | remembrall start | Start the Docker database container | | remembrall stop | Stop the Docker database container | | remembrall status | Show memory count, symbol count, connection status | | remembrall doctor | Check for common problems (Docker, pgvector, schema, model) | | remembrall reset --force | Drop and recreate the schema (deletes all data) | | remembrall version | Print version and config path |

Configuration

Config file: ~/.remembrall/config.toml (created by remembrall init)

Environment variables override config file values:

| Variable | Description | |----------|-------------| | REMEMBRALL_DATABASE_URL or DATABASE_URL | PostgreSQL connection string | | REMEMBRALL_SCHEMA | Database schema name (default: remembrall) |

Project Structure

crates/
  remembrall-core/          # Library - parsers, memory store, graph store, embedder
  remembrall-server/        # MCP server + CLI binary
  remembrall-test-harness/  # Parser quality testing against ground truth
  remembrall-recall-test/   # Search quality testing
docs/                       # Architecture and test plan docs
test-fixtures/              # Ground truth TOML files for 8 languages
tests/                      # Recall test fixtures

Performance

| Operation | Time | |-----------|------| | Memory store | 7ms | | Semantic search (HNSW) | <1ms | | Full-text search | <1ms | | Hybrid recall (end-to-end) | ~25ms | | Impact analysis | 4-9ms | | Symbol lookup | <1ms | | Index 89 Python files | 2.3s |

License

MIT