Clexo

clexo

Session memory and cross-AI context for Claude Code and Codex Claude Code forgets. clexo remembers.

Why • Quick Start • vs /compact /clear /resume • CLI • MCP • How it works

---

> Inside a Claude Code session, type !clexo save. Then /clear. > The next session auto-restores the snapshot — summary + memory preserved, raw context cleared. > No /compact wait. No claude --resume reloading the full history. No /clear loss.

---

✨ Why

If you live in Claude Code or Codex, three context operations all hurt. clexo replaces all three.

| | The pain | clexo replacement | |---|----------|-------------------| | 🐢 | /compact — 1-3 minutes on long sessions, blocks you in-session | !clexo save — ~80 ms snapshot, then /clear and continue | | 💸 | claude --resume — re-loads the entire history into context | clexo load — restores the compact snapshot only | | 🪦 | /clear — irreversible, loses everything | /clear after !clexo save — auto-restored on next session |

Plus one structural gap nothing else closes: Codex doesn't see Claude's history; Claude doesn't see Codex's. clexo indexes both into one archive — load a Codex session into Claude, or vice versa.

Zero daemon. No API key. Self-indexing on demand. Your AI sessions become a searchable meta-memory across every prior conversation.

---

🚀 Quick Start

pipx install git+https://github.com/sankrant/clexo
clexo install

Two steps: pipx installs the clexo command into an isolated environment (no system-Python pollution, and no "python3 too old" — pipx picks a suitable interpreter); clexo install then wires it into Claude Code. Both are idempotent and safe to re-run.

> No pipx? Add it with brew install pipx (macOS) or python3 -m pip install --user pipx. Prefer uv? uv tool install git+https://github.com/sankrant/clexo. Working from a local checkout? git clone … && cd clexo && ./install.sh runs the same two steps.

What the install does

Nothing hidden — two steps, each with one job:

| Step | What it does | What it touches | |------|--------------|-----------------| | pipx install … | Isolated venv with clexo + its one dependency (mcp); puts the clexo command on PATH. Touches nothing in Claude Code. | ~/.local/bin/clexo | | clexo install | Registers the MCP server and adds two hooks. Idempotent; backs up settings.json first; re-points an older install. | ~/.claude.json (MCP), ~/.claude/settings.json (hooks) |

The two hooks clexo install adds to ~/.claude/settings.json:

• SessionStart → clexo session-start — restores a pending snapshot after /clear (the auto-restore behavior)
• SessionEnd → clexo sync — indexes the just-ended session in the background

It registers one MCP server: claude mcp add --scope user clexo clexo serve. Upgrading from an older install? clexo install re-points stale server.py-based hooks/MCP to the clexo command and removes the old ~/.local/bin/clexo symlink.

clexo's own data — the search index, transcript archive, and snapshots — lives in ~/.clexo/, created on first use. No daemon, no API key, nothing sent anywhere. (Hook details: [docs/hooks.md](docs/hooks.md).)

To remove clexo: claude mcp remove --scope user clexo, delete the clexo SessionStart/SessionEnd blocks from ~/.claude/settings.json, then pipx uninstall clexo (and optionally rm -rf ~/.clexo to drop the index/archive).

Try it

# Inside a Claude Code session, drop a save and clear cleanly:
!clexo save            # snapshot the current session (~80 ms)
/clear                 # standard Claude Code; the next session auto-restores

# From any terminal:
clexo search "csrf token"        # FTS across every session, ever
clexo tag auth-fix               # name the current session
clexo load auth-fix              # launch a fresh claude, snapshot restored via hook
clexo resume auth-fix            # or reopen the original session (claude --resume; full rehydrate)
clexo stats                      # how many tokens you've saved so far

---

🔁 The three Claude Code operations clexo replaces

/compact → !clexo save

/compact re-summarises the entire conversation in place. On a long session it can take minutes — you sit and wait. !clexo save writes a compact snapshot to disk in milliseconds. You can /clear immediately and the next session auto-restores it.

The ! prefix matters: it runs clexo save as a bash command directly, bypassing the model entirely. Zero tokens consumed, no MCP round-trip, no AI cost — the fastest possible save. (You can also ask the agent to use the save MCP tool; that works but costs model tokens.)

claude --resume → clexo load

claude --resume rehydrates the full saved conversation back into context — every message, every tool call, every file read, up to the model's context window (200K on Sonnet, 1M on Opus). On a long session that's a slow rehydrate and your full context budget consumed before the first new turn. clexo load restores the saved snapshot (summary + recent exchanges + key file refs) — typically a few thousand tokens. Same continuity, a fraction of the context.

/clear → /clear (after !clexo save)

/clear is normally irreversible. After !clexo save, it isn't: the SessionStart hook reads the pending snapshot when the next session starts and injects it as additional context. You keep summary + memory; you only lose the verbose raw history.

---

🧰 What it does

• Search every Claude Code and Codex conversation you've ever had (FTS5)
• save the current session into a compact snapshot, load it later — context survives /clear and crosses between Claude and Codex
• pick raw exchanges (including bash output and file reads) from any past session
• tag sessions with friendly names — clexo resume my-auth-fix jumps straight back into claude --resume
• Zero daemon — self-indexing via byte-offset tracking; one optional SessionEnd hook keeps the index fresh

---

⚙️ Manual install

clexo install does the Claude Code wiring for you. To do it by hand instead:

# 1. Install the package (isolated)
pipx install .            # from a checkout — or: pip install .

# 2. Register the MCP server with Claude Code
claude mcp add --scope user clexo clexo serve

# 3. (Recommended) install the hooks — enables auto-restore after /clear
clexo install-hooks
#    or merge the hooks block from settings.json.example into
#    ~/.claude/settings.json manually

Verify the MCP server with claude mcp list — you should see clexo: clexo serve ✓ Connected.

Upgrading

pipx install --force git+https://github.com/sankrant/clexo   # or: pipx upgrade clexo
clexo install                                                # re-points hooks + MCP if needed

Upgrading from an older git-clone install? Same two commands — clexo install re-points the old server.py-based hooks and MCP registration to the clexo command (backing up settings.json first) and removes the stale ~/.local/bin/clexo wrapper symlink.

---

💻 CLI

clexo stats                          Show usage stats
clexo sync                           Index new messages now
clexo search                  Search chat history
clexo save [sid|tag]                 Snapshot the current (or given) session
clexo saved [--short]                List saved snapshots, newest first, with the
                                     id fragment to reload each

clexo tag  [--force] [sid]     Tag the current (or given) session
clexo tags [--short|--keywords]      List tags, newest first (--short: name+date)
clexo untag                    Remove a tag
clexo load                 Set pending snapshot and launch a fresh claude
                                     (SessionStart hook injects the snapshot)
clexo resume               Exec 'claude --resume ' — reopens the
                                     original session, full history (no snapshot)
clexo resume                         (no args) Interactive picker over recent
                                     sessions; choose resume / load mode
clexo show                 Print the saved snapshot to stdout (inspect only)

clexo install                        Wire MCP server + hooks into Claude Code
                                     (re-runnable; re-points an older install)
clexo install-hooks                  Wire just the SessionStart + SessionEnd hooks
                                     (idempotent; backs up settings.json first)
clexo serve                          Run the MCP server (Claude Code invokes this)

load vs resume: load is the clexo path — fresh session, compact snapshot, cheap context. resume is a friendly-name wrapper around claude --resume — same session, full rehydrate, no clexo summarization.

All commands work from anywhere — !clexo tag my-fix inside a Claude session tags that session.

---

🔌 MCP tools

When clexo is registered as an MCP server, Claude can invoke these directly. You usually don't call them manually — just say "search my history for X", "load my last session", "tag this as auth-fix".

| Tool | What it does | |------|--------------| | search | FTS search across all sessions (filters: project_filter, source_filter='claude'\|'codex', pwd=true to scope to the current directory). sort='time' displays results oldest-first. Empty query = list recent. | | load | Load a session's snapshot (summary + recent exchanges) into context. Accepts UUID or tag. | | save | Snapshot the current session for restore on the next start. | | pick | Drill into a session's raw exchanges (incl. tool output). FTS-anchored; supports before/after scroll. Accepts UUID or tag. | | tag | Assign a friendly name to a session. Collisions return a "exists, pass replace=True or pick a new name" prompt. | | tags | List all tags (newest first) with each session's summary and opening/closing lines. short=True for just name+date; keywords=True to add TF-IDF keywords. | | untag | Remove a tag mapping. | | get_stats | Usage counters. |

---

🛠️ How it works

• Indexing — SQLite FTS5 (porter tokenizer). Byte-offset tracking per JSONL file means syncs are O(new bytes), not O(file size). New messages are picked up on the next search; the optional SessionEnd hook runs --sync in the background.
• Source files —
• Claude Code: ~/.claude/projects/**/*.jsonl (user/assistant messages; ai-title, custom-title, last-prompt records)
• Codex: ~/.codex/sessions/**/*.jsonl (event_msg, response_item)
• Snapshots — save writes ~/.clexo/chain-.md containing the summary, key file refs, and the most recent N tokens of exchanges. The SessionStart hook reads the pending snapshot, packs it under Claude Code's 10K hook context cap, and injects it as additionalContext.
• Tags — small tags table mapping tag → session_id. One session can have many tags; tag names are [a-z0-9_-], normalized to lowercase, and can't look like a UUID. Wherever a UUID is accepted (load, pick, save, resume), a tag works too.
• Keywords in tags listing — TF-IDF over each session's messages: user text weighted 3×, raw count threshold 2 (filters typos/one-offs), IDF computed against the full corpus and cached across the listing.

---

Configuration

~/.clexo/config.json (created on first use):

{
  "refresh_tokens_min": 4000,
  "refresh_tokens_max": 8000
}

| Key | Default | Description | |-----|---------|-------------| | refresh_tokens_min | 4000 | Minimum token budget for save's exchange window | | refresh_tokens_max | 8000 | Maximum token budget (cap) | | debug | false | If true, write hook + sync diagnostics to ~/.clexo/hook.log |

Tokens are approximated at 4 chars/token.

---

Tests

pip install pytest
pytest tests/

---

License

MIT — see [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sankrant
• Source: sankrant/clexo
• License: MIT

Install and usage instructions live in the source repository linked above.