Decision: company brain structure (agent-readable)
Current truth (the structure we run)
Hybrid context architecture: a small always-loaded index (MEMORY.md, capped ~200 lines / 25KB) + atomic on-demand pages pulled just-in-time by path. Curate the smallest high-signal set; push detail to on-demand pages. Flat markdown + index — no embeddings/graph until a curated index stops being navigable.
Page format kept: Current truth (rewritten in place) / Open questions / Timeline (append-only). Durable state never fights history.
Frontmatter extended: description (the retrieval lever — a sharp line agents scan from the index), status (evergreen|log|accepted|superseded), last_reviewed, source. rebuild-index.sh now uses description as the index hook.
Granularity: atomic pages, but not atomized. Promote a page to a directory only when a concept is a cluster with a shared entrypoint (overview + on-demand sub-files = the progressive-disclosure unit).
Decisions: significant → own page (decisions/<date>-<slug>.md, supersede not delete); tactical → a Timeline line + decision | LOG line. Engineering/build decisions live in the product repo, not here.
Boundaries (link, don’t duplicate): backlog/status → Linear; product spec → product repo docs/; the brain holds the KNOW/why + pointers. A duplicated fact drifts.
Product brain: ado-platform.md (hub/index) · ado-score-model.md · architecture.md (links to repo docs) · roadmap.md (strategic Now/Next/Later → Linear epics; scaffold) · ideas.md (pre-Linear triage; scaffold). pricing-packaging.md to add.
Research brain (planned): research/hypotheses/ (bets: must-be-true statement · confidence · falsification criteria · append-only evidence · decision trigger) and research/competitors/ (Alpic, Ora) — directories of atomic evergreen pages, fed by a weekly deep-research pass.
Pipelines: hourly Granola call-ingest; the brain-notify Telegram bot (push → new-call / wiki-commit / skill-review pings, diff links); planned weekly deep-research-per-hypothesis/competitor (lighter harness, human owns the confidence call; X/Twitter excluded — no cheap reliable access).
Why
Grounded in two adversarially-verified deep-research passes (2026-06-14). Primary sources: Anthropic context-engineering + Claude Code memory docs + Agent Skills + the llms.txt spec; Torres/Strategyzer for hypothesis tracking. Caveats: evidence is Anthropic-centric (cross-vendor angle unverified); llms.txt is an index format for our own agents, not an SEO mechanism; the 200-line cap is Claude-Code-specific.
The team’s existing setup (capped MEMORY.md + promotion gate, per-entity pages, AGENTS.md, the page format, git history) already implements the recommended hybrid index+JIT pattern — so this is refine, not rebuild.
Open questions
When does research/ outgrow flat-files-plus-index and need embeddings/graph? (No verified size threshold.)
Promotion/demotion criteria for the always-loaded MEMORY.md layer beyond the existing gate.
Product-page curation cadence (the product wiki’s context isn’t transcript-derived — needs a human ritual; staleness on last_reviewed as the trigger).