BM · Barroso Memory

Memória persistente para o seu agente de IA.

O BM guarda o que importa em arquivos Markdown OKF v0.2 no seu próprio diretório. Qualquer agente lê e escreve por MCP, local primeiro — e, com o sync Git opcional, cada escrita vira commit no seu repositório. Sem backend, sem nuvem obrigatória.

Instalar agora Ver release no GitHub
OKF v0.2 9 tools MCP sync Git opcional 0 backend
sem nuvem

Local primeiro

Um diretório com Markdown é uma memória completa. Sem Git, sem servidor, sem conta — funciona offline, no seu projeto ou num pendrive.

OKF v0.2

Feito para agentes

Conceitos com frontmatter, índices, log e grafo de links. O agente busca, lê, valida e escreve pelas tools MCP — não por grep.

git puro

Sync opcional e automático

Habilite com um comando e a memória vira repositório: cada escrita valida, commita e empurra via Git puro. Vários agentes, um repositório — conflito de conceito nunca é sobrescrito em silêncio.

01

Instalar

O BM é um binário único, sem dependências — o comando se chama okf (herança do okf-agent-memory que o originou). Baixe para o seu sistema ou compile do fonte.

PowerShell
mkdir "$env:USERPROFILE\.local\bin" -Force
Invoke-WebRequest "https://github.com/ruanbarroso/okf-agent-memory/releases/latest/download/okf-windows-amd64.exe" -OutFile "$env:USERPROFILE\.local\bin\okf.exe"
$p = [Environment]::GetEnvironmentVariable("Path","User")
[Environment]::SetEnvironmentVariable("Path", "$p;$env:USERPROFILE\.local\bin", "User")

Abra um novo terminal (para o PATH recém-atualizado) e confirme: okf version → okf version v0.4.2-bm.1 (OKF v0.2 specification)

02

Criar sua memória

Um comando cria o bundle OKF v0.2 — estrutura de diretórios, index.md, log.md e o registro de conceitos. Pronto para o agente usar.

passo 1 · local

O bundle, puro Markdown

PowerShell / bash
$ okf init ~/memoria
$ okf validate ~/memoria
passo 2 · opcional

Sync Git, automático

PowerShell / bash
$ okf sync init ~/memoria
$ git -C ~/memoria remote add origin [email protected]:seu-usuario/sua-memoria.git
o agente escreve valida OKF v0.2 commita e empurra e o ciclo recomeça sozinho a cada escrita

Sem esse passo, o BM é 100% local — Git nunca é obrigatório. Com o sync ligado, vários agentes podem escrever no mesmo repositório: pushes rejeitados resolvem por fetch + rebase, log.md e index.md se unem sozinhos, e conflito no mesmo conceito para para resolução manual — nada é sobrescrito em silêncio. Detalhes no guia de sync.

03

Apontar seu agente (MCP)

O BM é um servidor MCP (stdio, JSON-RPC). Basta apontar qualquer agente para o comando okf mcp <caminho-da-memória>. A configuração abaixo funciona na maioria dos clientes:

configuração base
{
  "mcpServers": {
    "bm": {
      "command": "okf",
      "args": ["mcp", "~/memoria"]
    }
  }
}

Claude Code

um comando, vale para todas as sessões (-s user)
terminal
$ claude mcp add -s user bm -- okf mcp ~/memoria

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json · ~/Library/Application Support/Claude/claude_desktop_config.json
json
{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

Cursor

~/.cursor/mcp.json (global) · .cursor/mcp.json (por projeto)
json
{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json
json
{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

OpenCode

opencode.json (global ou do projeto)
json
{
  "mcp": {
    "bm": { "type": "local", "command": ["okf", "mcp", "~/memoria"] }
  }
}

Qualquer outro agente

procure por “MCP servers” na documentação do seu agente

Se o cliente aceita servidores MCP stdio, o comando é sempre okf mcp <caminho-da-memória>. Use a configuração base acima no formato que o seu agente pedir.

No Windows, caminho no JSON usa barra dupla: "args": ["mcp", "C:\\Users\\voce\\memoria"]. Reinicie o agente após salvar a configuração — o BM aparece na lista de servidores como bm.

04

O que o agente ganha

Nove tools MCP, tudo validado contra o OKF v0.2 — busca, leitura, escrita com bookkeeping automático de log.md e index.md, validação de conformidade e controle do sync Git.

okf_search

Busca conceitos por termos, tags e títulos (BM25), ou por caminho de código via code_refs.

okf_show

Mostra um conceito e suas relações.

okf_validate

Valida conformidade OKF v0.2, conectividade do grafo e drift de descrições.

okf_create

Cria conceito com registro automático em log.md e index.md.

okf_update

Atualiza um conceito existente.

okf_relate

Liga dois conceitos com descrição de contexto.

okf_sync_statussync

Estado do sync Git: habilitado, branch, arquivos sujos, ahead/behind.

okf_sync_refreshsync

Puxa a branch configurada do remote (fetch + fast-forward/rebase).

okf_sync_publishsync

Valida, commita e empurra agora — o mesmo fluxo do sync automático.

Com o sync habilitado, o servidor MCP publica sozinho depois de cada escrita (agrupando com debounce e fazendo flush no encerramento) e atualiza o bundle a partir do remote na inicialização da sessão.

Seu agente nunca mais esquece.

Instale, aponte o agente, e a memória passa a crescer sozinha — conceito por conceito, commit por commit.

Instalar o BM Ver o código no GitHub