| 1 | # KB v2 Memory Contract |
| 2 | |
| 3 | Production-oriented memory contract for stable long sessions and predictable context routing. |
| 4 | |
| 5 | ## Goals |
| 6 | |
| 7 | - Keep response latency stable during long chats. |
| 8 | - Preserve decision-grade memory without dragging full archives into hot context. |
| 9 | - Make context loading explicit, measurable, and reversible. |
| 10 | |
| 11 | ## Publication boundary (канон) |
| 12 | |
| 13 | - Источник правды по публичной KB: репозиторий **agent-notes** — **`knowledge/PUBLISHING.md`** (политика; **входит** в kb-public), пути-исключения — **`knowledge/public-kb.ignore`** (только в полном каноне), операции пуша и хосты — **только** под **`knowledge/work/`** (в kb-public не копируется), сборка **`scripts/build-public-kb.ps1`** (плюс **`<!-- public-cut -->`** в `agent-notes.md`, фильтр по первой строке «НЕ ПУБЛИКОВАТЬ»). |
| 14 | - Путь **`knowledge/work/`** (включая **`work/projects`**) — оперативный слой; в **kb-public** не попадает, если перечислен в **`public-kb.ignore`** (по умолчанию так и есть). |
| 15 | |
| 16 | ## Layer Boundaries |
| 17 | |
| 18 | - **L0 (hot cache):** current goal, next action, blockers, guardrails. |
| 19 | - **L1 (working state):** active contracts and near-term decisions. |
| 20 | - **L2 (archive):** historical batches, long analyses, raw transcripts, large artifacts. |
| 21 | - **L3 (router):** status/playbook/matrix entrypoints and retrieval order. |
| 22 | |
| 23 | ## Budgets and SLO |
| 24 | |
| 25 | - **L0+L1 soft budget:** up to 6000 chars. |
| 26 | - **L0+L1 hard budget:** up to 12000 chars. |
| 27 | - Above soft budget -> warning, recommend `compact_hot_context`. |
| 28 | - Above hard budget -> critical, require compaction before continuing deep work. |
| 29 | |
| 30 | ## Retrieval Contract |
| 31 | |
| 32 | - Default order: `status -> playbook -> matrix -> kb`. |
| 33 | - Router must load only top relevant sections first. |
| 34 | - Archive access is explicit and query-driven (no full L2 hydration by default). |
| 35 | |
| 36 | ## Operational Triggers |
| 37 | |
| 38 | - Run `memory_health`: |
| 39 | - before long implementation sessions, |
| 40 | - after large context imports, |
| 41 | - after context compression recovery. |
| 42 | - Run `route_context`: |
| 43 | - before deep task start, |
| 44 | - when scope changes, |
| 45 | - when mixed-domain ambiguity appears. |
| 46 | - Run `compact_hot_context`: |
| 47 | - when `memory_health` emits warning/critical, |
| 48 | - before release/debug marathons. |
| 49 | |
| 50 | ## Minimal Governance |
| 51 | |
| 52 | - Preserve additive compatibility for MCP tools. |
| 53 | - Keep destructive behavior behind explicit `apply=true`. |
| 54 | - Record only decision-grade deltas in hot context. |
| 55 | |