Memento

Uma camada de memória local-first, agnóstica de LLM para assistentes de IA
runmemento.com

Toda sessão de IA começa do mesmo jeito: reexplicar suas preferências, as convenções do seu projeto, as decisões que você tomou na semana passada, os becos sem saída a evitar. Cada ferramenta resolve isso do seu próprio jeito isolado (CLAUDE.md, .cursorrules, copilot-instructions.md, ChatGPT Memory) — mas você, o humano, é a única constante. Sua memória não deveria se fragmentar entre fornecedores.

Memento é um lugar onde essa memória vive. Ele executa um servidor MCP sobre um arquivo SQLite local, então qualquer assistente de IA compatível com MCP — Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, um bot de pesquisa, um agente personalizado — pode ler e gravar memória estruturada e durável sobre você, seu trabalho e suas decisões. Local-first, sem chamadas de rede de saída por padrão, sem dependência de fornecedor.

_{Um chat novo sem contexto prévio — Memento fornece a memória do que foi decidido na semana passada.}

Quickstart

Três passos de zero até uma camada de memória funcional:

1. Execute init (interativo em um TTY)

npx @psraghuveer/memento init

Cria o banco de dados sob o padrão XDG ($XDG_DATA_HOME/memento/memento.db, tipicamente ~/.local/share/memento/memento.db em POSIX), executa migrações e — em um TTY — guia você por quatro perguntas de configuração de uma tecla:

• Seu nome preferido. Armazenado como a chave de configuração user.preferredName para que as memórias leiam "Raghu prefere …" em vez de "O usuário prefere …".
• Instalar a skill incluída? Um y/N. Copia skills/memento/ em ~/.claude/skills/ para clientes que carregam skills no formato Anthropic.
• Semear com um pacote inicial? Escolha um dos quatro pacotes incluídos (engineering-simplicity, pragmatic-programmer, twelve-factor-app, google-sre) para que sua loja tenha memórias úteis desde o primeiro dia. Pule para começar vazio.
• Instalar automaticamente o snippet de persona? Detecta clientes de IA na sua máquina e escreve um bloco delimitado por marcadores no arquivo de instruções personalizadas de escopo do usuário de cada um (~/.claude/CLAUDE.md para Claude Code, ~/.config/opencode/AGENTS.md para OpenCode, ~/Documents/Cline/Rules/memento.md para Cline). Idempotente e removível. Clientes somente de interface (Cowork, Claude Desktop, Claude Chat, Cursor User Rules) recebem instruções de colar impressas.

Depois, imprime snippets MCP de copiar-e-colar para cada cliente suportado. Idempotente — execute novamente a qualquer momento para reimprimir os snippets e refazer qualquer pergunta que você pulou. Passe --no-prompt para suprimir o fluxo interativo (CI, scripts).

2. Conecte seu cliente de IA

init imprime ou uma linha de subcomando (onde o cliente fornece uma) ou um snippet JSON para mesclar no arquivo de configuração MCP do cliente. Escolha o do seu cliente, cole e reinicie o cliente para que ele carregue o novo servidor MCP.

O passo a passo completo por cliente está em docs/guides/mcp-client-setup.md.

3. Confirme que o snippet de persona alcança seu assistente

Memento fornece três superfícies de ensino — um instructions MCP como espinha dorsal no protocolo, uma skill incluída para clientes com suporte a skills e o snippet de persona. Dos três, apenas o snippet de persona tem garantia de chegar ao prompt de sistema do assistente em toda mensagem — a especificação MCP deixa instructions opcional e as implementações de clientes variam em como o expõem; a skill é acionada por intenção, então não dispara em mensagens neutras iniciais.

Se você disse Y na pergunta de instalação automática da persona no Passo 1, isso já está feito para todo cliente baseado em arquivos detectado na sua máquina — o snippet foi gravado em ~/.claude/CLAUDE.md, ~/.config/opencode/AGENTS.md e/ou ~/Documents/Cline/Rules/memento.md conforme aplicável. Para clientes somente de interface (Cowork, Claude Desktop, Claude Chat em claude.ai, Cursor User Rules) e para qualquer cliente seu onde o instalador automático não atuou, copie o snippet de persona de docs/guides/teach-your-assistant.md e cole no campo de instruções personalizadas / prompt de sistema do cliente (o nome do campo varia — "Custom Instructions" na interface de configurações do cliente, etc.).

É isso. Verifique se o protocolo funciona de ponta a ponta com npx @psraghuveer/memento verify-setup — um ciclo de ida e volta de gravação/pesquisa/limpeza que prova que seu assistente consegue de fato chamar o Memento.

Então tente uma sessão nova: "Lembre que eu prefiro pnpm em vez de npm para projetos Node." Na próxima sessão, pergunte "Qual é meu gerenciador de pacotes preferido?" e o assistente deve lembrar sem você explicar de novo.

Popule sua loja com um pacote

Uma instalação nova do Memento fica vazia. Pacotes são conjuntos YAML curados de memórias que você instala em um passo — um guia de stack (Rust + Axum, TypeScript + pnpm, Python + uv…), as convenções de uma equipe ou um conjunto pessoal que você criou em outra máquina.

memento pack install engineering-simplicity

Esse comando instala um dos pacotes incluídos — onze memórias destiladas de The Laws of Simplicity de John Maeda. Quatro pacotes incluídos vêm de fábrica: engineering-simplicity, pragmatic-programmer (dicas de Hunt & Thomas), twelve-factor-app (Wiggins / Heroku) e google-sre (livros de SRE do Google). Pré-visualize antes de instalar com memento pack preview <id-or-path>; liste o que está instalado com memento pack list; remova a qualquer momento com memento pack uninstall <id> --confirm (dry-run por padrão).

Pacotes também são como você compartilha. Crie um a partir das suas memórias existentes com memento pack create e depois distribua como arquivo, URL HTTPS ou contribuição da comunidade. A tag reservada pack:<id>:<version> carimba toda memória instalada por pacote para que a proveniência nunca se perca. Guia completo: docs/guides/packs.md. Justificativa de design: ADR-0020.

Começando

Pré-requisitos. Node.js ≥ 22.11 e um kit de ferramentas C/C++ para que better-sqlite3 possa compilar em plataformas sem build prévio (ferramentas de linha de comando do Xcode no macOS, build-essential no Debian/Ubuntu).

Execute init uma vez para configurar tudo:

npx @psraghuveer/memento init

init define o banco de dados como padrão no diretório de dados XDG; passe --db /custom/path/memento.db (ou defina MEMENTO_DB=/custom/path/memento.db) se quiser um local não padrão.

Para executar o servidor diretamente (por exemplo, para depuração):

npx @psraghuveer/memento serve

O servidor fica ouvindo em stdio por requisições MCP. Para passar flags extras (por exemplo, um local de banco de dados personalizado):

npx @psraghuveer/memento serve --db ~/.local/share/memento/memento.db

Você também pode apontar para um banco de dados existente com a variável de ambiente MEMENTO_DB.

Verifique a instalação executando npx @psraghuveer/memento doctor (adicione --quick para pular as sondas de banco de dados e embedder; adicione --mcp para também escanear arquivos de configuração de clientes MCP conhecidos). Para um resumo de uma tela do que está na sua loja, npx @psraghuveer/memento status. Para inspecionar o que sua instalação pode fazer — comandos registrados, configuração atual, local do banco de dados — sem falar MCP, execute npx @psraghuveer/memento context. Para testar o transporte MCP de ponta a ponta, npx @psraghuveer/memento ping.

Conectar o Memento a um cliente MCP (Claude Desktop, Claude Code, Cursor, Cline, OpenCode, VS Code Agent mode, …) é coberto passo a passo em docs/guides/mcp-client-setup.md. O resumo é o quickstart de três passos acima: init (que instala automaticamente o snippet de persona nos clientes baseados em arquivos detectados se você disser Y), cole o snippet do servidor MCP no seu cliente e, para clientes somente de interface, cole o snippet de persona manualmente.

Recuperação vetorial (correspondência de paráfrases sobre FTS) está ligada por padrão. A primeira busca dispara um download de modelo único (~110 MB) em $XDG_CACHE_HOME/memento/models (ou ~/.cache/memento/models / %LOCALAPPDATA%\memento\Cache\models); depois disso, tanto o braço FTS quanto o vetorial rodam automaticamente. Se o modelo ainda não tiver sido baixado, a busca degrada graciosamente para somente FTS. Para opções de configuração e detalhes de integração com bibliotecas, veja docs/guides/embeddings.md.

Operar a loja no dia a dia — compact, backup, status, agendamento — é coberto em docs/guides/operations.md. O fluxo de conflitos está em docs/guides/conflicts.md. Para preparar um assistente de IA a usar bem o Memento, veja docs/guides/teach-your-assistant.md — e, se seu cliente carrega skills no formato Anthropic, instale a skill incluída como enriquecimento por intenção sobre o snippet de persona.

Veja e faça a curadoria da sua loja no navegador. npx @psraghuveer/memento dashboard inicia uma interface web local-first que lê contra seu MEMENTO_DB: contagens de memória por tipo e escopo, trilha de auditoria, triagem de conflitos, inspeção de configuração, pacotes instalados. Somente localhost, protegida por um token aleatório por execução na URL que o lançador entrega ao navegador, sem telemetria. O dashboard é um pacote irmão (@psraghuveer/memento-dashboard) enviado sob ADR-0018; veja docs/guides/dashboard.md para o passo a passo completo.

Empacou? Modos de falha comuns (erros de build do better-sqlite3, command not found: memento, STORAGE_ERRORs, dependência de embedder ausente) são cobertos em docs/guides/troubleshooting.md.

Para o fluxo de trabalho de contribuidores (branching, convenções de commit, checklist de PR) veja CONTRIBUTING.md. Agentes de IA trabalhando no código devem também ler AGENTS.md.

Princípios guia

Estes são os quatro princípios contra os quais toda decisão de design é julgada. Eles estão documentados em detalhes em ARCHITECTURE.md.

1. Primeiros princípios. Cada constructo existe porque provamos que precisamos dele, não porque é assim que as coisas costumam ser feitas.
2. Modular. Qualquer componente pode ser substituído sem reescrever o resto.
3. Extensível. Novas variantes não exigem mudanças que quebrem o funcionamento.
4. Configurável pelo usuário. O comportamento é moldado pela configuração, não pelo código.

O que o Memento é

Quatro pilares. As mesmas quatro palavras usadas em qualquer outro lugar onde isso é descrito.

• Local. Um único arquivo SQLite sob seu diretório home. Sem nuvem, sem telemetria, sem chamadas de rede de saída por padrão. Totalmente offline.
• Tipado. Cinco tipos de memória — fact, preference, decision, todo, snippet — com campos específicos por tipo (uma decisão carrega sua justificativa, um todo sua data de vencimento, um snippet sua linguagem). O assistente consegue raciocinar sobre o que ainda é verdade, não apenas recuperar blocos de texto.
• Auditado. Toda gravação produz um evento em um log de anexação somente. Conflitos aparecem para triagem em vez de coexistirem silenciosamente. Memórias decaem se você não as confirma. Você pode responder "por que isso está aqui?" e "quando mudou?" a qualquer momento.
• Seu. Comportamento configurável (cada peso de recuperação, cada meia-vida de decaimento, cada regra de limpeza), exportação e importação JSONL, Apache-2.0. Leve sua memória entre máquinas, saia a qualquer momento. Sem dependência de fornecedor.

Além disso: agnóstico de LLM (funciona com qualquer modelo com que seu cliente fala), nativo de MCP (Claude Desktop, Claude Code, Cursor, GitHub Copilot, Cline, OpenCode, Aider, agentes personalizados), consciente de privacidade (o limpador baseado em regex remove segredos antes da persistência; padrões são configuráveis pelo usuário).

O que o Memento não é

• Não é um armazenamento de histórico de chat. Ele registra memória destilada e estruturada — preferências, fatos, episódios, lições — não transcrições cruas.
• Não é um grafo de conhecimento ou banco semântico. Use as ferramentas certas para isso.
• Não é um serviço de nuvem. A memória vive na sua máquina; embedders em nuvem, sincronização entre máquinas e memória compartilhada em equipe não fazem parte do produto.
• Não é uma plataforma de plugins. A arquitetura deixa a porta aberta, mas o Memento vem com uma superfície fixa para manter o padrão de qualidade.

A lista completa de fora de escopo e limitações atuais está em KNOWN_LIMITATIONS.md.

Como tudo se encaixa

┌─────────────────────────────────────────────────────────┐
│  Clients: Claude Desktop, Claude Code, Cursor, Copilot, │
│           OpenCode, custom agents, …                    │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP (stdio)
┌──────────────────────▼──────────────────────────────────┐
│  memento-server (MCP adapter)                           │
└──────────────────────┬──────────────────────────────────┘
                       │ Command registry
┌──────────────────────▼──────────────────────────────────┐
│  memento-core: services, scope resolver, scrubber,      │
│                conflict detector, decay engine          │
└──────────────────────┬──────────────────────────────────┘
                       │ Repository interfaces
┌──────────────────────▼──────────────────────────────────┐
│  SQLite (better-sqlite3) + FTS5 + optional sqlite-vec   │
└─────────────────────────────────────────────────────────┘

Uma visão geral arquitetural completa está em ARCHITECTURE.md. Cada decisão significativa possui um Registro de Decisão de Arquitetura.

Para contribuidores (humanos ou IA)

Contribuições são bem-vindas tanto de autores humanos quanto assistidos por IA. Tratamos ambos com os mesmos padrões.

• Leia AGENTS.md se você é um agente de IA ou trabalha com um. É o conjunto canônico de instruções; CLAUDE.md e .github/copilot-instructions.md são ponteiros leves para ele.
• Leia CONTRIBUTING.md para configuração de desenvolvimento, branching, convenções de commit e o ciclo de vida de PRs.
• Abra uma issue de proposta de design antes de qualquer mudança não trivial.
• Use o template de PR. Ele pede que você justifique, não apenas descreva, a mudança.

Usamos GitHub Discussions para perguntas e ideias; o rastreador de issues é para bugs e trabalho aceito.

Licença

Apache-2.0. Veja NOTICE para atribuição.

Pacotes

Memento é um pequeno workspace de pacotes focados. A arquitetura está documentada em docs/architecture/ e as decisões de design em docs/adr/; ambos são a fonte da verdade sobre o que Memento faz e por quê.

Package	Notes
@psraghuveer/memento-schema	Schemas de memória / evento / escopo / scrubber / conflito / config / resultado, além de schemas de valor por ConfigKey.
@psraghuveer/memento-core	Armazenamento e migrações, repositórios de memória + evento, resolvedor de escopo, scrubber, mecanismo de decaimento com passada de arquivamento compact, detecção de conflito + fluxo de substituição, hook de embedding + driver de re-embed em lote, interface EmbeddingProvider, pipeline de recuperação vetorial FTS + força bruta + ranker, e o registro de comandos com caminho de execução validado (ADR 0003).
@psraghuveer/memento-server	Adaptador MCP — buildMementoServer projeta o registro de comandos @psraghuveer/memento-core como ferramentas MCP; serveStdio o conecta ao stdio. Usado por memento serve.
@psraghuveer/memento-embedder-local	EmbeddingProvider local com suporte de transformers.js + bge-base-en-v1.5. Distribuído como dependência regular; init lazy single-flight baixa o modelo no primeiro uso. Veja ADR 0006.
@psraghuveer/memento (CLI)	O binário memento publicado (npx @psraghuveer/memento ou npm i -g @psraghuveer/memento). Comandos de ciclo de vida (init, serve, dashboard, context, doctor, verify-setup, status, ping, backup, export, import, pack, store migrate, completions, explain, skill-path, uninstall) além de uma projeção genérica da superfície do registro (memento <namespace> <verb>). Veja docs/reference/cli.md.
@psraghuveer/memento-dashboard	Dashboard web local-first. Servidor Hono in-process com o engine + SPA React construída com Vite. Iniciado por memento dashboard; vincula apenas 127.0.0.1. Veja ADR-0018 e docs/guides/dashboard.md.
@psraghuveer/memento-landing	Página de destino de marketing. SPA estática, implantada no GitHub Pages a cada push para main que toca packages/landing/**. Espelha os design tokens do dashboard; alternância claro/escuro. Privada (não publicada no npm).