sessionmem

Servidor MCP local-first que concede a assistentes de codificação de IA memória de sessão persistente. 85,6% de redução de tokens, sem nuvem.

GitHub

Experimente este MCPPatrocinado

Documentação

sessionmem

85,6% menos tokens. Cada sessão já começa conhecendo seu código. Armazenado inteiramente na sua máquina.

New session. Claude starts fresh.

WITHOUT sessionmem:
  You explain the stack. The JWT bug from last week.
  The Stripe migration that's halfway done. The billing code to stay away from.
  Same questions. Different day.

WITH sessionmem:
  [warning] JWT blacklist must be checked before issuing new tokens. Fixed PR #47.
  [decision] Stripe migration ~50% done. Do NOT use /lib/billing-v1.
  [fact] Stack: TypeScript, Next.js, Postgres.

  Claude: "Looks like you're mid-Stripe migration. Where do you want to pick up?"

sessionmem é um servidor MCP que observa suas sessões de codificação e armazena o que realmente importou — decisões, avisos, coisas que poderiam te prejudicar se o Claude as esquecesse. No início de cada nova sessão, ele injeta automaticamente os trechos relevantes. Funciona com Claude Code, Cursor, Cline, Codex, Windsurf e qualquer ferramenta que fale MCP.

Tudo permanece na sua máquina. Sem conta, sem nuvem, sem dados saindo do seu computador, a menos que você ative isso explicitamente.

Início rápido

Nenhuma experiência com programação é necessária. Você só precisa de um terminal (Prompt de Comando, Terminal ou PowerShell) e Node.js instalado.

1. Instale o sessionmem

npm install -g sessionmem

2. Registre-o na sua ferramenta de IA

Execute isto dentro da pasta do projeto em que você está trabalhando, com sua ferramenta de IA (Claude Code, Cursor, etc.) configurada:

sessionmem install

Isso faz três coisas:

Informa ao host MCP da sua ferramenta de IA sobre o sessionmem para que ele possa ser iniciado automaticamente.
Cria um arquivo de configuração em ~/.sessionmem/config.json com padrões seguros e que respeitam a privacidade, mas somente se um já não existir.
Injeta instruções em ~/.claude/CLAUDE.md para que o Claude Code conheça as ferramentas do sessionmem e as use proativamente (idempotente, portanto seguro para reexecutar).

3. Comece a usar sua ferramenta de IA normalmente

sessionmem run

(Na maioria das vezes, você não executará isso manualmente. O host da sua ferramenta de IA o inicia automaticamente depois que ele é registrado.)

É isso. A partir daqui:

sessionmem observa suas sessões em segundo plano.
Ao final de cada sessão, ele registra um resumo curto do que importou.
No início da sua próxima sessão, ele lembra silenciosamente seu assistente dos trechos relevantes.

Você pode verificar se tudo está funcionando com:

sessionmem ping

Sumário

Que problema isso resolve?
Como o sessionmem é diferente?
Resultados de benchmark
Como funciona (em linguagem simples)
Referência de comandos CLI
Privacidade, segredos e seus dados
Apodrecimento de memória: mantendo a memória precisa ao longo do tempo
Modo equipe (opcional)
Resumo em nuvem (opcional, desativado por padrão)
Ferramentas suportadas
Documentação adicional
Solução de problemas
Perguntas frequentes
Contribuindo
Licença

Que problema isso resolve?

Se você já usou um assistente de codificação com IA por mais de um dia, provavelmente já passou por isto:

Você gasta vinte minutos explicando a configuração do seu projeto, as bibliotecas que usa, um bug complicado que já corrigiu e uma decisão que tomou sobre como a autenticação deveria funcionar. O assistente concorda com a cabeça, ajuda você... e então, na sua próxima sessão, ele esqueceu tudo. Você explica tudo de novo.

Isso acontece porque a maioria dos assistentes de IA só "sabe" o que está dentro da conversa atual. Quando essa conversa termina, o contexto desaparece.

sessionmem resolve isso ficando silenciosamente entre seu assistente e seu projeto:

Enquanto você trabalha, ele captura o que acontece na sessão.
Quando a sessão termina, ele resume as partes importantes (decisões tomadas, avisos, fatos úteis) em notas curtas e duráveis.
Na próxima vez que você iniciar uma sessão, ele lembra o assistente das notas mais relevantes, automaticamente, em uma pequena quantidade de texto.

Você não executa nenhuma dessas etapas manualmente. Depois de instalado, ele simplesmente funciona em segundo plano.

Como o sessionmem é diferente?

Existem outros projetos de "memória para Claude" por aí (por exemplo, ferramentas como claude-mem e projetos comunitários similares). Aqui está o que diferencia o sessionmem:

	sessionmem	Ferramentas de memória típicas em nuvem/somente Claude
Onde os dados são armazenados?	Um único arquivo SQLite no seu computador (`~/.sessionmem/memories.db`)	Frequentemente um serviço hospedado, um banco de dados vetorial em nuvem ou um processo de servidor separado que você precisa executar
Conta / cadastro necessário?	Não, nunca	Às vezes
Com quais ferramentas de IA funciona?	Claude Code, Cursor, Codex, Cline, Windsurf, Antigravity, QCoder e qualquer outro host compatível com MCP	Geralmente apenas uma ferramenta específica (comumente somente Claude Code)
Redação de segredos	Integrada, ativada por padrão. Chaves de API, tokens, senhas e chaves privadas são removidas antes que qualquer coisa seja salva.	Frequentemente não tratada, ou deixada para o usuário
Controle de orçamento de tokens	Memórias injetadas são limitadas a um orçamento de tokens pequeno e fixo para não inflar cada conversa (veja benchmarks abaixo)	Varia, frequentemente ilimitado
Limpeza de memórias antigas/obsoletas	Política de retenção integrada remove automaticamente memórias antigas (configurável, ativada por padrão)	Frequentemente cresce para sempre ("apodrecimento de memória")
Compartilhamento em equipe	Opcional, via uma pasta compartilhada que você já controla (unidade de rede, diretório sincronizado). Sem necessidade de servidor.	Geralmente requer um backend hospedado compartilhado
Capaz de funcionar offline	Sim, totalmente. Funciona sem conexão de rede por padrão.	Geralmente requer acesso à rede para o serviço de memória

Em resumo: sessionmem é a opção chata, local, "apenas um arquivo SQLite": fácil de inspecionar, fazer backup e excluir, sem dependência de nenhum fornecedor específico de ferramenta de IA.

Resultados de benchmark

Esses números vêm de npm run benchmark (scripts/benchmark.mjs), que executa o código real de recuperação e injeção em produção sobre um conjunto fixo e sintético de dados de teste, sem chamadas de rede. Os resultados são totalmente reproduzíveis. Veja docs/benchmark.md para o relatório completo e como regenerá-lo.

Economia de tokens

Redução de ~85,6% em tokens em comparação com carregar o histórico completo da sessão.

	Tokens
Histórico completo da sessão (linha de base)	1.587
O que o sessionmem injeta no início da sua próxima sessão	228

Na prática: em vez de reler (ou reexplicar) cerca de 1.600 tokens de contexto passado a cada sessão, o assistente recebe um resumo de 230 tokens apenas das coisas que importam: decisões, avisos e fatos-chave.

Precisão de recuperação

Taxa de acerto de 100%: cada uma das 10 consultas de teste recuperou com sucesso a memória que deveria.

Métrica	Resultado
Taxa de acerto (10 consultas selecionadas)	100,0%
Recall	100,0%
Precisão	33,3%

A precisão de 33,3% é esperada aqui: cada consulta recupera as 3 principais memórias candidatas, e apenas uma dessas três é a correspondência "esperada" para uma determinada consulta de teste. As outras duas ainda são contexto relevante para o agente, apenas não são aquela que está sendo avaliada. O número importante é recall/taxa de acerto: a memória certa nunca é perdida.

Esses benchmarks são determinísticos e reproduzíveis. Execute-os você mesmo:

npm run build      # benchmark imports the compiled code from dist/
npm run benchmark  # regenerates docs/benchmark.md

Como funciona (em linguagem simples)

        ┌──────────────────────────────────────────────┐
        │                  Your AI tool                 │
        │   (Claude Code, Cursor, Codex, Cline, ...)    │
        └───────────────────────┬──────────────────────┘
                                 │
                     ┌───────────▼───────────┐        ┌──────────────┐
                     │   sessionmem adapter   │        │ sessionmem   │
                     │ (translates for your   │        │     CLI      │
                     │   specific AI tool)    │        │ (you type    │
                     └───────────┬───────────┘        │  commands)   │
                                 │                     └──────┬───────┘
                                 ▼                            │
                     ┌──────────────────────────────────────────────┐
                     │              sessionmem core engine           │
                     │  watches sessions · writes summaries ·        │
                     │  finds relevant memories · trims to fit       │
                     └───────────────────────┬──────────────────────┘
                                              │
                                              ▼
                     ┌──────────────────────────────────────────────┐
                     │         One SQLite file on your computer      │
                     │     ~/.sessionmem/memories.db                 │
                     └──────────────────────────────────────────────┘

Adaptadores são pequenos componentes que sabem como conversar com cada ferramenta de IA específica. É por isso que o sessionmem pode suportar muitas ferramentas: adicionar uma nova não muda como a memória em si funciona.
O mecanismo central é o mesmo independentemente da ferramenta que você usa. Ele decide o que vale a pena lembrar, quão relevante será depois e quanto cabe em um pequeno "lembrete" no início da sua próxima sessão.
O banco de dados é apenas um arquivo. Você pode fazer backup, movê-lo, inspecioná-lo ou excluí-lo como qualquer outro arquivo no seu computador.

Para um mergulho técnico mais profundo, veja docs/architecture.md.

Referência de comandos CLI

Comando	O que faz
`sessionmem install`	Registra o sessionmem no host MCP atual e grava a configuração padrão.
`sessionmem uninstall [--purge]`	Remove o sessionmem do host. `--purge` também exclui o banco de dados local.
`sessionmem run`	Inicia o servidor MCP.
`sessionmem ping`	Verifica a conectividade do servidor.
`sessionmem search <query> [--limit <n>]`	Busca memórias por consulta semântica.
`sessionmem list`	Lista todas as memórias do projeto atual.
`sessionmem show <id>`	Mostra detalhes completos de uma memória.
`sessionmem forget <id> [--force]`	Exclui uma memória por ID.
`sessionmem export [path]`	Exporta memórias para um arquivo JSON.
`sessionmem import <path> [--merge]`	Importa memórias de um arquivo JSON.
`sessionmem stats`	Mostra estatísticas de memória do projeto atual.
`sessionmem savings [--json]`	Mostra economia de tokens com compressão e injeção, com porcentagem.
`sessionmem redact-scan [--apply]`	Examina memórias armazenadas em busca de segredos; `--apply` redige no local.
`sessionmem retention prune [--force] [--days <n>]`	Remove memórias antigas (simulação por padrão).
`sessionmem config get <key>` / `config set <key> <value>`	Lê e grava a configuração de políticas.
`sessionmem team enable <path>` / `team disable` / `team status`	Gerencia o modo de memória de equipe com caminho compartilhado.
`sessionmem sync`	Envia memórias locais e puxa memórias de colegas via caminho compartilhado.

Privacidade, segredos e seus dados

Tudo permanece na sua máquina por padrão. Sem conta, sem telemetria, sem serviço de memória hospedado. Armazenamento, recuperação e resumo são todos executados localmente, regidos por ~/.sessionmem/config.json.

Segredos são removidos automaticamente

Antes que qualquer coisa seja salva, sessionmem remove automaticamente padrões comuns de segredos e os substitui por REDACTED:

Endereços de e-mail
Chaves de API (sk-..., AWS AKIA..., GitHub ghp_.../gho_..., etc.)
Tokens Bearer e JWTs
Blocos de chaves privadas (-----BEGIN ... PRIVATE KEY-----)
Segredos no formato de string de conexão (password=..., secret=...)

Isso está ativado por padrão. Você pode examinar e limpar memórias mais antigas a qualquer momento:

sessionmem redact-scan          # see what would be redacted
sessionmem redact-scan --apply  # actually redact in place

Detalhes completos: docs/privacy-and-retention.md.

Apodrecimento de memória: mantendo a memória precisa ao longo do tempo

"Apodrecimento de memória" é o que acontece quando um sistema de memória continua acumulando notas para sempre. Eventualmente, ele se enche de decisões desatualizadas, fatos duplicados e ruído, e o assistente começa a exibir informações obsoletas em vez de informações úteis.

sessionmem foi projetado para evitar isso de algumas maneiras:

Poda por retenção: memórias mais antigas que uma janela configurável (padrão de 90 dias) são automaticamente elegíveis para limpeza. Isso é executado como uma verificação leve ao final de cada sessão e também pode ser executado manualmente:
```
sessionmem retention prune          # dry run - shows what *would* be deleted
sessionmem retention prune --force  # actually deletes
```
Classificação ponderada por importância: quando as memórias são recuperadas, elas são classificadas por uma combinação de relevância semântica, atualidade e importância. Notas antigas e de baixa importância naturalmente afundam e param de ser exibidas antes mesmo de serem podadas.
Injeção com orçamento de tokens: apenas as memórias mais bem classificadas e relevantes são injetadas (limitadas a um pequeno orçamento de tokens, veja benchmarks), para que mesmo um grande armazenamento de memórias não produza contexto inflado e ruidoso.
Resolução de conflitos no modo equipe: quando memórias são mescladas de colegas, o sistema usa última-escrita-vence por id (para que duplicatas obsoletas não se acumulem), preservando a pontuação de importância mais alta (para que um aviso crítico não seja silenciosamente rebaixado).

O benchmark de recuperação acima (100% de taxa de acerto / 100% de recall) demonstra que mesmo com a classificação e a limitação em vigor, a memória certa ainda aparece. A precisão não é sacrificada em troca de compactação.

Você sempre tem o controle: exporte tudo primeiro se quiser um registro permanente antes de podar:

sessionmem export

Modo equipe (opcional)

Quer que os assistentes de IA de toda a sua equipe compartilhem decisões e avisos? Aponte o sessionmem para uma pasta compartilhada (uma unidade de rede, um diretório sincronizado ou qualquer local que todos possam ler e gravar):

sessionmem team enable <shared-path>
sessionmem sync

Desativado por padrão: nada é compartilhado até que você ative.
Sem necessidade de servidor. São apenas arquivos em uma pasta que você já controla.
As memórias dos colegas aparecem com um prefixo author: para que você saiba de onde vieram.
Segredos são re-mascarados em cada memória recuperada, para que o snapshot de um colega não possa reintroduzir algo que sua política de mascaramento teria removido.

Detalhes completos, incluindo o modelo de confiança: docs/team-mode.md.

Sumarização em nuvem (opcional, desativado por padrão)

Por padrão, a sumarização (transformar uma sessão em uma memória curta) acontece inteiramente de forma local, sem chamadas de API.

Se você ativar explicitamente (allowCloudSummarization=true) e fornecer um ANTHROPIC_API_KEY, a sumarização pode usar a API do Claude para resumos de maior qualidade. Se isso falhar, ela automaticamente volta para a sumarização local. Suas sessões nunca ficam sem sumarização.

Detalhes: docs/cloud-summarization.md.

Ferramentas suportadas

sessionmem funciona com qualquer host compatível com MCP, incluindo:

Claude Code
Cursor
Codex
Cline
Windsurf
Antigravity
QCoder

...e qualquer outra ferramenta que implemente o Model Context Protocol.

Documentação adicional

Arquitetura: como o motor principal, adaptadores, CLI e armazenamento SQLite se encaixam.
Benchmark: relatório completo de redução de tokens e precisão de recuperação, e como reproduzi-lo.
Privacidade e retenção: mascaramento de segredos, poda de retenção e configuração.
Modo de equipe: memória de equipe em caminho compartilhado.
Sumarização em nuvem: o caminho opcional de sumarização em nuvem.
Migração: o sistema de migração SQLite e a política de atualização de versão.
Solução de problemas: falhas de instalação, problemas de adaptadores e problemas de build nativo do better-sqlite3.

Solução de problemas

Enfrentou problemas ao instalar ou executar o sessionmem? Comece com docs/troubleshooting.md. Ele cobre falhas de instalação, problemas específicos de adaptadores, dados de sessão ausentes e problemas de build do módulo nativo (better-sqlite3) em diferentes plataformas.

Duas verificações rápidas que resolvem a maioria dos relatos:

sessionmem install   # idempotent — re-registers the MCP server and all three hooks
sessionmem stats     # memories, sessions, and session_events for the current project

Se o stats mostrar sessions: 0 após trabalho real, consulte “0 sessões” / nenhum dado de sessão registrado. As memórias são vinculadas à raiz do repositório, então cada diretório dentro de um repositório compartilha um bucket; fora de um repositório, o diretório de trabalho em si é a chave.

Verificações rápidas:

sessionmem ping     # is the server reachable?
sessionmem stats    # is data being stored?

FAQ

Como dou memória entre sessões ao Cursor, Cline ou Windsurf? Instale o sessionmem (npm i -g sessionmem) e execute sessionmem install no seu projeto. Ele se registra automaticamente como servidor MCP em qualquer host compatível.

Como dou memória persistente ao Claude Code? Mesma instalação. O sessionmem também é distribuído como plugin do Claude Code (o arquivo .claude-plugin no repositório), então funciona também com o sistema nativo de plugins do Claude Code.

Existe um servidor de memória MCP local que funcione offline sem chave de API? Sim. O sessionmem armazena tudo em um único arquivo SQLite em ~/.sessionmem/memories.db e funciona totalmente offline por padrão. Nada sai da sua máquina a menos que você ative explicitamente o caminho opcional de sumarização em nuvem.

Como o sessionmem é diferente do claude-mem? O sessionmem não é exclusivo do Claude. Ele funciona com Cursor, Cline, Codex, Windsurf, Antigravity, QCoder e qualquer outro host MCP, não apenas com o Claude Code. Ele também mascara segredos (chaves de API, tokens, JWTs) por padrão, remove memórias obsoletas automaticamente e inclui benchmarks reproduzíveis que você pode executar.

O sessionmem envia meu código para a nuvem? Não. Nada sai da sua máquina por padrão. O caminho opcional de sumarização em nuvem é opt-in e desativado por padrão.

Como vejo quantos tokens o sessionmem economizou? Execute sessionmem savings para ver um detalhamento da compressão de armazenamento (tokens brutos de sessão vs tokens de memória) e eficiência de injeção. Adicione --json para saída legível por máquina.

Contribuindo

Issues e pull requests são bem-vindos. O código é TypeScript, testado com Vitest e verificado com ESLint:

npm install
npm run build
npm test
npm run lint

Configuração MCP para desenvolvimento local: Copie .mcp.json.example para .mcp.json para desenvolvimento local, ou use sessionmem install para configurar automaticamente. O arquivo .mcp.json está no gitignore porque contém caminhos específicos da máquina.

Licença

MIT