diff --git a/workplans/WARDEN-WP-0024-experiential-memory-and-agent-sessions.md b/workplans/WARDEN-WP-0024-experiential-memory-and-agent-sessions.md new file mode 100644 index 0000000..76a7e6b --- /dev/null +++ b/workplans/WARDEN-WP-0024-experiential-memory-and-agent-sessions.md @@ -0,0 +1,252 @@ +--- +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
(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 ] [--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. \ No newline at end of file