can-you-assist/docs/cya-memory-activation-and-retrospection-concept.md

# Conceptual Model: Contextual Memory Activation and Retrospection Loops (CYA-WP-0003 T01)

**Date:** 2026-05-27  
**Workplan:** CYA-WP-0003  
**Related:** INTENT.md, MemoryVision.md, history/2026-05-27-CYA-Intent-Scope-Gap-Analysis-Post-0002.md, CYA-WP-0002 results

## Guiding Principle

Memory in `cya` must be **proactively useful** and **user-steerable over time**.

Two complementary mechanisms achieve this:

1. **Contextual Activation** — Relevant memory is automatically surfaced based on the user's current working context (especially directory/project), without the user having to explicitly recall it every time.
2. **Retrospection Loops** — Structured, recurring reflection sessions allow the user to review how memory was used, reflect on effectiveness, and explicitly set or refine goals, preferences, and "rules for future assistance."

Together they create a user-controlled continuous optimization loop: Use → Surface memory in context → Reflect → Evolve memory/goals → Better future context and behavior.

This directly addresses the remaining gaps after CYA-WP-0002: moving from passive storage to active, contextually-aware, longitudinally improving assistance.

## Alignment with INTENT.md and MemoryVision.md

**From INTENT.md:**
- "Personalized Console Helper" that adapts to habits, preferred styles, repository conventions, recurring workflows, safety preferences.
- `phase-memory` must support "project-specific memory", "distinguishing global, local, temporary, and contextual memory".
- Core principle: user’s working memory belongs to the user.

**From MemoryVision.md:**
- Primary relevant kinds: Project/Directory Memory, Workflow Recipes & Patterns, Learned Preferences & Conventions, Safety & Trust Signals.
- `cya` is a consumer that requests activation of context packages.
- Every response influenced by memory must explain **which** memory items and why.
- Support for profile-driven behavior (what to stabilize, compact, etc.).

The proposed model is a direct, practical realization of these for the current and near-term phase (local JSON backing evolving toward full phase-memory).

## Model 1: Memory Activation

### Definition
**Memory Activation** is the process by which `cya` automatically selects and injects relevant items from the user's memory store into the assistance context for a given request, based on contextual signals.

### Primary Activation Signal (MVP for this workplan)
- **Current working directory + git root** (the `scope` already used in the T02 implementation).
- When the user runs `cya` in a directory, the system preferentially activates items whose `scope` matches the cwd or any ancestor directory up to the git root.
- Project identity (git remote or root path) can serve as a stronger key for "project memory".

### Activation Layers (in priority order)
1. Explicitly user-pinned or high-priority items for the current scope.
2. Recently used or high-confidence stabilized preferences for the project/directory.
3. Workflow patterns and recipes previously approved/refined in this context.
4. Safety & trust signals (e.g., "never auto-run" patterns remembered for this project).
5. General (global) user preferences as fallback.

### Activation Metadata (for explainability)
Every activated item must carry:
- `provenance`: where it came from (retrospection, explicit remember, etc.)
- `confidence` / stability phase hint
- `reason_for_activation`: why it was selected for this context/request

This must be surfaced cleanly in `--explain-context` and (when relevant) in the final response.

### User Control
- `--no-memory` or per-request opt-out.
- Ability to say "always include X in this project" or "never activate Y here".
- `cya memory export/inspect/forget` for the current scope.

## Model 2: Retrospection as a First-Class Interaction Pattern

### Definition
A **Retrospection** is a deliberate, bounded session (user-initiated or lightly prompted) in which the user and `cya` jointly review recent interactions, memory usage, and outcomes, then explicitly capture reflection and forward-looking intent.

### Retrospection Flow (High-Level)
1. Trigger: `cya retrospect` (or equivalent special prompt/mode).
2. Review phase:
   - Show recent assistance cycles and which memory items were activated.
   - Surface outcomes (was the suggestion accepted? did it require extra clarification?).
3. Reflection phase:
   - User answers guided questions: "What worked well?", "What should I have remembered?", "How do I want to be helped differently going forward?"
4. Goal-setting / Intent capture:
   - New or updated preferences.
   - Interaction goals (e.g., "Prefer concise answers with one alternative", "Always warn about destructive commands even if I have approved the pattern before").
   - Explicit stabilization or forgetting decisions.
5. Commit phase:
   - Outcomes are stored as first-class memory records (with `kind: "retrospection"` or "interaction_goal").
   - These receive preferential treatment in future activation (higher weight for the same scope).

### Retrospection Outputs as Higher-Order Memory
- `kind: "interaction_goal"` or "retrospection_outcome"
- Fields: goal_text, applies_to (scope, kinds, task_classes), priority, review_date
- These can influence:
  - What gets activated.
  - Explanation depth and style passed in context to the LLM.
  - Safety tuning (e.g., "treat this pattern more conservatively in this project").

### Relationship to Activation
Retrospection is one of the most powerful ways new memory enters the system in a high-quality, user-vetted form. Activated memory during normal use can trigger a lightweight retrospection prompt ("Would you like to capture this as a recurring preference?").

## Integration with Existing Ports and Future phase-memory

### Minimal Extensions Identified for T02
Current ports (post-0002) already provide a good foundation via the `scope` and `profile` parameters.

Recommended small evolutions (to be detailed and implemented in T02):
- Add support for a `kind` parameter / filter in `recall_preferences` (to boost or specifically request retrospection outcomes, interaction goals, etc.).
- Add `activation_context` or richer hinting when calling recall (so the orchestrator can say "current cwd + recent task class").
- Standardize a `retrospection` / `interaction_goal` kind in the stored records.
- Add a lightweight `remember_retrospection_outcome(...)` helper (or just use `remember_preference` with special kind) for now.
- Ensure `export_memory` can filter and pretty-print retrospection records.

Longer term (when wiring to full phase-memory):
- Retrospection outcomes become natural input to profile execution and stabilization planners.
- Activation becomes a proper request for a "context package" under user profile constraints.

### Explainability & Safety (Non-Negotiable)
- Any memory-activated context (including from retrospection goals) must be explainable.
- Retrospection-derived goals that would affect risky commands must still pass through the rule-based risk classifier (T03/T04 invariants preserved).
- Users can always review, edit, or delete retrospection records.

## Proposed Design Artifacts to Produce in Later Tasks
- Retrospection prompt templates / guided flow (T04).
- Changes to orchestrator context assembly for automatic activation (T03).
- Observability for "memory activated from retrospection goals" (T06).
- User-facing examples in README (T07).

## Acceptance Criteria for T01 (Self-Check)

- [x] The two ideas (activation + retrospection) are clearly defined and shown to reinforce each other.
- [x] Models are consistent with INTENT.md (personalized helper, project-specific memory, user control) and MemoryVision.md (kinds, activation, explainability, profile direction).
- [x] Concrete, minimal extensions to the current port surface have been identified.
- [x] Safety and explainability requirements are explicitly preserved.
- [ ] (To be validated in review) The concepts feel natural in a terminal workflow.

This document serves as the primary output of T01. It can be referenced and evolved in subsequent tasks and eventually folded into MemoryVision.md or a dedicated user guide.