From d181525b88556ba1836168ad2f7cd0b60bd73409 Mon Sep 17 00:00:00 2001
From: DBT <nvue.dev@gmail.com>
Date: Mon, 23 Feb 2026 15:32:05 +0000
Subject: [PATCH] enable runtime compaction tracking and refresh compaction
 config docs

---
 README.md                  |  9 +++++++--
 README_EN.md               |  9 +++++++--
 config.example.json        |  5 +++++
 pkg/agent/loop.go          |  9 +++++----
 pkg/tools/sessions_tool.go | 11 ++++++-----
 5 files changed, 30 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index e417b35..f13a642 100644
--- a/README.md
+++ b/README.md
@@ -137,16 +137,21 @@ clawgo channel test --channel telegram --to <chat_id> -m "ping"
 ## 🧠 记忆、自主与上下文压缩
 
 - 启动会读取 `AGENTS.md`、`SOUL.md`、`USER.md` 作为行为约束与语义上下文。
-- 网关启动后会执行一次自检任务，结合历史会话与 `memory/HEARTBEAT.md` 判断是否继续未完成任务。
+- 网关启动后会执行一次自检任务，结合历史会话与 `HEARTBEAT.md` 判断是否继续未完成任务。
 - 上下文压缩同时按消息数量阈值和上下文体积阈值触发，控制 token 成本与长会话稳定性。
 - 上下文压缩模式支持 `summary`、`responses_compact`、`hybrid`；`responses_compact` 需要代理配置 `protocol=responses` 且 `supports_responses_compact=true`。
 - 分层记忆支持 `profile / project / procedures / recent notes`。
 
-上下文压缩配置示例：
+心跳与上下文压缩配置示例：
 
 ```json
 "agents": {
   "defaults": {
+    "heartbeat": {
+      "enabled": true,
+      "every_sec": 1800,
+      "ack_max_chars": 64
+    },
     "context_compaction": {
       "enabled": true,
       "mode": "summary",
diff --git a/README_EN.md b/README_EN.md
index 49d03ae..81d2eeb 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -137,16 +137,21 @@ clawgo channel test --channel telegram --to <chat_id> -m "ping"
 ## 🧠 Memory, Autonomy, and Context Compaction
 
 - On startup, the agent loads `AGENTS.md`, `SOUL.md`, and `USER.md` as behavior and semantic constraints.
-- Gateway startup triggers a self-check task using history and `memory/HEARTBEAT.md` to decide whether unfinished tasks should continue.
+- Gateway startup triggers a self-check task using history and `HEARTBEAT.md` to decide whether unfinished tasks should continue.
 - Context compaction is triggered by both message-count and transcript-size thresholds.
 - Compaction modes are `summary`, `responses_compact`, and `hybrid`; `responses_compact` requires `protocol=responses` and `supports_responses_compact=true` on the active proxy.
 - Layered memory supports `profile / project / procedures / recent notes`.
 
-Context compaction config example:
+Heartbeat + context compaction config example:
 
 ```json
 "agents": {
   "defaults": {
+    "heartbeat": {
+      "enabled": true,
+      "every_sec": 1800,
+      "ack_max_chars": 64
+    },
     "context_compaction": {
       "enabled": true,
       "mode": "summary",
diff --git a/config.example.json b/config.example.json
index 7b3ba83..731a338 100644
--- a/config.example.json
+++ b/config.example.json
@@ -7,6 +7,11 @@
       "max_tokens": 8192,
       "temperature": 0.7,
       "max_tool_iterations": 20,
+      "heartbeat": {
+        "enabled": true,
+        "every_sec": 1800,
+        "ack_max_chars": 64
+      },
       "context_compaction": {
         "enabled": true,
         "mode": "summary",
diff --git a/pkg/agent/loop.go b/pkg/agent/loop.go
index 1544fe4..10f4605 100644
--- a/pkg/agent/loop.go
+++ b/pkg/agent/loop.go
@@ -833,10 +833,11 @@ func alSessionListForTool(sm *session.SessionManager, limit int) []tools.Session
 	out := make([]tools.SessionInfo, 0, len(items))
 	for _, s := range items {
 		out = append(out, tools.SessionInfo{
-			Key:       s.Key,
-			Kind:      s.Kind,
-			Summary:   s.Summary,
-			UpdatedAt: s.Updated,
+			Key:             s.Key,
+			Kind:            s.Kind,
+			Summary:         s.Summary,
+			CompactionCount: s.CompactionCount,
+			UpdatedAt:       s.Updated,
 		})
 	}
 	return out
diff --git a/pkg/tools/sessions_tool.go b/pkg/tools/sessions_tool.go
index 4103776..2325a97 100644
--- a/pkg/tools/sessions_tool.go
+++ b/pkg/tools/sessions_tool.go
@@ -11,10 +11,11 @@ import (
 )
 
 type SessionInfo struct {
-	Key       string
-	Kind      string
-	Summary   string
-	UpdatedAt time.Time
+	Key             string
+	Kind            string
+	Summary         string
+	CompactionCount int
+	UpdatedAt       time.Time
 }
 
 type SessionsTool struct {
@@ -152,7 +153,7 @@ func (t *SessionsTool) Execute(ctx context.Context, args map[string]interface{})
 		var sb strings.Builder
 		sb.WriteString("Sessions:\n")
 		for _, s := range items {
-			sb.WriteString(fmt.Sprintf("- %s kind=%s updated=%s\n", s.Key, s.Kind, s.UpdatedAt.Format(time.RFC3339)))
+			sb.WriteString(fmt.Sprintf("- %s kind=%s compactions=%d updated=%s\n", s.Key, s.Kind, s.CompactionCount, s.UpdatedAt.Format(time.RFC3339)))
 		}
 		return strings.TrimSpace(sb.String()), nil
 	case "history":