# 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).
- Deeply aligned the two ideas with INTENT.md (Personalized Console Helper, project-specific memory, recurring workflows, user control) and MemoryVision.md (Project/Directory Memory, Workflow Recipes, activation planning, explainability requirements).
- Defined clear models:
- **Memory Activation**: Automatic, scope-aware (cwd + git root) surfacing of relevant items (preferences, patterns, safety signals) with strong provenance and user control.
- **Retrospection Loops**: Deliberate reflection sessions that produce higher-order memory (`interaction_goal`, retrospection outcomes) which preferentially influence future activation and behavior.
- The two mechanisms reinforce each other: normal use generates candidates for retrospection; retrospection produces high-quality memory that improves future activation.
- Identified minimal port/data model extensions for T02 (richer `kind` support and activation hints in recall, standardized retrospection record kinds).
Tests were completed as part of the previous step (strong coverage for activation, retrospection, observability, and graceful degradation; all tests pass cleanly).
- Heavily expanded the Memory section in README.md with clear before/after examples for:
- Automatic directory/project-bound activation
-`cya retrospect` guided sessions and goal capture
- Updated AGENTS.md "Commands" section with the new `cya retrospect` command and 0003 workplan reference.
- Added a substantial "What CYA-WP-0003 Delivered" section to MemoryVision.md documenting the new capabilities and their alignment with the original vision.
- Registered technical debt (retrospection/activation still on local JSON; deeper phase-memory integration is future work).
- **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.
**Status: done** — all 7 tasks completed via ralph loop. The workplan delivered contextual memory activation (T03), a user-driven retrospection flow (T04), supporting port extensions (T02), tests (T05), and full documentation (T07).
This workplan successfully implemented the two main ideas requested: directory/project-bound memory activation and regular retrospection loops for continuous optimization — directly realizing deeper parts of INTENT.md and MemoryVision.md.
**Status note**: CYA-WP-0003 is complete. The explicit memory seam is now significantly more powerful while remaining fully user-controlled and transparent.
