diff --git a/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md b/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md new file mode 100644 index 0000000..1a97003 --- /dev/null +++ b/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md @@ -0,0 +1,186 @@ +--- +id: CYA-WP-0003 +type: workplan +title: "Contextual Memory Activation and Retrospection Loops for Continuous Optimization" +domain: capabilities +repo: can-you-assist +status: proposed +owner: grok +topic_slug: foerster-capabilities +created: "2026-05-27" +updated: "2026-05-27" +state_hub_workstream_id: null +--- + +# CYA-WP-0003: Contextual Memory Activation and Retrospection Loops for Continuous Optimization + +## Goal + +Build on the real memory foundation delivered in CYA-WP-0002 to make memory **actively useful** for context-aware assistance, with two primary advances: + +1. **Directory- and project-bound memory activation**: Automatically and intelligently surface relevant memory when the user is working in a specific directory or project, without requiring explicit recall every time. +2. **Regular retrospection loops**: Enable structured, recurring reflection sessions between the user and `cya` that turn memory into a vehicle for continuous improvement — reviewing what worked, setting interaction goals, and evolving preferences over time. + +This workplan directly addresses two remaining gaps identified in the post-0002 Intent-vs-Scope analysis: +- Moving from passive memory storage to **proactive, contextually activated** memory. +- Establishing the foundation for true **longitudinal adaptation** and a user-driven optimization loop. + +## Background & References + +- `INTENT.md` — especially the "Personalized Console Helper" section and the explicit call for `phase-memory` to support "project-specific memory" and "recurring workflows". +- `MemoryVision.md` — defines primary memory kinds relevant to cya, including Project/Directory Memory and Workflow Recipes. +- `history/2026-05-27-CYA-Intent-Scope-Gap-Analysis-Post-0002.md` — identifies remaining gaps in contextual activation and longitudinal value after 0002. +- CYA-WP-0002 — delivered the real (persisting) memory implementation and explicit ports. +- Current memory ports in `src/cya/memory/__init__.py` (the `scope` parameter is the natural starting point for directory binding). +- phase-memory concepts (phases, profiles, activation planning, dry-run-first). + +## Non-Goals (for this slice) + +- Full autonomous agentic behavior or background memory harvesting. +- Deep semantic understanding of code or notes (still out of scope). +- Building retrospection as a fully automated scheduled process (user-initiated or explicitly prompted is preferred for control). +- Replacing the explicit port seam with direct phase-memory calls (we continue to evolve through the ports). +- Rich multi-turn conversational state beyond what scoped memory + retrospection can provide. + +## Task Breakdown + +### T01 — Refine the conceptual model for contextual activation and retrospection loops + +```task +id: CYA-WP-0003-T01 +status: todo +priority: high +state_hub_task_id: null +``` + +- Deeply align the two ideas (directory-bound activation + regular retrospections) with INTENT.md and MemoryVision.md. +- Define clear models for: + - "Memory activation" (what gets recalled automatically, when, and why). + - Retrospection as a first-class interaction pattern (what is captured, how goals/preferences are updated). +- Produce a short design note (or section in MemoryVision) describing the interaction loop. +- Identify minimal extensions needed to the existing memory ports and data model. + +**Acceptance criteria**: +- Clear, written concept exists and is consistent with INTENT and MemoryVision. +- The two ideas are shown to reinforce each other rather than compete. + +### T02 — Extend memory ports and data model for activation and retrospection + +```task +id: CYA-WP-0003-T02 +status: todo +priority: high +state_hub_task_id: null +``` + +- Evolve the four ports (or add minimal new ones) to better support: + - Richer scoping and activation hints (e.g., directory + project identity + optional profile). + - Storing and retrieving "retrospection outcomes" and "interaction goals" as first-class memory. +- Define lightweight structures for retrospection records and activated context packages. +- Maintain full backward compatibility and user inspectability. + +**Acceptance criteria**: +- Ports and data model support the concepts from T01 without breaking existing usage. +- All new memory remains fully user-visible and editable. + +### T03 — Implement directory- and project-bound memory activation + +```task +id: CYA-WP-0003-T03 +status: todo +priority: high +state_hub_task_id: null +``` + +- In the orchestrator (and context collection path), automatically activate relevant memory based on the current working directory and git root. +- Make activation smart but transparent: surface what was activated and why (especially via `--explain-context`). +- Allow users to influence activation (e.g., "always include these memories in this project"). + +**Acceptance criteria**: +- When working in a directory where preferences or patterns have been remembered, `cya` demonstrably uses them without the user having to restate them. +- Activation is visible and controllable. + +### T04 — Build the retrospection interaction flow + +```task +id: CYA-WP-0003-T04 +status: todo +priority: high +state_hub_task_id: null +``` + +- Design and implement a retrospection mode or dedicated subcommand / prompt pattern. +- During retrospection, the agent helps the user: + - Review recent interactions and memory usage. + - Reflect on what helped or didn't. + - Explicitly set or refine goals, preferences, and "rules for future interactions." +- Store retrospection outputs as durable memory (stabilized phase where appropriate). + +**Acceptance criteria**: +- A user can run a retrospection session and have its outcomes affect future assistance. +- The flow feels natural in a terminal and respects user control. + +### T05 — Close the continuous optimization loop + +```task +id: CYA-WP-0003-T05 +status: todo +priority: medium +state_hub_task_id: null +``` + +- Wire retrospection outcomes back into normal assistance flows (context building, explanation style, safety tuning, memory activation). +- Add basic mechanisms so that "interaction goals" set during retrospection measurably influence future behavior. +- Ensure the loop remains user-driven and auditable. + +**Acceptance criteria**: +- After a retrospection session, subsequent `cya` interactions demonstrably reflect the user's stated goals and reflections. + +### T06 — Tests, observability, and graceful degradation + +```task +id: CYA-WP-0003-T06 +status: todo +priority: high +state_hub_task_id: null +``` + +- Add comprehensive tests for activation logic, retrospection flows, and the closed optimization loop. +- Ensure strong observability (what memory was activated, what retrospection outcomes influenced a response). +- Verify graceful behavior when memory is unavailable or the user opts out of retrospection. + +**Acceptance criteria**: +- New behaviors have solid test coverage. +- `pytest` remains clean with no new external dependencies for normal runs. + +### T07 — Documentation, examples, and handoff + +```task +id: CYA-WP-0003-T07 +status: todo +priority: medium +state_hub_task_id: null +``` + +- Heavily update README with before/after examples of directory-bound activation and retrospection sessions. +- Document the new interaction patterns in AGENTS.md and MemoryVision.md. +- Register extension points and any new technical debt. +- Provide clear guidance for phase-memory owners on how retrospection data can flow into richer profiles. + +**Acceptance criteria**: +- A reader can understand and try the new capabilities from the README alone. +- The concepts are clearly connected back to INTENT and MemoryVision. + +## Dependencies & Cross-Repo Coordination + +- **phase-memory**: The concepts here are designed to be consumable and eventually enriched by richer phase-memory capabilities (profiles, phases, activation planning). Close coordination recommended during T01/T02. +- **markitect-tool**: May become relevant if retrospection outcomes or directory contexts are expressed as memory profiles. +- State Hub: For tracking this as the direct follow-on to CYA-WP-0002. + +## Proposed Status & Activation + +This workplan is created in `proposed` status. It should be reviewed, moved to `ready`, and activated once the team confirms alignment with phase-memory's current and near-term capabilities. + +--- + +**Status note**: This workplan picks up directly where CYA-WP-0002 left off, moving from "we now have real memory" to "memory is actively and intelligently helping the user in context, with a built-in mechanism for continuous improvement." \ No newline at end of file