KeyBrain — Memória Persistente para Agents de IA
raomaster/keybrain
Base de conhecimento local para agents de IA lembrarem contexto e decisões
Ver no GitHubAgent que oferece memória persistente e base de pesquisa para desenvolvedores usando Claude Code, Copilot e Cursor. Funciona local-first, sem nuvem ou chaves de API, capturando URLs, PDFs, artigos e notas que são automaticamente classificados, organizados e recuperáveis via busca semântica entre sessões.
Instalação
npx convez-ai raomaster/keybrain1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manter memória de decisões arquiteturais e convenções de código entre sessões
- Organizar e recuperar artigos, PDFs e pesquisas técnicas via busca semântica
- Construir base de conhecimento pessoal integrada com Obsidian
Veredito

KeyBrain resolve um problema real: agents de IA que esquecem contexto entre sessões. A abordagem local-first e integração nativa com ferramentas populares (Claude Code, Cursor, Obsidian) a tornam prática. Requer setup inicial e cron job, mas oferece controle total sobre dados sensíveis.
README
A tradução para o português deste README ainda está na fila.
KeyBrain
Persistent memory and research base for AI coding agents. Local-first, open source, yours.
Install · How it works · Commands · Docs · Contributing
What is KeyBrain?
KeyBrain gives AI coding agents (Claude Code, Copilot, Cursor) persistent memory and a research base they can actually use. Capture URLs, PDFs, papers, decisions, and notes — your agent classifies, organizes, and recalls them across sessions via semantic search.
No more re-explaining context every conversation. No cloud. No API keys. No vendor lock-in.
Why KeyBrain?
Two weeks ago Andrej Karpathy tweeted something that crystallized what I'd been building:
"Using LLMs to build personal knowledge bases for various topics of research interest..."
The problem is concrete: AI coding agents start from zero every session. They forget your architectural decisions, your conventions, your accumulated research. Existing solutions (Notion AI, Mem, hosted plugins) ship your context to servers you don't control.
KeyBrain is the local-first answer: a knowledge base your agent maintains for you, that lives on your disk, and works across every AI tool you use.
Install
Copy-paste this prompt to any AI agent (Claude Code, Copilot, Cursor, Gemini CLI):
I want to install KeyBrain — persistent memory and research base for my AI coding agents.
1. Clone the repo: git clone https://github.com/raomaster/keybrain.git ~/keybrain
2. Run the installer: bash ~/keybrain/setup/install.sh
3. The script will ask where to install (default: ~/Knowledge)
4. After installation, configure auto-processing:
"Configure a cron job to run $KB_VAULT/bin/process-inbox.sh every 15 minutes."
Or generate a model-pinned cron with:
kb cron print --process-model "anthropic/claude-sonnet-4-5"
During installation, KeyBrain detects OpenCode and Claude Code and asks which agent should power kb process. OpenCode is the recommended default for corporate environments where Claude is not approved.
Requirements: macOS, Linux, or Windows 10/11. Python 3.12+ installed automatically.
Setting up Obsidian
After the installer runs, open your vault in Obsidian:
- Install Obsidian if not already installed
- macOS: the installer does this automatically via Homebrew
- Windows/Linux: download from obsidian.md
- Open Obsidian
- Click Open folder as vault
- Navigate to your vault path (default:
~/Knowledge) - Click Open
Your knowledge base will appear with all folders and notes organized automatically.
Corporate Windows users (Git Bash): Run
bash setup/install.shdirectly from Git Bash — no PowerShell required. Python 3.12+ must be installed first from python.org.
How it works
You AI Agent
│ │
│ kb "article URL" │
│ kb add document.pdf │
│ Obsidian Web Clipper │
│ ↓ │
│ inbox/ │
│ ↓ │
│ process-inbox.sh
│ │
│ ┌──────┴──────┐
│ │ Classifies │
│ │ Archives │
│ │ Links wikis │
│ │ Updates index│
│ └──────┬──────┘
│ │
│ ↓ │
│ wiki/ + raw/ + decisions/ │
│ ↓ │
│ "search my KB for X" │
│ → keybrain agent skill │
│ → ChromaDB (milliseconds) │
Commands
| Command | What it does |
|---|---|
kb "text or URL" | Save text or URL to inbox |
kb add <file> | Copy file (PDF, Word, Excel, etc.) to inbox |
kb process | Force inbox processing now |
kb status | Show pending inbox count + last commit |
kb doctor | Check installation health without changing files |
kb cron status | Verify process/dream cron jobs and the configured processing model |
kb cron print | Generate safe cron entries for process/dream jobs |
kb update | Update KeyBrain framework from GitHub |
kb open | Open vault in file manager |
Agent skill
KeyBrain installs a universal keybrain skill for coding agents. Ask naturally:
| Prompt | What the agent should do |
|---|---|
| "busca en mi kb X" / "search my KB for X" | Run semantic search and answer with vault context |
| "guarda esto en KeyBrain" | Save durable content to the inbox |
| "procesa mi KB" | Run the configured inbox processor |
| "revisa la salud de mi vault" | Check structure, indexes, and pending inbox files |
Supported formats
Via markitdown:
| Format | Extension |
|---|---|
.pdf | |
| Word | .docx |
| Excel | .xlsx, .xls |
| PowerPoint | .pptx |
| Images (OCR) | .jpg, .png |
| Audio (transcription) | .mp3, .wav |
| HTML | .html |
| CSV/JSON | .csv, .json |
| YouTube | URLs (extracts title, description, and transcript) |
| EPub | .epub |
Supported agents
KeyBrain works with any AI agent via agentskills.io. The installer tries npx skills@latest first; if npm/npx is unavailable, it copies the keybrain skill to known global skill paths.
| Agent | Method |
|---|---|
| Claude Code | ~/.claude/skills/keybrain/ |
| Codex | ~/.codex/skills/keybrain/ and ~/.agents/skills/keybrain/ |
| OpenCode | ~/.config/opencode/skills/keybrain/ |
| GitHub Copilot (VS Code) | ~/.copilot/skills/keybrain/ |
| Cursor / Gemini CLI | ~/.cursor/skills/keybrain/, ~/.gemini/skills/keybrain/ |
| Antigravity 2.0 | ~/.gemini/antigravity/skills/keybrain/ |
| Antigravity CLI | ~/.gemini/antigravity-cli/skills/keybrain/ |
| Claude.ai Projects | Copy-paste SKILL.md to Project instructions |
Hermes and OpenClaw use dedicated integration paths because their skill and memory models need agent-specific setup.
Configuration
| Variable | Default | Description |
|---|---|---|
KB_VAULT | $HOME/Knowledge | Vault location |
KB_VENV | $KB_VAULT/.venv | Python virtual environment location |
KB_CHROMADB | $KB_VAULT/.chromadb | ChromaDB index location |
KB_PROCESS_AGENT | opencode | Agent backend for kb process (opencode or claude) |
KB_PROCESS_MODEL | agent default | Model used by the inbox processing cron |
KB_PROCESS_VARIANT | unset | OpenCode model variant / reasoning effort |
KB_PROCESS_EFFORT | unset | Claude Code effort (low, medium, high, xhigh, max) |
KB_PROCESS_MAX_BUDGET_USD | unset | Claude Code print-mode spend cap |
# In your shell profile (.zshrc / .bashrc / PowerShell $PROFILE)
export KB_VAULT="$HOME/Google Drive/My Drive/Knowledge" # cloud sync
export KB_VENV="$HOME/.local/share/keybrain/venv" # optional runtime outside sync
export KB_CHROMADB="$HOME/.local/share/keybrain/chromadb" # optional index outside sync
export KB_PROCESS_AGENT="opencode" # or "claude"
export KB_PROCESS_MODEL="anthropic/claude-sonnet-4-5" # optional cron model pin
export PATH="$KB_VAULT/bin:$PATH"
kb-dream is deterministic and does not call an LLM, so model settings only apply to process-inbox.sh.
Personalizing your agent
KeyBrain installs a USER.md template to ~/.claude/USER.md during setup (Claude Code only). Edit it with your name, role, and preferences — the agent reads it on demand to tailor responses to you.
Why YAML? Structured key-value format uses ~30% fewer tokens than prose (reference), keeping your identity file fast to load.
---
# USER.md — [Your Name]
# Read on-demand, not every prompt.
---
identity:
name: [Your Name]
role: [e.g. "Senior Software Engineer", "Data Scientist"]
expertise: [python, typescript, react]
projects:
main: [~/Code/myproject]
style:
expects: [peer-level technical, options with tradeoffs]
dislikes: [over-explanation, unsolicited refactors]
For other agents (Copilot, Cursor, Codex): create the file manually and add an instruction to read it in your agent's config (e.g., .github/copilot-instructions.md, AGENTS.md).
Architecture
vault/
├── inbox/ ← Entry zone (you add files here)
├── raw/articles/ ← Processed articles
├── raw/courses/ ← Course notes
├── raw/research/ ← Papers and research
├── wiki/ ← Compiled knowledge (agent-maintained)
├── decisions/ ← Architecture Decision Records
├── conversations/ ← Chat exports
├── bin/ ← CLI tools + Python scripts
├── CLAUDE.md ← Agent instructions (the "magic")
└── .chromadb/ ← Local vector database
The "magic" is CLAUDE.md — 250+ lines of instructions that tell your AI agent exactly how to classify, organize, and maintain your knowledge. The scripts are thin wrappers.
Cloud sync
KeyBrain works with any cloud sync provider. If you store your vault inside a synced folder, exclude .venv/ and .chromadb/ — they are regenerable and can be hundreds of MB.
| Provider | How to exclude a folder |
|---|---|
| Google Drive | Create an empty .gdignore file inside the folder |
| iCloud | Rename the folder with a .nosync extension (e.g. .venv.nosync) |
| OneDrive | Rename the folder with a .nosync extension |
| Dropbox | Use Selective Sync in the Dropbox desktop app |
# Google Drive example
touch ~/Knowledge/.venv/.gdignore
touch ~/Knowledge/.chromadb/.gdignore
License
MIT
Links
- Use Cases — step-by-step scenarios
- Contributing — how to contribute
- Changelog — version history