@@ -327,3 +327,67 @@ This architecture replaced the previous snapshot compaction model (v0.4.x) which
327327 The loop slice model eliminates these issues by composing context from atomic units (system + prompt + loop) rather than arbitrary time windows.
328328
329329 See `documentation/archive/` for historical compaction implementation details.
330+
331+## Turn-Aware Context Composition (v0.5.0+)
332+
333+As of v0.5.0, context composition distinguishes between historical turns and the current turn.
334+
335+### Architecture
336+
337+**Turn Boundary:** Detected by finding the most recent user-initiated prompt (direct message, broadcast, or system nudge).
338+
339+**Historical Turns:** All messages before the turn boundary
340+- Compressed using `extractLatestToolLoop()`
341+- Only the most recent complete tool loop is included
342+- Saves context space for older conversations
343+
344+**Current Turn:** All messages from turn boundary to present
345+- Included WITHOUT compression
346+- Preserves complete multi-step tool sequences
347+- Essential for multi-step reasoning (e.g., login → get_status → get_notifications)
348+
349+### Example
350+
351+```
352+Historical:
353+ [user: "old question"]
354+ [assistant: tool_call_1]
355+ [tool: result_1]
356+ [assistant: tool_call_2] ← Only latest loop included
357+ [tool: result_2] ← Only latest loop included
358+
359+Current Turn:
360+ [user: "new question"] ← Turn boundary
361+ [assistant: login_call] ← All included
362+ [tool: session_id: abc123] ← All included
363+ [assistant: status_call] ← All included
364+ [tool: status_result] ← All included
365+```
366+
367+### Benefits
368+
369+1. **Multi-step reasoning:** LLM can reference earlier tool results within the same turn
370+2. **Session persistence:** Session IDs from login remain visible throughout the turn
371+3. **Context efficiency:** Historical turns compressed, current turn preserved
372+4. **Orphan prevention:** Complete tool loops stay together
373+
374+### Implementation
375+
376+**Function:** `getContextMemories()` in `internal/core/mysis.go`
377+
378+**Turn Detection:** `findLastUserPromptIndex()` scans backwards to find the most recent user prompt
379+
380+**Composition:**
381+1. System prompt (always first)
382+2. Historical context (compressed via `extractLatestToolLoop()`)
383+3. Current turn (uncompressed, from turn boundary to present)
384+
385+### Migration from v0.4.x
386+
387+**Before (Loop-based):**
388+- Context: `[system] + [prompt source] + [latest tool loop only]`
389+- Issue: Multi-step tool sequences truncated (login result lost)
390+
391+**After (Turn-aware):**
392+- Context: `[system] + [historical compressed] + [current turn complete]`
393+- Fixed: Complete current turn preserved, enabling multi-step reasoning