generated from coulomb/repo-seed
80 lines
2.3 KiB
Markdown
80 lines
2.3 KiB
Markdown
# 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. |