From 02d6f3447bd9e9191ed5b563f64a918559418457 Mon Sep 17 00:00:00 2001 From: tegwick Date: Wed, 27 May 2026 12:50:46 +0200 Subject: [PATCH] Persist agentic memory research + create CYA-WP-0005 (profiles 0-3 + phase-memory feedback) - Persist deep research on self-improving loops (Reflexion, Generative Agents, procedural/meta-policy) as history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md - Create CYA-WP-0005 workplan (proposed): baseline current memory as Profile 0, define Profiles 1-3 mapping the three variations, with tasks for docs, optional Profile 1 spike, tests/safety, and explicit T04 for phase-memory suggestions deliverable - Add standalone sister-repo feedback doc docs/phase-memory-optimization-suggestions.md (9 prioritized categories: ports/activation, synthesis hooks, procedural support, retrieval, lifecycle, explainability, safety, observability, retrospection interop) - All per explicit 2026-05-28 request: 'Persist the research. Create a workplan to establish the current memory handling as profile 0 and add profile 1-3. For interface optimization and missing functionality in phase-memory provide optimization suggestions to the sister repo. Commit register and sync the workplan.' - Follows AGENTS.md: small inspectable change, references prior 0002/0003/0004 + MemoryVision + post-0004 gap analysis - Next: register workstream, seed IDs, make fix-consistency, progress event (self-exec per prior authorization pattern) Artifacts ready for State Hub registration and sister-repo handoff. --- docs/phase-memory-optimization-suggestions.md | 129 +++++++++ ...-CYA-Agentic-Memory-Research-Variations.md | 250 +++++++++++++++++ ...mory-profiles-and-phase-memory-feedback.md | 251 ++++++++++++++++++ 3 files changed, 630 insertions(+) create mode 100644 docs/phase-memory-optimization-suggestions.md create mode 100644 history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md create mode 100644 workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md diff --git a/docs/phase-memory-optimization-suggestions.md b/docs/phase-memory-optimization-suggestions.md new file mode 100644 index 0000000..ec4c22a --- /dev/null +++ b/docs/phase-memory-optimization-suggestions.md @@ -0,0 +1,129 @@ +# Optimization Suggestions & Missing Functionality for phase-memory + +**Date:** 2026-05-28 +**Source:** CYA-WP-0005 (Agentic Memory Profiles) + persisted research `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` +**Audience:** phase-memory / markitect owners (sister repo) +**Purpose:** Actionable, prioritized feedback from the cya consumer so that Profiles 0–3 (and the self-improving loops they enable) can be realized cleanly, safely, and with excellent user control / explainability. + +## Context (Why This Feedback Exists) + +`can-you-assist` (`cya`) is a **consumer** of the phase-memory profile-driven memory layer. After CYA-WP-0002/0003 we have a high-quality local approximation (Profile 0) behind explicit ports that already uses `profile`, `kinds`, `activation_context`, retrospection outcomes as higher-order memory, provenance, and phase hints. This delivers real directory/project-bound activation and a `cya retrospect` continuous-optimization loop today. + +To evolve to true agentic self-improving behavior we need **three progressive profiles** (defined in the research doc and CYA-WP-0005): + +- **Profile 1 (Reflexion-style verbal)**: Store and preferentially activate natural-language self-reflections / lessons (builds directly on existing retrospection kinds and `remember_retrospection_outcome`). +- **Profile 2 (Generative-Agents-style hierarchical)**: Episodic stream → LLM synthesis of abstractions (conventions, patterns) with citations → storage in stabilized phases + multi-factor retrieval. +- **Profile 3 (Procedural / meta-policy)**: First-class evolvable "how I behave" rules/procedures; meta-reflection proposes changes under strong audit + safety guardrails. + +**Profile 0 is already shipped** (local JSON + activation + retrospection). The seam (4 ports + kinds + activation_context + provenance) is deliberately stable. The suggestions below are the concrete extensions we need from phase-memory to make Profiles 1–3 natural, safe, and explainable without cya owning storage or lifecycle policy. + +All suggestions respect cya invariants: +- Memory may only **increase** caution (rule-based RiskClassifier in cya is primary; memory feeds it but never relaxes it). +- Everything is user-inspectable, exportable, and veto-able. +- Full provenance for every item (raw or synthesized). +- Dry-run / proposal semantics for any memory evolution. +- cya never bypasses explicit user confirmation for non-SAFE actions. + +## Prioritized Suggestions (9 Categories) + +### 1. Refined Port Signatures & Activation Context (Must-have for Profile 1, baseline for 2/3) +- Make `activation_context: dict[str, Any]` (cwd, git_root, task_class, recent_kinds, token_budget_hint) a first-class, documented parameter on `recall_preferences` / context-package requests (cya already prototypes this locally). +- Support `kinds: list[str]` filter + boost natively (cya has `KIND_PREFERENCE | RETROSPECTION | INTERACTION_GOAL`; will add `REFLECTION`, `SYNTHESIZED_CONVENTION`, `PROCEDURAL_RULE`, etc.). +- Return structure from recall/export must include: `items[]` with per-item provenance + phase + citations (for synthesized), `provenance[]` array, `dry_run_plan` (when relevant), `profile`, `phase_summary`. +- Add a distinct `remember_event` / `ingest_retrospection_outcome` (or keep thin wrapper) so planners receive high-quality, typed input from cya's guided reflection sessions. + +**Why**: Enables the activation boost and kind-based preferential treatment that 0003 already proved valuable, and that all three profiles rely on. + +### 2. Synthesis / Reflection Planner Hooks (Required for Profile 2, nice for 1) +- Expose (or allow cya to request) a "run_reflection_pass(profile, scope, recent_memories, budget)" that returns proposed abstractions with citations, confidence, and suggested phase (fluid/stabilized). +- Dry-run first: every synthesis returns a proposal object (before any write) that cya can present to the user for review/edit/approve ("phase-memory proposes 4 stabilized conventions from your last 12 sessions — accept?"). +- Recursive / hierarchical synthesis support (reflections on reflections) with citation chains. + +**Why**: Directly implements the Generative-Agents reflection module and the "retrospection outputs as higher-order memory" model from 0003. + +### 3. First-Class Procedural / Meta-Policy Support (Required for Profile 3) +- Dedicated collection or `kind` namespace for procedural items (`procedural_rule`, `meta_policy`, `explanation_strategy`, `safety_tuning`). +- Policy-evolution planner: input = recent outcomes + current procedural set + safety incidents; output = structured patch proposal + safety-impact analysis ("this change tightens risk posture on destructive commands"). +- Guardrail primitives that the PolicyGateway can enforce: "procedural changes may not relax risk classification without explicit user + operator override." + +**Why**: Highest-leverage self-improvement layer (the assistant gets better at *being* an assistant). Highest risk if uncontrolled — needs the strongest dry-run + veto UX. + +### 4. Activation & Multi-Factor Retrieval (Strong for 1 & 2, essential for 3) +- Configurable composite scoring for retrieval: recency (decay), importance (LLM-inferred or user-pinned), relevance (to current activation_context or query), phase_weight, kind_boost. +- Profile can declare defaults ("for terminal assistance in Rust projects, weight retrospection + procedural at 2.0"). +- cya can request "context package for a console turn, max 4k tokens, prioritize X kinds, under profile Y" and receive a planned package + explanation. + +**Why**: Replaces cya's current simple boost logic with something phase-memory can optimize consistently across consumers. + +### 5. Lifecycle, Phase Transitions & Compaction (Baseline for all profiles) +- Explicit phase-transition proposals (fluid → stabilized → rigid) with human-readable diffs and citation back to source memories. +- Compaction / eviction planner with dry-run + rationale ("these 17 near-duplicate reflections can be merged into 3; confidence 0.85"). +- TTL, review_date, last_used on items; cya can surface "this convention has not been reviewed in 90 days — re-validate in retrospect?" + +**Why**: Realizes the ephemeral/fluid/stabilized/rigid model in MemoryVision and prevents unbounded growth while keeping user in control. + +### 6. Explainability & Audit (Non-negotiable for all profiles) +- Every memory item (raw, synthesized, or procedural) carries machine-readable + human-readable provenance: source memories, reflection prompt id or planner id, timestamps, author (user vs system), last review. +- Structured "memory influence" objects that cya can render directly in `--explain-context` and final responses without fragile parsing. +- Full export of a profile/scope includes the procedural rule set, recent synthesis activity, and token budget accounting by phase. + +**Why**: Matches cya's core promise ("I can see exactly what it knows and why it used it") and is required for user trust when the system starts synthesizing and evolving its own behavior. + +### 7. Safety & Policy Integration (Critical for 2 & 3) +- Memory evolution operations declare safety impact: none / tightens / potentially relaxes. +- Hook or query so cya's rule-based RiskClassifier can consult memory policy / procedural rules before activation (or to inject forced-confirmation signals). +- "Memory evolution veto mode" (per-profile or global): all proposals require explicit approval; no auto-stabilization or auto-procedural changes. +- Rollback / versioning for the procedural layer itself (user can say "revert to the rules from 2026-05-20"). + +**Why**: Preserves the hard invariant that memory never weakens safety. Procedural evolution is powerful but must never become a covert policy bypass. + +### 8. Observability & Introspection (Strongly desired for 1–3) +- Profile/scope introspection endpoint that returns: active procedural rules (with provenance), recent synthesis activity + citations, token usage by phase/kind, items nearing review or compaction. +- Event log query so cya can answer "show me the memory events that caused this preference to be activated." +- Cost / token / LLM-call accounting surfaced per recall or synthesis request (helps users understand the price of richer memory). + +**Why**: Makes the self-improving loop transparent and debuggable from the terminal. + +### 9. Retrospection / Continuous Optimization Interop (Direct enabler for 1 + foundation for 2/3) +- Standard event schema or ingestion path for "retrospection session completed" (with captured goals, interaction_goals, reflections, explicit stabilization decisions) that phase-memory planners consume natively. +- cya can tag a retrospection outcome as "high-importance for stabilization" or "candidate for procedural rule extraction." +- Planners can propose "based on 3 recent retrospections in this project, I recommend promoting these 2 patterns to stabilized + adding 1 procedural rule — review?" + +**Why**: `cya retrospect` (0003) is already the highest-quality way new, user-vetted memory enters the system. phase-memory should treat it as privileged input rather than generic events. + +## Handoff Notes for phase-memory / markitect + +- **Reference artifacts** (please read in this order): + 1. MemoryVision.md (especially the 0002 T01 integration contract with refined port signatures, phases, primary kinds, profile-driven behavior examples, safety/explainability requirements). + 2. `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` (full research + the three profile definitions + cya-specific mappings). + 3. `docs/cya-memory-activation-and-retrospection-concept.md` (0003 T01 — the activation layers + retrospection-as-higher-order-memory model that Profiles 1–3 build on). + 4. CYA-WP-0005 (this workplan) — tasks T01–T04 are the direct consumers of the feedback. + 5. Current cya port implementation: `src/cya/memory/__init__.py` (Profile 0; the signatures and return shapes we want to keep stable or evolve in place). + +- **Coordination channel**: State Hub (topic 64418556-3206-457a-ba29-6884b5b12cf3 for can-you-assist / capabilities domain). Workstream for CYA-WP-0005 will be registered. Progress events and decisions will be posted there. Direct messages or shared docs also fine. + +- **Prioritization guidance**: + - Items in categories 1, 6, 7 are **foundational** — they protect user control, explainability, and safety even for Profile 0 today. + - Categories 2, 4, 5, 9 enable Profile 1 + 2 with high leverage. + - Category 3 + strong guardrails in 7 are the big unlock (and biggest risk) for Profile 3. + - Observability (8) makes the whole story usable and debuggable. + +- **Non-requests (for clarity)**: We are not asking phase-memory to own the cya CLI, the rule-based risk classifier, or terminal-specific prompting. We want the memory operating layer (profiles, planners, phases, graph/event store, policy) to be excellent so cya can be a thin, safe, highly-explainable consumer. + +## Success Criteria (from cya perspective) + +phase-memory + these suggestions are successful when a cya user can say: +- "I ran `cya retrospect`, captured three lessons, and now the assistant reliably surfaces the right one in this project — and I can see exactly why." +- "phase-memory proposed stabilizing four patterns from my last month of work; I reviewed the citations and accepted two. The assistant now behaves differently and I know why." +- "I defined a procedural rule for how I like Rust error handling explained. The assistant follows it, and when it suggested changing the rule it showed me the safety impact and asked for approval." +- "I exported my memory for project X, saw the procedural layer and the synthesis history, and deleted two items. The assistant respected it immediately." + +These map directly to the long-term success criteria already in MemoryVision.md. + +--- + +**Document status**: Living feedback artifact. Will be updated in CYA-WP-0005 T04 (polish + extraction) and as we learn more during profile implementation spikes. Please treat the numbered categories above as the actionable input for planning and interface design in phase-memory. + +**Contact / next step**: After CYA-WP-0005 T04/T08 complete (workplan registered + suggestions doc finalized), the cya side will open a State Hub coordination message or workstream handoff with this doc + the research + MemoryVision contract attached. + +Thank you — the profile model and self-improving loops are only as good as the memory operating system they run on. We are excited to collaborate on making phase-memory the excellent, user-controlled foundation for the whole ecosystem. \ No newline at end of file diff --git a/history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md b/history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md new file mode 100644 index 0000000..68c1908 --- /dev/null +++ b/history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md @@ -0,0 +1,250 @@ +# Agentic Memory & Self-Improving Loops: Research Synthesis and Three Variations for can-you-assist + +**Date:** 2026-05-28 +**Context:** Post CYA-WP-0004 (packaging), during planning for memory profile evolution (CYA-WP-0005) +**Related:** MemoryVision.md, docs/cya-memory-activation-and-retrospection-concept.md, CYA-WP-0002/0003, history/2026-05-28-CYA-Intent-Scope-Gap-Analysis-Post-0004.md, phase-memory (sister repo) +**Author:** Grok (research + synthesis for cya) + +## Executive Summary + +Deep research into agentic memory architectures for LLM agents reveals mature patterns for **closed self-improving loops**: Trial/Interaction → Evaluation/Feedback (success/failure signals, user outcomes) → Reflection/Synthesis/Critique (verbal or structured) → Memory Update/Consolidation (store abstractions, rules, or critiques) → Improved future behavior via retrieval/activation. + +Key exemplars: +- **Reflexion (Shinn et al., NeurIPS 2023)**: Verbal reinforcement via stored self-reflections. Dramatic gains with minimal infra. +- **Generative Agents (Park et al., SIGGRAPH 2023)**: Memory stream + LLM-powered reflection module synthesizing abstractions + multi-factor scored retrieval. +- **Procedural / Meta-policy evolution** (LangMem, A-Mem, LEGOMem patterns): Agents dynamically rewrite their own high-level rules, procedures, or system instructions based on experience. + +These map cleanly to cya's existing foundation (post-0003: real JSON memory with `kinds`, `activation_context`, retrospection outcomes as higher-order memory, directory/project scoping, provenance, safety integration, `cya retrospect` guided loop) and the phase-memory vision (phases: ephemeral/fluid/stabilized/rigid; profile-driven planners; explicit ports). + +**Recommendation for cya**: Establish current (post-0003 local JSON + activation + retrospection) as explicit **Profile 0** baseline. Then implement **Profiles 1–3** incrementally, each adding one dimension of agentic self-improvement while preserving non-negotiables: user control/inspectability, explainability (provenance + `--explain-context`), rule-based safety (memory never downgrades risk or bypasses confirmation), and the cya/phase-memory boundary (cya consumes; phase-memory owns storage/lifecycle/planners). + +This document persists the research and directly feeds CYA-WP-0005 (profile definitions + phase-memory interface feedback). + +## Research Sources & Core Patterns + +### Reflexion (Shinn et al. 2023) +- Core idea: After each trial (e.g., code gen + test feedback, or assistant suggestion + user outcome), the agent generates a **natural-language self-reflection** ("what went wrong / what should I remember for next time?") using the LLM itself. +- Store these reflections in an **episodic memory buffer** (list of (trajectory, reflection, outcome)). +- On next similar task: prepend the most relevant past reflections + trajectories to the prompt. +- Feedback sources flexible: unit tests, environment rewards, human critique, or (in cya) explicit user "accept / revise / reject" + retrospection. +- Results (paper): +11–34% absolute gains on HumanEval / HotpotQA / AlfWorld with GPT-4 / Claude-1; works with open models too. +- Key properties: **lightweight** (no fine-tuning, no embeddings required for MVP), **highly explainable** (reflections are human-readable English), **verbal reinforcement learning**. +- Limitations: Can accumulate noise if reflections are low-quality; needs good relevance filtering or recency/importance scoring. + +**Primary citation**: Shinn et al., "Reflexion: Language Agents with Verbal Reinforcement Learning", https://arxiv.org/abs/2303.11366 (NeurIPS 2023). Additional analysis: Lilian Weng "LLM Powered Autonomous Agents" (https://lilianweng.github.io/posts/2023-06-23-agent/), LangChain Reflexion tutorial. + +### Generative Agents (Park et al. 2023) +- **Memory stream**: All experiences stored as natural-language "memory objects" (timestamped observations, actions, thoughts). +- **Reflection module** (periodic, often at night or low-load): LLM is prompted to generate questions about recent memories, then synthesize **high-level abstractions** (e.g., "I prefer concise git status output and always want alternatives listed") with citations back to source memories. Recursive: reflections can themselves be reflected upon → hierarchy. +- **Retrieval**: For a new situation, score every memory by a composite: + - Recency (exponential decay) + - Importance (LLM infers 1–10 saliency for the agent) + - Relevance (embedding cosine similarity to current context/query) +- Retrieved memories + top reflections fed into planning / action. +- Used to drive believable agents in a Sims-like sandbox (25 agents, 2 weeks simulated). +- Strengths: Produces **rich, human-interpretable** higher-order knowledge; natural hierarchy aligns with phase-memory's fluid→stabilized→rigid phases. +- Cost: More LLM calls for synthesis; needs embedding store or smart sampling for scale. + +**Primary citation**: Park et al., "Generative Agents: Interactive Simulacra of Human Behavior", https://arxiv.org/abs/2304.03442 (SIGGRAPH 2023). Excellent overview in Lilian Weng post above. + +### Procedural Memory & Meta-Policy Evolution (LangMem, A-Mem, LEGOMem, MemGPT patterns) +- **Procedural memory**: Not "what happened" or "what I prefer", but **"how I should behave / what procedure to follow"**. + - LangMem (LangChain): Three stores — episodic (events), semantic (facts), **procedural** (evolving instructions / system prompts / rules the agent rewrites for itself). + - Agents observe outcomes, run "meta-reflection", and propose patches to their own high-level policy or few-shot examples. +- **A-Mem (Agentic Memory)**: Dynamic graph where memories are nodes with auto-generated keywords/tags/context; agents autonomously evolve the graph structure and connections over time. No fixed schema. +- **LEGOMem**: Procedural memory specifically for reusable workflows / "recipes" (e.g., "when debugging a failing test in this project: run X, inspect Y, propose minimal patch"). +- **MemGPT**: OS-inspired virtual context management — "main context" (RAM), recall (disk), archival (cold store); paging + function calls to manage what is in the LLM window. Hierarchical + procedural control. +- Common thread: The agent treats its own **operating policy / instructions / strategies** as first-class mutable memory that improves via experience. +- Highest upside for self-improvement (the system literally gets "smarter at being an assistant" rather than just knowing more facts). +- Highest risk: Uncontrolled policy drift, safety regressions, user surprise ("why did it start doing X differently?"). + +**Key references**: +- LangMem: https://blog.langchain.dev/langmem-building-production-ready-agents-with-long-term-memory/ and docs. +- A-Mem: https://arxiv.org/abs/2409.16166 (autonomous memory evolution). +- MemGPT: https://arxiv.org/abs/2310.08560. +- Lilian Weng survey (covers procedural aspects). + +### Cross-Cutting Architectural Patterns +- **Episodic stream** (time-stamped records) scored by recency/importance/relevance + activation context (directory, project, task class). +- **Reflection / synthesis** as a distinct, often offline or user-triggered step (natural fit for `cya retrospect`). +- **Hierarchical / phased storage**: raw events → summaries → abstractions → rigid core (aligns perfectly with phase-memory phases). +- **Procedural layer** on top: meta-rules that govern retrieval, synthesis thresholds, safety posture, explanation style, etc. +- **Provenance + audit everywhere**: every synthesized item cites sources; every activation explains why. +- **Dry-run / proposal semantics** for any memory evolution (user veto before commit). +- **Safety firewall**: memory-derived signals can only **increase** caution (cya RiskClassifier invariant). + +## Three Variations for cya + phase-memory + +These are ordered by increasing agentic power and implementation cost. All preserve cya's core contract (user-controlled, explainable, safety-first, explicit seam to phase-memory). + +### Variation 1: Reflexion-Style Verbal Self-Improvement Loop (Profile 1 candidate) +**Core loop**: +1. Normal assistance (memory activated via current 0003 activation_context + kinds). +2. Outcome capture: user accepts/revises/rejects, or runs `cya retrospect`. +3. Verbal reflection: LLM (or guided prompt) produces 1–3 concise "lessons" in natural language, e.g. "In this Rust project the user always wants `cargo clippy` before suggesting fixes; remember to surface that early." +4. Store via `remember_retrospection_outcome` (or new `remember_reflection`) with `kind="reflection"` or `kind="verbal_lesson"`. +5. Future recall: boost `kinds=["reflection", "retrospection", "interaction_goal"]` + activation_context match; prepend top-N to context envelope (high salience). +6. Explainability: surface "3 verbal reflections from prior sessions in this project influenced this suggestion" + the actual text in `--explain-context`. + +**cya mapping (builds directly on 0003)**: +- Existing `KIND_RETROSPECTION` + `remember_retrospection_outcome` + `cya retrospect` flow is ~80% of the infrastructure. +- Add a lightweight "capture lesson" step at end of retrospect (or auto after notable interactions). +- New `kind` values + filter support already in ports. +- Preferential activation for reflection kinds (small change to current boost logic). +- Safety: reflections that touch risky patterns still route through RiskClassifier. + +**Pros**: Lowest infra cost, maximum explainability (plain English), immediate value, fits terminal workflow perfectly. +**Cons**: Reflections can be noisy or contradictory without synthesis (addressed in Var 2). +**Phase-memory fit**: Minimal new requirements — just good support for `kind` filtering + provenance on recall. Later: a "reflection planner" that can suggest compaction of duplicate lessons. + +**See also**: Shinn paper, current `docs/cya-memory-activation-and-retrospection-concept.md` (retrospection outputs as higher-order memory). + +### Variation 2: Generative-Agents-Style Hierarchical Memory Stream + Synthesis (Profile 2 candidate) +**Core loop**: +1. Episodic capture: every assistance turn, outcome, retrospection, explicit remember → structured memory record (timestamp, kind, scope, activation_context, raw text or structured payload, provenance). +2. Periodic synthesis (user-triggered via `cya retrospect --synthesize`, or background/low-load, or phase-memory planner): LLM clusters recent fluid memories for the scope/profile, generates abstractions (preferences, project conventions, recurring workflows, "in this repo we always..."), with citations. +3. Store synthesized items with higher phase hint ("stabilized") and new kinds (e.g. `KIND_SYNTHESIZED_CONVENTION`, `KIND_PROJECT_PATTERN`). +4. Retrieval/activation: multi-factor scoring (recency + explicit importance + relevance to current cwd/git/task_class + profile match) + the existing activation_context boost. +5. Hierarchy: raw retrospection → synthesized convention → (later) higher-order "this user values X across all projects". +6. Compaction: phase-memory (or cya helper) can propose merging/evicting with dry-run + user review. + +**cya mapping**: +- Current local JSON can serve as the episodic stream (already has ts, scope, kind, profile, value). +- `export_memory` + `recall_preferences(..., activation_context=...)` already return provenance. +- Orchestrator already injects activated memory into ContextEnvelope. +- Extend retrospect flow to offer "synthesize patterns from recent sessions" as an explicit user choice. +- Add simple importance scoring (LLM call or heuristic) on remember. +- Wire synthesized items back through the same recall path (they just have different kinds/phases). + +**Pros**: Richer longitudinal value, directly realizes MemoryVision "Project / Directory Memory" + "Workflow Recipes", natural fit for phase-memory's phases and planners. +**Cons**: More LLM calls (synthesis cost); requires good citation tracking to keep explainability. +**Phase-memory fit**: Strong alignment. phase-memory should expose: +- Synthesis / reflection planner entrypoint (or allow cya to request "run reflection pass for this profile/scope"). +- Structured memory objects with citation/provenance fields. +- Phase transition proposals (fluid → stabilized) with dry-run. +- Multi-factor retrieval API that cya can parameterize (recency weight, importance weight, relevance query). + +**See also**: Park paper, MemoryVision phases + "profile-driven behavior" section, 0003 activation layers. + +### Variation 3: Procedural / Meta-Policy Evolution (Profile 3 candidate — aspirational) +**Core loop**: +1. Base behavior defined by a small set of **first-class procedural memory items** (kinds: `procedural_rule`, `meta_policy`, `explanation_strategy`, `safety_tuning`). + - Example: "When user is in a Rust project with recent compilation errors, always surface `cargo check` output early and propose minimal patches before broad refactors." +2. Meta-reflection (triggered after retrospection, or on explicit "improve my assistant rules"): LLM reviews recent outcomes + current procedural rules + safety incidents, proposes **patches or new rules**. +3. Proposal + audit: phase-memory (or cya) presents the diff ("+1 procedural rule, -0, changed confidence on 2") in human review form; user can edit/approve/veto. +4. On approval: the new rule is stored with high phase/stability and becomes part of future activation / prompt construction / risk hints. +5. Guardrails: all procedural changes are **additive or tightening only** by default (never relax safety without explicit user action); every rule carries provenance + last-review date; cya RiskClassifier treats procedural memory as a strong "force confirmation" signal source. + +**cya mapping**: +- New dedicated kinds + a `remember_procedural_rule` helper (thin wrapper). +- A new `cya improve-rules` or extension to `retrospect` that runs the meta-reflection. +- Orchestrator / safety layer reads procedural items with highest priority for injection (system prompt augmentation or risk context). +- Export/inspect must make procedural layer very prominent ("these 7 rules govern how I behave for you in this project"). +- Strong integration with the existing rule-based RiskClassifier (procedural memory can only raise the assessed risk level). + +**Pros**: Highest self-improvement leverage — the assistant literally gets better at *being an assistant* for this user. +**Cons**: Highest risk of drift or unintended behavior; requires the strongest audit, veto, and rollback UX. +**Phase-memory fit** (most demanding): +- First-class **procedural memory** kind + dedicated planner (policy evolution planner). +- Proposal / diff semantics for memory changes (dry-run + structured review objects). +- Explicit hooks for "meta-reflection" passes that cya can invoke with bounded context. +- Safety / policy gateway that can enforce "procedural changes may not weaken risk posture without user override". +- Versioning / rollback for the procedural layer itself. +- Profile can declare "aggressiveness of self-evolution" (conservative / balanced / bold) with corresponding planner behavior. + +**See also**: LangMem procedural store, A-Mem autonomous evolution, LEGOMem workflow recipes, safety invariants in cya's classifier.py (T04 0002). + +## Profile 0 Baseline (Current Post-0003 Reality) + +Before defining 1–3, the workplan must explicitly document and stabilize **Profile 0** as the shipped baseline so future profiles have a clear "from here" point. + +**Exact current implementation** (as of post-0003 + 0004): +- Backing: user-controlled `~/.config/cya/memory/.json` (list of records). Inspectable, editable, deletable by user. No hidden state. +- Ports (src/cya/memory/__init__.py): + - `KIND_PREFERENCE`, `KIND_RETROSPECTION`, `KIND_INTERACTION_GOAL` + - `remember_preference(key, value, scope="cwd", *, profile=None, ttl=None, kind=KIND_PREFERENCE)` + - `recall_preferences(scope="cwd", task_class=None, *, kinds=None, profile=None, limit=50, activation_context=None)` → returns items + rich provenance + phase hint + note about local json + - `forget(scope, keys=None, *, profile=None)` + - `export_memory(scope, *, profile=None, kinds=None)` → includes `by_kind` counts, provenance_summary, phases list + - `remember_retrospection_outcome(...)` convenience (sets kind automatically) +- Activation (0003): simple but effective boost — items whose scope/profile match `activation_context` (populated by ContextEnvelope with cwd + git_root) are moved to front of results. Wired in orchestrator.py for every assistance request + `--explain-context` panel. +- Retrospection (0003): `cya retrospect` subcommand (guided questions, review recent memory usage, capture goals → stored as first-class retrospection records with preferential future activation). +- Safety integration (unchanged invariant): memory signals only append rationale or force confirmation in RiskClassifier; never downgrade risk level or bypass mandatory confirmation. +- Observability: `--explain-context` surfaces activated memory items, provenance, phase, activation reason. +- Explainability: every recall/export carries "source: cya-local-memory-json (T02+0003; activation + retrospection support)". +- Limitations (intentional): no embeddings, no synthesis, no procedural layer, no phase transitions, local only (no graph/event store), no profile execution planner yet. + +This is deliberately a **high-quality local approximation** that delivers real user value today (contextual activation + continuous optimization loop via retrospect) while keeping the seam (profile/kind/activation_context parameters) ready for replacement by full phase-memory. + +**Profile 0 success criteria** (for 0005 T0x): The above is clearly documented in MemoryVision.md (add "What CYA-WP-0003 Delivered" + "Profile 0 Baseline" sections), tests cover kinds + activation_context + retrospection roundtrips, README/AGENTS mention the current loop, and the new workplan treats it as the stable starting point for 1–3. + +## Recommendations & Next Steps (for CYA-WP-0005) + +1. **Persist this research** (this document) and reference it from the workplan. +2. Create CYA-WP-0005 with tasks for: + - Formalize Profile 0 baseline (update MemoryVision, SCOPE, code comments, tests). + - Define + implement Profile 1 (Reflexion verbal) as small delta on existing retrospect/kinds machinery. + - Profile 2 skeleton (episodic capture + synthesis entrypoint + hierarchical kinds). + - Profile 3 exploration spike (procedural kind + proposal UX, strong guardrails). + - Standalone or section "Optimization Suggestions & Missing Functionality for phase-memory" (see below). + - Update docs, examples, MemoryVision with profile matrix. + - Register workplan, commit, sync via fix-consistency. +3. **Do not** start full implementation of 1–3 until the workplan is reviewed and activated (per AGENTS convention). + +## Optimization Suggestions & Missing Functionality for phase-memory (Sister Repo) + +(This section is the direct input for the "provide optimization suggestions to the sister repo" part of the request. It will be extracted or expanded as a deliverable in 0005.) + +**High-priority interface / contract improvements** (to make Profiles 1–3 natural): + +1. **Refined / extended port signatures** (build on the CYA-WP-0002 T01 contract already in MemoryVision): + - Add `activation_context: dict` (cwd, git_root, task_class, recent_kinds) as first-class param to recall (already prototyped in cya local). + - Support `kinds: list[str]` filter/boost in recall (already in cya; make phase-memory native). + - Return richer `provenance` + `dry_run_plan` + `phase` + `synthesis_citations` in recall/export results. + - Add `remember_event(...)` or `ingest_retrospection_outcome(...)` as distinct from generic remember (for planner input). + +2. **Synthesis / Reflection planner hooks**: + - Expose (or allow cya to request) a "run_reflection_pass(profile, scope, recent_memories)" that returns proposed abstractions with citations and confidence. + - Dry-run semantics for all synthesis proposals (cya can present "phase-memory proposes these 4 stabilized conventions — review?"). + +3. **First-class procedural / meta-policy support** (for Profile 3): + - Dedicated `kind` values or a separate `procedural_rules` collection. + - Policy evolution planner: input = recent outcomes + current rules; output = proposed patches + impact analysis (esp. safety impact). + - Guardrail primitives: "this change may not relax risk posture" that the PolicyGateway can enforce. + +4. **Activation & retrieval enhancements**: + - Multi-factor scoring API (recency, importance, relevance, user_pinned, phase_weight) that cya can parameterize per request or per profile. + - Profile-aware activation requests: cya says "give me a context package for a terminal assistance turn in this cwd under profile X, budget 4k tokens, prioritize retrospection + procedural kinds". + +5. **Lifecycle & phase management**: + - Explicit phase transition proposals (fluid → stabilized) with user-reviewable diffs. + - Compaction / eviction planner with dry-run + rationale. + - TTL + review_date on memory items (cya can surface "this convention has not been reviewed in 90 days"). + +6. **Explainability & audit**: + - Every returned memory item (raw or synthesized) must carry machine + human readable provenance (source memories, reflection prompt id, timestamp, author). + - Structured "memory influence" objects that cya can render cleanly in `--explain-context` and final output without custom parsing. + +7. **Safety & policy integration**: + - Memory evolution operations must be able to declare "safety impact: none / tightens / potentially relaxes". + - Hook for cya's rule-based RiskClassifier to consult memory policy before activation (or to inject forced-confirmation signals from procedural rules). + - User-level "memory evolution veto mode" (all proposals require explicit approval; no auto-stabilization). + +8. **Observability & introspection**: + - `export_memory` / profile introspection that includes "active procedural rules", "recent synthesis activity", "token budget usage by phase". + - Event log query API so cya can show "memory events that led to this activated preference". + +9. **Retrospection / continuous optimization interop**: + - Standard event schema for "retrospection session completed" that phase-memory planners can consume directly. + - Ability for cya to say "this retrospection outcome should be treated as high-importance for stabilization". + +**Non-goals for near-term phase-memory feedback**: full embedding/semantic index details, voice, cross-user sharing, production scale numbers. Focus on the **profile + planner + procedural + dry-run proposal** surface that lets cya deliver the three self-improving variations safely and explainably. + +These suggestions will be turned into a clean, reviewable artifact (standalone doc or PR-ready section) in CYA-WP-0005 and shared with the phase-memory / markitect owners via State Hub or direct coordination. + +--- + +**End of persisted research document.** +This artifact, together with the three gap analyses in history/, MemoryVision.md, and the activation concept doc, forms the knowledge base for CYA-WP-0005. + +Next: Create the workplan that turns this research into executable tasks (profile 0 baseline + 1–3 + phase-memory feedback deliverable). \ No newline at end of file diff --git a/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md new file mode 100644 index 0000000..c6a9737 --- /dev/null +++ b/workplans/CYA-WP-0005-agentic-memory-profiles-and-phase-memory-feedback.md @@ -0,0 +1,251 @@ +--- +id: CYA-WP-0005 +type: workplan +title: "Agentic Memory Profiles (0–3) and phase-memory Interface Optimization" +domain: capabilities +repo: can-you-assist +status: proposed +owner: grok +topic_slug: foerster-capabilities +created: "2026-05-28" +updated: "2026-05-28" +state_hub_workstream_id: "" +--- + +# CYA-WP-0005: Agentic Memory Profiles (0–3) and phase-memory Interface Optimization + +## Goal + +Establish the **current memory handling** (post-CYA-WP-0003 real JSON + contextual activation + retrospection outcomes + kinds + activation_context ports) as explicit **Profile 0** baseline, then define and plan **Profiles 1–3** that progressively add agentic self-improving loop capabilities: + +- **Profile 1 (Reflexion-style verbal)**: Leverage and extend the existing `cya retrospect` + `KIND_RETROSPECTION` machinery to store and preferentially activate verbal self-reflections / lessons. +- **Profile 2 (Generative-Agents-style hierarchical synthesis)**: Episodic capture → periodic LLM synthesis of higher-order abstractions (conventions, patterns, strategies) stored with phase hints and citations. +- **Profile 3 (Procedural / meta-policy evolution)**: First-class evolvable "how I behave" rules and procedures, with meta-reflection proposing changes under strong user audit and safety guardrails. + +As a first-class deliverable, produce concrete, actionable **optimization suggestions and missing functionality feedback** for the `phase-memory` sister repo (markitect domain) so that the profile model and self-improving loops can be realized with clean boundaries, dry-run safety, and excellent explainability. + +All work preserves cya's non-negotiable invariants: user-controlled & inspectable memory, full provenance/explainability (via `--explain-context` and export), rule-based safety (memory signals may only increase caution; never downgrade risk or bypass confirmation), and the explicit cya/phase-memory seam (cya is consumer; phase-memory owns storage, lifecycle planners, and profile execution). + +## Background & References + +- **Research foundation**: `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` (persisted 2026-05-28) — deep synthesis of Reflexion (Shinn 2023), Generative Agents (Park 2023), procedural/meta-policy patterns (LangMem, A-Mem, LEGOMem, MemGPT), cross-cutting architectures, and direct mappings to cya + phase-memory. +- **Current baseline (Profile 0)**: Post-0003 implementation in `src/cya/memory/__init__.py` (real persisting JSON with kinds, activation_context, remember_retrospection_outcome, by_kind export, provenance), wired in `orchestrator.py`, `cli/`, and risk classifier. See also `docs/cya-memory-activation-and-retrospection-concept.md` (0003 T01) and MemoryVision.md integration contract. +- **Gap context**: `history/2026-05-28-CYA-Intent-Scope-Gap-Analysis-Post-0004.md` shows memory & longitudinal adaptation moved from "large" to "small-medium" thanks to 0003; deeper agentic/self-improving behavior and full phase-memory integration remain the next frontier. +- **Vision alignment**: MemoryVision.md (profile-driven behavior, phases, primary kinds, safety/explainability requirements, refined port signatures from 0002 T01 contract), INTENT.md ("Personalized Console Helper" that improves over time via user-steerable memory), SCOPE.md (post-0004 delivered: contextual activation + `cya retrospect` continuous optimization loop). +- **Prior workplans**: 0002 (memory ports + real JSON), 0003 (activation + retrospection loops), 0004 (packaging — retired). 0001 (MVP foundation). +- **Sister repo**: phase-memory (profile execution, phases: ephemeral/fluid/stabilized/rigid, planners for lifecycle/activation/compaction/synthesis, MemoryGraphStore/EventLog/PolicyGateway ports, Markitect interop). cya must provide clear, prioritized feedback on what it needs from that layer. + +This workplan turns the research into an executable, reviewable plan while keeping the first slice deliberately scoped (baseline + definitions + high-quality feedback artifact + minimal Profile 1 skeleton if capacity allows). + +## Non-Goals (for this workplan) + +- Full implementation of Profiles 2 and 3 (spikes / design only; implementation may be later slices or owned by phase-memory). +- Automatic / background synthesis or meta-reflection without explicit user trigger or dry-run review. +- Changes to the rule-based RiskClassifier safety core (memory influence remains strictly additive for caution). +- Deep embedding / semantic index work (phase-memory concern). +- PyPI release or CI automation (already registered as debt in 0004). +- Activation of this workplan or ralph-loop execution (create proposed, register, sync; activation is a later operator decision). + +## Task Breakdown + +### T01 — Persist research and establish shared vocabulary + +```task +id: CYA-WP-0005-T01 +status: todo +priority: high +state_hub_task_id: "" +``` + +**Description**: Ensure the deep agentic memory research is first-class and referenceable. Create (or confirm) the persisted research document and add a short "Agentic Memory Research" section to MemoryVision.md that introduces the three profile directions with links. + +**Acceptance criteria**: +- `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` exists, is complete, and contains the three variations, cya mappings, Profile 0 baseline description, and phase-memory suggestions (already produced in pre-workplan step). +- MemoryVision.md gains a clear "Research Foundation & Profile Directions (2026-05)" section (or equivalent) that references the history doc and the three variations. +- No duplication of long research text in MemoryVision — it points to the history artifact. + +**Deliverables**: Updated MemoryVision.md (small additive section), confirmation that research doc is committed. + +### T02 — Formalize Profile 0 as the explicit shipped baseline + +```task +id: CYA-WP-0005-T02 +status: todo +priority: high +state_hub_task_id: "" +``` + +**Description**: Treat the current post-0003 memory implementation (local JSON, kinds, activation_context, retrospection helper, provenance, safety integration, `cya retrospect`) as **Profile 0**. Document it clearly so Profiles 1–3 have a stable "from here" point. Update all relevant docs and code headers. + +**Acceptance criteria**: +- MemoryVision.md contains a new "Profile 0 Baseline (Post-0003)" section that exactly describes the current ports, backing store, activation logic, retrospection flow, safety invariants, and explainability surface (pull from research doc + src/cya/memory + orchestrator). +- SCOPE.md "Current Delivered Scope" and "Integrates With" sections are updated to name "Profile 0 (contextual activation + retrospection loop on local JSON)" as delivered capability. +- `src/cya/memory/__init__.py` and `orchestrator.py` gain short header comments: "Profile 0 implementation — see CYA-WP-0005 and MemoryVision for evolution to 1–3." +- Tests (test_memory.py) explicitly assert Profile 0 behaviors (kinds, activation_context boost, retrospection roundtrip, by_kind export, provenance in results). +- README and AGENTS.md mention "Current memory profile: 0 (real contextual + retrospection; Profiles 1–3 planned)" with link to the workplan. + +**Deliverables**: Updated MemoryVision, SCOPE, source headers, tests, README/AGENTS. Clear, testable definition of Profile 0. + +### T03 — Define Profiles 1–3 with cya-specific integration plans + +```task +id: CYA-WP-0005-T03 +status: todo +priority: high +state_hub_task_id: "" +``` + +**Description**: Turn the research synthesis into concrete profile definitions, each with: intent, core loop, mapping to existing cya ports/kinds/orchestrator/retrospect/risk, delta required, phase-memory dependencies, safety/explainability notes, and acceptance criteria sketch. Include a simple profile selection / capability matrix. + +**Acceptance criteria**: +- MemoryVision.md (or a new `docs/memory-profiles.md`) contains crisp definitions for Profiles 1 (Reflexion verbal self-improvement), 2 (hierarchical synthesis), 3 (procedural/meta-policy), each with the elements above and direct references to the 2026-05-28 research doc. +- Workplan itself contains the same definitions in an appendix or "Profile Definitions" section for standalone readability. +- A one-page "Profile Capability Matrix" (table) shows for each profile: primary new kinds, activation enhancements, synthesis needs, procedural support, user control surface, safety impact, estimated implementation cost for cya vs phase-memory. +- No implementation code yet (except minimal scaffolding if it falls out of T04); definitions and docs only for this task. + +**Deliverables**: Rich profile definitions in MemoryVision + workplan, capability matrix, clear handoff points for phase-memory. + +### T04 — Produce Optimization Suggestions & Missing Functionality feedback for phase-memory + +```task +id: CYA-WP-0005-T04 +status: todo +priority: high +state_hub_task_id: "" +``` + +**Description**: Extract, polish, and package the "Optimization Suggestions & Missing Functionality for phase-memory" content (already drafted in the research doc) into a clean, reviewable, sister-repo-targeted deliverable. This is one of the primary outputs of the workplan. + +**Acceptance criteria**: +- A focused artifact exists: `docs/phase-memory-optimization-suggestions.md` (or `history/2026-05-28-CYA-phase-memory-Feedback.md`) containing prioritized, actionable items in the 9 categories from the research (refined ports, synthesis/planner hooks, procedural support, activation/retrieval, lifecycle/phase, explainability/audit, safety/policy integration, observability, retrospection interop). +- Each item states: what cya needs, why (which profile or invariant it enables), suggested interface shape or behavior, and priority (must-have for Profile 1, nice for 2, required for 3). +- The document is written for phase-memory / markitect owners (clear, non-cya-centric language where possible, references the MemoryVision contract). +- Workplan and MemoryVision reference the feedback doc as the official coordination artifact. +- (Optional but recommended) A short summary table or "Top 5 asks" is included for quick reading in State Hub messages or cross-repo sync. + +**Deliverables**: Standalone, high-quality feedback document ready for handoff to the phase-memory team. This directly fulfills the user request "For interface optimization and missing functionality in phase-memory provide optimization suggestions to the sister repo." + +### T05 — Minimal Profile 1 implementation spike (Reflexion verbal) — optional but recommended + +```task +id: CYA-WP-0005-T05 +status: todo +priority: medium +state_hub_task_id: "" +``` + +**Description**: If time and review allow, implement a thin but real end-to-end slice of Profile 1 on top of Profile 0: new `kind="reflection"` support (or reuse retrospection), enhancement to `cya retrospect` (or new `cya reflect`) to capture verbal lessons, preferential activation for reflection kinds, rendering in `--explain-context` and final output, tests, and docs. All changes must be small, inspectable, and preserve safety invariants. + +**Acceptance criteria** (if executed): +- `remember_reflection` or extended `remember_retrospection_outcome` path works and stores with the new kind. +- `recall_preferences(..., kinds=["reflection", ...])` + activation_context returns them preferentially. +- `cya retrospect` (or a new subcommand) offers a "capture lesson / reflection" step whose output is stored and later activated. +- `--explain-context` and normal responses surface "X verbal reflections influenced this" with the actual text when relevant. +- All new memory still flows through RiskClassifier (can only add caution). +- Full roundtrip tests + README example. +- If the spike grows beyond a small delta, it is carved into its own follow-on workplan and this task is marked partial + blocked. + +**Deliverables**: Working (if minimal) Profile 1 behavior that users can exercise today, or a clear "spike complete, production slice needs X" note. + +### T06 — Update tests, observability, and safety surface for profile evolution + +```task +id: CYA-WP-0005-T06 +status: todo +priority: medium +state_hub_task_id: "" +``` + +**Description**: Ensure the test suite and explainability mechanisms treat profiles as first-class and that safety invariants are explicitly asserted for any memory that could influence future profiles. + +**Acceptance criteria**: +- `tests/test_memory.py` (and any new profile tests) cover: profile param passthrough, kind filtering/boosting, activation_context with profile, export by_kind including new reflection/procedural kinds, provenance on all recall/export results. +- Risk classifier tests (or new integration) assert that memory records with high-risk keywords or from procedural kinds still force confirmation and never downgrade risk level. +- `--explain-context` output (or the ContextEnvelope) includes profile id and a "memory profile influence" section when non-default. +- No new auto-execution or hidden memory paths introduced. + +**Deliverables**: Green tests that will continue to pass as Profiles 1–3 are added; explicit safety assertions for the profile machinery. + +### T07 — Documentation, examples, and user-facing story + +```task +id: CYA-WP-0005-T07 +status: todo +priority: medium +state_hub_task_id: "" +``` + +**Description**: Make the new profile model discoverable and usable for the primary operator and future contributors. + +**Acceptance criteria**: +- README "Memory" or "Advanced" section describes Profile 0 today + the roadmap to 1–3 with links to the workplan and research doc. +- AGENTS.md updated with the new workplan reference and any new dev commands (e.g. running retrospect with synthesis). +- At least one concrete example in docs/ or README showing a user exercising Profile 0 (or 1 if T05 landed) and seeing the self-improvement loop in action. +- MemoryVision.md "Success Criteria" or "Profile-Driven Behavior" section is refreshed to speak in profile terms. + +**Deliverables**: Updated public docs so a new reader understands where memory is today and where it is headed. + +### T08 — Register, commit, sync with State Hub, and close the workplan slice + +```task +id: CYA-WP-0005-T08 +status: todo +priority: high +state_hub_task_id: "" +``` + +**Description**: Follow AGENTS.md exactly: commit all artifacts (research doc, workplan, suggestions doc, doc updates), create/register the workstream in State Hub for the topic, seed `state_hub_workstream_id` (and task ids if returned) into the Markdown frontmatter and task blocks, run `make fix-consistency REPO=can-you-assist` until it reports ✓ PASS (self-execute per prior "do that yourself" authorization pattern), log a progress event, and mark the workplan frontmatter `status: ready` or `proposed` per operator preference (recommended: proposed until review). + +**Acceptance criteria**: +- Git commit(s) exist with clear messages referencing CYA-WP-0005 and the user request. +- State Hub workstream exists for topic `64418556-3206-457a-ba29-6884b5b12cf3` with title matching the workplan; id is written into the .md. +- `make fix-consistency REPO=can-you-assist` exits with RESULT: ✓ PASS (warnings on description drift or closed bootstrap items are acceptable and noted). +- `.custodian-brief.md` is regenerated with the new workplan visible (or noted as ready/proposed). +- A progress event is POSTed to State Hub with summary of the slice (research persisted + workplan created + feedback prepared for phase-memory). +- Workplan frontmatter status is set appropriately (proposed or ready); no tasks are left in "in_progress" without justification. +- Operator is reminded (in final output) to run the consistency make if the assistant did not self-execute it. + +**Deliverables**: Fully registered, synced, committed workplan + artifacts; State Hub and brief reflect the new planning artifact; clean handoff for future activation or ralph-loop. + +## Dependencies & Cross-Repo Coordination + +- **phase-memory (markitect)**: Primary consumer of the T04 feedback deliverable. The suggestions doc + MemoryVision contract (already shared) + this workplan should be the coordination package. State Hub messages or direct handoff recommended after T04/T08. +- **State Hub**: Workstream + task tracking, progress events, decisions (if any profile policy choices arise). Use for cross-domain visibility (capabilities ↔ markitect). +- No hard runtime dependency on llm-connect for this planning slice. + +## Debt & Future Work (Registered) + +This workplan explicitly registers the following as first-class items for later slices or sister-repo ownership: + +- Full implementation of Profile 2 (hierarchical synthesis + compaction) and Profile 3 (procedural evolution + meta-reflection UX). +- Profile selection / switching UX (`cya memory profile ...` or config file) and per-request profile hints. +- Automatic (background or low-load) synthesis triggers vs purely user-triggered. +- Rollback / versioning for procedural memory changes. +- Integration of profile-driven memory evolution proposals into the rule-based risk surface (so a proposed rule change can be risk-assessed before user review). +- Deeper phase-memory wiring: replace local JSON backing with real graph/event store while preserving the exact same port signatures and explainability surface. +- PyPI / release of a version that includes Profile 1 (or higher) — builds on 0004 debt. +- Long-term: cya participation in phase-memory planner dry-runs for activation and compaction budgets. + +These will be tracked via State Hub (this workplan's tasks + future ADRs or child workplans). + +## Success Criteria (for the workplan as a whole) + +When complete: +- Anyone (operator, future contributor, phase-memory owner) can read the research doc + this workplan + MemoryVision and understand exactly what "memory profile 0" is today and what 1–3 will add. +- A high-quality, actionable feedback package exists for the phase-memory sister repo that directly enables the three self-improving variations. +- The seam (ports, kinds, activation_context, provenance) is proven stable enough to support profile evolution without breaking changes. +- All changes are small, inspectable, tested, safe, and committed + synced per AGENTS protocol. + +--- + +**Status note**: This workplan is created in `proposed` state. It captures a focused, high-leverage planning and feedback slice. Implementation of the profiles (beyond the baseline documentation and optional Profile 1 spike) should be activated only after review and operator go-ahead, following the ralph-workplan discipline used for 0001–0004. + +**References** (non-exhaustive): +- Research: `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` +- Memory contract: MemoryVision.md (esp. 0002 T01 integration contract) +- Activation/retrospection concept: `docs/cya-memory-activation-and-retrospection-concept.md` +- Post-0004 assessment: `history/2026-05-28-CYA-Intent-Scope-Gap-Analysis-Post-0004.md` +- Prior workplans: 0002, 0003 (memory foundation), 0004 (packaging) +- External: Shinn Reflexion (2023), Park Generative Agents (2023), LangMem / A-Mem / MemGPT literature (see research doc for links) + +This completes the planning artifact requested in the 2026-05-28 user query. \ No newline at end of file