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)

• The two ideas (activation + retrospection) are clearly defined and shown to reinforce each other.
• Models are consistent with INTENT.md (personalized helper, project-specific memory, user control) and MemoryVision.md (kinds, activation, explainability, profile direction).
• Concrete, minimal extensions to the current port surface have been identified.
• 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.