knowledge

Default box: .box/ in the current working directory unless the user names another location. Org box (the <host>/<org>/octobrain-box repo): read it like any indexed source; never write it — propose the addition to the user. Placement test: would another project reuse this unchanged? → org box. Reference org notes from project notes, never copy them; when the two conflict, the project note wins.

WRITE — durable knowledge arrives (from the user, a brief, or memory)

1. Durable test — write only if all four hold:
   • Context-independent: true outside this session ("we deploy via X", not "the deploy just failed").
   • Concept-oriented: a fact, decision, rule, or procedure — not an event or progress note.
   • Persistent: still true and useful next month; expiring facts get a review= date in the meta line.
   • Cross-agent: a different specialist would benefit, not just this conversation. Any fail → it belongs in memory, not the box; say so instead of writing.
2. Dedup gate: search + match the box for the concept first. An existing note covers it → update that note in place. Never write a near-duplicate.
3. Write the note per . New file → add its line to the README map.
4. Empty box on first write → bootstrap .box/README.md with the map and a condensed copy of the authoring rules, then write the first note.
5. Your own just-written notes may not be indexed until the next box sync — verify writes with view/read, not search.

PROMOTE — "build the knowledge base" / "consolidate what we know"

remember() with broad multi-term queries → run every recalled fact through the durable test → dedup gate per surviving fact → write notes in batches → report what was promoted and what stayed memory-only (and why).

Parallel-first: batch independent searches, reads, and edits in one block; sequential only when an output feeds the next call.

Note format — written for the retriever

octobrain chunks at every heading (the heading path travels with each chunk) and retrieval is hybrid: semantic search plus regex match. Every rule below exists to serve one of the two:

• One durable topic per file, atomic claims at the section level. Filename = kebab-case declarative slug (session-tokens-rotate-daily.md), no dates; only decisions/ carries the sequential adr-NNNN- prefix. Slugs and headings are citation anchors — pick once, never rename; status changes happen inside the file.
• H1 = a declarative claim (the note's thesis), not a label: "Session tokens rotate daily", never "Tokens".
• Line 2 — the meta line, regex-friendly key=value tokens: Meta: type=decision status=active updated=2026-07-22 source=user-confirmed review=2027-01-01 type ∈ decision|reference|guide|term · status ∈ active|superseded · source = user-confirmed | url | inferred · review only for expiring facts.
• Then the lead: 1–3 sentences stating the full claim, self-contained. Title + meta + lead form the top chunk — the note's best retrieval surface.
• Each ## section is retrieved alone: self-contained, ~150–350 words, split past ~500. Declarative heading stating the claim ("Refresh flow re-issues both tokens", never "Details") — the stored heading path is each chunk's context, so a descriptive heading is free contextual retrieval. Repeat the subject noun; no pronouns or "as above" pointing across sections. Keep code blocks and tables whole.
• Serve both search modes in the same sentence: the exact literal in backticks AND its plain description — "SESSION_TTL (session expiry timeout) defaults to 24h".
• Decisions use ## Context / ## Decision / ## Consequences (good and bad). Guides use numbered steps under declarative section headings. Glossary: each ## is the canonical term, body defines it and names forbidden synonyms.
• End multi-note topics with Related: — relative markdown links ([session store](../reference/session-store.md)), never wikilinks.

Lifecycle

• Corrections and drift → update the note in place; git history is the archive.
• Reversed decision → write a new adr-NNNN with a Supersedes: link; flip the old one to status=superseded plus Superseded-by:. An accepted decision's substance is never edited and its file never renamed — rationale stays durable context.
• Wrong or harmful note → delete the file (deletion prunes it from the index) and update the README map.
• Keep the box small and high-signal: merge overlapping notes, one fact in exactly one place, README map always current; on every write, verify your relative links resolve.