doc-serve-skill

内容来源：README.md（说明文档） · 原始地址 · 查看安装指南

原始内容

---
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)).

### 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](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/QUICK_START.md) - Get running in minutes
- [Plugin Guide](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/PLUGIN_GUIDE.md) - Complete plugin documentation
- [User Guide](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/USER_GUIDE.md) - Detailed usage guide
- [MCP Quickstart](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/MCP_QUICKSTART.md) - Use Agent Brain over MCP in ~5 minutes
- [Project Setup: Plugin + Skills + MCP](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/PROJECT_SETUP_PLUGIN_SKILLS_MCP.md) - Wire all three into one project

### Reference
- [API Reference](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/API_REFERENCE.md) - REST API documentation
- [MCP User Guide](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/MCP_USER_GUIDE.md) - MCP server: 16 tools, resources, prompts, OAuth
- [Configuration](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/CONFIGURATION.md) - All configuration options
- [Provider Configuration](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/agent-brain-plugin/skills/using-agent-brain/references/provider-configuration.md) - Provider setup
- [Integrations](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/INTEGRATIONS.md) - Connect agent-brain-mcp to LLM frameworks + editors

### Architecture
- [Architecture Overview](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/ARCHITECTURE.md) - System design
- [GraphRAG Guide](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/docs/GRAPHRAG_GUIDE.md) - Knowledge graph features
- [Code Indexing](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/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`](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/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](https://github.com/SpillwaveSolutions/doc-serve-skill/blob/HEAD/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)

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

# 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).

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:

Searches documentation for auth concepts
Queries code for auth-related functions
Uses graph mode to find dependencies
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 - Get running in minutes
Plugin Guide - Complete plugin documentation
User Guide - Detailed usage guide
MCP Quickstart - Use Agent Brain over MCP in ~5 minutes
Project Setup: Plugin + Skills + MCP - Wire all three into one project

Reference

API Reference - REST API documentation
MCP User Guide - MCP server: 16 tools, resources, prompts, OAuth
Configuration - All configuration options
Provider Configuration - Provider setup
Integrations - Connect agent-brain-mcp to LLM frameworks + editors

Architecture

Architecture Overview - System design
GraphRAG Guide - Knowledge graph features
Code Indexing - AST-aware chunking

CLI Usage (Alternative)

While the plugin is the recommended interface, you can also use the CLI directly:

# 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 under the unreleased entry for the full design (Issue #179).

Development

Prerequisites

Python 3.10+
Poetry (dependency management)
Task (task runner)

Setup

git clone https://github.com/SpillwaveSolutions/agent-brain.git
cd agent-brain
task install

Running Tests

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 for setup instructions.

Before pushing changes, always run:

task before-push

License

MIT License - see LICENSE file for details.