Skip to content

First008/mesh

BranchesTags

Repository files navigation

MESH 🕸️

Multi-repository AI Code Assistant with Semantic Search. Ask questions about your codebase, get accurate answers based on actual code with file:line references.

Quick Start • Architecture • Configuration • API • Development

What is MESH?

MESH is a semantic search gateway for codebases. It indexes code into vector embeddings, performs intelligent search, and uses LLMs to answer questions with zero hallucinations.

Problem vs Solution

Without MESH With MESH
AI hallucinates non-existent code Answers strictly from indexed code
Manual grep/find through thousands of files Semantic search finds relevant code automatically
Context scattered across repos Single gateway for all repositories
Separate AI setup per project One service, unlimited repos

Key Features

  • Semantic Search: Vector embeddings with Qdrant, chunk aggregation for complete files
  • Multi-Repository: Single gateway manages unlimited repos with branch-aware indexing
  • Cost Optimized: 90% cost reduction via Anthropic prompt caching, incremental indexing
  • Universal Integration: REST API, MCP protocol for Claude Code, GitHub webhooks
  • Zero Hallucinations: Strict context-only constraints, file:line references for all claims

Quick Start

Prerequisites

  • Docker and Docker Compose
  • Ollama (free local embeddings) OR OpenAI API key
  • Anthropic API key (recommended) OR OpenAI/Ollama for LLM

1. Install Ollama (Recommended)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
or 
brew install ollama

# Start service
ollama serve

# Pull embedding model (1.3GB)
ollama pull bge-m3

2. Configure

git clone https://github.com/First008/mesh.git
cd mesh

# Create .env in mesh root directory
cat > .env << EOF
ANTHROPIC_API_KEY=sk-ant-your-key-here
LOG_LEVEL=info
# Optional: Set if mesh is not in same directory as other repos
# BASE_DIR=/path/to/parent/directory
EOF

Directory Structure:

/your/projects/
  ├── mesh/              (this repository)
  ├── repo1/             (your codebases)
  ├── repo2/
  └── repo3/

If your repos are siblings to mesh (as above), you don't need BASE_DIR - the default works. If mesh is elsewhere, set BASE_DIR=/your/projects in .env.

Create configs/repos.yaml: Prepare repositories with proper name, path (relative to /repos mount), focus paths, exclude patterns and personality for best results.

3. Start

# Start services (from project root)
docker compose up -d

# Watch logs
docker compose logs -f mesh-gateway

# Wait for: "INF Gateway initialized successfully"

4. Query

# Health check
curl http://localhost:9000/health

# Ask a question
curl -X POST http://localhost:9000/ask/your-repo \
  -H 'Content-Type: application/json' \
  -d '{"question":"How does authentication work?"}'

Response includes:

  • Answer with code snippets and file:line references
  • Token usage (input/output/cached)
  • Cost tracking per query

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  MESH Gateway (Single Container)            │
│  ┌────────────┐              ┌──────────────────────┐       │
│  │ HTTP Server│              │  Branch Scanner      │       │
│  │ Port 9000  │              │  Auto Re-index       │       │
│  └─────┬──────┘              └──────────────────────┘       │
│        │                                                     │
│  ┌─────▼──────────────────────────────────────────────┐     │
│  │      Repository Agents (Per Repo)                  │     │
│  │  ┌──────────────┐  ┌──────────────┐               │     │
│  │  │ Repo 1 Agent │  │ Repo 2 Agent │    ... more   │     │
│  │  │ ├─ LLM       │  │ ├─ LLM       │               │     │
│  │  │ ├─ Vector    │  │ ├─ Vector    │               │     │
│  │  │ └─ Context   │  │ └─ Context   │               │     │
│  │  └──────────────┘  └──────────────┘               │     │
│  └────────────────────────────────────────────────────┘     │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
        ┌─────────────────────────────────┐
        │   Qdrant Vector Database        │
        │   (Branch-Aware Collections)    │
        │                                 │
        │  mesh-repo1-main-v1             │
        │  mesh-repo1-staging-v1          │
        │  mesh-repo2-develop-v1          │
        └─────────────────────────────────┘

Core Components

Component Location Purpose
Gateway internal/gateway Multi-repo orchestration, branch scanning
Agent internal/agent Per-repo LLM integration, context building
Vector Store internal/vectorstore Indexing, semantic search, chunking
Context Builder internal/context File selection, context layering
LLM Providers internal/llm Anthropic, OpenAI, Ollama adapters
HTTP Server internal/server REST API endpoints
MCP Server internal/mcp Model Context Protocol for Claude Code

Execution Modes (single binary):

  • Gateway: Multi-repo (recommended)
  • HTTP: Single-repo backward compatibility
  • MCP: Claude Code integration

See ARCHITECTURE.md for detailed design.

Configuration

Repository Configuration (configs/repos.yaml)

port: 9000
qdrant_url: "qdrant:6334"

# Embedding config
embedding_provider: "ollama"          # ollama | openai
embedding_model: "bge-m3"             # bge-m3 (8K context) | nomic-embed-text (2K)
ollama_url: "http://host.docker.internal:11434"

# LLM config
llm_provider: "anthropic"             # anthropic | openai | ollama
llm_model: "claude-sonnet-4-5-20250929"

# Repositories
repos:
  - name: my-backend
    path: /repos/my-backend
    focus_paths:                      # Optional: prioritize important code
      - internal/**
      - pkg/**
    personality: |                     # Optional: customize AI expertise
      Expert in Go microservices, gRPC, distributed systems.

Docker Compose

Uses docker-compose.yml in the project root for the gateway (single file for multi-repo setup).

Volume Mount Configuration: The compose file automatically mounts your repositories using BASE_DIR from .env:

volumes:
  - ${BASE_DIR:-../../..}:/repos:ro  # Auto-discovers sibling repos

No configuration needed if your directory structure is:

/your/projects/
  ├── mesh/
  ├── repo1/
  └── repo2/

Custom location? Set in .env:

BASE_DIR=/path/to/your/projects

Embedding Models

Model Context Quality Speed Use Case
bge-m3 8K tokens Highest ~6s Production (recommended)
nomic-embed-text 2K tokens Good ~2s Fast iteration, small files only (large files will fail)

LLM Providers

Anthropic Claude (Recommended):

  • 90% cost reduction via prompt caching
  • Best code understanding quality
  • ~$0.03-0.10 per query

Ollama (Free):

  • Zero cost, runs locally
  • Requires 32GB+ RAM, GPU recommended
  • Models: llama3.3:70b, deepseek-coder-v2

OpenAI:

  • Good quality, no caching support
  • ~$0.05-0.30 per query

API Reference

Endpoints

Endpoint Method Description
/health GET Service health check
/info GET Service information (mode, model, etc)
/metrics GET Usage statistics (gateway only)
/repos GET List indexed repositories with branch info (gateway only)
/repos/:repo GET Get specific repository info (gateway only)
/ask POST Query repository (single-repo mode)
/ask/:repo POST Query specific repository (gateway mode)
/ask-all POST Query all repositories (gateway mode)
/repos/:repo/reindex POST Trigger incremental re-indexing (gateway only)
/webhooks/github POST GitHub webhook receiver (gateway only)

Query Example

Request:

curl -X POST http://localhost:9000/ask/my-backend \
  -H 'Content-Type: application/json' \
  -d '{"question":"How does retry logic work?"}'

Response:

{
  "answer": "Based on [internal/retry/retry.go:45]:\n\n```go\nfunc RetryWithBackoff(fn func() error, maxRetries int) error {\n    for i := 0; i < maxRetries; i++ {\n        if err := fn(); err == nil {\n            return nil\n        }\n        time.Sleep(backoff(i))\n    }\n    return ErrMaxRetriesExceeded\n}\n```\n\nThe system uses exponential backoff...",
  "repo": "my-backend",
  "model": "claude-sonnet-4-5-20250929",
  "usage": {
    "input_tokens": 15420,
    "output_tokens": 1893,
    "cached_tokens": 13200
  }
}

List Repositories

Request:

curl http://localhost:9000/repos | jq

Response:

{
  "repos": [
    {
      "name": "my-backend",
      "path": "/repos/my-backend",
      "branch": "main",
      "indexed_at": "2025-12-28T10:30:00Z",
      "file_count": 247,
      "commit_sha": "abc123..."
    }
  ],
  "count": 1
}

Development

Build

# Install dependencies
go mod download

# Build all binaries
make build-all

# Build specific binaries
make build                # mesh-agent (gateway/HTTP/MCP)
make build-mcp-bridge     # MCP bridge for Claude Code
make build-indexer        # Standalone indexer

Run Locally

# Gateway mode (multi-repo)
make run-gateway

# HTTP mode (single repo)
make run

# MCP mode (Claude Code integration)
make run-mcp

Test

# All tests
make test

# With coverage
make test-coverage

# With race detection
make test-race

# Specific package
go test ./internal/vectorstore/...

Docker

# Build and start
make docker-up

# View logs
make docker-logs

# Stop
make docker-down

# Rebuild
make docker-build

Extend

Add new embedding provider: Implement EmbeddingProvider interface in internal/vectorstore/:

type EmbeddingProvider interface {
    CreateEmbedding(ctx context.Context, text string) ([]float32, error)
    GetModelName() string
    GetDimensions() int
}

Add new LLM provider: Implement LLMProvider interface in internal/llm/:

type LLMProvider interface {
    Ask(systemPrompt, userPrompt string) (Response, error)
    AskWithCache(systemPrompt, cacheableContext, regularContext, question string) (Response, error)
    SupportsPromptCaching() bool
    CountTokens(text string) int
}

See CONTRIBUTING.md for guidelines.

Branch Management

MESH automatically tracks the current git branch for each repository:

# Automatically indexes current branch on startup
docker compose up -d

# Switch branch and re-index
cd /repos/my-backend
git checkout develop
curl -X POST http://localhost:9000/repos/my-backend/reindex

# Auto re-indexing every 5 minutes via BranchScanner
# Or trigger via GitHub webhook on push

Collections are branch-specific: mesh-{repo}-{branch}-v1

Performance

Indexing (typical 250-file repo):

  • Initial: 2-6 minutes
  • Incremental: 1-5 seconds (only changed files)
  • Workers: 2-6 parallel (adaptive)

Query:

  • Semantic search: 50-100ms
  • Total latency: 2-15 seconds (including LLM)

Resource Usage (tested: 9 repos, 2000 files):

  • Memory: 1.2GB (gateway 600MB + Qdrant 600MB)
  • Disk: ~5MB per 1000 files

Requirements:

  • Minimum: 2GB RAM, 2 CPU cores, 10GB disk
  • Recommended: 4GB RAM, 4 CPU cores, 20GB SSD
  • With local Ollama LLM: 32GB+ RAM, GPU with 24GB+ VRAM

Technology Stack

  • Go: 1.24.1
  • Qdrant: Vector database (HNSW indexing)
  • Anthropic SDK: Claude API with prompt caching
  • Ollama: Local embeddings and LLM
  • OpenAI SDK: Cloud embeddings and LLM
  • Gin: HTTP framework
  • MCP SDK: Model Context Protocol
  • Zerolog: Structured logging

See go.mod for full dependency list.

MCP Integration (Claude Code)

# Build bridge
make build-mcp-bridge

# Add to Claude Code
~/.local/bin/claude mcp add mesh-gateway \
  --transport stdio \
  -- /path/to/mesh/mesh-mcp-bridge \
     --agent-url=http://localhost:9000 \
     --gateway

# Query from Claude Code
@ask_my_backend How does authentication work?

GitHub Webhook Auto Re-indexing

  1. GitHub Settings → Webhooks → Add webhook

    • Payload URL: http://your-server:9000/webhooks/github
    • Content type: application/json
    • Events: Just the push event

  2. Ensure repo names match repos.yaml configuration

  3. Push code → automatic re-indexing

Security

  • Local embeddings: Ollama keeps data on-premise
  • Read-only mounts: MESH cannot modify code
  • API keys: Environment variables, not committed
  • Network: Use reverse proxy (nginx/Caddy) for production TLS

License

GNU General Public License v3.0 - see LICENSE

Documentation

MESH: Accurate code understanding for AI-assisted development.

About

Mesh is a semantic code search and Q&A gateway that provides LLM-powered answers about multiple codebases simultaneously.

Resources

Readme

License

GPL-3.0 license

Code of conduct

Code of conduct

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages