A file-first personal knowledge base your coding agent operates. Markdown is the source of truth; the search index is disposable and rebuilt on demand.
Storage history and pressure evidence describes bounded operational sampling, recovery and Critical notification receipts.
- Quickstart — create a private brain, capture a note and find it without API keys; then choose whether to personalize it with an agent.
- Concepts — learn how files, frontmatter, types and links fit together, and what the disposable index does.
- Daily workflow — capture, connect and review notes, refresh the index, and sync a brain you already own.
These pages are the reading order for a new user. The guides below explain optional capabilities; the references answer a specific command or setting question. This Markdown index is also the navigation source for public docs.
| Guide | Use it to |
|---|---|
| Modules | Enable domain workflows or author a local module; follow links to each module's full reference. |
| Storage | Inspect capacity, find large files, run owner-supported maintenance, and review recoverable attachment removal. |
| Media | Decide which assets to keep in git and how large files behave during sync. |
| Evaluating search | Build a query set and measure retrieval without mistaking an invalid set for a useful score. |
| Hosting | Back up a local brain and understand the separate, not-yet-published hosting-template path. |
| Extending | Implement a provider at an existing experimental seam; modules and infrastructure providers are separate mechanisms. |
These references follow the source in this repository. Check brain --version
and the installed package's CHANGELOG.md when using a published release;
versioned additions are not available in older packages. The quickstart uses
the published template rather than a source checkout.
| Doc | What's in it |
|---|---|
| supported-inputs.md | Shared compatibility policy and complete input-family inventory for brain config, environment, JSON settings and canonical module content. |
| configuration.md | The full brain.config.ts reference — every key, its type, default, and an example — plus common environment variables, root resolution, and the brain.config.json variant. |
| cli.md | Command reference for the brain bin — all commands, key flags, and which --json shapes are contract-bound. |
| mcp.md | The stdio MCP server: registration, the eight core brain_* tools and module tools, staleness warnings, and taxonomy-generated type filters. |
| extending/README.md | Provider configuration and each seam's registration entry point, the bar for promoting a community provider to a built-in, and the verbatim not-pluggable list. |
| extending/embeddings.md | The EmbeddingProvider seam. |
| extending/completions.md | The CompletionProvider seam. |
| extending/agent-runners.md | The AgentRunner seam. |
| extending/rerankers.md | The opt-in Reranker seam and its evaluation evidence. |
| extending/skill-emitters.md | The SkillEmitter seam. |
| extending/agent-backends.md | The AgentBackend seam: authoring a chat-UI agent backend — turn lifecycle, the permission bridge, and how ui-server loads backends. |
| conditional-forms.md | Conditional questions in one card, visible-answer results, configurable limits and keyless schema-cost estimates. |
| http-api.md | Complete mounted-route inventory, supported HTTP authentication/inputs/responses/errors, SDK dependencies and internal UI transport boundary. |
| content-index-queries.md | Supported synchronous content-index results, validation, compatibility and snapshot lifetime. |
| inbox-storage.md | Internal durable Queue and Action storage, guarded transactions, checkpoints, cursor replay and recovery ownership. |
| inbox-actions.md | Atomic escalation and exactly-once decisions, deterministic snooze, cap/expiry/suppression, bounded retries and staging compensation. |
| inbox-budget.md | Autonomous spend/turn admission, conservative reservations, frozen settlement and crash recovery. |
| inbox-runtime.md | Queue lifecycle, expired-lease recovery and the protected local HTTP poke with boot token rotation. |
| inbox-notifications.md | Counted Action pushes, fixed windows, client-local quiet hours and digest coverage, per-device attempt history. |
| inbox-recovery.md | Complete operational backup, staging consistency, empty-target restore, crash resumption and the 24-hour recovery point. |
| integration-contract.md | The stable machine surface: CLI --json shapes, MCP tools, supported HTTP/wire behavior, brain.db reads, and versioning rules. |
| Doc | What's in it |
|---|---|
| process/github.md | Where work lives: the label taxonomy, what a milestone commits to, the project board's fields, the issue lifecycle, and what an agent does before writing code. |
| process/testing.md | Testing and proof: the offline test harness, tests that cannot fail, failing-first receipts, required PR proof and the GitHub Actions CI policy. |
| process/feature-captures.md | Editorial screenshot and demo recipes, source/readiness rules and public asset provenance. |
| decisions/README.md | Why things are the way they are — the alternatives rejected and the measurements that decided them. Read the record for whatever you are about to change. |
| investigations/README.md | Dated historical reports, pinned source evidence and measurement limitations; current guidance remains in the guides and decisions. |
| plans/README.md | Design for work that is not built yet. Normally at most one. |
- The agent contract (
@schlessera/brain/CONTRACT.md) — the Layer-1 rules imported into every brain'sCLAUDE.md. - Each first-party module's own README for its full field reference.