OpenMemBrain

OpenMemBrain é a membrana inteligente para a memória de codificação de IA. Ela lê e aprende autonomamente com suas sessões de codificação — você nunca precisa dizer a ela o que salvar. Ela absorve seletivamente o conhecimento do projeto, bloqueia segredos, filtra ruídos, resolve conflitos e persiste apenas o que importa.

GitHubExperimente este MCPPatrocinado

Documentação

OpenMembrane

OpenMembrane é a membrana inteligente para a memória de codificação com IA. Ela lê e aprende autonomamente com suas sessões de codificação — você nunca precisa dizer a ela o que salvar. Ela absorve seletivamente o conhecimento do projeto, bloqueia segredos, filtra ruídos, resolve conflitos e persiste apenas o que importa.

Sem esforço manual. Nenhum dado sai da sua máquina, a menos que você escolha. Segura, privada e confiável por design.

Sumário

Instalação
Configurando Sua Ferramenta de IA
Captura Automática de Memória
Variáveis de Ambiente
Ferramentas MCP
Arquitetura
Diagnóstico e Erros
Arquivos de Fallback Estáticos
Desenvolvimento
Documentação
Zero esforço — aprende com as sessões automaticamente, sem comandos ou prompts necessários
Seguro por padrão — segredos são detectados e rejeitados antes de chegarem ao armazenamento
Autogerenciável — deduplica, resolve conflitos e filtra ruídos por conta própria
Local primeiro — toda a memória permanece na sua máquina; sincronização em nuvem opcional hospedada na UE/CH
Independente de ferramenta — funciona com qualquer ferramenta de codificação com IA via MCP (Claude, Copilot, Cursor, OpenCode e outras)

Instalação

Instale e execute o servidor MCP com npx (requer Node.js >= 18):

npx openmembrane

Ou instale globalmente:

npm install -g openmembrane
openmembrane

Nenhuma conta em nuvem é necessária. Toda a memória é armazenada localmente.

Configurando Sua Ferramenta de IA

O OpenMembrane roda como um servidor MCP sobre stdio. Adicione-o à configuração MCP da sua ferramenta de IA:

Claude Desktop

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}

Claude Code

claude mcp add openmembrane -- npx openmembrane

VS Code / GitHub Copilot

Adicione a .vscode/mcp.json no seu projeto:

{
  "servers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}

Cursor

Adicione a .cursor/mcp.json no seu projeto:

{
  "mcpServers": {
    "openmembrane": {
      "command": "npx",
      "args": ["openmembrane"]
    }
  }
}

OpenCode

Adicione a ~/.config/opencode/opencode.json:

{
  "mcp": {
    "openmembrane": {
      "type": "local",
      "command": ["npx", "-y", "openmembrane"]
    }
  }
}

Consulte .opencode/INSTALL.md para configuração detalhada, incluindo instruções globais e configuração de desenvolvimento a partir do código-fonte.

Captura Automática de Memória

Adicionar o servidor MCP dá à sua ferramenta de IA acesso às ferramentas do OpenMembrane. Para garantir que a IA as use automaticamente — carregando a memória do projeto no início da sessão e salvando conhecimento durável conforme é descoberto — adicione um arquivo de instrução global.

Crie ~/.config/openmembrane/instructions.md com instruções para a IA:

Chamar get_project_rules, get_relevant_context e list_memory_candidates no início de cada sessão.
Chamar remember proativamente quando conhecimento durável for descoberto, fornecendo conteúdo estruturado e um tipo (por exemplo, coding_rule, known_gotcha, architecture_decision). Nenhuma chave de API é necessária.

Em seguida, conecte o arquivo à configuração global da sua ferramenta:

Plataforma	Mecanismo de instrução global
OpenCode	`"instructions": ["~/.config/openmembrane/instructions.md"]` em `~/.config/opencode/opencode.json`
Claude Code	Anexe a `~/.claude/CLAUDE.md`
Cursor	Adicione às Regras para IA nas Configurações do Cursor
VS Code / Copilot	Crie `~/.copilot/instructions/openmembrane.instructions.md` com `applyTo: "**"`

Consulte os guias de configuração específicos da plataforma em docs/setup/ para instruções detalhadas.

Alternativamente, execute export_static_memory_files em qualquer projeto para gerar arquivos de instrução por projeto (AGENTS.md, CLAUDE.md, etc.) que incluem tanto instruções de uso quanto memórias armazenadas.

Variáveis de Ambiente

Por padrão, a memória local é armazenada em .openmembrane no diretório de trabalho atual. Substitua isso com:

OPENMEMBRANE_HOME: diretório para armazenamentos de memória JSON locais.
OPENMEMBRANE_PROJECT_ID: id de projeto padrão quando uma chamada de ferramenta não passa projectId.

Ferramentas MCP

remember — salva memória estruturada diretamente. Forneça conteúdo, tipo e escopo/tags opcionais. Nenhuma chave de API é necessária. Suporta modo único e em lote.
propose_memory_from_session — envia uma transcrição ou resumo de sessão para extração LLM no lado do servidor. Requer um extrator configurado. Útil para adaptadores de automação.
get_project_rules — recupera regras e convenções do projeto para o escopo atual.
get_relevant_context — encontra memórias relevantes para uma consulta em linguagem natural.
search_memory — pesquisa memórias salvas por consulta, escopo, tipo ou tags.
list_memory_candidates — lista candidatos de memória pendentes aguardando aprovação.
approve_memory_candidate — aprova um candidato pendente para salvá-lo como memória.
approve_all_candidates — aprova todos os candidatos pendentes de uma vez.
reject_memory_candidate — rejeita um candidato pendente com um motivo opcional.
reject_all_candidates — rejeita todos os candidatos pendentes de uma vez.
update_memory — atualiza o conteúdo, tipo, escopo ou tags de uma memória salva.
supersede_memory — marca uma memória como substituída, opcionalmente vinculando uma substituição.
review_stale_memories — lista memórias mais antigas que um limite (padrão: 6 meses).
export_static_memory_files — gera arquivos de instrução estáticos (AGENTS.md, CLAUDE.md, etc.).
get_diagnostics — recupera eventos de diagnóstico filtrados por severidade ou código.
list_audit_log — recupera eventos de auditoria recentes.

Arquitetura

O OpenMembrane suporta dois caminhos para salvar memória:

remember (primário): A ferramenta de IA chama remember diretamente com conteúdo estruturado e tipo. Nenhum LLM no lado do servidor é necessário. As memórias passam pelo pipeline completo (detecção de segredos, filtragem de políticas, deduplicação) e são salvas automaticamente.
propose_memory_from_session (secundário): Um adaptador ou ferramenta de IA envia uma transcrição completa da sessão para extração LLM no lado do servidor. Requer um extrator configurado (OpenAI ou provedor compatível).

remember tool                          propose_memory_from_session
  |                                      |
  v                                      v
processStructured()                    SessionIngestor
  |                                      -> SecretDetector redaction
  v                                      -> MemoryExtractor interface
MemoryClassifier                         -> MemoryClassifier
  -> PolicyEngine                        -> PolicyEngine
  -> Deduplicator                        -> Deduplicator
  -> ConflictDetector                    -> ConflictDetector
  -> ActionRecommender                   -> ActionRecommender
  -> MemoryStore or PendingCandidateStore

Responsabilidades dos pacotes:

packages/core: tipos de domínio, interface de extração, verificações de políticas, classificação, deduplicação, detecção de conflitos e orquestração do pipeline.
packages/storage: persistência JSON local para memória salva, aprovações pendentes e eventos de auditoria.
packages/exporters: geração de arquivos de fallback estáticos para ferramentas de IA que leem arquivos de instrução do projeto.
packages/shared: pequenos utilitários de runtime para IDs, tempo e tipos de resultado.
apps/mcp-server: servidor MCP local expondo memória salva e fluxos de trabalho de aprovação para ferramentas de IA.

Chamadas LLM específicas de provedores são intencionalmente mantidas fora do núcleo. O limite é:

interface MemoryExtractor {
  extract(input: SessionInput): Promise<MemoryCandidate[]>;
}

O MockMemoryExtractor é usado para testes determinísticos. O LlmMemoryExtractor suporta OpenAI e qualquer endpoint de API compatível (via baseUrl).

Diagnóstico e Erros

O OpenMembrane distingue histórico de auditoria de diagnóstico:

Eventos de auditoria descrevem atividade normal de memória, como ingestão de sessão, extração de candidatos, memória salva, candidatos na fila e candidatos rejeitados.
Diagnósticos descrevem problemas operacionais, como erros de validação, candidatos ausentes, armazenamentos JSON locais inválidos, tentativas de aprovação inseguras e falhas de exportação.

As ferramentas MCP retornam payloads de erro seguros voltados ao usuário com um diagnosticId. O diagnóstico detalhado pode ser inspecionado através de get_diagnostics sem expor transcrições brutas ou segredos.

Arquivos de Fallback Estáticos

Os exportadores estáticos podem gerar:

AGENTS.md
CLAUDE.md
.github/copilot-instructions.md
.cursor/rules/openmembrane.mdc
docs/ai/project-memory.md

Esses arquivos são fallbacks de compatibilidade para ferramentas que não podem recuperar memória via MCP. Por padrão, os exportadores omitem memórias confidential porque esses arquivos podem ser commitados no controle de versão. Os chamadores devem optar explicitamente para incluir memória confidencial.

Desenvolvimento

git clone https://github.com/mohamadalhusseinie/openmembrane.git
cd openmembrane
npm install

Execute o servidor MCP localmente (a partir do código-fonte via tsx):

npm run mcp:stdio

Execute testes e verificação de tipos:

npm test          # vitest
npm run typecheck # tsc --noEmit
npm run check     # both

Construa o pacote publicável:

npm run build

Documentação

Arquitetura — design do pipeline, esquemas de tipos, superfície de ferramentas MCP, dependências de pacotes
Segurança e Privacidade — tratamento de segredos, regras de armazenamento de dados, política de uso de LLM
Visão do Produto — tese do produto, fluxo de trabalho UX, critérios de qualidade de memória
Roadmap — plano de entrega em fases do MVP local ao modo hospedado
Contribuindo — configuração, fluxo de trabalho de desenvolvimento, diretrizes de PR