{"id":50682280,"url":"https://github.com/SpillwaveSolutions/agent-brain","last_synced_at":"2026-06-25T18:00:58.965Z","repository":{"id":329336531,"uuid":"1117943302","full_name":"SpillwaveSolutions/agent-brain","owner":"SpillwaveSolutions","description":"Private RAG system with semantic context ingestion to improve source of truth of reliable sources","archived":false,"fork":false,"pushed_at":"2026-06-23T04:59:43.000Z","size":15765,"stargazers_count":109,"open_issues_count":22,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-06-23T06:17:33.613Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SpillwaveSolutions.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmaps/change_request_prd_multi_clients.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-17T03:28:50.000Z","updated_at":"2026-06-23T04:59:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/SpillwaveSolutions/agent-brain","commit_stats":null,"previous_names":["spillwavesolutions/doc-serve-skill"],"tags_count":40,"template":false,"template_full_name":null,"purl":"pkg:github/SpillwaveSolutions/agent-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpillwaveSolutions%2Fagent-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpillwaveSolutions%2Fagent-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpillwaveSolutions%2Fagent-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpillwaveSolutions%2Fagent-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SpillwaveSolutions","download_url":"https://codeload.github.com/SpillwaveSolutions/agent-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SpillwaveSolutions%2Fagent-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34786231,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-25T02:00:05.521Z","response_time":101,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T20:00:23.310Z","updated_at":"2026-06-25T18:00:58.906Z","avatar_url":"https://github.com/SpillwaveSolutions.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"---\nlast_validated: 2026-03-16\n---\n\n# Agent Brain\n\nA 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.\n\n## Overview\n\nAgent 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.\n\n| Component | Description |\n|-----------|-------------|\n| **Plugin** | 24 slash commands, 3 agents, 2 skills for Claude Code |\n| **Skills** | Intelligent search mode selection and query optimization |\n| **Agents** | Research assistant, search assistant, setup assistant |\n| **Server** | FastAPI backend for indexing and retrieval |\n| **CLI** | Command-line tool (also used by plugin internally) |\n\n## Quick Start (Claude Code Plugin)\n\n### 1. Install the Plugin\n\n```bash\nclaude plugins install github:SpillwaveSolutions/agent-brain\n```\n\n### 2. Set Up Your Project\n\nIn Claude Code, run:\n```\n/agent-brain-setup\n```\n\nThis interactive wizard will:\n- Install the Python packages (`agent-brain-rag`, `agent-brain-cli`)\n- Configure your API keys\n- Initialize the project\n- Start the server\n- Index your documentation\n\n### 3. Search with Commands\n\n```\n/agent-brain-search \"how does authentication work\"\n```\n\nThat's it! The plugin handles everything automatically.\n\n## Plugin Commands\n\n### Search Commands\n\n| Command | Description | Use When |\n|---------|-------------|----------|\n| `/agent-brain-search` | Smart hybrid search (recommended) | General questions |\n| `/agent-brain-semantic` | Pure semantic/vector search | Conceptual queries |\n| `/agent-brain-keyword` | BM25 keyword search | Error messages, function names |\n| `/agent-brain-hybrid` | Hybrid with alpha tuning | Fine-tuned searches |\n| `/agent-brain-graph` | Knowledge graph search | \"What calls X?\", dependencies |\n| `/agent-brain-multi` | All modes combined (RRF) | Maximum recall |\n\n### Server Commands\n\n| Command | Description |\n|---------|-------------|\n| `/agent-brain-start` | Start the server (auto-port) |\n| `/agent-brain-stop` | Stop the server |\n| `/agent-brain-status` | Check health and document count |\n| `/agent-brain-index` | Index documents or code |\n\n### Setup Commands\n\n| Command | Description |\n|---------|-------------|\n| `/agent-brain-setup` | Complete guided setup wizard |\n| `/agent-brain-install` | Install pip packages |\n| `/agent-brain-init` | Initialize project directory |\n| `/agent-brain-verify` | Verify configuration |\n| `/agent-brain-providers` | Configure embedding/summarization providers |\n\n## Plugin Agents\n\nAgent Brain includes three intelligent agents for complex tasks:\n\n| Agent | Description | Triggered By |\n|-------|-------------|--------------|\n| **Search Assistant** | Multi-step search across modes, synthesizes answers | \"Find all references to...\", \"Research how...\" |\n| **Research Assistant** | Deep exploration with follow-up queries | \"Investigate...\", \"Analyze the architecture of...\" |\n| **Setup Assistant** | Guided installation and troubleshooting | \"Help me set up Agent Brain\", configuration issues |\n\n### Example Agent Interaction\n\n**You**: \"Research how authentication is implemented across the codebase\"\n\n**Research Assistant**:\n1. Searches documentation for auth concepts\n2. Queries code for auth-related functions\n3. Uses graph mode to find dependencies\n4. Synthesizes comprehensive answer with references\n\n## Plugin Skills\n\nSkills provide intelligent context to Claude for optimal searching:\n\n| Skill | Purpose |\n|-------|---------|\n| **using-agent-brain** | Search mode selection, query optimization, API knowledge |\n| **configuring-agent-brain** | Installation, provider configuration, troubleshooting |\n\nWhen you ask about documentation or code, Claude automatically uses the skill to:\n- Choose the best search mode for your query\n- Set appropriate parameters (top_k, threshold, alpha)\n- Interpret and synthesize results\n\n## Search Modes\n\n| Mode | Best For | Example Query |\n|------|----------|---------------|\n| `HYBRID` | General questions (default) | \"How does caching work?\" |\n| `VECTOR` | Conceptual understanding | \"Explain the architecture\" |\n| `BM25` | Exact terms, error codes | \"NullPointerException\", \"getUserById\" |\n| `GRAPH` | Relationships, dependencies | \"What classes use AuthService?\" |\n| `MULTI` | Comprehensive search | \"Everything about data validation\" |\n\n## Pluggable Providers\n\nAgent Brain supports multiple providers for embeddings and summarization:\n\n### Embedding Providers\n| Provider | Models | Local |\n|----------|--------|-------|\n| OpenAI | text-embedding-3-large, text-embedding-3-small | No |\n| Ollama | nomic-embed-text, mxbai-embed-large | Yes |\n| Cohere | embed-english-v3.0, embed-multilingual-v3.0 | No |\n\n### Summarization Providers\n| Provider | Models | Local |\n|----------|--------|-------|\n| Anthropic | claude-haiku-4-5-20251001, claude-sonnet-4-5-20250514 | No |\n| OpenAI | gpt-5, gpt-5-mini | No |\n| Gemini | gemini-3-flash, gemini-3-pro | No |\n| Grok | grok-4, grok-4-fast | No |\n| Ollama | llama4:scout, mistral-small3.2, qwen3-coder | Yes |\n\n### Fully Local Mode\n\nRun completely offline with Ollama:\n```\n/agent-brain-providers\n# Select Ollama for both embeddings and summarization\n```\n\n## Features\n\n### Code Search\n- **10 Programming Languages**: Python, TypeScript, JavaScript, Java, Kotlin, C, C++, C#, Go, Rust, Swift\n- **AST-Aware Chunking**: Tree-sitter parsing preserves code structure\n- **LLM Summaries**: AI-generated descriptions improve semantic search\n- **Language Filtering**: Filter results by programming language\n\n### GraphRAG (Knowledge Graph)\n- Entity and relationship extraction\n- Dependency-aware queries (\"What calls X?\")\n- Code structure visualization\n\n### Multi-Instance Architecture\n- Per-project isolated servers\n- Automatic port allocation\n- Work on multiple projects simultaneously\n\n## Project Structure\n\n```\nagent-brain/\n├── agent-brain-plugin/        # Claude Code plugin (primary interface)\n│   ├── commands/              # 24 slash commands\n│   ├── agents/                # 3 intelligent agents\n│   └── skills/                # 2 context skills\n├── agent-brain-server/        # FastAPI backend\n├── agent-brain-cli/           # CLI tool (used by plugin)\n└── docs/                      # Documentation\n```\n\n## Documentation\n\n### Getting Started\n- [Quick Start](docs/QUICK_START.md) - Get running in minutes\n- [Plugin Guide](docs/PLUGIN_GUIDE.md) - Complete plugin documentation\n- [User Guide](docs/USER_GUIDE.md) - Detailed usage guide\n\n### Reference\n- [API Reference](docs/API_REFERENCE.md) - REST API documentation\n- [Configuration](docs/CONFIGURATION.md) - All configuration options\n- [Provider Configuration](agent-brain-plugin/skills/using-agent-brain/references/provider-configuration.md) - Provider setup\n- [Integrations](docs/INTEGRATIONS.md) - Connect agent-brain-mcp to LLM frameworks + editors\n\n### Architecture\n- [Architecture Overview](docs/ARCHITECTURE.md) - System design\n- [GraphRAG Guide](docs/GRAPHRAG_GUIDE.md) - Knowledge graph features\n- [Code Indexing](docs/CODE_INDEXING.md) - AST-aware chunking\n\n## CLI Usage (Alternative)\n\nWhile the plugin is the recommended interface, you can also use the CLI directly:\n\n```bash\n# Install\npip install agent-brain-rag agent-brain-cli\n\n# Initialize and start\nagent-brain init                     # auto-generates a per-project API key\nagent-brain start --daemon\n\n# Index and query\nagent-brain index /path/to/docs --include-code\nagent-brain query \"authentication\" --mode hybrid\n```\n\n\u003e **Note on authentication.** As of the next release, every data endpoint\n\u003e requires `X-API-Key`. `agent-brain init` writes a 32-byte urlsafe key\n\u003e into `.agent-brain/config.json` (mode `0o600`); the CLI and\n\u003e `agent-brain-mcp` pick it up automatically. Pass `--no-api-key` to\n\u003e `agent-brain init` for the legacy no-auth experience on `127.0.0.1`.\n\u003e The server refuses to start on any non-loopback bind without a key\n\u003e set. See [`docs/CHANGELOG.md`](docs/CHANGELOG.md) under the unreleased\n\u003e entry for the full design (Issue #179).\n\n## Development\n\n### Prerequisites\n- Python 3.10+\n- Poetry (dependency management)\n- Task (task runner)\n\n### Setup\n```bash\ngit clone https://github.com/SpillwaveSolutions/agent-brain.git\ncd agent-brain\ntask install\n```\n\n### Running Tests\n```bash\ntask test           # All tests\ntask before-push    # Full quality check\n```\n\n## Technology Stack\n\n- **Plugin**: Claude Code slash commands, agents, skills\n- **Server**: FastAPI + Uvicorn\n- **Vector Store**: ChromaDB (HNSW, cosine similarity)\n- **BM25 Index**: LlamaIndex BM25Retriever\n- **Graph Store**: SimplePropertyGraphStore / Kuzu\n- **Embeddings**: OpenAI or Ollama\n- **Summarization**: Claude, GPT-5, Gemini, Grok, or Ollama\n- **AST Parsing**: tree-sitter (10 languages)\n- **CLI**: Click + Rich\n- **Build System**: Poetry\n\n## Contributing\n\nSee the [Developer Guide](docs/DEVELOPERS_GUIDE.md) for setup instructions.\n\n**Before pushing changes**, always run:\n```bash\ntask before-push\n```\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Links\n\n- [GitHub Wiki](https://github.com/SpillwaveSolutions/agent-brain/wiki)\n- [Plugin Marketplace](https://skillzwave.ai/)\n- [Issue Tracker](https://github.com/SpillwaveSolutions/agent-brain/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSpillwaveSolutions%2Fagent-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSpillwaveSolutions%2Fagent-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSpillwaveSolutions%2Fagent-brain/lists"}