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