{
  "markdown": "# RemembrallMCP\n\n![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg) [![Crates.io](https://img.shields.io/crates/v/remembrall-server.svg)](https://crates.io/crates/remembrall-server) [![CI](https://github.com/roboticforce/remembrallmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/roboticforce/remembrallmcp/actions/workflows/ci.yml) [![Docker](https://img.shields.io/docker/pulls/cdnsteve/remembrallmcp.svg)](https://hub.docker.com/r/cdnsteve/remembrallmcp)\n\nWhole-codebase knowledge for AI coding agents. A field-aware code graph plus persistent memory, built on Rust, Postgres + pgvector, and exposed over MCP.\n\n**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.\n\n**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.\n\n**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.\n\n**2. Persistent Memory** - Decisions, patterns, and organizational knowledge that survive between sessions. Hybrid semantic + full-text search finds relevant context instantly.\n\n```\nremembrall_recall(\"authentication middleware patterns\")\n-> 3 relevant memories from past sessions\n\nremembrall_index(\"/path/to/project\", \"myapp\")\n-> Builds dependency graph: 847 symbols, 1,203 relationships\n\nremembrall_impact(\"AuthMiddleware\", direction=\"upstream\")\n-> 12 files depend on AuthMiddleware (with confidence scores)\n\nremembrall_impact(\"amount\", direction=\"upstream\")\n-> methods that read self.amount, across the whole codebase\n\nremembrall_store(\"Switched from JWT to session tokens because...\")\n-> Decision stored for future sessions\n```\n\n### Why the code graph matters\n\nWithout 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.\n\nWith 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.\n\n| | Without RemembrallMCP | With RemembrallMCP |\n|---|---|---|\n| \"What calls UserService?\" | Agent greps, reads 8-15 files, spawns sub-agents | `remembrall_impact` - 1 call, <1ms |\n| \"Where is auth middleware defined?\" | Agent globs, reads matches, filters | `remembrall_lookup_symbol` - 1 call, <1ms |\n| \"Who references the `amount` field?\" | Agent greps for `self.amount`, misses ORM and cross-module usages | `remembrall_impact` - 1 call, <1ms |\n| \"What did we decide about caching?\" | Agent has no context, asks you | `remembrall_recall` - 1 call, ~25ms |\n| Typical exploration cost | 5,000-20,000 tokens per question | ~200 tokens (tool call + response) |\n\nThe 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.\n\nThis 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.\n\n### Benchmarks\n\nRemembrallMCP is currently benchmarked on two surfaces:\n\n- **Agent productivity on code tasks** - Tested on [pallets/click](https://github.com/pallets/click) v8.1.7 (594 symbols, 1,589 relationships). Five identical coding tasks run with and without RemembrallMCP. [Full report](benchmarks/reports/benchmark-2026-04-02.md).\n- **Memory recall quality** - Local recall harness run against 31 ground-truth queries covering search quality, filtering, edge cases, ranking, and latency.\n\n| Metric | Without RemembrallMCP | With RemembrallMCP | Delta |\n|--------|----------------------|---------------------|-------|\n| Total tool calls (5 tasks) | 112 | 5 | **-95.5%** |\n| Estimated tokens | ~56,000 | ~1,000 | **-98.2%** |\n| Avg tool calls per question | 22.4 | 1.0 | **-95.5%** |\n\nThe 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.\n\n| Memory Recall Metric | Result |\n|---|---|\n| Queries passed | **31 / 31** |\n| Recall@5 | **0.917** |\n| Precision@5 | **0.619** |\n| MRR | **0.908** |\n| p95 latency | **14ms** |\n\nRun the benchmarks yourself: see [`benchmarks/`](benchmarks/) for the harness and task definitions.\n\nFor the broader benchmark strategy across memory retrieval, long-horizon memory, code graph correctness, and agent productivity, see [`docs/benchmark-roadmap.md`](docs/benchmark-roadmap.md).\n\n## Requirements\n\n- Docker (for the easiest setup) or PostgreSQL 16 with [pgvector](https://github.com/pgvector/pgvector)\n- For GitHub ingestion: [GitHub CLI](https://cli.github.com/) (`gh`) installed and authenticated\n\n## Quick Start\n\n### Option 1: Docker Compose (easiest)\n\n```bash\ngit clone https://github.com/roboticforce/remembrallmcp.git\ncd remembrallmcp\n\n# Start Postgres, initialize the schema, download the embedding model,\n# and run the MCP server. The remembrall container stays up after setup.\ndocker compose up -d\n\n# Verify it's running (database connected, schema ready)\ndocker compose exec remembrall remembrall status\n```\n\nThat's it. Postgres with pgvector, the schema, and the embedding model are all set up automatically. The database and model cache persist across restarts.\n\nThe `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.\n\nTo connect an MCP client (Claude Code, Cursor, Codex) to the server, see [Connect to your MCP client](#connect-to-your-mcp-client) below.\n\n### Option 2: Download prebuilt binary\n\n```bash\n# macOS (Apple Silicon)\ncurl -fsSL https://github.com/roboticforce/remembrallmcp/releases/latest/download/remembrall-aarch64-apple-darwin.tar.gz | tar xz\nsudo mv remembrall /usr/local/bin/\n\n# Linux (x86_64)\ncurl -fsSL https://github.com/roboticforce/remembrallmcp/releases/latest/download/remembrall-x86_64-unknown-linux-gnu.tar.gz | tar xz\nsudo mv remembrall /usr/local/bin/\n\n# Initialize (sets up Postgres via Docker, creates schema, downloads model)\nremembrall init\n```\n\n### Option 3: Build from source (requires Rust 1.94+)\n\n```bash\ncargo build -p remembrall-server --release\n# Binary is at target/release/remembrall\n\nremembrall init\n```\n\n### Connect to your MCP client\n\n#### Codex\n\nCodex 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.\n\n**If `remembrall` is installed in `PATH`:**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"remembrall\"\n    }\n  }\n}\n```\n\n**If running from a local source checkout:**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"/path/to/remembrallmcp/target/release/remembrall\",\n      \"env\": {\n        \"DATABASE_URL\": \"postgres://postgres:postgres@localhost:5450/remembrall\"\n      }\n    }\n  }\n}\n```\n\n**If using Docker Compose from Codex:**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"docker\",\n      \"args\": [\"compose\", \"-f\", \"/path/to/remembrallmcp/docker-compose.yml\", \"run\", \"--rm\", \"-T\", \"remembrall\"]\n    }\n  }\n}\n```\n\nRestart Codex after adding the server so it reconnects and loads the tools.\n\n#### Claude Code, Cursor, and other MCP clients\n\nAdd to your project's `.mcp.json` (works with Claude Code, Cursor, and any MCP-compatible client).\n\n**If using a prebuilt binary or built from source:**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"remembrall\"\n    }\n  }\n}\n```\n\n**If using Docker Compose:**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"docker\",\n      \"args\": [\"compose\", \"-f\", \"/path/to/remembrallmcp/docker-compose.yml\", \"run\", \"--rm\", \"-T\", \"remembrall\"]\n    }\n  }\n}\n```\n\nEach 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`.\n\n**If running from source (not installed to PATH):**\n\n```json\n{\n  \"mcpServers\": {\n    \"remembrall\": {\n      \"command\": \"/path/to/remembrallmcp/target/release/remembrall\",\n      \"env\": {\n        \"DATABASE_URL\": \"postgres://postgres:postgres@localhost:5450/remembrall\"\n      }\n    }\n  }\n}\n```\n\nRestart your MCP client. All 9 tools will be available automatically.\n\n### Try it\n\n```\n> \"Store a memory: We chose Postgres over MongoDB because our query patterns\n   are relational. Type: decision, tags: database, architecture\"\n\n> \"Recall what we know about database decisions\"\n\n> \"Index this project and show me the impact of changing UserService\"\n```\n\n## MCP Tools\n\n### Memory\n\n| Tool | Description |\n|------|-------------|\n| `remembrall_recall` | Search memories - hybrid semantic + full-text with RRF fusion |\n| `remembrall_store` | Store decisions, patterns, knowledge with vector embeddings |\n| `remembrall_update` | Update an existing memory (content, summary, tags, or importance) |\n| `remembrall_delete` | Remove a memory by UUID |\n| `remembrall_ingest_github` | Bulk-import merged PR descriptions from a GitHub repo |\n| `remembrall_ingest_docs` | Scan a directory for markdown files and ingest them as memories |\n\n### Code Intelligence\n\n| Tool | Description |\n|------|-------------|\n| `remembrall_index` | Parse a project directory into a field-aware code graph (functions, classes, methods, and fields across 9 languages) |\n| `remembrall_impact` | Blast radius analysis - \"what breaks if I change this?\" Works on functions, classes, methods, and fields |\n| `remembrall_lookup_symbol` | Find where a function, class, method, or field is defined across the project |\n\n## Supported Languages\n\n| Language | Extensions | Quality Score |\n|----------|-----------|---------------|\n| Python | .py | A (94.1) |\n| Java | .java | A (92.6) |\n| JavaScript | .js, .jsx | A (92.0) |\n| Rust | .rs | A (91.0) |\n| Go | .go | A (90.7) |\n| Ruby | .rb | B (87.9) |\n| TypeScript | .ts, .tsx | B (84.3) |\n| Kotlin | .kt, .kts | B (82.9) |\n| C# | .cs | A (96.8) |\n\nScores 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%.\n\n## Cold Start\n\nA new RemembrallMCP instance has no knowledge. Use the ingestion tools to bootstrap from existing project history.\n\n**From GitHub PR history:**\n\n```\n> remembrall_ingest_github repo=\"myorg/myrepo\" limit=100\n```\n\nFetches 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.\n\n**From markdown docs:**\n\n```\n> remembrall_ingest_docs path=\"/path/to/project\"\n```\n\nWalks 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.\n\nRun both once per project. After ingestion, `remembrall_recall` has immediate context.\n\n## Architecture\n\n```\nSource Code                   Organizational Knowledge\n    |                                 |\n    v                                 v\nTree-sitter Parsers           Ingestion Pipeline\n(9 languages)                 (GitHub PRs, Markdown docs)\n    |                                 |\n    v                                 v\n+--------------------------------------------------+\n|              Postgres + pgvector                  |\n|                                                   |\n|  memories (text + embeddings + metadata)          |\n|  symbols (functions, classes, methods, fields)    |\n|  relationships (calls, imports, defines,          |\n|                 inherits, references)             |\n+--------------------------------------------------+\n                          |\n                    MCP Server (stdio)\n                          |\n              Any MCP-compatible AI agent\n```\n\n- **Parsing:** tree-sitter (Rust bindings, no Python in the pipeline)\n- **Embeddings:** fastembed (all-MiniLM-L6-v2, 384-dim, in-process ONNX Runtime)\n- **Search:** Hybrid RRF (semantic cosine similarity + full-text tsvector)\n- **Graph queries:** Recursive CTEs with cycle detection and confidence decay\n- **Transport:** stdio via rmcp\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `remembrall init` | Set up database, schema, and embedding model |\n| `remembrall serve` | Run the MCP server (default when no subcommand given) |\n| `remembrall start` | Start the Docker database container |\n| `remembrall stop` | Stop the Docker database container |\n| `remembrall status` | Show memory count, symbol count, connection status |\n| `remembrall doctor` | Check for common problems (Docker, pgvector, schema, model) |\n| `remembrall reset --force` | Drop and recreate the schema (deletes all data) |\n| `remembrall version` | Print version and config path |\n\n## Configuration\n\nConfig file: `~/.remembrall/config.toml` (created by `remembrall init`)\n\nEnvironment variables override config file values:\n\n| Variable | Description |\n|----------|-------------|\n| `REMEMBRALL_DATABASE_URL` or `DATABASE_URL` | PostgreSQL connection string |\n| `REMEMBRALL_SCHEMA` | Database schema name (default: `remembrall`) |\n\n## Project Structure\n\n```\ncrates/\n  remembrall-core/          # Library - parsers, memory store, graph store, embedder\n  remembrall-server/        # MCP server + CLI binary\n  remembrall-test-harness/  # Parser quality testing against ground truth\n  remembrall-recall-test/   # Search quality testing\ndocs/                       # Architecture and test plan docs\ntest-fixtures/              # Ground truth TOML files for 9 languages\ntests/                      # Recall test fixtures\n```\n\n## Performance\n\n| Operation | Time |\n|-----------|------|\n| Memory store | 7ms |\n| Semantic search (HNSW) | <1ms |\n| Full-text search | <1ms |\n| Hybrid recall (end-to-end) | ~25ms |\n| Impact analysis | 4-9ms |\n| Symbol lookup | <1ms |\n| Index 89 Python files | 2.3s |\n\n## License\n\nMIT\n",
  "bytes": 15701,
  "sha": "e477a52ea60c7a92d782ff37fa74524355fe1ec6ea5ac94242a4044a4357a6ee",
  "repo_slug": "cdnsteve/remembrallmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cdnsteve_remembrallmcp_4aa491d0/readme"
}