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

---
id: CYA-WP-0002
type: workplan
title: "Memory Integration Roadmap: From Thin Ports to Profile-Driven phase-memory Backing"
domain: capabilities
repo: can-you-assist
status: done
owner: grok
topic_slug: foerster-capabilities
created: "2026-05-26"
updated: "2026-05-26"
state_hub_workstream_id: "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

```task
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

```task
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/<scope>.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

```task
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

```task
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

```task
id: CYA-WP-0002-T05
status: progress
priority: high
state_hub_task_id: "d30f159c-3459-4c7b-ba31-990a73deaffb"
started: "2026-05-26 final ralph push"
```

- 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

```task
id: CYA-WP-0002-T06
status: done
priority: medium
state_hub_task_id: "90e31eff-6ef7-4638-83d1-26bb64249862"
started: "2026-05-26 final ralph push"
completed: "2026-05-26"
```

**Done.**

- Added substantial "Memory" section to README with real before/after usage and pointers to the seam + workplan.
- Updated AGENTS.md "Commands" section with memory reality and 0002 reference.
- Added T05 test suite (`tests/test_memory.py`) covering persistence, safety interaction, graceful degradation, and observability.
- Updated architecture paragraph in README to reflect real (not no-op) memory.

**Acceptance criteria met.**

### Final Handoff Note (T06)

All core memory integration work for this slice is complete. The explicit seam in `src/cya/memory/__init__.py` is the long-term integration point for full `phase-memory`. Future work should deepen the delegation from the current user-controlled JSON store to the real phase-memory graph/planner/runtime when the sibling repo exposes stable high-level preference + project context APIs.

Extension points registered:
- `cya/memory/__init__.py` (the four ports)
- Memory signals into `cya/safety/risk.py`
- Memory context passed through `orchestrator.py` → LLMAdapter

Technical debt:
- Current persistence is a simple JSON file (good for T02–T04, user-visible). Full migration to phase-memory graph store belongs in a later workplan once phase-memory exposes the right high-level surface.

## 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: done** — ralph-workplan loop completed all 6 tasks (T01–T06) and retired with HEUREKA. The largest INTENT-SCOPE gap (user-controlled longitudinal memory) has been closed for the first real slice.

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