代码图谱记忆 syncable-dev/memtrace-public

你的智能体值得拥有结构化记忆。

Syncable 出品的官方 Memtrace。 从 memtrace.io/docs 开始。官方包是 npm 上的 memtrace，公开仓库是 syncable-dev/memtrace-public。其他同名项目与此无关。把 memtrace --version 的输出和 Stable 与 Nightly 发布记录对照一下。

需要安装支持，就到官方公开仓库提 issue，写清你的操作系统、Memtrace 版本和完整报错。分享日志前先删掉凭据和私有源码。Syncable 团队维护这个包及其支持渠道。

📖 文档 · ⭐ 给我们点星 · memtrace.io ·
npm ·
Discord

Memtrace 把你的代码库变成一张实时知识图谱，AI 编程智能体能在毫秒内查询它 —— 每个函数、每个类、每条调用边、每个版本，跨所有会话，不用重读文件，也不会弄坏它们看不见的东西。

90 秒内让你的智能体集群共享结构化记忆。

结构化 · 零 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

然后让智能体为工作区建索引，拉取影响范围、演进历史或架构简报。详情见：syncable-dev/dsh-plugin-memtrace。

它能做什么

每个版本，三件事。

🧭 让一群编码智能体在同一个仓库上干活，还不会陷入合并地狱。 每个智能体读同一份调用图，看到同样的影响范围，继承同样的时间历史。不会撞车，不会用到过期上下文。

🔁 重放任何重构，全程掌握因果。 智能体清楚知道谁依赖谁，也知道什么时候变了什么。再也不会出现「我重构了一个函数，14 个测试挂了，却没人发现」。

⚡ 50k 文件的仓库，90 秒内建好索引。 Rust + Tree-sitter，API 成本 $0，支持 20+ 种语言，外加能识别框架的扫描器（Vapor、Lapis、Kong、GitHub Actions、Terraform、RLS policies……），完全本地运行。你的代码永远不离开你的机器。

🆕 LeanCTX 原生 —— 压缩读取、智能目录树、价值账本。 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, lat） | 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 目前处于内测阶段。我们分批放量，好让反馈闭环更紧——每一批用户都会进入一个 Discord 频道，真实的 bug 报告一周内就能拿到修复。

→ 在 memtrace.io 加入等待列表。

已经有权限了？npm install -g memtrace，90 秒后就能开始建索引。完整安装步骤见下文。

🔒 隐私。 Memtrace 完全跑在你自己的机器上，源码不会离开本机。唯一的网络流量是许可证校验、节点/边的聚合计数，以及可关闭的崩溃遥测——不含源码、不含文件路径、不含符号名。完整说明：PRIVACY.md、TELEMETRY.md。用 MEMTRACE_TELEMETRY=off 关闭遥测。

为什么会有 Memtrace

好用的代码智能工具已经不少了。GitNexus 和 CodeGrapherContext 构建基于 AST 的图，能回答「我的仓库里现在有什么」。

Memtrace 是一个双时间维度的情节式结构化知识图谱。 它建立在同样的 AST 基础之上，又加了两个维度：

- 时间记忆——每个符号都带着完整的版本历史。六种评分算法（impact、novelty、recency、directional、compound、overview）让智能体可以问不同的时间问题：「改了什么？」、「哪里出乎意料？」、「什么会崩？」。
- 跨服务 API 拓扑——Memtrace 会画出仓库之间的 HTTP 调用图，识别出你的架构里哪些服务调用了哪些端点。

除此之外，结构层本身也很全面：

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

智能体不只是搜索你的代码。它会记住代码。

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

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

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

Mem0 通过 client.add() 处理数据，每个记忆条目都会排队等待异步 LLM 抽取和冲突解决（来源）。用 infer=True（默认值）批量摄取，意味着每个文件都要走一遍 LLM 流水线。吞吐量受限于你的 LLM 服务商的速率限制。

两者处理大型代码库都会累积 $10–50+ 的 API 成本，因为每条关系都是推理出来的，而不是解析出来的。

Memtrace 走的是另一条路： 它索引 1,500 个文件只需 1.2–1.8 秒，花费 $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 — diff 到符号的范围映射

代码质量
- find_dead_code — 零调用者检测
- find_most_complex_functions — 复杂度热点
- calculate_cyclomatic_complexity
- get_repository_stats

时序分析
- get_evolution — 6 种评分模式
- get_timeline — 完整版本历史
- detect_changes — 基于 diff 的范围

图算法
- 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 个智能体技能

Memtrace 附带技能/指导，教智能体如何使用图谱。它们会根据你的提问自动触发——无需提示词工程。

| 技能 | 你说…… |
| memtrace-search | "find this function", "where is X defined" |
| 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。

时间引擎

六种评分算法，应对不同的时间维度问题：

| 模式 | 最适合 |
| compound | 通用型「改了什么？」——按影响、新颖度、时间近度加权混合 |
| impact | 「什么崩了？」——按爆炸半径排序（in_degree^0.7 × (1 + out_degree)^0.3） |
| novel | 「什么出乎意料？」——用意外度评分做异常检测 |
| recent | 「事故附近改了什么？」——指数时间衰减 |
| directional | 「新增了什么、删掉了什么？」——非对称评分 |
| overview | 模块级快速摘要 |

使用 Structural Significance Budgeting，挑出最小的一组变更，覆盖总显著度的 ≥80%。

兼容性

| 编辑器 / 智能体 | 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 服务器 |

技能就是工作流提示词，教智能体怎么把工具串起来用。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

不想全局装命令行也行：

npx -y @deepseek-ai/dsh plugin --profile web add github:syncable-dev/dsh-plugin-memtrace
这个 bundle 会注册 Memtrace 的技能，并在 Harness 配置档里启动 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+ 读取的 SKILL.md 格式与 Claude 相同。

项目本地安装（技能随仓库一起走）：

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

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

安装器也会为较新的智能体界面写入技能/指引和 MCP 配置：

| 智能体 | 全局技能 / 指引 | 全局 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"：

重新安装，让 npm 保留可选依赖
npm install -g memtrace --include=optional

或者从最新版刷新 memtrace install # 内置自更新
npm install -g memtrace@latest --force

或者直接安装平台二进制文件（这里以 Apple Silicon 为例——换成你的平台）
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（包括 PostgreSQL 用于 RLS 的 CREATE POLICY，并带有从策略指向 Drizzle / Prisma / TS schema 符号的跨语言边）。

框架感知扫描器，构建在 AST 层之上：

- 后端 HTTP： Express · NestJS · Encore · Fastify · Vapor · Hummingbird · FastAPI · Flask · Django · Gin · Chi · Echo · Actix · Lapis · Kong · OpenResty · Rails routes
- 前端 / 客户端： RTK Query · TanStack Query · SWR · URLSession · AsyncHTTPClient · axios · fetch · SwiftUI views
- CI / 基础设施： GitHub Actions 工作流（job、step、needs: 边）· Terraform 变量 / 模块 / 数据源 · Helm chart · K8s manifest
- 包与依赖图： package.json 的 script + 依赖 · Cargo.toml 依赖 · pyproject.toml（尽力而为）
- 数据库： PostgreSQL RLS 策略 + 触发器 + 函数，并带有指向 ORM schema 的启发式边

环境要求

Memtrace 在本地运行 —— 首次索引很吃 CPU / 内存，之后的查询和增量索引要轻得多。

| | 最低 | 推荐 |
| CPU | 4 核 | 大型 monorepo 建议 8 核以上 |
| 内存 | 8 GB RAM | 16–32 GB RAM |
| 磁盘 | 5 GB 可用 | 10–20 GB 可用 |
| GPU | 不需要 | 不需要 |
| Node.js | ≥ 18 | 当前 LTS |
| Git | 时序分析需要 | 完整仓库历史效果最佳 |

遥测

从 v0.3.17 起，Memtrace 自带可关闭的遥测，帮我们在有人提 issue 之前就抓到崩溃、回归和性能问题。

- 收集： 应用启动事件、索引 / 嵌入耗时、panic 报告、Memtrace 自身 crate 产生的 WARN/ERROR 日志行。
- 不收集： 源代码、文件内容、符号名、嵌入向量、仓库名或路径、分支名、提交数据。
- 脱敏： 每个载荷在落盘之前都会过一遍脱敏器，剔除家目录路径、token 形态的字符串和邮箱地址。

用一个环境变量就能关掉：

MEMTRACE_TELEMETRY=off memtrace start # 单次运行
export MEMTRACE_TELEMETRY=off # 永久生效（~/.zshrc、~/.bashrc）

或者在编辑器的 MCP 配置里加："env": { "MEMTRACE_TELEMETRY": "off" }。

完整说明见 TELEMETRY.md，包括磁盘上的队列结构、接收端的数据存放位置，以及怎么查看本来会发送哪些数据。

许可与归属

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

基准测试套件以 MIT 协议放在 benchmarks/ 下——完全可复现，运行它们不需要任何专有代码。

memtrace.io · Discord ·
npm ·
Issues

Built by Syncable · Copenhagen 🇩🇰

MseeP.ai Security Assessment Badge