◆Franklin/Docs

Configuration

The ~/.blockrun/ directory structure and key configuration files.

Directory Structure

All of Franklin's persistent state lives in ~/.blockrun/:

text
~/.blockrun/
├── payment-chain        # Active payment chain ("base" or "solana")
├── wallets/             # Encrypted wallet keystores
│   ├── base.json
│   └── solana.json
├── sessions/            # Persisted conversation sessions
│   ├── <session-id>.json
│   └── ...
├── brain/               # Long-term memory store
│   ├── index.json
│   └── embeddings/
├── learnings.jsonl      # Self-evolution rules (one JSON object per line)
├── runcode-stats.json   # Aggregated usage and cost statistics
├── mcp.json             # Global MCP server configuration
└── config.json          # User preferences

Key Files

payment-chain

A plain text file containing the active payment chain. Set automatically by franklin setup:

bash
cat ~/.blockrun/payment-chain
# Output: base

sessions/

Each session is a JSON file containing the full conversation history, tool call results, and metadata. Sessions are crash-safe — they are written after every completed turn.

Session recovery

If Franklin crashes mid-session, restart it in the same directory. It automatically detects and resumes the last active session.

runcode-stats.json

Aggregated statistics including total tokens used, cost per model, and session counts. Used by franklin insights and the web panel.

json
{
  "totalTokens": 1284503,
  "totalCostUsd": 0.42,
  "modelBreakdown": {
    "claude-sonnet-4-20250514": { "calls": 89, "tokens": 502300, "costUsd": 0.31 },
    "llama-3.1-8b": { "calls": 214, "tokens": 782203, "costUsd": 0.00 }
  },
  "sessionCount": 23
}

learnings.jsonl

The self-evolution memory. Each line is a JSON object recording a lesson Franklin has learned from your feedback and corrections:

json
{"rule": "Always use pnpm in this project, not npm", "context": "package-manager", "created": "2025-01-15T10:30:00Z"}
{"rule": "Run tests before committing", "context": "workflow", "created": "2025-01-16T14:22:00Z"}

brain/

Long-term memory storage. Franklin stores project-specific knowledge here — architecture decisions, API patterns, debugging history — and retrieves relevant context automatically at the start of each session.

mcp.json

Global MCP server configuration. Servers defined here are available in every project. See the MCP Integration guide for the full format.

config.json

User preferences. Can also be set via franklin config:

json
{
  "defaultModel": "auto",
  "trustMode": false,
  "theme": "auto",
  "compactThreshold": 0.8
}