Files

tegwick b7a2cc48ba chore(docs+tests): complete T05 + T06 for CYA-WP-0002. All 6 tasks done. README Memory section, AGENTS update, full test coverage for real memory + safety. Workplan retired.

2026-05-26 07:01:12 +02:00

9.8 KiB

Raw Permalink Blame History

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	done	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: 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

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.

9.8 KiB Raw Permalink Blame History Unescape Escape