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

---

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.