Memtrace

你的 Agent 值得拥有结构化记忆。

Syncable 官方 Memtrace。 请从 memtrace.io/docs 开始。官方软件包是 npm 上的 memtrace，公开代码库是 syncable-dev/memtrace-public。其他同名项目与此无关。请将 memtrace --version 与稳定版和 Nightly 版本历史进行比较。

如需安装支持，请在官方公开代码库中提交问题，并附上你的操作系统、Memtrace 版本和准确的错误信息。分享日志时，请移除凭据和私有源代码。Syncable 团队负责维护此软件包及其支持渠道。

📖 文档  ·  ⭐ 为我们加星  ·  memtrace.io  ·  npm  ·  Discord

Memtrace 将你的代码库转化为实时知识图谱，让 AI 编码 Agent 能在毫秒内查询所有会话中的每个函数、类、调用边和版本，无需重新读取文件，也不会破坏它们看不到的内容。

不到 90 秒，即可让你的 Agent 集群使用共享的结构化记忆。

结构化 · 零 LLM 调用  ·  双时态 · 时间回溯查询  ·  支持回放 · 零盲目重构

---

DeepSeek Harness

Memtrace 可作为 DeepSeek Harness 插件运行。请先安装 Harness（npm install -g @deepseek-ai/dsh — 对应的命令是 dsh），然后添加 Memtrace：

npx -y @deepseek-ai/dsh plugin --profile web add github:syncable-dev/dsh-plugin-memtrace

然后让 Agent 为工作区建立索引，并提取影响范围、演进历程或架构简报。详情请见：syncable-dev/dsh-plugin-memtrace。

---

功能

每次发布都提供三项功能。

🧭   在同一代码仓库上运行一组编码 Agent，避免合并混乱。 每个 Agent 读取相同的调用图，了解相同的影响范围，并继承相同的时间历史。不会发生冲突，也不会出现过时的上下文。

🔁   在充分了解因果关系的情况下重放任意重构。 Agent 能准确看到依赖关系，以及每项变更发生的时间。不再有 “我重构了一个函数，结果 14 个没人发现的测试挂了。”

⚡   在 90 秒内为一个含 5 万个文件的代码仓库建立索引。 采用 Rust + Tree-sitter，API 成本为 $0，支持 20 多种语言和框架感知扫描器（Vapor、Lapis、Kong、GitHub Actions、Terraform、RLS 策略，等等），完全在本地运行。你的代码绝不会离开你的设备。

🆕   LeanCTX Native — 压缩读取、智能树和价值账本。 为 get_source_window 新增四种压缩模式、单次调用即可生成目录映射、实时 Token 节省仪表板，以及一个可选启用的自适应学习器，其表现比静态表高约 14%。完整说明：docs/leanctx-native.md。v0.3.57+ 版本可用。

https://github.com/user-attachments/assets/e7d6a1e9-c912-4e65-a421-bd0256dffa5a

---

数据

操作	Memtrace	最佳替代方案	Δ
为 1,500 个文件建立索引	1.5s · $0	Mem0：31 min · $10–50	快约 1,200×
精确符号查询（acc@1，延迟）	96.6% · 0.07 ms	GitNexus：97.0% · 8.95 ms	延迟降低 128×
图调用方召回率（Django）	81.6%	GitNexus：5.3%	15.4×
增量重新索引 p95	42.5 ms	CodeGrapher：613.7 ms	14.4×
混合 acc@1（Django，3K 个案例）	73.9%	GitNexus：38.6%	1.91×
PR 代码审查 F1（50 个 PR）	0.7268	Cubic v2：0.6077	+19.60%
RSS／进程	26 MB	ChromaDB：1,060 MB	内存占用低 41×
语言	16+（Tree-sitter）	各不相同	—

可复现的基准测试套件：benchmarks/。相同的机器、相同的语料库、相同的适配器约定。基准真值来自 Python 的 ast 和 pyright LSP，绝不取自任何工具自身的索引。数据集不会让任何系统占据主场优势。

详细分析：BENCHMARKS-v0.3.22.md · BENCHMARKS-v0.3.29.md · 代码审查器基准测试

---

GitHub Star 增长

---

获取访问权限

Memtrace 目前处于私有 Beta 测试阶段。我们正分批开放访问权限，以便及时收集反馈——每批用户都会进入一个 Discord 频道，我们会在一周内根据真实的错误报告发布修复。

→ 在 memtrace.io 加入候补名单。

已经获得访问权限？运行 npm install -g memtrace，90 秒内即可开始建立索引。完整设置说明见下文。

🔒 隐私。 Memtrace 完全在你的设备上运行。源代码绝不会离开你的设备。唯一的网络通信包括许可证验证、聚合节点／边计数，以及可选择退出的崩溃遥测——不包含源代码、文件路径或符号名称。完整说明：PRIVACY.md、TELEMETRY.md。使用 MEMTRACE_TELEMETRY=off 可禁用遥测。

---

Memtrace 为何存在

现有优秀的代码智能工具已经不少。GitNexus 和 CodeGrapherContext 构建基于 AST 的图，适用于*"当前代码仓库中有什么"。*

**Memtrace 是一个双时态情景结构知识图谱。**它基于相同的 AST 基础，并增加了两个维度：

• 时间记忆 — 每个符号都带有完整的版本历史。六种评分算法（影响、新颖度、近期性、方向性、复合、概览）让 Agent 能提出不同的时间相关问题："改了什么？"、"有什么出乎意料？"、"什么会出问题？"
• 跨服务 API 拓扑 — Memtrace 可映射仓库之间的 HTTP 调用图，检测架构中的哪些服务会调用哪些端点。

此外，结构层也十分全面：

符号是节点	函数、类、接口、类型、端点
关系是边	CALLS、IMPLEMENTS、IMPORTS、EXPORTS、CONTAINS
社区检测	Louvain 算法可自动识别架构模块
混合检索	Tantivy BM25 + 向量嵌入 + Reciprocal Rank Fusion + cross-encoder 重排
原生 Rust	编译后的二进制文件，无 Python/JS 运行时开销，查询延迟 p95 低于 8 ms

Agent 不只是搜索代码。它还记得代码。

---

Memtrace 与通用记忆系统（Mem0、Graphiti）的比较

Mem0 和 Graphiti 是强大的对话记忆引擎，旨在跟踪实体知识（例如 User -> Likes -> Apples）。它们在这方面表现出色。对于代码智能而言，取舍在于它们依赖 LLM 推理来构建图谱 — 处理数千个源文件时，这会增加成本和耗时。

Graphiti 通过 add_episode() 处理数据，每个 episode 都会触发多次 LLM 调用 — 实体提取、关系解析、去重。按每分钟约 50 个 episode 的速度（来源），摄取 1,500 个代码文件需要 1–2 小时。

Mem0 通过 client.add() 处理数据，会为每个记忆条目排队执行异步 LLM 提取和冲突解决（来源）。使用 infer=True（默认值）进行批量摄取，意味着每个文件都要经过 LLM 流程。吞吐量受 LLM 提供商的速率限制约束。

对于大型代码库，两者都会累积 $10–50+ 的 API 费用，因为每种关系都是通过推理得出，而非解析得到。

**Memtrace 采用了不同的方法：**它只需 1.2–1.8 秒即可为 1,500 个文件建立索引，费用为 $0.00 — 无 LLM 调用、无 API 费用、无速率限制。原生 Tree-sitter AST 解析器会在本地确定性地解析符号引用（CALLS、IMPLEMENTS、IMPORTS）。代价是 Memtrace 专为代码打造 — 它无法像 Mem0 和 Graphiti 那样处理对话中的实体记忆。

---

25+ 个 MCP 工具

Memtrace 通过 Model Context Protocol 提供完整的结构分析工具集。

搜索与发现 find_code — BM25 + 语义搜索 + RRF 混合检索 find_symbol — 精确 / 模糊匹配，使用 Levenshtein 算法 关系 analyze_relationships — 调用方、被调用方、层级、导入关系 get_symbol_context — 一次调用即可查看 360° 全貌 影响分析 get_impact — 影响范围及风险评级 detect_changes — 将差异映射到符号影响范围 代码质量 find_dead_code — 检测零调用代码 find_most_complex_functions — 复杂度热点 calculate_cyclomatic_complexity get_repository_stats

时间分析 get_evolution — 6 种评分模式 get_timeline — 完整版本历史 detect_changes — 基于差异的影响范围 图算法 find_bridge_symbols — 中介中心性 find_central_symbols — PageRank / 度数 list_communities — Louvain 模块 list_processes / get_process_flow API 拓扑 get_api_topology — 跨代码库 HTTP 图 find_api_endpoints find_api_calls 索引与监视 index_directory — 解析、解析关系、生成嵌入 watch_directory — 实时增量更新 execute_cypher — 直接查询图

---

17 个 Agent 技能

Memtrace 附带技能 / 指引，教 Agent 如何使用图谱。系统会根据你的提问自动触发，无需编写提示词。

技能	你可以说……
memtrace-search	“查找这个函数”、“X 定义在哪里”
memtrace-relationships	“谁调用了这个函数”、“显示类层级结构”
memtrace-evolution	“本周改了什么”、“它是如何演变的”
memtrace-impact	“如果我修改这个会有什么问题”、“影响范围”
memtrace-quality	“查找死代码”、“复杂度热点”
memtrace-graph	“展示架构”、“查找瓶颈”
memtrace-api-topology	“列出 API 端点”、“服务依赖关系”
memtrace-index	“为这个项目建立索引”、“解析这个代码库”
memtrace-cochange	“还有什么会跟着一起改”、“隐藏的耦合”

此外还有 8 个工作流技能，可根据决策逻辑串联多个工具：memtrace-first、codebase-exploration、change-impact-analysis、incident-investigation、refactoring-guide、continuous-memory、episode-replay 和 session-continuity。

---

时间引擎

针对不同时间问题的 6 种评分算法：

模式	适用场景
compound	通用的“发生了什么变化？”——对影响、新颖性和近期性进行加权融合
impact	“什么出问题了？”——按影响范围排序（in_degree^0.7 × (1 + out_degree)^0.3）
novel	“有什么出乎意料？”——通过惊异度评分检测异常
recent	“事件发生前后有哪些变化？”——指数时间衰减
directional	“新增了什么，移除了什么？”——非对称评分
overview	快速的模块级摘要

使用 结构重要性预算，呈现覆盖总重要性 ≥80% 的最小变更集合。

---

兼容性

编辑器 / Agent	MCP 工具（25+）	技能 / 指南	安装
Claude Code	✅	✅	npm install -g memtrace — 全自动
Claude Desktop	✅	✅	自动 — 与 Claude Code 共享
DeepSeek Harness	✅	✅	npx -y @deepseek-ai/dsh plugin --profile web add github:syncable-dev/dsh-plugin-memtrace
Cursor (v2.4+)	✅	✅	npm install -g memtrace — 全自动
Codex CLI	✅	✅	npm install -g memtrace — 全自动
Windsurf	✅	✅	npm install -g memtrace — 全自动
VS Code (Copilot)	✅	✅	npm install -g memtrace — 全自动
Hermes	✅	✅	npm install -g memtrace — 全自动
OpenCode	✅	✅	npm install -g memtrace — 全自动
Kiro	✅	Steering	npm install -g memtrace — 全自动
Cline / Roo Code	✅	—	手动添加 MCP 服务
任意 MCP 客户端	✅	—	手动添加 MCP 服务

技能是工作流提示词，用于指导 Agent 如何串联工具。Kiro 不使用 SKILL.md，因此 Memtrace 会改为写入等效的自动 steering 文件。

---

设置

DeepSeek Harness

dsh 来自 @deepseek-ai/dsh，而非 Memtrace。

npm install -g @deepseek-ai/dsh
dsh plugin --profile web add github:syncable-dev/dsh-plugin-memtrace

也可以不使用全局 CLI：

npx -y @deepseek-ai/dsh plugin --profile web add github:syncable-dev/dsh-plugin-memtrace

该软件包会在 Harness 配置中注册 Memtrace 的技能，并启动 memtrace mcp。首次启动时可能会通过 npx 获取 Memtrace 二进制文件；可通过 npm install -g memtrace 和 MEMTRACE_BIN=memtrace 指定本地安装。

Claude Code + Claude Desktop

npm install -g memtrace

自动处理所有事项：二进制文件、17 项技能、MCP 服务、插件和市场。一条命令即可适配两个编辑器。

手动设置：

claude plugin marketplace add https://github.com/syncable-dev/memtrace-public.git
claude plugin install memtrace-skills@memtrace --scope user
claude mcp add memtrace -- memtrace mcp

Cursor

npm install -g memtrace 会自动处理所有事项。Cursor v2.4+ 读取与 Claude 相同的 SKILL.md 格式。

安装到项目本地（技能会随仓库一同迁移）：

npx memtrace-skills install --only cursor --local

Codex、Windsurf、VS Code、Hermes、OpenCode 和 Kiro

安装程序还会为较新的 Agent 平台写入技能 / 指南和 MCP 配置：

Agent	全局技能 / 指南	全局 MCP 配置	项目本地支持
Codex	~/.agents/skills/	~/.codex/config.toml	.agents/skills/、.codex/config.toml
Windsurf	~/.codeium/windsurf/skills/	~/.codeium/windsurf/mcp_config.json	.windsurf/skills/；MCP 仍为用户级配置
VS Code / Copilot	~/.copilot/skills/	VS Code 用户级 mcp.json	.github/skills/、.vscode/mcp.json
Hermes	~/.hermes/skills/	~/.hermes/config.yaml	仅支持用户级
OpenCode	~/.config/opencode/skills/	~/.config/opencode/opencode.json	.opencode/skills/、opencode.json
Kiro	~/.kiro/steering/	~/.kiro/settings/mcp.json	.kiro/steering/、.kiro/settings/mcp.json

仅安装所选集成：

npx memtrace-skills install --only codex,windsurf,vscode,hermes,opencode,kiro

在支持的情况下安装项目本地配置：

npx memtrace-skills install --only codex,vscode,opencode,kiro --local

其他 MCP 客户端

对于 Cline、Roo Code，或任何只需要 MCP 工具的客户端，请手动添加此服务：

{
  "mcpServers": {
    "memtrace": {
      "command": "memtrace",
      "args": ["mcp"],
      "env": {}
    }
  }
}

编辑器	配置文件
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code (Copilot)	项目根目录下的 .vscode/mcp.json
Codex	~/.codex/config.toml 或 .codex/config.toml
Hermes	~/.hermes/config.yaml
OpenCode	~/.config/opencode/opencode.json 或项目中的 opencode.json
Kiro	~/.kiro/settings/mcp.json 或 .kiro/settings/mcp.json
Cline	扩展面板中的 Cline MCP 设置

卸载

memtrace uninstall      # removes skills, MCP server, plugin, settings
npm uninstall -g memtrace

已经先运行了 npm uninstall？清理脚本位于 ~/.memtrace/uninstall.js：

node ~/.memtrace/uninstall.js

安装故障排除

npm install -g memtrace 会安装一个精简的主软件包和一个平台专用二进制文件（@memtrace/darwin-arm64、@memtrace/linux-x64、@memtrace/win32-x64 之一）。如果 memtrace start 报错 "Could not find binary for your platform"：

# Re-run install, asking npm to keep optional deps
npm install -g memtrace --include=optional

# Or refresh from latest
memtrace install         # built-in self-update
npm install -g memtrace@latest --force

# Or install the platform binary directly (Apple Silicon shown — swap for your platform)
npm install -g @memtrace/darwin-arm64

这通常只会发生在 npm 配置为跳过可选依赖的机器上（企业级 npmrc、某些 CI 缓存）。

---

语言

编程语言： Rust · Go · TypeScript · JavaScript · Python · Java · C · C++ · C# · Swift · Kotlin · Ruby · PHP · Dart · Scala · Perl · Lua — 完整 AST：函数、类、类型、调用、复杂度。

基础设施与配置： YAML · HCL / Terraform · JSON · TOML · SQL（包括用于 RLS 的 PostgreSQL CREATE POLICY，并支持从策略到 Drizzle / Prisma / TS 架构符号的跨语言关联）。

基于 AST 层的框架感知型扫描器：

• 后端 HTTP： Express · NestJS · Encore · Fastify · Vapor · Hummingbird · FastAPI · Flask · Django · Gin · Chi · Echo · Actix · Lapis · Kong · OpenResty · Rails 路由
• 前端 / 客户端： RTK Query · TanStack Query · SWR · URLSession · AsyncHTTPClient · axios · fetch · SwiftUI 视图
• CI / 基础设施： GitHub Actions 工作流（作业、步骤、needs: 关联）· Terraform 变量 / 模块 / 数据源 · Helm 图表 · K8s 清单
• 包与依赖关系图： package.json 脚本 + 依赖 · Cargo.toml 依赖 · pyproject.toml（尽力而为）
• 数据库： PostgreSQL RLS 策略 + 触发器 + 函数，并通过启发式关联连接到 ORM 架构

---

要求

Memtrace 在本地运行——首次索引会大量占用 CPU / RAM，后续查询和增量索引则轻量得多。

	最低要求	推荐配置
CPU	4 核	大型单体仓库建议 8 核以上
内存	8 GB RAM	16–32 GB RAM
磁盘	5 GB 可用空间	10–20 GB 可用空间
GPU	不需要	不需要
Node.js	≥ 18	当前 LTS 版本
Git	时间分析所必需	完整仓库历史可获得最佳效果

---

遥测

自 v0.3.17 起，Memtrace 默认启用可选择退出的遥测功能，帮助我们在有人提交问题报告之前发现崩溃、回归和性能问题。

• 收集内容： 应用启动事件、索引 / 嵌入耗时、panic 报告、Memtrace 自有 crate 的 WARN / ERROR 日志行。
• 不收集： 源代码、文件内容、符号名称、嵌入、仓库名称或路径、分支名称、提交数据。
• 清理： 每个负载在写入磁盘前都会经过清理程序，移除主目录路径、类似令牌的字符串和电子邮件地址。

通过一个环境变量禁用：

MEMTRACE_TELEMETRY=off memtrace start                    # per-run
export MEMTRACE_TELEMETRY=off                             # permanent (~/.zshrc, ~/.bashrc)

也可以在编辑器的 MCP 配置中设置："env": { "MEMTRACE_TELEMETRY": "off" }。

完整说明——包括磁盘队列布局、数据在接收端的存储位置，以及如何检查即将发送的内容——请参阅 TELEMETRY.md。

---

许可证与所有权

专有 EULA。 私有 Beta 期间及正式发布后，个人开发者均可免费使用。索引器 + 数据库（MemDB）为闭源。

基准测试套件采用 MIT 许可证，位于 benchmarks/ — 完全可复现，运行时无需专有代码。

---

memtrace.io  ·  Discord  ·  npm  ·  问题反馈

由 Syncable 打造 · 哥本哈根 🇩🇰