can-you-assist/MemoryVision.md

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/<scope>.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).

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.