agent-brain
Local-first RAG memory for AI agents: hybrid + GraphRAG search, MCP server with OAuth 2.1, plugin for Claude Code / OpenCode / Codex.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/spillwavesolutions--agent-brain)HTML
<a href="/listings/spillwavesolutions--agent-brain"><img src="/api/listings/spillwavesolutions--agent-brain/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Install the Plugin
# 1. Add the Agent Brain marketplace (the repo is a plugin marketplace) claude plugins marketplace add SpillwaveSolutions/agent-brain # 2. Install the plugin from that marketplace claude plugins install agent-brain@agent-brain-marketplace
> Installing a Claude Code plugin does **not** use `pip`. The plugin is > installed through the marketplace above; the underlying Python packages > (`agent-brain-rag`, `agent-brain-cli`) are installed for you by the > `/agent-brain-setup` wizard (or manually via `pip` — see [CLI Usage](#cli-usage-alternative)).
Other hosts
The same plugin installs into Codex, Cursor, Grok Build, and OpenCode through the CLI. Each command converts the shared payload into the host's native layout and, with `--with-mcp`, registers the MCP server in that host's config file.
pip install agent-brain-rag agent-brain-cli agent-brain-ag-mcp agent-brain install-agent --agent codex --with-mcp # .codex/skills/agent-brain + AGENTS.md; MCP in ~/.codex/config.toml agent-brain install-agent --agent cursor --with-mcp # .cursor/plugins/agent-brain + .cursor/rules; MCP in .cursor/mcp.json agent-brain install-agent --agent grok --with-mcp # .grok/plugins/agent-brain; zero-config Claude load, MCP in .mcp.json agent-brain install-agent --agent opencode --with-mcp # .opencode/plugins/agent-brain; MCP in opencode.json
A conforming [Agent Plugins 1.0](https://agent-plugins.org/specification) client reads `agent-brain-plugin/plugin.json`, `skills/`, and `mcp.json` directly. See [docs/HOSTS.md](docs/HOSTS.md) for the manifest each host reads.
2. Set Up Your Project
In Claude Code, run:
/agent-brain-setup
This interactive wizard will: - Install the Python packages (`agent-brain-rag`, `agent-brain-cli`) - Configure your API keys - Initialize the project - Start the server - Index your documentation
3. Search with Commands
/agent-brain-search "how does authentication work"
That's it! The plugin handles everything automatically.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
.claude-plugin/marketplace.json · Manifest · 23 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- {
- "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
- "name": "agent-brain-marketplace",
- "version": "2.0.0",
- "description": "Marketplace for Agent Brain document search plugins with hybrid BM25/semantic retrieval and GraphRAG",
- "owner": {
- "name": "Spillwave Solutions",
- "email": "support@spillwave.com"
- },
- "plugins": [
- {
- "name": "agent-brain",
- "description": "Document search with hybrid BM25/semantic retrieval, GraphRAG knowledge graphs, and pluggable providers",
- "version": "10.7.0",
- "author": {
- "name": "Spillwave Solutions",
- "email": "support@spillwave.com"
- },
- "source": "./agent-brain-plugin",
- "category": "productivity"
- }
- ]
- }
README.md · README · 306 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- last_validated: 2026-03-16
- ---
- # Agent Brain
- A RAG-based (Retrieval-Augmented Generation) document indexing and semantic search system for AI agents and applications. Agent Brain enables intelligent querying of documentation and source code using natural language.
- ## Overview
- Agent Brain provides **AI-first** document and code search through a Claude Code plugin with skills, commands, and agents. Use slash commands to search, agents for complex research tasks, and skills for intelligent query optimization.
- | Component | Description |
- |-----------|-------------|
- | **Plugin** | 30 slash commands, 3 agents, 2 skills for Claude Code |
- | **Skills** | Intelligent search mode selection and query optimization |
- | **Agents** | Research assistant, search assistant, setup assistant |
- | **Server** | FastAPI backend for indexing and retrieval |
- | **CLI** | Command-line tool (also used by plugin internally) |
- ## Quick Start (Claude Code Plugin)
- ### 1. Install the Plugin
- ```bash
- # 1. Add the Agent Brain marketplace (the repo is a plugin marketplace)
- claude plugins marketplace add SpillwaveSolutions/agent-brain
- # 2. Install the plugin from that marketplace
- claude plugins install agent-brain@agent-brain-marketplace
- ```
- > Installing a Claude Code plugin does **not** use `pip`. The plugin is
- > installed through the marketplace above; the underlying Python packages
- > (`agent-brain-rag`, `agent-brain-cli`) are installed for you by the
- > `/agent-brain-setup` wizard (or manually via `pip` — see [CLI Usage](#cli-usage-alternative)).
- #### Other hosts
- The same plugin installs into Codex, Cursor, Grok Build, and OpenCode through the CLI. Each command converts the shared payload into the host's native layout and, with `--with-mcp`, registers the MCP server in that host's config file.
- ```bash
- pip install agent-brain-rag agent-brain-cli agent-brain-ag-mcp
- agent-brain install-agent --agent codex --with-mcp # .codex/skills/agent-brain + AGENTS.md; MCP in ~/.codex/config.toml
- agent-brain install-agent --agent cursor --with-mcp # .cursor/plugins/agent-brain + .cursor/rules; MCP in .cursor/mcp.json
- agent-brain install-agent --agent grok --with-mcp # .grok/plugins/agent-brain; zero-config Claude load, MCP in .mcp.json
- agent-brain install-agent --agent opencode --with-mcp # .opencode/plugins/agent-brain; MCP in opencode.json
- ```
- A conforming [Agent Plugins 1.0](https://agent-plugins.org/specification) client reads `agent-brain-plugin/plugin.json`, `skills/`, and `mcp.json` directly. See [docs/HOSTS.md](docs/HOSTS.md) for the manifest each host reads.
- ### 2. Set Up Your Project
- In Claude Code, run:
- ```
- /agent-brain-setup
- ```
- This interactive wizard will:
- - Install the Python packages (`agent-brain-rag`, `agent-brain-cli`)
- - Configure your API keys
- - Initialize the project
- - Start the server
- - Index your documentation
- ### 3. Search with Commands
- ```
- /agent-brain-search "how does authentication work"
- ```
- That's it! The plugin handles everything automatically.
- ## Plugin Commands
- ### Search Commands
- | Command | Description | Use When |
- |---------|-------------|----------|
- | `/agent-brain-search` | Smart hybrid search (recommended) | General questions |
- | `/agent-brain-semantic` | Pure semantic/vector search | Conceptual queries |
- | `/agent-brain-keyword` | BM25 keyword search | Error messages, function names |
- | `/agent-brain-hybrid` | Hybrid with alpha tuning | Fine-tuned searches |
- | `/agent-brain-graph` | Knowledge graph search | "What calls X?", dependencies |
- | `/agent-brain-multi` | All modes combined (RRF) | Maximum recall |
- ### Server Commands
- | Command | Description |
- |---------|-------------|
- | `/agent-brain-start` | Start the server (auto-port) |
- | `/agent-brain-stop` | Stop the server |
- | `/agent-brain-status` | Check health and document count |
- | `/agent-brain-index` | Index documents or code |
- ### Setup Commands
- | Command | Description |
- |---------|-------------|
- | `/agent-brain-setup` | Complete guided setup wizard |
- | `/agent-brain-install` | Install pip packages |
- | `/agent-brain-init` | Initialize project directory |
- | `/agent-brain-verify` | Verify configuration |
- | `/agent-brain-providers` | Configure embedding/summarization providers |
- ## Plugin Agents
- Agent Brain includes three intelligent agents for complex tasks:
- | Agent | Description | Triggered By |
- |-------|-------------|--------------|
- | **Search Assistant** | Multi-step search across modes, synthesizes answers | "Find all references to...", "Research how..." |
- | **Research Assistant** | Deep exploration with follow-up queries | "Investigate...", "Analyze the architecture of..." |
- | **Setup Assistant** | Guided installation and troubleshooting | "Help me set up Agent Brain", configuration issues |
- ### Example Agent Interaction
- **You**: "Research how authentication is implemented across the codebase"
- **Research Assistant**:
- 1. Searches documentation for auth concepts
- 2. Queries code for auth-related functions
- 3. Uses graph mode to find dependencies
- 4. Synthesizes comprehensive answer with references
- ## Plugin Skills
- Skills provide intelligent context to Claude for optimal searching:
- | Skill | Purpose |
- |-------|---------|
- | **using-agent-brain** | Search mode selection, query optimization, API knowledge |
- | **configuring-agent-brain** | Installation, provider configuration, troubleshooting |
- When you ask about documentation or code, Claude automatically uses the skill to:
- - Choose the best search mode for your query
- - Set appropriate parameters (top_k, threshold, alpha)
- - Interpret and synthesize results
- ## Search Modes
- | Mode | Best For | Example Query |
- |------|----------|---------------|
- | `HYBRID` | General questions (default) | "How does caching work?" |
- | `VECTOR` | Conceptual understanding | "Explain the architecture" |
- | `BM25` | Exact terms, error codes | "NullPointerException", "getUserById" |
- | `GRAPH` | Relationships, dependencies | "What classes use AuthService?" |
- | `MULTI` | Comprehensive search | "Everything about data validation" |
- ## Pluggable Providers
- Agent Brain supports multiple providers for embeddings and summarization:
- ### Embedding Providers
- | Provider | Models | Local |
- |----------|--------|-------|
- | OpenAI | text-embedding-3-large, text-embedding-3-small | No |
- | Ollama | nomic-embed-text, mxbai-embed-large | Yes |
- | Cohere | embed-english-v3.0, embed-multilingual-v3.0 | No |
- ### Summarization Providers
- | Provider | Models | Local |
- |----------|--------|-------|
- | Anthropic | claude-haiku-4-5-20251001, claude-sonnet-4-5-20250514 | No |
- | OpenAI | gpt-5, gpt-5-mini | No |
- | Gemini | gemini-3-flash, gemini-3-pro | No |
- | Grok | grok-4, grok-4-fast | No |
- | Ollama | llama4:scout, mistral-small3.2, qwen3-coder | Yes |
- ### Fully Local Mode
- Run completely offline with Ollama:
- ```
- /agent-brain-providers
- # Select Ollama for both embeddings and summarization
- ```
- ## Features
- ### Code Search
- - **10 Programming Languages**: Python, TypeScript, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift
- - **AST-Aware Chunking**: Tree-sitter parsing preserves code structure
- - **LLM Summaries**: AI-generated descriptions improve semantic search
- - **Language Filtering**: Filter results by programming language
- ### GraphRAG (Knowledge Graph)
- - Entity and relationship extraction
- - Dependency-aware queries ("What calls X?")
- - Code structure visualization
- ### Multi-Instance Architecture
- - Per-project isolated servers
- - Automatic port allocation
- - Work on multiple projects simultaneously
- ## Project Structure
- ```
- agent-brain/
- ├── agent-brain-plugin/ # Claude Code plugin (primary interface)
- │ ├── commands/ # 30 slash commands
- │ ├── agents/ # 3 intelligent agents
- │ └── skills/ # 2 context skills
- ├── agent-brain-server/ # FastAPI backend
- ├── agent-brain-cli/ # CLI tool (used by plugin)
- └── docs/ # Documentation
- ```
- ## Documentation
- ### Getting Started
- - [Quick Start](docs/QUICK_START.md) - Get running in minutes
- - [Plugin Guide](docs/PLUGIN_GUIDE.md) - Complete plugin documentation
- - [User Guide](docs/USER_GUIDE.md) - Detailed usage guide
- - [MCP Quickstart](docs/MCP_QUICKSTART.md) - Use Agent Brain over MCP in ~5 minutes
- - [Project Setup: Plugin + Skills + MCP](docs/PROJECT_SETUP_PLUGIN_SKILLS_MCP.md) - Wire all three into one project
- ### Reference
- - [API Reference](docs/API_REFERENCE.md) - REST API documentation
- - [MCP User Guide](docs/MCP_USER_GUIDE.md) - MCP server: 16 tools, resources, prompts, OAuth
- - [Configuration](docs/CONFIGURATION.md) - All configuration options
- - [Provider Configuration](agent-brain-plugin/skills/using-agent-brain/references/provider-configuration.md) - Provider setup
- - [Integrations](docs/INTEGRATIONS.md) - Connect agent-brain-mcp to LLM frameworks + editors
- ### Architecture
- - [Architecture Overview](docs/ARCHITECTURE.md) - System design
- - [GraphRAG Guide](docs/GRAPHRAG_GUIDE.md) - Knowledge graph features
- - [Code Indexing](docs/CODE_INDEXING.md) - AST-aware chunking
- ## CLI Usage (Alternative)
- While the plugin is the recommended interface, you can also use the CLI directly:
- ```bash
- # Install
- pip install agent-brain-rag agent-brain-cli
- # Initialize and start
- agent-brain init # auto-generates a per-project API key
- agent-brain start --daemon
- # Index and query
- agent-brain index /path/to/docs --include-code
- agent-brain query "authentication" --mode hybrid
- ```
- > **Note on authentication.** As of the next release, every data endpoint
- > requires `X-API-Key`. `agent-brain init` writes a 32-byte urlsafe key
- > into `.agent-brain/config.json` (mode `0o600`); the CLI and
- > `agent-brain-mcp` pick it up automatically. Pass `--no-api-key` to
- > `agent-brain init` for the legacy no-auth experience on `127.0.0.1`.
- > The server refuses to start on any non-loopback bind without a key
- > set. See [`docs/CHANGELOG.md`](docs/CHANGELOG.md) under the unreleased
- > entry for the full design (Issue #179).
- ## Development
- ### Prerequisites
- - Python 3.10+
- - Poetry (dependency management)
- - Task (task runner)
- ### Setup
- ```bash
- git clone https://github.com/SpillwaveSolutions/agent-brain.git
- cd agent-brain
- task install
- ```
- ### Running Tests
- ```bash
- task test # All tests
- task before-push # Full quality check
- ```
- ## Technology Stack
- - **Plugin**: Claude Code slash commands, agents, skills
- - **Server**: FastAPI + Uvicorn
- - **Vector Store**: ChromaDB (HNSW, cosine similarity)
- - **BM25 Index**: LlamaIndex BM25Retriever
- - **Graph Store**: SimplePropertyGraphStore / Kuzu
- - **Embeddings**: OpenAI or Ollama
- - **Summarization**: Claude, GPT-5, Gemini, Grok, or Ollama
- - **AST Parsing**: tree-sitter (10 languages)
- - **CLI**: Click + Rich
- - **Build System**: Poetry
- ## Contributing
- See the [Developer Guide](docs/DEVELOPERS_GUIDE.md) for setup instructions.
- **Before pushing changes**, always run:
- ```bash
- task before-push
- ```
- ## License
- MIT License - see LICENSE file for details.
- ## Links
- - [GitHub Wiki](https://github.com/SpillwaveSolutions/agent-brain/wiki)
- - [Plugin Marketplace](https://skillzwave.ai/)
- - [Issue Tracker](https://github.com/SpillwaveSolutions/agent-brain/issues)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.