coulomb/can-you-assist
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(memory): add MemoryVision.md + gap analysis and related doc updates

Browse Source 
- 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:
Bernd Worsch
2026-05-26 02:42:54 +02:00
parent ece0453f12
commit f93b766e12
5 changed files with 351 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
AGENTS.md
View File

@@ -166,20 +166,28 @@ First useful worker moves:
## Commands
The repo is currently an intent/document seed. There is no build or test
system yet.
Useful inspection commands:
```bash
rg --files
sed -n '1,240p' INTENT.md
# Install (editable, for development)
pip install -e .
# Run the assistant
cya "your natural language request here"
cya --help
cya --explain-context "show me what context would be collected"
# Tests (safety-focused, no LLM required)
python -m pytest tests/ -q
# or: pytest tests/ -q
# Git / inspection (always useful)
git status --short
git log --oneline -5
rg --files
```
When implementation starts, update this section with the package manager,
build, test, lint, and local run commands.
No formal lint or build system yet (ruff is configured in pyproject.toml but not enforced in CI for the first slice). Add `make test` / `make lint` targets in a follow-on when needed.
Current primary entry point: `cya` (after editable install).
## Workplan Convention

111
MemoryVision.md Normal file
View 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.

113
SCOPE.md
View File

@@ -2,45 +2,98 @@
## Purpose
`can-you-assist` provides `cya`, a console-native LLM helper for practical
local work. It lets a terminal user ask for help in natural language, gather
relevant local context intentionally, and receive safe, explainable assistance
for command-line, repository, filesystem, note, and text workflows.
`can-you-assist` provides the `cya` command — a console-native, backend-agnostic LLM assistant for practical local work.
It allows users to express intent in natural language from the terminal and receive safe, explainable, context-aware assistance while keeping memory, history, preferences, and adaptation under explicit user control.
## Current Status (Post MVP Slice)
The first narrow implementation slice (CYA-WP-0001) has been delivered. A working `cya` tool now exists that can be installed with `pip install -e .`.
Core capabilities implemented:
- Natural language request handling via a clean Typer CLI.
- Bounded, transparent, non-recursive local context collection (cwd + git + environment + explicit files).
- Genuine rule-based risk classification with mandatory terminal confirmation for anything above "safe".
- Stable `LLMAdapter` Protocol boundary (currently satisfied by a deterministic `FakeLLMAdapter`).
- Strictly minimal explicit no-op ports for future `phase-memory` integration.
- A small orchestrator that coordinates the above.
All LLM interaction flows through the documented adapter seam. No production path bypasses it.
## Owns
- The `cya` command-line user experience.
- Intent parsing and task framing for local shell work.
- Local context collection from the current directory, selected files, stdin,
git state, logs, notes, and user-provided paths.
- Safe command suggestion and explanation workflows.
- Prompt/request orchestration against `llm-connect`.
- Local preference and memory usage through `phase-memory`.
- Transparent configuration and inspectable local state for this assistant.
- The `cya` command-line user experience and argument parsing.
- Intent framing and high-level task classification for console work.
- Local context collection (current directory, git state, selected files, stdin, minimal environment facts).
- Safety layer: rule-based risk assessment + mandatory explicit confirmation flow.
- Orchestration of the request → context → safety → LLM adapter → response pipeline.
- The stable `LLMAdapter` Protocol and the contract for how `cya` talks to LLM backends.
- Explicit, minimal integration points (ports) for `phase-memory`.
- Transparent, inspectable behavior (especially via `--explain-context`).
- User-facing documentation, examples, and safety guarantees for the CLI tool.
## Does Not Own
- Provider-specific LLM clients or vendor credentials; that belongs in
`llm-connect`.
- Long-term memory storage semantics; that belongs in `phase-memory`.
- Global State Hub implementation or workstream indexing.
- Autonomous shell execution without clear user confirmation.
- Hidden, vendor-owned personalization or opaque memory.
- Any specific LLM provider, API client, or model hosting (belongs to `llm-connect`).
- Durable memory storage, preference models, history semantics, or adaptation algorithms (belongs to `phase-memory`).
- Global work tracking, decisions, or cross-repo coordination (belongs to State Hub / custodian).
- Autonomous or background execution of commands without explicit user confirmation.
- Deep repository indexing, embeddings, or large-scale content analysis (explicit non-goal of the first slice).
- Voice, speech, phone-bridge, or non-terminal interfaces (future work).
- Packaging, distribution, or multi-platform installers beyond basic editable install.
- Long-lived conversational REPL or session state (one-shot + very lightweight session only).
## Integrates With
- `llm-connect` for backend-agnostic model access.
- `phase-memory` for user-controlled history, preferences, and adaptation.
- State Hub for work tracking, repo coordination, progress, and decisions.
| Project | Responsibility | Integration Style |
|---------------|-----------------------------------------|------------------------------------|
| `llm-connect` | Provider access, config, token counting, structured responses | Stable `LLMAdapter` Protocol |
| `phase-memory`| User-controlled memory, preferences, history | Explicit thin ports (currently no-op) |
| State Hub | Work tracking, decisions, coordination | HTTP REST (non-runtime) |
## Initial Direction
## MVP Scope (CYA-WP-0001)
The first implementation slice should establish a minimal but real CLI:
What was explicitly in scope for the first slice:
- parse a natural-language request;
- inspect current working-directory context safely;
- produce an explainable command or answer;
- route LLM calls through an adapter boundary shaped for `llm-connect`;
- leave memory hooks explicit but thin until `phase-memory` integration is
ready;
- include tests around command-suggestion safety and context selection.
- A functional `cya` CLI that accepts natural language requests.
- Safe, bounded context collection with full transparency (`--explain-context`).
- Rule-based safety classification as the primary mechanism, with mandatory confirmation.
- A clean, documented adapter boundary for future real LLM backends.
- Strictly minimal memory ports (no hidden state, no local JSON store).
- Basic orchestrator that ties the pieces together.
- Test coverage focused on safety invariants and context rules.
- Clear public boundaries and extension points.
## Explicitly Out of Scope (MVP and Near-Term)
- Any durable or sophisticated memory implementation.
- Real `llm-connect` client (only the contract + fake exists).
- Deep git/repository understanding beyond basic status + log.
- Automatic command execution (even "safe" suggestions).
- Structured editing / patch generation.
- Multi-turn conversation state.
- Cost tracking, token budgeting, or usage dashboards.
- Team/shared memory or collaboration features.
- Plugin system or domain-specific extensions.
## Extension Points (Registered)
- `cya/llm/adapter.py` — `LLMAdapter` Protocol (the primary seam).
- `cya/memory/__init__.py` — the four explicit ports (`remember_preference`, `recall_preferences`, `forget`, `export_memory`).
- `cya/safety/risk.py` — the `_RULES` table and `classify()` function.
- `cya/context/collector.py` — collection functions and ignore policy.
- `cya/orchestrator.py` — the main coordination entry point.
## Success Criteria (Current Slice)
A new user can:
- Clone the repo, run `pip install -e .`, and successfully use `cya` for 2–3 realistic tasks after reading only the README.
- Understand exactly what context is being sent via `--explain-context`.
- Trust that dangerous actions will never execute without explicit confirmation.
- See a clear path for how real `llm-connect` and `phase-memory` will plug in later.
Sibling project owners can read the workplan + boundary documentation and know precisely where their packages integrate.
---
**This SCOPE document reflects the state after the CYA-WP-0001 MVP slice.** It is intentionally narrower than the long-term vision in INTENT.md.

111
history/2026-05-26-CYA-Intent-Scope-Gap-Analysis.md Normal file
View File

@@ -0,0 +1,111 @@
# Gap Analysis: INTENT.md vs SCOPE.md (Post CYA-WP-0001 MVP)
**Date:** 2026-05-26
**Repo:** can-you-assist
**Workplan:** CYA-WP-0001 (completed)
**Author:** Grok (in ralph loop)
## Executive Summary
The original INTENT.md describes an ambitious, long-term vision for a personalized, memory-aware, console-native LLM assistant with strong user control and adaptation over time.
The current SCOPE.md (updated after the MVP slice) and the delivered implementation (T01–T08) are much narrower and more disciplined. This is largely healthy and intentional, but creates several significant gaps against the original intent — particularly around memory and longitudinal value.
## Strong Alignments
| Area | INTENT.md Position | Current Reality (SCOPE + Implementation) | Assessment |
|-----------------------------|---------------------------------------------|---------------------------------------------------|----------|
| Console-native experience | Foundational | Excellent (Typer + rich, one-shot + explain) | Strong match |
| Safety & confirmation | Important (explicit confirmation) | Core product behavior (rule-based + mandatory) | Exceeded intent |
| Explainability & transparency | Strong requirement | Very well delivered (`--explain-context`, provenance) | Strong match |
| Backend agnosticism | Must route through llm-connect | Clean LLMAdapter Protocol + Fake (zero bypass) | Excellent |
| Clear repo boundaries | cya / llm-connect / phase-memory separation | Clearly documented and implemented | Very good |
| User control | Central principle | Respected (especially memory ports) | Good |
## Key Gaps
### 1. Memory & Adaptation (Largest Divergence)
**INTENT.md** repeatedly positions memory as central to long-term value:
- "keep the memory, history, preferences, and adaptation under the user’s control"
- The tool should "become more useful through memory"
- Support for recurring workflows, project-specific memory, learned patterns, preferences over time
- Explicit relationship to `phase-memory` as a first-class partner
**Current SCOPE / Delivered**:
- T05 deliberately implemented the thinnest possible no-op ports only.
- No accumulation of value across sessions.
- Real adaptation, recipes, project profiles, etc. are future work.
**Gap Type**: Intentional narrowing for the first slice, but this is the biggest deviation from the spirit of the original intent. The memory story is currently the weakest link relative to INTENT.
### 2. Depth of Local Context Understanding
**INTENT.md** envisions rich assistance with:
- Code repositories ("where is the CLI entry point?", "suggest a safe first refactoring")
- Local notes and knowledge work
- Project structures and conventions
**Current Implementation**:
- Context collector is intentionally shallow (top-level entries only, no recursion, minimal git understanding beyond basic status).
**Gap Type**: Medium to large. The tool currently functions more as a "safe, context-aware command suggester" than a deep repository or knowledge assistant.
### 3. One-Shot vs Longitudinal Value
**INTENT.md**:
- Strong emphasis on the assistant learning the user's habits, conventions, aliases, and recurring patterns over time.
- "Personalized console helper"
**Current Reality**:
- The MVP is almost entirely one-shot (with optional context explanation).
- Very little mechanism yet for the assistant to improve for a specific user or project across uses.
**Gap Type**: Large. This is one of the core long-term differentiators described in INTENT.
### 4. Safety Implementation (Positive Gap)
**INTENT.md**: Safety and confirmation are mentioned but relatively lightly sketched.
**Current SCOPE**: Genuine rule-based assessment as the *primary* mechanism, with structured output designed to be fed to the LLM, plus mandatory confirmation. This is more mature and product-like than the original intent.
**Assessment**: Positive. The current implementation strengthened this area beyond the initial vision (per explicit operator direction during stack review).
### 5. Test Coverage and Trust
- INTENT implies the tool must be trustworthy for real daily workflows.
- T07 delivered solid safety-invariant and collector tests.
- However, full orchestrator + adapter contract testing and end-to-end scenarios are still relatively light compared to what long-term trust would require.
## Summary Table
| Dimension | INTENT Ambition | Current SCOPE Reality | Gap Size | Nature |
|---------------------------|-------------------------------------|----------------------------------------|--------------|--------|
| Memory & Adaptation | Central long-term differentiator | Minimal explicit no-op ports only | Large | Intentional narrowing |
| Depth of context | Repository + notes understanding | Shallow top-level collector | Medium-Large | Scope control |
| Longitudinal value | Learns workflows over time | Strong one-shot experience | Large | Future work |
| Safety | Important | Core rigorous product behavior | Positive | Exceeded |
| Boundaries & seams | Clear separation | Very clearly defined + implemented | Small | Well aligned |
| Console-native + explainable | Strong | Strongly delivered | Small | Well aligned |
## Recommendations
1. **Keep the narrow SCOPE** for the near term — it is healthy and prevents scope creep.
2. **Memory Integration Roadmap** — The single most important piece of future work to align with INTENT. Consider creating a dedicated `MemoryVision.md` (or similar) that bridges the current thin ports to the richer phase-memory concepts (profiles, phases, activation planning, etc.).
3. **Depth vs Breadth Tradeoff** — Decide explicitly whether the next slices should deepen context understanding (better git + file understanding) or prioritize the memory story.
4. **Elevate Safety** — The current rule-based safety layer is one of the project's strongest differentiators. It may deserve more prominent treatment in both INTENT and SCOPE over time.
5. **Test Maturity** — As we move beyond the first slice, T07-style safety tests should be complemented by stronger contract and orchestrator tests to support the trust claims in INTENT.
---
**Source Documents**:
- Original INTENT.md
- Updated SCOPE.md (post CYA-WP-0001)
- CYA-WP-0001-console-native-mvp.md (especially Non-Goals and T05/T08)
- Delivered implementation (src/cya/memory, safety, orchestrator, etc.)
This analysis was generated as part of closing the first ralph-workplan loop.

31
workplans/CYA-WP-0001-console-native-mvp.md
View File

@@ -4,12 +4,13 @@ type: workplan
title: "Console-Native MVP: CLI Skeleton, Safe Assistance Flow, and Integration Boundaries"
domain: capabilities
repo: can-you-assist
status: active
status: finished
owner: grok
topic_slug: foerster-capabilities
created: "2026-05-25"
updated: "2026-05-26"
state_hub_decision_id: "a644364b-11c4-49a9-bf17-99063382e27b"
state_hub_workstream_id: "a3ef5a46-17be-41a9-8df8-f457d86462da"
---
# CYA-WP-0001: Console-Native MVP — CLI Skeleton, Safe Assistance Flow, and Integration Boundaries
@@ -96,6 +97,7 @@ This workplan establishes the CLI surface, context collector, safety layer, and
id: CYA-WP-0001-T01
status: done
priority: high
state_hub_task_id: "716a8679-39b1-4b99-a2d4-44b1f5076f9e"
```
Bootstrap the minimal runnable package and the primary user-facing command.
@@ -122,6 +124,7 @@ Bootstrap the minimal runnable package and the primary user-facing command.
id: CYA-WP-0001-T02
status: done
priority: high
state_hub_task_id: "349dc524-56ca-4f4f-a7a9-7afbca35c166"
```
Implement the "Context Collector" responsibility described in INTENT.md and SCOPE.md.
@@ -152,6 +155,7 @@ Hard constraints for this slice:
id: CYA-WP-0001-T03
status: done
priority: high
state_hub_task_id: "28306063-cfb5-4049-ab45-365526bd3e28"
```
This is a core product behavior, not an afterthought.
@@ -185,6 +189,7 @@ Never auto-execute anything in this slice, even "safe" suggestions, unless the u
id: CYA-WP-0001-T04
status: done
priority: high
state_hub_task_id: "54b32952-6a92-4ee6-8688-3ca7de026d8a"
```
Per SCOPE.md and INTENT.md, `can-you-assist` owns orchestration and the CLI experience; `llm-connect` owns provider access.
@@ -214,6 +219,7 @@ Define a small, stable interface (protocol / abstract base / typed call) in this
id: CYA-WP-0001-T05
status: done
priority: medium
state_hub_task_id: "134065b5-3421-4353-80b4-9a55b5a2015e"
```
Prepare the ground for `phase-memory` without pulling a dependency or inventing hidden state.
@@ -244,6 +250,7 @@ All memory interactions must be behind these ports. No global singletons, no imp
id: CYA-WP-0001-T06
status: done
priority: high
state_hub_task_id: "26146d92-e1c9-462c-9721-f50c5c37f5a4"
```
The piece that turns raw user intent + collected context into a well-formed request to the LLM adapter and then turns the adapter response into terminal output the user can act on.
@@ -266,6 +273,7 @@ The orchestrator must be testable in isolation with a fake LLM adapter.
id: CYA-WP-0001-T07
status: done
priority: high
state_hub_task_id: "71bd300a-0049-4e4d-9ea3-c75546a2b5c6"
```
Choose and bootstrap a test framework appropriate for a console tool (pytest is the obvious default given the Python signal).
@@ -288,8 +296,9 @@ Prefer fast, hermetic, no-network tests as the default. Any test that touches a
```task
id: CYA-WP-0001-T08
status: in_progress
status: done
priority: medium
state_hub_task_id: "d51801b1-2184-4ec5-91c1-b5b535dcef6a"
```
Make the MVP usable and the integration points obvious.
@@ -330,6 +339,24 @@ Once the stack review is complete, change the workplan `status` to `active` and
- State Hub consistency command (run after any workplan or task file change):
`cd ~/state-hub && make fix-consistency REPO=can-you-assist`
## Extension Points & Technical Debt (T08 note)
**Obvious extension points registered during the slice:**
- `cya/llm/adapter.py` — the `LLMAdapter` Protocol (primary seam for llm-connect).
- `cya/memory/__init__.py` — the four explicit no-op ports (primary seam for phase-memory).
- `cya/safety/risk.py` — the `_RULES` table (easy to extend with new patterns).
- `cya/context/collector.py` — the ignore policy and collect_* functions.
- `cya/orchestrator.py` — the single `handle_request` entry point.
**Technical debt / follow-on notes (for State Hub registration):**
- No real lint/CI enforcement yet (ruff configured but not wired).
- No `make` targets or formal test/lint scripts beyond raw `pytest`.
- README mentions USAGE but a dedicated short USAGE.md could be added later.
- The fake adapter responses are intentionally simplistic; richer canned scenarios can be added in T07 follow-ups.
- Confirmation flow is terminal-only (correct per spec); future voice bridge will need the same contract.
These items are captured here per T08 acceptance criteria and can be turned into State Hub extension-point or debt records after `fix-consistency`.
---
**Status note**: Created as the direct output of bootstrap Task T02. This file is the authoritative plan. Do not implement the tasks until the status is moved to `active` after stack review.