# 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 Memory Bridge

[简体中文](README.zh-CN.md)

Codex Memory Bridge helps you find old local Codex conversations, inspect saved memory, generate reusable memory packs, and restore hidden threads so they become visible again in your current Codex setup.

It is designed for a very practical problem: your local Codex data still exists, but after a provider switch or environment change, the old threads no longer show up in the normal Codex thread list.

The tool uses only the Python standard library. It does not copy `auth.json`, and it does not send local thread content anywhere.

## When To Use It

Use this project when you want to:

- search old local Codex threads across one or more homes
- preview saved summaries, saved memory, and recent messages
- export a portable Markdown memory pack
- generate a bridge prompt for continuing work in a new conversation
- restore old threads into a target Codex home
- retag existing local threads after switching providers

## Recommended Way To Use It

For most users, the Web UI is the best entry point.

It is simpler than the CLI because you can:

- choose the source and target `.codex` directories from dropdowns
- click threads directly instead of typing thread IDs
- preview saved memory and recent messages in one place
- run restore previews before writing anything
- batch-process the current filtered result set
- inspect backups and roll back a restore from the same screen

The CLI is still useful, but mainly for advanced users who want direct commands, scripting, or manual multi-home control.

## Environment

You only need:

- Python 3
- local Codex data such as `sessions/`, `state_5.sqlite`, and optionally `memories_1.sqlite`
- a browser that can open a local `http://127.0.0.1:*` page for the Web UI

Codex has used two local database layouts:

- Newer layout: `{CODEX_HOME}/sqlite/state_5.sqlite` and `{CODEX_HOME}/sqlite/memories_1.sqlite`
- Older flat layout: `{CODEX_HOME}/state_5.sqlite` and `{CODEX_HOME}/memories_1.sqlite`

The bridge resolves the active store automatically. If the `sqlite/state_5.sqlite` database exists, it is treated as the active Codex store and write operations use that database. Otherwise the tool falls back to the older flat layout.

## Quick Start

Start with the Web UI:

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

Do not open `webui/index.html` directly by double-clicking it. The UI depends on the local Python HTTP server started by `cmb-ui.cmd`.

Typical flow in the Web UI:

1. Select the source home that contains the old threads
2. Select the target home that your current Codex is using
3. Search and click the thread you want
4. Inspect saved memory, summary, and recent messages
5. Run restore preview
6. Confirm and apply only if the preview looks correct

## Web UI

The local UI lets you:

- auto-discover likely Codex homes
- choose a search source home
- choose a restore target home
- search by title, provider, workspace, or message content
- click a thread instead of typing a thread ID
- preview saved memory and full recent messages
- export a Markdown memory pack
- preview restore actions before writing
- batch-process the current filtered result set
- inspect restore backups and roll back a specific restore

The UI is read-only by default. All restore-style actions require an explicit preview and confirmation before writing local data.

Each discovered home displays its detected store layout, such as `sqlite` or `flat`. Hover the home badge to see the exact `state_db`, `memory_db`, and `goals_db` paths the tool will read or write.

## CLI Quick Start

Use the CLI when you prefer direct commands or need something scriptable.

Examples:

```powershell
.\cmb.cmd doctor
.\cmb.cmd search "keyword"
.\cmb.cmd show 019ec052
.\cmb.cmd bridge 019ec052 --clipboard
```

Use `doctor` first when a restore appears to succeed but Codex still does not show the thread. It prints the exact active database paths, for example whether the tool is using `{CODEX_HOME}/sqlite/state_5.sqlite` or `{CODEX_HOME}/state_5.sqlite`.

## Restore vs Bridge

Use `bridge` when you only want to carry old context into a new conversation.

Use `restore` when you want Codex itself to show the old conversation again in its normal thread list.

Preview:

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

Apply:

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

## Common Recovery Case

If you originally used the official provider and later switched to a third-party proxy, your old threads may still exist locally but remain tagged with the old provider, such as `openai`.

In that case, the UI may show the thread contents, but the current Codex app may not show those threads in its normal list.

Codex Memory Bridge handles this in two ways:

- if the thread is in another Codex home, it can import it into the current target home
- if the thread is already in the same home, it can retag the existing thread instead of importing a duplicate

This same-home retag flow is the practical fix for "my old memory is still there, but my current provider cannot see it."

## Active Database Layout

If the Web UI says a restore succeeded but the Codex desktop app still does not show the thread, the most important thing to check is whether the bridge wrote to the same SQLite database that Codex is actively using.

Run:

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

or open the Web UI and hover the home badge. Confirm that `State DB` points to the active layout:

- If `{CODEX_HOME}/sqlite/state_5.sqlite` exists, the bridge should report layout `sqlite` and use that path.
- If the `sqlite/` database does not exist, the bridge should report layout `flat` and use `{CODEX_HOME}/state_5.sqlite`.

This matters because a stale flat database can exist beside the newer `sqlite/` directory. In that case, writing the flat database may look successful in the tool but will not change what the current Codex desktop app displays.

## Safety

Before local writes, the tool creates backups under:

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

`retag` safety behavior:

1. Creates a SQLite backup of `state_5.sqlite`
2. Backs up the matching rollout JSONL
3. Refuses to write outside `sessions/` or `archived_sessions/`
4. Refuses to modify a rollout updated within the last 60 seconds unless `--force-active` is used
5. Restores the JSONL if the database write fails

## Multiple Codex Homes

If auto-discovery misses a home, pass it manually:

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

In the UI, the restore target is whatever you choose in the target-home dropdown. In the CLI, the tool prefers the actual current `CODEX_HOME`; if that home is not in the provided list, it falls back to the first `--home`.

## Commands

- `doctor`: inspect local stores and provider distribution
- `reindex`: rebuild desktop visibility metadata for local threads
- `list`: show recent threads
- `search`: search metadata and full conversation text
- `show`: preview a thread
- `export`: write a Markdown memory pack
- `bridge`: build a restore prompt for the active provider
- `restore`: import or retag a thread into the target Codex home
- `retag`: change provider and optional model metadata with backups
- `webui`: start the local browser UI

## Tests

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