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 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
Modos de Implantação
Variáveis de Ambiente
Ferramentas MCP
Arquitetura
Diagnósticos 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 e privado por padrão — a memória é armazenada localmente em .openmembrane/ ignorado pelo git
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 para o modo Local Privado padrão, que armazena memória localmente em .openmembrane/ ignorado pelo git.

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 à medida que é 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.

Modos de Implantação

O OpenMembrane vem com o modo Local Privado por padrão e o modo GitHub Team para memória compartilhada por meio de um repositório privado dedicado. Os modos Self-Hosted Team e Managed Team estão planejados. Arquivos exportados estáticos são separados da sincronização de equipe; consulte Modos de Implantação para o limite de memória aprovada e o fluxo de trabalho de pull request do GitHub.

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ósticos e Erros

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

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 por meio 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 por 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

Compile 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
Modos de Implantação — modos atuais Local Privado e GitHub Team, além dos modos de equipe planejados
Roadmap — plano de entrega em fases para Local Privado, GitHub Team e modos de equipe planejados
Contribuindo — configuração, fluxo de trabalho de desenvolvimento, diretrizes de PR