HELIOS· field notes
FN·1FN·2
docs / field notes / 2
field note · 2 · getting started

Your First Vault

The whole system in one working session — then the shortest honest path from an empty vault to an agent that reads, writes, and cites. Fifteen minutes, no hand-waving.

HELIOS FIELD NOTES·~6 min·watch the terminal
a real session, replayed

Watch an agent work a vault

This is the exact tool sequence from the staging smoke test — the one the journal attributed line by line.

agent ⇄ helios /mcp
orient
Read the vault's AGENTS.md resource — the contract for this vault.
queue
vault_new_sources: what's waiting to be compiled?
compile
Read the raw source, write a cited page — it lands as a seedling.
verify
vault_query answers from the page just written — with evidence.
attributed
The journal names the agent. Later, a human promotes — named too.
the human's promotion happens in the Helios console — the agent can only propose
01 · the synopsis

What this actually is

Helios began as a working single-machine system: markdown vaults on disk, an agent contract in AGENTS.md, a ~280-line shell script doing deterministic retrieval, and a local read-only console called Flux that gave every vault an operating-system view. It worked — the question was whether it could become a product without losing what made it work.

the four ideas (unchanged)

Compile sources into a wiki once instead of RAG-ing raw text forever · hold every page to the tiny OKF contract · keep the human PARA layer separate from the agent wiki · retrieve with deterministic code, zero model calls. Field note 1 is the tour.

what hosting added

One physically isolated database per vault (a Durable Object), real auth with agents as named principals, an MCP server so your agent operates the vault, share links, quotas, backups, and export that round-trips your markdown byte-for-byte.

what the console became

The same OS-per-vault console, hosted: home/desktop, search/spotlight, graph/file-manager, journal/system-log, pulse/activity-monitor — still read-only, still showing the truth rather than editing it.

what it refuses to be

Not a RAG search box over your raw files. Not auto-promoted "AI knowledge". Not a silo — the export button and the append-only journal are the trust features, not the fine print.

02 · where helios comes into play

The kernel multiplies

On one machine, Flux served two vaults for one person. In Helios, the same shape multiplies: the kernel (routing, auth, search, alarms, billing) is shared across everyone, while every vault keeps its own database, its own vector namespace, its own R2 prefix, its own privacy rules, its own journal. Your agent connects with a key scoped to exactly one vault; a colleague's share link reads exactly one vault; deleting a vault leaves exactly nothing.

The practical consequence: you can give an agent real write access to your knowledge base without giving it your knowledge base. The blast radius of any mistake is one seedling in one vault, waiting for your review.

03 · begin

The fifteen-minute path

  1. Sign up at /app — your personal org is provisioned on first use.
  2. Create a vault from the personal template (agents write wiki-only) or engineering (agents also keep project records).
  3. Import your Obsidian vault or markdown folder — frontmatter preserved verbatim, PARA folders detected, nothing rejected (odd pages get flagged for you instead).
  4. Mint an agent key in Settings (shown once), and point any MCP client at /mcp with it.
  5. Paste the contract prompt into your agent — or better, let it read the vault's own AGENTS.md resource — then drop a first raw source into the queue and call vault_ingest_source with its rawId. Text, HTML, and PDF compile into cited wiki pages plus 2–3 inbox seedlings.
  6. Review the seedlings on the home screen. Promote what earned it. You're running.
the detailed version

Chapter 04 walks all eight steps interactively — who acts, what to click, what to call — and ends with the copy-paste prompt that teaches any agent the whole system, including how the console behaves as an OS per vault.

That's the pitch and the path. The system was built so that the interesting part of your day is reading compiled knowledge and deciding what to trust — not feeding a retrieval pipeline and hoping. Go plant something.