# 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|codex|grok|...` |

## 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.