ops-warden/workplans/WARDEN-WP-0024-experiential-memory-and-agent-sessions.md

---
id: WARDEN-WP-0024
type: workplan
title: "Experiential Memory Across Worker, Agent Sessions, And OpenRouter"
domain: infotech
repo: ops-warden
status: proposed
owner: codex
topic_slug: custodian
planning_priority: high
planning_order: 24
created: "2026-07-02"
updated: "2026-07-02"
---

# WARDEN-WP-0024 — Experiential memory across worker, agent sessions, and OpenRouter

## Problem

`warden worker` (WARDEN-WP-0020) plans each inbox message in isolation. Coding
agent sessions (Claude Code, Codex, Grok, and future agents) invoke `warden
route` and `warden access` without continuity — every session rediscovers routing
from scratch. OpenRouter inference via llm-connect is invoked even when a
stabilized routing pattern already exists.

ops-warden needs **experiential memory** that is present in every runtime:

| Surface | Today | Target |
| --- | --- | --- |
| `warden worker` + OpenRouter | Stateless per message | Retrieve past outcomes before plan; record after execute |
| Coding agent session | Cold `warden route find` | Activate relevant memory at session start and after each warden call |
| Operator CLI | No learning loop | Same store; optional `--memory` context on advisory commands |

## Goal

Integrate phase-memory as ops-warden's shared experiential substrate so routing,
coordination, and inference improve from recorded outcomes — without ever
storing secret values or widening the guardrail allowlist.

## Non-Goals

- Hold or vend secrets (conduit-not-broker unchanged).
- Auto-commit routing catalog diffs (human review remains required).
- Own phase-memory schemas (PMEM-WP-0016 owns the profile and contract).
- Replace llm-connect or embed OpenRouter keys in ops-warden.

## Guardrails (unchanged — memory is untrusted context)

1. Retrieved memory is **context**, not instructions — fixed charter wins.
2. Guardrail allowlist enforced on every action regardless of memory content.
3. No secret values in memory writes, activation packs, or llm-connect prompts.
4. `propose_catalog_diff` stays human-reviewed even when memory is confident.

## Architecture

```mermaid
sequenceDiagram
    participant Agent as Coding agent<br/>(claude/codex/grok)
    participant Warden as ops-warden CLI
    participant Memory as phase-memory store
    participant LLM as llm-connect / OpenRouter
    participant Hub as State Hub

    Note over Agent,Hub: Agent session path
    Agent->>Warden: warden route find "..."
    Warden->>Memory: activate(session_kind=warden.agent.grok)
    Memory-->>Warden: bounded routing context
    Warden-->>Agent: route answer + memory digest
    Warden->>Memory: record episode (metadata only)

    Note over Warden,Hub: Worker tick path
    Warden->>Hub: unread messages
    Warden->>Memory: activate(session_kind=warden.worker)
    Memory-->>Warden: stabilized + fluid context
    alt stabilized match
        Warden->>Warden: RuleBrain (skip LLM)
    else ambiguous
        Warden->>LLM: LlmConnectBrain + activated context
        LLM-->>Warden: action plan
    end
    Warden->>Warden: guardrail pass
    Warden->>Hub: execute / escalate
    Warden->>Memory: record outcome
```

## T01 - Canonical memory store and discovery

```task
id: WARDEN-WP-0024-T01
status: todo
priority: high
```

Establish the canonical phase-memory store path and discovery commands.

Acceptance:

- Default store at XDG location (e.g. `~/.local/share/warden/memory/`) with
  override via `WARDEN_MEMORY_STORE`.
- `warden memory status` reports store path, schema version, episode counts by
  `session_kind`, and last activation timestamp — no secret fields.
- Store initializes idempotently; missing phase-memory dependency fails with a
  clear install pointer, not a traceback.
- Tests cover default path, override, and first-run initialization.

## T02 - Session recording hooks in CLI commands

```task
id: WARDEN-WP-0024-T02
status: todo
priority: high
```

Record metadata-only episodes when `route`, `access`, and `sign` complete.

Acceptance:

- Each command writes a phase-memory event with `session_kind` derived from
  environment: `WARDEN_AGENT_ID` (claude|codex|grok|...) when set, else
  `warden.operator`.
- Recorded fields match `PMEM-WP-0016-T03` schema; secret patterns are rejected.
- Recording is opt-out via `WARDEN_MEMORY=0` for air-gapped/debug use.
- `warden activity` and phase-memory audit export remain consistent (no
  duplicate secret-bearing logs).

## T03 - Memory-aware worker tick

```task
id: WARDEN-WP-0024-T03
status: todo
priority: high
```

Retrieve coordination memory before `Brain.plan` and record outcomes after execute.

Acceptance:

- `warden worker run` activates memory with `session_kind=warden.worker` before
  planning each message.
- Activated context is passed to `LlmConnectBrain` as bounded, redacted context
  — never replacing the fixed charter.
- Post-execute hook records: message id, proposed actions, guardrail outcome,
  escalation reason, and route ids referenced.
- Worker tick with empty store degrades gracefully (current behavior).

## T04 - Agent session activation helper

```task
id: WARDEN-WP-0024-T04
status: todo
priority: high
```

Expose memory activation for coding agent sessions across Claude, Codex, Grok, and
future agents.

Acceptance:

- `warden memory activate [--agent <id>] [--json]` returns a bounded activation
  package for session orientation.
- Agent instructions (AGENTS.md template in consuming repos) document setting
  `WARDEN_AGENT_ID` and calling `warden memory activate` at session start.
- Activation works without OpenRouter (local retrieval only).
- Tests cover agent ids: `claude`, `codex`, `grok`, and an unknown future id.

## T05 - Cross-runtime continuity

```task
id: WARDEN-WP-0024-T05
status: todo
priority: high
```

Ensure worker ticks see agent session episodes and vice versa.

Acceptance:

- Agent session routing outcomes appear in worker activation within the same
  store without manual export/import.
- Worker escalation outcomes are visible to subsequent agent session activations.
- Continuity is verified by an integration test: agent session write → worker
  read → agent session read round-trip.
- Episode retention follows the ops-warden profile compaction rules from
  PMEM-WP-0016.

## T06 - OpenRouter efficiency layer

```task
id: WARDEN-WP-0024-T06
status: todo
priority: medium
```

Skip or downgrade OpenRouter calls when stabilized memory provides a verified match.

Acceptance:

- When stabilized memory contains a verified route match for the message need,
  `RuleBrain` handles the plan and llm-connect is not called.
- Ambiguous cases still use `LlmConnectBrain`; memory context is additive only.
- Efficiency metrics (llm_calls_avoided, rule_brain_resolution_rate) are
  recorded for evaluation scenarios in PMEM-WP-0016.
- Dry-run mode reports whether LLM would have been skipped and why.

## T07 - Operator and agent documentation

```task
id: WARDEN-WP-0024-T07
status: todo
priority: medium
```

Document the memory workflow for operators and coding agents.

Acceptance:

- Wiki page covers: store location, session kinds, agent env vars, memory
  activation at session start, and interaction with OpenRouter inference.
- ops-warden AGENTS.md and the state-hub agent template include memory
  orientation steps for Claude, Codex, and Grok sessions.
- Credential routing doc cross-links PMEM-WP-0016 contract; anti-patterns
  updated (no secret values in memory store).
- Scheduled worker playbook notes memory retention and evaluation gate checks.

## Acceptance Criteria

- phase-memory is present and useful in all three runtime surfaces (worker,
  agent session, operator CLI) through one canonical store.
- OpenRouter inference cost decreases when stabilized routing memory matches.
- Cross-runtime continuity is tested and regression-gated.
- Security invariants (no-secret, allowlist, conduit-not-broker) are unchanged.

## Dependencies

- `PMEM-WP-0016` (phase-memory) — profile, event schema, activation pack,
  evaluation scenarios. **Implement contract (T01–T03) before WARDEN T03–T05.**
- `WARDEN-WP-0020` — worker brain and guardrails (finished).
- `WARDEN-WP-0022` — audit trail for correlation (finished).
- llm-connect / OpenRouter — required only for T06 live efficiency measurement;
  T01–T05 work offline.

## Suggested Implementation Order

1. PMEM-WP-0016 T01–T03 (profile + contract + event schema)
2. WARDEN-WP-0024 T01–T02 (store + CLI recording)
3. PMEM-WP-0016 T04 (activation pack)
4. WARDEN-WP-0024 T03–T05 (worker + agent activation + continuity)
5. PMEM-WP-0016 T05–T06 + WARDEN-WP-0024 T06–T07 (evaluation + docs)

## Closure Review

Pending implementation.