Architecture Decision Records¶
We record significant, hard-to-reverse decisions as ADRs using a light
MADR format. One file per decision, immutable once
Accepted — supersede rather than edit.
Index¶
| ADR | Title | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Implementation stack: TypeScript + Node + pnpm monorepo | Accepted |
| 0003 | Concurrency: atomic files + union merge + derived indexes | Accepted |
| 0004 | License: Apache-2.0 | Accepted |
| 0005 | Search: SQLite FTS5 now, pluggable embeddings later | Accepted |
| 0006 | Sync architecture: resident daemon | Superseded by 0032 |
| 0007 | Curation & review gate: in-repo staging queue | Accepted |
| 0008 | Curation locality: staging is per-user local, canon syncs | Accepted |
| 0009 | Brain-level config & feature flags (incl. optional auto-ADR) | Accepted |
| 0010 | Secret scanning: built-in regex default, gitleaks optional | Accepted |
| 0011 | Brain wiring: global user registry is the default source | Superseded by 0024 |
| 0012 | MCP distribution via the plugin at user scope | Accepted |
| 0019 | Access model: git permissions are the ACL; clone on demand | Accepted |
| 0020 | Ask the brain: the host agent synthesizes; cited retrieval | Accepted |
| 0021 | Embeddings: opt-in local-first semantic dedup; vectors in index | Accepted |
| 0022 | Decisions captured by default: autoAdr on + /decide command |
Accepted |
| 0023 | Org-brain graduation: cross-brain recurrence → org-brain, opt-in | Accepted |
| 0024 | Rule-based brain resolution: match by git identity or path | Accepted |
| 0026 | Portable plugin runtime: observable, fail-loud npx fallback | Accepted |
| 0027 | Host-neutral session extraction: Claude Code and Codex adapters | Accepted |
| 0028 | Codex lifecycle parity uses a distinct hook manifest and turn-boundary capture | Accepted |
| 0029 | Person-backed responsibility attribution for brain writes | Accepted |
| 0030 | LLM curation pass: durability judge + consolidation completes ADR-0007's curator | Accepted |
| 0031 | Project identity is resolved at read time; provenance is immutable | Accepted |
| 0032 | Sync moves from resident daemon to session lifecycle; daemon becomes an opt-in profile | Accepted |
| 0033 | Action-time contradiction guard (PreToolUse, opt-in, non-blocking default) | Accepted |
| 0034 | Obsidian-friendly derived layout: per-project MOCs, wikilinks, shipped vault config | Accepted |
| 0035 | Physical layout keys off the resolved project (supersedes ADR-0031 §1's "no file moves") | Accepted |
| 0036 | A fifth note kind: meeting (paste-and-summarize, hybrid extraction) |
Accepted |
| 0037 | Purge leaked secrets from git history: destructive rewrite + force-push | Accepted |
| 0038 | Notes carry an ingestion trust tier: internal vs. external | Accepted |
| 0039 | Capture receipts: every dropped candidate leaves a structured, persisted trace | Accepted |
| 0040 | The MCP server syncs for itself on hosts without our lifecycle hooks | Accepted |
| 0043 | External ingestion is a candidate-producer contract; connectors never write to the brain | Accepted |
| 0044 | Agent-assisted ingestion: the host's own connectors are the fetch layer for OAuth sources | Accepted |
| 0045 | External intake does not auto-promote; bulk import lands as a promotion PR | Accepted |
Process¶
- Copy the format of an existing ADR. Number sequentially.
- Status:
Proposed→Accepted/Rejected. Later decisions can mark an ADRSuperseded by ADR-XXXX. - Link the ADR from the relevant GitHub issue (decision tickets carry
type:decision). - Keep it short: Context → Decision → Consequences → Alternatives.