Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spillwavesolutions--agent-brain/badge.svg)](/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

i

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)

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "agent-brain-marketplace",
  4. "version": "2.0.0",
  5. "description": "Marketplace for Agent Brain document search plugins with hybrid BM25/semantic retrieval and GraphRAG",
  6. "owner": {
  7. "name": "Spillwave Solutions",
  8. "email": "support@spillwave.com"
  9. },
  10. "plugins": [
  11. {
  12. "name": "agent-brain",
  13. "description": "Document search with hybrid BM25/semantic retrieval, GraphRAG knowledge graphs, and pluggable providers",
  14. "version": "10.7.0",
  15. "author": {
  16. "name": "Spillwave Solutions",
  17. "email": "support@spillwave.com"
  18. },
  19. "source": "./agent-brain-plugin",
  20. "category": "productivity"
  21. }
  22. ]
  23. }
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)

  1. ---
  2. last_validated: 2026-03-16
  3. ---
  4. # Agent Brain
  5. 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.
  6. ## Overview
  7. 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.
  8. | Component | Description |
  9. |-----------|-------------|
  10. | **Plugin** | 30 slash commands, 3 agents, 2 skills for Claude Code |
  11. | **Skills** | Intelligent search mode selection and query optimization |
  12. | **Agents** | Research assistant, search assistant, setup assistant |
  13. | **Server** | FastAPI backend for indexing and retrieval |
  14. | **CLI** | Command-line tool (also used by plugin internally) |
  15. ## Quick Start (Claude Code Plugin)
  16. ### 1. Install the Plugin
  17. ```bash
  18. # 1. Add the Agent Brain marketplace (the repo is a plugin marketplace)
  19. claude plugins marketplace add SpillwaveSolutions/agent-brain
  20. # 2. Install the plugin from that marketplace
  21. claude plugins install agent-brain@agent-brain-marketplace
  22. ```
  23. > Installing a Claude Code plugin does **not** use `pip`. The plugin is
  24. > installed through the marketplace above; the underlying Python packages
  25. > (`agent-brain-rag`, `agent-brain-cli`) are installed for you by the
  26. > `/agent-brain-setup` wizard (or manually via `pip` — see [CLI Usage](#cli-usage-alternative)).
  27. #### Other hosts
  28. 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.
  29. ```bash
  30. pip install agent-brain-rag agent-brain-cli agent-brain-ag-mcp
  31. agent-brain install-agent --agent codex --with-mcp # .codex/skills/agent-brain + AGENTS.md; MCP in ~/.codex/config.toml
  32. agent-brain install-agent --agent cursor --with-mcp # .cursor/plugins/agent-brain + .cursor/rules; MCP in .cursor/mcp.json
  33. agent-brain install-agent --agent grok --with-mcp # .grok/plugins/agent-brain; zero-config Claude load, MCP in .mcp.json
  34. agent-brain install-agent --agent opencode --with-mcp # .opencode/plugins/agent-brain; MCP in opencode.json
  35. ```
  36. 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.
  37. ### 2. Set Up Your Project
  38. In Claude Code, run:
  39. ```
  40. /agent-brain-setup
  41. ```
  42. This interactive wizard will:
  43. - Install the Python packages (`agent-brain-rag`, `agent-brain-cli`)
  44. - Configure your API keys
  45. - Initialize the project
  46. - Start the server
  47. - Index your documentation
  48. ### 3. Search with Commands
  49. ```
  50. /agent-brain-search "how does authentication work"
  51. ```
  52. That's it! The plugin handles everything automatically.
  53. ## Plugin Commands
  54. ### Search Commands
  55. | Command | Description | Use When |
  56. |---------|-------------|----------|
  57. | `/agent-brain-search` | Smart hybrid search (recommended) | General questions |
  58. | `/agent-brain-semantic` | Pure semantic/vector search | Conceptual queries |
  59. | `/agent-brain-keyword` | BM25 keyword search | Error messages, function names |
  60. | `/agent-brain-hybrid` | Hybrid with alpha tuning | Fine-tuned searches |
  61. | `/agent-brain-graph` | Knowledge graph search | "What calls X?", dependencies |
  62. | `/agent-brain-multi` | All modes combined (RRF) | Maximum recall |
  63. ### Server Commands
  64. | Command | Description |
  65. |---------|-------------|
  66. | `/agent-brain-start` | Start the server (auto-port) |
  67. | `/agent-brain-stop` | Stop the server |
  68. | `/agent-brain-status` | Check health and document count |
  69. | `/agent-brain-index` | Index documents or code |
  70. ### Setup Commands
  71. | Command | Description |
  72. |---------|-------------|
  73. | `/agent-brain-setup` | Complete guided setup wizard |
  74. | `/agent-brain-install` | Install pip packages |
  75. | `/agent-brain-init` | Initialize project directory |
  76. | `/agent-brain-verify` | Verify configuration |
  77. | `/agent-brain-providers` | Configure embedding/summarization providers |
  78. ## Plugin Agents
  79. Agent Brain includes three intelligent agents for complex tasks:
  80. | Agent | Description | Triggered By |
  81. |-------|-------------|--------------|
  82. | **Search Assistant** | Multi-step search across modes, synthesizes answers | "Find all references to...", "Research how..." |
  83. | **Research Assistant** | Deep exploration with follow-up queries | "Investigate...", "Analyze the architecture of..." |
  84. | **Setup Assistant** | Guided installation and troubleshooting | "Help me set up Agent Brain", configuration issues |
  85. ### Example Agent Interaction
  86. **You**: "Research how authentication is implemented across the codebase"
  87. **Research Assistant**:
  88. 1. Searches documentation for auth concepts
  89. 2. Queries code for auth-related functions
  90. 3. Uses graph mode to find dependencies
  91. 4. Synthesizes comprehensive answer with references
  92. ## Plugin Skills
  93. Skills provide intelligent context to Claude for optimal searching:
  94. | Skill | Purpose |
  95. |-------|---------|
  96. | **using-agent-brain** | Search mode selection, query optimization, API knowledge |
  97. | **configuring-agent-brain** | Installation, provider configuration, troubleshooting |
  98. When you ask about documentation or code, Claude automatically uses the skill to:
  99. - Choose the best search mode for your query
  100. - Set appropriate parameters (top_k, threshold, alpha)
  101. - Interpret and synthesize results
  102. ## Search Modes
  103. | Mode | Best For | Example Query |
  104. |------|----------|---------------|
  105. | `HYBRID` | General questions (default) | "How does caching work?" |
  106. | `VECTOR` | Conceptual understanding | "Explain the architecture" |
  107. | `BM25` | Exact terms, error codes | "NullPointerException", "getUserById" |
  108. | `GRAPH` | Relationships, dependencies | "What classes use AuthService?" |
  109. | `MULTI` | Comprehensive search | "Everything about data validation" |
  110. ## Pluggable Providers
  111. Agent Brain supports multiple providers for embeddings and summarization:
  112. ### Embedding Providers
  113. | Provider | Models | Local |
  114. |----------|--------|-------|
  115. | OpenAI | text-embedding-3-large, text-embedding-3-small | No |
  116. | Ollama | nomic-embed-text, mxbai-embed-large | Yes |
  117. | Cohere | embed-english-v3.0, embed-multilingual-v3.0 | No |
  118. ### Summarization Providers
  119. | Provider | Models | Local |
  120. |----------|--------|-------|
  121. | Anthropic | claude-haiku-4-5-20251001, claude-sonnet-4-5-20250514 | No |
  122. | OpenAI | gpt-5, gpt-5-mini | No |
  123. | Gemini | gemini-3-flash, gemini-3-pro | No |
  124. | Grok | grok-4, grok-4-fast | No |
  125. | Ollama | llama4:scout, mistral-small3.2, qwen3-coder | Yes |
  126. ### Fully Local Mode
  127. Run completely offline with Ollama:
  128. ```
  129. /agent-brain-providers
  130. # Select Ollama for both embeddings and summarization
  131. ```
  132. ## Features
  133. ### Code Search
  134. - **10 Programming Languages**: Python, TypeScript, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift
  135. - **AST-Aware Chunking**: Tree-sitter parsing preserves code structure
  136. - **LLM Summaries**: AI-generated descriptions improve semantic search
  137. - **Language Filtering**: Filter results by programming language
  138. ### GraphRAG (Knowledge Graph)
  139. - Entity and relationship extraction
  140. - Dependency-aware queries ("What calls X?")
  141. - Code structure visualization
  142. ### Multi-Instance Architecture
  143. - Per-project isolated servers
  144. - Automatic port allocation
  145. - Work on multiple projects simultaneously
  146. ## Project Structure
  147. ```
  148. agent-brain/
  149. ├── agent-brain-plugin/ # Claude Code plugin (primary interface)
  150. │ ├── commands/ # 30 slash commands
  151. │ ├── agents/ # 3 intelligent agents
  152. │ └── skills/ # 2 context skills
  153. ├── agent-brain-server/ # FastAPI backend
  154. ├── agent-brain-cli/ # CLI tool (used by plugin)
  155. └── docs/ # Documentation
  156. ```
  157. ## Documentation
  158. ### Getting Started
  159. - [Quick Start](docs/QUICK_START.md) - Get running in minutes
  160. - [Plugin Guide](docs/PLUGIN_GUIDE.md) - Complete plugin documentation
  161. - [User Guide](docs/USER_GUIDE.md) - Detailed usage guide
  162. - [MCP Quickstart](docs/MCP_QUICKSTART.md) - Use Agent Brain over MCP in ~5 minutes
  163. - [Project Setup: Plugin + Skills + MCP](docs/PROJECT_SETUP_PLUGIN_SKILLS_MCP.md) - Wire all three into one project
  164. ### Reference
  165. - [API Reference](docs/API_REFERENCE.md) - REST API documentation
  166. - [MCP User Guide](docs/MCP_USER_GUIDE.md) - MCP server: 16 tools, resources, prompts, OAuth
  167. - [Configuration](docs/CONFIGURATION.md) - All configuration options
  168. - [Provider Configuration](agent-brain-plugin/skills/using-agent-brain/references/provider-configuration.md) - Provider setup
  169. - [Integrations](docs/INTEGRATIONS.md) - Connect agent-brain-mcp to LLM frameworks + editors
  170. ### Architecture
  171. - [Architecture Overview](docs/ARCHITECTURE.md) - System design
  172. - [GraphRAG Guide](docs/GRAPHRAG_GUIDE.md) - Knowledge graph features
  173. - [Code Indexing](docs/CODE_INDEXING.md) - AST-aware chunking
  174. ## CLI Usage (Alternative)
  175. While the plugin is the recommended interface, you can also use the CLI directly:
  176. ```bash
  177. # Install
  178. pip install agent-brain-rag agent-brain-cli
  179. # Initialize and start
  180. agent-brain init # auto-generates a per-project API key
  181. agent-brain start --daemon
  182. # Index and query
  183. agent-brain index /path/to/docs --include-code
  184. agent-brain query "authentication" --mode hybrid
  185. ```
  186. > **Note on authentication.** As of the next release, every data endpoint
  187. > requires `X-API-Key`. `agent-brain init` writes a 32-byte urlsafe key
  188. > into `.agent-brain/config.json` (mode `0o600`); the CLI and
  189. > `agent-brain-mcp` pick it up automatically. Pass `--no-api-key` to
  190. > `agent-brain init` for the legacy no-auth experience on `127.0.0.1`.
  191. > The server refuses to start on any non-loopback bind without a key
  192. > set. See [`docs/CHANGELOG.md`](docs/CHANGELOG.md) under the unreleased
  193. > entry for the full design (Issue #179).
  194. ## Development
  195. ### Prerequisites
  196. - Python 3.10+
  197. - Poetry (dependency management)
  198. - Task (task runner)
  199. ### Setup
  200. ```bash
  201. git clone https://github.com/SpillwaveSolutions/agent-brain.git
  202. cd agent-brain
  203. task install
  204. ```
  205. ### Running Tests
  206. ```bash
  207. task test # All tests
  208. task before-push # Full quality check
  209. ```
  210. ## Technology Stack
  211. - **Plugin**: Claude Code slash commands, agents, skills
  212. - **Server**: FastAPI + Uvicorn
  213. - **Vector Store**: ChromaDB (HNSW, cosine similarity)
  214. - **BM25 Index**: LlamaIndex BM25Retriever
  215. - **Graph Store**: SimplePropertyGraphStore / Kuzu
  216. - **Embeddings**: OpenAI or Ollama
  217. - **Summarization**: Claude, GPT-5, Gemini, Grok, or Ollama
  218. - **AST Parsing**: tree-sitter (10 languages)
  219. - **CLI**: Click + Rich
  220. - **Build System**: Poetry
  221. ## Contributing
  222. See the [Developer Guide](docs/DEVELOPERS_GUIDE.md) for setup instructions.
  223. **Before pushing changes**, always run:
  224. ```bash
  225. task before-push
  226. ```
  227. ## License
  228. MIT License - see LICENSE file for details.
  229. ## Links
  230. - [GitHub Wiki](https://github.com/SpillwaveSolutions/agent-brain/wiki)
  231. - [Plugin Marketplace](https://skillzwave.ai/)
  232. - [Issue Tracker](https://github.com/SpillwaveSolutions/agent-brain/issues)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.