clexo

Ocho herramientas MCP (search, load, save, pick, tag, tags, untag, get_stats) sobre un índice local SQLite FTS5 de sesiones pasadas de Claude Code y Codex.

GitHub

Prueba este MCPPatrocinado

Documentación

clexo

Memoria de sesión y contexto entre AIs para Claude Code y Codex
Claude Code olvida. clexo recuerda.

Por qué • Inicio rápido • vs /compact /clear /resume • CLI • MCP • Cómo funciona

Dentro de una sesión de Claude Code, escribe !clexo save. Luego /clear. La siguiente sesión restaura automáticamente la instantánea — resumen + memoria preservados, contexto crudo limpiado. Sin espera de /compact. Sin claude --resume recargando el historial completo. Sin pérdida de /clear.

clexo save → /clear → auto-restored next session

✨ Por qué

Si vives en Claude Code o Codex, tres operaciones de contexto duelen. clexo reemplaza las tres.

	El dolor	El reemplazo de clexo
🐢	`/compact` — 1-3 minutos en sesiones largas, te bloquea en la sesión	`!clexo save` — instantánea de ~80 ms, luego `/clear` y continúa
💸	`claude --resume <id>` — recarga todo el historial en el contexto	`clexo load <tag>` — restaura solo la instantánea compacta
🪦	`/clear` — irreversible, pierde todo	`/clear` después de `!clexo save` — se restaura automáticamente en la siguiente sesión

Más una brecha estructural que nada más cierra: Codex no ve el historial de Claude; Claude no ve el de Codex. clexo indexa ambos en un solo archivo — carga una sesión de Codex en Claude, o viceversa.

Cero demonio. Sin clave de API. Auto-indexación bajo demanda. Tus sesiones de IA se convierten en una meta-memoria buscable en cada conversación anterior.

🚀 Inicio rápido

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

Dos pasos: pipx instala el comando clexo en un entorno aislado (sin contaminar el Python del sistema, y sin "python3 demasiado viejo" — pipx elige un intérprete adecuado); clexo install luego lo conecta a Claude Code. Ambos son idempotentes y seguros de re-ejecutar.

¿Sin pipx? Añádelo con brew install pipx (macOS) o python3 -m pip install --user pipx. ¿Prefieres uv? uv tool install git+https://github.com/sankrant/clexo. ¿Trabajando desde un checkout local? git clone … && cd clexo && ./install.sh ejecuta los mismos dos pasos.

Qué hace la instalación

Nada oculto — dos pasos, cada uno con un trabajo:

Paso	Qué hace	Qué toca
`pipx install …`	Venv aislado con clexo + su única dependencia (`mcp`); pone el comando `clexo` en el PATH. No toca nada en Claude Code.	`~/.local/bin/clexo`
`clexo install`	Registra el servidor MCP y añade dos hooks. Idempotente; respalda `settings.json` primero; re-apunta una instalación anterior.	`~/.claude.json` (MCP), `~/.claude/settings.json` (hooks)

Los dos hooks que clexo install añade a ~/.claude/settings.json:

SessionStart → clexo session-start — restaura una instantánea pendiente después de /clear (el comportamiento de auto-restauración)
SessionEnd → clexo sync — indexa la sesión recién terminada en segundo plano

Registra un servidor MCP: claude mcp add --scope user clexo clexo serve. ¿Actualizando desde una instalación anterior? clexo install re-apunta hooks/MCP obsoletos basados en server.py al comando clexo y elimina el antiguo enlace simbólico ~/.local/bin/clexo.

Los datos propios de clexo — el índice de búsqueda, el archivo de transcripciones y las instantáneas — viven en ~/.clexo/, creado en el primer uso. Sin demonio, sin clave de API, nada se envía a ningún lado. (Detalles de hooks: docs/hooks.md.)

Para eliminar clexo: claude mcp remove --scope user clexo, borra los bloques clexo SessionStart/SessionEnd de ~/.claude/settings.json, luego pipx uninstall clexo (y opcionalmente rm -rf ~/.clexo para eliminar el índice/archivo).

Pruébalo

# 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

🔁 Las tres operaciones de Claude Code que clexo reemplaza

`/compact` → `!clexo save`

/compact re-resume toda la conversación en el lugar. En una sesión larga puede tomar minutos — te sientas y esperas. !clexo save escribe una instantánea compacta al disco en milisegundos. Puedes /clear inmediatamente y la siguiente sesión la restaura automáticamente.

El prefijo ! importa: ejecuta clexo save como un comando bash directamente, evitando el modelo por completo. Cero tokens consumidos, sin ida y vuelta MCP, sin costo de IA — el guardado más rápido posible. (También puedes pedirle al agente que use la herramienta MCP save; eso funciona pero cuesta tokens del modelo.)

`claude --resume <uuid>` → `clexo load <tag>`

claude --resume rehidrata la conversación guardada completa de vuelta al contexto — cada mensaje, cada llamada de herramienta, cada lectura de archivo, hasta el límite de contexto del modelo (200K en Sonnet, 1M en Opus). En una sesión larga eso es una rehidratación lenta y tu presupuesto de contexto completo consumido antes del primer turno nuevo. clexo load restaura la instantánea guardada (resumen + intercambios recientes + referencias clave de archivos) — típicamente unos pocos miles de tokens. Misma continuidad, una fracción del contexto.

`/clear` → `/clear` (después de `!clexo save`)

/clear normalmente es irreversible. Después de !clexo save, no lo es: el hook SessionStart lee la instantánea pendiente cuando comienza la siguiente sesión y la inyecta como contexto adicional. Conservas resumen + memoria; solo pierdes el historial crudo verboso.

🧰 Qué hace

Busca en cada conversación de Claude Code y Codex que hayas tenido (FTS5)
save la sesión actual en una instantánea compacta, load más tarde — el contexto sobrevive a /clear y cruza entre Claude y Codex
pick intercambios crudos (incluyendo salida de bash y lecturas de archivos) de cualquier sesión pasada
tag sesiones con nombres amigables — clexo resume my-auth-fix salta directamente de vuelta a claude --resume <uuid>
Cero demonio — auto-indexación mediante seguimiento de desplazamiento de bytes; un hook opcional SessionEnd mantiene el índice fresco

⚙️ Instalación manual

clexo install hace la conexión de Claude Code por ti. Para hacerlo a mano en su lugar:

# 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

Verifica el servidor MCP con claude mcp list — deberías ver clexo: clexo serve ✓ Connected.

Actualización

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

¿Actualizando desde una instalación anterior de git-clone? Los mismos dos comandos — clexo install re-apunta los hooks antiguos basados en server.py y el registro MCP al comando clexo (respaldando settings.json primero) y elimina el enlace simbólico obsoleto ~/.local/bin/clexo.

💻 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 es la ruta de clexo — sesión fresca, instantánea compacta, contexto barato. resume es un envoltorio de nombre amigable alrededor de claude --resume <uuid> — misma sesión, rehidratación completa, sin resumen de clexo.

Todos los comandos funcionan desde cualquier lugar — !clexo tag my-fix dentro de una sesión de Claude etiqueta esa sesión.

🔌 Herramientas MCP

Cuando clexo está registrado como servidor MCP, Claude puede invocarlas directamente. Normalmente no las llamas manualmente — solo di "busca en mi historial X", "carga mi última sesión", "etiqueta esto como auth-fix".

Herramienta	Qué hace
`search`	Búsqueda FTS en todas las sesiones (filtros: `project_filter`, `source_filter='claude'\|'codex'`, `pwd=true` para limitar al directorio actual). `sort='time'` muestra resultados del más antiguo al más reciente. Consulta vacía = lista recientes.
`load`	Carga la instantánea de una sesión (resumen + intercambios recientes) al contexto. Acepta UUID o etiqueta.
`save`	Crea una instantánea de la sesión actual para restaurarla en el próximo inicio.
`pick`	Profundiza en los intercambios crudos de una sesión (incl. salida de herramientas). Anclado por FTS; soporta desplazamiento `before`/`after`. Acepta UUID o etiqueta.
`tag`	Asigna un nombre amigable a una sesión. Las colisiones devuelven un mensaje "existe, pasa `replace=True` o elige un nombre nuevo".
`tags`	Lista todas las etiquetas (más recientes primero) con el resumen de cada sesión y las líneas de apertura/cierre. `short=True` para solo nombre+fecha; `keywords=True` para añadir palabras clave TF-IDF.
`untag`	Elimina un mapeo de etiqueta.
`get_stats`	Contadores de uso.

🛠️ Cómo funciona

Indexación — SQLite FTS5 (tokenizador porter). El seguimiento de desplazamiento de bytes por archivo JSONL significa que las sincronizaciones son O(bytes nuevos), no O(tamaño de archivo). Los mensajes nuevos se recogen en la siguiente búsqueda; el hook opcional SessionEnd ejecuta --sync en segundo plano.
Archivos fuente —
- Claude Code: ~/.claude/projects/**/*.jsonl (mensajes user/assistant; registros ai-title, custom-title, last-prompt)
- Codex: ~/.codex/sessions/**/*.jsonl (event_msg, response_item)
Instantáneas — save escribe ~/.clexo/chain-<sid>.md que contiene el resumen, referencias clave de archivos y los N tokens más recientes de intercambios. El hook SessionStart lee la instantánea pendiente, la empaqueta bajo el límite de contexto de hook de 10K de Claude Code y la inyecta como additionalContext.
Etiquetas — pequeña tabla tags que mapea tag → session_id. Una sesión puede tener muchas etiquetas; los nombres de etiqueta son [a-z0-9_-], normalizados a minúsculas y no pueden parecer un UUID. Dondequiera que se acepte un UUID (load, pick, save, resume), una etiqueta también funciona.
Palabras clave en el listado tags — TF-IDF sobre los mensajes de cada sesión: texto de usuario ponderado 3×, umbral de recuento crudo 2 (filtra errores tipográficos/una sola vez), IDF calculado contra el corpus completo y cacheado en el listado.

Configuración

~/.clexo/config.json (creado en el primer uso):

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

Clave	Predeterminado	Descripción
`refresh_tokens_min`	4000	Presupuesto mínimo de tokens para la ventana de intercambios de `save`
`refresh_tokens_max`	8000	Presupuesto máximo de tokens (límite)
`debug`	`false`	Si `true`, escribe diagnósticos de hook + sincronización en `~/.clexo/hook.log`

Los tokens se aproximan a 4 caracteres/token.

Pruebas

pip install pytest
pytest tests/

Licencia

MIT — ver LICENSE.

clexo

Documentación

clexo

✨ Por qué

🚀 Inicio rápido

Qué hace la instalación

Pruébalo

🔁 Las tres operaciones de Claude Code que clexo reemplaza

/compact → !clexo save

claude --resume <uuid> → clexo load <tag>

/clear → /clear (después de !clexo save)

🧰 Qué hace

⚙️ Instalación manual

Actualización

💻 CLI

🔌 Herramientas MCP

🛠️ Cómo funciona

Configuración

Pruebas

Licencia

`/compact` → `!clexo save`

`claude --resume <uuid>` → `clexo load <tag>`

`/clear` → `/clear` (después de `!clexo save`)