◆Franklin/Docs

Architecture

System overview, key modules, token pipeline, and error recovery.

System Overview

Franklin is structured as a pipeline. Every user message flows through these stages:

text
CLI Entry → Agent Loop → LLM Client → Tool Dispatch → x402 Payment
  1. CLI Entry— parses flags, loads config, initializes the session
  2. Agent Loop— orchestrates the think-act-observe cycle until the task is complete
  3. LLM Client— routes requests to the optimal model via the Smart Router
  4. Tool Dispatch— executes tool calls (file ops, shell, search, MCP) and returns results
  5. x402 Payment— settles micropayments per API call using USDC on Base or Solana

Key Modules

text
agent/       Agent loop, planning, and orchestration
tools/       Built-in tool implementations (file, shell, search, browser)
router/      Smart Router — model selection, cost optimization, fallback chains
wallet/      Wallet management, x402 payment signing
session/     Session persistence, crash recovery, replay
brain/        Long-term memory storage and retrieval
learnings/   Self-evolution rules (learnings.jsonl)

Token Pipeline

Franklin aggressively compacts context to stay within model limits and minimize cost. The pipeline runs in order:

  1. optimize— strips redundant whitespace, collapses repeated tool outputs
  2. reduce— summarizes older conversation turns into compact representations
  3. microCompact— applies token-level compression (abbreviations, deduplication)
  4. autoCompact— triggered automatically when context approaches the model's limit

Automatic compaction

You never need to manually compact. When the context window fills, Franklin summarizes the conversation and continues seamlessly. The /compact slash command forces immediate compaction if needed.

Error Recovery

Franklin handles failures at every layer with specific strategies:

  • Context overflow— triggers autoCompact to summarize and free tokens
  • Transient errors— exponential backoff with jitter, up to 3 retries
  • Rate limits— falls back to the next model in the Smart Router's ranked list
  • Payment failure— tries alternate payment chain, then falls back to free NVIDIA models

Design Principles

  • Tool-agnostic core— the agent loop is decoupled from tool implementations. Any tool that satisfies the CapabilityHandler interface can be plugged in.
  • Plugin-first extensibility— new capabilities are added as plugins, not core changes. The plugin discovery system loads dev, user, and bundled plugins automatically.
  • Crash-safe sessions— sessions are persisted to disk after every turn. If Franklin crashes, restart and your conversation resumes from the last completed turn.