feat(memory): deterministic buffer turn-summaries (no LLM) (#16)

* feat(memory): deterministic buffer turn-summaries (no LLM)

The tier-2 buffer is injected into the system prompt every turn but each
entry was a naive truncation of raw text (message[:97]+"..." or
shorten(s,100)) — a byte slice that can split a UTF-8 rune and usually
captures only filler ("Sure, I'll help. Let me start by..."), leaving the
buffer with almost no recall signal.

Centralize summarization in MemoryManager.AppendBuffer via a new
deterministic, no-LLM, rune-safe summarizeForBuffer: strip fenced/inline
code, conservative markdown, collapse whitespace, drop a leading filler
clause (only when substance remains), and excerpt to 200 runes at a
sentence/word boundary. All 8 call sites now pass raw text.

Placement is load-bearing: summarization lives in AppendBuffer, not
Buffer.Append, so RestoreBuffer (which calls Buffer.Append directly with
already-summarized lines) never re-processes persisted summaries. Old
session buffers restore verbatim — no migration. shorten() is retained
for its non-buffer callers (session labels, tool-result display).

Tests: table-driven heuristic cases (code/markdown/filler/multibyte/
hard-cut), an AppendBuffer no-mid-word-cut regression, and a verbatim
RestoreBuffer guard for the invariant.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* fix(memory): harden buffer excerpt against early-terminator collapse

Adversarial review (AI Verification Protocol) found two defects in
summarizeForBuffer:

- D-01 (critical): when the only sentence terminator in the window was an
  early abbreviation/version/domain ("e.g.", "v1.2", "node.js"), the
  excerpt collapsed to a few runes (e.g. "e.g.…") — destroying the
  summary. Now a sentence cut is only preferred when it lands at least
  halfway through the window; otherwise fall back to the word boundary
  near the cap.
- D-02 (minor): an unclosed code fence (unmatched by the fenced-block
  regex) left a stray backtick in the output. Residual backticks are now
  stripped after inline-code unwrapping.

Adds regression tests for both.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* test(memory): make LLM test mocks concurrency-safe

CI's `go test -race` flagged a write/write data race on mockLLM.lastUser
in TestConsolidateOnEnd_FiresAtSessionEnd. Root cause:
OnSessionEndWithProvenance legitimately calls the LLM from two goroutines
at once — synchronous episode extraction plus the background
consolidation goroutine — but the test mocks held unsynchronized shared
state.

- mockLLM: guard lastUser with a mutex; add getLastUser() accessor.
- countCallsLLM: replace the non-atomic *int counter with atomic.Int64
  and a calls() accessor (same latent race, same OnSessionEnd trigger).

Test-only change; no production code affected. Verified with
`go test ./internal/memory/... -short -race -count=30` and the full
`go test ./... -short -race` suite.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: jkyberneees

cmd/odek/main.go

@@ -877,9 +877,9 @@ func run(args []string) error {
 			messages = append([]llm.Message{{Role: "system", Content: systemMessage}}, messages...)
 		}
 
-		// Append user input to buffer
+		// Append user input to buffer (AppendBuffer summarizes raw text).
 		if mm := agent.Memory(); mm != nil {
-			mm.AppendBuffer("user", shorten(f.Task, 100))
+			mm.AppendBuffer("user", f.Task)
 		}
 
 		result, allMessages, runErr = agent.RunWithMessages(ctx, messages)
@@ -889,7 +889,7 @@ func run(args []string) error {
 			if mm := agent.Memory(); mm != nil {
 				for i := len(allMessages) - 1; i >= 0; i-- {
 					if allMessages[i].Role == "assistant" && allMessages[i].Content != "" {
-						mm.AppendBuffer("agent", shorten(allMessages[i].Content, 100))
+						mm.AppendBuffer("agent", allMessages[i].Content)
 						break
 					}
 				}
@@ -1675,9 +1675,9 @@ func continueCmd(args []string) error {
 	messages := sess.GetMessages()
 	messages = append(messages, llm.Message{Role: "user", Content: task})
 
-	// Append user input to buffer
+	// Append user input to buffer (AppendBuffer summarizes raw text).
 	if mm := agent.Memory(); mm != nil {
-		mm.AppendBuffer("user", shorten(task, 100))
+		mm.AppendBuffer("user", task)
 	}
 
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
@@ -1710,7 +1710,7 @@ func continueCmd(args []string) error {
 		if mm := agent.Memory(); mm != nil {
 			for i := len(allMessages) - 1; i >= 0; i-- {
 				if allMessages[i].Role == "assistant" && allMessages[i].Content != "" {
-					mm.AppendBuffer("agent", shorten(allMessages[i].Content, 100))
+					mm.AppendBuffer("agent", allMessages[i].Content)
 					break
 				}
 			}

cmd/odek/repl.go

@@ -224,13 +224,9 @@ func replCmd(args []string) error {
 		origLen := len(messages)
 		messages = append(messages, llm.Message{Role: "user", Content: input})
 
-		// Append user input to buffer
+		// Append user input to buffer (AppendBuffer summarizes raw text).
 		if mm := agent.Memory(); mm != nil {
-			userSummary := input
-			if len(userSummary) > 100 {
-				userSummary = userSummary[:97] + "..."
-			}
-			mm.AppendBuffer("user", userSummary)
+			mm.AppendBuffer("user", input)
 		}
 
 		// Run agent with full history
@@ -241,14 +237,10 @@ func replCmd(args []string) error {
 			continue
 		}
 
-		// Append agent response to buffer
+		// Append agent response to buffer (AppendBuffer summarizes raw text).
 		if mm := agent.Memory(); mm != nil && len(allMessages) > 0 {
 			if last := allMessages[len(allMessages)-1]; last.Role == "assistant" {
-				summary := last.Content
-				if len(summary) > 100 {
-					summary = summary[:97] + "..."
-				}
-				mm.AppendBuffer("agent", summary)
+				mm.AppendBuffer("agent", last.Content)
 			}
 		}
 

cmd/odek/serve.go

@@ -652,10 +652,9 @@ func handlePrompt(
 	}
 	writeWSJSON(conn, map[string]any{"type": "session", "session_id": sid, "model": resolved.Model, "sandbox": resolved.Sandbox})
 
-	// Append user input to buffer
+	// Append user input to buffer (AppendBuffer summarizes raw text).
 	if mm := agent.Memory(); mm != nil {
-		userSummary := shorten(prompt, 100)
-		mm.AppendBuffer("user", userSummary)
+		mm.AppendBuffer("user", prompt)
 	}
 
 	// Run agent. Audit recorder wired around the loop so every
@@ -753,8 +752,7 @@ func handlePrompt(
 	if mm := agent.Memory(); mm != nil {
 		for _, msg := range newMsgs {
 			if msg.Role == "assistant" && msg.Content != "" {
-				agentSummary := shorten(msg.Content, 100)
-				mm.AppendBuffer("agent", agentSummary)
+				mm.AppendBuffer("agent", msg.Content)
 				break
 			}
 		}

internal/memory/episode_index_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"path/filepath"
 	"sync"
+	"sync/atomic"
 	"testing"
 )
 
@@ -157,12 +158,11 @@ func TestEpisodeIndex_FormatEpisodeContextNoLLM(t *testing.T) {
 	resetEpIdxes()
 	dir := t.TempDir()
 
-	callCount := 0
 	llm := &mockLLM{responses: map[string]string{
 		"Summarize": "session summary",
 	}}
 	// Override SimpleCall to count calls.
-	countingLLM := &countCallsLLM{inner: llm, count: &callCount}
+	countingLLM := &countCallsLLM{inner: llm}
 
 	cfg := DefaultMemoryConfig()
 	cfg.LLMSearch = boolPtr(true) // explicitly on — FormatEpisodeContext must still skip it
@@ -172,11 +172,11 @@ func TestEpisodeIndex_FormatEpisodeContextNoLLM(t *testing.T) {
 	msgs := []string{"user: hi", "assistant: built the postgres schema", "user: ok", "assistant: done"}
 	mm.OnSessionEndWithProvenance("20260605-a", 5, msgs, EpisodeProvenance{})
 
-	before := callCount
+	before := countingLLM.calls()
 
 	// FormatEpisodeContext must not add any LLM calls.
 	_ = mm.FormatEpisodeContext("postgres schema")
-	after := callCount
+	after := countingLLM.calls()
 
 	if after != before {
 		t.Errorf("FormatEpisodeContext made %d LLM call(s); want 0 (should use vector index only)",
@@ -185,16 +185,23 @@ func TestEpisodeIndex_FormatEpisodeContextNoLLM(t *testing.T) {
 }
 
 // countCallsLLM wraps mockLLM and counts SimpleCall invocations.
+//
+// The counter is atomic: OnSessionEndWithProvenance calls the LLM from two
+// goroutines at once (synchronous episode extraction + background
+// consolidation), so a plain int would race under `go test -race`.
 type countCallsLLM struct {
 	inner *mockLLM
-	count *int
+	n     atomic.Int64
 }
 
 func (c *countCallsLLM) SimpleCall(ctx context.Context, system, user string) (string, error) {
-	*c.count++
+	c.n.Add(1)
 	return c.inner.SimpleCall(ctx, system, user)
 }
 
+// calls returns the number of SimpleCall invocations so far.
+func (c *countCallsLLM) calls() int { return int(c.n.Load()) }
+
 // TestEpisodeIndex_ConcurrentSafety: N goroutines sharing one memory dir write
 // episodes and recall concurrently. No race, no crashes.
 func TestEpisodeIndex_ConcurrentSafety(t *testing.T) {
@@ -267,22 +274,21 @@ func TestEpisodeIndex_AbsPath(t *testing.T) {
 // returns vector-ranked candidates without making any LLM call.
 func TestSearchEpisodes_LLMSearchFalse(t *testing.T) {
 	resetEpIdxes()
-	llmCalls := 0
-	llm := &countCallsLLM{inner: &mockLLM{responses: map[string]string{}}, count: &llmCalls}
+	llm := &countCallsLLM{inner: &mockLLM{responses: map[string]string{}}}
 	cfg := DefaultMemoryConfig()
 	cfg.LLMSearch = boolPtr(false)
 	mm := NewMemoryManager(t.TempDir(), llm, cfg)
 
 	msgs := []string{"user: hi", "assistant: postgres schema done", "user: ok", "assistant: done"}
 	mm.OnSessionEndWithProvenance("20260701-a", 5, msgs, EpisodeProvenance{})
 
-	before := llmCalls
+	before := llm.calls()
 	results, err := mm.SearchEpisodes("postgres", 3)
 	if err != nil {
 		t.Fatalf("SearchEpisodes: %v", err)
 	}
-	if llmCalls != before {
-		t.Errorf("llm_search=false should fire 0 LLM calls, got %d", llmCalls-before)
+	if after := llm.calls(); after != before {
+		t.Errorf("llm_search=false should fire 0 LLM calls, got %d", after-before)
 	}
 	_ = results
 }
@@ -373,15 +379,13 @@ func TestSearchEpisodes_RankFnErrorFallback(t *testing.T) {
 func TestSearchEpisodes_OOVFallbackToLLM(t *testing.T) {
 	resetEpIdxes()
 	dir := t.TempDir()
-	llmCalls := 0
 	llm := &countCallsLLM{
 		inner: &mockLLM{responses: map[string]string{
 			"Summarize":  "postgres work",
 			"relevance":  "0",
 			"rank":       "0",
 			"most relev": "0",
 		}},
-		count: &llmCalls,
 	}
 	cfg := DefaultMemoryConfig()
 	cfg.LLMSearch = boolPtr(true)
@@ -390,10 +394,10 @@ func TestSearchEpisodes_OOVFallbackToLLM(t *testing.T) {
 	msgs := []string{"user: hi", "assistant: postgres schema done", "user: ok", "assistant: done"}
 	mm.OnSessionEndWithProvenance("20260705-a", 5, msgs, EpisodeProvenance{})
 
-	before := llmCalls
+	before := llm.calls()
 	// Query with zero vocabulary overlap (all OOV) → recallByVector returns nil → fallback to Search
 	_, _ = mm.SearchEpisodes("xyzzy wumpus frobnitz", 3)
-	after := llmCalls
+	after := llm.calls()
 	t.Logf("OOV query: llm calls=%d (0 means vector returned nothing, fallback to LLM Search)", after-before)
 	// After D-05 fix: OOV → recallByVector returns nil → SearchEpisodes falls back to episodes.Search
 	// which uses the LLM ranker. We don't assert an exact count because the fallback

internal/memory/memory.go

@@ -449,11 +449,18 @@ Entries for %s:
 
 // ── Buffer Operations ────────────────────────────────────────────────
 
-// AppendBuffer adds a turn summary to the in-memory ring buffer.
+// AppendBuffer adds a turn summary to the in-memory ring buffer. Callers pass
+// the RAW turn text; summarizeForBuffer derives a clean, bounded excerpt here so
+// every entry point shares one policy.
+//
+// Invariant: summarization lives here, not in Buffer.Append, so that
+// RestoreBuffer (which calls Buffer.Append directly with already-formatted,
+// already-summarized lines) never re-processes persisted summaries.
 func (m *MemoryManager) AppendBuffer(role, message string) {
 	if m.cfg.BufferEnabled == nil || !*m.cfg.BufferEnabled {
 		return
 	}
+	message = summarizeForBuffer(message)
 	line := FormatBufferLine(role, message)
 	m.buffer.Append(line)
 	m.markPromptDirty()
@@ -468,6 +475,10 @@ func (m *MemoryManager) GetBuffer() []string {
 }
 
 // RestoreBuffer loads buffer lines from a saved slice (e.g., from session).
+//
+// Invariant: these lines are already-formatted, already-summarized buffer
+// entries. They go straight to Buffer.Append and MUST NOT be routed through
+// AppendBuffer/summarizeForBuffer, which would corrupt the persisted summaries.
 func (m *MemoryManager) RestoreBuffer(lines []string) {
 	if m.cfg.BufferEnabled == nil || !*m.cfg.BufferEnabled {
 		return

internal/memory/memory_test.go

@@ -4,17 +4,27 @@ import (
 	"context"
 	"os"
 	"strings"
+	"sync"
 	"testing"
+	"unicode/utf8"
 )
 
 // mockLLM is a simple LLMClient mock for testing.
+//
+// SimpleCall is concurrency-safe: OnSessionEndWithProvenance legitimately calls
+// the LLM from two goroutines at once (synchronous episode extraction + the
+// background consolidation goroutine), so the mock must guard its shared state
+// or `go test -race` flags a write/write race on lastUser.
 type mockLLM struct {
-	responses map[string]string // query prefix → response
+	responses map[string]string // query prefix → response (read-only after init)
+	mu        sync.Mutex        // guards lastUser
 	lastUser  string            // captured last user prompt
 }
 
 func (m *mockLLM) SimpleCall(ctx context.Context, system, user string) (string, error) {
+	m.mu.Lock()
 	m.lastUser = user
+	m.mu.Unlock()
 	for prefix, resp := range m.responses {
 		if strings.Contains(system, prefix) || strings.Contains(user, prefix) {
 			return resp, nil
@@ -23,6 +33,13 @@ func (m *mockLLM) SimpleCall(ctx context.Context, system, user string) (string,
 	return "", nil
 }
 
+// getLastUser returns the last captured user prompt under the lock.
+func (m *mockLLM) getLastUser() string {
+	m.mu.Lock()
+	defer m.mu.Unlock()
+	return m.lastUser
+}
+
 func TestMemoryManagerAddAndReadFacts(t *testing.T) {
 	dir := t.TempDir()
 	mm := NewMemoryManager(dir, nil, DefaultMemoryConfig())
@@ -149,6 +166,72 @@ func TestMemoryManagerBufferRestore(t *testing.T) {
 	}
 }
 
+// bufferMessage extracts the message portion of a formatted buffer line
+// ("HH:MM  role  message").
+func bufferMessage(t *testing.T, line string) string {
+	t.Helper()
+	parts := strings.SplitN(line, "  ", 3)
+	if len(parts) != 3 {
+		t.Fatalf("unexpected buffer line format: %q", line)
+	}
+	return parts[2]
+}
+
+// TestAppendBufferCleansAndDoesNotMidWordCut verifies that AppendBuffer routes
+// raw text through summarizeForBuffer: code/markdown noise is stripped and the
+// excerpt is bounded and rune-safe (no mid-word/mid-rune chop).
+func TestAppendBufferCleansAndDoesNotMidWordCut(t *testing.T) {
+	dir := t.TempDir()
+	mm := NewMemoryManager(dir, nil, DefaultMemoryConfig())
+
+	raw := "Sure, I'll help with that.\n\n```go\nfunc main() {}\n```\n" +
+		strings.Repeat("Then we verify the behavior carefully. ", 30)
+	mm.AppendBuffer("agent", raw)
+
+	lines := mm.GetBuffer()
+	if len(lines) != 1 {
+		t.Fatalf("expected 1 buffer line, got %d", len(lines))
+	}
+	msg := bufferMessage(t, lines[0])
+
+	if strings.Contains(msg, "\n") {
+		t.Errorf("buffer message contains a newline: %q", msg)
+	}
+	if strings.Contains(msg, "```") {
+		t.Errorf("buffer message still contains a code fence: %q", msg)
+	}
+	if !utf8.ValidString(msg) {
+		t.Errorf("buffer message is not valid UTF-8: %q", msg)
+	}
+	if n := utf8.RuneCountInString(msg); n > maxBufferSummaryRunes+1 {
+		t.Errorf("buffer message rune count %d exceeds cap %d (+1)", n, maxBufferSummaryRunes)
+	}
+}
+
+// TestRestoreBufferPreservesLinesVerbatim guards the load-bearing invariant:
+// RestoreBuffer must NOT re-summarize. It includes a line whose content would be
+// mangled if it were routed through summarizeForBuffer.
+func TestRestoreBufferPreservesLinesVerbatim(t *testing.T) {
+	dir := t.TempDir()
+	mm := NewMemoryManager(dir, nil, DefaultMemoryConfig())
+
+	saved := []string{
+		"14:00  user  first turn",
+		"14:01  agent  Sure, I'll help. ```code``` # heading",
+	}
+	mm.RestoreBuffer(saved)
+
+	lines := mm.GetBuffer()
+	if len(lines) != len(saved) {
+		t.Fatalf("expected %d lines, got %d", len(saved), len(lines))
+	}
+	for i := range saved {
+		if lines[i] != saved[i] {
+			t.Errorf("line %d not verbatim:\n got  %q\n want %q", i, lines[i], saved[i])
+		}
+	}
+}
+
 func TestMemoryManagerBuildSystemPrompt(t *testing.T) {
 	dir := t.TempDir()
 	mm := NewMemoryManager(dir, nil, DefaultMemoryConfig())
@@ -255,12 +338,13 @@ func TestOnSessionEnd_StructuredPrompt(t *testing.T) {
 		"user: great, please add tests",
 	})
 
-	if llm.lastUser == "" {
+	last := llm.getLastUser()
+	if last == "" {
 		t.Fatal("extraction LLM was not called")
 	}
-	lower := strings.ToLower(llm.lastUser)
+	lower := strings.ToLower(last)
 	if !strings.Contains(lower, "user:") && !strings.Contains(lower, "assistant:") {
-		t.Error("extraction prompt should contain user:/assistant: labels, got:\n" + llm.lastUser)
+		t.Error("extraction prompt should contain user:/assistant: labels, got:\n" + last)
 	}
 }