generated from coulomb/repo-seed
Add WARDEN-WP-0024 experiential memory and agent session workplan.
Integrate phase-memory across worker ticks, coding agent sessions, and operator CLI with shared store, OpenRouter efficiency, and unchanged guardrails.
This commit is contained in:
@@ -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<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.
|
||||||
Reference in New Issue
Block a user