Core Concepts

Algo Workspaces

.md↗

Every algorithm gets its own uniquely-slugged directory on disk — a mission card, versioned strategy folders, two append-only logs, and per-algo data. Two sessions building the same strategy name never collide.

Where algos live

~/.local/share/finny/algos/          # Linux/macOS
%LOCALAPPDATA%\finny\algos\          # Windows

Each algo lives under a kebab-case slug plus an 8-char hex id — for example btc-mean-reversion-1h.a3f8c9e2. The hex id guarantees that identical names from different sessions never share a directory.

Directory layout

btc-mean-reversion-1h.a3f8c9e2/
├── mission.md            # Identity card — YAML frontmatter + prose rationale
├── prefs.md              # Per-algo sizing, risk, constraints
├── decisions.md          # Append-only HUMAN design log
├── memory.md             # Append-only AGENT summary (written on /compact)
├── CURRENT               # Single token pointing to active version (e.g. "v01")
├── data/
│   ├── stock/            # OHLCV parquet files (AAPL.parquet)
│   ├── crypto/           # BTC-USD.parquet
│   ├── sec/              # SEC filings (AAPL-10K-2024-01-15.md)
│   └── news/
│       ├── headlines/    # One file per day (2025-05-20.md)
│       └── body/         # Full articles, opened on demand
├── v01/
│   ├── strategy.py       # Executable strategy
│   ├── backtest.json     # Structured results (absent until first run)
│   └── reasoning.md      # Why this version exists
├── v02/
│   └── ...
└── .archive/             # Raw chat transcripts per day

The mission card

mission.md is the algo's identity. YAML frontmatter captures scope and status; the body holds the freeform thesis.

yaml
---
schema_version: 2
name: btc-mean-reversion-1h
status: research          # research | backtested | paper | live | retired
created: 2025-05-18
hypothesis: |
  BTC reverts to its 20-period hourly VWAP after >2σ deviations...
scope:
  asset_class: crypto     # equities | crypto | futures | fx | options | mixed
  universe: [BTC-USD]
  horizon: intraday       # intraday | days | weeks | months
exit_conditions: |
  - Time stop: close if open > 4 hours
  - Price stop: 1.5% adverse move
---

Versioning

Padded two-digit names
v01 through v99. Zero-padding keeps lexicographic order in sync with numeric order.
User-gated
Finny never silently creates a new version. You decide when a change is significant enough to bump.
Structural intent only
A new version marks a real design change — not parameter tuning. Sweeping rsi_period over a grid stays in the same version.
Three files per version
strategy.py, backtest.json, and reasoning.md. The CURRENT token at the workspace root points to the active version.

Two append-only logs

decisions.md — the human voice

You write here. Design decisions, things you tried, dead ends. Finny never edits this file.

memory.md — the agent voice

Written only on /compact. Structured so a fresh session can pick up cold without rereading the whole transcript.

markdown
## 2025-05-20 — compaction (v02)
- active version: v02
- since last compaction: Rewrote entry logic to Bollinger squeeze.
  Backtested v02 — Sharpe 1.8, max DD -6.2%.
- open threads:
  - Consider adding volume filter

The active algo

A global marker file at ~/.local/share/finny/active-algo tracks which workspace is currently selected. Resolution chain:

  • Explicit marker (set by /algo use).
  • Otherwise, walk up from the current working directory looking for a mission.md.
  • If neither resolves, no algo is active and most tools refuse to run.
→
Why workspaces matter
Per-algo isolation is what makes the research subagents, watchers, and per-algo data directories possible. News headlines pulled for one strategy don't leak into another; a v03 backtest can't overwrite v02 results.