enable runtime compaction tracking and refresh compaction config docs

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",

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",

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",

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,
+			Key:             s.Key,
-			Kind:      s.Kind,
+			Kind:            s.Kind,
-			Summary:   s.Summary,
+			Summary:         s.Summary,
-			UpdatedAt: s.Updated,
+			CompactionCount: s.CompactionCount,
+			UpdatedAt:       s.Updated,
 		})
 	}
 	return out

pkg/tools/sessions_tool.go

@@ -11,10 +11,11 @@ import (
 )
 
 type SessionInfo struct {
-	Key       string
+	Key             string
-	Kind      string
+	Kind            string
-	Summary   string
+	Summary         string
-	UpdatedAt time.Time
+	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":