# Clexo > Session memory and cross-AI context for Claude Code and Codex — search, save/load, pick, tag past sessions. MCP server + CLI. - **Type:** MCP server - **Install:** `agentstack add mcp-sankrant-clexo` - **Verified:** Pending review - **Seller:** [sankrant](https://agentstack.voostack.com/s/sankrant) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [sankrant](https://github.com/sankrant) - **Source:** https://github.com/sankrant/clexo ## Install ```sh agentstack add mcp-sankrant-clexo ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 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`](https://docs.astral.sh/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 ```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) - **`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: ```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 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): ```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](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](https://github.com/sankrant) - **Source:** [sankrant/clexo](https://github.com/sankrant/clexo) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-sankrant-clexo - Seller: https://agentstack.voostack.com/s/sankrant - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.