This commit is contained in:
oss-sync
@@ -0,0 +1,324 @@
|
||||
# Improve task memory and conversation recall
|
||||
|
||||
## Summary
|
||||
|
||||
Long-running local tasks can lose early user instructions, constraints, and
|
||||
decisions after several exchanges. The codebase already has partial mechanisms:
|
||||
|
||||
- `MissionUpdate` / Mission Brief pins `goal`, `done`, `open`, and
|
||||
`clarifications`.
|
||||
- `Conversation` persists `logs/transcript.jsonl` and can replay prior turns on
|
||||
continuation.
|
||||
- `buildLocalConversationContext()` injects recent task comments.
|
||||
- `handoffContext` carries the previous piece result.
|
||||
|
||||
However, these do not give the agent a reliable way to preserve task state or
|
||||
actively search older conversation history.
|
||||
|
||||
This issue proposes three related improvements:
|
||||
|
||||
1. Make Mission Brief a stronger task-state ledger.
|
||||
2. Add agent-facing conversation search/read tools.
|
||||
3. Update prompts so the agent proactively revisits prior conversation when
|
||||
task context is ambiguous or long-running.
|
||||
|
||||
## Problem
|
||||
|
||||
In multi-turn tasks, the agent often appears to forget early conversation
|
||||
details, especially:
|
||||
|
||||
- original user constraints
|
||||
- decisions made after clarification
|
||||
- "do not change X" instructions
|
||||
- previous failed attempts
|
||||
- which files were already inspected or changed
|
||||
- why a plan was chosen
|
||||
|
||||
Current behavior is understandable from the implementation:
|
||||
|
||||
- `MissionUpdate` is optional and model-driven; it is not enforced at movement
|
||||
boundaries.
|
||||
- Mission Brief fields are too coarse for long implementation tasks.
|
||||
- local task context only injects the recent conversation window.
|
||||
- transcript replay is automatic context carry-over, not searchable retrieval.
|
||||
- prompt compaction/summarization can remove or compress important details.
|
||||
|
||||
## Existing Mechanisms To Reuse
|
||||
|
||||
### Mission Brief
|
||||
|
||||
Source: `src/engine/tools/mission.ts`
|
||||
|
||||
Mission Brief is the best existing place for pinned task state because it is:
|
||||
|
||||
- per local task
|
||||
- visible at the top of every movement prompt
|
||||
- editable by the agent through `MissionUpdate`
|
||||
- editable by the user in the UI
|
||||
- intended to prevent long-conversation drift
|
||||
|
||||
This should be extended rather than replaced.
|
||||
|
||||
### Conversation transcript
|
||||
|
||||
Source: `src/engine/context/conversation.ts`
|
||||
|
||||
`logs/transcript.jsonl` is already written during execution and replayed on
|
||||
continuation. It should remain the raw audit source. New search tools should
|
||||
read from it instead of stuffing the whole transcript into prompt context.
|
||||
|
||||
### Local task comments
|
||||
|
||||
Source: `src/engine/local-context.ts`
|
||||
|
||||
Task comments are the user-facing conversation layer. They should be searchable
|
||||
alongside transcript entries because user instructions often live in comments,
|
||||
requests, and interjections.
|
||||
|
||||
## Proposed Design
|
||||
|
||||
### 1. Extend Mission Brief schema
|
||||
|
||||
Add fields that separate task facts from progress:
|
||||
|
||||
```ts
|
||||
interface MissionBrief {
|
||||
goal?: string;
|
||||
user_constraints?: string;
|
||||
decisions?: string;
|
||||
done?: string;
|
||||
open?: string;
|
||||
current_focus?: string;
|
||||
touched_files?: string;
|
||||
risks?: string;
|
||||
clarifications?: string;
|
||||
last_updated_by_movement?: string;
|
||||
}
|
||||
```
|
||||
|
||||
Keep backwards compatibility with existing `goal`, `done`, `open`, and
|
||||
`clarifications`.
|
||||
|
||||
### 2. Make movement-boundary updates explicit
|
||||
|
||||
At the end of each movement, encourage or enforce a Mission Brief update when
|
||||
the movement made meaningful progress.
|
||||
|
||||
Suggested behavior:
|
||||
|
||||
- On movement start, render the current Mission Brief as today.
|
||||
- During movement, the model can still call `MissionUpdate`.
|
||||
- Before `transition` or `complete`, prompt guidance should require the agent to
|
||||
update `done`, `open`, `current_focus`, and relevant `decisions` if stale.
|
||||
- Optionally add a lightweight stale-check:
|
||||
- if a movement used tools or edited files
|
||||
- and no `MissionUpdate` occurred
|
||||
- inject a reminder before accepting terminal control calls
|
||||
|
||||
Do not make this a hard blocker initially; use a reminder first to avoid
|
||||
creating loops.
|
||||
|
||||
### 3. Add `SearchTaskConversation`
|
||||
|
||||
Add a META tool available to all local-task pieces.
|
||||
|
||||
Suggested signature:
|
||||
|
||||
```ts
|
||||
SearchTaskConversation({
|
||||
query: string;
|
||||
source?: "comments" | "transcript" | "both";
|
||||
author?: "user" | "agent" | "system";
|
||||
kind?: "request" | "comment" | "interjection" | "result" | "ask" | "progress" | "handoff";
|
||||
limit?: number;
|
||||
})
|
||||
```
|
||||
|
||||
Search sources:
|
||||
|
||||
- DB local task comments
|
||||
- `runtimeDir/transcript.jsonl` when available
|
||||
|
||||
Return compact excerpts only:
|
||||
|
||||
```md
|
||||
## Conversation Search Results
|
||||
|
||||
- comment:123 user/comment 2026-06-30T...
|
||||
excerpt: ...
|
||||
|
||||
- transcript:42 user 2026-06-30T...
|
||||
excerpt: ...
|
||||
```
|
||||
|
||||
Constraints:
|
||||
|
||||
- cap result count
|
||||
- cap excerpt length
|
||||
- never return full transcript by default
|
||||
- search only the current task's conversation
|
||||
- respect existing task/space authorization boundaries
|
||||
|
||||
### 4. Add `ReadTaskConversation`
|
||||
|
||||
Add a companion tool to read context around a known hit.
|
||||
|
||||
Suggested signature:
|
||||
|
||||
```ts
|
||||
ReadTaskConversation({
|
||||
ref: "comment:123" | "transcript:42";
|
||||
before?: number;
|
||||
after?: number;
|
||||
})
|
||||
```
|
||||
|
||||
Return nearby entries with strict caps. This keeps search cheap and lets the
|
||||
agent inspect the exact conversation around an old decision.
|
||||
|
||||
### 5. Wire conversation retrieval into Mission Brief refresh
|
||||
|
||||
Update prompt guidance for long tasks:
|
||||
|
||||
- If user constraints or decisions are unclear, use `SearchTaskConversation`
|
||||
before asking the user.
|
||||
- When updating `user_constraints` or `decisions`, prefer citing old comments or
|
||||
transcript refs in the brief.
|
||||
- Before asking the user a clarification, search the task conversation when the
|
||||
missing information may already have been stated earlier.
|
||||
- Before changing previously touched files or revising a prior decision, search
|
||||
for older constraints/decisions related to the file or topic.
|
||||
|
||||
Example Mission Brief snippet:
|
||||
|
||||
```md
|
||||
### User constraints
|
||||
- Keep existing auth flow unchanged. Source: comment:17
|
||||
- Do not rewrite unrelated UI. Source: transcript:42
|
||||
|
||||
### Decisions
|
||||
- Extend Mission Brief instead of creating a second TaskState store. Source: comment:23
|
||||
```
|
||||
|
||||
### 6. Add proactive recall guidance to system/movement prompts
|
||||
|
||||
The new tools should not be passive. Update prompt guidance so the agent
|
||||
actively uses them when forgetting early conversation is likely.
|
||||
|
||||
Suggested rules:
|
||||
|
||||
- At the start of a follow-up task, review Mission Brief first.
|
||||
- If Mission Brief is missing, stale, or too vague, call
|
||||
`SearchTaskConversation` before proceeding with assumptions.
|
||||
- If the task has multiple user turns or interjections, search conversation
|
||||
history for constraints before making broad edits.
|
||||
- If the agent is about to ask the user something, first search prior comments
|
||||
and transcript for the answer unless the question is truly new.
|
||||
- If a movement resumes after context compaction, search for relevant older
|
||||
decisions before modifying files.
|
||||
- When search results reveal durable constraints or decisions, update
|
||||
Mission Brief immediately.
|
||||
|
||||
Candidate prompt copy:
|
||||
|
||||
```md
|
||||
## Conversation recall
|
||||
For long-running or follow-up tasks, do not rely only on the visible recent
|
||||
context. If an earlier user constraint, decision, or clarification may affect
|
||||
your next action, use SearchTaskConversation / ReadTaskConversation before
|
||||
proceeding. Prefer retrieving prior context over asking the user to repeat it.
|
||||
When you find durable task facts, update MissionUpdate so they remain pinned.
|
||||
```
|
||||
|
||||
Keep this guidance concise so it does not crowd out movement-specific
|
||||
instructions.
|
||||
|
||||
## Files Likely Involved
|
||||
|
||||
- `src/db/repository.ts`
|
||||
- extend `MissionBrief`
|
||||
- update parse/update tests
|
||||
- add query helpers for task comments if needed
|
||||
|
||||
- `src/engine/tools/mission.ts`
|
||||
- extend `MissionUpdate` schema
|
||||
- clamp/render new fields
|
||||
- tests for partial updates
|
||||
|
||||
- `src/engine/agent-loop/prompt.ts`
|
||||
- render new Mission Brief fields
|
||||
- update movement guidance around state refresh
|
||||
- add concise proactive recall guidance for long/follow-up tasks
|
||||
|
||||
- `src/engine/agent-loop/watchdogs.ts`
|
||||
- optionally add stale Mission Brief reminder logic
|
||||
- optionally remind the agent to search conversation history when Mission Brief
|
||||
is empty/stale during later iterations
|
||||
|
||||
- `src/engine/tools/index.ts`
|
||||
- add new conversation tools to META_TOOLS
|
||||
|
||||
- `src/engine/tools/conversation.ts` or `src/engine/tools/task-conversation.ts`
|
||||
- implement `SearchTaskConversation`
|
||||
- implement `ReadTaskConversation`
|
||||
|
||||
- `src/engine/tools/core.ts`
|
||||
- expose safe context fields needed by conversation tools, e.g. taskId,
|
||||
runtimeDir, workspacePath, repo access if needed
|
||||
|
||||
- `src/worker.ts`
|
||||
- ensure ToolContext has enough current-task context for the new tools
|
||||
|
||||
- `ui/src/components/detail/tabs/OverviewTab.tsx`
|
||||
- expose new Mission Brief fields for user editing
|
||||
|
||||
- `ui/src/content/help/*.md`
|
||||
- update help docs if behavior/UI changes
|
||||
|
||||
- `ui/src/content/help/00-changelog.md`
|
||||
- add a user-facing changelog entry
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
- Mission Brief supports new fields while preserving existing data.
|
||||
- Existing tasks with old Mission Brief JSON still load correctly.
|
||||
- `MissionUpdate` can update new fields independently.
|
||||
- Mission Brief rendering keeps a bounded prompt size.
|
||||
- Movement guidance encourages updating Mission Brief before transitions.
|
||||
- Prompt guidance tells the agent to search prior conversation before asking the
|
||||
user to repeat information or making assumptions in long/follow-up tasks.
|
||||
- Prompt guidance tells the agent to search prior conversation before asking the
|
||||
user to repeat information or making assumptions in long/follow-up tasks.
|
||||
- `SearchTaskConversation` can find old user comments by keyword.
|
||||
- `SearchTaskConversation` can find transcript entries when `transcript.jsonl`
|
||||
exists.
|
||||
- `ReadTaskConversation` can return bounded context around a search result.
|
||||
- Tools are scoped to the current task and cannot read other task logs.
|
||||
- Tests cover:
|
||||
- old Mission Brief compatibility
|
||||
- new Mission Brief fields
|
||||
- conversation search over comments
|
||||
- conversation search over transcript
|
||||
- prompt text includes proactive recall guidance
|
||||
- bounded output and excerpt truncation
|
||||
- authorization/task scoping
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Do not put task-specific state into `UpdateUserMemory`; that is user-wide
|
||||
memory and would pollute future unrelated tasks.
|
||||
- Do not inject the full transcript into every prompt.
|
||||
- Do not replace `Conversation` replay; retrieval should complement it.
|
||||
- Do not make Mission Brief update a hard terminal blocker until reminder-only
|
||||
behavior has been observed.
|
||||
|
||||
## Suggested Implementation Order
|
||||
|
||||
1. Extend Mission Brief schema and UI rendering.
|
||||
2. Extend `MissionUpdate` and prompt rendering.
|
||||
3. Add reminder-only movement-boundary guidance.
|
||||
4. Implement `SearchTaskConversation` for DB comments.
|
||||
5. Add transcript search.
|
||||
6. Add `ReadTaskConversation`.
|
||||
7. Add proactive recall prompt guidance and tests.
|
||||
8. Update help docs and changelog.
|
||||
Reference in New Issue
Block a user