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

id, type, title, domain, repo, status, owner, topic_slug, planning_priority, planning_order, created, updated

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

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

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

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

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

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

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

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

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.