Folio

A markdown vault as memory. A local AI agent as your strategy partner.

Part of Aion Lumen.

---

A vault as memory.
A campaign as structure.
A hearth at the center.

Why Folio exists

Cloud AI forgets you at the end of every session. You start over. Every time. Folio is the generator that keeps the heat on: a local markdown vault holds your full context, a locally-running AI agent reads it directly, and nothing leaves your machine. Markdown as source of truth — no lock-in, no subscription. The full story is at aion-lumen.ch/folio.

Status

Status: v0.1.0 public preview
License: AGPL-3.0
Platforms: Linux / macOS / WSL2

Stack

• SvelteKit 2 + Svelte 5 (Runes), Tailwind CSS 4
• SQLite (local, file-based) via better-sqlite3 — no DB server
• Local LLMs via Hermes Agent (Nous Research)
• Cytoscape.js for graph visualisations

Quick Start

Prerequisites: Node.js 20+. The demo vault runs fully self-contained — no Hermes needed. A running Hermes Agent is only required for the AI chat / full operation (see below).

git clone https://github.com/aion-lumen/folio.git
cd folio
npm install
npm run build
npm run preview

Open http://localhost:4173 and follow the Setup Wizard. On first launch you can connect an existing vault, start from a demo vault, or create one from scratch.

Environment — create .env in the project root:

VAULT_PATH=/path/to/your/vault
HERMES_API_URL=http://localhost:8642
HERMES_API_KEY=your-key-here

For vault layout and mail integration, see docs/VAULT.md and docs/MAIL.md.

Demo (mock data)

Bundled demo of the full pipeline against isolated *-demo.db files on port 5174 — your real ~/.folio is untouched. Prerequisites: seed the demo state from multi-agent-lab first (see Demo (full stack) below).

bash scripts/demo-server.sh

Then open http://localhost:5174/pipeline (Pipeline page) or http://localhost:5174/council (Council list).

Demo (full stack)

Full pipeline demo (folio UI + multi-agent worker simulation) — no IMAP, no LLM, no real data. Reproducible end-to-end against a fictional Alex + Maya household in the Algarve.

1. Clone both repos side-by-side:

   git clone https://github.com/aion-lumen/folio.git
   git clone https://github.com/aion-lumen/multi-agent-lab.git

2. Seed the demo DBs in multi-agent-lab. This populates the isolated *-demo.db files (folio + council + feedback) with the demo content — Council is NOT required, an empty ~/.council/ works:

   cd multi-agent-lab
   python3 -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   cp config/user_context.example.yaml config/user_context.yaml
   cp config/immo_whitelist.example.yaml config/immo_whitelist.yaml
   cp config/regelwerk.example.yaml config/regelwerk.yaml
   make demo

3. Start the folio demo server (isolated *-demo.db, port 5174):

   cd ../folio
   npm install
   bash scripts/demo-server.sh

4. Open http://localhost:5174/pipeline — Pipeline page should render with seeded worker runs, validator opinions, and a populated Hauskauf kanban.

See docs/quickstart.md for the demo's environment variables and what each *-demo.db file holds.

Screenshots

Captured against the bundled demo state (fictional Alex + Maya household in Algarve, no real data). Reproducible end-to-end — see multi-agent quickstart for the make demo workflow.

_{Heute dashboard — four cards as entry points (vault, mail-queue, pipeline, hermes chat).}

_{Council — properties ranked by three lens personas (Borda-aggregated), cluster-aware (cross-portal same-address detection).}

_{Pipeline overview — data-flow diagram (IMAP → Worker → Validator → Auto-Übernahme → Council-Ingest).}

_{Validator mid-run — three blind LLM voices (gemma · qwen · qwen-thinking), 13 / 15 Stimmen geprüft. Delphi-Prinzip: each voice classifies independently.}

_{Council-Lens mid-run — three personas evaluate property candidates (Borda voting → consolidated Top-10).}

_{Verlauf detail — per-run Lauf-Spur with Block-Gründe breakdown and a sample of imported mails.}

_{Hauskauf campaign — kanban over the candidates that passed the 4/4 consensus (heuristik + 3 LLM voices).}

_{Mail queue — domain × actionability tags, sender ranking, search + filters.}

Mail pipeline (reference architecture)

Folio orchestrates the Python pipeline in multi-agent-lab:

flowchart LR
  folio[folio manager.ts]
  worker[production_worker.py]
  validator[validator_batch.py]
  feedback[(feedback.db)]
  foliodb[(folio.db)]
  folio -->|spawn silent| worker
  worker --> feedback
  folio -->|mail_ids handoff| validator
  validator --> foliodb

Loading

Set AION_LUMEN_PATH if the repo is not at ~/Projects/aion-lumen/multi-agent. See multi-agent docs/quickstart.md for an offline demo.

What works today

• Strategic view — campaign banner, all five acts, active chapter
• Tactical view — kanban with drag-and-drop, gantt, objective selection
• Objective detail panel — status, deadline, progress note, history
• Hermes chat — agent reads and edits vault files via tool calls
• Vault format — plain markdown + YAML frontmatter, git-friendly
• Setup wizard, demo vault, model switcher

What's coming

• v0.2 — Voice input (STT), interview-style setup wizard, mobile PWA, approval UI for risky tool calls
• v0.3 — Frostpunk view: generator metaphor, resource decay, harder visual atmosphere
• v1.0 — Multi-user, NAS deployment, public vault templates

See docs/ROADMAP.md for the full roadmap.

Contributing

Built by one person. Slow on purpose. Issues and pull requests welcome.

This is a solo project — contemplative pace, not startup velocity. If something is broken or missing, open an issue.

Acknowledgements

• Andrej Karpathy for thinking out loud about local knowledge bases
• Nous Research for Hermes Agent
• nesquena for Hermes Web UI
• 11 bit studios for Frostpunk 2 (mental model)

License

AGPL-3.0 — see LICENSE.

Design assets (Aion Lumen mark, color system) are CC BY 4.0.

---

Folio provides the engine. The course is yours.

— afm.