generated from coulomb/repo-seed
docs(memory): add MemoryVision.md + gap analysis and related doc updates
- New MemoryVision.md outlining long-term vision for phase-memory integration in cya (profiles, phases, lifecycle, ports) - Persisted full Intent-vs-Scope gap analysis in history/ - Updated SCOPE.md to reflect post-MVP reality and MemoryVision direction - Minor cross-references in AGENTS.md and the CYA-WP-0001 workplan This lays the foundation for the next workplan (CYA-WP-0002) focused on realizing the MemoryVision. Refs: MemoryVision.md, history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md, CYA-WP-0001 T05/T08
This commit is contained in:
111
MemoryVision.md
Normal file
111
MemoryVision.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# Memory Vision for can-you-assist (cya)
|
||||
|
||||
**Status:** Initial vision (post CYA-WP-0001)
|
||||
**Date:** 2026-05-26
|
||||
**Related Work:** CYA-WP-0001 T05 (minimal ports), phase-memory architecture, INTENT.md
|
||||
|
||||
## Guiding Principle
|
||||
|
||||
> The user’s working memory must belong to the user — not to any assistant interface, vendor, or opaque system.
|
||||
|
||||
`cya` must never become a memory silo. All memory, history, preferences, and adaptation behavior must flow through explicit, inspectable ports provided by `phase-memory`.
|
||||
|
||||
## Relationship to phase-memory
|
||||
|
||||
`phase-memory` is the **profile-driven memory operating layer** for the broader ecosystem. It is responsible for:
|
||||
|
||||
- Interpreting **Markitect memory profiles** as executable runtime plans.
|
||||
- Modeling memory in distinct **phases**:
|
||||
- `ephemeral` — short-lived, high-turnover (e.g., current conversation window)
|
||||
- `fluid` — recent but still malleable context
|
||||
- `stabilized` — reviewed and relatively durable knowledge/preferences
|
||||
- `rigid` — high-confidence, long-term, rarely changing (core identity, strong conventions)
|
||||
- Planning and executing (or dry-running) **lifecycle actions**:
|
||||
- Retention
|
||||
- Refresh
|
||||
- Compaction
|
||||
- Stabilization
|
||||
- Activation (under token/item budgets)
|
||||
- Policy, audit, and review gates around memory changes.
|
||||
|
||||
`cya` is a **consumer** of this layer. It does **not** own memory semantics, storage, or lifecycle policy.
|
||||
|
||||
## How cya Will Use Memory
|
||||
|
||||
`cya` will treat memory as a first-class, explainable input to every assistance cycle, while keeping ownership and control firmly with the user (via phase-memory).
|
||||
|
||||
### Primary Memory Kinds Relevant to cya
|
||||
|
||||
- **Conversation / Interaction History** — primarily fluid/ephemeral
|
||||
- **Learned Preferences & Conventions** — stabilized over time (command style, safety tolerance, explanation depth, shell aliases, etc.)
|
||||
- **Project / Directory Memory** — stabilized or rigid context specific to a working directory or repository
|
||||
- **Workflow Recipes & Patterns** — stabilized reusable sequences the user has approved or refined
|
||||
- **Safety & Trust Signals** — rigid or stabilized (user-defined risk thresholds, trusted command patterns)
|
||||
- **Source Provenance** — metadata about where knowledge came from (files, git history, previous sessions)
|
||||
|
||||
### Integration Model (Building on T05 Ports)
|
||||
|
||||
The four explicit ports defined in T05 (`cya/memory/__init__.py`) are the permanent integration surface:
|
||||
|
||||
- `remember_preference(key, value, scope)`
|
||||
- `recall_preferences(scope, task_class)`
|
||||
- `forget(scope, keys)`
|
||||
- `export_memory(scope)`
|
||||
|
||||
Over time these will be wired to real `phase-memory` capabilities. `cya` will additionally:
|
||||
|
||||
1. **Produce structured memory events** (conversation turns, accepted suggestions, explicit user feedback, safety decisions) that phase-memory can ingest as fluid memory.
|
||||
2. **Request context packages** via phase-memory’s activation planning (respecting user-defined profiles and token budgets).
|
||||
3. **Surface memory influence** in responses — users should be able to see “this suggestion was shaped by your saved preference for concise git output + recent project conventions.”
|
||||
4. **Honor user-initiated lifecycle actions** (export, reset, compact, stabilize) exposed through the ports or dedicated `cya memory ...` subcommands in the future.
|
||||
|
||||
### Profile-Driven Behavior
|
||||
|
||||
In the longer term, users (or the system) will be able to supply or generate **Markitect-compatible memory profiles** that tell phase-memory how `cya` should behave regarding their memory. Examples of profile intent that matter to cya:
|
||||
|
||||
- “Keep my last 30 days of shell interactions fluid, but stabilize any workflow I have used more than 5 times.”
|
||||
- “Treat everything in `~/notes/projects/` as stabilized by default, but require review before anything becomes rigid.”
|
||||
- “Aggressively compact conversational memory after 48 hours unless I mark it important.”
|
||||
- “Never let total activated context for a single `cya` request exceed 8k tokens without explicit approval.”
|
||||
|
||||
`cya` will request activation plans and context packages that respect these profiles.
|
||||
|
||||
## Safety and Explainability Requirements
|
||||
|
||||
Because memory directly influences suggestions:
|
||||
|
||||
- Every response that used non-ephemeral memory must be able to explain **which** memory items influenced it and why.
|
||||
- Memory-driven suggestions must still pass through the T03 risk classifier.
|
||||
- Users must be able to temporarily or permanently disable memory influence for a session or scope (`cya --no-memory ...` or equivalent).
|
||||
- Export and inspection of memory must be first-class and low-friction.
|
||||
|
||||
## Current State (Post MVP)
|
||||
|
||||
As of the end of CYA-WP-0001:
|
||||
|
||||
- Only the four thin no-op ports exist (T05).
|
||||
- No actual memory is persisted or recalled by `cya`.
|
||||
- The orchestrator and safety layer are ready to consume memory signals when they become available.
|
||||
- The architecture deliberately avoids any hidden or local-JSON fallback memory (per explicit operator direction).
|
||||
|
||||
This is the correct starting point. Real integration will be done as a subsequent slice, using the ports as the stable contract.
|
||||
|
||||
## Open Questions & Future Work
|
||||
|
||||
- How will `cya` generate or help users author memory profiles?
|
||||
- What is the right granularity for “project memory” vs global memory?
|
||||
- How should safety decisions and user overrides themselves become first-class memory citizens?
|
||||
- Can/should `cya` participate in compaction and stabilization planning, or should it only consume the results?
|
||||
- What observability (cost, token usage, memory influence) should be exposed at the CLI level?
|
||||
|
||||
## Success Criteria (Longer Term)
|
||||
|
||||
`cya` + `phase-memory` together are successful when a user can say:
|
||||
|
||||
- “This assistant actually knows my preferences and project conventions, but I can see exactly what it knows and change it whenever I want.”
|
||||
- “I switched LLM providers and my assistant still feels like *mine*.”
|
||||
- “I asked it to forget everything about project X last month, and it actually did.”
|
||||
|
||||
---
|
||||
|
||||
This document is distinct from the Intent-vs-Scope gap analysis. It is the forward-looking vision for how memory will evolve in `cya` once real `phase-memory` integration begins. It should be updated as integration work progresses and as phase-memory itself matures.
|
||||
Reference in New Issue
Block a user