# Memory Vision for can-you-assist (cya) **Status:** Initial vision (post CYA-WP-0001) **Date:** 2026-05-26 **Related Work:** CYA-WP-0001 T05 (minimal ports), phase-memory architecture, INTENT.md ## Guiding Principle > The user’s working memory must belong to the user — not to any assistant interface, vendor, or opaque system. `cya` must never become a memory silo. All memory, history, preferences, and adaptation behavior must flow through explicit, inspectable ports provided by `phase-memory`. ## Relationship to phase-memory `phase-memory` is the **profile-driven memory operating layer** for the broader ecosystem. It is responsible for: - Interpreting **Markitect memory profiles** as executable runtime plans. - Modeling memory in distinct **phases**: - `ephemeral` — short-lived, high-turnover (e.g., current conversation window) - `fluid` — recent but still malleable context - `stabilized` — reviewed and relatively durable knowledge/preferences - `rigid` — high-confidence, long-term, rarely changing (core identity, strong conventions) - Planning and executing (or dry-running) **lifecycle actions**: - Retention - Refresh - Compaction - Stabilization - Activation (under token/item budgets) - Policy, audit, and review gates around memory changes. `cya` is a **consumer** of this layer. It does **not** own memory semantics, storage, or lifecycle policy. ## How cya Will Use Memory `cya` will treat memory as a first-class, explainable input to every assistance cycle, while keeping ownership and control firmly with the user (via phase-memory). ### Primary Memory Kinds Relevant to cya - **Conversation / Interaction History** — primarily fluid/ephemeral - **Learned Preferences & Conventions** — stabilized over time (command style, safety tolerance, explanation depth, shell aliases, etc.) - **Project / Directory Memory** — stabilized or rigid context specific to a working directory or repository - **Workflow Recipes & Patterns** — stabilized reusable sequences the user has approved or refined - **Safety & Trust Signals** — rigid or stabilized (user-defined risk thresholds, trusted command patterns) - **Source Provenance** — metadata about where knowledge came from (files, git history, previous sessions) ### Integration Model (Building on T05 Ports) The four explicit ports defined in T05 (`cya/memory/__init__.py`) are the permanent integration surface: - `remember_preference(key, value, scope)` - `recall_preferences(scope, task_class)` - `forget(scope, keys)` - `export_memory(scope)` Over time these will be wired to real `phase-memory` capabilities. `cya` will additionally: 1. **Produce structured memory events** (conversation turns, accepted suggestions, explicit user feedback, safety decisions) that phase-memory can ingest as fluid memory. 2. **Request context packages** via phase-memory’s activation planning (respecting user-defined profiles and token budgets). 3. **Surface memory influence** in responses — users should be able to see “this suggestion was shaped by your saved preference for concise git output + recent project conventions.” 4. **Honor user-initiated lifecycle actions** (export, reset, compact, stabilize) exposed through the ports or dedicated `cya memory ...` subcommands in the future. ### Profile-Driven Behavior In the longer term, users (or the system) will be able to supply or generate **Markitect-compatible memory profiles** that tell phase-memory how `cya` should behave regarding their memory. Examples of profile intent that matter to cya: - “Keep my last 30 days of shell interactions fluid, but stabilize any workflow I have used more than 5 times.” - “Treat everything in `~/notes/projects/` as stabilized by default, but require review before anything becomes rigid.” - “Aggressively compact conversational memory after 48 hours unless I mark it important.” - “Never let total activated context for a single `cya` request exceed 8k tokens without explicit approval.” `cya` will request activation plans and context packages that respect these profiles. ## Safety and Explainability Requirements Because memory directly influences suggestions: - Every response that used non-ephemeral memory must be able to explain **which** memory items influenced it and why. - Memory-driven suggestions must still pass through the T03 risk classifier. - Users must be able to temporarily or permanently disable memory influence for a session or scope (`cya --no-memory ...` or equivalent). - Export and inspection of memory must be first-class and low-friction. ## Current State (Post MVP) As of the end of CYA-WP-0001: - Only the four thin no-op ports exist (T05). - No actual memory is persisted or recalled by `cya`. - The orchestrator and safety layer are ready to consume memory signals when they become available. - The architecture deliberately avoids any hidden or local-JSON fallback memory (per explicit operator direction). This is the correct starting point. Real integration will be done as a subsequent slice, using the ports as the stable contract. ## Open Questions & Future Work - How will `cya` generate or help users author memory profiles? - What is the right granularity for “project memory” vs global memory? - How should safety decisions and user overrides themselves become first-class memory citizens? - Can/should `cya` participate in compaction and stabilization planning, or should it only consume the results? - What observability (cost, token usage, memory influence) should be exposed at the CLI level? ## Success Criteria (Longer Term) `cya` + `phase-memory` together are successful when a user can say: - “This assistant actually knows my preferences and project conventions, but I can see exactly what it knows and change it whenever I want.” - “I switched LLM providers and my assistant still feels like *mine*.” - “I asked it to forget everything about project X last month, and it actually did.” --- ## Agentic Memory Research & Profile Directions (2026-05) **Date:** 2026-05-28 (ralph start for CYA-WP-0005) **Related:** `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md`, CYA-WP-0003 (activation + retrospection), CYA-WP-0005 Building directly on the 0002 integration contract (below), the 0003 contextual activation + `cya retrospect` continuous optimization loop, and the post-0004 gap analysis (memory moved from large gap to small-medium), deep research into agentic/self-improving memory architectures was performed and persisted. The research synthesizes three canonical patterns for closed self-improving loops in LLM agents (Trial → Evaluation/Feedback → Reflection/Synthesis → Memory Update → Improved future behavior): - **Profile 1 — Reflexion-style verbal self-improvement** (lightweight, high-explainability): Store natural-language self-reflections/lessons (leveraging existing `KIND_RETROSPECTION` + `remember_retrospection_outcome` + `cya retrospect`). Preferentially activate them via kinds + activation_context in future turns. Plain-English "verbal reinforcement" that users can inspect and edit. - **Profile 2 — Generative-Agents-style hierarchical synthesis**: Treat assistance outcomes, retrospections, and explicit remembers as an episodic stream. Periodic (user-triggered or planner-driven) LLM synthesis produces higher-order abstractions (project conventions, workflow patterns, "in this scope we always...") with citations, stored in stabilized phases. Multi-factor retrieval (recency + importance + relevance + profile/scope match) + the existing activation boost. - **Profile 3 — Procedural / meta-policy evolution** (highest leverage, highest guardrail needs): First-class evolvable "how I should behave" rules and procedures as a distinct tier. Meta-reflection (after retrospection or explicit "improve my rules") proposes patches to the procedural layer. Strong dry-run + user veto + safety impact analysis required; changes can only tighten (or maintain) the rule-based risk posture by default. Detailed definitions, cya-specific implementation mappings (ports, kinds, orchestrator wiring, safety invariants), capability matrix, and phase-memory interface requirements live in the persisted research document and are executed via CYA-WP-0005 tasks T02–T05. This directly addresses several Open Questions above (profile authoring, granularity of project memory, safety signals as first-class memory, observability of memory influence, participation in planning/compaction) while preserving all cya invariants (user control, full provenance/explainability, rule-based safety that memory can only strengthen). **Next in this workplan:** T02 formalizes the current post-0003 implementation as explicit **Profile 0** baseline (the stable foundation everything else builds on). T03 adds the full profile definitions + matrix. T04 delivers the concrete optimization suggestions for the phase-memory sister repo. See also the full research artifact and CYA-WP-0005 for acceptance criteria and cross-links. --- ## Profile 0 Baseline (Post-0003 / Current Shipped) **Status:** Shipped and stable as the production memory implementation (CYA-WP-0002 T02 real JSON + CYA-WP-0003 contextual activation + retrospection extensions). This is the explicit foundation on which Profiles 1–3 will be built. **Guiding Principle (Profile 0):** Deliver real, user-controlled, contextually activated, longitudinally improving memory *today* using a high-quality local approximation, while keeping the integration seam (profile, kinds, activation_context, provenance, phase hints) completely stable and ready for eventual replacement by full phase-memory planners, graph store, and lifecycle rules. No hidden state; everything is user-inspectable and user-owned. ### Backing Store & Persistence - Location: `~/.config/cya/memory/.json` (one file per scope, default "cwd"). - Format: Simple list of dict records. Fully human-readable and editable by the user. - Fields per record (typical): `key`, `value`, `ts` (epoch), `scope`, `profile`, `kind`. - User can `cat`, edit, or delete these files at any time; `cya` will respect the changes on next run. - When full phase-memory is wired, this backing will be replaced by the durable graph/event store while preserving the exact same high-level port behavior and return shapes. ### Public API (the stable cya ↔ phase-memory seam) All entry points live in `src/cya/memory/__init__.py`: - **Constants** (standard kinds used by cya and `cya retrospect`): - `KIND_PREFERENCE` - `KIND_RETROSPECTION` - `KIND_INTERACTION_GOAL` - **Core functions** (signatures as of 2026-05, all support `profile` for future multi-profile use): - `remember_preference(key, value, scope="cwd", *, profile=None, ttl=None, kind=KIND_PREFERENCE)` - `recall_preferences(scope="cwd", task_class=None, *, kinds=None, profile=None, limit=50, activation_context=None) -> dict` - Returns: `{"items": [...], "provenance": [...], "phase": "fluid", "profile": ..., "note": "..."}` - `forget(scope="cwd", keys=None, *, profile=None)` - `export_memory(scope="cwd", *, profile=None, kinds=None) -> dict` (includes `by_kind` counts, `provenance_summary`, `phases` list) - `remember_retrospection_outcome(...)` — convenience wrapper that chooses the right kind for higher-order memory from reflection sessions. **Activation logic (0003):** When `activation_context` (populated by the orchestrator from `ContextEnvelope` with `cwd` + git root) is supplied to `recall_preferences`, items whose `scope` or `profile` matches are boosted to the front of the result list. This makes directory/project-bound memory feel proactive without any user having to explicitly recall it. **Retrospection as first-class input (0003):** `cya retrospect` (guided flow) produces records with special kinds that receive preferential activation in future turns. These are the seed for the self-improving loop described in the 2026-05 research. **Guaranteed properties of every call:** - Rich `provenance` array always present (source, count, activation_context, etc.). - `phase` hint returned (currently always "fluid" for the local store; will become meaningful once phase-memory lifecycle is wired). - Graceful degradation: on any error the ports log a loud warning to stderr and return safe empty/default values. Never crash the assistance path. - All memory influence is visible via `--explain-context`. ### Safety & Explainability Invariants (non-negotiable for Profile 0 and all future profiles) - Memory signals are **only additive** to caution. They may append rationale or force confirmation in the rule-based `RiskClassifier`, but they never downgrade a risk level or bypass mandatory explicit user confirmation for non-SAFE commands. - Every memory-influenced response can explain exactly which items were activated, why (activation_context match, kind boost, recency, retrospection provenance), and what phase they came from. - Users can always opt out per-request (`--no-memory` or equivalent) or globally inspect/forget via the ports + future `cya memory` subcommands. ### Usage Sites in the Current System - `src/cya/orchestrator.py`: Calls `recall_preferences` with activation_context on every assistance request; injects results into the `ContextEnvelope` passed to the LLM; renders memory influence in `--explain-context` panels. - `src/cya/cli/main.py` (retrospect subcommand): Uses `recall_preferences` + `remember_retrospection_outcome` to close the user-driven continuous optimization loop. - Risk classifier: Receives memory context and applies only the "increase caution" rules. ### Relationship to Profiles 1–3 and phase-memory Profile 0 is deliberately a **complete, usable, production-quality local implementation** of the seam defined in the 0002 T01 contract (refined in 0003). It already delivers the INTENT/SCOPE vision for contextual + longitudinal memory with excellent explainability and zero hidden state. Future profiles will layer on top: - Profile 1 adds verbal reflection storage + preferential activation (mostly a small delta on existing retrospection kinds + `cya retrospect`). - Profile 2 adds episodic capture + synthesis passes (new kinds + calls into phase-memory reflection planners). - Profile 3 adds procedural rules + meta-policy evolution (new tier + strong proposal/audit UX + safety guardrails). All of them must continue to satisfy the invariants above and must continue to work against the exact same port signatures (or compatible extensions). **See:** `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` (research + mappings), CYA-WP-0005 T01–T03, `docs/cya-memory-activation-and-retrospection-concept.md`, current `src/cya/memory/__init__.py` (the reference implementation), and the 0002 integration contract below (the original seam that Profile 0 realizes). --- ## Profiles 1–3: Definitions and cya Integration Plans **Date:** 2026-05-28 (CYA-WP-0005 T03) **Source:** Synthesized from `history/2026-05-28-CYA-Agentic-Memory-Research-Variations.md` (the deep research artifact). These are the authoritative working definitions for the self-improving memory profiles. All three preserve cya's non-negotiable contract: user-controlled, fully explainable, safety-first (memory only increases caution), explicit seam to phase-memory. The three profiles are ordered by increasing agentic power and implementation cost. ### Profile 1 — Reflexion-Style Verbal Self-Improvement Loop **Intent:** Enable lightweight, high-explainability self-improvement by capturing and preferentially activating natural-language "lessons" and verbal reflections from user interactions and retrospection sessions. **Core Loop (condensed):** 1. Normal assistance with current Profile 0 activation. 2. Outcome capture (accept/revise/reject or explicit `cya retrospect`). 3. Verbal reflection generated (1–3 concise lessons in plain English). 4. Stored with new or extended `kind` (e.g. `reflection` or `verbal_lesson`) via `remember_retrospection_outcome` / new helper. 5. Future recall boosts these kinds + activation_context; they are prepended with high salience. 6. Visible in `--explain-context` and final output ("3 verbal reflections influenced this..."). **cya Mapping (builds directly on 0003):** - ~80% already exists (`KIND_RETROSPECTION`, `remember_retrospection_outcome`, `cya retrospect` flow, kind filter in recall, activation_context boost). - Small delta: lightweight "capture lesson" step at end of retrospect (or auto after notable outcomes); new `kind` values; preferential activation logic tweak. - Orchestrator already has the wiring to surface them. **Delta Required:** Minor enhancements to retrospect CLI flow and recall boosting; new `kind` constant(s). **Phase-memory Fit:** Minimal for MVP — good native `kinds` filter + provenance. Later: a lightweight "reflection planner" for compaction of duplicate lessons. **Safety / Explainability:** Reflections that touch risky patterns still go through the rule-based RiskClassifier. All items carry full provenance. Users can inspect/edit/forget them directly. **See also:** Research doc Variation 1, Shinn et al. (Reflexion), current `docs/cya-memory-activation-and-retrospection-concept.md`. ### Profile 2 — Generative-Agents-Style Hierarchical Memory Stream + Synthesis **Intent:** Move from passive storage to active synthesis of higher-order knowledge (project conventions, recurring workflows, "in this scope we always...") so the assistant becomes meaningfully smarter over time with citations back to source events. **Core Loop:** 1. Episodic capture of every turn/outcome/retrospection (structured records with ts, kind, scope, activation_context, payload, provenance). 2. Periodic synthesis (user-triggered via `cya retrospect --synthesize`, or phase-memory planner): LLM clusters recent fluid memories and produces abstractions with citations. 3. Store synthesized items with elevated phase hint ("stabilized") and dedicated kinds (`KIND_SYNTHESIZED_CONVENTION`, `KIND_PROJECT_PATTERN`, etc.). 4. Retrieval uses multi-factor scoring (recency + importance + relevance + profile/scope match) + existing activation boost. 5. Hierarchy emerges naturally (raw → synthesized → higher-order). 6. Compaction / phase transitions proposed with dry-run + user review. **cya Mapping:** - Local JSON already provides a usable episodic stream. - `export_memory` + recall with activation_context already return provenance. - Orchestrator already injects memory into ContextEnvelope. - Extend `retrospect` to offer synthesis as an explicit option. - Add lightweight importance scoring on remember. - Synthesized items flow through the same recall path (different kinds/phases). **Delta Required:** Synthesis entrypoint (or call into phase-memory planner), new kinds, importance scoring, UI affordance in retrospect for "synthesize patterns". **Phase-memory Fit (strong alignment):** - Synthesis / reflection planner entrypoint (cya can request "run reflection pass"). - Structured objects with citation/provenance fields. - Phase transition proposals (fluid → stabilized) with dry-run diffs. - Multi-factor retrieval API that cya can parameterize. **Safety / Explainability:** Every synthesized item carries machine + human readable citations. All influence is visible in `--explain-context`. Synthesis proposals are always reviewable (dry-run first). **See also:** Research doc Variation 2, Park et al. (Generative Agents), MemoryVision phases section. ### Profile 3 — Procedural / Meta-Policy Evolution (Aspirational) **Intent:** Allow the assistant to evolve its own high-level "how I should behave" rules and procedures as first-class, auditable, evolvable memory — the highest-leverage form of self-improvement, with the strongest guardrails. **Core Loop:** 1. Base behavior driven by a dedicated tier of procedural memory items (`procedural_rule`, `meta_policy`, `explanation_strategy`, `safety_tuning`). 2. Meta-reflection (after retrospect or explicit "improve my rules"): LLM reviews recent outcomes + current rules + safety incidents and proposes patches. 3. Proposal + audit: phase-memory / cya presents structured diff ("+1 rule, safety impact: tightens") for user review/edit/approve/veto. 4. On approval: rule stored with high stability/phase and becomes active in future activation, prompt construction, and risk hints. 5. Guardrails: changes are additive or tightening only by default; every rule has provenance + last-review date; RiskClassifier treats procedural items as strong "force confirmation" signals. **cya Mapping:** - New dedicated kinds + `remember_procedural_rule` helper. - New `cya improve-rules` (or retrospect extension) that triggers meta-reflection. - Orchestrator / safety layer gives procedural items highest priority for injection. - Export/inspect surfaces the procedural layer prominently. - Tight integration with existing rule-based RiskClassifier. **Delta Required:** New kinds + helper, meta-reflection flow + UI, prominent procedural layer in export/explain, stronger safety injection. **Phase-memory Fit (most demanding):** - First-class procedural memory collection + dedicated policy evolution planner. - Proposal/diff semantics with structured review objects (dry-run). - Explicit meta-reflection hooks with bounded context. - Safety/policy gateway enforcing "cannot weaken risk posture without override". - Versioning/rollback for the procedural layer. - Profile-level "aggressiveness" setting (conservative / balanced / bold). **Safety / Explainability:** Highest bar. All proposals declare safety impact. User veto is mandatory for anything that could relax posture. Full audit trail. **See also:** Research doc Variation 3, LangMem procedural, A-Mem, LEGOMem, cya `risk/classifier.py`. ### Profile Capability Matrix | Aspect | Profile 0 (baseline) | Profile 1 (Verbal Reflexion) | Profile 2 (Hierarchical Synthesis) | Profile 3 (Procedural Evolution) | |-------------------------------|---------------------------------------|------------------------------------------|---------------------------------------------|-----------------------------------------------| | Primary new kinds | preference, retrospection, interaction_goal | reflection / verbal_lesson | synthesized_convention, project_pattern | procedural_rule, meta_policy, safety_tuning | | Activation model | scope/profile boost + recency | + kind boost for reflections | + multi-factor (recency + importance + relevance) | + highest priority for procedural items | | Synthesis / Reflection | None (user only via retrospect) | Lightweight verbal lessons (user or light auto) | Periodic LLM synthesis with citations (planner or user-triggered) | Meta-reflection proposes rule patches (strong audit) | | Procedural support | None | None | None | First-class tier + evolution planner | | User control surface | remember / forget / export / retrospect | + "capture lesson" in retrospect | "synthesize patterns" option + review dry-runs | Full proposal review, veto, rollback | | Safety impact | Additive only (never downgrades) | Same + reflections can force confirmation | Same + synthesis proposals carry impact tags | Highest: cannot relax risk without explicit override | | cya implementation effort | Already shipped | Small (retrospect step + kind boost) | Medium (synthesis entrypoint + importance) | High (new flow + UI + safety injection) | | phase-memory effort (key) | N/A (local approximation) | Minimal (kinds + provenance) | High (synthesis planner, phase proposals, multi-factor retrieval) | Highest (procedural planner, diff/review objects, policy gateway) | | Explainability | Full provenance + --explain-context | + actual reflection text | + citations on every synthesized item | + full audit trail on every rule change | **Notes on the matrix:** Costs are relative. Profile 1 is designed to deliver quick wins on top of existing 0003 machinery. Profiles 2 and 3 require increasing collaboration with phase-memory planners and stronger dry-run/audit primitives. ### Handoff & Next Steps (within CYA-WP-0005) - T04 turns the suggestions section of the research doc into the polished, standalone `docs/phase-memory-optimization-suggestions.md` (or equivalent) for sister-repo coordination. - T05+ explore minimal implementation spikes (starting with Profile 1) only after the definitions and phase-memory feedback are reviewed. - All profile work must preserve the Profile 0 invariants documented above. See the full research artifact for deeper citations (Shinn, Park, LangMem, etc.) and the detailed phase-memory feedback list. --- ## cya ↔ phase-memory Integration Contract (CYA-WP-0002 T01) **Date:** 2026-05-26 (ralph iter 1) **Status:** Draft — produced during T01 review; to be validated with phase-memory owners. **Parties:** `cya` (capabilities domain, consumer for terminal assistance) and `phase-memory` (markitect domain, provider of phase-aware runtime planning, lifecycle, activation, and low-level ports). ### Scope for CYA-WP-0002 (first real slice) - Memory kinds: primarily `preference` (user prefs, workflow patterns, "never auto-run" standing rules) + basic project/cwd context. - Scopes: `cwd` (default), project/directory. - Phases: ephemeral/fluid for session-conversation prefs; stabilized (with dry-run + review) for user-declared long-term prefs per lifecycle-rules. - Operations: remember, recall (with provenance + explainable plan), forget (scoped), export (for transparency and --explain-context). - Non-goals (this slice): full 9 kinds, embeddings/SemanticIndex, durable kontextual graph, voice, full profile authoring. ### Refined Port Signatures (cya seam) These replace/extend the T05 no-op signatures. Implementations in T02+ will delegate to `phase_memory` (ports, planner, lifecycle, runtime or high-level sugar). ```python def remember_preference( key: str, value: Any, scope: str = "cwd", *, profile: str | None = None, # e.g. "cya-assistant-v1" or user profile id ttl: str | None = None, # e.g. "30d" or phase hint ) -> None: ... def recall_preferences( scope: str = "cwd", task_class: str | None = None, *, kinds: list[str] | None = None, # ["preference", "task"] etc. profile: str | None = None, limit: int = 50, ) -> dict[str, Any]: # Returns: {"items": [...], "provenance": [...], "dry_run_plan": {...}, "phase": "fluid", "profile": ...} ... def forget(scope: str = "cwd", keys: list[str] | None = None, *, profile: str | None = None) -> None: ... def export_memory(scope: str = "cwd", *, profile: str | None = None) -> dict[str, Any]: # Includes status, phase info, provenance summary, policy notes for explain. ... ``` All calls must be non-blocking for the assistance path; failures → graceful empty + stderr warn (current behavior preserved). ### Ownership & Responsibilities - **cya owns**: the seam (these 4 functions + wiring in orchestrator/cli for context + explain), safety integration (memory signals feed rule-based RiskClassifier but never bypass confirmation), user-visible explainability (provenance rendered in --explain-context and final output), graceful degradation. - **phase-memory owns**: the profile execution planner, phase/lifecycle/retention/compaction planners (dry-run first), low-level ports (MemoryGraphStore, MemoryEventLog, PolicyGateway, ...), adapter orchestration, Markitect contract interop, provenance/audit in results. - Boundary: cya calls high-level or planner entry points; never mutates graph directly or bypasses policy/review gates. ### Gaps & Required Follow-up - phase-memory pilot maturity for "preference" kind high-level sugar (or cya builds minimal adapter on graph/event for T02). - Shared cya profile contract (markitect.memory.profile.v1) for assistance prefs. - Standardized provenance envelope for cya explain rendering. - T04: memory signals must still trigger mandatory confirmation for dangerous commands. - T05/T06: fake adapter for tests, docs with before/after, State Hub extension points. **References:** phase-memory/docs/{architecture.md, markitect-interop.md, lifecycle-rules.md, local-persistence.md, ports.py, planner.py}; cya src/cya/memory/__init__.py (seam), orchestrator.py; CYA-WP-0002 T02–T06; MemoryVision success criteria. ## What CYA-WP-0003 Delivered (Contextual Activation + Retrospection) **Date:** 2026-05-27 0003 moved memory from "real but mostly passive" to **proactively useful and user-steerable over time**. ### Key Additions - **Directory / Project-bound Memory Activation (T03)** Memory is now automatically activated based on the current working directory and git root. The orchestrator passes `activation_context`, and `recall_preferences` boosts relevant items. Activation is fully visible in `--explain-context` with provenance. - **Retrospection as a First-Class Interaction Pattern (T04)** Added the `cya retrospect` subcommand — a guided terminal reflection session. Users review recent memory usage, reflect, and explicitly record: - Interaction goals - Refined preferences - Safety rules These are stored with special kinds (`retrospection`, `interaction_goal`) and get preferential treatment in future activations. - **Port & Data Model Extensions (T02)** - `kind` parameter on `remember_preference` - `activation_context` support on `recall_preferences` - `remember_retrospection_outcome()` helper - Improved `export_memory` with kind filtering and `by_kind` summary - Full backward compatibility maintained. - **Tests & Observability (T05)** Comprehensive tests for activation boosting, retrospection records, provenance, and graceful degradation. ### Impact A user can now: - Teach `cya` once in a project and have it automatically remember those preferences. - Run `cya retrospect` periodically to steer how the assistant behaves in the future. - See exactly which memories influenced any response. These features directly realize the "Personalized Console Helper" and "continuous optimization" vision from INTENT.md while staying within the explicit port seam. **Next logical deepening:** When `phase-memory` exposes stable high-level activation + profile APIs, the local JSON implementation can be replaced while keeping the same user experience and `cya retrospect` flow. --- This document is distinct from the Intent-vs-Scope gap analysis. It is the forward-looking vision for how memory will evolve in `cya` once real `phase-memory` integration begins. It should be updated as integration work progresses and as phase-memory itself matures.