can-you-assist/workplans/CYA-WP-0003-contextual-memory-activation-and-retrospection.md

---
id: CYA-WP-0003
type: workplan
title: "Contextual Memory Activation and Retrospection Loops for Continuous Optimization"
domain: capabilities
repo: can-you-assist
status: active
owner: grok
topic_slug: foerster-capabilities
created: "2026-05-27"
updated: "2026-05-27"
state_hub_workstream_id: "ac9a9d42-4db9-44d0-9b41-5e16d87c65c8"
---

# 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: done
priority: high
state_hub_task_id: "335595b4-96fe-401f-ab4c-0824a6ba3f05"
started: "2026-05-27 ralph iter 1"
completed: "2026-05-27"
```

**Done** — produced `docs/cya-memory-activation-and-retrospection-concept.md`.

- 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).
- Non-negotiables (explainability + safety invariants) explicitly preserved.

**Acceptance criteria met**:
- Clear, written concept document exists and is consistent with INTENT and MemoryVision.
- The ideas are shown to reinforce each other in a user-controlled continuous optimization loop.

### 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: "6f50bdf4-6252-4b93-9697-407ef432cd90"
```

- 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: "45731b48-74a5-485b-bd56-72f387db3846"
```

- 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: "fb63edc4-1e3f-4964-a2b6-19b29d00ffd8"
```

- 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: "f17a4f42-1630-4244-bdd4-c8d732e8de9b"
```

- 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: "c7da1a0d-647f-48d9-aba3-d2e62791e05f"
```

- 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: "d120efff-eaf6-4630-a3d3-3e70a3db4e09"
```

- 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.

## Activation & Ralph Execution

**Status: active** — activated for ralph-workplan loop execution (HEUREKA promise). This workplan directly continues the memory journey from CYA-WP-0002, moving from basic real memory to proactive, contextually activated memory with built-in retrospection for continuous user-driven optimization.

---

**Status note**: Picks up directly where CYA-WP-0002 left off.