Obelisk 记忆层详解:如何让你的编码Agent永久"记住"设计决策与项目约定
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 记忆层的两层架构
Obelisk 明确区分"证据"和"结论",这也是它和"向量记忆 / 隐式记忆"方案最大的不同:
| 层 | 内容 | 查询方式 | 定位 |
|---|---|---|---|
| 证据层 | 真实会话、消息、工具调用、subagent | search() / messages() / sql() |
可审计的原始记录 |
| 结论层(Memory) | 经你批准的 markdown 记忆文件 | memories() |
结论缓存,不替代证据 |
设计哲学写在 CONTEXT.md 里:证据优先于断言(Evidence before assertion)——记忆只是"合成缓存",每个结论都能沿着源会话 ID 和消息区间回溯到原始记录。
markdown 文件 + SQLite 注册表 + FTS 全文检索
一条 Obelisk 记忆由三部分组成:
- markdown 文件:记忆正文,通常放在项目里的
.obelisk/memories/目录,写明决策、理由、备选方案与约束; 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 用于软删除;
memories_fts全文索引:对path和summary建 FTS5 索引,memories()的query参数就是基于它做排序召回的,实现见 packages/core/src/query.ts。
这样做的好处:召回时 Agent 只读摘要就能判断相关性,命中后再读 markdown 全文,成本极低。
保存记忆:Agent 提议,你批准
写入记忆的完整流程由 skill-doc/references/memory-workflow.md 规定,核心规则只有一条:持久化写入必须经你批准。
什么值得存? 设计决策、项目约定、被放弃的备选方案、反复出现的失败原因、多个证据点支撑的结论。一次性查找和不确定结论不存。
四步流程:
- Agent 通过普通
--query脚本拿到源会话/消息 ID,并检查现有记忆避免重复; - 向你提议并等待批准——这是硬性要求,Agent 不能静默写记忆;
- 批准后,把结论写成 markdown 文件(如
.obelisk/memories/design-decision.md); - 用
obelisk --attune <script>注册,脚本里调用remember()。
--attune 是一个独立的变更入口:它只暴露 remember() 和 forget() 两个函数,没有任何检索能力,和只读的 --query 严格分离。remember() 会校验文件存在、summary 必须是英文,注册记录里还带上了来源消息区间,方便日后回溯。可复制的注册脚本范例见 skill-doc/references/query-patterns.md,实现源码在 packages/core/src/query.ts。
召回记忆:先问记忆,再验证据
下一次会话开始时,Agent 的检索顺序是:
- 调
memories({ query: '...' })召回相关结论(查询词用英文,按 FTS 相关度排序); - 用
search()回到会话证据核验——记忆只是"先验笔记",不是最终权威; - 回答时自然标注哪些结论来自既有记忆;
- 如果发现新结论值得沉淀,再次走"提议 → 批准 → 写入"流程。
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 查询自动降级为只读,互不干扰。
安装与配置:三步让 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 的记忆默认"归档而不删除"——这让"永久记住"这件事,第一次变得可审计、可撤销、可信任。

