feat(memory) + docs: T01 complete — cya/phase-memory integration contract (MemoryVision), refined port signatures in seam (no-op preserved), phase-memory (arch/interop/lifecycle/ports) review; workplan T01 marked done. ralph iter 1.

MemoryVision.md

@@ -108,4 +108,66 @@ This is the correct starting point. Real integration will be done as a subsequen
 
 ---
 
+## 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.
+
+---
+
 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.