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

Getting Started

This is the operator's path: create a master vault, describe your people, and compile everyone's slice. It takes about five minutes.

Prerequisites

  • Python 3.12+ and uv (or any way to install the brain package).
  • git on your PATH — the compiler and write-back service operate on real git repos.
Semantic search loads the sqlite-vec SQLite extension, which needs a Python built with extension loading enabled — the uv-managed and Homebrew CPython builds have it; the macOS python.org framework build does not. If it can't load, search silently runs keyword-only. This only affects the vector leg; everything else works on any Python 3.12+.
Install the CLI from the repo:
uv tool install git+https://github.com/joedanz/brainkit
# or, from a clone:  uv pip install -e .
brain --help should now list the init, rename-entities, ingest, webhook, compile, writeback, promotions, shares, cycle, index, search, graph, facts, mcp, status, dashboard, and doctor subcommands.

Stand up a company brain

  1. Scaffold the master vault
    brain init /srv/brain/master --company "Acme Co"
    This creates the space layout (Company/, Teams/, People/, Clients/) — including the seeded Company/Intel/ wiki — seeds _meta/org.yaml and _meta/spaces.yaml (plus a commented _meta/webhook.yaml.example for when you want services pushing notes in), writes the server assistant protocol to the master-root AGENTS.md, and makes the initial git commit.
    Clients/ is just the default name for the third-party tree — pick your own at init with --entities (and --entity for the singular):
    brain init acme-brain --company "Acme" --entities Agencies --entity agency
  2. Add your people
    Edit /srv/brain/master/_meta/org.yaml — one entry per person, with their roles and teams:
    people:
  admin: {name: Admin, roles: [admin]}   # curation identity — no agent, writes Company, approves promotions and company-wide shares
  alice: {name: Alice Nguyen, teams: [sales], email: alice@acme.com}
  bob:   {name: Bob Rivera, teams: [ops], email: bob@acme.com}
    Keep the admin role on a dedicated identity, not on an employee: everyone who chats with an agent should be a plain employee (read-only on Company), so no one's agent can write shared knowledge without the human approval step.
    email is optional — add it for anyone who should be able to email notes into their brain. Adjust _meta/spaces.yaml only if the default visibility (Company readable by everyone, Teams/People scoped by membership) doesn't fit. See Configuration for the schema.
  3. Compile everyone's vault
    brain compile --master /srv/brain/master --out /srv/brain/compiled
    Each person gets a compiled/<person-id>/ vault containing only the spaces they may read, plus generated AGENTS.md / CLAUDE.md context files scoped to them. Add --person alice to compile a single slice.
A person's device only ever sees the last compiled output, so a stale compile means stale knowledge (never leaked knowledge — the compiler fails closed). Once people are editing, don't run compile by hand: schedule brain cycle (write-back → sweep → recompile → triage) on a cron job under flock (not a master git hook — a hook fires in the middle of a cycle's own commits), and gate it with brain doctor to catch integrity problems before anyone syncs.
# ongoing loop (cron): refresh everyone, then health-check
*/10 * * * * flock -n /var/lock/brain-cycle brain cycle --master /srv/brain/master --out /srv/brain/compiled --json >> /var/log/brain-cycle.log  2>&1
0    * * * * brain doctor --master /srv/brain/master --out /srv/brain/compiled --json >> /var/log/brain-doctor.log 2>&1
Keep the flock -n. A cycle that runs longer than its interval — a big vault, a slow reindex — would otherwise have the next tick start on top of it, and two compilers rebuilding the same vault race over the same swap directories. With the lock, an overlapping tick simply skips and the next one picks up. doctor is read-only and needs no lock.
Add --index to the cycle line to also refresh each vault's search index server-side. Employees who run their agent on their own device build the index locally instead — see Per-employee setup.

What you just built

/srv/brain/
  master/                 # the single source of truth (one git repo)
    Company/              # Decisions/ Playbook/ Templates/ Intel/ (distilled outside knowledge)
    Teams/ People/ Clients/
    _meta/                # org.yaml, spaces.yaml, promotions/ — never compiled out
    AGENTS.md             # server assistant protocol (master only)
  compiled/
    alice/                # Alice's slice — her People/, her Teams/, Company/
      .brain/             # local search index — machine-local, gitignored
    bob/                  # Bob's slice — his People/, his Teams/, Company/
Next, hand each person sync access to their slice — see Per-employee setup — and wire up how notes get in, from a plain file drop to email or chat, in Getting things in.
Powered byHolocron