# Algo Workspaces

> 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.

Source: https://finnyai.tech/docs/workspaces

## 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**: Scout 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. Scout 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.