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.

---

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.