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.

---

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