Obelisk 记忆层详解:如何让你的编码Agent永久"记住"设计决策与项目约定

原创2026-11-01 10:33:141,364 阅读

Obelisk 记忆层详解:如何让你的编码Agent永久"记住"设计决策与项目约定

还在为编码 Agent"失忆"烦恼?Obelisk 记忆层把 Claude Code、Codex 等工具的历史会话索引进本地 SQLite 数据库,让你和设计决策、项目约定相关的结论沉淀为可检索的记忆——Agent 永久"记住",你随时审计、归档。

先说痛点:为什么编码 Agent 总是"失忆"

用过 Claude Code、Codex 这类编码 Agent 的开发者都熟悉这种场景:

  • 上个月敲定的"为什么选 SQLite 而不是 Postgres",这次对话里 Agent 忘得一干二净;
  • 团队约定"禁止引入新依赖",Agent 却毫无印象;
  • 同一个 bug 反复修,因为 Agent 根本不记得上次是怎么修的。

Agent 每次会话结束,上下文就归零。历史散落在各家工具的 JSONL 日志里,2 万行碎片,没人能查。

Obelisk 解决的就是这件事:它把你本地的 agent 历史统一索引进一个 SQLite 数据库(~/.obelisk/obelisk.sqlite),并提供两层记忆——原始证据层 + 结论记忆层。前者让 Agent 毫秒级查询任何历史细节,后者让"值得记住的结论"跨会话存活。

Obelisk 桌面应用 Memory 面板,展示本地编码 Agent 会话记忆与项目列表

Obelisk 记忆层的两层架构

Obelisk 明确区分"证据"和"结论",这也是它和"向量记忆 / 隐式记忆"方案最大的不同:

层 内容 查询方式 定位
证据层 真实会话、消息、工具调用、subagent search() / messages() / sql() 可审计的原始记录
结论层(Memory) 经你批准的 markdown 记忆文件 memories() 结论缓存,不替代证据

设计哲学写在 CONTEXT.md 里:证据优先于断言(Evidence before assertion)——记忆只是"合成缓存",每个结论都能沿着源会话 ID 和消息区间回溯到原始记录。

markdown 文件 + SQLite 注册表 + FTS 全文检索

一条 Obelisk 记忆由三部分组成:

  1. markdown 文件:记忆正文,通常放在项目里的 .obelisk/memories/ 目录,写明决策、理由、备选方案与约束;
  2. memories 表:注册表记录,定义在 packages/core/src/schema.sql:
CREATE TABLE IF NOT EXISTS memories (
  id TEXT PRIMARY KEY, session_id TEXT, project TEXT,
  message_start TEXT, message_end TEXT,
  path TEXT, anchors TEXT, summary TEXT, created_at TEXT,
  deleted_at TEXT, deleted_reason TEXT);

关键字段一眼看懂:path 指向 markdown 文件,session_id + message_start/message_end 标出证据来源的会话和消息区间,summary 是英文检索摘要,anchors 是召回锚点(比如关联文件),deleted_at 用于软删除;

  1. memories_fts 全文索引:对 path 和 summary 建 FTS5 索引,memories() 的 query 参数就是基于它做排序召回的,实现见 packages/core/src/query.ts。

这样做的好处:召回时 Agent 只读摘要就能判断相关性,命中后再读 markdown 全文,成本极低。

保存记忆:Agent 提议,你批准

写入记忆的完整流程由 skill-doc/references/memory-workflow.md 规定,核心规则只有一条:持久化写入必须经你批准。

什么值得存? 设计决策、项目约定、被放弃的备选方案、反复出现的失败原因、多个证据点支撑的结论。一次性查找和不确定结论不存。

四步流程:

  1. Agent 通过普通 --query 脚本拿到源会话/消息 ID,并检查现有记忆避免重复;
  2. 向你提议并等待批准——这是硬性要求,Agent 不能静默写记忆;
  3. 批准后,把结论写成 markdown 文件(如 .obelisk/memories/design-decision.md);
  4. 用 obelisk --attune <script> 注册,脚本里调用 remember()。

--attune 是一个独立的变更入口:它只暴露 remember() 和 forget() 两个函数,没有任何检索能力,和只读的 --query 严格分离。remember() 会校验文件存在、summary 必须是英文,注册记录里还带上了来源消息区间,方便日后回溯。可复制的注册脚本范例见 skill-doc/references/query-patterns.md,实现源码在 packages/core/src/query.ts。

召回记忆:先问记忆,再验证据

下一次会话开始时,Agent 的检索顺序是:

  1. 调 memories({ query: '...' }) 召回相关结论(查询词用英文,按 FTS 相关度排序);
  2. 用 search() 回到会话证据核验——记忆只是"先验笔记",不是最终权威;
  3. 回答时自然标注哪些结论来自既有记忆;
  4. 如果发现新结论值得沉淀,再次走"提议 → 批准 → 写入"流程。

is_invoking: true 的会话是当前会话本身,Agent 不会把"正在进行的对话"误当成历史证据——这套检索语义细节都写在 skill-doc/references/retrieval-semantics.md。

遗忘与更新:归档而非删除

记忆会过时,Obelisk 的解法是软删除:

  • forget({ id, reason }):归档一条记忆。记录标记 deleted_at 和归档原因,活跃召回自动跳过它,但 markdown 文件和审计信息都原样保留,实现见 packages/core/src/query.ts;
  • 更新 = 归档 + 替换:不是原地改写,而是先 forget() 旧记录,再 remember() 新文件,两步在同一个 --attune 脚本里完成。

也就是说,任何一条"被推翻的设计决策"都能追溯:当初为什么这么定、什么时候被谁以什么理由归档的。

在桌面应用里管理你的记忆

Agent 侧的记忆操作,你都能在 Obelisk 桌面应用里看到并接手:

  • 列表 + 详情:搜索、按项目筛选、按时间排序,点开直接读 markdown 原文;
  • 一键归档/恢复:归档操作带撤销倒计时;
  • 健康状态:broken、partial 等状态一目了然;
  • 应用源码入口在 app/src/renderer/src/views/MemoryList.vue,界面交互逻辑(筛选、排序、详情展开)就写在这里。

CLI 和桌面应用读写同一个 ~/.obelisk/obelisk.sqlite:应用运行时独占索引写锁,CLI 查询自动降级为只读,互不干扰。

Obelisk 记忆层演示:编码 Agent 通过 obelisk 命令查询本地历史会话并总结结论

安装与配置:三步让 Agent 拥有记忆

Obelisk 需要 Node.js 22.13+,CLI 零运行时 npm 依赖(用 Node 内置 SQLite):

npm install --global @obelisk-apps/cli
obelisk install        # 安装 /obelisk agent skill

也可以把 SKILL.md 里的引导语直接发给你的编码 Agent,让它替你完成安装。

装好后,在任意 Agent 会话里:

/obelisk 上次 auth bug 最后到底改了哪些文件,为什么这么改
/obelisk 这个文件最近在哪些 sessions 里被反复修改
/obelisk recap this week

首次运行约 5 秒建索引(100 个会话的量级),之后全增量。默认查询接口有 overview()、sessions()、search()、messages()、memories()、summaries()、sql() 七个函数,签名详见 skill-doc/references/api-reference.md。

小结:让记忆有据可查

Obelisk 记忆层的设计可以浓缩成三句话:

  • markdown 是真相,索引只是缓存:记忆正文是人人可读的 markdown,SQLite 里的注册记录只负责检索与追溯;
  • 写入必须经人批准:Agent 可以提议、归档、更新,但持久化动作永远先问你;
  • 结论永远可回溯:每条记忆都挂着源会话和消息区间,审计链完整。

设计决策会随代码演化而过时,所以 Obelisk 的记忆默认"归档而不删除"——这让"永久记住"这件事,第一次变得可审计、可撤销、可信任。

登录后查看全文
obelisk