Overview

TeaRAGs is an MCP server that orchestrates code vectorization, trajectory enrichment, and quality-aware retrieval. It sits between the AI agent and the vector database, managing the complexity of embedding, git metadata extraction, and reranking.

System Architecture

Component Layers

1. Agent Layer

The AI agent (Claude Code, Roo, Cursor, or custom) orchestrates the overall workflow:

• Decides when to search code
• Formulates natural language queries
• Interprets search results
• Verifies findings with grep (best practice)
• Makes code generation decisions

The agent communicates with TeaRAGs via the MCP protocol (stdio or HTTP transport).

2. TeaRAGs MCP Server (Orchestration Engine)

TeaRAGs is the central orchestrator with six internal subsystems:

Component	Responsibility	Key Details
Code Indexer	Scans codebase, performs AST-aware chunking via tree-sitter	Respects .gitignore / .contextignore. Handles incremental updates (added/modified/deleted files)
Git Enricher	Extracts metadata from git log and git blame	Computes 19 signals: churn, volatility, authorship, bug-fix rates, task IDs. File-level and chunk-level granularity
Search Engine	Converts queries to vectors, applies filters, executes search	Qdrant filters (language, path, git metadata). Semantic search and hybrid search (BM25 + RRF)
Reranker	Re-scores results using trajectory signals	Composable presets: hotspots, ownership, techDebt, stable, etc. Custom weight configs supported
Embedding Pipeline	Batches chunks for efficient embedding generation	Manages concurrency, retry logic, backpressure. Supports Ollama, OpenAI, Cohere, Voyage AI
MCP Tools Handler	Exposes MCP tools, handles invocation and validation	Tools: index_codebase, search_code, semantic_search, reindex_changes

3. External Services

Service	Role	Details
Qdrant	Vector database	Dense vectors (768–3072 dim), sparse vectors (BM25 for hybrid search), payload (19 git signals + file metadata). Cosine similarity search at scale
Embedding Service	Text → vector conversion	Ollama (local, recommended: jina-embeddings-v2-base-code), OpenAI (text-embedding-3-small/large), Cohere (embed-english-v3.0), Voyage AI (voyage-code-2)

4. Data Sources

Source	Purpose	Details
Codebase	Source files and documentation	TypeScript, Python, Go, Ruby, Markdown, README. Respects .gitignore exclusion rules
Git Repository	History for trajectory enrichment	Commit history, author metadata, timestamps. Task IDs from commit messages (JIRA, GitHub, Linear)
Cache Storage (~/.tea-rags-mcp/)	Incremental indexing and performance	Snapshots — file hash snapshots. Git cache — L1 (memory) + L2 (disk) for git blame. Logs — debug logs (DEBUG=1)

Request Flow

A typical search request flows through six steps:

1. Agent Invocation

Agent: search_code "authentication logic" --rerank stable

2. Query Embedding

TeaRAGs sends the query to the Embedding Service:

"authentication logic" → [0.23, -0.41, 0.18, ...]

3. Vector Search

TeaRAGs queries Qdrant with:

• Query vector
• Optional filters (language, path, author, etc.)
• Limit (default: 50 candidates)

4. Semantic Ranking

Qdrant returns top 50 chunks ranked by cosine similarity:

[
  {"path": "src/auth/middleware.ts", "score": 0.91, "git": {...}},
  {"path": "src/auth/jwt.ts", "score": 0.87, "git": {...}},
  ...
]

5. Trajectory Reranking

TeaRAGs re-scores results using git signals and the stable preset:

• Boosts low-churn, low-bugfix code
• Penalizes high-volatility code
• Returns top 5 chunks

6. Agent Decision

Agent receives enriched results:

• Reads candidate files
• Verifies with grep (e.g., grep "function authenticate")
• Uses actual identifiers in generated code

Key Principles

TeaRAGs as Orchestrator

TeaRAGs does not replace the agent's decision-making. It provides:

• High-recall candidate selection (semantic search finds relevant code)
• Quality signals (trajectory enrichment quantifies stability, ownership, risk)
• Structured results (file paths, line numbers, metadata)

The agent still:

• Decides which code to use
• Verifies exact identifiers with grep
• Generates final code

Separation of Concerns

Component	Responsibility
Agent	Workflow orchestration, decision-making, verification
TeaRAGs	Indexing, embedding, enrichment, reranking
Qdrant	Vector storage, similarity search
Embedding Service	Text → vector conversion
Git	Source of truth for code history

Data Flow Direction

Indexing:  Codebase + Git → TeaRAGs → Embedding Service → Qdrant
Searching: Agent → TeaRAGs → Qdrant (retrieve) → TeaRAGs (rerank) → Agent

Performance Characteristics

• Indexing: Millions of LOC in minutes (see benchmarks)
• Search: Near-instant (<1s for most queries)
• Incremental updates: Only changed files re-indexed
• Concurrency: Configurable batch sizes, parallel workers
• Caching: Git metadata cached, embedding pipeline batched

Next Steps

• Indexing Pipeline — deep dive into code vectorization
• Data Model — chunk schema, payload structure, vector dimensions
• Pipeline Stages — chunking, embedding, enrichment stages
• Cache Lifecycle — snapshot management, incremental updates