Codex-Vault

给任何 LLM agent 加上持久记忆。 你的笔记，你的 git，你的数据。

问题

LLM agent 每次对话都从零开始。上次做的决策忘了，讨论过的方案忘了，知识永远无法积累。

方案

一个结构化的知识库 + 3 个 hook，让 agent 拥有跨 session 的记忆。支持 Claude Code 和 Codex CLI。纯 markdown + git，没有外部依赖。

核心用法

6 个动作，覆盖日常全部场景：

| 动作 | 怎么做 | 什么时候用 | |------|--------|-----------| | 设目标 | 编辑 brain/North Star.md | 首次使用，或方向调整时 | | 随手记 | /dump 内容 | 做了决策、有了想法、完成了什么 — 随时 dump | | 查记忆 | /recall 关键词 | 忘了之前的决策、想找历史笔记 | | 吃内容 | /ingest URL或文件 | 看到好文章、拿到新资料，结构化存入 | | 收尾 | /wrap-up | session 结束前，检查质量、更新索引 | | 体检 | /lint | vault 健康审计 — 断链、孤儿、过期、标签漂移等 13 项检查 |

Codex CLI 用 $dump、$recall、$ingest、$wrap-up、$lint。

提示词模板

直接复制使用，替换 <> 里的内容：

/dump — 随手记

/dump 我们决定用 <方案A> 而不是 <方案B>，因为 <原因>
/dump <项目名> 完成了，关键成果：<成果描述>
/dump 今天发现一个规律：<规律描述>
/dump 记住：<任何你想让 agent 下次记得的事>

/recall — 查记忆

/recall <关键词>
/recall 我们之前怎么决定的 <某件事>
/recall <项目名> 的进展

/ingest — 吃内容

/ingest <URL>
/ingest sources/<文件名>.md

/wrap-up — 收尾

/wrap-up

不需要参数，agent 自动扫描本次 session 的变更。

/lint — 体检

/lint

不需要参数，自动执行 13 项 vault 健康检查。

日常最高频的就是 /dump。其他按需使用。

30 秒上手

# 在你的项目目录下：
npx @suwujs/codex-vault init
claude                                  # 或: codex

填好 .vault/brain/North Star.md，开始对话。

集成模式（在其他项目中运行 init 时的默认行为）会创建 .vault/ — 一个隐藏目录，自动加入 .gitignore，每个开发者各自拥有本地 vault，不会产生合并冲突。独立模式（在 codex-vault 仓库内）仍然使用 vault/。

git clone https://github.com/sukbearai/codex-vault.git /tmp/codex-vault
bash /tmp/codex-vault/plugin/install.sh

独立模式：在 codex-vault 仓库内运行 install.sh，以 vault/（而非 .vault/）为工作目录。

工作原理

你说话
  ↓
classify hook（分类：决策？进展？想法？）
  ↓
Agent 写笔记（按 instructions.md 规范）
  ↓
validate hook（检查：frontmatter？wikilinks？正确目录？）
  ↓
git commit（持久化）
  ↓
下次 session → session-start hook 注入上下文

Hook 驱动整个循环：

| Hook | 触发时机 | 做什么 | Claude Code | Codex CLI | |------|---------|--------|-------------|-----------| | session-start | Agent 启动 | 注入 North Star 目标、近期 git 变更、活跃项目、vault 文件清单 | SessionStart | SessionStart | | classify-message | 每条消息 | 检测决策、成果、项目更新 — 提示 agent 该归档到哪里 | UserPromptSubmit | UserPromptSubmit | | validate-write | 写 .md 后 / 执行 Bash 后 | 检查 frontmatter 和 wikilinks（Claude）；检测命令失败（Codex） | PostToolUse (Write|Edit) | PostToolUse (Bash) |

支持的 Agent

| Agent | Hooks | Skills | 状态 | |-------|-------|--------|------| | Claude Code | .claude/settings.json 3 hooks | /dump /recall /ingest /wrap-up /lint | 完整支持 | | Codex CLI | .codex/hooks.json 3 hooks | $dump $recall $ingest $wrap-up $lint | 完整支持 | | 其他 | 写适配器（指南） | 取决于 agent | 社区贡献 |

Vault 结构

集成模式下 vault 位于 .vault/（隐藏目录，默认已 gitignore）。独立模式下位于 vault/。内部结构相同：

.vault/                   （集成模式）或 vault/（独立模式）
  Home.md                 入口 — 当前焦点、快速链接
  SCHEMA.md               域定义、标签分类法、页面阈值
  log.md                  操作日志（append-only）
  brain/
    North Star.md         目标和方向 — 每次 session 自动读取
    Memories.md           记忆索引
    Key Decisions.md      值得跨 session 记住的决策
    Patterns.md           反复出现的规律
  work/
    Index.md              所有工作笔记的索引
    active/               进行中的项目
    archive/              已完成的项目
  templates/              笔记模板
  thinking/               草稿区 — 想清楚后归档，然后删除
  sources/                原始资料 — 不可修改，agent 只读
  reference/              问答回写 — 有价值的综合分析

八个目录，一份 Schema，五种笔记类型。

使用场景

详见 docs/usage.md — 7 个真实场景，从首次安装到项目完成，每一步都有输入和输出示例。

v0.8.0 新特性

• /lint skill — 13 项 vault 健康审计：断链、孤儿页面、索引完整性、frontmatter 校验、过期内容、大页面、标签审计、日志检查、索引膨胀、日志轮转、拆分建议、归档完整性、主题地图
• SCHEMA.md — 域定义、标签分类法（先声明后使用）、页面阈值（创建/更新/拆分/归档）、frontmatter 规范
• 矛盾追踪 — contradictions frontmatter 字段，双向标记冲突信息；/ingest 自动检测与现有内容的矛盾
• 批量摄入 — /ingest 支持多源批量处理，跨源去重、单次搜索、统一索引更新
• 回写决策逻辑 — /recall 使用 4 条保存 / 3 条不保存的决策矩阵；synthesized_from 字段追踪来源页面
• Obsidian 集成指南 — docs/obsidian.md，含 Dataview 查询、Graph View 技巧、推荐配置
• 预读协议 — 5 个 skill 均以 Step 0 上下文检查开始（读取 work/Index.md + SCHEMA.md）
• 新 frontmatter 字段 — type（work/decision/source-summary/reference/thinking）、sources（源文档路径）、synthesized_from（综合引用来源）
• Hook 增强 — session-start 注入 SCHEMA 上下文（标签分类法 + 页面阈值）；validate-write 校验标签白名单和 type 字段
• /wrap-up 增强 — 归档时自动迁移反向链接，3+ 笔记 session 后推荐运行 lint
• 11 条 Pitfalls 防错清单 — 常见反模式（详见 plugin/instructions.md 和 vault/CLAUDE.md）
• 5 个模板重构 — 所有模板增加内容结构规范和新 frontmatter 字段

设计原则

1. 数据主权 — 你的 markdown，你的 git，你的机器。没有云端锁定。
2. Agent 无关 — hook 是通用接口。一个 vault，多个 agent。
3. 默认极简 — 3 个 hook，~100 行指令。按需增加复杂度。
4. 图优先 — 目录按用途分组，[[wikilinks]] 按语义分组。链接是主要的组织工具。
5. 面向未来 — 即使模型有了内建记忆，vault 仍然有价值：可审计、可迁移、git 追踪的本地存储。

CLI

npx @suwujs/codex-vault init        # 安装 .vault/ + hooks 到当前项目
npx @suwujs/codex-vault upgrade     # 升级 hooks 和 skills（保留 vault 数据）
npx @suwujs/codex-vault uninstall   # 移除 hooks 和 skills（保留 vault 数据）
# init 会自动将 .vault/ 加入 .gitignore — 每位开发者拥有独立的本地 vault。

测试

npm test                # 完整 E2E 测试
npm run test:cli        # CLI 命令测试（22 个）
npm run test:hooks      # Hook 脚本测试（33 个）

配置

| 配置项 | 文件 | 说明 | |--------|------|------| | 自动执行 skills | .vault/.codex-vault/config.json（独立模式为 vault/.codex-vault/config.json） | {"classify_mode": "auto"} — 检测到意图后自动执行对应 skill，而非建议 |

依赖

• Git
• Python 3
• Node.js >= 18（CLI 安装用）
• Claude Code 或 Codex CLI（二选一）
• 可选：Obsidian（图谱视图、反向链接、可视化浏览）

灵感来源

• llm-wiki by Karpathy — 这个模式的起源

License

MIT