phase-memory/docs/ops-warden-memory-contract.md

Ops-Warden Cross-Runtime Memory Contract

Updated: 2026-07-02

Purpose

phase-memory provides a shared experiential substrate for ops-warden across:

• warden worker ticks with llm-connect / OpenRouter inference
• Coding agent sessions (Claude Code, Codex, Grok, future agents)
• Direct operator CLI use

All runtimes use one canonical store and the same redaction rules.

Canonical Store

Setting	Default
Path	~/.local/share/warden/memory/
Override	WARDEN_MEMORY_STORE
Opt-out	WARDEN_MEMORY=0

Layout:

• metadata.json — store schema and profile id
• events.jsonl — append-only session episodes

Session Kinds

Runtime	session_kind	Selection
Worker	warden.worker	WARDEN_SESSION_KIND=warden.worker during worker ticks
Operator CLI	warden.operator	default when WARDEN_AGENT_ID is unset
Agent session	warden.agent.<id>	`WARDEN_AGENT_ID=claude

Event Schema

Schema: phase_memory.ops_warden.session_event.v1

Required metadata fields:

• session_kind, command, outcome (resolved|escalated|skipped)
• need_fingerprint (digest only — never the raw need text when sensitive)
• route_id, agent_id, session_id, diagnostic_codes

Rejected writes containing token-like values or raw URLs.

Activation

activate_ops_warden_memory returns:

• stabilized route matches (verified repeats)
• recent episodes filtered by session kind / need fingerprint
• llm_calls_avoided when stabilized memory covers the need

Rigid memory (charter, allowlist) is import-only and never promoted from episodes.

Default Behavior

Memory is enabled by default (WARDEN_MEMORY=1). ops-warden implicitly calls ensure_memory_context on every command; explicit warden memory activate is optional introspection only.

Agent Session Orientation

Coding agents should:

1. Set WARDEN_AGENT_ID to their runtime id (claude, codex, grok, or future).
2. Use normal warden route / warden access commands; memory loads and episodes are recorded automatically.

Evaluation

Ops-warden memory quality is measured by:

• routing_repeat_accuracy
• cross_runtime_continuity
• llm_calls_avoided_count

Use evaluation_trend_regression_gate when promoting worker or routing changes.