Architecture Overview

Overview

Wilson’s architecture is based on Dexter, an autonomous financial research agent. The core patterns — agent loop, scratchpad, tool system, and skills — are adapted from financial research to personal finance bookkeeping.

Agent Loop

The core execution cycle:

User query
  → Build initial prompt (system prompt + conversation history)
  → Loop (max iterations):
      → Call LLM with system prompt + tools bound
      → If LLM returns text only → final answer, done
      → If LLM returns tool calls → execute them all
      → Add results to scratchpad
      → Check context threshold, clear oldest results if over limit
      → Build iteration prompt with tool results
      → Continue loop
  → If max iterations reached → return summary

Key Design Decisions

• Full tool results in context — No summarization of tool outputs. When the token threshold is exceeded, oldest results are cleared entirely. This preserves accuracy at the cost of context window.
• Event-driven UI — The agent yields typed events (thinking, tool_start, tool_end, tool_error, done) so the TUI can render real-time progress.
• No streaming — Each LLM call is a complete invocation, not streamed. This simplifies tool call handling.

Scratchpad

The scratchpad is an append-only log that tracks all tool results within a query session.

• Persisted for debugging
• Tool call counting with soft limits (warns at 3 calls per tool, never blocks)
• Similarity detection to catch near-duplicate tool calls
• In-memory context clearing when the token threshold is exceeded

System Prompt

The system prompt is assembled dynamically from:

1. SOUL.md — Wilson’s personality, values, and communication style
2. Tool descriptions — Rich descriptions of all available tools
3. Budget context — Current category budgets and spending data
4. Skill descriptions — Loaded from frontmatter of all discovered skills

LLM Facade

A central callLlm() function with retry logic routes to provider-specific adapters. All 9 providers are normalized to a common internal message format.

Provider resolution is prefix-based:

• gpt- → OpenAI adapter
• claude- → Anthropic adapter
• gemini- → Google adapter
• ollama: → Ollama adapter
• Others → OpenAI-compatible adapter

Data Flow

User Input → Agent Loop → Tool Calls → SQLite DB
                ↕                         ↕
            LLM Provider           Transaction Data
                ↕
           Scratchpad (context management)

All financial data flows through local SQLite. The only external calls are to the configured LLM provider for AI inference.