v0.8.68 Memory: seed project-scoped recall ahead of the full backend

[Hmbown]

Problem

Current memory is mostly a user-scoped retained Markdown block. That is useful, but it does not give agents a lightweight per-project recall surface or a seed for project decisions/conventions before the full external-memory backend lands.

Scope

Build a small 0.8.68 seed that is compatible with the longer-term Moraine direction in #3495 without trying to implement all of #3495.

Target shape:

• Project-scoped memory files under CodeWhale state, keyed by workspace identity.
• remember can tag entries as user-global or project-scoped.
• At turn start, CodeWhale can recall a bounded project memory slice plus existing user memory.
• The recall path must be observable in /status, /memory, or equivalent diagnostics.

Likely Files

• crates/tui/src/tools/remember.rs
• crates/tui/src/memory.rs
• prompt/context assembly around memory injection or recall
• docs/MEMORY.md

Acceptance Criteria

• A project-scoped memory entry is retained separately from user-global memory.
• A later turn in the same workspace can recall the project entry without leaking it into unrelated workspaces.
• Memory recall has size bounds and does not silently dominate the system prompt.
• Docs explain the relationship to v0.8.66: Adopt Moraine as CodeWhale's memory backend (ingestion adapter + MCP recall) #3495 and make clear this is a local seed, not the final backend.

[Hmbown]

What exists today — and a tension with the documented Moraine direction worth resolving in the issue

While scoping this, I mapped the current memory surface:

• remember tool (crates/tui/src/tools/remember.rs:21-81): single input note, auto-approved (ApprovalRequirement::Auto, :60), writes via crate::memory::append_entry(path, note) (:72) to context.memory_path (an Option<PathBuf>; None = disabled). There is no scope/project parameter — the schema has exactly one field.
• crates/tui/src/memory.rs (307 lines): load() (:60), as_system_block() (:73, wraps in <user_memory source="…">, truncates at MAX_MEMORY_SIZE = 100 KiB, :55), compose_block() (:131), append_entry() (:143, writes - (YYYY-MM-DD HH:MM UTC) note).
• Injection is verbatim, whole-file, no retrieval. compose_block reads the entire file into one block. There is no recall/search/relevance logic anywhere today.
• Injection sites: core/engine.rs:854 (engine ctor) and :3274 (refresh_system_prompt), threaded through PromptSessionContext { user_memory_block } and rendered at prompts.rs:1390-1394.
• Path resolution: config/paths.rs:191-203 default_memory_path → primary ~/.codewhale/memory.md, legacy fallback ~/.deepseek/memory.md.

The Moraine tension this issue should resolve explicitly

memory.rs:1-44 is documented DEPRECATED (v0.8.66–v0.8.71) in favor of Moraine, and the documented direction is that recall comes from an external MCP server the user installs (moraine-cli + moraine-mcp), not a Rust backend. There is no Rust backend trait, no abstraction, no extension point for a recall backend today. MemoryConfig.moraine_fallback already exists (config.rs:1384), and prompts/memory_guidance.md:25-37 tells the model to use Moraine MCP tools (search_sessions, open, list_sessions, file_attention) if present in the catalog.

This issue asks for a local Rust seed (project-scoped file + bounded recall at turn start). That is not contradictory with Moraine, but the issue should be explicit that this is a bridge layer, not the Moraine replacement, so we do not end up with two parallel recall paths that Moraine then has to displace.

Suggested design to keep the seed Moraine-compatible

1. Project key from existing state. The workspace is already available on Config / engine.config.workspace (used at engine.rs:2431), so keying memory by project is feasible without new identity machinery.
2. Add an optional scope to remember ("user" | "project", default "user"). Project entries write to a per-project path under CODEWHALE_HOME (e.g. .codewhale/memory/projects/<slug>.md); user entries keep today's ~/.codewhale/memory.md.
3. Leave a recall trait seam. Even for the seed, structure the turn-start recall as fn recall(project_key, query) -> Vec<MemoryHit> (or similar) behind a trait, with a file-grep implementation now and a Moraine-via-MCP implementation later. This is the single design choice that prevents the bridge from becoming permanent dead weight.
4. Bounded injection. Keep the existing whole-file <user_memory> block for user-global (it is already size-capped at 100 KiB), add a separately size-bounded <project_memory> block, and surface both in /memory and /status per the issue's observability criterion. Naive substring/grep recall on the project file is enough for the seed; vector recall is Moraine's job.

What is genuinely new here

The retain side is a small extension (one parameter + one path). The genuinely-new logic is the recall bounding — deciding what subset of a project memory file is relevant to the current turn without dumping the whole file. For a seed, last-N-entries-matching-keywords is defensible; anything smarter should wait for Moraine so we do not build a retrieval engine we then throw away.

[hegu-1]

Project-scoped recall is the right intermediate step before a full backend, but I would avoid modeling it as just another retained Markdown block.

A useful seed structure could be:

• decisions.md: architectural/product decisions that should survive sessions;
• conventions.md: coding/style/project-specific rules;
• failed_paths.md: attempted approaches that should not be repeated blindly;
• open_threads.md: unresolved questions and blockers;
• session_trace/: raw or compacted run notes;
• INDEX.md: generated view derived from the authored files.

The important boundary is: user memory is not project memory, and generated summaries are not the source of truth. If project recall starts as a small markdown-native substrate, later vector/KG/search layers can be rebuilt around it without losing provenance.

This is very close to how I structure a Personal AI OS / memory vault: authored records first, generated recall views second. Reference if useful: https://github.com/hegu-1/personal-memory-vault-starter