th-memory-mcp

Servidor MCP de memória de longo prazo para OpenCode e outros harnesses — armazena preferências, lições e histórico de uso em um único arquivo SQLite local (100% local, sem API externa) para que a IA possa "lembrar e se adaptar" ao usuário por meio de aprendizado baseado em contexto.

GitHub
1
Experimente este MCPPatrocinado

Documentação

th-memory-mcp

npm version npm downloads License: MIT Node

Servidor MCP de memória de longo prazo para OpenCode — armazena preferências, lições e histórico de uso em um único arquivo SQLite local (100% local, sem API externa) para que a IA possa "lembrar e se adaptar" ao usuário por meio de aprendizado baseado em contexto.

Status: v2.2.2 — um mecanismo de memória temporal, ciente de conflitos e com recuperação híbrida. 16 ferramentas MCP, 20 suítes de teste aprovadas. Migração de esquema não destrutiva da v1 (todos os dados da v1 são preservados). Novo na v2: estados de ciclo de vida, validade temporal, resolução de conflitos/deduplicação com escopo USER/SESSION/PROJECT/GLOBAL, recuperação híbrida FTS+vetorial (RRF), grafo de memória, montagem de get_context, consolidação periódica e link_memory / merge_memory / update_memory / import_memory / extract_memories.

Requisitos

  • Node.js >= 20 — o servidor usa APIs exclusivas do Node (o build nativo de better-sqlite3 e a resolução de import.meta.url) e o SDK MCP exige um runtime moderno. Testes de CI no Node 20.x e 22.x.
  • npm — para instalar dependências e executar os scripts de build/teste (npm install, npm run build, npm test).
  • OpenCode — o host que carrega este servidor MCP e o plugin de captura automática. Qualquer build que suporte MCP via stdio + plugins funciona; o plugin roda no runtime Bun integrado do OpenCode.
  • SO: Windows / macOS / Linux — o servidor é multiplataforma (Node). O plugin de captura automática roda onde o runtime Bun do OpenCode roda. Nota para Windows: MEMORY_DB_PATH é mais fácil de definir com setx; no macOS/Linux use export no seu perfil de shell.

Nenhum serviço externo, conta ou chave de API é necessário — tudo vive em um único arquivo SQLite local.

Início Rápido

Caminho mais rápido: após clonar, execute npm run quickstart — ele compila, configura opencode.json, implanta o plugin e define MEMORY_DB_PATH para você em um único comando. As etapas abaixo mostram exatamente o que ele faz (use-as se preferir controle manual).

Instalação via npm (alternativa): instale o servidor globalmente com npm install -g th-memory-mcp (ou execute-o sob demanda com npx th-memory-mcp), depois aponte o mcp command em opencode.json para th-memory-mcp em vez do dist/index.js compilado. O plugin de captura automática ainda vem deste repositório (copie src/plugin/learning-capture.ts conforme descrito na etapa 4 abaixo).

# 1. Clone and build
git clone https://github.com/worakorn-prince/th-memory-mcp.git
cd th-memory-mcp
npm install
npm run build

# 2. Share one DB between the server and the plugin
#    Windows (PowerShell):
setx MEMORY_DB_PATH "$PWD/data/memory.db"
#    macOS / Linux (add to your shell profile, e.g. ~/.zshrc):
# export MEMORY_DB_PATH="$PWD/data/memory.db"
  1. Mescle isso no seu ~/.config/opencode/opencode.json (substitua <REPO> pelo caminho absoluto do clone):
{
  "instructions": ["<REPO>/AGENTS.memory.example.md"],
  "mcp": {
    "memory": {
      "type": "local",
      "command": ["node", "<REPO>/dist/index.js"],
      "enabled": true,
      "environment": { "MEMORY_DB_PATH": "<REPO>/data/memory.db" }
    }
  }
}
  1. (Opcional) Captura automática: copie src/plugin/learning-capture.ts → ~/.config/opencode/plugins/
  2. Reinicie o OpenCode
  3. Experimente: "Lembre-se de que prefiro pnpm" → nova sessão → "Qual gerenciador de pacotes eu prefiro?"

Arquitetura

OpenCode ──┬─ Plugin learning-capture (Bun)  ── auto-captures prompts/tool/error into DB
            │                                   └─ injects profile back into context on compaction
             └─ MCP th-memory-mcp (Node.js stdio)  ── 16 tools read/write the same SQLite DB
                                                      ▲
                               Global instructions (memory-protocol.md) teach the AI to use the tools

Consulte ARCHITECTURE_v2.md para a especificação completa da arquitetura.

Por que th-memory-mcp?

LLMs não se lembram de você entre sessões — cada novo chat começa em branco. O th-memory-mcp dá à sua IA uma memória de longo prazo privada e local:

  • Aprendizado baseado em contexto, não fine-tuning — captura suas preferências, correções e hábitos, e os recupera no contexto na próxima vez. Mesmo mecanismo dos recursos de memória dos principais produtos de IA, sem enviar nenhum dado para fora da sua máquina.
  • 100% local e privado — um único arquivo SQLite, sem nuvem, sem API externa. Segredos são filtrados antes de qualquer armazenamento.
  • Baixa sobrecarga — cada chamada de ferramenta é limitada (latência < 10 ms, tamanho de saída limitado) e a IA só consulta a memória quando é realmente útil, então nunca infla seu contexto.
  • Resiliente — toda ferramenta degrada graciosamente; se o banco de dados estiver indisponível, a IA continua funcionando em vez de travar.
  • Aberto e extensível — licença MIT, 16 ferramentas documentadas, um destilado baseado em regras e um plugin de captura automática que você pode adaptar.

Funciona com outros harnesses

O th-memory-mcp é um servidor MCP padrão, então as 9 ferramentas funcionam em qualquer lugar onde MCP-over-stdio seja suportado. A captura automática completa (captura em segundo plano de prompts/ferramentas/erros + injeção de perfil) precisa de um runtime de hooks — o OpenCode tem isso integrado; o Claude Code obtém via nossa ponte de hooks; Codex e Cursor usam as ferramentas manualmente (sem runtime de hooks ainda).

RecursoOpenCodeClaude CodeQwen CodeCodexCursor
16 ferramentas MCP✅✅✅✅✅
Captura automática (segundo plano)✅ plugin✅ hooks⚠️ adaptador❌ manual❌ Rules
Injeção de perfil✅ compactação✅ UserPromptSubmit❌ get_profile❌ get_profile❌ get_profile
Busca semântica local✅ (v2.0)✅ (v2.0)✅ (v2.0)✅ (v2.0)✅ (v2.0)
  • Claude Code: consulte CLAUDE_CODE_HOOKS.md — hooks prontos replicam o plugin do OpenCode (captura + injeção de perfil em UserPromptSubmit/PreCompact, destilado baseado em regras em SessionEnd).
  • Qwen Code: consulte QWEN_SETUP.md — o MCP funciona totalmente; os hooks usam o esquema Gemini-CLI, então a captura automática precisa de um pequeno adaptador.
  • Codex: consulte CODEX_SETUP.md
  • Cursor: consulte CURSOR_SETUP.md

Todos os harnesses compartilham um único arquivo SQLite via MEMORY_DB_PATH, então a memória capturada em qualquer lugar é legível em todos os lugares.

Destaques

  • Memória estruturada — preferências com pontuação de confiança, além de registros dedicados de lesson (situação → erro → correção) para capturar correções, não apenas fatos simples.
  • Ciclo de vida e temporal — toda memória tem um estado de ciclo de vida (ativa/obsoleta/substituída/arquivada), pontuação de confiança/importância/saliência, decaimento por tipo e intervalos de validade para que a IA possa raciocinar sobre a verdade em um ponto no tempo e cadeias de substituição.
  • Ciente de conflitos — detecção de duplicatas, detecção de contradições e resolução de atualização/substituição preservam ambos os lados de evidências ambíguas em vez de sobrescrever silenciosamente.
  • Recuperação híbrida — get_context combina busca por palavras-chave FTS5 com um embedding vetorial local sem dependências (fusão RRF + pontuação) e depois monta um contexto com orçamento de tokens com expansão opcional do grafo de memória.
  • Consolidação — agrupamento periódico de memórias semelhantes em memórias derivadas com proveniência completa (links derived_from).
  • Tailandês / i18n de primeira classe — tokenização ciente de tailandês no destilado; a IA aceita tailandês e inglês de forma intercambiável.
  • Privado por padrão — um único arquivo SQLite local, sem nuvem, sem chaves de API, com linhas de segredo (api_key=, password:, token) filtradas antes do armazenamento.
  • Multi-harness — roda no OpenCode, Claude Code, Codex e Cursor compartilhando um único banco de dados; captura automática + injeção de perfil via plugin do OpenCode ou hooks do Claude.
  • Leve e resiliente — Node + better-sqlite3, sem extensões nativas extras; toda ferramenta degrada graciosamente para que a IA continue funcionando se o banco de dados estiver indisponível.

Scripts

ComandoDescrição
npm run buildcompila TypeScript → dist/
npm startexecuta o servidor MCP (stdio) a partir de dist/index.js
npm run distilldestilado baseado em regras: interações → seções de perfil + poda de dados antigos (env RETENTION_DAYS padrão 30)
npm testsuíte completa: captura, destilado, ciclo de vida, temporal, conflito, recuperação, grafo, contexto, consolidação, benchmark, segurança, tools_v21, smoke, e2e_transport, retrieval_benchmark, recall_regression, escopo, perfil, extração de entidades, conflict_benchmark
node test/capture.test.mjstesta o núcleo de captura (filtra segredos, deduplica, trunca, insere SQL)
node test/distill.test.mjstesta o núcleo de destilado (tokenização tailandesa, estatísticas, seções de perfil, poda)
node test/lifecycle.test.mjstesta o mecanismo de ciclo de vida (estados, decaimento, substituição)
node test/temporal.test.mjstesta o modelo temporal (validade, recuperação histórica)
node test/conflict.test.mjstesta a resolução de conflitos e deduplicação
node test/retrieval.test.mjstesta a recuperação híbrida FTS+vetorial+RRF
node test/graph.test.mjstesta o grafo de memória (entidades, relações, travessia)
node test/context.test.mjstesta a montagem de contexto + orçamento de tokens
node test/consolidation.test.mjstesta agrupamento + memórias derivadas
node test/benchmark.test.mjsbenchmark de latência sobre 300 memórias
node test/security.test.mjsverificações de injeção / segurança
node test/smoke.mjsteste smoke de ponta a ponta via JSON-RPC (16 ferramentas)

Ferramentas (16)

FerramentaDescrição
rememberupsert de preferência (categoria+chave) — salvar novamente a mesma chave aumenta a confiança em 0,1 (limite 1,0)
recallbusca preferências + lições (FTS5) + interações correspondentes recentes. Use antes de iniciar uma nova tarefa
get_profilevisão geral do perfil do usuário: seções de perfil + principais preferências + 5 lições mais recentes
save_lessonregistra uma lição aprendida com uma correção (situação / erro / correção)
search_historybusca prompts anteriores do usuário por palavra-chave (trechos de 200 caracteres por linha)
forgetexclui uma linha de memória (preferência/lição/interação) por id (+tipo evita conflito de id entre tabelas)
memory_statsestatísticas de memória: contagens por tipo, tamanho do banco de dados, interação mais antiga/mais recente, seções de perfil
get_recent_interactionslista interações brutas recentes (filtro por tipo) — matéria-prima para o Smart Distill
export_memoryexporta memória para JSON sob data/exports/ apenas (nome de arquivo auto-saneado)
get_contextmonta memórias relevantes para a tarefa atual via recuperação híbrida (+ expansão opcional do grafo) com orçamento de tokens
consolidateagrupa memórias semelhantes via similaridade de embedding; opcionalmente cria memórias derivadas/consolidadas vinculadas via derived_from
link_memorycria uma relação tipada entre duas memórias no grafo (supports/contradicts/supersedes/derived_from/related_to/caused_by/depends_on)
merge_memorymescla uma duplicata/quase duplicata em uma memória canônica (a origem se torna substituída, proveniência em metadata.merged_from)
update_memoryatualiza campos mutáveis no lugar, ou cria uma memória substituta quando content muda (defina supersede=false para editar no lugar)
import_memoryimporta memórias de JSON (valida tipo, deduplica contra existentes, nunca sobrescreve cegamente); dry-run por padrão, apply=true para inserir
extract_memoriesescaneia interações capturadas recentes em busca de frases de intenção de memória e propõe candidatos de memória (determinístico, sem LLM); dry-run por padrão, apply=true para criar (fonte=capturada)

Instalar com OpenCode

  1. Mescle a seção mcp de opencode.example.json no seu opencode.json (global ou nível de projeto)
    • Importante: defina MEMORY_DB_PATH para o MESMO arquivo de banco de dados tanto para o servidor quanto para o plugin (o exemplo usa <ABSOLUTE_PATH>/th-memory-mcp/data/memory.db), caso contrário o plugin de captura automática grava em um banco de dados diferente daquele que a IA lê
    • Como definir (escolha um):
      • defina no environment do mcp (veja o exemplo) — cobre apenas o servidor MCP
      • ou defina como variável de ambiente de nível de sistema/usuário (ex.: setx MEMORY_DB_PATH "D:/path/to/memory.db" no Windows) — cobre servidor e plugin, já que o plugin roda no mesmo processo do OpenCode
  2. Anexe as regras globais de memória — adicione a opencode.json: 
    "instructions": ["C:/Users/<user>/.config/opencode/memory-protocol.md"]
    (o conteúdo de exemplo das regras está em AGENTS.memory.example.md — pode ser anexado no nível do projeto)
  3. (Opcional) Implante o plugin de captura automática: copie src/plugin/learning-capture.ts → ~/.config/opencode/plugins/learning-capture.ts
  4. Reinicie o OpenCode (a configuração é carregada apenas na inicialização)
  5. Teste: "Lembre-se de que prefiro pnpm" → abra uma nova sessão e pergunte de volta

Uso diário

A IA aceita tailandês e inglês de forma intercambiável — você pode alternar de idioma a qualquer momento sem aviso.

Comando de exemploFerramenta / efeito
"Lembre que..."remember — salvar uma preferência
"Resumir memória" / "destilar memória"Destilação Inteligente — a IA lê get_recent_interactions, encontra padrões e salva insights por conta própria
"Como está minha memória?" / "status da memória"memory_stats
"Exportar memória" / "fazer backup da memória"export_memory
"Pesquisar histórico..."search_history
"Esquecer..."forget

Cuidados de longo prazo: execute npm run distill ocasionalmente para resumir estatísticas e podar interações com mais de 30 dias.

Estrutura de data/

data/
├── memory.db          # SQLite (WAL mode) — main DB (+ .db-wal, .db-shm)
└── exports/           # JSON files from export_memory (writeable only in this dir)
  • O caminho do banco de dados pode ser sobrescrito pela variável de ambiente MEMORY_DB_PATH
  • tudo em data/ é ignorado pelo git

Licença

MIT © 2026 worakorn-prince

Este projeto é licenciado sob a Licença MIT — consulte o arquivo LICENSE para o texto completo.