clexo MCP server
Commit Nov 9, 2026Provides session memory and cross-AI context for Claude Code and Codex by allowing users to search, save, tag, and load past AI conversations.
Also known as sankrant/clexo
- Stars
- 1
- Tools
- 8
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 9, 2026
- License
- MIT
What is clexo MCP?
clexo provides session memory and cross-AI context for Claude Code and Codex by allowing users to search, save, tag, and load past AI conversations. It exposes 8 tools, such as search, load, save.
Summary generated from the project's README
About clexo MCP server
clexo provides a persistent memory layer for developers using Claude Code and Codex. It allows you to bridge the gap between different AI tools by indexing conversation histories into a single searchable archive. This means you can load a Codex session into Claude or vice versa, ensuring context is never lost when switching environments.
The system operates locally without a daemon or the need for API keys, storing all data in your home directory. It uses an MCP server to provide tools like search, tag, and load directly to your AI client. By using specific hooks, it can automatically restore a compact snapshot of your previous work after you use the clear command, saving you from the high token costs of reloading full histories.
Installation is handled via pipx or uv, and the tool integrates with Claude Code through a simple install command. It replaces slow manual operations with fast snapshots that preserve summaries and key file references while clearing out verbose raw context.
What you can do with it
- 1Restore context after clearing historyYou can save a session snapshot and then clear the current chat to start fresh without losing your progress.
- 2Search across multiple AI toolsA developer can perform a full-text search to find specific code snippets or discussions across both Claude and Codex sessions.
Written from the project's README. Every use case is checked against a quote from it.
clexo MCP tools 8
Detected from the READMEsearchloadsavepicktagtagsuntagget_stats
| search | — | |
| load | — | |
| save | — | |
| pick | — | |
| tag | — | |
| tags | — | |
| untag | — | |
| get_stats | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablesankrant/clexo is public and reachablegithub.com/sankrant/clexo ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-09github.com/sankrant/clexo ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model8 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubInside a Claude Code session, type
!clexo save. Then/clear. The next session auto-restores the snapshot — summary + memory preserved, raw context cleared. No/compactwait. Noclaude --resumereloading the full history. No/clearloss.
✨ 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 <id> — re-loads the entire history into context |
clexo load <tag> — 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 withbrew install pipx(macOS) orpython3 -m pip install --user pipx. Preferuv?uv tool install git+https://github.com/sankrant/clexo. Working from a local checkout?git clone … && cd clexo && ./install.shruns 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
# 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 <uuid> → clexo load <tag>
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 <uuid>- 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:
# 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 <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 <uuid> — 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
SessionEndhook runs--syncin the background. - Source files —
- Claude Code:
~/.claude/projects/**/*.jsonl(user/assistantmessages;ai-title,custom-title,last-promptrecords) - Codex:
~/.codex/sessions/**/*.jsonl(event_msg,response_item)
- Claude Code:
- Snapshots —
savewrites~/.clexo/chain-<sid>.mdcontaining the summary, key file refs, and the most recent N tokens of exchanges. TheSessionStarthook reads the pending snapshot, packs it under Claude Code's 10K hook context cap, and injects it asadditionalContext. - Tags — small
tagstable mappingtag → 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
tagslisting — 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.
clexo MCP questions
What tools does clexo MCP provide?
It exposes 8 tools, including search, load, save, pick, tag.
How does clexo help with Claude Code sessions?
It replaces slow operations like /compact with fast snapshots and allows you to restore context after using /clear.
Can I use my Claude history in Codex?
Yes, clexo indexes both Claude and Codex sessions into a single archive, allowing you to load a Codex session into Claude or vice versa.
Does clexo require an API key or a running daemon?
No, it operates with zero daemon and requires no API key.
Where is the clexo data stored?
All data, including the search index and transcript archive, is stored locally in the ~/.clexo/ directory.