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```bash
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.)
**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```bash
# 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)
savethe current session into a compact snapshot,loadit later — context survives/clearand crosses between Claude and Codexpickraw exchanges (including bash output and file reads) from any past sessiontagsessions with friendly names —clexo resume my-auth-fixjumps straight back intoclaude --resume- Zero daemon — self-indexing via byte-offset tracking; one optional
SessionEndhook keeps the index fresh
⚙️ Manual install
clexo install does the Claude Code wiring for you. To do it by hand instead:```bash
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```bash
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 <query> 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 <name> [--force] [sid] Tag the current (or given) session
clexo tags [--short|--keywords] List tags, newest first (--short: name+date)
clexo untag <name> Remove a tag
clexo load <name|sid> Set pending snapshot and launch a fresh claude
(SessionStart hook injects the snapshot)
clexo resume <name|sid> Exec 'claude --resume <uuid>' — reopens the
original session, full history (no snapshot)
clexo resume (no args) Interactive picker over recent
sessions; choose resume / load mode
clexo show <name|sid> 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):```json
{
"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```bash
pip install pytest
pytest tests/
```
License
MIT — see LICENSE.
