clexo

clexo

Memória de sessão e contexto entre IAs para Claude Code e Codex
Claude Code esquece. clexo lembra.

Por quê • Início rápido • vs /compact /clear /resume • CLI • MCP • Como funciona

---

Dentro de uma sessão do Claude Code, digite !clexo save. Depois, /clear. A próxima sessão restaura automaticamente o snapshot — resumo + memória preservados, contexto bruto limpo. Sem espera de /compact. Sem claude --resume recarregando todo o histórico. Sem perda de /clear.

---

✨ Por quê

Se você vive no Claude Code ou no Codex, três operações de contexto são dolorosas. clexo substitui todas as três.

	A dor	Substituição do clexo
🐢	/compact — 1-3 minutos em sessões longas, bloqueia você durante a sessão	!clexo save — snapshot em ~80 ms, depois /clear e continue
💸	claude --resume <id> — recarrega todo o histórico no contexto	clexo load <tag> — restaura apenas o snapshot compacto
🪦	/clear — irreversível, perde tudo	/clear após !clexo save — restaurado automaticamente na próxima sessão

Mais uma lacuna estrutural que nada mais fecha: Codex não vê o histórico do Claude; Claude não vê o do Codex. clexo indexa ambos em um único arquivo — carregue uma sessão do Codex no Claude, ou vice-versa.

Zero daemon. Sem chave de API. Auto-indexação sob demanda. Suas sessões de IA se tornam uma meta-memória pesquisável em todas as conversas anteriores.

---

🚀 Início rápido

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

Dois passos: pipx instala o comando clexo em um ambiente isolado (sem poluir o Python do sistema, e sem "python3 muito antigo" — pipx escolhe um interpretador adequado); clexo install então o conecta ao Claude Code. Ambos são idempotentes e seguros para reexecutar.

Sem pipx? Adicione com brew install pipx (macOS) ou python3 -m pip install --user pipx. Prefere uv? uv tool install git+https://github.com/sankrant/clexo. Trabalhando a partir de um checkout local? git clone … && cd clexo && ./install.sh executa os mesmos dois passos.

O que a instalação faz

Nada escondido — dois passos, cada um com uma função:

Passo	O que faz	O que altera
pipx install …	venv isolado com clexo + sua única dependência (mcp); coloca o comando clexo no PATH. Não altera nada no Claude Code.	~/.local/bin/clexo
clexo install	Registra o servidor MCP e adiciona dois hooks. Idempotente; faz backup de settings.json primeiro; redireciona uma instalação mais antiga.	~/.claude.json (MCP), ~/.claude/settings.json (hooks)

Os dois hooks que clexo install adiciona ao ~/.claude/settings.json:

• SessionStart → clexo session-start — restaura um snapshot pendente após /clear (o comportamento de restauração automática)
• SessionEnd → clexo sync — indexa a sessão recém-terminada em segundo plano

Ele registra um servidor MCP: claude mcp add --scope user clexo clexo serve. Atualizando de uma instalação mais antiga? clexo install redireciona hooks/MCP obsoletos baseados em server.py para o comando clexo e remove o symlink antigo ~/.local/bin/clexo.

Os dados do próprio clexo — o índice de busca, o arquivo de transcrições e os snapshots — ficam em ~/.clexo/, criado no primeiro uso. Sem daemon, sem chave de API, nada é enviado a lugar algum. (Detalhes dos hooks: docs/hooks.md.)

Para remover o clexo: claude mcp remove --scope user clexo, exclua os blocos clexo SessionStart/SessionEnd de ~/.claude/settings.json, depois pipx uninstall clexo (e opcionalmente rm -rf ~/.clexo para descartar o índice/arquivo).

Experimente

# 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

---

🔁 As três operações do Claude Code que o clexo substitui

/compact → !clexo save

/compact re-resume toda a conversa no lugar. Em uma sessão longa, pode levar minutos — você fica esperando. !clexo save grava um snapshot compacto em disco em milissegundos. Você pode /clear imediatamente e a próxima sessão o restaura automaticamente.

O prefixo ! importa: ele executa clexo save como um comando bash diretamente, ignorando o modelo por completo. Zero tokens consumidos, sem ida e volta MCP, sem custo de IA — o salvamento mais rápido possível. (Você também pode pedir ao agente para usar a ferramenta MCP save; isso funciona, mas custa tokens do modelo.)

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

claude --resume reidrata a conversa salva completa de volta ao contexto — cada mensagem, cada chamada de ferramenta, cada leitura de arquivo, até o limite da janela de contexto do modelo (200K no Sonnet, 1M no Opus). Em uma sessão longa, isso é uma reidratação lenta e seu orçamento de contexto inteiro é consumido antes do primeiro novo turno. clexo load restaura o snapshot salvo (resumo + trocas recentes + referências de arquivos-chave) — tipicamente alguns milhares de tokens. Mesma continuidade, uma fração do contexto.

/clear → /clear (após !clexo save)

/clear normalmente é irreversível. Após !clexo save, não é: o hook SessionStart lê o snapshot pendente quando a próxima sessão começa e o injeta como contexto adicional. Você mantém resumo + memória; você só perde o histórico bruto verboso.

---

🧰 O que faz

• Busque em todas as conversas do Claude Code e Codex que você já teve (FTS5)
• save a sessão atual em um snapshot compacto, load depois — o contexto sobrevive a /clear e cruza entre Claude e Codex
• pick trocas brutas (incluindo saída de bash e leituras de arquivo) de qualquer sessão passada
• tag sessões com nomes amigáveis — clexo resume my-auth-fix volta direto para claude --resume <uuid>
• Zero daemon — auto-indexação via rastreamento de deslocamento de bytes; um hook opcional SessionEnd mantém o índice atualizado

---

⚙️ Instalação manual

clexo install faz a conexão com o Claude Code para você. Para fazer manualmente:

# 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

Verifique o servidor MCP com claude mcp list — você deve ver clexo: clexo serve ✓ Connected.

Atualizando

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

Atualizando de uma instalação antiga via git clone? Os mesmos dois comandos — clexo install redireciona os hooks antigos baseados em server.py e o registro MCP para o comando clexo (fazendo backup de settings.json primeiro) e remove o symlink wrapper 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 é o caminho do clexo — sessão nova, snapshot compacto, contexto barato. resume é um wrapper de nome amigável em torno de claude --resume <uuid> — mesma sessão, reidratação completa, sem sumarização do clexo.

Todos os comandos funcionam de qualquer lugar — !clexo tag my-fix dentro de uma sessão do Claude marca essa sessão.

---

🔌 Ferramentas MCP

Quando o clexo está registrado como servidor MCP, o Claude pode invocá-las diretamente. Você normalmente não as chama manualmente — apenas diga "busque no meu histórico por X", "carregue minha última sessão", "marque isso como auth-fix".

Ferramenta	O que faz
search	Busca FTS em todas as sessões (filtros: project_filter, source_filter='claude'|'codex', pwd=true para limitar ao diretório atual). sort='time' exibe resultados do mais antigo para o mais recente. Consulta vazia = lista as recentes.
load	Carrega o snapshot de uma sessão (resumo + trocas recentes) no contexto. Aceita UUID ou tag.
save	Cria snapshot da sessão atual para restauração no próximo início.
pick	Aprofunda nas trocas brutas de uma sessão (incluindo saída de ferramentas). Ancorado em FTS; suporta rolagem before/after. Aceita UUID ou tag.
tag	Atribui um nome amigável a uma sessão. Colisões retornam um prompt "existe, passe replace=True ou escolha um novo nome".
tags	Lista todas as tags (mais recentes primeiro) com o resumo de cada sessão e linhas de abertura/fechamento. short=True para apenas nome+data; keywords=True para adicionar palavras-chave TF-IDF.
untag	Remove um mapeamento de tag.
get_stats	Contadores de uso.

---

🛠️ Como funciona

• Indexação — SQLite FTS5 (tokenizador porter). Rastreamento de deslocamento de bytes por arquivo JSONL significa que as sincronizações são O(novos bytes), não O(tamanho do arquivo). Novas mensagens são captadas na próxima busca; o hook opcional SessionEnd executa --sync em segundo plano.
• Arquivos de origem —
  • Claude Code: ~/.claude/projects/**/*.jsonl (mensagens user/assistant; registros ai-title, custom-title, last-prompt)
  • Codex: ~/.codex/sessions/**/*.jsonl (event_msg, response_item)
• Snapshots — save grava ~/.clexo/chain-<sid>.md contendo o resumo, referências de arquivos-chave e os N tokens mais recentes de trocas. O hook SessionStart lê o snapshot pendente, empacota-o sob o limite de contexto de hook de 10K do Claude Code e o injeta como additionalContext.
• Tags — pequena tabela tags mapeando tag → session_id. Uma sessão pode ter várias tags; nomes de tags são [a-z0-9_-], normalizados para minúsculas, e não podem parecer um UUID. Onde um UUID é aceito (load, pick, save, resume), uma tag também funciona.
• Palavras-chave na listagem tags — TF-IDF sobre as mensagens de cada sessão: texto do usuário ponderado 3×, limite de contagem bruta 2 (filtra erros de digitação/ocorrências únicas), IDF calculado contra o corpus completo e armazenado em cache na listagem.

---

Configuração

~/.clexo/config.json (criado no primeiro uso):

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

Chave	Padrão	Descrição
refresh_tokens_min	4000	Orçamento mínimo de tokens para a janela de trocas de save
refresh_tokens_max	8000	Orçamento máximo de tokens (limite)
debug	false	Se true, grava diagnósticos de hook + sincronização em ~/.clexo/hook.log

Tokens são aproximados em 4 caracteres/token.

---

Testes

pip install pytest
pytest tests/

---

Licença

MIT — veja LICENSE.