Skip to content

spillwavesolutions/agent-brain

v10.7.0MIT

Local-first RAG memory for AI agents: hybrid BM25/semantic search, GraphRAG, and an MCP server with OAuth 2.1. Index docs and code, then search from Claude Code, Cursor, Codex, OpenCode, or Grok Build.

GitHubOpen Website

Agent Brain Plugin

A multi-host plugin for document search with hybrid BM25/semantic retrieval. Index your documentation and source code, then search using keyword matching, semantic similarity, or combined hybrid mode. Installs natively in Claude Code, OpenCode, Codex, Cursor, and Grok Build; a conforming Agent Plugins 1.0 client can consume plugin.json + skills/ + mcp.json.

Features

  • Hybrid Search: Combines BM25 keyword matching with semantic vector search for best results
  • Three Search Modes: BM25 (fast keywords), Vector (semantic), Hybrid (combined)
  • Multi-Instance: Run separate servers for different projects with automatic port allocation
  • Code Search: AST-aware indexing for Python, TypeScript, JavaScript, Java, Go, Rust, C, C++

Installation

1. Install Claude Code Plugin

# Add the marketplace, then install the plugin from it
claude plugins marketplace add SpillwaveSolutions/agent-brain
claude plugins install agent-brain@agent-brain-marketplace

Codex, Cursor, Grok Build, OpenCode

Install the Python packages first (step 2), then let the CLI convert this plugin into the host's native layout:

agent-brain install-agent --agent codex --with-mcp     # .codex/skills/agent-brain + AGENTS.md
agent-brain install-agent --agent cursor --with-mcp    # .cursor/plugins/agent-brain + .cursor/rules
agent-brain install-agent --agent grok --with-mcp      # .grok/plugins/agent-brain (zero-config Claude load)
agent-brain install-agent --agent opencode --with-mcp  # .opencode/plugins/agent-brain

Agent Plugins 1.0 clients read plugin.json, skills/, and mcp.json in this directory directly. AGENTS.md is the host compatibility contract. The full host table is in docs/HOSTS.md.

2. Install Agent Brain Packages

pip install agent-brain-rag agent-brain-cli

3. Configure API Key

export OPENAI_API_KEY="sk-proj-..."

4. Initialize and Start

agent-brain init
agent-brain start
agent-brain index /path/to/docs

Quick Start

Once installed, use these slash commands in Claude Code:

/agent-brain-search "authentication flow"    # Hybrid search (recommended)
/agent-brain-semantic "how does auth work"   # Conceptual search
/agent-brain-keyword "AuthenticationError"   # Exact term search

Commands

Search Commands

CommandDescription
/agent-brain-searchHybrid search (BM25 + semantic)
/agent-brain-semanticSemantic vector search
/agent-brain-keywordBM25 keyword search

Setup Commands

CommandDescription
/agent-brain-installInstall pip packages
/agent-brain-setupComplete guided setup
/agent-brain-configConfigure API keys
/agent-brain-initInitialize project
/agent-brain-verifyVerify installation

Server Commands

CommandDescription
/agent-brain-startStart server (auto-port)
/agent-brain-stopStop server
/agent-brain-statusShow server health
/agent-brain-listList all instances

Indexing Commands

CommandDescription
/agent-brain-indexIndex documents
/agent-brain-resetClear all indexed content

Help

CommandDescription
/agent-brain-helpShow all commands

Search Modes

ModeSpeedBest ForExample Query
hybridSlowerGeneral queries"OAuth implementation guide"
bm25FastTechnical terms, function names"AuthenticationError"
vectorSlowerConcepts, explanations"how does authentication work"

Requirements

  • Python 3.10+
  • OpenAI API key (for vector/hybrid search)
  • Optional: Anthropic API key (for code summarization)

Skills

This plugin includes two skills:

  1. using-agent-brain: Search mode guidance and API reference
  2. agent-brain-setup: Installation, configuration, and troubleshooting

License

MIT

Support