can-you-assist/workplans/CYA-WP-0002-memory-integration-roadmap.md

id, type, title, domain, repo, status, owner, topic_slug, created, updated, state_hub_workstream_id

id	type	title	domain	repo	status	owner	topic_slug	created	updated	state_hub_workstream_id
CYA-WP-0002	workplan	Memory Integration Roadmap: From Thin Ports to Profile-Driven phase-memory Backing	capabilities	can-you-assist	active	grok	foerster-capabilities	2026-05-26	2026-05-26	ef676f87-97f4-4635-a80d-4065730df87f

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

id: CYA-WP-0002-T01
status: done
priority: high
state_hub_task_id: "d79840e3-2b24-48be-aac6-a8ed505153d4"
started: "2026-05-26 ralph iter 1"
completed: "2026-05-26"

Done in ralph iter 1.

• Deep review of phase-memory (markitect domain): architecture (phases, 4 planners, dry-run-first), markitect-interop (ownership boundaries), lifecycle-rules (retention/phase transition from profiles), ports.py (MemoryGraphStore, EventLog, PolicyGateway, etc.), package structure (planner, runtime, service, adapters).
• 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).

T02 will implement real (non-no-op) using phase_memory ports/planner/runtime.

T02 — Implement real (non-no-op) memory port implementations in cya

id: CYA-WP-0002-T02
status: todo
priority: high
state_hub_task_id: "8bb93e26-0b2c-4ea7-8af0-6e70ca969b52"

• Replace or extend the T05 no-op ports with real calls into phase-memory (via its runtime or adapters).
• Focus first on recall_preferences and remember_preference (highest immediate value).
• Add basic support for project/directory scoped memory.
• Ensure graceful degradation when phase-memory is not available.

Acceptance criteria:

• cya can actually recall and persist simple preferences across invocations.
• Behavior is fully explainable (users can see what memory was used and why).

T03 — Wire memory into the orchestrator and response pipeline

id: CYA-WP-0002-T03
status: todo
priority: high
state_hub_task_id: "76c091c3-4978-48f1-996e-62a5fdbb6f12"

• Update orchestrator.py to consult memory ports when building AssistanceRequest.
• Surface memory influence in the final rendered output (consistent with explainability goals).
• Handle memory-related safety implications (e.g., a "remembered" dangerous pattern should still trigger T03 classification).

Acceptance criteria:

• At least one realistic workflow shows measurable improvement due to memory (e.g., user no longer has to restate preferences).
• Memory usage is visible in --explain-context or equivalent.

T04 — Update safety & risk layer for memory signals

id: CYA-WP-0002-T04
status: todo
priority: medium
state_hub_task_id: "bc77e793-b453-46b4-9442-4461af1ef43d"

• Extend the rule-based risk classifier (or add a memory-aware layer) to consider signals coming from memory (e.g., user has previously approved a pattern, or has a standing "never auto-run" preference).
• Ensure memory cannot be used to bypass safety.

Acceptance criteria:

• Memory-influenced suggestions still respect the mandatory confirmation rules.
• Tests cover memory + safety interaction.

T05 — Tests, observability, and graceful degradation

id: CYA-WP-0002-T05
status: todo
priority: high
state_hub_task_id: "d30f159c-3459-4c7b-ba31-990a73deaffb"

• Expand the test suite (building on T07) with memory-specific tests (in-memory fake phase-memory adapter, profile scenarios, error cases).
• Add basic observability (e.g., "memory used: X items, Y tokens").
• Ensure the experience remains excellent even when memory is disabled or unavailable.

Acceptance criteria:

• New memory behavior has strong test coverage.
• pytest still passes cleanly; no new external dependencies for the default test run.

T06 — Documentation, examples, and handoff

id: CYA-WP-0002-T06
status: todo
priority: medium
state_hub_task_id: "90e31eff-6ef7-4638-83d1-26bb64249862"

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

Activation & Ralph Execution

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.

References

• MemoryVision.md
• history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md
• CYA-WP-0001 (especially T05)
• ~/phase-memory/docs/ (architecture, markitect-interop, lifecycle-rules, etc.)
• src/cya/memory/__init__.py (current ports)

---

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.