Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From agent-brain
Installs and configures Agent Brain RAG document search system with Ollama or OpenAI/Anthropic providers. Covers pip installs, env vars, project init, server management, and troubleshooting.
npx claudepluginhub spillwavesolutions/agent-brain --plugin agent-brainHow this skill is triggered — by the user, by Claude, or both
Slash command
/agent-brain:configuring-agent-brainThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Installation and configuration for Agent Brain document search with pluggable providers.
Searches documents, codebases, and knowledge bases using BM25 keyword, semantic vector, hybrid, graph, and multi retrieval modes for dependencies, relationships, and references.
Provides production-ready patterns for LLM apps including RAG pipelines, chunking strategies, vector DB selection, embedding models, and AI agent architectures. Use for designing RAG systems, agents, and LLMOps.
Provides production-ready patterns for building LLM applications: RAG pipelines, document chunking, embedding models, vector database selection, and agent architectures.
Share bugs, ideas, or general feedback.
Installation and configuration for Agent Brain document search with pluggable providers.
Agent Brain supports multiple AI coding runtimes from a single canonical plugin source:
| Runtime | Install Command |
|---|---|
| Claude Code | agent-brain install-agent --agent claude |
| OpenCode | agent-brain install-agent --agent opencode |
| Gemini CLI | agent-brain install-agent --agent gemini |
All runtimes share the same .agent-brain/ data directory for indexes, configuration, and server state. The install-agent command converts the canonical plugin format into each runtime's native format automatically.
Use --global for user-level installation, or --dry-run to preview files before writing.
# 1. Install packages
pip install agent-brain-rag agent-brain-cli
# 2. Install and start Ollama
brew install ollama # macOS
ollama serve &
ollama pull nomic-embed-text
ollama pull llama3.2
# 3. Configure for Ollama
export EMBEDDING_PROVIDER=ollama
export EMBEDDING_MODEL=nomic-embed-text
export SUMMARIZATION_PROVIDER=ollama
export SUMMARIZATION_MODEL=llama3.2
# 4. Initialize and start
agent-brain init
agent-brain start
agent-brain status
# 1. Install packages
pip install agent-brain-rag agent-brain-cli
# 2. Configure API keys
export OPENAI_API_KEY="sk-proj-..." # For embeddings
export ANTHROPIC_API_KEY="sk-ant-..." # For summarization (optional)
# 3. Initialize and start
agent-brain init
agent-brain start
agent-brain status
Validation: After each step, verify success before proceeding to the next.
The canonical entry point for a complete guided setup is /agent-brain-setup. It asks all configuration questions interactively before running any CLI commands, then writes a comprehensive config.yaml.
The wizard asks the following questions in sequence:
| Step | Question | Config Keys Set |
|---|---|---|
| 2 | Embedding Provider | embedding.provider, embedding.model, optionally embedding.base_url, embedding.api_key or embedding.api_key_env |
| 3 | Summarization Provider | summarization.provider, summarization.model, optionally summarization.base_url, summarization.api_key or summarization.api_key_env |
| 4 | Storage Backend | storage.backend (chroma or postgres) |
| 5 | GraphRAG | graphrag.enabled, graphrag.store_type, graphrag.use_code_metadata |
| 6 | Default Query Mode | Written as YAML comment: # query.default_mode |
| Option | Provider Key | Model | Notes |
|---|---|---|---|
| Ollama (FREE, local) | ollama | nomic-embed-text | Requires Ollama running locally |
| OpenAI | openai | text-embedding-3-large | Requires OPENAI_API_KEY |
| Cohere | cohere | embed-multilingual-v3.0 | Requires COHERE_API_KEY, multi-language support |
| Google Gemini | gemini | text-embedding-004 | Requires GOOGLE_API_KEY |
| Custom | (user-specified) | (user-specified) | Specify provider, model, and base_url |
| Option | Provider Key | Model | Notes |
|---|---|---|---|
| Ollama (FREE, local) | ollama | llama3.2 | Requires Ollama running locally |
| Ollama + Mistral (FREE, local) | ollama | mistral-small3.2 | Better summarization quality |
| Anthropic | anthropic | claude-haiku-4-5-20251001 | Requires ANTHROPIC_API_KEY |
| OpenAI | openai | gpt-4o-mini | Requires OPENAI_API_KEY |
| Google Gemini | gemini | gemini-2.0-flash | Requires GOOGLE_API_KEY |
| Grok (xAI) | grok | grok-3-mini-fast | Requires XAI_API_KEY |
After answering all questions, the wizard writes a comprehensive config.yaml covering:
embedding.* — provider, model, api_key or api_key_env, optional base_urlsummarization.* — provider, model, api_key or api_key_env, optional base_urlstorage.* — backend selection and (if PostgreSQL) connection settingsgraphrag.* — enabled flag, store_type, use_code_metadata# query.default_mode as a YAML comment (informational)The file is chmod 600 automatically. A security warning is shown: never commit config.yaml to git.
PostgreSQL + BM25: When storage.backend: "postgres" is selected, the
disk-based BM25 index is replaced by PostgreSQL's built-in full-text search
(tsvector + websearch_to_tsquery). The --mode bm25 command works
identically from the user's perspective. Language is configurable via
storage.postgres.language (default: "english").
/agent-brain-config handles provider-specific details when called standalone (without the full wizard). It includes storage backend selection, indexing exclude patterns, and Ollama status checks.
python --versionpip install agent-brain-rag agent-brain-cli
Verify installation succeeded:
agent-brain --version
Expected: Version number displayed (e.g., 3.0.0 or current version)
pip install "agent-brain-rag[graphrag]" agent-brain-cli
# Kuzu backend (optional):
pip install "agent-brain-rag[graphrag-kuzu]" agent-brain-cli
export ENABLE_GRAPH_INDEX=true # Master switch (default: false)
export GRAPH_STORE_TYPE=simple # or kuzu
export GRAPH_INDEX_PATH=./graph_index
export GRAPH_USE_CODE_METADATA=true # Extract from AST metadata
export GRAPH_USE_LLM_EXTRACTION=true # Use LLM extractor when available
export GRAPH_MAX_TRIPLETS_PER_CHUNK=10 # Triplet cap per chunk
export GRAPH_TRAVERSAL_DEPTH=2 # Default traversal depth
export GRAPH_EXTRACTION_MODEL=claude-haiku-4-5
Add the same values to your .env if you prefer file-based config.
python -m venv .venv
source .venv/bin/activate # macOS/Linux
pip install agent-brain-rag agent-brain-cli
| Problem | Solution |
|---|---|
pip not found | Run python -m ensurepip |
| Permission denied | Use pip install --user or virtual env |
| Module not found after install | Restart terminal or activate venv |
| Wrong Python version | Use python3.10 -m pip install |
Counter-example - Wrong approach:
# DO NOT use sudo with pip
sudo pip install agent-brain-rag # Wrong - creates permission issues
Correct approach:
pip install --user agent-brain-rag # Correct - user installation
# OR use virtual environment
Agent Brain supports pluggable providers with two configuration methods.
Create a config.yaml file in one of these locations:
.agent-brain/config.yaml~/.agent-brain/config.yaml~/.config/agent-brain/config.yaml./config.yaml or ./agent-brain.yaml# ~/.agent-brain/config.yaml
server:
url: "http://127.0.0.1:8000"
port: 8000
project:
state_dir: null # null = use default (.agent-brain)
embedding:
provider: "openai"
model: "text-embedding-3-large"
api_key: "sk-proj-..." # Direct key, OR use api_key_env
# api_key_env: "OPENAI_API_KEY" # Read from env var
summarization:
provider: "anthropic"
model: "claude-haiku-4-5-20251001"
api_key: "sk-ant-..." # Direct key, OR use api_key_env
# api_key_env: "ANTHROPIC_API_KEY"
Config file search order: AGENT_BRAIN_CONFIG env → current dir → project dir → user home
Security: If storing API keys in config file:
chmod 600 ~/.agent-brain/config.yaml.gitignore: config.yamlSet variables in shell or .env file:
export EMBEDDING_PROVIDER=openai
export EMBEDDING_MODEL=text-embedding-3-large
export SUMMARIZATION_PROVIDER=anthropic
export SUMMARIZATION_MODEL=claude-haiku-4-5-20251001
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
Precedence order: CLI options → environment variables → config file → defaults
Best for privacy, air-gapped environments:
Config file (~/.agent-brain/config.yaml):
embedding:
provider: "ollama"
model: "nomic-embed-text"
base_url: "http://localhost:11434/v1"
summarization:
provider: "ollama"
model: "llama3.2"
base_url: "http://localhost:11434/v1"
Or environment variables:
export EMBEDDING_PROVIDER=ollama
export EMBEDDING_MODEL=nomic-embed-text
export SUMMARIZATION_PROVIDER=ollama
export SUMMARIZATION_MODEL=llama3.2
Prerequisite: Ollama must be installed and running with models pulled.
Config file:
embedding:
provider: "openai"
model: "text-embedding-3-large"
api_key: "sk-proj-..."
summarization:
provider: "anthropic"
model: "claude-haiku-4-5-20251001"
api_key: "sk-ant-..."
Or environment variables:
export OPENAI_API_KEY="sk-proj-..."
export ANTHROPIC_API_KEY="sk-ant-..."
embedding:
provider: "openai"
model: "text-embedding-3-large"
api_key: "sk-proj-..."
summarization:
provider: "ollama"
model: "llama3.2"
GraphRAG enables graph-based entity-relationship extraction for advanced query modes.
YAML config keys (config.yaml):
graphrag:
enabled: false # Master switch (default: false)
store_type: "simple" # "simple" (in-memory) or "kuzu" (persistent disk)
use_code_metadata: true # Extract entities from AST metadata (imports, classes)
Corresponding environment variables:
| Env Var | Config Key | Default | Description |
|---|---|---|---|
ENABLE_GRAPH_INDEX | graphrag.enabled | false | Master switch |
GRAPH_STORE_TYPE | graphrag.store_type | simple | simple or kuzu |
GRAPH_USE_CODE_METADATA | graphrag.use_code_metadata | true | AST metadata extraction |
Note: GraphRAG requires the --include-code flag during indexing to extract code structure:
agent-brain index ./src --include-code
For Kuzu (persistent), install the optional extra first:
pip install "agent-brain-rag[graphrag-kuzu]"
Agent Brain supports the following query modes, selectable per request with --mode:
| Mode | Description | Requirements |
|---|---|---|
hybrid | Vector similarity + BM25 keyword (recommended default) | None |
semantic | Pure vector similarity search | None |
bm25 | Keyword-only search (fast, no embedding needed) | None |
graph | Entity relationship graph traversal | GraphRAG + ChromaDB backend |
multi | Fuses vector + BM25 + graph with RRF | GraphRAG + ChromaDB backend |
Note: graph and multi modes are not available with PostgreSQL backend.
GraphRAG uses an in-memory/Kuzu graph store that is separate from the vector
store — it currently integrates only with ChromaDB.
Per-request override:
agent-brain query "authentication flow" --mode hybrid
agent-brain query "class relationships" --mode graph # GraphRAG + ChromaDB required
agent-brain query "how do services work" --mode multi # GraphRAG + ChromaDB required
Note: There is no global query.default_mode config key yet. Mode is per-request only. The setup wizard writes the selected default mode as a YAML comment for documentation purposes.
agent-brain verify
Counter-example - Common mistake:
# DO NOT put keys in shell command history
OPENAI_API_KEY="sk-proj-abc123" agent-brain start # Wrong - key in history
Correct approaches:
# Use config file (keys are in file, not command line)
agent-brain start
# Or use environment from shell profile
export OPENAI_API_KEY="sk-proj-..." # In ~/.bashrc
agent-brain start
Navigate to the project root and run:
agent-brain init
Verify initialization succeeded:
ls .agent-brain/config.json
Expected: File exists
agent-brain start
Verify server started:
agent-brain status
Expected output:
Server Status: healthy
Port: 49321
Documents: 0
Mode: project
agent-brain index ./docs
Verify indexing succeeded:
agent-brain status
Expected: Documents count > 0
agent-brain query "test query" --mode hybrid
Expected: Search results or "No results" (not an error)
Run each command and verify expected output:
agent-brain --version shows version number (7.0.0+)echo ${OPENAI_API_KEY:+SET} shows "SET" (if using OpenAI)ls .agent-brain/config.json file existsagent-brain status shows "healthy"agent-brain status shows document count > 0agent-brain query "test" returns results or "no matches"agent-brain folders list shows indexed foldersagent-brain types list shows file type presetsagent-brain jobs shows job queue (empty or with history)echo ${ENABLE_GRAPH_INDEX} shows "true"agent-brain status --json | jq '.graph_index' shows graph index infoagent-brain query "class relationships" --mode graph returns results or graceful erroragent-brain query "how it works" --mode multi returns fused resultsagent-brain verify
This runs all checks and reports any issues.
After indexing documents, verify the pipeline is working:
# Monitor indexing job
agent-brain jobs --watch
# Check job completed successfully
agent-brain jobs <job_id>
# Verify incremental indexing works
agent-brain index ./docs # Should show eviction summary with unchanged files
# Validate injection scripts before use
agent-brain inject ./docs --script enrich.py --dry-run
This skill focuses on installation and configuration. Do NOT use for:
using-agent-brain skill insteadusing-agent-brain skill insteadusing-agent-brain skill insteadusing-agent-brain skill insteadScope boundary: Once Agent Brain is installed, configured, initialized, and verified healthy, switch to the using-agent-brain skill for search operations.
pip install --force-reinstall agent-brain-rag agent-brain-cli
# Test OpenAI key
curl -s https://api.openai.com/v1/models \
-H "Authorization: Bearer $OPENAI_API_KEY" | head -c 100
Expected: JSON response (not error)
# Check for stale state
rm -f .agent-brain/runtime.json
rm -f .agent-brain/lock.json
agent-brain start
# Verify Ollama is running
curl http://localhost:11434/api/tags
Expected: JSON with model list
agent-brain status # Check document count
If count is 0, index documents:
agent-brain index ./docs
| Variable | Required | Default | Description |
|---|---|---|---|
AGENT_BRAIN_CONFIG | No | - | Path to config.yaml file |
AGENT_BRAIN_URL | No | http://127.0.0.1:8000 | Server URL for CLI |
AGENT_BRAIN_STATE_DIR | No | .agent-brain | State directory path |
EMBEDDING_PROVIDER | No | openai | Provider: openai, cohere, ollama |
EMBEDDING_MODEL | No | text-embedding-3-large | Model name |
SUMMARIZATION_PROVIDER | No | anthropic | Provider: anthropic, openai, gemini, grok, ollama |
SUMMARIZATION_MODEL | No | claude-haiku-4-5-20251001 | Model name |
OPENAI_API_KEY | Conditional | - | Required if using OpenAI |
ANTHROPIC_API_KEY | Conditional | - | Required if using Anthropic |
GOOGLE_API_KEY | Conditional | - | Required if using Gemini |
XAI_API_KEY | Conditional | - | Required if using Grok |
COHERE_API_KEY | Conditional | - | Required if using Cohere |
EMBEDDING_CACHE_MAX_MEM_ENTRIES | No | 1000 | Max in-memory LRU entries (~12 MB at 3072 dims per 1000 entries) |
EMBEDDING_CACHE_MAX_DISK_MB | No | 500 | Max disk size for the SQLite embedding cache |
Note: Environment variables override config file values. Config file values override defaults.
The embedding cache is automatic — no setup required. Embeddings are cached on first compute and reused on subsequent reindexes of unchanged content, significantly reducing OpenAI API costs when using file watching or frequent reindexing.
The two cache env vars allow tuning for specific environments:
EMBEDDING_CACHE_MAX_MEM_ENTRIES (e.g., 5000) to keep more embeddings
in the fast in-memory tier and reduce SQLite lookupsEMBEDDING_CACHE_MAX_MEM_ENTRIES (e.g., 200) to
limit RAM usage; the disk cache still provides cost savings even with a small memory tierEMBEDDING_CACHE_MAX_DISK_MB (e.g., 100) to cap the SQLite
cache database size; oldest entries are evicted when the limit is reachedThe disk cache uses SQLite with WAL mode for safe concurrent access during indexing operations.
The query cache is automatic — no setup required. Identical queries within the TTL window return instantly without hitting storage.
graph and multi modes bypass the cache — each call reaches storage
for fresh results.QUERY_CACHE_TTL — cache TTL in seconds (default: 300, i.e., 5 minutes)QUERY_CACHE_MAX_SIZE — max cached query results (default: 256)| Guide | Description |
|---|---|
| Configuration Guide | Config file format and locations |
| Installation Guide | Detailed installation options |
| Provider Configuration | All provider settings |
| Troubleshooting Guide | Extended issue resolution |