MCP Light Memory

Memória persistente local-first para agentes de codificação que preserva o contexto relevante do projeto entre sessões e reduz o uso desnecessário de tokens.

GitHubExperimente este MCPPatrocinado

Documentação

MCP Light Memory

Memória persistente leve, local-first, para agentes de codificação e clientes MCP.
anteriormente internal-rag

O que é isso?

MCP Light Memory é um sistema de memória persistente, leve, local-first, para agentes de codificação e clientes MCP (Warp, OpenCode, JetBrains AI Assistant / PyCharm, Claude Code, Cursor). Ele atua como uma camada de checkpoint + recuperação — armazena o estado durável mínimo necessário para retomar trabalhos complexos entre sessões, sem manter a conversa completa no contexto do modelo.

Quando seu agente inicia uma tarefa, ele chama context e recebe decisões passadas relevantes, armadilhas, restrições e hipóteses — ranqueadas, deduplicadas e com limite de confiança. Quando termina, ele faz checkpoint do estado de trabalho. Na próxima sessão, mesmo após um reinício, a memória está lá.

Por que usar?

Problema	Como o MCP Light Memory resolve
Agentes esquecem tudo entre sessões	Arquivos Markdown persistem em disco; o agente os recupera via BM25 + embeddings opcionais
Histórico completo da sessão é grande demais para o contexto	Apenas memórias relevantes são recuperadas (com orçamento de tokens, diversificadas por MMR)
Dependência de nuvem / preocupações com privacidade	100% local, offline, zero chamadas de rede, sem daemon
Setup pesado / dependências	Zero dependências de runtime obrigatórias (stdlib pura Python 3.8+); `sentence-transformers` opcional para melhor recuperação semântica
Injeção de prompt via memória armazenada	Cada memória recuperada é explicitamente `trust: untrusted` evidência com heurística de aviso de injeção (ADR-015)
Isolamento multi-projeto	Roteador com allowlist de registro, `write:false` limite rígido, isolamento por subprocesso por chamada
Deriva do protocolo MCP	Suporte a duas eras: `2026-07-28` moderno + `2024-11-05` legado…`2025-11-25`

Como funciona (mecanismos)

Markdown é a fonte da verdade. Cada memória é um arquivo .md com frontmatter YAML (id, type, status, tags, sources, links, valid_from, valid_to, supersedes). Legível por humanos, diffable, durável.
SQLite é um cache reconstruível. Índice BM25/FTS5 + vetores de embedding opcionais + rastreamento de uso. Delete-o e tudo é reconstruído a partir do Markdown.
Recuperação: BM25 puro em Python + embeddings densos opcionais → fusão RRF → diversificação MMR → boosts de política (tipo/status/temporal) → corte por orçamento de tokens. Modo adaptativo: esparso primeiro, denso apenas se fraco.
Ciclo de vida: remember → update → supersede (vincula em ambas as direções, nunca exclui histórico) → forget (arquiva, nunca exclui) → timeline (visão temporal). search --at YYYY-MM-DD para consultas históricas.
Limite de confiança: o conteúdo recuperado é envolvido em === BEGIN/END INTERNAL_RAG MEMORY === com um cabeçalho SECURITY NOTICE. JSON/MCP estruturado carrega trust: untrusted + security_flags: ["instruction_like_content"] opcional.
Frescor da evidência: cada resultado inclui evidence_state (present/missing/unverifiable) para evidência local semelhante a caminho — derivado no momento da recuperação, nunca persistido.
Roteador multi-projeto: um servidor MCP stdio na frente de muitos projetos via registro JSON. write:false bloqueia ferramentas de mutação antes de gerar um filho. Isolamento por subprocesso por chamada (sem estado compartilhado).

Configuração

Pré-requisitos

Python 3.8+ (usa o launcher py, python ou python3 — o instalador detecta automaticamente o interpretador real e rejeita o stub do WindowsApps)
Git (o projeto alvo deve ser um repositório git)
Opcional: pip install sentence-transformers numpy para melhor recuperação semântica

A versão atual é definida pelo arquivo VERSION — verifique-o (ou execute mlm.py --version) em vez de codificar um número esperado.

Início rápido

Clone este repositório uma vez e instale em qualquer projeto:

# Windows (PowerShell)
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python ~/mcp-light-memory/install.py . --client warp

# Linux/macOS
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python3 ~/mcp-light-memory/install.py . --client warp

O instalador:

copia arquivos de skill + cria INTERNAL_RAG/ + AGENTS.md
executa init + checkpoint + validate (para que guard seja OK imediatamente)
registra automaticamente o servidor MCP na configuração do cliente quando pode fazê-lo com segurança (ou relata MANUAL_REQUIRED / imprime instruções do JetBrains)
escreve o caminho absoluto para o interpretador Python verificado (sobrevive a problemas de PATH do Windows)

python .agents\skills\internal-rag\mlm.py --version   # reports the installed version
python .agents\skills\internal-rag\mlm.py status       # expect: INTERNAL_RAG ready
python .agents\skills\internal-rag\mlm.py guard        # expect: GUARD OK

Matriz de instalação

Um instalador, quatro clientes, dois escopos de configuração. Guia completo: docs/INSTALLATION.md.

Cliente	Escopo do projeto	Escopo global
Warp (gravação de configuração automática; ativação do projeto pode exigir aprovação)	`install.py . --client warp`	`install.py . --client warp --global`
OpenCode stable (V1) (automático para gravações seguras de JSON)	`install.py . --client opencode`	`install.py . --client opencode --global`
OpenCode 2 (V2, beta) (automático para gravações seguras de JSON)	`install.py . --client opencode2`	`install.py . --client opencode2 --global`
JetBrains AI / PyCharm (manual na UI do IDE)	`install.py . --client jetbrains`	`install.py . --client jetbrains --global`

--global altera o escopo da CONFIGURAÇÃO DO CLIENTE (~/.warp/.mcp.json vs {repo}/.warp/.mcp.json, ~/.config/opencode/opencode.json vs projeto opencode.json). O servidor ainda aponta para o projeto alvo onde você instalou.
Precisa de um endpoint MCP global para muitos repositórios? Use o roteador multi-projeto — docs/MCP-MULTI-PROJECT.md.
JetBrains/PyCharm é assistido, não totalmente automático: o instalador prepara o JSON + Diretório de Trabalho; você adiciona o servidor em Settings → Tools → AI Assistant → MCP e escolhe Server level = Project ou Global.
Configuração manual (sem instalador) por cliente: docs/INSTALLATION.md + páginas de clientes (Warp · OpenCode).

Zero-shot: prompts de copiar e colar para Warp e OpenCode

Você pode colar um destes diretamente no agente do cliente. Substitua C:\Projects\App pelo caminho real do repositório alvo.

Warp — instalar para um projeto:

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in Warp, using project scope. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, update it with git pull --ff-only. Apply the canonical installation contract from the repository and run install.py with TARGET_PROJECT=C:\Projects\App and --client warp without --global. Do not force-overwrite an existing configuration. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification. If Warp requires an additional project activation/toggle/approval, state the exact client-side step and do not claim the server is active before it is completed.

Warp — configuração global do cliente para um projeto:

Install and configure MCP Light Memory (mcp-light-memory) in Warp globally for project C:\Projects\App. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Apply the canonical installation contract and run install.py with TARGET_PROJECT=C:\Projects\App, --client warp, and --global. Remember: --global means the global Warp client configuration, while the server must still be bound to C:\Projects\App; do not use the multi-project router. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification.

OpenCode — instalar para um projeto (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in OpenCode. By "OpenCode" I mean stable/V1, so use --client opencode, not opencode2. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App and --client opencode without --global. Do not force-overwrite an existing configuration. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED (for example because opencode.jsonc exists), do not report success: safely edit the JSONC while preserving comments and unrelated settings if you have appropriate file-editing tools; otherwise report the exact manual action required. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the OpenCode configuration contains mcp-light-memory and C:\Projects\App.

OpenCode — configuração global do cliente para um projeto (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) globally in OpenCode for project C:\Projects\App. By "OpenCode" I mean stable/V1, so use --client opencode. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App, --client opencode, and --global. --global means the global OpenCode client configuration, while the server must still be bound only to C:\Projects\App; do not use the multi-project router. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED, do not report success and follow the safe JSONC instructions. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global OpenCode configuration contains mcp-light-memory and the C:\Projects\App path.

Para OpenCode 2 / V2, use os mesmos prompts, mas diga explicitamente OpenCode 2 / V2 e exija --client opencode2. Mais variantes: docs/ZERO-SHOT-SETUP-PROMPTS.md.

Detalhes de configuração

Warp

O Warp lê configurações de servidor MCP de ~/.warp/.mcp.json (global, auto-spawn) ou {repo}/.warp/.mcp.json (projeto, requer alternância manual conforme documentação do Warp). Formato: mcpServers.<name> com command, args, working_directory (sempre defina — o armazenamento de memória é resolvido a partir dele). Veja examples/warp.example.json e docs/WARP-SETUP.md.

OpenCode stable (V1)

O OpenCode lê opencode.json/.jsonc na raiz do projeto, ou ~/.config/opencode/opencode.json globalmente. Servidores V1 são planos sob mcp.<name> (sem sub-chave servers) com enabled: true e command como um array — veja examples/opencode-legacy.example.json e docs/OPENCODE.md.

OpenCode 2 (V2, beta)

Mesmos arquivos de configuração, formato diferente: mcp.servers.<name>, command como um array, e sem campo enabled (V2 desativa via disabled: true) — veja examples/opencode-v2.example.jsonc e docs/OPENCODE.md.

JetBrains AI Assistant / PyCharm

O PyCharm NÃO lê automaticamente nenhum arquivo de configuração MCP. O instalador imprime JSON pronto para colar + Diretório de Trabalho; você adiciona o servidor em Settings → Tools → AI Assistant → MCP (STDIO) e escolhe Server level = Project ou Global. Veja examples/jetbrains.example.json.

Roteador multi-projeto

Uma conexão MCP na frente de muitos projetos — allowlist de registro, write:false limite rígido, isolamento por subprocesso por chamada.

Arquivo de registro (`projects.json`)

{
  "projects": {
    "backend": { "root": "/abs/path/backend", "write": true },
    "shared-lib": { "root": "/abs/path/shared-lib", "write": false }
  }
}

Configuração do Warp para o roteador

{
  "mcpServers": {
    "mcp-light-memory-router": {
      "command": "python3",
      "args": ["/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py", "--registry", "/abs/path/projects.json"],
      "working_directory": "/abs/path/mcp-light-memory"
    }
  }
}

Veja docs/MCP-MULTI-PROJECT.md para detalhes.

Fluxo de trabalho

context --task "current task"
  ↓
recovery, if required (RECOVERY REQUIRED)
  ↓
checkpoint before first change
  ↓
implementation
  ↓
checkpoint after each milestone
  ↓
guard before finishing

Comandos principais (alias CLI: mlm.py ou legado irag.py):

mlm.py context --task "..."
mlm.py checkpoint --reason "..."
mlm.py search --query "..." --limit 8
mlm.py remember --type decision --title "..." --body "..."
mlm.py show <ref>
mlm.py update <ref> --status superseded
mlm.py status
mlm.py guard
mlm.py validate
mlm.py doctor

Mapeamento de caminhos (rebrand: internal-rag → MCP Light Memory)

Novo nome	Caminho legado (mantido para compatibilidade)
`MCP Light Memory` (produto)	`internal-rag` (nome de produto obsoleto)
`mlm` / `mlm.py` (CLI principal)	`irag.py` (alias legado, ainda funciona)
`mcp-light-memory` (nome do servidor MCP)	`internal-rag` (legado, ainda funciona em configurações)
`mcp-light-memory-router` (nome do roteador)	`internal-rag-router` (legado)
`INTERNAL_RAG/` (pasta de armazenamento — inalterada)	—
`.agents/skills/internal-rag/` (diretório de skills — inalterado)	—

A pasta em disco INTERNAL_RAG/ e o diretório de skills .agents/skills/internal-rag/ são intencionalmente mantidos sob seus nomes legados para compatibilidade zero-migration. Veja docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md.

Memória durável (CRUD)

remember --type decision --title "..." --body "..." --tags "a,b" --evidence "src/x.py:42" --links "decisions/other.md"
show <path-or-id>
show <ref> --section Knowledge
update <ref> --add-tags "new" --append "New evidence: ..."
supersede <ref> --by <new> --reason "..."
forget <ref>              # archives, does not delete
link --from <ref> --to <ref>
timeline --limit 20
status
history

Tipos: decision, knowledge, constraint, gotcha, failure, hypothesis, session.

Pilha de tarefas (interrupções)

mlm.py push --task "interrupted work" --reason "user-priority"
mlm.py tasks
mlm.py resume
mlm.py forget-task <id>   # drop a specific task
mlm.py forget-task         # clear the whole stack

Configuração (`.irag.yml`, opcional)

retrieval:
  limit: 10
  mmr_lambda: 0.4
  min_score: 0.3
  embeddings: auto        # auto | on | off
  profile: english-fast   # english-fast (default) | multilingual (PL/EN projects)
  embeddings_model: null  # explicit model overrides the profile
tokens:
  context_budget: 5000
checkpoints:
  auto_archive_sessions: true
  max_task_stack: 24

mlm.py config mostra a configuração efetiva. mlm.py config --init escreve um modelo.

Embeddings opcionais (melhor recuperação)

pip install -r requirements-optional.txt

Quando o pacote está disponível e .irag.yml tem embeddings: auto (padrão), a recuperação usa embeddings com fallback para BM25. Substitua em tempo de execução com --embeddings on|off|auto.

Dois perfis de recuperação (veja docs/EMBEDDINGS.md):

english-fast (padrão, all-MiniLM-L6-v2)
multilingual (intfloat/multilingual-e5-small) — para projetos polonês-inglês

Offline / air-gapped

python pack.py --with-embeddings --profile english-fast
# -> internal-rag-offline-1.8.1.zip   (name from pack.py; 1.8.1 = VERSION file)
# On the air-gapped machine:
unzip internal-rag-offline-*.zip -d internal-rag-offline
pip install --no-index --find-links wheels/ -r requirements-optional.txt
python install.py "/path/to/project" --client <warp|opencode|opencode2|jetbrains>

Veja docs/OFFLINE.md para detalhes.

Privacidade e Git

O modo de instalação padrão é somente local. O instalador usa .git/info/exclude, não o .gitignore do projeto, para que a memória local e os arquivos de integração não sejam commitados acidentalmente.

Antes de publicar um projeto:

python .\privacy_check.py "D:\path\to\project"

Esperado: RESULT: PASS

Remoção completa de um projeto

python .\uninstall.py "D:\path\to\project"

O desinstalador cria um backup fora do repositório e remove INTERNAL_RAG e suas integrações. Use --keep-memory para preservar os dados de memória.

Documentação

Instalação · Uso diário · Referência CLI
Arquitetura · Ciclo de vida da memória · Recuperação
MCP · MCP multi-projeto
Decisões de arquitetura (ADR) · Configuração
Embeddings · Offline · Git hooks
Privacidade e Git · Desinstalação · Solução de problemas
Prompts de setup zero-shot · Migração · Branding

Estrutura em um projeto alvo

project/
├── AGENTS.md
├── .irag.yml                    # optional config
├── INTERNAL_RAG/
│   ├── WORKING_STATE.md
│   ├── INDEX.md
│   ├── .checkpoint.json
│   ├── decisions/  knowledge/  gotchas/  failures/  hypotheses/  sessions/  archive/
│   └── exports/
├── .agents/skills/internal-rag/
│   ├── SKILL.md
│   ├── mlm.py                   # primary CLI (forwards to irag.py)
│   ├── irag.py                  # core (legacy alias, still the canonical module)
│   ├── irag_embeddings.py       # optional plugin
│   └── irag_hooks.py            # optional git hooks
└── .opencode/                   # OpenCode integration (optional)

Fonte da verdade

instruções atuais do usuário, 2. código/testes/configuração atuais, 3. especificações/ADRs, 4. memória verificada, 5. notas de sessão, 6. hipóteses.

A memória pode estar desatualizada. O código tem precedência.

Licença

MIT.

Changelog

1.8.0 — Configuração manual do JetBrains

--client jetbrains não escreve mais um arquivo de configuração falso (o PyCharm ignora arquivos de configuração MCP). Imprime JSON pronto para colar + instruções de menu do IDE.
--unregister --client jetbrains imprime um lembrete para remover na UI do IDE.

1.7.2 — cwd do JetBrains + mensagens específicas do cliente

JetBrains: grava working_directory como dica + imprime WARNING com o caminho exato para definir em Settings → Tools → AI Assistant → MCP.
Mensagens de reinicialização específicas do cliente (Reiniciar PyCharm / Reiniciar Warp / Reiniciar OpenCode).
Memory store: <path> impresso na saída da instalação para verificação imediata.

1.7.1 — Correção do stub do Python no Windows

detect_python() rejeita o stub de 0 bytes do WindowsApps; prefere py -0p; verifica cada candidato com --version.
Verificação pós-registro: executa --version imediatamente após gravar a configuração e relata PASS/FAIL.
--unregister exclui arquivos de configuração vazios + diretórios pai (corrige o esqueleto morto .warp/.mcp.json → GUARD STALE).

1.7.0 — Rebranding para MCP Light Memory

Rebranding total de internal-rag para MCP Light Memory (mcp-light-memory). Novo alias de CLI mlm (mlm.py). Assets de logo/ícone. Documento de migração. Checklist de rebranding no GitHub.
Compatível com versões anteriores: irag.py, INTERNAL_RAG/, nomes antigos do servidor MCP preservados como aliases obsoletos.
18 testes de consistência do rebranding.

1.6.1 — Endurecimento pós-v1.6

Benchmark de mutação/ciclo de vida (11 cenários). Limite de confiança (ADR-015): trust: untrusted + security_flags. Frescor de evidências (ADR-016): evidence_state. Benchmark de escala (100/1k/10k). Regressões de segurança do roteador (+12 testes). Teste de consistência da documentação. 249 testes aprovados.

1.6.0 — Qualidade de recuperação + MCP 2026-07-28

Benchmark de qualidade de memória (37 casos). MCP 2026-07-28 de dupla era (server/discover, _meta, structuredContent, outputSchema). Registro estrito write. Fontes no prefixo do chunk. Recuperação adaptativa. Contexto ciente de links. consolidate --prepare. Benchmark de latência do roteador. ADR-010…016.

1.5.0 — Portão de abstenção + roteador multi-projeto

Portão de relevância/abstenção (--meta). Pré-filtro de candidatos FTS5. Roteador MCP multi-projeto. Endurecimento do protocolo MCP (stdout puro, verificado por SDK). 168 testes.

1.4.0 — Chunking + deduplicação + ciclo de vida temporal

Chunking ciente de seções (schema v3). Deduplicação SimHash. Perfil multilíngue PL/EN. Ciclo de vida temporal (valid_from/valid_to/supersedes/--at). consolidate --dry-run.

1.3.0 — Cache de embeddings persistente

BLOBs float32 no nível de chunk no SQLite. Vários modelos coexistem. index --vacuum/--embed-missing.

1.0.2 — Orçamento de tokens + privacidade

Aplicação do orçamento de tokens. Detecção de memória obsoleta. Detecção de duplicatas. Verificação de privacidade no momento da gravação. Temporizador automático de checkpoint. Pacote offline/air-gapped.

1.0.0 — Lançamento inicial

Recuperação BM25 + MMR. CRUD completo de memória. Pilha de tarefas. Servidor MCP (JSON-RPC stdio). Hooks do Git. Diagnósticos. Exportação/importação. Orçamento de tokens.

MCP Light Memory

Documentação

MCP Light Memory

O que é isso?

Por que usar?

Como funciona (mecanismos)

Configuração

Pré-requisitos

Início rápido

Matriz de instalação

Zero-shot: prompts de copiar e colar para Warp e OpenCode

Detalhes de configuração

Warp

OpenCode stable (V1)

OpenCode 2 (V2, beta)

JetBrains AI Assistant / PyCharm

Roteador multi-projeto

Arquivo de registro (projects.json)

Configuração do Warp para o roteador

Fluxo de trabalho

Mapeamento de caminhos (rebrand: internal-rag → MCP Light Memory)

Memória durável (CRUD)

Pilha de tarefas (interrupções)

Configuração (.irag.yml, opcional)

Embeddings opcionais (melhor recuperação)

Offline / air-gapped

Privacidade e Git

Remoção completa de um projeto

Documentação

Estrutura em um projeto alvo

Fonte da verdade

Licença

Changelog

1.8.0 — Configuração manual do JetBrains

1.7.2 — cwd do JetBrains + mensagens específicas do cliente

1.7.1 — Correção do stub do Python no Windows

1.7.0 — Rebranding para MCP Light Memory

1.6.1 — Endurecimento pós-v1.6

1.6.0 — Qualidade de recuperação + MCP 2026-07-28

1.5.0 — Portão de abstenção + roteador multi-projeto

1.4.0 — Chunking + deduplicação + ciclo de vida temporal

1.3.0 — Cache de embeddings persistente

1.0.2 — Orçamento de tokens + privacidade

1.0.0 — Lançamento inicial

Arquivo de registro (`projects.json`)

Configuração (`.irag.yml`, opcional)