# CYA-WP-0002: Memory Integration Roadmap — From Thin Ports to Real phase-memory Backing
## Goal
Move `cya` from the strictly minimal no-op memory ports delivered in CYA-WP-0001 (T05) toward concrete, valuable integration with `phase-memory`.
Deliver at least one or two real memory capabilities (user preferences + basic project/directory memory) that demonstrably improve the quality and personalization of assistance, while establishing the technical and organizational patterns needed to realize the full **MemoryVision.md**.
This workplan directly addresses the largest gap identified in the Intent-vs-Scope analysis: the disconnect between INTENT.md's strong emphasis on user-controlled, longitudinal memory and the current thin implementation.
## Background & References
- **MemoryVision.md** (newly created) — the target vision.
-`history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md` — documents the memory gap as the biggest divergence.
- CYA-WP-0001 T05 — the current thin ports that must be evolved (not replaced wholesale).
- phase-memory architecture (see ~/phase-memory/docs/architecture.md, markitect-interop.md, etc.).
- Existing ports in `src/cya/memory/__init__.py`.
## Non-Goals (for this slice)
- Full realization of every memory kind in MemoryVision.md.
- Building or forking phase-memory functionality.
- Deep repository indexing or embeddings (still out of scope per original MVP non-goals).
- Voice or non-terminal memory experiences.
- Complete profile authoring tooling inside cya (we can consume profiles created elsewhere).
## Task Breakdown
### T01 — Review current phase-memory state and refine integration contract
- Current cya thin ports (src/cya/memory/__init__.py) confirmed as the seam.
- Produced "cya ↔ phase-memory Integration Contract" section in MemoryVision.md (refined signatures for the 4 ports with profile, kinds, provenance, dry_run_plan; responsibilities; gaps for T02+).
- Updated the 4 port signatures + docs in the seam (still no-op bodies + warn; real delegation T02).
**Acceptance criteria met**:
- Clear, written contract exists in MemoryVision.md and is the authoritative reference for this integration.
- Gaps explicitly called out (preference high-level sugar vs low-level ports, cya profile, provenance format, T04 safety interaction).
**Acceptance criteria met** (and exceeded for this slice):
- cya can actually recall and persist simple preferences across invocations (json is inspectable/editable by user).
- Behavior fully explainable (provenance + phase in every recall/export).
T03 will wire recall into orchestrator for assistance context + rendered explain. Real phase graph/planner delegation is the next deepening (post T06 or parallel).
- Updated orchestrator.py: import + consult recall_preferences(".") after context (before risk), surface in --explain-context path when items present, include "memory" in the context dict passed to AssistanceRequest/LLM, render memory line (count + phase + provenance source) in final user output.
- Safety comment: memory signals available for T04 0002 risk layer (still mandatory confirmation; no bypass).
- Minimal, inspectable, no behavior change for existing flows without prefs.
**Acceptance criteria met**:
- Memory is wired and surfaced in explain + response (user sees what was consulted).
- Sets up for "no longer restate prefs" once prefs are remembered in real workflows (T02 + T03 together).
- Heavily update README and add Memory section with real before/after examples.
- Update AGENTS.md and MemoryVision.md with lessons learned.
- Register new extension points and any technical debt in State Hub (via the workplan).
- Produce clear integration guide for phase-memory owners.
**Acceptance criteria**:
- A reader of the README can understand and exercise the new memory features.
- Sibling teams have clear documentation on the integration points.
## Dependencies & Cross-Repo Coordination
- **phase-memory**: Must be sufficiently mature (ports + basic runtime) for real integration. Any required work on their side must be coordinated early.
- **markitect-tool**: Likely needed for profile contracts if we want to go beyond hard-coded behavior.
- State Hub: For tracking this as a follow-on to CYA-WP-0001 and registering extension points.
**Status: active** — ralph-workplan loop initialized (HEUREKA promise, max 20 iterations) to drive all 6 tasks to completion. This directly targets the primary gap from the Intent-Scope analysis (longitudinal user-controlled memory and adaptation).
**Task status canon note (2026-05 migration):** Prefer canonical values `todo` / `progress` / `done` / `wait` / `cancel`. Legacy aliases accepted during window; AGENTS.md and workplans will be modernized in T06.
**Status note**: Created immediately after the MemoryVision and gap analysis work. This is the direct follow-on workplan to CYA-WP-0001 focused on closing the largest identified gap.
