The Thinking Brain

The brain is Synapses’ optional local intelligence layer. It runs via Ollama and adds reasoning capabilities on top of the code graph — from smart context assembly to architectural decision tracking and multi-agent orchestration.

Prerequisites

1. Install Ollama — ollama.com
2. Pull a model — the brain works with any Ollama model, but llama3 or codellama are recommended:

   ollama pull llama3

3. Enable in synapses.json:

   {
     "brain": {
       "enabled": true,
       "model": "llama3",
       "url": "http://localhost:11434"
     }
   }

Intelligence Tiers

The brain operates in tiers of increasing capability. Higher tiers use more compute but provide deeper reasoning.

Tier 0: Graph Only (No Brain)

No Ollama required. Synapses uses BFS graph traversal with intent-based edge weighting. This is what you get when the brain is disabled.

• Fast, deterministic
• Good for small-to-medium projects
• No semantic understanding

Tier 1: Smart Context Assembly

The brain reviews the raw graph slice and reranks entities by relevance to the task. It removes noise and highlights what matters.

{
  "tool": "get_context",
  "arguments": {
    "mode": "intent",
    "task": "Fix the race condition in the cache invalidation logic",
    "intent": "debug",
    "brain_tier": 1
  }
}

• Prunes irrelevant entities from the graph slice
• Adds brief explanations of why each entity is relevant
• Moderate latency (1-3 seconds depending on model)

Tier 2: Architectural Reasoning

The brain analyzes the context packet and provides architectural insights: potential issues, design pattern suggestions, and connections that the graph alone would not surface.

{
  "tool": "get_context",
  "arguments": {
    "mode": "intent",
    "task": "Redesign the notification system to support multiple channels",
    "intent": "plan",
    "brain_tier": 2
  }
}

• Everything from Tier 1
• Architectural analysis and suggestions
• ADR (Architectural Decision Record) drafting
• Higher latency (3-10 seconds)

Tier 3: Orchestrator

Used for multi-agent scenarios. The brain coordinates work claims, resolves conflicts, and provides global awareness across agents.

• Everything from Tier 2
• Multi-agent conflict resolution
• Global task prioritization
• Highest latency

Context Packets

When the brain is active, get_context(mode="intent") returns enhanced context packets:

Context Packet (Tier 1):
├── Code entities (reranked by relevance)
├── Relevance explanations
├── Relationship graph (pruned)
├── Applicable rules
└── Related episodes

Context Packet (Tier 2):
├── Everything from Tier 1
├── Architectural analysis
├── Suggested ADRs
├── Risk assessment
└── SDLC phase recommendations

SDLC Phase Awareness

The brain adjusts its output based on the current SDLC phase. See SDLC Awareness for details on setting phases.

ADR Generation

At Tier 2+, the brain can generate Architectural Decision Records:

{
  "tool": "rules",
  "arguments": {
    "action": "upsert_adr",
    "title": "Use connection pooling for webhook delivery",
    "status": "accepted",
    "context": "Webhook delivery latency is too high with per-request connections",
    "decision": "Implement HTTP connection pooling with a max pool size of 100",
    "consequences": "Reduced latency, increased memory usage, need connection health checks"
  }
}

The brain suggests ADRs when it detects significant architectural decisions in the context. You can accept, modify, or dismiss them.

When to Use Brain vs Skip It

Use the brain when:

• Working on a large codebase (500+ files) where graph noise is high
• Planning architectural changes that span multiple packages
• Reviewing PRs and want automated architectural analysis
• Coordinating multiple agents

Skip the brain when:

• Working on small projects where graph traversal is sufficient
• Making simple, localized changes
• Latency is critical (brain adds 1-10 seconds per call)
• Ollama is not available in your environment

Configuration Options

{
  "brain": {
    "enabled": true,
    "model": "llama3",
    "url": "http://localhost:11434",
    "default_tier": 1,
    "max_tier": 2,
    "timeout_seconds": 30
  }
}

• default_tier — tier used when not specified in the tool call
• max_tier — maximum tier allowed (prevents accidental Tier 3 usage)
• timeout_seconds — how long to wait for Ollama before falling back to graph-only