Architecture & Design

How Synapse's 3-layer context engine processes your codebase locally.

Synapse runs entirely on your machine. No data leaves your workstation. The entire context engine is a single .synap/synap.db SQLite file per repository.

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                      Your Repository                            │
│  Source Files (.py, .ts, .rs, .go, .java, +22 more languages)  │
└──────────────────────────┬──────────────────────────────────────┘
                           │  git diff-tree / inotify
                           ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Synapse Daemon                               │
│                                                                 │
│  ┌──────────────────┐     ┌──────────────────────────────────┐  │
│  │  Tree-sitter     │────▶│  SQLite WAL Database             │  │
│  │  AST Parser      │     │  (.synap/synap.db)               │  │
│  │  (25+ grammars)  │     │                                  │  │
│  └──────────────────┘     │  ● symbols (AST nodes + hashes)  │  │
│                           │  ● edges (caller → callee)        │  │
│  ┌──────────────────┐     │  ● files (path + git OID)        │  │
│  │  Git OID Tracker │────▶│  ● symbols_fts (FTS5 index)      │  │
│  │  (HEAD watcher)  │     │  ● wiki_queue (async jobs)       │  │
│  └──────────────────┘     │  ● checkpoints (L3 state)        │  │
│                           │  ● lessons (L3 memory)           │  │
│  ┌──────────────────┐     │  ● decisions (L3 log)            │  │
│  │  Wiki Worker     │────▶│  ● llm_calls (cost tracking)     │  │
│  │  (async LLM)     │     └──────────────────────────────────┘  │
│  └──────────────────┘                                           │
└──────────────────────────────────────────────────────────────────┘
                           │
              ┌────────────┼────────────┐
              ▼            ▼            ▼
    ┌──────────────┐  ┌─────────┐  ┌──────────┐
    │ FastMCP Stdio│  │  CLI    │  │ REST API │
    │  (IDE Agent) │  │ synap * │  │ Port 9876│
    └──────────────┘  └─────────┘  └──────────┘

The 3-Layer Context Model

L1 — Structural Code Graph

The lowest and fastest layer. Built by Tree-sitter parsing and stored entirely in SQLite.

Source File
    │
    ▼  Tree-sitter grammar (language-specific)
AST (Abstract Syntax Tree)
    │
    ▼  Node extractor (function_definition, class_definition, import)
Symbols Table
    ● symbol_id  = sha256(path + name + kind + start_line)
    ● name, kind, start_line, end_line, source_text
    ● module_key = dot-separated path (e.g. src.auth.service)
    │
    ▼  Import resolver (cross-file edge linking)
Edges Table
    ● caller_id → callee_id (depends_on relationship)
    │
    ▼  FTS5 virtual table
symbols_fts (keyword search, O(log n))

Query path: When an agent calls search, Synapse runs:

Deterministic intent classification (EXACT_SYMBOL, SEMANTIC, STRUCTURAL)
Recursive CTE graph traversal for call chains
FTS5 keyword match with BM25 ranking
LRU-cached vector dot-product similarity (if embed provider configured)
tiktoken context budgeting — returns only what fits the token limit

Latency: 9.2ms median (vs 7,214ms for synchronous LLM file-scan approaches)

L2 — Semantic Wiki

An asynchronous documentation layer that generates and maintains markdown summaries under .synap/wiki/.

Symbol Indexed / File Modified
    │
    ▼
wiki_queue (SQLite table: status=pending)
    │
    ▼  Background worker (polls every 5s)
LLM Provider
(Ollama / OpenAI / Anthropic / Gemini)
    │
    ▼
.synap/wiki/<filepath>.md
    ● Function signatures and summaries
    ● Architecture notes
    ● Usage examples

Wiki generation is non-blocking — it never delays CLI commands or MCP responses. If no LLM is configured (structural Mode A), placeholder files are written.

L3 — Behavioral Memory

Stateful memory that persists across agent sessions and prevents repeated mistakes.

Event                         Action
──────────────────────────────────────────────────
git revert detected     →  Lesson created (pending)
Agent calls log_decision →  Decision logged
Agent calls checkpoint  →  State snapshot saved
Human: synap lessons approve <id>  →  Lesson active
Lesson age > expiry_days  →  Auto-pruned (expired)

During every retrieval call, approved lessons are injected at the top of context as critical system constraints — forcing the agent to avoid previously-failed patterns.

Design Principles

Why SQLite, not a Vector Database?

SQLite WAL mode provides:

Sub-millisecond queries via FTS5 and indexed symbol lookups
Zero infrastructure — a single file, no Docker containers
ACID transactions safe for concurrent daemon + CLI access
Recursive CTEs for caller/callee graph traversal in one query

Vector databases excel at fuzzy semantic matching but fail at exact symbol lookup. Synapse uses both: SQLite for structural precision, local vector embeddings for semantic fuzzy search — combined in a single hybrid query.

Why Tree-sitter?

Tree-sitter generates concrete syntax trees, not token streams. This means:

class AuthService is always identified as a class_definition node, regardless of formatting
Import paths are resolved to actual file paths, not just strings
The same parser grammars are used by GitHub, NeoVim, and Helix

Why Local-First?

Your proprietary source code never leaves your machine. With Ollama + nomic-embed-text, the entire stack runs offline at zero cost.