Mnemoverse Docs

Appearance

KV Policy — Contract v0 ​

This page defines the kv_policy contract emitted by ACS in render_context_reply.v0. It specifies how working memory entries should be treated across turns.

Contract source of truth:

  • Schema: schemas/render_context_reply.v0.json → properties.kv_policy
  • Field location: api/internal.md (ACS → CEO)

Schema shape (v0):

  • kv_policy is optional object with three string arrays
    • pin: string[]
    • compress: string[]
    • evict: string[]
  • additionalProperties: false

Semantics:

  • pin: items that must remain in memory without eviction during the current turn and at least until the next ACS decision point.
  • compress: items eligible for lossless or lossy compaction (summarize/merge/downgrade LOD) to reduce footprint; logical key identity must remain stable.
  • evict: items that should be removed from the cache as soon as practical. They may be reloaded later if referenced again.

Identity and referential rules:

  • Keys SHOULD reference fragment.id values present in fragments[] of the same reply or persistent cache keys known to CEO.
  • Keys MUST be unique per array. Duplicates have no additive effect and MAY be ignored.
  • Unknown keys MUST be ignored safely (no hard failure).

Conflict resolution (when the same key appears in multiple arrays):

  1. pin wins over compress and evict
  2. compress wins over evict
  3. If an implementation receives conflicting directives, it MUST apply the strongest directive per the order above and MAY log a LOW_COVERAGE or PARTIAL_DATA warning if conflicts are frequent.

Privacy interactions:

  • kv_policy only references keys. It MUST NOT include raw text or sensitive content.
  • When privacy_mode is redact or block at provider-side, ACS still MAY emit kv_policy for stable keys; CEO must not expose sensitive text while applying the policy.

Operational guidance:

  • Pin minimal set: pin only prerequisites of imminent generation (e.g., macro summaries and active micros).
  • Prefer compress for large micros/atomics with medium near-term utility.
  • Evict stale, low-reuse, or redundant fragments first; consider time since last use and benefit/size ratio.

Examples (valid to schema):

Minimal policy: { "kv_policy": { "pin": ["doc:sum:Q"], "compress": [], "evict": [] } }

Mixed policy with conflicts (receiver applies precedence rules): { "kv_policy": { "pin": ["frag:macro:123"], "compress": ["frag:micro:789", "frag:atomic:777", "frag:macro:123"], "evict": ["frag:atomic:555", "frag:micro:789"] } }

Notes:

  • The examples above show only the kv_policy node for brevity. In actual replies, kv_policy appears alongside fragments[] and metrics (see api/internal.md).

Related:

  • Internal API contract: api/internal.md
  • Planner heuristics: acs/planner-and-selection.md (KV Policy Heuristics)
  • Metrics reference: metrics.md