heimdall

这是什么？适合谁？

Heimdall（ArihantDeva/heimdall）给 AI coding agent 提供跨仓库的持久记忆，回答一个问题：「我在另一个项目里已经解决过这个吗？」——用一次经过验证的搜索取代 20 分钟的 grep、find、ls 循环。

它解决的三个问题：

1. 记忆不限于一个仓库——其他记忆工具都是 per-project 的，但你的工作不是：一个项目里写好的优化函数在别处可能有用。Heimdall 把你碰过的所有东西索引进一张语义图。
2. 定位时间从几分钟降到几秒——新 Agent 会话烧几十条 bash 命令摸清地形；Heimdall 把相关的前置工作注入会话首条 prompt，并支撑一次 kb_search 调用：排序、限定范围、已验证。
3. 零 token 开销——索引是本地 daemon：文件监听 + tree-sitter AST 解析 + sqlite。索引一个文件只耗 CPU，从不调用 LLM。

核心差异化：检索结果带信任裁决（trust verdict），在查询时对照真实文件系统重新验证：

• STRONG — 路径存在、词法覆盖强、且文件实际内容回答了问题
• WEAK — 仅语义匹配，可能但未验证
• REBUILT — 文件移动了，Heimdall 找到并自动重新锚定
• STALE / REMOVED — 死路径，记录并修剪，不再参与排序

Agent 对一个死路径采取行动比没有答案更糟。排序检索可信到可以直接行动。

适合人群：有大量 side project 的独立开发者；频繁换仓库、换语言、跨月工作的工程师；被「重复造轮子」困扰的人。

使用前提：Node ≥ 22.5（journal 用内置 node:sqlite）、bash、python3；macOS 优先（launchd 管理），Linux 手动 daemon；搜索需要 Graft 后端（vendor/graft 从源码构建）。

准备工作

1. Node ≥ 22.5：npm i -g @arihantdeva/heimdall。
2. python3 + bash：tree-sitter 提取桥和脚本依赖。
3. Graft 后端（搜索和 doctor 需要）：从 vendor/graft/ 构建，二进制放 PATH。
4. 成本：MIT 开源；索引零 token 成本（tree-sitter + 本地 CPU 嵌入，bge-m3 模型）。
5. 时间预算：安装 + 接线 harness 约 5 分钟；构建 Graft 后端再加几分钟。

快速上手（3 步）

第一步：安装并接线

npm i -g @arihantdeva/heimdall
heimdall init --harness claude-code   # 或 pi | codex | cursor | windsurf | all

init 把整套 enforcement 栈接进 harness：指令文件里的记忆规则、一个 MCP 服务器（kb_search/kb_insert/kb_sync）、以及一个 guard hook——当 Agent 退回 ls/grep/find 链而不是搜记忆时发出警告。

第二步：配置后端并检查健康

cp "$(npm root -g)/@arihantdeva/heimdall/config/heimdall.yaml.example" ~/.graft/config.yaml
heimdall doctor   # 应打印 HEALTHY

第三步：第一次搜索

heimdall search "excel tracker portfolio optimization"

成功判定：输出带信任裁决的排序结果，形如 1. [STRONG] portfolio optimizer — ~/work/quant-bot/src，且路径是真实存在于磁盘上的文件。

初级用法

记录可复用工作

heimdall insert --title "portfolio optimizer" \
  --body "~/work/quant-bot/src — EV-optimizer entry point" \
  --keywords portfolio,optimize

守护 Agent 不退回 grep

guard hook 在连续 3 次 grep 风格动作仍未 kb_search 时警告；Agent 可用 kb_guard_pause 工具自我暂停 1–20 轮。

深度阶梯

节点按深度索引，默认推荐 max：

高级玩法

自愈与收敛

• heimdall daemon — 单写者：监听、reconcile、定时 audit
• heimdall reconcile --all — 深度 audit + 修复一切
• heimdall verify --deep — 只读漂移报告，exit 1 若有漂移，CI 安全
• heimdall hint PATH ... — 标记路径脏，无需锁

邮箱入索引（CPU-only，只读）

heimdall ingest-email --accounts a1,a2 --limit 50
heimdall search "subject or sender words"

邮件变成可检索知识，和代码同图。

可插拔后端

默认 Graft（零配置）；也可用 mnemosyne-oss（SQLite 后端），HEIMDALL_BACKEND=mnemosyne 一次切换或持久切换。

小技巧

1. 信任裁决胜过相似度分数：STRONG 可免确认轮直接行动，WEAK 要复核。
2. 默认 max 深度：图不仅知道文件存在，还知道函数、类和调用关系。
3. 审计做后盾：heimdall verify 对账 journal 和文件系统，--deep 重哈希抓同尺寸同 mtime 的重写。
4. 自愈优于清理：文件移动自动 REBUILT 重锚定，删除精确回收自己的节点，别手动删 journal 数据。
5. 守护规则防偷懒：guard 警告 3 次 grep 后，让 Agent 学会先问记忆再摸盘。

常见踩坑

踩坑 1：装了但搜不到（graft 没建）

• 现象：heimdall search 报错或空结果。
• 原因：ranked search 需要 Graft 后端，init 只完成 harness 接线。
• 解决：按 Quickstart 构建 graft、放 PATH、heimdall doctor 确认 HEALTHY。

踩坑 2：L3 静默降级到 L1

• 现象：以为索引到函数级，实际只有文件级。
• 原因：L2/L3 需要 tree-sitter，机器上没有时降级到 L1 而非失败。
• 解决：heimdall depth src/server.ts 看 requested vs effective depth；装 tree-sitter 后 audit 自动重索引。

踩坑 3：把 journal 当可删文件

• 现象：rm ~/.heimdall/ 后记忆全丢。
• 原因：journal.db 是权威索引，不是 build artifact。
• 解决：数据在 ~/.heimdall/ 和 ~/.graft/，永远别盲目 rm/mv。

踩坑 4：期望即时一致

• 现象：刚改文件立刻搜，图还是旧的。
• 原因：Heimdall 的诚实保证是有界陈旧收敛，不是瞬时正确。
• 解决：等一次 reconcile pass，或 heimdall hint PATH 手动标记脏加速。

踩坑 5：数据泄露担忧

• 现象：担心源码被发到云端。
• 原因：误解索引机制。
• 解决：索引是 tree-sitter + 本地 CPU 嵌入（bge-m3），搜索跑本地 daemon，代码从不出盘。

常见问题 FAQ

Q1: 我的代码会离开我的机器吗？

A: 不会。索引是 tree-sitter 解析 + 本地 CPU 嵌入；搜索跑在本地 daemon；没有任何数据上报。对比 mem0/Zep/Letta 默认把内容发给提取 LLM，Heimdall 是零泄露架构。

Q2: 需要 GPU 吗？

A: 不需要。嵌入模型 bge-m3 跑在 Apple Silicon / 任意现代 CPU 上。可选 GPU 能提速到 3.4 倍。

Q3: 和 grep 有什么不同？

A: grep 找你已经知道存在的字符串；Heimdall 回答「我是否解决过类似问题」，跨所有碰过的项目、排序并对照磁盘真实状态验证。

Q4: 文件移动或删除怎么办？

A: reconciler 在下一轮 pass 发现。移动的文件自动重新锚定（REBUILT 裁决）；删除精确回收自己的节点；死路径不再参与排序。

Q5: 生产就绪吗？

A: v0.2.0，作者机器上跑着约 12800 个活动节点，166 测试套件守护并发不变式。LongMemEval 基准 harness 在 bench/ 中（进行中）。定位偏独立开发者工作流。

进阶学习建议

掌握基础后，建议深入：

1. 跨仓库知识复利：刻意在每次解决完一个可复用问题后 heimdall insert 一条记录，让「知识跟着你跨仓库、跨语言、跨月份」。
2. 守护规则调优：把 guard 的 grep 阈值和 kb_guard_pause 暂停轮数调到适合你的工作节奏，减少误报又不放过偷懒。
3. 邮箱入图：用 ingest-email 把邮件卡片并进语义图，让「某封邮件里的方案」和「某段代码」能在同一次搜索里互相命中。

参考链接

• 官方仓库
• npm: @arihantdeva/heimdall
• Graft 后端

最后更新：2026-08-27 · 作者：MagicNetWorld · 基于公开资料整理，关键数据经 GitHub API 独立实测核验，AI 辅助生成