Sync Memory

sync-memory 是一个给 Codex / Codex Desktop 用的本地 skill。

它解决两个常见问题：

1. 你在账号 A 里做过项目开发，切到账号 B 之后，希望还能接着用之前保存的项目记忆和上下文。
2. 你切换账号、provider 或模型之后，Codex Desktop 左侧本机历史线程突然看不到了，但这些线程其实还在本地数据库里。

这个项目把这两件事整合到了一起：

• 恢复本地共享记忆
• 检查并修复本机历史线程的可见性
• 在每次最终回复后追加本地可读的额度状态页脚

这个项目是干什么的

这个项目不是云端聊天同步工具，也不是 OpenAI 官方账号级 memory 迁移工具。

它做的是一层“本地恢复”：

• 把你主动保存的项目记忆、偏好、命令、上下文保存在本机
• 在切换账号后的新会话里，恢复一次这些记忆
• 检查本机 ~/.codex/state_5.sqlite 里的历史线程，判断它们是不是因为 provider / model 变化而不再显示
• 在你确认之后，把这些旧线程重新挂到当前目标下，让它们重新显示在侧边栏
• 从本机 rollout JSONL 的 token_count 事件读取背景信息、5 小时限额、7 天限额，并格式化成回复页脚

适合什么场景

• 你从一个账号切到另一个账号，还想继续同一个项目
• 你不想每次都手动重新解释项目背景
• 你切号后发现侧边栏历史空了，但你知道本地数据还在
• 你希望“切号后的第一轮”自动恢复一次记忆，而不是每轮都读

不适合什么场景

• 直接读取 OpenAI 云端另一个账号的私有内置 memory
• 直接下载另一个账号的云端聊天记录
• 跨电脑自动同步未迁移的本地数据库
• 替代官方账号系统或官方 memory 系统

安装

如果你已经在仓库目录里，安装只需要：

bash install.sh

如果你想让用户在任意目录下一条命令直接安装，推荐在 GitHub 里写成这样：

REPO_URL="<your-repo-url>" && TMP_DIR="$(mktemp -d)" && git clone --depth 1 "$REPO_URL" "$TMP_DIR/sync-memory" && bash "$TMP_DIR/sync-memory/install.sh" && rm -rf "$TMP_DIR"

这样用户无论当前在哪个目录，都可以直接把项目拉下来并安装。

如果你已经确定了 GitHub 仓库地址，也可以把上面的 <your-repo-url> 直接替换成真实地址。

默认会安装到：

${CODEX_HOME:-$HOME/.codex}/skills/sync-memory

安装时还会在下面这个文件里写入一个带标记的 quota footer 规则块：

${CODEX_HOME:-$HOME/.codex}/AGENTS.md

以后 Codex 在每次最终回复前会自动运行本项目的 quota_status.py，然后把额度状态输出贴到回复末尾。 额度数字和进度条必须来自这个 Python 脚本的 stdout，模型只负责粘贴，不负责估算或改写。 如果开关关闭，脚本默认运行时不会输出任何内容，因此最终回复也不会追加额度页脚。 用户也可以直接对 Codex 说“打开额度”或“关闭额度”，Codex 会自动运行对应的开关命令。

最常见的使用方式

切换到另一个账号后，在新会话里直接对 Codex 说：

我刚切换账号了，先帮我恢复这个项目之前的记忆和上下文，再继续当前任务。

如果你怀疑左侧历史聊天也不见了，就说：

我刚切换账号了，先帮我恢复这个项目之前的记忆，并检查一下旧聊天记录是不是需要恢复显示。

这就是最推荐的使用方式。

命令行用法

1. 初始化本地共享记忆

第一次使用时执行：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" init

2. 切号后统一恢复

这是最核心的命令：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" after-switch --cwd "$PWD"

它会：

• 恢复一次共享记忆
• 检查本地历史是否需要修复
• 默认只检查，不直接改数据库

3. 只恢复记忆

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" restore-once --cwd "$PWD"

4. 记录新的项目记忆

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" note --account A --project my-project --text "Use pytest -q before handoff."

5. 注册一个项目

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" project-init --project my-project --path /absolute/project/path --summary "Short project summary"

6. 检查本地历史是否需要恢复

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/codex_history_sync.py" --json status

7. 修复本地历史显示

如果你确认要把旧线程重新显示到当前目标下：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/memory_sync.py" after-switch --cwd "$PWD" --sync-history

或者直接调用底层脚本：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/codex_history_sync.py" --json sync

8. 自动输出额度状态

安装后，Codex 会在每次最终回复前自动运行：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/quota_status.py" --cwd "$PWD"

如果开关开启，最终回复末尾会自动追加类似下面的额度状态：

背景信息:      剩余 91%  (已使用 24,512/共 258K)
5 小时限额:   ████████████████████████░░░░░░░░  剩余 75%  (重置时间: 01:54)
7 天限额:     ███░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  剩余 8%  (重置时间: 4月29日)

如果只想手动查看，也可以直接运行：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/quota_status.py" --cwd "$PWD"

9. 开关额度页脚

用户可以直接对 Codex 说：

• 打开额度
• 关闭额度
• 显示额度
• 不要显示额度

Codex 会自动运行对应命令。也可以手动执行下面的命令。

开启：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/quota_status.py" on

关闭：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/quota_status.py" off

查看状态：

python3 "${CODEX_HOME:-$HOME/.codex}/skills/sync-memory/scripts/quota_status.py" status

开关状态保存在：

${CODEX_HOME:-$HOME/.codex}/shared-memory/quota-footer.json

它实际做了什么

共享记忆部分

把项目记忆写入本机目录，例如：

• ~/.codex/shared-memory/shared-memory.md
• ~/.codex/shared-memory/projects/<project>.md
• ~/.codex/shared-memory/accounts/<account>.md

历史修复部分

检查并操作本机的：

• ~/.codex/state_5.sqlite

在修改前会自动创建备份，备份目录通常是：

• ~/.codex/history_sync_backups

安全边界

这个项目能做：

• 恢复你主动保存的本地项目记忆
• 让本机已经存在的旧线程重新显示
• 在修复历史前自动备份本地数据库

这个项目不能做：

• 读取另一个 OpenAI 账号的私有云端 memory
• 把云端隐藏状态原样搬到另一个账号
• 无中生有恢复已经删除的本地历史数据库

项目结构

• README.md: 给 GitHub 用户看的说明
• SKILL.md: 给 Codex 看的 skill 说明
• install.sh: 一键安装脚本
• scripts/memory_sync.py: 共享记忆与 after-switch 统一入口
• scripts/codex_history_sync.py: 本地历史显示修复
• scripts/quota_status.py: 额度状态页脚
• references/: 补充规则和集成说明

使用建议

• 第一次先运行一次 init
• 切号后优先使用 after-switch
• 如果要修复历史显示，建议先关闭 Codex Desktop
• 除非你明确想恢复旧线程显示，否则先看 status 再决定要不要 sync

一句话总结

这是一个帮助你在切换 Codex / OpenAI 账号之后，继续接住“本地项目记忆”和“本机历史线程”的本地 skill。