How saahilpal/synapse works
Synap is a local, Git-aware structural context engine for coding agents. Its main workflow watches repository changes, indexes source structure into SQLite, and serves token-bounded context through MCP retrieval. Separate capabilities include generated wiki pages, branch-persistent checkpoints and lessons, and a diagnostic API. The graph follows the README’s runtime design and relationships visible in excerpts or the SOURCE INDEX; unsampled implementation details are represented only where documented, and uncertain connections are omitted.
Main entry points: engine.py Runtime and Indexer · sqlite.py SQLite Knowledge Store · daemon.py Runtime Daemon · main.py CLI Commands
Components 21
Runtime and Git
- CLI Commands
src/synap_git/cli/main.py - Runtime Daemon
src/synap_git/indexer/daemon.py - Git State Watcher
src/synap_git/git/state.py - Diagnostic API
src/synap_git/api/app.py
Indexing and Knowledge
- Runtime and Indexer
src/synap_git/indexer/engine.py - File Scanner
src/synap_git/indexer/scanner.py - Structural Parser
src/synap_git/parser/registry.py - SQLite Knowledge Store
src/synap_git/storage/sqlite.py - Semantic Wiki
src/synap_git/indexer/wiki.py
Agent Context
- Hybrid Retrieval
src/synap_git/retrieval/engine.py - Behavioral Memory
src/synap_git/retrieval/memory.py - MCP Tool Server
src/synap_git/mcp/server.py - Checkpoint Commands
src/synap_git/cli/checkpoint.py - Lesson Commands
src/synap_git/cli/lessons.py
Providers and Diagnostics
- Configuration
src/synap_git/config.py - Provider Factory
src/synap_git/provider/factory.py - Provider Interface
src/synap_git/provider/base.py - OpenAI Provider
src/synap_git/provider/openai.py - Structured Logging
src/synap_git/diagnostics/logger.py
Other components
- Developer
- AI Coding Agent
Connections 27
- Developer → CLI Commands: runs commands
- CLI Commands → Runtime Daemon: invokes
src/synap_git/cli/main.py - Runtime Daemon → Git State Watcher: starts watcher
- Runtime Daemon → Runtime and Indexer: coordinates indexing
src/synap_git/indexer/daemon.py - Runtime Daemon → Diagnostic API: hosts server
src/synap_git/indexer/daemon.py - Git State Watcher → Runtime and Indexer: detects commit changes
- Runtime and Indexer → File Scanner: scans files
src/synap_git/indexer/engine.py - Runtime and Indexer → Structural Parser: parses source
src/synap_git/indexer/engine.py - Runtime and Indexer → SQLite Knowledge Store: stores index
src/synap_git/indexer/engine.py - Structural Parser → File Scanner: uses language mapping
src/synap_git/parser/registry.py - Runtime and Indexer → Semantic Wiki: generates documentation
src/synap_git/indexer/engine.py - Semantic Wiki → SQLite Knowledge Store: uses wiki queue
src/synap_git/indexer/wiki.py - AI Coding Agent → MCP Tool Server: calls tools
- MCP Tool Server → Runtime and Indexer: delegates runtime calls
src/synap_git/mcp/server.py - Runtime and Indexer → Hybrid Retrieval: runs queries
src/synap_git/indexer/engine.py - Hybrid Retrieval → SQLite Knowledge Store: searches graph and symbols
src/synap_git/retrieval/engine.py - MCP Tool Server → SQLite Knowledge Store: records agent memory
src/synap_git/mcp/server.py - Checkpoint Commands → SQLite Knowledge Store: manages checkpoints
- Lesson Commands → Runtime and Indexer: uses runtime
src/synap_git/cli/lessons.py - Lesson Commands → SQLite Knowledge Store: manages lessons
- Diagnostic API → Runtime and Indexer: reads status and traces
src/synap_git/api/app.py - CLI Commands → Configuration: configures runtime
src/synap_git/cli/main.py - Runtime and Indexer → Configuration: initializes from
src/synap_git/indexer/engine.py - Runtime and Indexer → Provider Factory: creates providers
src/synap_git/indexer/engine.py - Provider Factory → Provider Interface: wraps providers
src/synap_git/provider/factory.py - Provider Factory → OpenAI Provider: selects provider
src/synap_git/provider/factory.py - Runtime and Indexer → Structured Logging: records operations
src/synap_git/indexer/engine.py