Design decisions

Each record covers one decision that is not obvious from reading the code, and states the condition under which it should be reversed. The reversal condition is the part that matters: a decision without one is a preference, and a preference nobody can argue with is how a codebase ossifies.

Format is MADR-shaped: context, decision, consequences, reversal condition.

#	Decision	Status
001	Memory decays on a 30-day half-life	Accepted
002	bbolt with a single writer, and a daemon to share it	Accepted
003	The knowledge graph has a write path but no automatic population	Accepted, partial
004	Local-first and single-node, deliberately not multi-tenant	Accepted
005	Embeddings degrade Ollama → OpenAI → Anthropic → keyword	Accepted
006	Retrieval signal weights are configurable	Accepted
007	Contradictions are resolved by tombstone, never by delete	Accepted
008	Knowledge-graph auto-population ships gated (--kg / env)	Accepted
009	KG activation persists as data-dir state via init --kg	Accepted
010	Pinned facts are exempt from decay, pruning and summarisation	Accepted
011	Consolidation is propose/apply with tombstone receipts; Ollama summarises locally	Accepted
012	Tool definitions are engineered against the TDQS rubric and pinned by contract tests	Accepted
013	Tool results carry structuredContent twins with declared output schemas	Accepted
014	agent_id is the canonical agent parameter; agent remains a deprecated alias	Accepted
015	checkpoint_resume returns a successful absence result under on_missing=empty	Accepted
016	Explicit confidence writes, eligibility filters and bounded opt-in retrieval preference	Accepted, default promotion pending

Writing a new one

Copy the shape of an existing record. Two rules:

1. The reversal condition has to be checkable. “If it becomes a problem” is not a condition. “If p95 recall latency exceeds 50 ms on a 100k-fact store” is.
2. Record what was rejected and why. The alternatives are most of the value; a decision with no alternatives listed reads as though there were none.