Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(session): mark no-op commits as skipped (#2931)

Qin Haojiefba6450abefe
diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.md
index a523fc2d9..d74463c34 100644
--- a/docs/en/api/05-sessions.md
+++ b/docs/en/api/05-sessions.md
@@ -996,7 +996,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
#### 1. API Implementation Introduction
-Commit a session. Message archiving (Phase 1) completes immediately. Summary generation and memory extraction (Phase 2) run asynchronously in the background. Returns a `task_id` for polling status.
+Commit a session. Message archiving (Phase 1) completes immediately. Summary generation and memory extraction (Phase 2) run asynchronously in the background when messages are archived. Archived commits return `status: "accepted"` with a `task_id`; no-op commits return `status: "skipped"` with `task_id: null`.
**Two-Phase Commit Flow:**
- **Phase 1 (Synchronous)**: Snapshot current messages, clear live session, create archive directory, write original messages
@@ -1004,6 +1004,7 @@ Commit a session. Message archiving (Phase 1) completes immediately. Summary gen
**Notes:**
- Rapid consecutive commits on the same session are accepted; each request gets its own `task_id`.
+- Empty sessions, or commits where all messages remain inside `keep_recent_count`, complete synchronously with `archived: false`.
- Background Phase 2 work is serialized by archive order: archive `N+1` waits until archive `N` writes `.done`.
- If an earlier archive failed and left no `.done`, later commit requests fail with `FAILED_PRECONDITION` until that failure is resolved.
- If committed messages contain durable facts, judgments, preferences, or events that mention `viking://resources/...`, memory extraction preserves the resource as a markdown link and records it in `MEMORY_FIELDS.resource_refs`.
@@ -1102,6 +1103,22 @@ ov session commit a1b2c3d4
}
```
+**No-op Response Example**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "status": "skipped",
+ "task_id": null,
+ "archive_uri": null,
+ "archived": false,
+ "reason": "no_messages"
+ }
+}
+```
+
---
### extract()
diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.md
index 4ed7ed3ac..f7bc8e46b 100644
--- a/docs/zh/api/05-sessions.md
+++ b/docs/zh/api/05-sessions.md
@@ -970,7 +970,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
#### 1. API 实现介绍
-提交会话。归档消息(Phase 1)立即完成,摘要生成和记忆提取(Phase 2)在后台异步执行。返回 `task_id` 用于查询后台任务状态。
+提交会话。归档消息(Phase 1)立即完成;有消息被归档时,摘要生成和记忆提取(Phase 2)在后台异步执行。产生归档的 commit 返回 `status: "accepted"` 和 `task_id`;没有可归档内容的 no-op commit 返回 `status: "skipped"` 和 `task_id: null`。
**两阶段提交流程**:
- **Phase 1(同步)**: 快照当前消息,清空 live session,创建归档目录,写入原始消息
@@ -978,6 +978,7 @@ curl -X POST http://localhost:1933/api/v1/sessions/a1b2c3d4/used \
**注意事项**:
- 同一 session 的多次快速连续 commit 会被接受;每次请求都会拿到独立的 `task_id`
+- 空 session,或所有消息都仍在 `keep_recent_count` 保留窗口内时,会同步完成并返回 `archived: false`
- 后台 Phase 2 会按 archive 顺序串行推进:`archive_N+1` 会等待 `archive_N` 写出 `.done` 后再继续
- 如果更早的 archive 已失败且没有 `.done`,后续 commit 会直接返回错误,直到该失败被处理
- 如果提交的消息中包含带 `viking://resources/...` 的长期事实、评价、偏好或事件,记忆抽取会把资源保留为 markdown 链接,并写入 `MEMORY_FIELDS.resource_refs`
@@ -1076,6 +1077,22 @@ ov session commit a1b2c3d4
}
```
+**No-op 响应示例**
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "session_id": "a1b2c3d4",
+ "status": "skipped",
+ "task_id": null,
+ "archive_uri": null,
+ "archived": false,
+ "reason": "no_messages"
+ }
+}
+```
+
---
### extract()
diff --git a/examples/openclaw-plugin/client.ts b/examples/openclaw-plugin/client.ts
index d6d2f932b..386135ad1 100644
--- a/examples/openclaw-plugin/client.ts
+++ b/examples/openclaw-plugin/client.ts
@@ -48,7 +48,7 @@ export type OpenVikingClientOptions = {
export type CommitSessionResult = {
session_id: string;
- /** "accepted" (async), "completed", "failed", or "timeout" (wait mode). */
+ /** "accepted" (async), "skipped" (no archive), "completed", "failed", or "timeout" (wait mode). */
status: string;
task_id?: string;
archive_uri?: string;
diff --git a/openviking/session/session.py b/openviking/session/session.py
index c36df4689..121ed8771 100644
--- a/openviking/session/session.py
+++ b/openviking/session/session.py
@@ -1118,10 +1118,11 @@ class Session:
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
- "status": "accepted",
+ "status": "skipped",
"task_id": None,
"archive_uri": None,
"archived": False,
+ "reason": "no_messages",
"trace_id": trace_id,
}
@@ -1137,10 +1138,11 @@ class Session:
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
- "status": "accepted",
+ "status": "skipped",
"task_id": None,
"archive_uri": None,
"archived": False,
+ "reason": "no_messages",
"trace_id": trace_id,
}
@@ -1157,7 +1159,7 @@ class Session:
get_current_telemetry().set("memory.extracted", 0)
return {
"session_id": self.session_id,
- "status": "accepted",
+ "status": "skipped",
"task_id": None,
"archive_uri": None,
"archived": False,