Skip to content

Architecture

Deployment modes

DepthFusion runs in one of four modes, controlled by DEPTHFUSION_MODE:

Mode Transport Embedding Typical use
local In-process stdio BM25 Developer laptop, single user
vps-cpu HTTP (/mcp + /sse) BM25 Self-hosted VPS, no GPU
vps-gpu HTTP + REST API Sentence-transformers Self-hosted VPS with GPU
mac-mlx HTTP + REST API MLX (Apple Silicon) macOS local inference

All modes expose the same 35 MCP tools. Feature flags determine which tools are active.

HTTP server transport

In vps-cpu, vps-gpu, and mac-mlx modes, the MCP server runs as a FastAPI app:

  • POST /mcp — Streamable HTTP (MCP 2025-03-26 spec)
  • GET /sse + POST /messages — legacy SSE transport (backward-compatible)
  • GET /query/* — REST API endpoints (requires DEPTHFUSION_REST_API=true)

The server is single-worker by design — the in-process session dict is not safe for uvicorn --workers N > 1. See the deployment docs for the Redis upgrade path if you need horizontal scale.

Retrieval pipeline

Every depthfusion_recall_relevant call runs a three-stage pipeline:

Query
  → BM25 candidate retrieval (always active)
  → Semantic rerank (when embedding backend configured)
  → CognitiveScorer (when cognitive_retrieval flag enabled)
  → Top-k results returned

The standard profile runs BM25 only. The research profile enables all three stages. Use mode="index" for a lightweight title-only lookup at ~10% token cost.

Event Graph Fabric

When DEPTHFUSION_GRAPH_ENABLED=true, DepthFusion maintains an entity graph across sessions:

  • Entities (files, functions, decisions, agents) are nodes
  • Relationships (modified, depends-on, supersedes, produced) are edges
  • depthfusion_graph_traverse walks the graph from any named entity
  • depthfusion_graph_status reports node/edge counts and coverage tier

The graph provides cross-session provenance: you can trace which agent made which decision and what downstream code was affected, across an entire project history.

Audit chain

All writes to the knowledge base are hash-chained: each entry stores SHA-256 of its predecessor. depthfusion-audit verify walks the chain and detects any deletion or tampering (gap in IDs or hash mismatch). See CLI Reference.