RemembrallMCP

RemembrallMCP

为 AI 编码 Agent 提供完整代码库知识。基于 Rust、Postgres + pgvector 构建，包含字段感知代码图谱和持久记忆，并通过 MCP 提供服务。

问题： AI 编码 Agent 每次会话只能看到书中的几页。它们需要从头开始 grep、阅读并重新推导代码库各部分如何协作——没有调用关系图谱，不知道更改会导致什么问题，也不记得过去会话中做出的决定。

解决方案： RemembrallMCP 为 Agent 提供完整代码库——跨 9 种语言的字段感知依赖图（函数、类、方法、字段及其相互引用），以及可跨会话保留的持久记忆。

1. 字段感知代码图谱 - 使用 tree-sitter 构建的实时代码库地图。涵盖 9 种语言中的函数、类、方法和数据字段，以及调用、导入、定义、继承和字段引用关系。询问“如果更改这个，会有什么影响？”——精确到单个结构体字段——即可在毫秒内得到答案，Agent 无需触碰任何内容。

2. 持久记忆 - 可跨会话保留的决策、模式和组织知识。混合语义 + 全文搜索可即时找到相关上下文。

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

为什么代码图谱很重要

没有 RemembrallMCP 时，Agent 每次会话都要从头探索代码库。Claude Code 会启动 Explore Agent，Codex 会读取数十个文件，Cursor 会在目录中 grep——仅仅为了弄清楚调用关系，就要耗费 token 和时间。单是一个“找出此函数的所有调用方”任务，就可能通过多次工具调用消耗数千个 token。

有了 RemembrallMCP，同样的查询只需调用一次 remembrall_impact，不到 1ms 即可返回，且无需消耗探索 token。依赖图已经构建完成，随时可用。

	不使用 RemembrallMCP	使用 RemembrallMCP
“谁调用了 UserService？”	Agent 使用 grep，读取 8-15 个文件，启动子 Agent	remembrall_impact - 1 次调用，<1ms
“身份验证中间件定义在哪里？”	Agent 使用 glob，读取匹配项并筛选	remembrall_lookup_symbol - 1 次调用，<1ms
“谁引用了 amount 字段？”	Agent 搜索 self.amount，遗漏 ORM 和跨模块用法	remembrall_impact - 1 次调用，<1ms
“我们对缓存做了什么决定？”	Agent 没有上下文，只能询问你	remembrall_recall - 1 次调用，约 25ms
典型探索成本	每个问题 5,000-20,000 个 token	约 200 个 token（工具调用 + 响应）

代码库越大，节省越多。在小型项目中，Agent 可以通过 grep 和阅读来逐步了解代码。在包含 500 个文件的单体仓库中，这种探索会成为瓶颈——Agent 会达到上下文限制、启动多个子 Agent，或完全遗漏跨模块依赖。RemembrallMCP 的图谱查询无论项目大小都能保持在 10ms 以内，因为结构已预先索引到 Postgres 中，而不是在运行时才发现。

这就是每次都只读书中几页的 Agent，与已经掌握整个代码库的 Agent 之间的区别。

基准测试

RemembrallMCP 目前针对两个方面进行了基准测试：

• 代码任务中的 Agent 效率 - 在 pallets/click v8.1.7（594 个符号、1,589 个关系）上进行测试。分别在使用和不使用 RemembrallMCP 的情况下运行五项相同的编码任务。完整报告。
• 记忆召回质量 - 使用本地召回测试框架，对涵盖搜索质量、筛选、边界情况、排序和延迟的 31 条真实查询进行测试。

指标	不使用 RemembrallMCP	使用 RemembrallMCP	差值
工具调用总数（5 项任务）	112	5	-95.5%
预估 Token 数	~56,000	~1,000	-98.2%
每个问题的平均工具调用次数	22.4	1.0	-95.5%

在更大的代码库上，节省效果会进一步累积。Click 约有 90 个文件——在拥有 500 多个文件的单体代码库中，不使用 RemembrallMCP 的 Agent 需要按比例进行更多探索调用，而图查询无论规模大小都能保持在 10ms 以内。

记忆召回指标	结果
通过的查询数	31 / 31
Recall@5	0.917
Precision@5	0.619
MRR	0.908
p95 延迟	14ms

亲自运行基准测试：请参阅 benchmarks/，了解测试框架和任务定义。

如需了解涵盖记忆检索、长时程记忆、代码图正确性和 Agent 效率的整体基准测试策略，请参阅 docs/benchmark-roadmap.md。

要求

• Docker（最简单的设置方式），或安装了 pgvector 的 PostgreSQL 16
• 如需采集 GitHub 数据：安装并完成身份验证的 GitHub CLI（gh）

快速开始

选项 1：Docker Compose（最简单）

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

就是这样。Postgres、pgvector、架构和嵌入模型都会自动完成设置。数据库和模型缓存会在重启后保留。

remembrall 容器启动时会运行 remembrall init（幂等设置），然后运行 remembrall serve，因此它会持续运行，且 docker compose exec 可用于执行状态检查、doctor 和其他命令。

要将 MCP 客户端（Claude Code、Cursor、Codex）连接到服务，请参阅下文的连接到 MCP 客户端。

选项 2：下载预构建二进制文件

# 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

选项 3：从源代码构建（需要 Rust 1.94+）

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

remembrall init

连接到 MCP 客户端

Codex

Codex 使用相同的 MCP 服务定义格式。将服务注册为 remembrall，并将其指向已安装的二进制文件或本地发布版本构建。

如果 remembrall 已安装在 PATH 中：

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

如果从本地源代码检出目录运行：

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

如果在 Codex 中使用 Docker Compose：

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

添加服务后，重启 Codex，以便它重新连接并加载工具。

Claude Code、Cursor 和其他 MCP 客户端

将配置添加到项目的 .mcp.json 中（适用于 Claude Code、Cursor 和任何兼容 MCP 的客户端）。

如果使用预构建二进制文件或从源代码构建：

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

如果使用 Docker Compose：

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

每次调用都会启动一个全新的容器，运行 remembrall init（幂等；其输出会发送到 stderr，因此不会破坏 MCP 流），然后通过 stdio 运行 remembrall serve。必须使用 -T 标志，以禁用 TTY 分配，确保 JSON-RPC 能够正常传递。db 服务会通过 depends_on 自动启动。

如果从源代码运行（未安装到 PATH）：

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

重启 MCP 客户端。全部 9 个工具将自动可用。

试用

> "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 工具

记忆

工具	描述
remembrall_recall	搜索记忆——结合语义搜索与全文搜索，并使用 RRF 融合
remembrall_store	使用向量嵌入存储决策、模式和知识
remembrall_update	更新现有记忆（内容、摘要、标签或重要性）
remembrall_delete	按 UUID 删除记忆
remembrall_ingest_github	从 GitHub 仓库批量导入已合并 PR 的描述
remembrall_ingest_docs	扫描目录中的 Markdown 文件，并将其导入为记忆

代码智能

工具	描述
remembrall_index	将项目目录解析为具备字段感知能力的代码图（涵盖 9 种语言中的函数、类、方法和字段）
remembrall_impact	影响范围分析——“如果我更改此处，会有哪些内容出问题？”适用于函数、类、方法和字段
remembrall_lookup_symbol	查找项目中函数、类、方法或字段的定义位置

支持的语言

语言	扩展名	质量评分
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)

这些评分是通过自动化基准测试，针对真实开源项目（Click、Gson、Axios、bat、Cobra、Sidekiq、Hono、Exposed、MediatR）测得的。C# 评分以 MediatR 12.4.1 为基准（69 个符号、48 个关系、9 个影响查询、10 个边界案例）：符号、导入和边界案例的准确率均为 100%；差距来自泛型接口继承（: IPipelineBehavior<TRequest, TResponse> 被解析为合成 UUID，而非类符号）以及一次字段分派调用解析错误。C# 字段级引用通过字段捕获测试夹具单独验证，准确率为 100%。

冷启动

新的 RemembrallMCP 实例不包含任何知识。使用导入工具，从现有项目历史中进行初始化。

从 GitHub PR 历史导入：

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

通过 gh 获取已合并的 PR，将标题和正文整理为记忆，并按项目添加标签。正文少于 50 个字符的 PR 会被跳过。基于内容指纹进行去重，避免重复运行时再次导入相同内容。

从 Markdown 文档导入：

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

遍历目录树，查找所有 .md 文件，按 H2 章节标题拆分，并将每个章节存储为可搜索的记忆。跳过 node_modules、.git、target 等目录。适用于 README、ARCHITECTURE、ADR 和各类文档。

每个项目运行一次这两种导入。导入后，remembrall_recall 即可立即获取上下文。

架构

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

• 解析： tree-sitter（Rust 绑定，处理流水线中不使用 Python）
• 嵌入： fastembed（all-MiniLM-L6-v2，384 维，进程内 ONNX Runtime）
• 搜索： 混合 RRF（语义余弦相似度 + 全文 tsvector）
• 图查询： 带环检测和置信度衰减的递归 CTE
• 传输： 通过 rmcp 使用 stdio

CLI 命令

命令	描述
remembrall init	设置数据库、架构和嵌入模型
remembrall serve	运行 MCP 服务（未指定子命令时的默认命令）
remembrall start	启动 Docker 数据库容器
remembrall stop	停止 Docker 数据库容器
remembrall status	显示记忆数量、符号数量和连接状态
remembrall doctor	检查常见问题（Docker、pgvector、架构、模型）
remembrall reset --force	删除并重新创建架构（删除所有数据）
remembrall version	输出版本和配置路径

配置

配置文件：~/.remembrall/config.toml（由 remembrall init 创建）

环境变量会覆盖配置文件中的值：

变量	描述
REMEMBRALL_DATABASE_URL 或 DATABASE_URL	PostgreSQL 连接字符串
REMEMBRALL_SCHEMA	数据库架构名称（默认值：remembrall）

项目结构

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

性能

操作	耗时
存储记忆	7ms
语义搜索（HNSW）	<1ms
全文搜索	<1ms
混合召回（端到端）	~25ms
影响分析	4-9ms
符号查找	<1ms
为 89 个 Python 文件建立索引	2.3s

许可证

MIT