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

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.

Feito para agentes

Formato OKF v0.2: conceitos com frontmatter, índices, log e grafo de links. O agente busca, lê, valida e escreve pelas tools MCP — não por grep.

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.

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.

Windows

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)

Linux / macOS

bash

curl -fsSL -o /tmp/okf https://github.com/ruanbarroso/okf-agent-memory/releases/latest/download/okf-linux-amd64
sudo install -m 755 /tmp/okf /usr/local/bin/okf
okf version

Arquivo na release	Sistema
okf-linux-amd64	Linux x64
okf-linux-arm64	Linux ARM64 (Raspberry Pi 4+, servidores ARM)
okf-darwin-arm64	macOS Apple Silicon (M1 em diante)
okf-darwin-amd64	macOS Intel

Não sabe a arquitetura? Rode uname -m: x86_64 = amd64, aarch64/arm64 = arm64. No macOS, troque a linha do curl pelo arquivo darwin correspondente.

Ou compile do fonte

bash

git clone https://github.com/ruanbarroso/okf-agent-memory && cd okf-agent-memory
go build -o okf ./cmd/okf   # Go 1.26+

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.

PowerShell / bash

okf init ~/memoria
okf validate ~/memoria

Sync Git, opcional e automático

Quer a memória versionada no GitHub e compartilhada entre agentes e máquinas? Habilite o sync — a partir daí, toda escrita valida, commita e empurra sozinha, via Git puro, sem nenhum backend:

PowerShell / bash

okf sync init ~/memoria
git -C ~/memoria remote add origin [email protected]:seu-usuario/sua-memoria.git

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.

Apontar seu agente (MCP)

O BM é um servidor MCP (stdio, JSON-RPC). Basta apontar qualquer agente para o comando okf mcp . 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)

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

{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

Cursor

~/.cursor/mcp.json (global) · .cursor/mcp.json (por projeto)

{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "bm": { "command": "okf", "args": ["mcp", "~/memoria"] }
  }
}

OpenCode

opencode.json (global ou do projeto)

{
  "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 . 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.

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.

Tool	O que faz
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_status	Estado do sync Git: habilitado, branch, arquivos sujos, ahead/behind.
okf_sync_refresh	Puxa a branch configurada do remote (fetch + fast-forward/rebase).
okf_sync_publish	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.