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: done
priority: high
state_hub_task_id: "8bb93e26-0b2c-4ea7-8af0-6e70ca969b52"
started: "2026-05-26 ralph iter 2 (after T01)"
completed: "2026-05-26"

Done in ralph iter 2 (verified).

• Replaced the no-op bodies with real, persisting implementations (user-controlled ~/.config/cya/memory/.json ; typed for future phase_memory.models migration).
• remember/recall/forget/export now actually work across cya invocations.
• Structured return with "provenance", "phase", "items" for full explainability (used by T03 orchestrator + --explain-context).
• Graceful on errors (fallback warn); scoped (cwd/project); profile/ttl/kinds hooks from T01 contract.
• Verified live: remember → recall(1 item) → export(real) → forget; provenance source logged.

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

T03 — Wire memory into the orchestrator and response pipeline

id: CYA-WP-0002-T03
status: done
priority: high
state_hub_task_id: "76c091c3-4978-48f1-996e-62a5fdbb6f12"
started: "2026-05-26 ralph iter 3 (after T02)"
completed: "2026-05-26"

Done in ralph iter 3 (verified wiring).

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

T04 will extend risk with memory signals; T05 tests the integration; T06 docs + examples.

T04 — Update safety & risk layer for memory signals

id: CYA-WP-0002-T04
status: done
priority: medium
state_hub_task_id: "bc77e793-b453-46b4-9442-4461af1ef43d"
started: "2026-05-26 ralph continuation (after T03)"
completed: "2026-05-26"

Done (verified).

• Extended classify() (backward-compatible memory: dict | None param) + added _apply_memory_signals helper.
• Memory signals can append rationale / force requires_confirmation=True for matching "never" prefs.
• Hard invariant preserved: memory never downgrades a non-SAFE level or clears confirmation (proven by test).
• Wired the call in orchestrator (T03 already had memory in scope).
• Live verification: destructive + "never_auto_run" memory → still requires confirmation; approved signals add friendly note only.

Acceptance criteria met (and the core safety promise strengthened).

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.