Design Decisions

Design Decisions

Key architectural decisions and rationale.

---

Why SQLite?

Decision: Use embedded SQLite instead of client-server database

Rationale:

• Zero configuration
• No separate database server
• ACID guarantees
• FTS5 built-in
• Suitable for local-first tool

Why stdio MCP Transport?

Decision: Use stdio instead of HTTP for MCP

Rationale:

• Simpler integration with Claude Code
• No port management
• Process-level isolation
• Standard practice for MCP servers

Why Singleton Patterns?

Decision: Use singletons for Memory, Config, MessageBus

Rationale:

• Application-wide state consistency
• Prevent multiple database connections
• Simpler API for users

Why 11 Agent Types?

Decision: Provide specific agent types vs. generic agent

Rationale:

• Clear separation of concerns
• Specialized system prompts
• Easier to understand and use
• Better task routing

Why FTS5 + Optional Vector?

Decision: FTS5 by default, vector search optional

Rationale:

• FTS5 faster for keyword search
• No API costs for FTS5
• Vector search for semantic queries
• Hybrid approach gives best of both

---

Related:

• System Architecture
• Data Model