codex-history-ingest

Codex 历史记录摄取 — 对话挖掘

从用户过去的 Codex 会话中提取知识，并将其整理到 Obsidian wiki 中。会话日志内容丰富但噪声较多：关注持久有效的知识，而非运行遥测数据。

可以直接调用此技能，也可以通过 wiki-history-ingest 路由器调用（/wiki-history-ingest codex）。

开始之前

写作配置： 在起草或改写自然语言 Markdown 之前，请阅读并应用 llm-wiki/SKILL.md 中的 Writing Profile Resolution 部分。框架架构、来源溯证、安全性和特定操作要求优先。 WRITING.md 中的偏好仅适用于新起草或改写的自然语言 Markdown；保留源内容和结构化记录。

1. 解析配置 — 遵循 llm-wiki/SKILL.md 中的 Config Resolution Protocol（内联 @name 覆盖 → 沿 CWD 向上查找 .env → 全局配置 → 提示设置）。由此获取 OBSIDIAN_VAULT_PATH 和 CODEX_HISTORY_PATH（默认为 ~/.codex）
2. 阅读保管库根目录下的 .manifest.json，检查已摄取的内容
3. 阅读保管库根目录下的 index.md，了解 wiki 已包含的内容

摄取模式

追加模式（默认）

检查 .manifest.json 中的每个源文件。仅处理：

• 清单中不存在的文件（新的会话记录、新的索引文件）
• 修改时间晚于清单中 ingested_at 的文件

常规同步时使用此模式。

完整模式

无论清单中是否已有记录，都处理所有内容。在执行 wiki-rebuild 后，或用户明确要求完整重新摄取时使用。

Codex 数据布局

Codex 将本地产物存储在 ~/.codex/ 下。

~/.codex/
├── sessions/                          # Session rollout logs by date
│   └── YYYY/MM/DD/
│       └── rollout-<timestamp>-<id>.jsonl
├── archived_sessions/                 # Archived rollout logs
├── session_index.jsonl                # Lightweight index of thread id/name/updated_at
├── history.jsonl                      # Local transcript history (if persistence enabled)
├── config.toml                        # User config (contains history settings)
└── state_*.sqlite / logs_*.sqlite     # Runtime DBs (usually skip)

按价值排序的关键数据源

1. session_index.jsonl — 用于获取 ID、标题和更新时间的最佳清单来源
2. sessions/**/rollout-*.jsonl — 内容丰富的结构化对话事件
3. history.jsonl — 启用时可作为有用的备用来源／时间线参考

除非用户明确要求，否则不要摄取 SQLite 内部数据。

步骤 1：调查并计算增量

扫描 CODEX_HISTORY_PATH，并与 .manifest.json 对比：

• ~/.codex/session_index.jsonl
• ~/.codex/sessions/**/rollout-*.jsonl
• ~/.codex/archived_sessions/**（可选；仅在用户要求查看归档历史时处理）
• ~/.codex/history.jsonl（可选备用来源）

对每个文件进行分类：

• 新增 — 清单中不存在
• 已修改 — 清单中已有记录，但文件的修改时间晚于 ingested_at
• 未更改 — 已摄取且未发生更改

深入解析前，先简要报告增量摘要。

步骤 2：优先解析会话索引

session_index.jsonl 通常包含如下条目：

{"id":"...","thread_name":"...","updated_at":"..."}

使用它来：

• 构建规范的会话清单
• 优先处理近期或信号度高的会话
• 将 rollout ID 映射为易读的对话名称

步骤 3：安全解析 Rollout JSONL

每一行 rollout-*.jsonl 都是一个事件封套，包含：

{
  "timestamp": "...",
  "type": "session_meta|turn_context|event_msg|response_item",
  "payload": { ... }
}

提取规则

• 优先提取用户意图和助手可见的输出
• 优先使用包含用户／助手消息内容的 response_item 记录
• 有选择地使用 event_msg 中有意义的里程碑；忽略纯遥测数据
• 将 session_meta 视为元数据（cwd、模型、ID），而非用户知识

跳过／噪声过滤

• Token 用量统计事件
• 不含语义内容的工具管道信息
• 原始命令输出，除非其中包含可复用的决策／模式
• 未带来新决策的重复计划快照

关键隐私过滤

Rollout 日志可能包含注入的指令、工具载荷和敏感文本。不要逐字摄取系统／开发者提示词或秘密信息。

• 删除 API 密钥、令牌、密码和凭据
• 除非相关且获得批准，否则对私人标识符进行脱敏
• 用摘要代替原始对话记录引用

步骤 4：按主题聚类

不要为每个会话都创建一个 wiki 页面。

• 将多个会话中稳定的主题归为一组
• 将混合会话拆分为独立主题
• 合并不同日期／项目中反复出现的概念
• 使用元数据中的 cwd 推断项目范围

第 5 步：提炼为 Wiki 页面

根据现有 Wiki 约定整理提取出的知识：

• 项目专属的架构／流程 -> projects/<name>/...
• 通用概念 -> concepts/
• 常见技术／调试手册 -> skills/
• 工具／服务 -> entities/
• 跨会话模式 -> synthesis/

对于每个受影响的项目，创建／更新 projects/<name>/<name>.md（以项目名称作为文件名，绝不使用 _project.md）。

编写规则

• 提炼知识，而不是记录时间顺序
• 避免写“我们在 X 日期讨论了……”，除非日期背景不可或缺
• 为每个新建／更新的页面添加 summary: frontmatter（1-2 句话，<= 200 个字符）
• 为每个新页面添加置信度和生命周期字段：

  base_confidence: 0.42
  lifecycle: draft
  lifecycle_changed: <obsidian-wiki memory now --date>
  

  更新页面时保持 lifecycle 不变。
• 添加来源标记：
  • ^[extracted]：直接依据明确的会话内容
  • ^[inferred]：综合多个事件／会话中的模式
  • ^[ambiguous]：会话内容存在冲突
• 为每个变更的页面添加／更新 provenance: frontmatter 组合

第 6 步：更新清单、日志和索引

更新 .manifest.json

对每个已处理的源文件，更新：

• ingested_at、size_bytes、modified_at
• source_type：codex_rollout | codex_index | codex_history
• project：推断出的项目名称（如适用）
• pages_created、pages_updated

添加／更新顶层项目／会话摘要区块：

{
  "project-name": {
    "source_path": "~/.codex/sessions/...",
    "last_ingested": "TIMESTAMP",
    "sessions_ingested": 12,
    "sessions_total": 40,
    "index_updated_at": "TIMESTAMP"
  }
}

更新特殊文件

使用一次加锁调用更新 index.md、log.md 和 hot.md：

obsidian-wiki memory sync CODEX_HISTORY_INGEST \
  sessions=<sessions> pages_updated=<pages_updated> \
  pages_created=<pages_created> mode=<mode> \
  --takeaways "Ingested 12 Codex sessions; surfaced recurring patterns in CLI tooling and shell scripting."

绝不要手动编辑 index.md、log.md 或 hot.md——该命令会加锁，避免并行写入方丢失你的更新。--takeaways 是以前会写入 Recent Activity 的单行概念摘要；省略该参数即可保留之前的 takeaways，不作改动。

完整流程见 .skills/llm-wiki/references/MEMORY.md。

隐私与合规

• 提炼并综合内容；避免直接倾倒原始记录
• 默认对任何看起来敏感的内容进行删节
• 存储个人／敏感详情前先询问用户
• 尽量少提及他人，并确保提及符合目的

参考

字段级解析说明和提取指南见 references/codex-data-format.md。

写入知识库后刷新 QMD

QMD 是搜索索引，并非事实来源。如果 $QMD_WIKI_COLLECTION 为空或未设置，则跳过此步骤。仅在此技能已写入或重写知识库 Markdown 文件后运行。如果 QMD 刷新失败，不要回滚知识库变更；应单独报告 QMD 状态。

如果已设置 $QMD_CLI，则使用它；否则使用 qmd。

${QMD_CLI:-qmd} update

如果输出提示需要向量或嵌入可能已过时，请运行：

${QMD_CLI:-qmd} embed

使用以下任一方式验证集合：

${QMD_CLI:-qmd} ls "$QMD_WIKI_COLLECTION"

或者，在已知具体页面路径时：

${QMD_CLI:-qmd} get "qmd://$QMD_WIKI_COLLECTION/<page>.md" -l 5

记录以下状态之一：

• QMD refreshed: update + embed + verified
• QMD refreshed: update only + verified
• QMD skipped: QMD_WIKI_COLLECTION unset
• QMD skipped: qmd CLI unavailable
• QMD failed: <short error summary>