RemembrallMCP

RemembrallMCP

Whole-codebase knowledge for AI coding agents. A field-aware code graph plus persistent memory, built on Rust, Postgres + pgvector, and exposed over MCP.

The problem: AI coding agents see a few pages out of the book each session. They grep, read, and re-derive how the codebase fits together from scratch - no map of what calls what, no way to know what breaks when something changes, and no memory of decisions made in past sessions.

The solution: RemembrallMCP gives the agent the whole codebase - a field-aware dependency graph (functions, classes, methods, fields, and the references between them) across 9 languages, plus persistent memory that survives between sessions.

1. Field-Aware Code Graph - A live map of your codebase built with tree-sitter. Functions, classes, methods, and data fields, plus call, import, defines, inherits, and field-reference relationships across 9 languages. Ask "what breaks if I change this?" - down to a single struct field - and get an answer in milliseconds, before the agent touches anything.

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

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_impact("amount", direction="upstream")
-> methods that read self.amount, across the whole codebase

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
"Who references the amount field?"	Agent greps for self.amount, misses ORM and cross-module usages	remembrall_impact - 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 reads a few pages out of the book every time and one that already holds the whole codebase.

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/roboticforce/remembrallmcp.git
cd remembrallmcp

# Start Postgres, initialize the schema, download the embedding model,
# and run the MCP server. The remembrall container stays up after setup.
docker compose up -d

# Verify it's running (database connected, schema ready)
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.

The remembrall container runs remembrall init (idempotent setup) followed by remembrall serve on startup, so it stays running and docker compose exec works for status, doctor, and other commands.

To connect an MCP client (Claude Code, Cursor, Codex) to the server, see Connect to your MCP client below.

Option 2: Download prebuilt binary

# macOS (Apple Silicon)
curl -fsSL https://github.com/roboticforce/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/roboticforce/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"]
    }
  }
}

Each invocation starts a fresh container, runs remembrall init (idempotent; its output goes to stderr so it never corrupts the MCP stream), then remembrall serve over stdio. The -T flag is required - it disables TTY allocation so JSON-RPC passes through cleanly. The db service starts automatically via depends_on.

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 field-aware code graph (functions, classes, methods, and fields across 9 languages)
remembrall_impact	Blast radius analysis - "what breaks if I change this?" Works on functions, classes, methods, and fields
remembrall_lookup_symbol	Find where a function, class, method, or field 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)
C#	.cs	A (96.8)

Scores measured against real open-source projects (Click, Gson, Axios, bat, Cobra, Sidekiq, Hono, Exposed, MediatR) using automated ground truth tests. The C# score is measured against MediatR 12.4.1 (69 symbols, 48 relationships, 9 impact queries, 10 edge cases): symbols, imports, and edge cases at 100%, with the gap coming from generic-interface inheritance (: IPipelineBehavior<TRequest, TResponse> resolves to a synthetic UUID instead of the class symbol) and a field-dispatch call misresolution. C# field-level references are validated separately by the field-capture fixture at 100%.

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
(9 languages)                 (GitHub PRs, Markdown docs)
    |                                 |
    v                                 v
+--------------------------------------------------+
|              Postgres + pgvector                  |
|                                                   |
|  memories (text + embeddings + metadata)          |
|  symbols (functions, classes, methods, fields)    |
|  relationships (calls, imports, defines,          |
|                 inherits, references)             |
+--------------------------------------------------+
                          |
                    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 9 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