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	proposed	grok	foerster-capabilities	2026-05-26	2026-05-26	null

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: todo
priority: high

• Deep review of current phase-memory implementation, ports, profiles, phases, and activation/lifecycle planners (as of late May 2026).
• Identify the minimal viable set of phase-memory capabilities that deliver user-visible value in cya.
• Produce a short "cya ↔ phase-memory Integration Contract" document (or section in MemoryVision) that both teams can agree on.
• Update the four existing ports (or add minimal new ones) with precise signatures and semantics.

Acceptance criteria:

• Clear, written contract exists and is reviewed by relevant owners.
• Any gaps or required phase-memory work are explicitly called out.

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

id: CYA-WP-0002-T02
status: todo
priority: high

• 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

• 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

• 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

• 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

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

Proposed Status & Activation

This workplan is created in proposed status. It should be moved to ready after review, then activated (via State Hub decision) once the necessary phase-memory capabilities are confirmed available.

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.