Pythia

Local Code Search & Architectural Memory for AI Agents

Pythia is an MCP server that gives AI coding agents deep, persistent understanding of any codebase. It runs entirely on your machine — no API keys, no cloud dependencies, no data leaves your laptop.

Human? Skip to the human-readable section. Everything below is written for your AI agent.

---

Agent Install Guide

You are an AI agent. A human has asked you to install Pythia. This section is written for you. Everything is non-interactive — no user input required at any point. Follow these steps exactly.

Windows Note

If you are running on Windows (PowerShell, cmd, Git Bash), Pythia requires WSL2. The install script is bash-only and Pythia uses Unix domain sockets.

1. Check if WSL is available: wsl --status
2. If not installed, tell the user to open an admin PowerShell and run wsl --install, then restart their machine
3. Run all Pythia commands inside WSL: wsl bash -c 'curl -fsSL https://raw.githubusercontent.com/michaeljboscia/pythia/main/install.sh | bash'
4. After install, run pythia init and pythia mcp install inside WSL as well

Step 1: Run the Install Script

The install script handles all prerequisites automatically — Node.js, build tools, npm permissions, everything:

curl -fsSL https://raw.githubusercontent.com/michaeljboscia/pythia/main/install.sh | bash

Success signal: Output ends with === Pythia installed successfully === Failure signal: Any line starting with [!] — read the message, it tells you exactly what's wrong and how to fix it.

Step 2: Verify the Binary

pythia --version

Expected: A version number (e.g., 3.0.1).

If command not found, the npm global bin directory may not be in PATH. Fix it:

export PATH="$HOME/.npm-global/bin:$PATH"
pythia --version

Step 3: Index the User's Project

cd /path/to/user/project
pythia init

First run downloads ~3 GB of GGUF models. This takes 2-10 minutes depending on connection speed. Subsequent runs on other projects reuse the cached models.

Success signal: Output shows an indexing summary with file count and chunk count.

Step 4: Register as MCP Server

pythia mcp install

This writes Pythia's MCP configuration to the agent's config file. After this step, tell the user they need to restart their AI agent session. Pythia's tools become available on the next session start.

Step 5: Confirm MCP Tools Are Available

After the user restarts their session, these MCP tools should be available:

Tool	What It Does
lcs_investigate	Semantic, structural, or reasoning-based code search
pythia_force_index	Re-index specific files or the entire workspace
pythia_corpus_health	Database stats — file count, chunk count, graph edges, model info
spawn_oracle	Start a persistent Gemini session loaded with architectural docs
ask_oracle	Query the Oracle — responses include numbered source citations
oracle_commit_decision	Write a formal Architectural Decision Record (MADR)
oracle_decommission	Archive an Oracle session safely (requires TOTP confirmation)

Agent Troubleshooting

If something fails, use this table to diagnose. Every row is a concrete symptom → fix pair:

Symptom	Cause	Fix
command not found: pythia	npm global bin not in PATH	export PATH="$HOME/.npm-global/bin:$PATH" then retry
npm ERR! node-gyp rebuild	Missing C++ toolchain	macOS: xcode-select --install / Ubuntu: sudo apt install build-essential python3
EACCES permission error	npm global prefix owned by root	npm config set prefix "$HOME/.npm-global" and update PATH
Model download hangs or fails	Insufficient disk or network issue	Need ~5 GB free disk. Check curl -fsSL https://registry.npmjs.org/ works
pythia init times out on large repo	Standard tier indexes deeply	Try pythia init --tier light for faster indexing (~2 min vs ~15 min, lower coverage)
pythia mcp install — no config written	Unknown MCP client	Manually add Pythia to the agent's MCP config (see Manual MCP Configuration below)

Manual MCP Configuration

If pythia mcp install doesn't detect your MCP client, add this to your MCP server configuration manually:

{
  "pythia": {
    "command": "pythia",
    "args": ["start"]
  }
}

For Claude Code, this goes in ~/.claude/mcp_config.json. For Gemini CLI, this goes in ~/.gemini/settings.json under mcpServers.

What the Install Script Does (For Agent Context)

The install script is safe to run on any macOS or Linux machine. It performs these checks in order:

1. curl — installs if missing (apt/dnf/apk)
2. Disk space — verifies ≥5 GB free, exits with clear error if not
3. Network — verifies npm registry is reachable, suggests proxy config if not
4. Node.js 22+ — installs via Homebrew (macOS) or NodeSource (Linux) if missing or outdated
5. Build tools — installs Xcode CLI tools (macOS, non-interactive) or build-essential (Linux) if missing
6. npm permissions — redirects global prefix to ~/.npm-global if system-owned (avoids EACCES)
7. Pythia — npm install -g pythia-lcs
8. Verification — confirms pythia command exists in PATH

The script does NOT require user interaction at any point. It does NOT modify system files outside of standard package manager operations. It uses sudo only when necessary and only if available (works without sudo in Docker/root contexts).

---

For Humans

Everything above is written for your AI agent. Here's the context for you.

What Pythia Does

AI agents struggle with large codebases because they can't see everything at once. Pythia gives them a local search engine that understands your code:

• Hybrid Search: Combines vector search, full-text search, and Reciprocal Rank Fusion — all reranked by a cross-encoder for precision
• Semantic Chunking: 16 Tree-sitter language grammars parse your code structurally, so search results align with function and class boundaries
• Architectural Memory: Your agent's reasoning gets persisted alongside the code, building institutional knowledge over time
• Zero Cost: Three GGUF models run locally on your machine. No API keys, no cloud, no data exfiltration

How to Install

Tell your AI agent:

"Install Pythia from github.com/michaeljboscia/pythia"

Your agent will read this README and handle everything. No manual steps required.

Or install manually:

curl -fsSL https://raw.githubusercontent.com/michaeljboscia/pythia/main/install.sh | bash
cd /your/project
pythia init          # downloads models (~3 GB first time), indexes your code
pythia start         # start the MCP server

Already have Node.js 22+ and a C++ compiler? Skip the script: npm install -g pythia-lcs

System Requirements

Requirement	Minimum	Notes
Node.js	v22+	Install script handles this
RAM	8 GB	Runs 3 GGUF models simultaneously
Storage	~5 GB	3 GB models + database (models shared across projects)
OS	macOS or Linux	Windows via WSL2

Embedding Models

Tier	Model	Size	Context	File Coverage	Command
Standard	gte-Qwen2-1.5B-instruct Q4_K_M	1.1 GB	32K	100%	pythia init
Light	nomic-embed-text-v1.5 Q4	80 MB	8K	~65%	pythia init --tier light

We benchmarked 8 models across real codebases. Context window proved more important than model quality — the #1 public benchmark model failed to index 73% of files due to a 2K context limit.

Thought Capture API

Pythia exposes a local HTTP API for agents to persist their reasoning. Thoughts become searchable alongside your code.

• POST /v1/thoughts — ingest architectural reasoning
• GET /v1/health — check server readiness

Configuration

Default config at ~/.pythia/config.json:

{
  "embeddings": {
    "mode": "local",
    "tier": "standard"
  }
}

For teams centralizing embedding generation (Ollama, Vertex AI, any OpenAI-compatible endpoint):

{
  "embeddings": {
    "mode": "openai_compatible",
    "base_url": "http://your-gpu-server:11434/v1",
    "api_key": "ollama",
    "model": "nomic-embed-text"
  }
}

Architecture

<your-workspace>/
└── .pythia/
    ├── lcs.db              # SQLite: chunks, embeddings, FTS, graph edges, thoughts
    └── pythia.sock         # Unix domain socket for Thought Capture API

~/.pythia/
├── config.json             # Global configuration
└── models/                 # Cached GGUF models (~3 GB, shared across all projects)
    ├── gte-qwen2-1.5b-Q4_K_M.gguf               (Embedder)
    ├── bge-reranker-v2-m3-Q8_0.gguf             (Cross-encoder reranker)
    └── qwen2.5-coder-1.5b-instruct-q4_k_m.gguf  (Chunk summarizer)

Benchmark Highlights

1. Context limits matter most: 32K context achieves 100% file coverage vs 27% for 2K-limit models
2. Chunking normalizes quality: Tree-sitter AST chunking compresses quality spread to 5-9 points
3. Quantization is practically free: Q4, Q8, and f16 variations within margin of noise
4. Reranking is essential: Cross-encoder reranking altered final ordering on 90% of queries

Full data and methodology: docs/benchmarks/BENCHMARK-RESULTS.md

---

Licensed under FSL-1.1-ALv2 (Functional Source License). Converts to Apache 2.0 after two years.