Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Pilot Onboarding

This is the quick end-to-end checklist for running a pilot: stand the company brain up once, onboard each employee, then keep the daily loop turning. Each step links to the guide that covers it in depth.

0. One-time company setup

Do this once, as the operator:
brain init /srv/brain/master --company "Acme Co"
# edit /srv/brain/master/_meta/org.yaml    — add people, roles, teams
# edit /srv/brain/master/_meta/spaces.yaml — adjust visibility if needed
brain compile --master /srv/brain/master --out /srv/brain/compiled
brain doctor  --master /srv/brain/master --out /srv/brain/compiled
# run after setup and from cron; nonzero exit = integrity error
Re-run brain compile on every master change, from cron (flock /var/lock/brain-cycle.lock brain cycle … does it as part of the cycle). The full walkthrough is in Getting started.

1. Per-employee setup

Running agents server-side instead of on employee devices? Follow the two-box reference deployment — steps 3–4 below happen inside each person's container at first boot, and the employee's entire setup is a chat pairing code. The architecture at a glance is in Where the brain lives.
  1. Grant sync access to their slice only
    Give the employee sync access to /srv/brain/compiled/<person-id> only (e.g., a per-person deploy key or per-person remote). Never to the master.
  2. Clone and open the vault
    On their machine, clone it and open the folder in Obsidian:
    git clone <their-vault-remote> ~/brain
    Curious what the whole web of notes looks like? See your brain as a graph.
  3. Install the agent profile (Hermes users)
    hermes profile install github.com/<your-org>/company-brain --alias
# set terminal.cwd to ~/brain in the profile config before first run
    Claude Code users need no install — the vault's CLAUDE.md carries the same protocol.
    While you're here, consider scheduling the decisions nudge as a hermes cron --no-agent job so your agent tells you when a decision is waiting on you, instead of you remembering to check Shares.md. It prints nothing when nothing is pending, so nothing is delivered.
  4. Build the local index and register it as a tool
    brain index --vault ~/brain
claude mcp add brain -- brain mcp --vault ~/brain
    brain index is keyword-only until an embedding provider is configured (see Configuration — BRAIN_EMBED_BASE_URL etc.); set one to add semantic search. The .brain/ index is machine-local and gitignored, so it never syncs — each device builds its own.
See Per-employee setup for the detailed version.

2. Daily flow

  • Transcripts and notes reach People/<you>/Inbox/; the agent ingests and routes them. Articles, links, PDFs, and screenshots you send get distilled into the shared Company/Intel/ wiki rather than archived whole. Drop a file directly, or feed a channel (email/chat/voice/upload) that wraps the intake primitive:
    echo "decided X" | brain ingest --master /srv/brain/master --person <you> --source voice
    Services that push (Fathom, Zapier, Composio triggers) can deliver directly: declare sources in _meta/webhook.yaml and run the signed receiver on the server, behind a TLS reverse proxy:
    brain webhook --master /srv/brain/master
    See Getting things in for every channel.
  • Edits sync back; the server runs one command per interval from cron, under flock /var/lock/brain-cycle.lock:
    brain cycle --master /srv/brain/master --out /srv/brain/compiled --json
    It applies every person's writeback (edits outside the person's write scope are held and the person is told in their Inbox), provisions any self-service client requests and routes pending or auto-applied share requests, sweeps agent drafts into the pending queue, and recompiles all vaults. Nonzero exit = at least one held or failed writeback or a tampering signal (an owner-mismatch client or share request).
  • Sharing: the agent drafts promotions; approve with brain promotions approve <id> --master ... --approver admin (the approver is an admin-role identity from org.yaml — a dedicated operator account, not an employee; anything else is refused). A separate, owner-initiated flow runs alongside it: whoever owns a space (an advisor granted, or self-service-created, a client) can share or revoke a colleague's access to it themselves via brain shares — share still queues for approval by its decider (the recipient for a person-share, a team lead for a team-share, an admin for company-wide), but revoke auto-applies the same cycle.
  • Search: after pulling, the agent refreshes its index (brain index --vault ~/brain — cheap, only changed files re-embed) and queries via the brain MCP tools. For server-hosted agents, add --index to the cycle so indexes refresh centrally:
    brain cycle --master /srv/brain/master --out /srv/brain/compiled --index --json

Deployment rule

Personal agents run on the employee's device, or in a container mounting only that person's vault. Hermes profiles do not sandbox the filesystem — never co-host multiple employees' agents uncontained.
The worked example of the container branch of this rule — two boxes, chat-only users, one Hermes container per person, plus the sync plane, visual surfaces, and a full runbook — is Reference deployment, with the architecture diagram in Where the brain lives.
Powered byHolocron