remem

remem: Memória local-first para Claude Code e OpenAI Codex

Pare de reexplicar seu projeto a cada nova sessão de agente de codificação.

Idioma: Inglês | 简体中文

remem captura, destila, pesquisa e injeta automaticamente memória de engenharia entre sessões do Claude Code e OpenAI Codex CLI. Decisões, justificativas de correção de bugs, padrões de projeto e preferências permanecem disponíveis por meio de hooks, MCP, CLI e uma API REST localhost.

Uma nova sessão do Claude Code relembra a causa raiz anterior, o commit e o TODO aberto com citações de memória e sem reexplicações.

O que o remem oferece

• Captura automática de sessão e destilação LLM em segundo plano.
• Recuperação com escopo de projeto entre Claude Code e Codex usando um único armazenamento local.
• Decisões pesquisáveis, correções de bugs, notas de arquitetura, preferências e evidências brutas de sessão.
• Atribuição de fonte, rótulos de desatualização, supressão, filas de revisão e auditorias de injeção.
• SQLite com criptografia SQLCipher por padrão para novas instalações.
• Acesso MCP, CLI e REST localhost autenticado a partir de um único runtime Rust.

O remem prioriza a qualidade da memória. A captura automática é o caminho principal; chamadas manuais de save_memory complementam quando uma decisão precisa ser registrada imediatamente.

Instale em cinco minutos

Homebrew

brew install majiayu000/tap/remem
"$(brew --prefix remem)/bin/remem" install --target codex

Use --target claude para Claude Code. --target all configura todos os hosts conhecidos, incluindo Cursor onde seu renderizador v1 é suportado.

Instalador autônomo

curl -fsSL https://raw.githubusercontent.com/majiayu000/remem/main/install.sh | env REMEM_NO_CONFIG=1 sh
~/.local/bin/remem install --target codex

npm ou Cargo

npm install -g @remem-ai/remem
# or
cargo install remem-ai --bin remem

remem install --target codex

GitHub Releases: binários pré-compilados para macOS e Linux em x64/arm64, com checksums publicados. Use um único executável canônico remem em PATH; remem doctor avisa quando hooks e terminais resolvem cópias diferentes.

Para atualizações específicas de canal, limites de plataforma, desvios de PATH e notas de instalação manual, leia o guia de instalação e atualização. O guia de documentação mais amplo vincula material de plugin e operacional.

Verifique a instalação

Reinicie o agente de codificação selecionado e execute:

remem doctor
remem status
remem search "last decision"

Uma instalação saudável do Claude Code ou Codex injeta memória relevante do projeto no SessionStart e enfileira destilação durável de sessão no Stop. O Codex também usa UserPromptSubmit para capturar cada prompt e exibir candidatos de memória opcionais e compactos. remem doctor verifica o esquema, chave de criptografia, banco de dados, hooks, registro MCP, worker e desvios comuns de caminho de instalação.

Contribuidores do repositório podem verificar a supressão duplicada do SessionStart com o fixture de fumaça executável isolado.

Para uma visão focada e somente leitura da verdade atual da memória:

remem doctor truth --cwd .

Suporte a hosts

Capacidade	Claude Code	Codex CLI	Cursor v1
Ferramentas de memória MCP	Sim	Sim	Sim no macOS/Linux
Injeção no SessionStart	Sim	Sim	Não suportado
Memória automática de sessão	Sim	Sim, baseada em Stop e baixo ruído	Não habilitada pelo instalador v1
Captura de eventos de ferramenta	Hooks instalados	Sem hook Bash de alta frequência por padrão	Comando runtime existe; sem hook instalado
Aplicação de regras de comando compiladas	Warn/block opcional no Bash	Não suportado	Não suportado
Windows	Suportado	Suportado	Não suportado

O instalador v1 do Cursor registra apenas MCP. Os comandos runtime verificados observe e summarize existem, mas remem install --target cursor não instala hooks de captura automática ou injeção no SessionStart.

O repositório também inclui um wrapper de plugin para Codex. Veja plugins/remem/README.md para instruções de runtime local do plugin e ativação explícita de hooks.

Por que usar o remem junto com a memória integrada

Arquivos integrados de MEMORY.md, CLAUDE.md e instruções de agente são ideais para um pequeno conjunto de fatos estáveis que devem estar sempre visíveis. O remem cobre a história de engenharia que é grande demais, dinâmica ou pesada em evidências para ser mantida manualmente.

Necessidade	Arquivos integrados	remem
Regras estáveis do projeto	Excelente	Suportado
Contexto em evolução	Instruções manuscritas; memória automática do Claude Code também escreve notas	Captura de sessão orientada por hooks e destilação em segundo plano
Pesquisar justificativas antigas	Limitado pelo texto carregado	Pesquisa curada e bruta
Tratamento de branch, tempo e desatualização	Manual	Integrado
Proveniência e auditoria de injeção	Histórico Git	Auditoria baseada em banco de dados
Revisão, supressão e governança de ciclo de vida	Edições manuais	Comandos de primeira classe

A memória automática do Claude Code já salva notas automaticamente. A distinção está na superfície da memória e em suas evidências, recuperação e controles de ciclo de vida, em vez de apenas persistência automática.

Use ambos. Mantenha regras concisas em arquivos nativos e deixe o remem reter a cauda longa de decisões, falhas, evidências e estado mutável do projeto.

A comparação mais ampla do ecossistema está no levantamento de ferramentas de memória datado.

Como funciona

Claude Code / Codex hooks
          |
          v
append-only captured_events ledger
          |
          v
coalesced background extraction and session rollup
          |
          v
governed candidates -> curated memories + workstreams + raw archive
          |
          v
FTS, entity, temporal, vector, graph, and optional local rerank retrieval
          |
          v
budgeted, source-attributed SessionStart context

Os hooks retornam rapidamente após captura durável ou enfileiramento. Workers em segundo plano realizam extração, governança de candidatos, compressão, enriquecimento de recuperação e limpeza de ciclo de vida. MCP, CLI, REST e SessionStart compartilham o mesmo armazenamento local e modelo de governança, mas aplicam políticas de elegibilidade específicas da superfície. A pesquisa explícita é uma superfície de inspeção e recuperação, portanto pode retornar memórias rotuladas como legacy_unverified; SessionStart padrão e CurrentTruth excluem essas linhas e registram o motivo.

A memória gerada é tratada como não confiável até passar por verificações de suporte à fonte, segredos, padrões de instrução, escopo e ciclo de vida. Conteúdo inseguro é descartado ou roteado para revisão com um motivo diagnosticável.

Para propriedade de módulos e fluxo de dados atual, leia docs/ARCHITECTURE.md.

A ferramenta MCP experimental context_bundle expõe o compilador versionado e com orçamento a chamadores explícitos. O comando experimental remem context-plan imprime um plano de recuperação específico da solicitação. Essas interfaces opt-in são rastreadas pelos contratos Context Bundle e retrieval-router.

A integração padrão do Codex permanece de baixo ruído: SessionStart fornece contexto estável, UserPromptSubmit fornece um índice de candidatos compacto e Stop enfileira sumarização em segundo plano. Os candidatos de prompt contêm IDs, títulos, estado, motivo da recuperação, custo estimado de leitura e uma dica de consulta de detalhes, mas nenhum corpo de memória. São leads opcionais que o Codex pode ignorar, abrir ou pesquisar além. O primeiro prompt também pode receber até duas âncoras de continuidade para que um prompt como continue não dependa de sobreposição lexical. O RRF híbrido existente classifica candidatos de memória; nenhum limite final de confiança decide relevância para o modelo. A extração automática pede títulos de candidatos curtos e específicos sem prefixo redundante de nome de projeto; títulos armazenados existentes permanecem intactos.

Para sua própria barra lateral do Codex, uma convenção de renomeação opcional é MMDD｜TYPE｜Topic, como 0903｜FIX｜FTS5 tokenizer mismatch. Se você usar um fluxo de trabalho de renomeação separado suportado pelo host, visualize os nomes propostos antes de aplicar em lote. Isso é apenas organização da barra lateral do host: o Remem não renomeia conversas do host nem importa esses nomes como substituições de intenção. Os campos estruturados de sessão/workstream do Remem permanecem autoritativos, e um título do host não altera tipos de memória ou identidade de workstream. Veja o contrato de intenção de sessão e a épica de implementação #1065.

Correções de rótulos de sessão/workstream usam POST /api/v1/session-intent/preview autenticado, depois confirmação explícita por meio de POST /api/v1/session-intent/apply. Mantenha cada opção sensível ou prefixo Bearer e seu valor na mesma linha lógica no tópico e motivo propostos. Por exemplo, curl --oauth2-bearer\nexample-value é rejeitado com HTTP 400 session_intent_cross_line_sensitive_argument; coloque a opção e o valor em uma linha antes de tentar novamente. A rejeição não cria token de visualização nem entrada de auditoria e não altera rótulos. Valores sensíveis na mesma linha são redigidos antes da visualização.

Fluxos de trabalho do dia a dia

Recuperar e inspecionar

remem search "database encryption"
remem search "deployment decision" --branch main --explain
remem show <memory-id>
remem why <memory-id>
remem current <state-key>

remem search mantém o terminal limpo: diagnósticos [INFO] [search-perf] por consulta são gravados no arquivo de log, não no stderr, em uso normal. Defina REMEM_DEBUG=1 para espelhá-los no stderr durante a depuração.

Aliases de projeto para worktrees Git

Quando um worktree tem sua própria chave de projeto, visualize um alias para o checkout principal, depois aplique após verificar os caminhos e a prova Git:

remem project alias add /path/to/worktree --canonical /path/to/main \
  --actor you --reason "same project"
remem project alias add /path/to/worktree --canonical /path/to/main \
  --actor you --reason "same project" --apply
remem project alias list
remem search "decision" --project /path/to/main
remem project alias revoke /path/to/worktree \
  --actor you --reason "worktree retired" --apply

O checkout principal já deve ter uma linha de projeto da captura normal do remem. O alias mantém linhas históricas em seus caminhos registrados enquanto pesquisas de projeto CLI e MCP incluem as memórias do worktree. add e revoke visualizam sem gravações no banco de dados, a menos que --apply esteja presente. A revogação remove o worktree do escopo de pesquisa do projeto principal; list relata aliases ativos com o ator e o motivo de sua ativação mais recente.

Agentes podem usar MCP search para resultados compactos e depois get_observations para detalhes selecionados. Use recuperação bruta apenas quando a memória curada não encontrar evidências exatas de transcrição:

remem raw search "exact phrase" --since 2026-06-01 --json

Liste sessões completas vinculadas ao host antes de ler uma transcrição exata:

remem raw sessions --latest 20 --json
remem raw messages --host codex-cli --source-root local \
  --project "/path/to/project" --session-id SESSION_ID --json
remem ingest-sessions --root codex-cli:archive=/path/to/sessions --json

As varreduras padrão de transcrição usam $CLAUDE_CONFIG_DIR/projects e $CODEX_HOME/sessions, com fallback para ~/.claude e ~/.codex. Uma substituição explicitamente vazia é um erro. Diretórios de substituição explícitos devem existir e ser legíveis; apenas padrões inferidos ausentes são ignorados. Diretórios --root explícitos permanecem suportados; diretórios subagents descendentes são excluídos das varreduras em lote. Os modos de sessão do Codex usam evidências nativas de fonte: IDE é interativo, exec explícito é não assistido mesmo com um originador Desktop, e evidências de subagente têm precedência. Esses são rótulos de fonte, não prova de quem iniciou uma execução. Modos salvos existentes são atualizados uma vez após verificar a evidência de classificação original; conflitos genuínos de proveniência ainda falham no lote. Isso adiciona o esquema v093: mantenha um backup do banco de dados antes de atualizar; binários mais antigos não podem abrir o esquema atualizado. Identidades e cursores brutos de mensagens são preservados. Copie host, source_root, project e session_id sem alterações de um resumo raw sessions para raw messages. Scripts existentes devem adicionar o seletor --host obrigatório e substituir --root LABEL=PATH por --root HOST:LABEL=PATH; o mesmo formato de raiz se aplica a raw reconcile. O envelope JSON relata excluded_legacy_rows, excluded_legacy_sessions, e excluded_legacy_identities quando algumas linhas de arquivo não conseguem entrar no contrato de sessão vinculado ao host. Cada sessão listada também carrega campos aditivos anuláveis mmdd, session_intent, session_topic, display_label e session_intent_source. mmdd é derivado da época de criação da sessão em Ásia/Xangai; o rótulo completo {MMDD}｜{INTENT}｜{topic} está presente apenas quando tanto a intenção quanto o tópico são conhecidos. Resumos de parada podem preencher esses campos com fonte summary; valores desconhecidos, vazios, longos demais ou editados se abstêm em vez de bloquear o restante do resumo. Consolidações automáticas de parada preservam substituições manuais de rótulos, incluindo limpezas explícitas, em turnos posteriores. A listagem ainda retorna sessões saudáveis; --latest N preenche esse limite apenas com sessões saudáveis e não permite que linhas não resolvidas ocupem esses slots. Use as identidades ignoradas (source_root, project, session_id e host quando conhecidas) para inspecionar ou reparar essas linhas. raw messages exato para um seletor ignorado permanece com falha fechada. Não reingira uma linha ignorada a menos que a ingestão possa realmente reivindicá-la — muitas linhas legadas não têm proveniência confiável de host. HOST é claude-code ou codex-cli, e LABEL se torna o source_root persistido. Evidência de snapshot de cursor requer uma integração remem summarize --host cursor Stop configurada e verificada manualmente; ingestão e reconciliação de --root do sistema de arquivos rejeitam cursor explicitamente.

Revisar e governar

remem review list
remem review approve <candidate-id>
remem memory suppress memory:<id> --reason "no longer relevant"
remem govern --action stale --dry-run --json <id>

Comandos de governança mutáveis expõem visualizações, confirmações explícitas ou limites de revisão de acordo com seu risco. Execute remem <command> --help para o contrato atual em vez de depender de um inventário de comandos copiado.

As ferramentas MCP compartilham esse armazenamento com contratos de fio mais rígidos. O contrato MCP canônico é GH981, incluindo a mutação #1061 e o limite de escopo:

• save_memory: passe host quando o host chamador for conhecido. Um host omitido é registrado como unknown, nunca inferido como codex-cli.
• govern_memory: execute primeiro uma simulação para visualizar IDs e versões atuais dessa transação de governança. Mutações sem simulação exigem expected_versions para cada ID, confirm_destructive=true e um motivo explícito.
• recall_user_context: forneça project ou cwd. O servidor não infere esse escopo a partir do diretório de trabalho do próprio processo.

O aplicativo Remem local mostra rótulos de sessão/workstream ou abstenção explícita. As sessões podem ser filtradas por intenção e data de criação em Ásia/Xangai. Operadores podem corrigir rótulos em lotes com uma visualização Antes/Depois, confirmação explícita e uma auditoria; a identidade do workstream e os títulos de conversa do host permanecem estáveis.

Configurar memória de IA e recuperação

remem config show
remem model current
remem model use balanced --dry-run
remem embedding status
remem embedding download --model multilingual-e5-small
remem embedding backfill --limit 1000

O modo de incorporação auto permanece local, a menos que uma chave de API específica do remem seja selecionada. O modelo local verificado é opcional; o fallback de hash de recurso rotulado permanece disponível. O reranker local de segundo estágio também é opcional e desabilitado até ser configurado.

Use as rotas de configuração atuais, o contrato de incorporação local e a ajuda de remem config, remem embedding ou remem reranker para detalhes.

Compartilhar ou editar memória fora do banco de dados

remem sync-memory --cwd .
remem export --markdown --output ./remem-memory
remem export --pack .remem-pack

Espelhos Markdown são editáveis por humanos. Pacotes de memória de projeto são exportações determinísticas, compatíveis com git, com importação ciente de proveniência e comportamento de quarentena. Consulte o guia de uso de memória e o contrato de pacote de memória de projeto.

Evidências e benchmarks

A suíte pública verificada separa evidências de capacidade do sistema de memória de evidências de resultados de agentes de codificação. Verifique-a localmente com:

cargo run -- bench verify --root eval/public --json-out /tmp/remem-bench-verify.json

A verificação resolve claims/registry.json ao lado do pai de --root, então um pacote externo mantém public/ e claims/ como irmãos e é independente do diretório de trabalho do chamador.

Snapshots públicos adversariais de SQLite são limitados a 64 MiB e devem ser imagens canônicas VACUUM; alvos de artefatos consumidos pelo verificador também devem resolver dentro da raiz pública declarada.

O relatório público atual não suporta alegações públicas de benchmark e é deliberadamente rotulado como directional_only_no_public_claim. A linha de base histórica isolada de codificação é evidência útil de engenharia, mas sua condição de memória pré-carregada não é comparável ao caminho atual de recuperação SessionStart.

Comandos de reprodução, esquemas de artefatos, limites de alegações e portões atuais vivem em:

• eval/README.md
• eval/public/README.md
• eval/coding-bench/README.md

As alegações do README excluem intencionalmente métricas locais não seladas que não têm relatório verificado.

Segurança e privacidade

• Instalações novas criam um banco de dados criptografado com SQLCipher e um arquivo de chave privada.
• O diretório de dados e a chave usam permissões restritivas por usuário.
• A API REST vincula-se a 127.0.0.1 e exige um token de portador.
• Visualizações de eventos capturados por hooks são editadas antes do armazenamento durável.
• Listagens de workstreams MCP e CLI projetam texto editado: atribuições semelhantes a credenciais, segredos curtos inline e opções de comando sensíveis são substituídos por [REDACTED] nos campos retornados (e no envelope --json da CLI project), enquanto caminhos de projeto comuns do sistema de arquivos permanecem legíveis. Linhas de workstream armazenadas mantêm seus valores canônicos para correspondência e verificações de escopo, então a saída consultada pode diferir do banco de dados quando segredos estavam presentes.
• Candidatos de memória e conteúdo injetado passam por defesas contra segredos e envenenamento.
• remem doctor relata criptografia, resíduo de texto simples, esquema e falhas de auditoria sem imprimir cargas de memória.

Leia SECURITY.md para política de relatórios e segurança. Contratos operacionais para ajuste de SQLite e defesa contra envenenamento de memória são mantidos fora da página inicial.

API REST

remem api --port 5567
TOKEN=$(cat ~/.remem/.api-token)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/health
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:5567/api/v1/capabilities

Os clientes devem detectar recursos por meio de /api/v1/capabilities. O contrato de endpoint e compatibilidade atual é mantido em docs/specs/SPEC-web-api.md.

Documentação

Use docs/README.md como página de salto para instalação, configuração, ciclo de vida da memória, recuperação, governança, API, plugin, operações, arquitetura e material de benchmark.

Os destinos mais comuns são:

• Arquitetura e fluxo de dados
• Guia de uso de memória
• Ciclo de vida da memória
• Plugin Codex
• Contrato da API REST
• Índice de especificações atual
• Changelog
• Contribuindo

Desinstalação

Visualize e remova hooks de host e registro MCP sem excluir memória:

remem uninstall --dry-run
remem uninstall

O banco de dados criptografado permanece no REMEM_DATA_DIR configurado. Faça backup antes de excluir manualmente esse diretório se a remoção de dados for pretendida. A exclusão comum de arquivos remove os dados locais do remem, mas não garante apagamento seguro de snapshots do sistema de arquivos, backups ou mídia de armazenamento subjacente.

Licença

MIT