SynapsesOS
Internals

Brain Pipeline Internals

The brain pipeline enriches the raw code graph with LLM-generated intelligence. It operates in tiers, each building on the previous one.

Tier 0: Ingestor

The ingestor generates lightweight summaries for code entities:

  • Receives a structured JSON prompt describing a node (function signature, body snippet, relationships)
  • Produces a 1-sentence summary and a set of tags
  • Results are stored in the summaries table in brain.sqlite

This is the cheapest tier — it runs on small models and processes high volumes.

Pruner

The pruner is a utility stage that strips boilerplate from web content (documentation pages, README fetches) using an LLM pass. This produces cleaner input for downstream tiers.

Tier 1: Guardian

The guardian enforces architectural rules:

  • Takes a rule violation detection (e.g., circular dependency, forbidden import) along with the surrounding code context
  • Produces an explanation of the violation and a suggested fix
  • Results are cached in the violations_cache table to avoid redundant LLM calls

The guardian includes a circuit breaker on Ollama pressure — if the local LLM server is overloaded, the guardian backs off and queues violations for later processing.

Tier 2: Enricher

The enricher runs a two-pass process:

Deterministic pass (no LLM needed):

  • SDLC phase detection via pattern matching (e.g., files in test/ are in the testing phase)
  • Complexity scoring: (fanIn + fanOut) * (1 + fanOut / 10) — a heuristic that weights nodes with high connectivity

Optional LLM pass:

  • Generates a 2-sentence architectural insight and flags concerns
  • Uses domain-specific prompt templates (different prompts for API handlers vs. data models vs. utility functions)

Context Builder

The context builder assembles the final Context Packet — a structured 7-section document returned to agents:

  1. Semantic focus — What the query is about
  2. Architectural insight — How the target fits into the system
  3. Active constraints — Rules and invariants that apply
  4. Team status — Current tasks and agent coordination state
  5. Quality gate — Test coverage, lint status, known issues
  6. Learned patterns — Historical patterns from past interactions
  7. Phase guidance — SDLC-aware suggestions

The PacketQuality heuristic scores the assembled packet from 0 to 1 based on completeness and freshness of each section.

Tier 3: Orchestrator

The orchestrator coordinates multi-agent work:

  • Receives a CoordinateRequest from an agent declaring what it intends to work on
  • Checks existing work claims to detect conflicts
  • Suggests a non-conflicting scope if the requested area overlaps with another agent’s active work

Supporting Infrastructure

ModelManager

Preloads LLM models based on the configured intelligence_mode. Ensures the right models are warm in Ollama before the pipeline needs them.

SystemPulse

Monitors system health:

  • RAM usage and availability
  • Ollama server health and response latency
  • Used by the scheduler and circuit breaker to make backpressure decisions

Scheduler

Manages the enrichment work queue:

  • P0 — Blocking (guardian violations on actively edited files)
  • P1 — Important (enrichment for recently queried nodes)
  • P2 — Background (batch enrichment of the full graph)

The scheduler drains the queue respecting priority order and system health — it pauses P2 work when RAM or Ollama pressure is high.