Status: accepted v0.2 — body sourced from TriGraph spec entity. Docs-mirror file added by docs lane to surface ratified specs that lacked an on-disk mirror.
SPEC-079: Memory Domain Contracts and Continuous Improvement Loop
SPEC-079 — Memory Domain Contracts and Continuous Improvement Loop
Status
Accepted v0.2 — ratified by Donna under delegated PO authority 2026-05-04 (Plan #10 v0.3 §1; Texi clean signoff via signal d802efdd).
Author: Candi
Architecture reviewer: Texi
PO / ratifier: Donna
Storage implementation owner: Donna
Acceptance panel: Porsche
Docs sweep: Desiree
Plan: Plan #10 Wave 2 Blocker #5
v0.2 Changelog
v0.2 folds Texi architectural review 5fc0e959: 12 binding amendments, 7 nits, 4 cross-blocker references, resolution of 5 v0.1 open questions.
Summary
This SPEC defines Prism memory domains: typed contracts for what kind of memory is being stored, who owns it, when it should be retrieved, which source/citation expectations apply, and how it feeds specialization routing and Candi’s continuous improvement loop.
The goal is not to store more memory. The goal is to store the right kind of memory with enough structure that agents retrieve useful context instead of generic summaries or stale noise.
This SPEC consumes SPEC-078 vocabulary and SPEC-065 telemetry definitions. It does not redefine SPEC-065’s locked four-event taxonomy or Phase 0 baseline methodology.
Shared Definitions
| Term | Definition |
|---|
memory_domain | A typed category of durable knowledge with a storage, metadata, retrieval, ownership, and lifecycle contract. |
domain_contract | The schema and behavior rules for a memory domain. |
owning_specialization | Specialization lane responsible for maintaining or interpreting a domain. Consumes ADR #48; specialization is routing/memory/skill authority, not governance authority. |
risk_tier | R0-R3 tier from SPEC-078 used to decide required memory reads/writes. |
method_fragment | Governed methodology unit from SPEC-078 that may require or produce domain-specific memory. |
consensus_artifact | Memory item recording proposal, review, amendment, veto, tie-break, or authorization within a consensus loop. |
validation_result | Memory item recording launcher, install, deploy, RTE, dashboard probe, or smoke-test validation evidence. |
CI_loop | Continuous improvement loop owned by Candi for detecting memory/routing/methodology misses and proposing refinements. |
recall_event | SPEC-065 memory_recall_events row; locked telemetry. |
citation_event | SPEC-065 memory_citation_events row; locked telemetry. |
Problem
Prism captures many artifacts: session deltas, decisions, TODOs, postmortems, research, operator inputs, specs, ADRs, journals, retros, recall events, citations. Current weakness: not every captured item declares what kind of memory it is, who should retrieve it, or what lifecycle rules apply.
Four failures: (1) Recall dilution — agents retrieve broad summaries when they need typed decision/rule/code-fact/handoff. (2) Routing misses — specialization-aware routing cannot reliably target right memory because domains are implicit. (3) Token waste — agents read too much static context. (4) Learning stalls — Candi cannot systematically improve methodology when failures aren’t classified by domain and cause.
Goals
Define canonical memory domains for Plan #10 work. Define required metadata per domain. Define retrieval behavior and citation expectations. Define which domains are mandatory at checkpoint/wrap by risk tier. Define how method fragments read/write memory domains. Preserve SPEC-065 telemetry baseline. Provide Porsche-visible acceptance measures. Establish Candi’s CI loop for domain refinement. Keep automated domain routing behind default-off feature flag.
Non-goals
No changes to SPEC-065 four-event taxonomy. No changes to memory_recall_events/memory_citation_events schemas in initial implementation. No production Tri-Graph governance recall dependency in initial implementation. No automatic rewrite/deletion of existing memories. No hard enforcement while feature flag off. No cross-tenant memory federation.
Feature Flag Contract
| Field | Value |
|---|
| Name | PRISM_MEMORY_DOMAINS_ENABLED |
| Default | false |
| Owner | Candi (domain semantics + CI-loop methodology); Donna (storage implementation authorization) |
| Operator-visible state | Future boot/report surfaces show enabled/disabled only when implementation exists. |
| Shadow mode | No. Passive domain inference while flag off requires separate SPEC/amendment. |
| Rollback | Set flag to false; domain metadata remains inert. No SPEC-065 telemetry rollback. |
false: existing memory writes continue unchanged, existing recall behavior continues unchanged, no domain requirement blocks checkpoint/wrap, no automatic domain-based routing, no method fragment injected based on domain, SPEC-065 telemetry unchanged.
When true in future implementation: Prism may validate domain metadata on new domain-aware writes, recommend required memory reads/writes by risk tier, surface domain-specific recall hints, report missing required domain records at checkpoint/wrap, emit CI-loop candidates when misses repeat.
No shadow mode. Default-off invariant test: start session with flag unset, perform semantic_recall/prism_memory_cite/prism_checkpoint/prism_wrap, verify response shapes match pre-SPEC-079, verify SPEC-065 telemetry unaffected, verify no checkpoint/wrap blocked for missing domain metadata.
Relationship to SPEC-065
SPEC-065 = measurement system. SPEC-079 = typing and routing system.
SPEC-065 locked definitions: Hit / Miss / No-attempt / Wasted-recall / memory quality vs agent quality / per-session primary unit / query classes (historical, architectural, current_state, decision, other) / citation kinds (cited, dismissed, flagged_stale, rewrote, saved_rework).
SPEC-079 must NOT change those definitions.
Strict baseline protection: no domain labels added to SPEC-065 telemetry rows during locked baseline; no mutation of memory_recall_events/memory_citation_events schema; no reinterpretation of Hit/Miss/No-attempt/Wasted-recall; no mid-baseline query-class or citation-kind drift; domain typing is orthogonal annotation/routing layer.
Domain metadata may be represented only as additive sidecar data, artifact/session-delta metadata, or future projection/graph properties after ratification and behind feature flag.
Canonical Memory Domains
| Domain | Purpose | Owning specialization | Typical source |
|---|
decision | Durable choice and rationale. | architecture / governance / engineering | ADR, checkpoint decision, ratified spec |
rule | Binding or advisory instruction. | governance | BIOS, PRISM.md, ORG, ADR, SPEC |
operator_preference | Human preference shaping defaults but not authority unless promoted. | governance / product | operator input, checkpoint |
task_state | Current status of active work. | lane owner | checkpoint, status update, plan |
codebase_fact | Verified fact about local implementation. | engineering / architecture | code inspection, tests, commit |
external_claim | Claim from web/repo/third-party docs/external system. | research / relevant lane | cited source |
handoff | Context needed by another agent/session to continue. | current owner | checkpoint, wrap, signal |
retrospective | Lesson from completed work. | governance / lane owner | retro, postmortem |
research_note | Exploratory synthesis that may inform later decisions. | research / relevant lane | docs/research, semantic_recall |
generated_summary | Derived summary from source material. | docs / governance | generated docs, wrap summaries |
consensus_artifact | Proposal/review/amendment/veto/authorization in a consensus loop. | governance / architecture / Donna | signals, SPEC review, Plan #10 |
validation_result | Verifiable outcome of launcher/install/deploy/RTE/dashboard probe/smoke validation. | engineering / runtime / telemetry / install | tests, smoke logs, deploy status, probe output |
method_fragment | Governed reusable methodology unit. DB artifact is SOR; docs are generated mirrors. | governance / owning specialization | SPEC-078 method fragments |
specialization_memory | Lane-specific pattern, context, or method. | named specialization | method fragment, lane notes |
Domain Contract Fields
domain: <slug>
schema_version: 1
source_of_record: prism_typed_artifact|artifact_metadata|session_delta_metadata|sidecar_annotation|graph_projection
source_ref: <path or artifact id>
authority_layer: global|tenant|org|project|user_session_runtime|n/a
owning_specialization: <specialization>
ratifier: <identity or null>
applies_to_specializations: [<specialization>]
applies_to_risk_tiers: [R0, R1]
required_metadata: [<field>]
source_expectation: none|local_source|citation_required|ratified_artifact
retention: transient|session|project|long_lived|append_only
update_behavior: append_only|supersede|mutable_with_audit|regenerate
retrieval_behavior: bootstrap|pre_action|on_demand|checkpoint|wrap|ci_loop
conflict_policy: <resolver>
supersedes: [<domain or artifact id>]
superseded_by: [<domain or artifact id>]
last_verified_at: <iso8601 or null>
tri_graph_node_type: <node type or null>
tri_graph_edges: [<edge type>]
telemetry_key: memory_domain.<slug>
telemetry_tags: [<tag>]
Domain-Specific Contracts (summary)
decision: ratified-artifact source; long-lived append-only or superseded; pre-action retrieval for arch/gov work; conflict→Texi/Candi/Donna-PO. rule: ratified-artifact/BIOS/live-state source; long-lived; bootstrap+pre-action; conflict→Candi (own domain, NOT subtype of decision). operator_preference: operator/Donna statement; never silently overrides rules; conflict→preference yields to rule unless promoted. task_state: checkpoint/status-signal/plan; bootstrap+checkpoint+wrap+handoff; Donna for Plan #10. codebase_fact: code/test/commit source; project retention superseded on impl change; pre-action; Donna/Texi conflict. external_claim: citation REQUIRED when materially used in ADR/SPEC/implementation/product/operational; optional for exploratory unused. handoff: checkpoint/wrap/signal; bootstrap+assignment-start; Donna for Plan #10 disputes. retrospective: retro/postmortem; append-only; bootstrap for high-severity + CI loop. research_note: research file/durable memory with sources; on-demand; conflict→owning-spec+Candi. generated_summary: source_refs required; regenerate/supersede; never SOR unless ratified; conflict→Desiree+Candi. consensus_artifact: proposal/review/amendment/veto/tie-break/authorization; append-only R2/R3; pre-impl + review + ratification + CI; conflict per SPEC-078. validation_result: launcher/install/deploy/RTE/dashboard probe/smoke output; project-or-long-lived; review/ratification/deploy/CI/panel; conflict→Donna(eng)/Samantha(rte)/Lafonda(install)/Porsche(panel). method_fragment: Prism-typed-artifact-DB-SOR + docs mirror; long-lived; trigger/assignment-start/CI; conflict→Candi/Texi/Donna. specialization_memory: lane note/method fragment/repeated pattern; project-or-spec-namespace; assignment-start + method-trigger; conflict→Candi+lane-owner.
Required Memory by Risk Tier
| Risk tier | Required reads | Required writes |
|---|
| R0 | Existing local context; recall optional unless historical/architectural claim. | checkpoint if state changed. |
| R1 | task_state + relevant codebase_fact; decision/rule recall when governed behavior touched. | task_state checkpoint; codebase_fact if verified new fact matters. |
| R2 | rule, decision, codebase_fact, relevant research_note, prior consensus_artifact. | consensus_artifact, decision/rule update if ratified, task_state checkpoint, RCA if issue. |
| R3 | All R2 + plan/task_state/handoff/retrospective. | consensus_artifact chain, handoff, checkpoint per milestone, final summary, validation_result, RCA. |
Method Fragment Integration
Method fragments from SPEC-078 declare: required memory domains, memory writes, owning specialization, applies_to_specializations, risk_tier_default, telemetry_key, conflict_policy.
Method fragments are Prism typed artifacts DB-SOR with generated docs mirrors. Consumed from SPEC-078 v0.2; NOT redecided here.
Example:
id: method.consensus.architecture-gate
required_context: [rule, decision, codebase_fact]
memory_writes: [consensus_artifact, task_state]
CI Loop
Candi owns methodology CI loop for memory domain usefulness.
Watches for: repeated No-attempt for domains that should have triggered recall, Miss events where domain label would improve retrieval, Wasted-recall caused by stale/ambiguous domain metadata, repeated prompt/method conflicts, agents loading excessive context for narrow specialization tasks, consensus loops missing required artifacts.
Outputs: method-fragment amendment, memory domain amendment, prompt/rule clarification, retrieval query improvement, TODO for implementation, ADR/SPEC amendment when authority changes, postmortem/RCA when issue occurred.
Candi authority: may create CI items, propose SPEC/ADR/method/domain amendments, resolve methodology conflicts within authority. Governance authority changes / contract changes / enforcement behavior changes require SPEC/ADR + Donna ratification + Texi review.
Cadence: immediate for urgent governance blockers; checkpoint-level for active workstream misses; every 3 SPEC-065 research cycles for baseline-compatible review.
Telemetry and Acceptance Panel
Porsche panels distinguish memory quality from agent quality, preserving SPEC-065. Candidates: recall events by query_class+memory_domain; citation events by citation_kind+memory_domain; No-attempt count by risk tier; Wasted-recall count by domain; consensus_artifact completeness for R2/R3; checkpoint/wrap missing-domain warnings when flag enabled; retrieval payload size by domain; top domains in CI items; per-session domain hit/miss trend; per-specialization recall quality. No claims about performance enter prompts until measured.
Storage Model
Initial implementation does NOT require new table. v1 represents domain metadata as: metadata on existing artifacts; tags on session deltas/notes/specs/ADRs; graph properties in future Tri-Graph; sidecar memory_domain_annotations table only if Donna’s review finds metadata-on-artifact insufficient.
Domain contracts themselves = Prism typed artifacts DB SOR + generated docs mirrors.
{
"memory_domain": "decision",
"schema_version": 1,
"owning_specialization": "governance",
"risk_tier": "R2",
"authority_layer": "project",
"source_ref": "ADR-48",
"last_verified_at": "2026-05-04T00:00:00Z",
"telemetry_key": "memory_domain.decision"
}
Wave 3 Tri-Graph Feed
Blocker #6 entities: MemoryDomain, DomainContract, ValidationResult, MethodFragment, ConsensusArtifact, ExternalClaim, Rule, Decision, CodebaseFact. Edges: HAS_DOMAIN, REQUIRES_READ, WRITES_DOMAIN, VALIDATES, CITES, SUPERSEDES, OWNED_BY_SPECIALIZATION.
Graph index = assistive recall surface; reports source/citation/freshness; does NOT silently outrank committed Ring authority or live prism_start state.
Implementation Phases
Phase 0 — Ratification only: Texi review, Donna ratification, no behavior-changing code.
Phase 1 — Manual domain tagging (validation paths only when flag-enabled): domain templates in docs/research/Prism-creation guidance; Candi tags CI items manually; Desiree docs sweep; no blocking.
Phase 2 — Advisory validation (flag-enabled): warn on missing domain metadata for new domain-aware writes; report risk-tier required domains at checkpoint/wrap; surface domain-specific recall suggestions; no hard block.
Phase 3 — Enforcement + Tri-Graph integration (separate authorization + Blocker #6 ratification): Tri-Graph indexes domain metadata; domain recall replaces repeated doc scanning; R2/R3 completion may require consensus_artifact completeness; Candi CI loop creates tracked improvement tasks.
Acceptance Criteria
- SPEC reviewed by Texi and ratified by Donna. ✓
- Feature flag named and default-off invariant specified. ✓
- SPEC-065 locked taxonomy preserved without modification. ✓
- Canonical memory domains defined. ✓
- Domain contract fields defined. ✓
- Required memory reads/writes defined by R0-R3. ✓
- Method-fragment integration defined. ✓
- Candi CI loop defined. ✓
- Porsche panel/probe candidates defined. ✓
- SPEC-065 strict baseline protection explicit. ✓
validation_result and method_fragment are canonical domains. ✓- Wave 3 Tri-Graph entities/edges listed. ✓
- With feature flag unset/false, existing recall/citation/checkpoint/wrap behavior remains unchanged. ✓
Review Decisions Folded in v0.2
rule remains its own memory domain, not a decision subtype.external_claim is mandatory whenever external research materially informs ADR/SPEC/implementation/product/operational claims; optional for unused exploratory.- Domain metadata on existing artifact/session-delta first; domain contracts DB SOR + docs mirrors; sidecar
memory_domain_annotations allowed at impl-time if needed.
- Missing-domain checkpoint/wrap behavior advisory in Phase 2 only; hard-blocking requires Phase 3 + separate authorization + tests.
- Launcher/install/deploy/RTE/dashboard smoke results use
validation_result domain.
References
- Plan #10 v0.3 (Donna ownership map)
- SPEC-078 v0.2 (Consensus-First Parallelism + Method Fragments)
- ADR #48 v0.2 (Identity / Specialization / Assignment / Style Model)
- SPEC-065 (Memory System Improvement: Research Methodology + Phase 0 Telemetry)
docs/research/operational-definitions-2026-05-01.mddocs/research/SPEC-065-draft.mdbackend/alembic/versions/029_spec065_memory_telemetry.pybackend/app/services/memory_telemetry_service.py- Texi architectural review
5fc0e959
- Texi clean signoff
d802efdd
