diff --git a/work-items/open/20260531-223506-memory-prompt-conditional-lookup/item.md b/work-items/open/20260531-223506-memory-prompt-conditional-lookup/item.md new file mode 100644 index 00000000..61819dc2 --- /dev/null +++ b/work-items/open/20260531-223506-memory-prompt-conditional-lookup/item.md @@ -0,0 +1,74 @@ +--- +id: 20260531-223506-memory-prompt-conditional-lookup +slug: memory-prompt-conditional-lookup +title: Memory prompt: conditional guidance and proactive lookup +status: open +kind: task +priority: P2 +labels: [memory, prompts, tools] +created_at: 2026-05-31T22:35:06Z +updated_at: 2026-05-31T22:35:06Z +assignee: null +legacy_ticket: null +--- + +## Background + +The normal tool-usage prompt currently contains memory guidance unconditionally: + +- use targeted lookup for past decisions, prior requests, durable preferences, project history, or rationale; +- use `MemoryQuery`, `KnowledgeQuery`, and `MemoryRead` appropriately; +- treat resident memory/knowledge as helpful but stale; +- avoid querying memory every turn; +- avoid mutation unless explicitly requested or running a memory maintenance worker. + +This is directionally correct, but two prompt-level issues remain: + +1. Memory/Knowledge guidance should be rendered only when the corresponding memory capability is enabled and available. If memory is disabled for a Pod/profile/internal worker, the prompt should not advertise tools or behavior that cannot be used. +2. The read-side guidance is too passive. Agents should be encouraged to use small targeted queries more often when prior project decisions, user preferences, historical rationale, recent ticket work, or policy/workflow context may affect the answer or action. + +This should be implemented as prompt/template behavior, not by weakening tool permissions or making memory lookup automatic. + +## Requirements + +- Gate memory/knowledge prompt text through the prompt/template engine based on whether memory/knowledge tools or resident memory features are enabled for the current worker. +- Do not show instructions for unavailable memory tools. +- Keep internal/disposable worker behavior conservative; do not accidentally inject normal Pod memory guidance into memory extraction/consolidation workers or other internal workers that should not see it. +- Strengthen normal Pod read-side guidance so agents perform small targeted `MemoryQuery` / `KnowledgeQuery` lookups more proactively when history may matter. +- Preserve the existing warnings: + - memory may be stale; + - authoritative current state is in user instructions, repository files, tickets, git history, and session logs; + - do not query memory mechanically every turn; + - mutation tools are for explicit user requests or memory maintenance workers. +- Do not introduce automatic pre-request memory queries in this ticket. +- Do not change memory extraction/consolidation semantics except as needed to keep prompt rendering coherent. + +## Suggested prompt direction + +The final wording does not need to match this exactly, but should convey: + +```text +Use memory and knowledge proactively when the request may depend on prior +project decisions, historical rationale, durable user preferences, recently +completed tickets, or established workflow/policy conventions. Prefer a small +targeted MemoryQuery/KnowledgeQuery before relying on vague recollection. + +Strong lookup triggers include: the user says "recently", "previously", "that +decision", "the ticket", "why", "policy", or "workflow"; you are about to make +a design recommendation; you are reviewing, merging, closing, or rescoping a +work item; or you are about to assert project history from memory. + +Do not query memory mechanically on every turn. Skip memory lookup for purely +local facts answered by current repository files, command output, or current +user instructions. +``` + +## Acceptance criteria + +- Normal Pod prompts include memory/knowledge guidance only when the corresponding capability is enabled and available. +- Prompts for memory-disabled profiles/workers do not advertise `MemoryQuery`, `KnowledgeQuery`, `MemoryRead`, or memory mutation tools. +- Normal Pod memory guidance explicitly encourages somewhat more frequent small targeted queries when history, rationale, preferences, tickets, policy, workflow, or prior decisions may matter. +- Existing stale/authority cautions and no-mechanical-query guidance remain. +- Internal memory extraction/consolidation prompts remain focused on their worker roles and do not inherit normal Pod guidance accidentally. +- Tests or focused snapshots cover enabled vs disabled prompt rendering, or the implementation otherwise includes a clear focused regression test for conditional rendering. +- `cargo fmt --check`, relevant prompt/worker tests, `./tickets.sh doctor`, and `git diff --check` pass.