agent-brain-rag 2.0.0

Agent Brain RAG - Intelligent document indexing and semantic search server that gives AI agents long-term memory

Agent Brain RAG Server

Agent Brain (formerly doc-serve) is an intelligent document indexing and semantic search system designed to give AI agents long-term memory.

AI agents need persistent memory to be truly useful. Agent Brain provides the retrieval infrastructure that enables context-aware, knowledge-grounded AI interactions.

Installation

pip install agent-brain-rag

Quick Start

1. Set environment variables:

   export OPENAI_API_KEY=your-key
   export ANTHROPIC_API_KEY=your-key
   

2. Start the server:

   agent-brain-serve
   

The server will start at http://127.0.0.1:8000.

Note: The legacy command doc-serve is still available but deprecated. Please use agent-brain-serve for new installations.

Search Capabilities

Agent Brain provides multiple search strategies to match your retrieval needs:

Search Type	Description	Best For
Semantic Search	Natural language queries using OpenAI embeddings (text-embedding-3-large)	Conceptual questions, finding related content
Keyword Search (BM25)	Traditional keyword matching with TF-IDF ranking	Exact matches, technical terms, code identifiers
Hybrid Search	Combines vector + BM25 for best of both approaches	General-purpose queries, balanced recall/precision
GraphRAG	Knowledge graph-based retrieval for relationship-aware queries	Understanding connections, multi-hop reasoning

Features

• Document Indexing: Load and index documents from folders (PDF, Markdown, TXT, DOCX, HTML)
• AST-Aware Code Ingestion: Smart parsing for Python, TypeScript, JavaScript, Java, Go, Rust, C, C++
• Multi-Strategy Retrieval: Semantic, keyword, hybrid, and graph-based search
• OpenAI Embeddings: Uses text-embedding-3-large for high-quality embeddings
• Claude Summarization: AI-powered code summaries for better context
• Chroma Vector Store: Persistent, thread-safe vector database
• FastAPI: Modern, high-performance REST API with OpenAPI documentation

Prerequisites

• Python 3.10+
• OpenAI API key (for embeddings)
• Anthropic API key (for summarization)

Development Installation

cd agent-brain-server
poetry install

Configuration

Copy the environment template and configure:

cp ../.env.example .env
# Edit .env with your API keys

Required environment variables:

• OPENAI_API_KEY: Your OpenAI API key for embeddings
• ANTHROPIC_API_KEY: Your Anthropic API key for summarization

Running the Server

# Development mode
poetry run uvicorn agent_brain_server.api.main:app --reload

# Or use the entry point
poetry run agent-brain-serve

API Documentation

Once running, visit:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc
• OpenAPI JSON: http://127.0.0.1:8000/openapi.json

API Endpoints

Health

• GET /health - Server health status
• GET /health/status - Detailed indexing status

Indexing

• POST /index - Start indexing documents from a folder
• POST /index/add - Add documents to existing index
• DELETE /index - Reset the index

Querying

• POST /query - Semantic search query
• GET /query/count - Get indexed document count

Example Usage

Index Documents

curl -X POST http://localhost:8000/index \
  -H "Content-Type: application/json" \
  -d '{"folder_path": "/path/to/docs"}'

Query Documents

curl -X POST http://localhost:8000/query \
  -H "Content-Type: application/json" \
  -d '{"query": "How do I configure authentication?", "top_k": 5}'

Architecture

agent_brain_server/
├── api/
│   ├── main.py           # FastAPI application
│   └── routers/          # Endpoint handlers
├── config/
│   └── settings.py       # Configuration management
├── models/               # Pydantic request/response models
├── indexing/
│   ├── document_loader.py  # Document loading
│   ├── chunking.py         # Text chunking
│   └── embedding.py        # Embedding generation
├── services/
│   ├── indexing_service.py # Indexing orchestration
│   └── query_service.py    # Query execution
└── storage/
    └── vector_store.py     # Chroma vector store

Development

Running Tests

poetry run pytest

Code Formatting

poetry run black agent_brain_server/
poetry run ruff check agent_brain_server/

Type Checking

poetry run mypy agent_brain_server/

Documentation

• User Guide - Getting started and usage
• Developer Guide - Contributing and development
• API Reference - Full API documentation

Release Information

• Current Version: See pyproject.toml
• Release Notes: GitHub Releases
• Changelog: Latest Release

Related Packages

• agent-brain-cli - Command-line interface for Agent Brain

License

MIT