AkurAI-Notes / docs/adr/005-memory-schema-and-supersession.md

Latest change b5edafd099fbb715485f63f0c36354159da099e2 - OLI-114: ADRs 002-005 (FTS vs ParadeDB, zoekt, chunking/embedding versioning, memory schema) by Dev Lead

# ADR 005: Memory schema and supersession

Status: Proposed (Dev Lead, 2026-09-30) · Epic OLI-112 · Phase 2 input

## Decisions
1. **Table `memory`:** id, type (`episodic|semantic|procedural`), text, scope (`global|project|agent`), scope_ref, source (issue/commit/note/run id), confidence 0..1, importance 0..1, owner, created_at, valid_from, valid_until, supersedes_id (self FK), status (`active|review|superseded|forgotten`), embedding(model_id, version, vector). One row is one fact; no multi-fact blobs.
2. **Supersession, never overwrite:** a contradicting same-subject fact inserts a new row with `supersedes_id = old.id`, sets `old.valid_until = now()` and `old.status = superseded`. History stays queryable (`as_of` recall). Contradiction = same subject (cosine >= 0.92 + rerank agreement) with a differing assertion; ambiguous cases go to `review`.
3. **Dedupe:** cosine >= 0.92 and reranker agreement merges into the existing row (bumps importance, appends source) instead of inserting.
4. **Review queue:** confidence < 0.6 is stored `review`, excluded from recall until accepted.
5. **Forget:** tombstone row (text blanked, id and audit kept), vector deleted, audit entry; owner/board only (ADR 006).
6. **Recall score:** `rerank * (0.7 + 0.2*importance + 0.1*recency_decay)`, only `active` and `valid_until` null or future, always with citations (`source`).
7. **Lifecycle:** episodic TTL 90 d with decay; weekly consolidation summarises clusters into a semantic fact keeping source links.
8. All reads go through the authz row filter of ADR 006.

## Consequences
Append-mostly table with a supersession chain; recall must filter on status/validity (partial index on `status='active'`). Schema is reference only until Phase 2; no DDL applied yet.