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 |
Writing a new one
Section titled “Writing a new one”Copy the shape of an existing record. Two rules:
- 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.
- 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.