Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

feat(agent): persist compaction checkpoints across turns (#3407)

lyingbug62f7da5eea3c
diff --git a/internal/agent/checkpoint.go b/internal/agent/checkpoint.go
new file mode 100644
index 000000000..8b256a738
--- /dev/null
+++ b/internal/agent/checkpoint.go
@@ -0,0 +1,36 @@
+package agent
+
+import (
+ "context"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
+ "github.com/Tencent/WeKnora/internal/logger"
+ "github.com/Tencent/WeKnora/internal/types"
+)
+
+// SetContextCheckpointSink enables persisting compaction checkpoints. Nil (the
+// default) keeps every compaction local to the turn that ran it.
+func (e *AgentEngine) SetContextCheckpointSink(sink types.ContextCheckpointSink) {
+ e.checkpointSink = sink
+}
+
+// saveContextCheckpoint writes a compaction that ends on a stored turn onto
+// that turn. Best-effort: a failed write costs the next turn one more
+// summarization, never this turn anything.
+func (e *AgentEngine) saveContextCheckpoint(ctx context.Context, cp *compaction.Checkpoint, round int) {
+ if cp == nil || e.checkpointSink == nil {
+ return
+ }
+ err := e.checkpointSink.SaveContextCheckpoint(ctx, cp.TurnID, &types.ContextCheckpoint{
+ Summary: cp.Summary,
+ CreatedAt: time.Now(),
+ })
+ if err != nil {
+ logger.Warnf(ctx, "[Agent][Round-%d] Failed to save context checkpoint on turn %s: %v",
+ round, cp.TurnID, err)
+ return
+ }
+ logger.Infof(ctx, "[Agent][Round-%d] Saved context checkpoint through turn %s (%d chars)",
+ round, cp.TurnID, len(cp.Summary))
+}
diff --git a/internal/agent/compaction/checkpoint_test.go b/internal/agent/compaction/checkpoint_test.go
new file mode 100644
index 000000000..65096556d
--- /dev/null
+++ b/internal/agent/compaction/checkpoint_test.go
@@ -0,0 +1,164 @@
+package compaction
+
+import (
+ "context"
+ "testing"
+
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// storedTurn is a turn replayed from the database: every message carries the
+// ID of the assistant message that closes it.
+func storedTurn(id string, rounds int, path string) []chat.Message {
+ msgs := []chat.Message{{Role: "user", Content: "question " + id}}
+ for i := 0; i < rounds; i++ {
+ callID := id + "-call-" + string(rune('a'+i%26))
+ msgs = append(msgs,
+ chat.Message{
+ Role: "assistant",
+ Content: filler(20),
+ ToolCalls: []chat.ToolCall{{
+ ID: callID,
+ Type: "function",
+ Function: chat.FunctionCall{
+ Name: "write_sandbox_file",
+ Arguments: `{"path":"` + path + `","content":"` + filler(40) + `"}`,
+ },
+ }},
+ },
+ chat.Message{Role: "tool", Name: "write_sandbox_file", ToolCallID: callID, Content: filler(30)},
+ )
+ }
+ msgs = append(msgs, chat.Message{Role: "assistant", Content: "answer " + id})
+ for i := range msgs {
+ msgs[i].TurnID = id
+ }
+ return msgs
+}
+
+// withStoredHistory puts stored turns between the system prompt and the live
+// turn, the way the engine assembles a request.
+func withStoredHistory(live []chat.Message, turns ...[]chat.Message) []chat.Message {
+ out := []chat.Message{live[0]}
+ for _, turn := range turns {
+ out = append(out, turn...)
+ }
+ return append(out, live[1:]...)
+}
+
+// The common case: the live turn outgrows the budget, so every stored turn is
+// summarized and the cut splits the live turn. The history part ends on the
+// last stored turn and can stand in for it later; the live turn's prefix
+// cannot, because that turn will be replayed verbatim once it is stored.
+func TestCheckpointEndsOnTheLastStoredTurn(t *testing.T) {
+ llm := &stubChat{response: "## Goal\nsummary"}
+ c := New(llm, newEstimator(t), testSettings())
+
+ msgs := withStoredHistory(reactTurn(12),
+ storedTurn("turn-a", 1, "/workspace/a.txt"),
+ storedTurn("turn-b", 1, "/workspace/b.txt"))
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+ require.True(t, result.SplitTurn)
+
+ require.NotNil(t, result.Checkpoint)
+ assert.Equal(t, "turn-b", result.Checkpoint.TurnID)
+ assert.Contains(t, result.Summary, "Turn Context (split turn)")
+ assert.NotContains(t, result.Checkpoint.Summary, "Turn Context (split turn)",
+ "the live turn's prefix must not outlive the turn")
+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/b.txt")
+ assert.NotContains(t, result.Checkpoint.Summary, "/workspace/out.html",
+ "files touched only by the live turn belong to its own replay")
+}
+
+// A cut that splits a stored turn still ends the history part on the turn
+// before it. The split turn's prefix is summarized for this request only; the
+// next request replays that turn whole.
+func TestCheckpointStopsBeforeASplitStoredTurn(t *testing.T) {
+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())
+
+ live := []chat.Message{{Role: "system", Content: "you are an agent"}, {Role: "user", Content: "next"}}
+ msgs := withStoredHistory(live,
+ storedTurn("turn-a", 1, "/workspace/a.txt"),
+ storedTurn("turn-b", 12, "/workspace/b.txt"))
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+ require.True(t, result.SplitTurn)
+
+ require.NotNil(t, result.Checkpoint)
+ assert.Equal(t, "turn-a", result.Checkpoint.TurnID)
+ assert.NotContains(t, result.Checkpoint.Summary, "/workspace/b.txt")
+}
+
+// A steered message opens a compaction turn but not a stored one. Cutting
+// there summarizes half of a stored turn as history, which no stored boundary
+// describes, so nothing is persisted.
+func TestNoCheckpointWhenHistoryEndsInsideAStoredTurn(t *testing.T) {
+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())
+
+ turn := []chat.Message{
+ {Role: "user", Content: "question"},
+ {Role: "assistant", ToolCalls: []chat.ToolCall{{
+ ID: "call-1", Type: "function",
+ Function: chat.FunctionCall{Name: "read_file", Arguments: `{"path":"/workspace/big.txt"}`},
+ }}},
+ {Role: "tool", Name: "read_file", ToolCallID: "call-1", Content: filler(800)},
+ {Role: "user", Content: "steered: also check the footer"},
+ {Role: "assistant", Content: "done"},
+ }
+ for i := range turn {
+ turn[i].TurnID = "turn-a"
+ }
+ live := []chat.Message{{Role: "system", Content: "you are an agent"}, {Role: "user", Content: "next"}}
+
+ result, err := c.Compact(context.Background(), withStoredHistory(live, turn), ReasonThreshold)
+ require.NoError(t, err)
+ require.False(t, result.SplitTurn, "the steered message is where the cut lands")
+ assert.Nil(t, result.Checkpoint)
+}
+
+func TestNoCheckpointForALiveTurnOnly(t *testing.T) {
+ c := New(&stubChat{response: "## Goal\nsummary"}, newEstimator(t), testSettings())
+
+ result, err := c.Compact(context.Background(), reactTurn(12), ReasonThreshold)
+ require.NoError(t, err)
+ assert.Nil(t, result.Checkpoint, "nothing stored was summarized")
+}
+
+// A raw archive is a stopgap for the request that needed it. Persisting it
+// would make every later turn carry the archive instead of retrying the
+// summarizer.
+func TestNoCheckpointFromADegradedSummary(t *testing.T) {
+ c := New(&stubChat{err: assert.AnError}, newEstimator(t), testSettings())
+
+ msgs := withStoredHistory(reactTurn(12), storedTurn("turn-a", 1, "/workspace/a.txt"))
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+ require.True(t, result.Degraded)
+ assert.Nil(t, result.Checkpoint)
+}
+
+// History loaded from a checkpoint starts with that summary. The next
+// checkpoint must fold it in, including the files it recorded, or everything
+// before the loaded turns is lost the moment a new checkpoint replaces it.
+func TestCheckpointCarriesTheLoadedSummaryForward(t *testing.T) {
+ llm := &stubChat{response: "## Goal\nupdated"}
+ c := New(llm, newEstimator(t), testSettings())
+
+ loaded := SummaryMessage("## Goal\nearlier work" + fileOps{written: []string{"/workspace/old.txt"}}.format())
+ live := reactTurn(12)
+ msgs := append([]chat.Message{live[0], loaded}, storedTurn("turn-c", 1, "/workspace/c.txt")...)
+ msgs = append(msgs, live[1:]...)
+
+ result, err := c.Compact(context.Background(), msgs, ReasonThreshold)
+ require.NoError(t, err)
+
+ require.NotNil(t, result.Checkpoint)
+ assert.Equal(t, "turn-c", result.Checkpoint.TurnID)
+ assert.Contains(t, llm.prompts[0], "<previous-summary>")
+ assert.Contains(t, llm.prompts[0], "earlier work")
+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/old.txt")
+ assert.Contains(t, result.Checkpoint.Summary, "/workspace/c.txt")
+}
diff --git a/internal/agent/compaction/compactor.go b/internal/agent/compaction/compactor.go
index 5cf174afd..4be437dfa 100644
--- a/internal/agent/compaction/compactor.go
+++ b/internal/agent/compaction/compactor.go
@@ -59,6 +59,18 @@ type Result struct {
// SplitTurn reports that the cut divided a single turn, so a turn-prefix
// summary was generated alongside the history summary.
SplitTurn bool
+ // Checkpoint is the part of this compaction a later turn can start from,
+ // or nil when there is none (see Preparation.checkpoint).
+ Checkpoint *Checkpoint
+}
+
+// Checkpoint is a summary that ends exactly on a stored turn. Persisted onto
+// that turn, it lets the next turn load the summary in place of everything up
+// to and including the turn, instead of summarizing the same history again.
+type Checkpoint struct {
+ // TurnID is the stored turn the summary covers through, inclusive.
+ TurnID string
+ Summary string
}
// Freed is how much room the compaction actually recovered. A non-positive
@@ -104,7 +116,8 @@ func (c *Compactor) Compact(
return nil, ErrNothingToCompact
}
- summary, degraded := c.buildSummary(ctx, prep)
+ history, historyDegraded := c.summarizeHistory(ctx, prep)
+ summary, prefixDegraded := c.appendTurnPrefix(ctx, prep, history)
summary += prep.fileOps.format()
compacted := Apply(messages, prep, summary)
@@ -116,51 +129,52 @@ func (c *Compactor) Compact(
TokensAfter: c.estimator.EstimateMessages(compacted),
MessagesBefore: len(messages),
MessagesAfter: len(compacted),
- Degraded: degraded,
+ Degraded: historyDegraded || prefixDegraded,
SplitTurn: prep.IsSplitTurn,
+ Checkpoint: prep.checkpoint(history, historyDegraded),
}, nil
}
-// buildSummary produces the checkpoint text, falling back to a raw archive for
-// any part the summarizer could not produce.
-func (c *Compactor) buildSummary(ctx context.Context, p *Preparation) (string, bool) {
- degraded := false
-
- history := p.PreviousSummary
- if len(p.MessagesToSummarize) > 0 {
- instructions := initialSummarizationInstructions
- if p.PreviousSummary != "" {
- instructions = updateSummarizationInstructions
- }
- text, err := c.summarize(
- ctx, p.MessagesToSummarize, p.PreviousSummary, instructions, c.settings.summaryBudget(),
- )
- if err != nil {
- degraded = true
- // The previous summary is still the best record of everything
- // before this span, so the archive is appended to it rather than
- // replacing it.
- history = joinNonEmpty(p.PreviousSummary, rawArchive(p.MessagesToSummarize))
- } else {
- history = text
- }
+// summarizeHistory folds the complete turns being dropped into the previous
+// summary, falling back to a raw archive when the summarizer fails.
+func (c *Compactor) summarizeHistory(ctx context.Context, p *Preparation) (string, bool) {
+ if len(p.MessagesToSummarize) == 0 {
+ return p.PreviousSummary, false
}
-
- if p.IsSplitTurn && len(p.TurnPrefixMessages) > 0 {
- prefix, err := c.summarize(
- ctx, p.TurnPrefixMessages, "", turnPrefixInstructions, c.settings.turnPrefixBudget(),
- )
- if err != nil {
- degraded = true
- prefix = rawArchive(p.TurnPrefixMessages)
- }
- if history == "" {
- history = "No prior history."
- }
- history += splitTurnSeparator + prefix
+ instructions := initialSummarizationInstructions
+ if p.PreviousSummary != "" {
+ instructions = updateSummarizationInstructions
}
+ text, err := c.summarize(
+ ctx, p.MessagesToSummarize, p.PreviousSummary, instructions, c.settings.summaryBudget(),
+ )
+ if err != nil {
+ // The previous summary is still the best record of everything
+ // before this span, so the archive is appended to it rather than
+ // replacing it.
+ return joinNonEmpty(p.PreviousSummary, rawArchive(p.MessagesToSummarize)), true
+ }
+ return text, false
+}
- return history, degraded
+// appendTurnPrefix adds the summary of a split turn's discarded head, so the
+// retained tail still has its originating request.
+func (c *Compactor) appendTurnPrefix(ctx context.Context, p *Preparation, history string) (string, bool) {
+ if !p.IsSplitTurn || len(p.TurnPrefixMessages) == 0 {
+ return history, false
+ }
+ degraded := false
+ prefix, err := c.summarize(
+ ctx, p.TurnPrefixMessages, "", turnPrefixInstructions, c.settings.turnPrefixBudget(),
+ )
+ if err != nil {
+ degraded = true
+ prefix = rawArchive(p.TurnPrefixMessages)
+ }
+ if history == "" {
+ history = "No prior history."
+ }
+ return history + splitTurnSeparator + prefix, degraded
}
// summarize runs one summarization call with retries.
diff --git a/internal/agent/compaction/prepare.go b/internal/agent/compaction/prepare.go
index 3a2808f29..a3f16685a 100644
--- a/internal/agent/compaction/prepare.go
+++ b/internal/agent/compaction/prepare.go
@@ -33,6 +33,9 @@ type Preparation struct {
PreviousSummary string
TokensBefore int
fileOps fileOps
+ // storedTurnID is the stored turn MessagesToSummarize ends exactly on, or
+ // "" when it ends inside a turn or reaches into the live one.
+ storedTurnID string
}
// Prepare picks the cut point and collects the message ranges around it.
@@ -89,9 +92,44 @@ func Prepare(messages []chat.Message, s Settings, estimator *agenttoken.Estimato
PreviousSummary: previousSummary,
TokensBefore: estimator.EstimateMessages(messages),
fileOps: extractFileOps(previousSummary, toSummarize, turnPrefix),
+ storedTurnID: storedTurnEndingAt(messages, historyEnd),
}
}
+// checkpoint returns the history summary as a Checkpoint when it ends exactly
+// on a stored turn. The turn-prefix summary is left out: it describes part of a
+// turn the next turn replays verbatim. Nothing newly summarized means the
+// previous checkpoint still stands, and a raw archive is not worth keeping
+// past the turn that needed it — the next turn retries the summarizer instead.
+func (p *Preparation) checkpoint(history string, degraded bool) *Checkpoint {
+ if p.storedTurnID == "" || len(p.MessagesToSummarize) == 0 || degraded {
+ return nil
+ }
+ ops := extractFileOps(p.PreviousSummary, p.MessagesToSummarize)
+ return &Checkpoint{TurnID: p.storedTurnID, Summary: history + ops.format()}
+}
+
+// storedTurnEndingAt returns the stored turn that ends immediately before end,
+// or "" if the message there is live or the same turn continues past end.
+//
+// Stored history always precedes the live turn, so a tagged message just
+// before end means everything since the previous summary is stored history
+// too, and the previous summary itself covered nothing live: a cut inside the
+// live turn leaves only live messages after it.
+func storedTurnEndingAt(messages []chat.Message, end int) string {
+ if end <= 0 || end > len(messages) {
+ return ""
+ }
+ turnID := messages[end-1].TurnID
+ if turnID == "" {
+ return ""
+ }
+ if end < len(messages) && messages[end].TurnID == turnID {
+ return ""
+ }
+ return turnID
+}
+
// Apply rebuilds the message list as system prompt, summary, and the verbatim
// tail. Nothing between the system prompt and the cut point survives.
func Apply(messages []chat.Message, p *Preparation, summary string) []chat.Message {
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index 2baa773e4..4e30df2c8 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -61,7 +61,10 @@ type AgentEngine struct {
// reported it could free nothing. Below that count the answer has not
// changed, so there is no reason to spend another summarization call.
compactionExhaustedAt int
- modelContext *modelcontext.Registry // single request-local boundary for every model handle
+ // checkpointSink, when set, persists compactions that end on a stored
+ // turn so later turns start from them. Nil keeps compaction turn-local.
+ checkpointSink types.ContextCheckpointSink
+ modelContext *modelcontext.Registry // single request-local boundary for every model handle
// steerSink, when set, lets users append messages into the running turn.
// Drained at every round boundary; nil disables mid-run injection.
steerSink types.SteerSink
diff --git a/internal/agent/engine_test.go b/internal/agent/engine_test.go
index b7a4fe290..405fe0b36 100644
--- a/internal/agent/engine_test.go
+++ b/internal/agent/engine_test.go
@@ -3,6 +3,7 @@ package agent
import (
"context"
"encoding/json"
+ "errors"
"fmt"
"strings"
"sync"
@@ -500,6 +501,92 @@ func TestContextCompactionDoesNotRunEveryRound(t *testing.T) {
"a context that cannot shrink must not spend another summarization call")
}
+// recordingCheckpointSink captures what the engine persists.
+type recordingCheckpointSink struct {
+ turnIDs []string
+ saved []*types.ContextCheckpoint
+ err error
+}
+
+func (s *recordingCheckpointSink) SaveContextCheckpoint(
+ _ context.Context, turnMessageID string, checkpoint *types.ContextCheckpoint,
+) error {
+ s.turnIDs = append(s.turnIDs, turnMessageID)
+ s.saved = append(s.saved, checkpoint)
+ return s.err
+}
+
+// storedHistoryOverflow is a request whose stored history ends on turn-b and
+// whose live turn has outgrown the keep-recent budget on its own.
+func storedHistoryOverflow() []chat.Message {
+ messages := []chat.Message{
+ {Role: "system", Content: "you are an agent"},
+ {Role: "user", Content: "first question", TurnID: "turn-a"},
+ {Role: "assistant", Content: "first answer", TurnID: "turn-a"},
+ {Role: "user", Content: "second question", TurnID: "turn-b"},
+ {Role: "assistant", Content: "second answer", TurnID: "turn-b"},
+ {Role: "user", Content: "build me a deck"},
+ }
+ body := strings.Repeat("tool output content ", 400)
+ for i := 0; i < 20; i++ {
+ id := fmt.Sprintf("call-%d", i)
+ messages = append(messages,
+ chat.Message{Role: "assistant", ToolCalls: []chat.ToolCall{{
+ ID: id,
+ Type: "function",
+ Function: chat.FunctionCall{Name: "write_sandbox_file", Arguments: `{"path":"/w/a.html"}`},
+ }}},
+ chat.Message{Role: "tool", Name: "write_sandbox_file", ToolCallID: id, Content: body},
+ )
+ }
+ return messages
+}
+
+// Without persistence every later turn re-summarizes the same stored history.
+// A compaction that ends on a stored turn is written back onto that turn.
+func TestContextCompactionPersistsACheckpointOnTheLastStoredTurn(t *testing.T) {
+ engine := newTestEngine(t, &summarizerChat{},
+ withMaxContextTokens(40000), withMaxCompletionTokens(4000))
+ sink := &recordingCheckpointSink{}
+ engine.SetContextCheckpointSink(sink)
+
+ messages := storedHistoryOverflow()
+ _, changed := engine.manageContextWindow(
+ context.Background(), messages, 1, engine.tokenEstimator.EstimateMessages(messages),
+ )
+ require.True(t, changed)
+
+ require.Equal(t, []string{"turn-b"}, sink.turnIDs)
+ require.Contains(t, sink.saved[0].Summary, "do the thing")
+ require.False(t, sink.saved[0].CreatedAt.IsZero())
+}
+
+// The checkpoint is an optimization for later turns. Failing to store it must
+// not undo the compaction this turn needed.
+func TestContextCheckpointFailureKeepsTheCompaction(t *testing.T) {
+ engine := newTestEngine(t, &summarizerChat{},
+ withMaxContextTokens(40000), withMaxCompletionTokens(4000))
+ engine.SetContextCheckpointSink(&recordingCheckpointSink{err: errors.New("db down")})
+
+ messages := storedHistoryOverflow()
+ before := engine.tokenEstimator.EstimateMessages(messages)
+ compacted, changed := engine.manageContextWindow(context.Background(), messages, 1, before)
+ require.True(t, changed)
+ require.Less(t, engine.tokenEstimator.EstimateMessages(compacted), before/2)
+}
+
+// Redacting a stored KB result must not detach it from its turn, or a summary
+// ending on that turn could no longer be recognized as ending there.
+func TestRedactHistoryKBResultsKeepsTurnID(t *testing.T) {
+ redacted := redactHistoryKBResults([]chat.Message{{
+ Role: "tool", Name: agenttools.ToolSearchKnowledge, ToolCallID: "c1",
+ Content: "stale chunk", TurnID: "turn-a",
+ }})
+ require.Len(t, redacted, 1)
+ require.NotEqual(t, "stale chunk", redacted[0].Content)
+ require.Equal(t, "turn-a", redacted[0].TurnID)
+}
+
// Asking for more output than the window can still hold is rejected outright
// by the provider, which surfaces to the agent as an unexplained failure.
func TestClampCompletionBudgetToContext(t *testing.T) {
diff --git a/internal/agent/observe.go b/internal/agent/observe.go
index 80955a21e..c945412ef 100644
--- a/internal/agent/observe.go
+++ b/internal/agent/observe.go
@@ -124,6 +124,7 @@ func (e *AgentEngine) runCompaction(
"degraded": result.Degraded,
})
e.emitContextCompacted(ctx, result, round)
+ e.saveContextCheckpoint(ctx, result.Checkpoint, round)
// The usage baseline described the pre-compaction context; keeping it
// would have the next round estimate against history that no longer
@@ -919,6 +920,7 @@ func redactHistoryKBResults(llmContext []chat.Message) []chat.Message {
Content: "[Previous retrieval result omitted — knowledge base may have changed. Please perform a fresh search.]",
ToolCallID: msg.ToolCallID,
Name: msg.Name,
+ TurnID: msg.TurnID,
})
} else {
redacted = append(redacted, msg)
diff --git a/internal/application/repository/message.go b/internal/application/repository/message.go
index 19ccf13b9..c36c83f32 100644
--- a/internal/application/repository/message.go
+++ b/internal/application/repository/message.go
@@ -406,6 +406,38 @@ func (r *messageRepository) UpdateMessageRenderedContent(ctx context.Context, se
Update("rendered_content", renderedContent).Error
}
+// UpdateMessageContextCheckpoint updates only the context_checkpoint column, so
+// it cannot race a full-row write of the same message.
+func (r *messageRepository) UpdateMessageContextCheckpoint(
+ ctx context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,
+) error {
+ return r.db.WithContext(ctx).
+ Model(&types.Message{}).
+ Where("id = ? AND session_id = ? AND role = ?", messageID, sessionID, "assistant").
+ Update("context_checkpoint", checkpoint).Error
+}
+
+// GetLatestContextCheckpoint returns the newest checkpointed assistant message.
+// Only the identity and ordering columns come back with the checkpoint: the
+// caller matches it against turns it has already loaded.
+func (r *messageRepository) GetLatestContextCheckpoint(
+ ctx context.Context, sessionID string,
+) (*types.Message, error) {
+ var messages []*types.Message
+ if err := r.db.WithContext(ctx).
+ Select("id", "session_id", "request_id", "role", "created_at", "context_checkpoint").
+ Where("session_id = ? AND role = ? AND context_checkpoint IS NOT NULL", sessionID, "assistant").
+ Order("created_at DESC, id DESC").
+ Limit(1).
+ Find(&messages).Error; err != nil {
+ return nil, err
+ }
+ if len(messages) == 0 {
+ return nil, nil
+ }
+ return messages[0], nil
+}
+
// DeleteMessagesBySessionID deletes all messages belonging to a session (soft delete)
func (r *messageRepository) DeleteMessagesBySessionID(ctx context.Context, sessionID string) error {
return r.db.WithContext(ctx).Where("session_id = ?", sessionID).Delete(&types.Message{}).Error
diff --git a/internal/application/repository/message_context_checkpoint_test.go b/internal/application/repository/message_context_checkpoint_test.go
new file mode 100644
index 000000000..d0b80cced
--- /dev/null
+++ b/internal/application/repository/message_context_checkpoint_test.go
@@ -0,0 +1,87 @@
+package repository
+
+import (
+ "context"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/require"
+)
+
+func TestGetLatestContextCheckpointReturnsTheNewestInTheSession(t *testing.T) {
+ repo, db := newMessageRepositoryForForkTest(t)
+ ctx := context.Background()
+ base := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)
+
+ none, err := repo.GetLatestContextCheckpoint(ctx, "s1")
+ require.NoError(t, err)
+ require.Nil(t, none)
+
+ seedMessage(t, db, "a1", "s1", "assistant", base)
+ seedMessage(t, db, "a2", "s1", "assistant", base.Add(time.Minute))
+ seedMessage(t, db, "a3", "s1", "assistant", base.Add(2*time.Minute))
+ seedMessage(t, db, "other", "s2", "assistant", base.Add(time.Hour))
+
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a1",
+ &types.ContextCheckpoint{Summary: "through one"}))
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a2",
+ &types.ContextCheckpoint{Summary: "through two"}))
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s2", "other",
+ &types.ContextCheckpoint{Summary: "another session"}))
+
+ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")
+ require.NoError(t, err)
+ require.NotNil(t, got)
+ require.Equal(t, "a2", got.ID)
+ require.Equal(t, "through two", got.ContextCheckpoint.Summary)
+ require.True(t, got.CreatedAt.Equal(base.Add(time.Minute)))
+
+ // A deleted turn takes its checkpoint with it.
+ require.NoError(t, repo.DeleteMessage(ctx, "s1", "a2"))
+ got, err = repo.GetLatestContextCheckpoint(ctx, "s1")
+ require.NoError(t, err)
+ require.Equal(t, "a1", got.ID)
+}
+
+// The session guard keeps a stray turn ID from writing into another session,
+// and the role guard keeps it off user rows.
+func TestUpdateMessageContextCheckpointIsScopedToTheSessionsAssistantRows(t *testing.T) {
+ repo, db := newMessageRepositoryForForkTest(t)
+ ctx := context.Background()
+ at := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)
+
+ seedMessage(t, db, "u1", "s1", "user", at)
+ seedMessage(t, db, "a1", "s1", "assistant", at)
+
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s2", "a1",
+ &types.ContextCheckpoint{Summary: "wrong session"}))
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "u1",
+ &types.ContextCheckpoint{Summary: "user row"}))
+
+ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")
+ require.NoError(t, err)
+ require.Nil(t, got)
+}
+
+// Messages are also saved whole (UpdateMessage) by paths that loaded them
+// before a checkpoint was written. Such a save must not clear it.
+func TestUpdateMessageKeepsAnExistingContextCheckpoint(t *testing.T) {
+ repo, db := newMessageRepositoryForForkTest(t)
+ ctx := context.Background()
+ at := time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)
+
+ seedMessage(t, db, "a1", "s1", "assistant", at)
+ stale, err := repo.GetMessage(ctx, "s1", "a1")
+ require.NoError(t, err)
+
+ require.NoError(t, repo.UpdateMessageContextCheckpoint(ctx, "s1", "a1",
+ &types.ContextCheckpoint{Summary: "kept"}))
+ stale.Content = "edited"
+ require.NoError(t, repo.UpdateMessage(ctx, stale))
+
+ got, err := repo.GetLatestContextCheckpoint(ctx, "s1")
+ require.NoError(t, err)
+ require.NotNil(t, got)
+ require.Equal(t, "kept", got.ContextCheckpoint.Summary)
+}
diff --git a/internal/application/service/agent_history.go b/internal/application/service/agent_history.go
index 5b93eb718..28b4e5c5b 100644
--- a/internal/application/service/agent_history.go
+++ b/internal/application/service/agent_history.go
@@ -9,7 +9,9 @@ import (
"strings"
"time"
+ "github.com/Tencent/WeKnora/internal/agent/compaction"
agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/chat"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
@@ -44,6 +46,12 @@ var agentHistoryThinkTagRegex = regexp.MustCompile(`(?s)<think>.*?</think>`)
// Turns lacking either user or assistant content are skipped. The newest
// maxRounds turns are returned in chronological order.
//
+// When a turn carries a context checkpoint (a compaction summary persisted by
+// an earlier run), history starts from it: the summary replaces that turn and
+// everything before it, and only later turns are replayed. Every replayed
+// message is tagged with its turn's assistant message ID so this run's
+// compaction can persist a new checkpoint in turn.
+//
// DB is treated as the single source of truth — there is no Redis/in-memory
// cache layer above this function. Callers are expected to invoke it once
// per turn before handing the messages to the agent engine.
@@ -70,20 +78,11 @@ func LoadAgentHistory(
return []chat.Message{}, nil
}
- // A turn is not always one user message. Mid-run steering persists every
- // injected message under the running turn's request ID, so a turn can be
- // user → tools → user → tools → answer. Keeping only the last user row
- // would drop the original question from the next turn's context.
- type turn struct {
- users []*types.Message
- assistant *types.Message
- createdAt time.Time
- }
- turns := make(map[string]*turn)
+ turns := make(map[string]*agentHistoryTurn)
for _, msg := range rows {
t, ok := turns[msg.RequestID]
if !ok {
- t = &turn{}
+ t = &agentHistoryTurn{}
turns[msg.RequestID] = t
}
switch msg.Role {
@@ -97,7 +96,7 @@ func LoadAgentHistory(
}
}
- completeTurns := make([]*turn, 0, len(turns))
+ completeTurns := make([]*agentHistoryTurn, 0, len(turns))
for _, t := range turns {
if len(t.users) > 0 && t.assistant != nil && t.assistant.IsCompleted {
sort.SliceStable(t.users, func(i, j int) bool {
@@ -111,18 +110,93 @@ func LoadAgentHistory(
return completeTurns[i].createdAt.Before(completeTurns[j].createdAt)
})
+ summary := ""
+ if checkpoint := loadContextCheckpoint(ctx, messageRepo, sessionID); checkpoint != nil {
+ completeTurns = turnsAfterCheckpoint(completeTurns, checkpoint)
+ summary = checkpoint.ContextCheckpoint.Summary
+ logger.Infof(ctx, "Agent history resumes from the context checkpoint on %s, %d turn(s) after it",
+ checkpoint.ID, len(completeTurns))
+ }
+
if len(completeTurns) > maxRounds {
completeTurns = completeTurns[len(completeTurns)-maxRounds:]
}
- out := make([]chat.Message, 0, len(completeTurns)*4)
+ out := make([]chat.Message, 0, len(completeTurns)*4+1)
+ if summary != "" {
+ out = append(out, compaction.SummaryMessage(summary))
+ }
for _, t := range completeTurns {
+ start := len(out)
out = append(out, buildUserHistoryMessage(t.users[0]))
out = append(out, buildTurnBodyMessages(t.assistant, t.users[1:])...)
+ for i := start; i < len(out); i++ {
+ out[i].TurnID = t.assistant.ID
+ }
}
return out, nil
}
+// agentHistoryTurn is one stored turn. A turn is not always one user message.
+// Mid-run steering persists every injected message under the running turn's
+// request ID, so a turn can be user → tools → user → tools → answer. Keeping
+// only the last user row would drop the original question from the next
+// turn's context.
+type agentHistoryTurn struct {
+ users []*types.Message
+ assistant *types.Message
+ createdAt time.Time
+}
+
+// loadContextCheckpoint returns the session's newest usable checkpoint, or nil.
+// A failed lookup degrades to history without one: the turn still runs, it
+// just pays for compaction again.
+func loadContextCheckpoint(
+ ctx context.Context, messageRepo interfaces.MessageRepository, sessionID string,
+) *types.Message {
+ msg, err := messageRepo.GetLatestContextCheckpoint(ctx, sessionID)
+ if err != nil {
+ logger.Warnf(ctx, "Failed to load the context checkpoint of session %s, "+
+ "loading history without it: %v", sessionID, err)
+ return nil
+ }
+ if msg == nil || msg.ContextCheckpoint == nil || strings.TrimSpace(msg.ContextCheckpoint.Summary) == "" {
+ return nil
+ }
+ return msg
+}
+
+// turnsAfterCheckpoint drops the turns a checkpoint already covers: its own
+// turn and every turn before it. A checkpoint older than the loaded window is
+// matched by time instead, which keeps every loaded turn.
+func turnsAfterCheckpoint(turns []*agentHistoryTurn, checkpoint *types.Message) []*agentHistoryTurn {
+ for i, t := range turns {
+ if t.assistant.ID == checkpoint.ID {
+ return turns[i+1:]
+ }
+ }
+ after := make([]*agentHistoryTurn, 0, len(turns))
+ for _, t := range turns {
+ if t.createdAt.After(checkpoint.CreatedAt) {
+ after = append(after, t)
+ }
+ }
+ return after
+}
+
+// messageCheckpointSink persists the engine's compaction checkpoints onto the
+// session's assistant messages, where LoadAgentHistory reads them back.
+type messageCheckpointSink struct {
+ repo interfaces.MessageRepository
+ sessionID string
+}
+
+func (s messageCheckpointSink) SaveContextCheckpoint(
+ ctx context.Context, turnMessageID string, checkpoint *types.ContextCheckpoint,
+) error {
+ return s.repo.UpdateMessageContextCheckpoint(ctx, s.sessionID, turnMessageID, checkpoint)
+}
+
// buildTurnBodyMessages replays one turn's assistant work with any mid-run
// user messages put back where they happened. Steered messages arrive between
// tool rounds, so replaying them all up-front (or dropping them) would tell
diff --git a/internal/application/service/agent_history_checkpoint_test.go b/internal/application/service/agent_history_checkpoint_test.go
new file mode 100644
index 000000000..339cdc8dd
--- /dev/null
+++ b/internal/application/service/agent_history_checkpoint_test.go
@@ -0,0 +1,168 @@
+package service
+
+import (
+ "context"
+ "errors"
+ "fmt"
+ "testing"
+ "time"
+
+ "github.com/Tencent/WeKnora/internal/models/chat"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/Tencent/WeKnora/internal/types/interfaces"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// checkpointHistoryRepo serves a fixed message list and one checkpoint lookup.
+type checkpointHistoryRepo struct {
+ interfaces.MessageRepository
+ rows []*types.Message
+ checkpoint *types.Message
+ checkpointErr error
+ updates []string
+}
+
+func (r *checkpointHistoryRepo) GetRecentMessagesBySession(
+ context.Context, string, int,
+) ([]*types.Message, error) {
+ return r.rows, nil
+}
+
+func (r *checkpointHistoryRepo) GetLatestContextCheckpoint(
+ context.Context, string,
+) (*types.Message, error) {
+ return r.checkpoint, r.checkpointErr
+}
+
+func (r *checkpointHistoryRepo) UpdateMessageContextCheckpoint(
+ _ context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,
+) error {
+ r.updates = append(r.updates, sessionID+"/"+messageID+"/"+checkpoint.Summary)
+ return nil
+}
+
+var historyBase = time.Date(2026, 9, 18, 9, 0, 0, 0, time.UTC)
+
+// storedTurns builds n completed turns; turn i has user u<i> and assistant a<i>.
+func storedTurns(n int) []*types.Message {
+ var rows []*types.Message
+ for i := 1; i <= n; i++ {
+ at := historyBase.Add(time.Duration(i) * time.Minute)
+ req := fmt.Sprintf("req-%d", i)
+ rows = append(rows,
+ &types.Message{
+ ID: fmt.Sprintf("u%d", i), RequestID: req, Role: "user",
+ Content: fmt.Sprintf("question %d", i), CreatedAt: at,
+ },
+ &types.Message{
+ ID: fmt.Sprintf("a%d", i), RequestID: req, Role: "assistant",
+ Content: fmt.Sprintf("answer %d", i), IsCompleted: true, CreatedAt: at.Add(time.Second),
+ },
+ )
+ }
+ return rows
+}
+
+func checkpointOn(msg *types.Message, summary string) *types.Message {
+ return &types.Message{
+ ID: msg.ID, SessionID: msg.SessionID, RequestID: msg.RequestID, Role: "assistant",
+ CreatedAt: msg.CreatedAt, ContextCheckpoint: &types.ContextCheckpoint{Summary: summary},
+ }
+}
+
+func contents(msgs []chat.Message) []string {
+ out := make([]string, len(msgs))
+ for i, m := range msgs {
+ out[i] = m.Content
+ }
+ return out
+}
+
+// Without a checkpoint history is what it always was, plus the turn tags the
+// engine needs to recognize a summary that ends on a stored turn.
+func TestLoadAgentHistoryTagsEveryMessageWithItsTurn(t *testing.T) {
+ repo := &checkpointHistoryRepo{rows: storedTurns(2)}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)
+ require.NoError(t, err)
+
+ require.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))
+ for i, want := range []string{"a1", "a1", "a2", "a2"} {
+ assert.Equal(t, want, got[i].TurnID, "message %d", i)
+ }
+}
+
+// The summary replaces its own turn and every turn before it; later turns are
+// replayed verbatim after it.
+func TestLoadAgentHistoryResumesFromTheCheckpoint(t *testing.T) {
+ rows := storedTurns(4)
+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[3], "## Goal\nturns one and two")}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)
+ require.NoError(t, err)
+
+ require.Len(t, got, 5)
+ assert.Equal(t, chat.MessageKindCompactionSummary, got[0].Kind)
+ assert.Equal(t, "user", got[0].Role)
+ assert.Contains(t, got[0].Content, "turns one and two")
+ assert.Empty(t, got[0].TurnID, "the summary is not a stored turn")
+ assert.Equal(t, []string{"question 3", "answer 3", "question 4", "answer 4"}, contents(got[1:]))
+ assert.Equal(t, "a3", got[1].TurnID)
+ assert.Equal(t, "a4", got[4].TurnID)
+}
+
+// A checkpoint can predate the rows fetched for the window. It still covers
+// everything before it, and every fetched turn is newer.
+func TestLoadAgentHistoryUsesACheckpointOlderThanTheWindow(t *testing.T) {
+ rows := storedTurns(4)
+ repo := &checkpointHistoryRepo{rows: rows[4:], checkpoint: checkpointOn(rows[1], "## Goal\nturn one")}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)
+ require.NoError(t, err)
+
+ require.Len(t, got, 5)
+ assert.Contains(t, got[0].Content, "turn one")
+ assert.Equal(t, []string{"question 3", "answer 3", "question 4", "answer 4"}, contents(got[1:]))
+}
+
+// The turn cap bounds the verbatim turns after the checkpoint, not the
+// summary, which is already bounded by the summarizer's budget.
+func TestLoadAgentHistoryCapsTurnsAfterTheCheckpoint(t *testing.T) {
+ rows := storedTurns(3)
+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[1], "## Goal\nturn one")}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 1)
+ require.NoError(t, err)
+
+ require.Len(t, got, 3)
+ assert.Equal(t, chat.MessageKindCompactionSummary, got[0].Kind)
+ assert.Equal(t, []string{"question 3", "answer 3"}, contents(got[1:]))
+}
+
+// A failed lookup costs the turn a re-summarization, not its history.
+func TestLoadAgentHistoryWithoutACheckpointWhenTheLookupFails(t *testing.T) {
+ repo := &checkpointHistoryRepo{rows: storedTurns(2), checkpointErr: errors.New("db down")}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)
+ require.NoError(t, err)
+ assert.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))
+}
+
+func TestLoadAgentHistoryIgnoresAnEmptyCheckpoint(t *testing.T) {
+ rows := storedTurns(2)
+ repo := &checkpointHistoryRepo{rows: rows, checkpoint: checkpointOn(rows[1], " ")}
+
+ got, err := LoadAgentHistory(context.Background(), repo, "s1", 5)
+ require.NoError(t, err)
+ assert.Equal(t, []string{"question 1", "answer 1", "question 2", "answer 2"}, contents(got))
+}
+
+func TestMessageCheckpointSinkWritesThroughTheSession(t *testing.T) {
+ repo := &checkpointHistoryRepo{}
+ sink := messageCheckpointSink{repo: repo, sessionID: "s1"}
+
+ require.NoError(t, sink.SaveContextCheckpoint(context.Background(), "a2",
+ &types.ContextCheckpoint{Summary: "sum"}))
+ assert.Equal(t, []string{"s1/a2/sum"}, repo.updates)
+}
diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.go
index fa989efb5..f15cc2782 100644
--- a/internal/application/service/session_agent_qa.go
+++ b/internal/application/service/session_agent_qa.go
@@ -241,6 +241,13 @@ func (s *sessionService) AgentQA(
engine.SetSteerSink(req.SteerSink)
}
+ // A compaction that ends on a stored turn is written back onto it, so the
+ // next turn loads the summary instead of summarizing the same history
+ // again. Without multi-turn there is no stored history to end on.
+ if agentConfig.MultiTurnEnabled {
+ engine.SetContextCheckpointSink(messageCheckpointSink{repo: s.messageRepo, sessionID: sessionID})
+ }
+
agentQuery := req.Query
var agentImageURLs []string
if agentModelSupportsVision && len(req.ImageURLs) > 0 {
diff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.go
index d908247f2..05b0d64f8 100644
--- a/internal/application/service/tenant_skill_install_test.go
+++ b/internal/application/service/tenant_skill_install_test.go
@@ -748,9 +748,10 @@ func TestInstallSkillRecoversFromNameConflict(t *testing.T) {
require.NoError(t, err)
require.Equal(t, "sk-1", id,
"the upload that lost the unique index must reuse the row that won")
- skill, getErr := fx.skillRepo.GetSkill(context.Background(), 7, "cfg-1", "sk-1")
- require.NoError(t, getErr)
- require.Equal(t, types.SkillStatusInstalling, skill.Status)
+ // The install runs in the background and the fixture row already starts at
+ // installing, so an immediate status read raced the goroutine and proved
+ // nothing. The run finishing on the reused row is what shows it was taken.
+ waitBackgroundInstallReady(t, fx, "the install must run on the row that won")
}
func TestInstallSkillRefusesWhenBundleCannotBeStored(t *testing.T) {
@@ -3206,8 +3207,9 @@ func (e *installAgentEngine) Execute(
}
return &types.AgentState{IsComplete: true}, nil
}
-func (e *installAgentEngine) SetMemoryPrompt(string) {}
-func (e *installAgentEngine) SetSteerSink(sink types.SteerSink) { e.sink = sink }
+func (e *installAgentEngine) SetMemoryPrompt(string) {}
+func (e *installAgentEngine) SetSteerSink(sink types.SteerSink) { e.sink = sink }
+func (e *installAgentEngine) SetContextCheckpointSink(types.ContextCheckpointSink) {}
type installSessionService struct {
fx *installFixture
diff --git a/internal/database/migration_sqlite_versioned_schema_test.go b/internal/database/migration_sqlite_versioned_schema_test.go
index bf7123184..28bff5ec7 100644
--- a/internal/database/migration_sqlite_versioned_schema_test.go
+++ b/internal/database/migration_sqlite_versioned_schema_test.go
@@ -34,21 +34,21 @@ var versionedSQLiteTables = []string{
// versionedSQLiteColumns maps each existing table to the columns that the
// versioned migrations add and the SQLite baseline was missing.
var versionedSQLiteColumns = map[string][]string{
- "memory_subjects": {"extraction_state"}, // 000094
- "memory_items": {"replaces_id"}, // 000094
- "tenants": {"api_principal_config"}, // 000064
- "users": {"is_system_admin"}, // 000053
- "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101
- "knowledge_bases": {"profile_config", "generated_profile"}, // 000101
- "messages": {"attachments", "usage", "sandbox_checkpoint"}, // 000034, 000085, 000097
- "sessions": {"parent_session_id", "forked_from_message_id", "fork_bootstrap"}, // 000097
- "tenant_invitations": {"token", "accepted_count"}, // 000054
- "embed_channels": {"allow_memory"}, // 000060
- "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064
- "mcp_tool_approvals": {"enabled"}, // 000091
+ "memory_subjects": {"extraction_state"}, // 000094
+ "memory_items": {"replaces_id"}, // 000094
+ "tenants": {"api_principal_config"}, // 000064
+ "users": {"is_system_admin"}, // 000053
+ "knowledges": {"pending_subtasks_count", "profile"}, // 000056, 000101
+ "knowledge_bases": {"profile_config", "generated_profile"}, // 000101
+ "messages": {"attachments", "usage", "sandbox_checkpoint", "context_checkpoint"}, // 000034/085/097/104
+ "sessions": {"parent_session_id", "forked_from_message_id", "fork_bootstrap"}, // 000097
+ "tenant_invitations": {"token", "accepted_count"}, // 000054
+ "embed_channels": {"allow_memory"}, // 000060
+ "mcp_oauth_tokens": {"principal_type", "principal_id"}, // 000064
+ "mcp_tool_approvals": {"enabled"}, // 000091
}
-const expectedSQLiteMigrationVersion = 23
+const expectedSQLiteMigrationVersion = 24
func TestSQLiteMigrationsCreateVersionedSchema(t *testing.T) {
repoRoot := sqliteRepoRoot(t)
diff --git a/internal/models/chat/chat.go b/internal/models/chat/chat.go
index 5a908ee22..55e34048b 100644
--- a/internal/models/chat/chat.go
+++ b/internal/models/chat/chat.go
@@ -93,6 +93,12 @@ type Message struct {
// providers reject unknown message fields on some endpoints, and this one
// means nothing to them anyway.
Kind MessageKind `json:"-"`
+ // TurnID is the stored assistant message whose turn this history message
+ // was replayed from. It is empty for the live turn and for messages the
+ // engine synthesized. Compaction uses it to tell whether a summary ends
+ // exactly on a stored turn, the only kind it can persist for later turns.
+ // Engine-internal like Kind, and kept off the wire for the same reason.
+ TurnID string `json:"-"`
}
// ToolCall represents a tool call in a message
diff --git a/internal/types/context_checkpoint.go b/internal/types/context_checkpoint.go
new file mode 100644
index 000000000..0ed58d2aa
--- /dev/null
+++ b/internal/types/context_checkpoint.go
@@ -0,0 +1,58 @@
+package types
+
+import (
+ "context"
+ "database/sql/driver"
+ "encoding/json"
+ "errors"
+ "time"
+)
+
+// ContextCheckpoint is an agent compaction summary persisted on the assistant
+// message of the last turn it covers. The next turn's history starts from the
+// newest checkpoint instead of from the raw turns it replaces, so a compaction
+// is paid for once rather than again on every later turn.
+//
+// Storing it on the covered turn rather than on the turn that ran the
+// compaction keeps the boundary implicit: a fork that copies the turn copies
+// the checkpoint with it, and deleting the turn drops the checkpoint too.
+type ContextCheckpoint struct {
+ Summary string `json:"summary"`
+ CreatedAt time.Time `json:"created_at"`
+}
+
+// Value implements the driver.Valuer interface for database serialization.
+func (c ContextCheckpoint) Value() (driver.Value, error) {
+ return json.Marshal(c)
+}
+
+// Scan implements the sql.Scanner interface for database deserialization.
+func (c *ContextCheckpoint) Scan(value any) error {
+ if value == nil {
+ *c = ContextCheckpoint{}
+ return nil
+ }
+ var b []byte
+ switch v := value.(type) {
+ case []byte:
+ b = v
+ case string:
+ b = []byte(v)
+ default:
+ return errors.New("types: cannot scan context checkpoint from unsupported type")
+ }
+ if len(b) == 0 {
+ *c = ContextCheckpoint{}
+ return nil
+ }
+ return json.Unmarshal(b, c)
+}
+
+// ContextCheckpointSink persists compaction checkpoints for the agent engine.
+// Declared in types for the same reason as SteerSink: the engine and the
+// service both need the shape and neither may import the other.
+type ContextCheckpointSink interface {
+ // SaveContextCheckpoint stores checkpoint on the assistant message
+ // turnMessageID, replacing any earlier checkpoint there.
+ SaveContextCheckpoint(ctx context.Context, turnMessageID string, checkpoint *ContextCheckpoint) error
+}
diff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.go
index ab3edd8bc..f0c3a2ea8 100644
--- a/internal/types/interfaces/agent.go
+++ b/internal/types/interfaces/agent.go
@@ -38,6 +38,11 @@ type AgentEngine interface {
// messages at every round boundary and persists accepted ones through
// the sink. Must be called before Execute.
SetSteerSink(sink types.SteerSink)
+
+ // SetContextCheckpointSink enables persisting compaction summaries that
+ // end on a stored turn, so later turns start from them. Nil (default)
+ // keeps compaction local to the turn. Must be called before Execute.
+ SetContextCheckpointSink(sink types.ContextCheckpointSink)
}
// AgentService defines the interface for agent-related operations
diff --git a/internal/types/interfaces/message.go b/internal/types/interfaces/message.go
index dbed461d4..543ec3714 100644
--- a/internal/types/interfaces/message.go
+++ b/internal/types/interfaces/message.go
@@ -106,6 +106,15 @@ type MessageRepository interface {
UpdateMessageImages(ctx context.Context, sessionID, messageID string, images types.MessageImages) error
// UpdateMessageRenderedContent updates the rendered_content column for a user message
UpdateMessageRenderedContent(ctx context.Context, sessionID, messageID string, renderedContent string) error
+ // UpdateMessageContextCheckpoint writes only the context_checkpoint column
+ // of an assistant message.
+ UpdateMessageContextCheckpoint(
+ ctx context.Context, sessionID, messageID string, checkpoint *types.ContextCheckpoint,
+ ) error
+ // GetLatestContextCheckpoint returns the newest assistant message in the
+ // session that carries a context checkpoint, projected to the columns
+ // history loading needs, or nil when there is none.
+ GetLatestContextCheckpoint(ctx context.Context, sessionID string) (*types.Message, error)
// DeleteMessage deletes a message
DeleteMessage(ctx context.Context, sessionID string, id string) error
// DeleteMessagesBySessionID deletes all messages belonging to a session
diff --git a/internal/types/message.go b/internal/types/message.go
index 32f7db04b..36e8fbced 100644
--- a/internal/types/message.go
+++ b/internal/types/message.go
@@ -410,6 +410,11 @@ type Message struct {
// failed checkpoint must never block the reply). A message without a
// checkpoint cannot serve as a fork point with sandbox state.
SandboxCheckpoint *SandboxCheckpoint `json:"sandbox_checkpoint,omitempty" gorm:"type:jsonb"`
+ // ContextCheckpoint is the agent compaction summary covering this turn
+ // and every turn before it (see ContextCheckpoint). Assistant messages
+ // only; nil unless a later turn's compaction ended exactly here. Internal
+ // to history loading, so it stays out of API responses.
+ ContextCheckpoint *ContextCheckpoint `json:"-" gorm:"type:jsonb;column:context_checkpoint"`
// Message creation timestamp
CreatedAt time.Time `json:"created_at"`
// Last update timestamp
diff --git a/migrations/sqlite/000024_message_context_checkpoint.down.sql b/migrations/sqlite/000024_message_context_checkpoint.down.sql
new file mode 100644
index 000000000..fa0921c4b
--- /dev/null
+++ b/migrations/sqlite/000024_message_context_checkpoint.down.sql
@@ -0,0 +1 @@
+ALTER TABLE messages DROP COLUMN context_checkpoint;
diff --git a/migrations/sqlite/000024_message_context_checkpoint.up.sql b/migrations/sqlite/000024_message_context_checkpoint.up.sql
new file mode 100644
index 000000000..1a133430e
--- /dev/null
+++ b/migrations/sqlite/000024_message_context_checkpoint.up.sql
@@ -0,0 +1,3 @@
+-- Mirrors versioned migration 000104_message_context_checkpoint: the agent
+-- compaction summary persisted on the last turn it covers.
+ALTER TABLE messages ADD COLUMN context_checkpoint TEXT;
diff --git a/migrations/versioned/000104_message_context_checkpoint.down.sql b/migrations/versioned/000104_message_context_checkpoint.down.sql
new file mode 100644
index 000000000..7f173f6c2
--- /dev/null
+++ b/migrations/versioned/000104_message_context_checkpoint.down.sql
@@ -0,0 +1 @@
+ALTER TABLE messages DROP COLUMN IF EXISTS context_checkpoint;
diff --git a/migrations/versioned/000104_message_context_checkpoint.up.sql b/migrations/versioned/000104_message_context_checkpoint.up.sql
new file mode 100644
index 000000000..f4a1120fb
--- /dev/null
+++ b/migrations/versioned/000104_message_context_checkpoint.up.sql
@@ -0,0 +1,7 @@
+-- Migration: 000104_message_context_checkpoint
+-- Agent compaction summaries persisted on the assistant message of the last
+-- turn they cover, so the next turn's history starts from the summary instead
+-- of summarizing the same turns again.
+ALTER TABLE messages ADD COLUMN IF NOT EXISTS context_checkpoint JSONB;
+
+COMMENT ON COLUMN messages.context_checkpoint IS 'Agent compaction summary covering this turn and every turn before it';
diff --git a/website-docs/03-features/07-agent.md b/website-docs/03-features/07-agent.md
index 11ad95c7f..25ee6bf6d 100644
--- a/website-docs/03-features/07-agent.md
+++ b/website-docs/03-features/07-agent.md
@@ -514,13 +514,17 @@ var ToolCapabilityRequirements = map[string]ToolRequirement{
若压缩后仍超预算,最后才裁短工具结果,工具结果预算取窗口的 20%,限制在 8192–32768 Token。没有可压缩内容或释放空间不足 5% 时,记下当前消息数量,避免在同一上下文大小反复花费模型调用。成功压缩会清除旧 usage 基线,并发出 context_compacted 事件,包含前后 Token/消息数、原因、split_turn 与 degraded。
+**压缩点持久化**。当摘要的历史部分恰好结束在某个已落库轮次的末尾时,引擎把这段摘要作为压缩点(`messages.context_checkpoint`)写回该轮的 assistant 消息,下一轮直接从它开始,不再对同一段历史重复摘要。历史消息在重建时带上所属轮次的 assistant 消息 ID(`chat.Message.TurnID`,不上线),据此判断切点是否落在轮次边界。以下情况不写压缩点:切点落在某个已落库轮次内部(例如停在追加消息处);摘要只覆盖当前轮;历史摘要回退成了原始归档(degraded)。切分轮前半段的摘要不写入压缩点,因为该轮下次会被完整重放。写入只更新这一列,失败时仅记日志,不影响本轮。压缩点存在被覆盖的那一轮上,所以会话分叉复制该轮时会一起复制,删除该轮时压缩点也随之失效。
+
提供商报告上下文超限(错误或响应截断判据)时,还可强制压缩并重试一次。仅因生成耗尽 completion 预算的截断不应误判成上下文超限。具体提供商错误识别见 `internal/agent/compaction/overflow.go`。
#### 会话历史(agent_history) {#_4-3-会话历史-agent-history}
跨轮历史由 `LoadAgentHistory`(`internal/application/service/agent_history.go`)每轮从 messages 表重建(DB 是唯一事实来源,无 Redis/内存缓存):
-- 取 `HistoryTurns × 4`(最低 50)条原始消息,按 `RequestID` 配对 user/assistant,只保留 assistant 已完成(`IsCompleted`)的完整轮,按时间排序取最近 `HistoryTurns` 轮;
+- 取 `HistoryTurns × 4`(最低 50)条原始消息,按 `RequestID` 配对 user/assistant,只保留 assistant 已完成(`IsCompleted`)的完整轮,按时间排序;
+- 会话中存在压缩点(见[上下文压缩与溢出恢复](#_4-2-上下文压缩与溢出恢复))时,取最新的一个:它所在的轮及更早的轮由一条摘要消息代替,放在历史最前面,之后的轮原样重放。压缩点早于本次读取范围时按时间判断,读到的轮都在它之后。压缩点查询失败时退回无压缩点的历史;
+- 再取最近 `HistoryTurns` 轮。这个上限只约束压缩点之后原样重放的轮,不包括摘要;
- 每轮展开为:user 消息(含图片 caption 与附件 prompt;忽略 `RenderedContent` 快照,避免将旧渲染协议带入上下文)→ 每个含工具调用的 `AgentStep` 展开为 assistant(with tool_calls) + 若干 tool 消息 → 末尾一条规范化最终答案 assistant 消息(剥离 `<think>` 块);
- 历史中的 tool 消息内容用 `CompactToolOutputForHistory`(`internal/agent/tools/persist.go`)压缩:带 `display_type` 的大载荷(如 `knowledge_chunks_list` 的 chunks、`grep_results` 的 chunk_results)替换为一行摘要(如 `"Listed 20/87 chunks from X (content omitted from history)"`)。