codex-recap

Topic-level automated memory management for Codex.

中文 | English

Inspired by hatawong/claude-recap

---

中文

一键安装

curl -fsSL https://raw.githubusercontent.com/WhiteCrow/codex-recap/main/install.sh | bash

默认安装位置：

• 源码目录：~/.local/share/codex-recap/src
• 命令入口：~/.local/bin/codex-recap

升级方式：重新执行同一条安装命令。
卸载方式：删除 ~/.local/share/codex-recap 和 ~/.local/bin/codex-recap。

如何使用

1. 在目标项目根目录执行一次：

codex-recap install

2. 正常启动 Codex。

3. 在会话里直接输入：

topic: <topic-name>
# 示例：topic: setup-auth
topic: current
topic: list

常用命令

topic: <topic-name>
topic: current
topic: list
topic: remember Do not auto-commit.
topic: remember-global Always prefer bun.
topic: rebuild
topic: off

自动化记忆管理会做什么

• 以 topic 为单位组织记忆，而不是把整个 session 压成一份大摘要。
• 当用户明显切换任务时，自动归档旧 topic 并切到新 topic。
• 当当前 topic 有实质进展时，在最终回复前自动 checkpoint。
• 用 topic 粒度恢复上下文，更适合继续执行、检索和人工查看。
• topic: off 可以暂停自动化管理，直到再次显式设置 topic。

要解决的问题

Codex 可以继续会话，但当任务切换、会话重开，或者长对话混入多个主题时，topic 级别的工作上下文仍然很容易漂散。没有结构化记忆管理时，同一个项目背景会被反复解释，进度埋在长 transcript 里，任务边界也会越来越模糊。

codex-recap 做什么

codex-recap 把 claude-recap 的核心思路适配到 Codex，具体依赖：

• 本地 Markdown memory
• 受控的 AGENTS.md 自动化规则
• 基于 topic 的归档与恢复
• 基于 transcript 的重建，作为兜底恢复路径

为什么是 topic 级别

• 比 session 级摘要更细，信息损失更少。
• 多任务切换时更容易恢复到正确上下文。
• 更适合 grep、人工阅读和继续执行。
• 归档和恢复都围绕具体任务，而不是混杂对话。

工作方式

1. codex-recap install 会向当前项目的 AGENTS.md 注入受控区块。
2. Codex 学会把 topic: 前缀消息识别为控制命令。
3. topic: <topic-name> 会映射到 codex-recap topic set <topic-name>。
4. topic 切换时，旧 topic 会被归档成 Markdown。
5. topic checkpoint 用于在最终回复前内部保存有意义的进展。
6. rebuild 会扫描最近匹配的 Codex transcript，在需要时重建 topic 上下文。

参考项目

这个项目参考了 hatawong/claude-recap。

codex-recap 保留了 topic-based memory 的核心思路，但结合 Codex 的约束，采用 AGENTS.md 驱动的自动化，而不是 Claude 的 hook 集成方式。

存储结构

默认存储在 ~/.codex-recap。如需覆盖，设置 MEMORY_HOME。

~/.codex-recap/
  REMEMBER.md
  projects/
    {encoded-project-path}/
      REMEMBER.md
      {session-id}/
        .topic_mode
        .current_topic
        .current_topic.json
        01-setup-auth.md
        02-fix-login-bug.md

限制

• 仅支持 Codex。
• 不依赖 hooks，但也不具备 hook 级强制保证。
• v1 不提供 MCP server。
• 自动化是通过 AGENTS.md 指令驱动的 best-effort 机制。

开发与验证

npm run check
npm test
npm run build

相关文档

• Architecture
• Usage
• Limitations

---

English

One-Line Install

curl -fsSL https://raw.githubusercontent.com/WhiteCrow/codex-recap/main/install.sh | bash

Default install locations:

• Source checkout: ~/.local/share/codex-recap/src
• Command wrapper: ~/.local/bin/codex-recap

To upgrade, rerun the same install command.
To uninstall, remove ~/.local/share/codex-recap and ~/.local/bin/codex-recap.

How to Use

1. Run once at the root of the target project:

codex-recap install

2. Start Codex normally.

3. Use these messages directly in the conversation:

topic: <topic-name>
# example: topic: setup-auth
topic: current
topic: list

Common Commands

topic: <topic-name>
topic: current
topic: list
topic: remember Do not auto-commit.
topic: remember-global Always prefer bun.
topic: rebuild
topic: off

What the Automation Does

• Organizes memory by topic instead of flattening an entire session into one summary.
• Archives the previous topic automatically when the user clearly switches tasks.
• Creates a checkpoint before the final reply when meaningful progress was made.
• Restores context at topic granularity, which is easier to continue, inspect, and grep.
• Lets you pause automation with topic: off until a new topic is explicitly set.

The Problem

Codex can continue a session, but topic-level working context is still easy to lose when tasks change, sessions restart, or a long thread drifts across multiple concerns. Without structured memory management, the same project context keeps getting re-explained, progress gets buried in long transcripts, and task boundaries blur.

What codex-recap Does

codex-recap adapts the core idea behind claude-recap to Codex by using:

• local Markdown memory
• managed AGENTS.md automation rules
• topic-based archival and recovery
• transcript-backed rebuild as a fallback recovery path

Why Topic-Level Matters

• It preserves more task-specific detail than session-level summaries.
• It handles task switching more cleanly.
• It makes archived context easier to inspect and reuse.
• It keeps memory centered on concrete units of work rather than mixed conversations.

How It Works

1. codex-recap install injects a managed block into the current project's AGENTS.md.
2. Codex learns to interpret topic:-prefixed messages as control commands.
3. topic: <topic-name> maps to codex-recap topic set <topic-name>.
4. Topic switches archive the previous topic into Markdown.
5. topic checkpoint is used internally to persist meaningful progress before final replies.
6. rebuild scans the latest matching Codex transcript and reconstructs topic context when needed.

Reference Project

This project is inspired by hatawong/claude-recap.

codex-recap keeps the core idea of topic-based memory, but adapts it to Codex constraints with AGENTS.md-driven automation instead of Claude hook-based integration.

Storage

By default memory is stored in ~/.codex-recap. Override it with MEMORY_HOME if needed.

~/.codex-recap/
  REMEMBER.md
  projects/
    {encoded-project-path}/
      REMEMBER.md
      {session-id}/
        .topic_mode
        .current_topic
        .current_topic.json
        01-setup-auth.md
        02-fix-login-bug.md

Limitations

• Codex-only.
• No hook dependency, but also no hook-level guarantees.
• No MCP server in v1.
• Automation is best-effort and instruction-driven through AGENTS.md.

Development

npm run check
npm test
npm run build

Documentation

• Architecture
• Usage
• Limitations