# codex-memory-bridge

**Repository Path**: chingan/codex-memory-bridge

## Basic Information

- **Project Name**: codex-memory-bridge
- **Description**: codex历史对话恢复，codex的对话记忆保存在本地时候，当从官方账号改到第三方中转时候可以使用此工具来恢复记忆
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: feat/memory-bridge
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-06-15
- **Last Updated**: 2026-06-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: codex

## README

# Codex 记忆桥

[English](README.md)

Codex 记忆桥用于查找本机旧的 Codex 对话、查看已保存的记忆内容、导出可复用的记忆包，并把“本地其实还在，但当前 Codex 看不到”的旧线程恢复出来。

它主要解决一个很实际的问题：你的本地 Codex 数据没有丢，只是因为切换了 provider 或环境，旧线程不再出现在当前 Codex 的正常列表里。

这个工具只使用 Python 标准库。它不会复制 `auth.json`，也不会把你的本地线程内容发送到任何远程服务。

## 适合什么场景

你可以用它来：

- 搜索一个或多个 Codex home 里的旧线程
- 预览已存摘要、已存记忆和最近消息
- 导出 Markdown 记忆包
- 生成 bridge prompt，在新会话里继续旧工作
- 把旧线程恢复到目标 Codex home
- 在切换 provider 之后重标记已有线程

## 推荐使用方式

对大多数用户来说，最推荐直接用 Web UI。

原因很简单，网页比命令行更省事：

- 可以直接从下拉框选择源 `.codex` 和目标 `.codex`
- 可以直接点线程，不需要手输线程 ID
- 可以在一个界面里看摘要、记忆和最近消息
- 可以先做恢复预演，再决定是否写入
- 可以直接批量处理当前筛选结果
- 可以在同一个页面里查看备份并回滚

CLI 不是不能用，而是更适合已经习惯命令行、想做脚本化处理，或者想手动精确控制多 home 参数的人。

## 环境要求

你只需要：

- Python 3
- 本地 Codex 数据，例如 `sessions/`、`state_5.sqlite`，以及可选的 `memories_1.sqlite`
- 能打开本地 `http://127.0.0.1:*` 页面的浏览器，用于 Web UI

Codex 目前见过两种本地数据库布局：

- 新版布局：`{CODEX_HOME}/sqlite/state_5.sqlite` 和 `{CODEX_HOME}/sqlite/memories_1.sqlite`
- 旧版 flat 布局：`{CODEX_HOME}/state_5.sqlite` 和 `{CODEX_HOME}/memories_1.sqlite`

工具会自动解析当前活跃数据库。如果存在 `sqlite/state_5.sqlite`，就优先把它当作 Codex 正在使用的数据库，所有写入操作都会写到这里；否则才回退到旧版 flat 布局。

## 快速开始

先用 Web UI：

```powershell
.\cmb-ui.cmd
```

不要直接双击打开 `webui/index.html`。这个页面依赖 `cmb-ui.cmd` 启动的本地 Python HTTP 服务。

网页里的典型操作流程：

1. 选择包含旧线程的来源 home
2. 选择当前 Codex 正在使用的目标 home
3. 搜索并点击你要处理的线程
4. 查看摘要、记忆和最近消息
5. 先做恢复预演
6. 预演结果确认无误后再执行写入

## Web UI

本地界面支持：

- 自动发现可能的 Codex home
- 选择搜索来源目录
- 选择恢复目标目录
- 按标题、provider、工作目录或消息内容搜索
- 直接点击线程，而不是手输线程 ID
- 预览已存记忆和最近完整消息
- 导出 Markdown 记忆包
- 在真正写入前先做恢复预演
- 对当前筛选结果做批量处理
- 查看 restore 备份历史，并回滚某一次恢复

Web UI 默认是只读浏览模式。所有 restore 类操作都必须先预演、再确认，最后才会写入本地数据。

每个已发现的 home 都会显示检测到的存储布局，例如 `sqlite` 或 `flat`。把鼠标悬停在 home 标签上，可以看到工具实际读写的 `state_db`、`memory_db` 和 `goals_db` 路径。

## CLI 快速开始

如果你更习惯命令行，或者想做脚本化操作，可以用下面这些命令：

```powershell
.\cmb.cmd doctor
.\cmb.cmd search "关键词"
.\cmb.cmd show 019ec052
.\cmb.cmd bridge 019ec052 --clipboard
```

如果网页显示恢复成功，但 Codex 桌面端仍然看不到线程，先运行 `doctor`。它会打印实际使用的数据库路径，方便确认工具写入的是 `{CODEX_HOME}/sqlite/state_5.sqlite`，还是旧版 `{CODEX_HOME}/state_5.sqlite`。

## Restore 和 Bridge 的区别

如果你只是想把旧上下文带到一个新会话里，用 `bridge`。

如果你想让 Codex 自己的线程列表重新显示旧对话，用 `restore`。

预演：

```powershell
.\cmb.cmd --home "$HOME\.codex" --home "D:\proxy-codex" restore 019ec052
```

写入：

```powershell
.\cmb.cmd --home "$HOME\.codex" --home "D:\proxy-codex" restore 019ec052 --apply
```

## 最常见的恢复场景

如果你一开始用的是官方 provider，后来切换到了第三方中转站，那么旧线程可能还带着 `openai` 这类旧 provider 标签。

这时通常会出现一种现象：工具能读到内容，但当前 Codex 的正常线程列表里看不到这些旧线程。

这个项目会按两种方式处理：

- 如果线程在另一个 Codex home 里，就导入到当前目标 home
- 如果线程已经在同一个 home 里，就直接重标记已有线程，而不是导入重复副本

这个“同目录重标记”就是修复“记忆还在，但当前 provider 看不到”的关键路径。

## 活跃数据库布局

如果 Web UI 显示恢复成功，但 Codex 桌面端仍然没有出现线程，最重要的是确认工具写入的 SQLite 数据库，是否就是当前 Codex 正在使用的数据库。

运行：

```powershell
.\cmb.cmd doctor
```

或者打开 Web UI，把鼠标悬停在 home 标签上。确认 `State DB` 指向当前活跃布局：

- 如果 `{CODEX_HOME}/sqlite/state_5.sqlite` 存在，工具应该显示布局为 `sqlite`，并使用这个路径。
- 如果不存在 `sqlite/` 数据库，工具才会显示布局为 `flat`，并使用 `{CODEX_HOME}/state_5.sqlite`。

这一点很关键，因为新版 Codex 可能已经改用 `sqlite/` 子目录，但根目录里仍然残留或被误生成一个旧的 flat 数据库。写入旧数据库时，工具看起来会成功，但当前 Codex 桌面端不会因此显示恢复的线程。

## 安全机制

执行本地写入前，工具会先在这里创建备份：

```text
~/.codex/backups/codex-memory-bridge/
```

`retag` 的安全行为：

1. 创建 `state_5.sqlite` 的 SQLite 备份
2. 备份对应的 rollout JSONL
3. 拒绝写入 `sessions/` 或 `archived_sessions/` 之外的文件
4. 默认拒绝修改最近 60 秒内仍在更新的 rollout，除非使用 `--force-active`
5. 如果数据库写入失败，会恢复 JSONL

## 多个 Codex Home

如果自动发现漏掉了某个 home，可以手动传入：

```powershell
.\cmb.cmd --home "$HOME\.codex" --home "D:\proxy-codex" search "关键词"
.\cmb-ui.cmd --home "$HOME\.codex" --home "D:\proxy-codex"
```

Web UI 中，恢复目标就是目标下拉框里选中的目录。命令行里，工具优先使用当前实际的 `CODEX_HOME`；如果它不在传入列表中，就回退到第一个 `--home`。

## 命令

- `doctor`：检查本地存储和 provider 分布
- `reindex`：重建本地线程的桌面端可见性元数据
- `list`：显示最近线程
- `search`：搜索元数据和完整对话文本
- `show`：预览线程
- `export`：导出 Markdown 记忆包
- `bridge`：生成适用于当前 provider 的恢复提示词
- `restore`：把线程导入或重标记到目标 Codex home
- `retag`：带备份修改 provider 和可选 model 元数据
- `webui`：启动本地浏览器界面

## 测试

```powershell
py -3 -m unittest discover -s tests -v
```