Skip to content

Feat/session auto commit v2 #3736

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
qin-ctx merged 3 commits into from
Aug 5, 2026
Merged

Feat/session auto commit v2 #3736

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
62e8d72
feat(session): add best-effort automatic session commit
zhoujh01 Aug 4, 2026
53e8244
refactor(session): flatten auto_commit_policy to top-level create field
zhoujh01 Aug 4, 2026
e95d62d
fix(session): address auto-commit review findings
zhoujh01 Aug 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
62 changes: 60 additions & 2 deletions docs/en/api/05-sessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Create a new session. Sessions are containers for conversations, storing message

**Code Entries:**
- `openviking/session/session.py:Session.__init__()` - Core Session class
- `openviking/session/auto_commit_policy.py:AutoCommitPolicy` - Auto-commit policy defaults and validation
- `openviking/server/routers/sessions.py:create_session()` - HTTP route
- `openviking_cli/client/base.py:BaseClient.create_session()` - Python SDK
- `crates/ov_cli/src/commands/session.rs:new_session()` - CLI command
Expand All @@ -43,6 +44,19 @@ Create a new session. Sessions are containers for conversations, storing message
|-----------|------|----------|---------|-------------|
| session_id | str | No | None | Session ID. Creates new session with auto-generated ID if None |
| memory_policy | object | No | None | Default memory extraction policy for the session. Optional `self` and `peer` switches control write targets, optional `working_memory.enabled=false` skips archive summaries, and optional top-level `memory_types` limits extraction to specific enabled memory schemas. Use JSON booleans for every `enabled` value. Legacy boolean-like values remain accepted temporarily (including string `"false"`, which is parsed as false) but emit a deprecation warning. When `memory_types` is omitted or `null`, all enabled memory schemas are allowed. Invalid shapes or unknown memory types are rejected with `InvalidArgumentError`. |
| auto_commit_policy | object | No | None | Optional auto-commit policy (see table below). Any provided fields are validated, clamped to their bounds, and merged over the defaults; the effective policy is returned in the response `result.auto_commit_policy` and persisted into session metadata. If no policy is provided, auto commit is disabled unless `memory.session_auto_commit.default_enabled=true`. The policy is immutable after creation. |

`auto_commit_policy` fields (all optional; omitted fields fall back to the defaults when a policy is present):

| Field | Type | Default | Max | Description |
|-------|------|---------|-----|-------------|
| `pending_token_threshold` | int | 10000 | 50000 | When uncommitted pending tokens exceed this value (strictly greater-than), an auto commit is triggered after a message write. |
| `message_count_threshold` | int | 50 | 500 | When the uncommitted live message count exceeds this value (strictly greater-than), an auto commit is triggered after a message write. |
| `idle_timeout_seconds` | int | 86400 | 604800 | After this many idle seconds, a session with uncommitted content becomes eligible for the server-side idle scheduler. An idle-timeout commit archives the full backlog and ignores `keep_recent_count`. |
| `keep_recent_count` | int | 2 | 500 | Number of recent live messages to keep (not archived) on a threshold-triggered auto commit. Idle-timeout commits ignore this and commit everything. |
| `min_commit_interval_seconds` | int | 0 | 604800 | Minimum seconds between two automatic commits (throttle). |

All fields have a minimum of `0` and are clamped into `[0, max]`. Unknown keys are rejected with `InvalidArgumentError`.

#### 3. Usage Examples

Expand All @@ -63,6 +77,20 @@ curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"session_id": "my-custom-session-id"}'

# Create new session with a custom auto-commit policy
curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"auto_commit_policy": {
"pending_token_threshold": 8000,
"message_count_threshold": 40,
"idle_timeout_seconds": 600,
"keep_recent_count": 10,
"min_commit_interval_seconds": 0
}
}'
```

**Python SDK**
Expand All @@ -80,6 +108,18 @@ print(f"Session ID: {result['session_id']}")
# Create new session with specified ID
result = await client.create_session(session_id="my-custom-session-id")
print(f"Session ID: {result['session_id']}")

# Create new session with a custom auto-commit policy
result = await client.create_session(
auto_commit_policy={
"pending_token_threshold": 8000,
"message_count_threshold": 40,
"idle_timeout_seconds": 600,
"keep_recent_count": 10,
"min_commit_interval_seconds": 0,
}
)
print(result["auto_commit_policy"])
```

**TypeScript SDK**
Expand Down Expand Up @@ -118,7 +158,8 @@ ov session new
"user": {
"account_id": "default",
"user_id": "alice"
}
},
"auto_commit_policy": null
},
"time": 0.1
}
Expand Down Expand Up @@ -227,6 +268,7 @@ Get session details including metadata, message statistics, commit history, etc.
- `commit_count`: Number of successful commits
- `memories_extracted`: Count statistics of extracted memories by category
- `last_commit_at`: Time of last commit
- `auto_commit_policy`: Effective auto-commit policy with defaults filled in; `null` when not enabled

**Code Entries:**
- `openviking/session/session.py:Session.load()` - Session loading
Expand Down Expand Up @@ -343,13 +385,29 @@ ov session get a1b2c3d4
"account_id": "default",
"user_id": "alice"
},
"pending_tokens": 450
"pending_tokens": 450,
"auto_commit_policy": {
"pending_token_threshold": 10000,
"message_count_threshold": 50,
"idle_timeout_seconds": 86400,
"keep_recent_count": 2,
"min_commit_interval_seconds": 0
}
}
}
```

---

### Updating Session Config

The auto-commit policy is immutable after creation. Set `auto_commit_policy` when
creating the session, then use `GET /api/v1/sessions/{session_id}` to inspect the
effective config. Runtime session-config updates are not exposed by the Sessions
API.

---

### list_tool_results()

List large tool results externalized from a session.
Expand Down
54 changes: 54 additions & 0 deletions docs/en/guides/01-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1168,6 +1168,59 @@ Legacy compatibility example:
}
```

##### Session Auto Commit Configuration

`memory.session_auto_commit` controls server-wide automatic session commit behavior.

```json
{
"memory": {
"session_auto_commit": {
"default_enabled": false,
"idle_enabled": false,
"check_interval_seconds": 60.0,
"scan_batch_size": 16,
"scan_batch_pause_seconds": 0.0
}
}
}
```

| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `default_enabled` | bool | Enables auto commit by default for newly created sessions that do not explicitly provide `auto_commit_policy`. When `false`, those sessions keep auto commit disabled | `false` |
| `idle_enabled` | bool | Enables the server-side idle-timeout auto-commit scheduler. When disabled, the idle scheduler is not started. Token- and message-count immediate triggering still works | `false` |
| `check_interval_seconds` | float | Poll interval for the idle scheduler in seconds. Must be greater than `0` | `60.0` |
| `scan_batch_size` | int | Maximum number of session meta files read concurrently in each idle scan batch. Must be greater than `0` | `16` |
| `scan_batch_pause_seconds` | float | Optional pause between idle scan batches, in seconds. Use this to reduce storage pressure during large scans | `0.0` |

Notes:

- `memory.session_auto_commit` is a server-wide control surface, not a per-session business policy.
- Per-session auto-commit behavior is configured through the session-level `auto_commit_policy` (see the table below). It is set only when creating a session (`POST /api/v1/sessions` with a top-level `auto_commit_policy` field) and viewed via `GET /api/v1/sessions/{session_id}`; runtime config PATCH is not supported.
- When `default_enabled=false`, sessions created without `auto_commit_policy` keep auto commit disabled and return `auto_commit_policy: null`. Providing `{}` or any policy field explicitly enables auto commit for that session and fills missing fields from the defaults below.
- When `default_enabled=true`, sessions created without `auto_commit_policy` get the default policy below.
- When `idle_enabled=false`:
- `SessionAutoCommitScheduler` is not started
- When `idle_enabled=true`:
- `SessionAutoCommitScheduler` wakes up periodically and scans session `.meta.json` files under AGFS `/local/{account}/user/{user}/sessions`
- It does not perform a dedicated startup recovery sweep; idle detection happens only on periodic scans
- Token- and message-count auto commit run inline after message writes, do not depend on the scheduler, and are unaffected by this switch.

###### Per-session Auto Commit Policy

When a session carries an `auto_commit_policy`, any field you omit falls back to the recommended default below. Sessions without a stored policy keep auto commit disabled. Values are clamped into `[0, max]`, and unknown keys are rejected with `InvalidArgumentError`. See [Sessions API](../api/05-sessions.md#create_session) for how to set and view it.

| Field | Type | Default | Max | Description |
|-------|------|---------|-----|-------------|
| `pending_token_threshold` | int | 10000 | 50000 | When uncommitted pending tokens exceed this value (strictly greater-than), an auto commit is triggered after a message write. |
| `message_count_threshold` | int | 50 | 500 | When the uncommitted live message count exceeds this value (strictly greater-than), an auto commit is triggered after a message write. |
| `idle_timeout_seconds` | int | 86400 | 604800 | After this many idle seconds, a session with uncommitted content becomes eligible for the server-side idle scheduler. Idle-timeout commits archive the full backlog and ignore `keep_recent_count`. |
| `keep_recent_count` | int | 2 | 500 | Number of recent live messages to keep (not archived) on a threshold-triggered auto commit. Idle-timeout commits ignore this and commit everything. |
| `min_commit_interval_seconds` | int | 0 | 604800 | Minimum seconds between two automatic commits (throttle). |

Code entry: `openviking/session/auto_commit_policy.py:AutoCommitPolicy`.


##### S3 Backend Configuration

Expand Down Expand Up @@ -1428,6 +1481,7 @@ For memory-related settings, add a `memory` section in `ov.conf`:
| `extraction_enabled` | Whether session commit runs long-term memory extraction. | `true` |
| `session_skill_extraction_enabled` | Whether session commit also extracts reusable skills into the current user's skill directory. | `false` |
| `link_enabled` | Whether memory extraction writes and resolves memory links. | `false` |
| `session_auto_commit` | Server-wide automatic session commit controls. This belongs under `memory`, not under `server`; see [Session Auto Commit Configuration](#session-auto-commit-configuration). | See section above |

### ovcli.conf

Expand Down
61 changes: 59 additions & 2 deletions docs/zh/api/05-sessions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ Session API 按认证用户作用域访问会话，并返回 canonical user sess

**代码入口**：
- `openviking/session/session.py:Session.__init__()` - Session 核心类
- `openviking/session/auto_commit_policy.py:AutoCommitPolicy` - 自动 commit 策略的默认值与校验
- `openviking/server/routers/sessions.py:create_session()` - HTTP 路由
- `openviking_cli/client/base.py:BaseClient.create_session()` - Python SDK
- `crates/ov_cli/src/commands/session.rs:new_session()` - CLI 命令
Expand All @@ -43,6 +44,19 @@ Session API 按认证用户作用域访问会话，并返回 canonical user sess
|------|------|------|--------|------|
| session_id | str | 否 | None | 会话 ID。如果为 None，则创建一个自动生成 ID 的新会话 |
| memory_policy | object | 否 | None | 会话默认的记忆抽取策略。可选的 `self` 和 `peer` 开关控制写入目标；可选的 `working_memory.enabled=false` 跳过 archive summary；可选的顶层 `memory_types` 将抽取限制为指定的 enabled memory schema。所有 `enabled` 值都应使用 JSON 布尔值。旧版 boolean-like 值暂时仍兼容（字符串 `"false"` 会正确解析为 false），但会产生弃用警告。未传或为 `null` 时允许所有 enabled memory schema。非法结构或未知 memory type 会以 `InvalidArgumentError` 拒绝。 |
| auto_commit_policy | object | 否 | None | 可选的自动 commit 策略（见下表）。传入的字段会被校验并 clamp 到取值范围，然后合并到默认值之上；最终生效的策略会在响应的 `result.auto_commit_policy` 中返回，并持久化到 session meta。未传 policy 时 auto commit 关闭，除非 `memory.session_auto_commit.default_enabled=true`。该策略创建后不可变。 |

`auto_commit_policy` 字段（均为可选；存在 policy 时，未传字段回退到默认值）：

| 字段 | 类型 | 默认值 | 上限 | 说明 |
|------|------|--------|------|------|
| `pending_token_threshold` | int | 10000 | 50000 | 当未提交的 pending token 超过该值（严格大于）时，会在消息写入后触发一次自动 commit。 |
| `message_count_threshold` | int | 50 | 500 | 当未提交的 live message 数量超过该值（严格大于）时，会在消息写入后触发一次自动 commit。 |
| `idle_timeout_seconds` | int | 86400 | 604800 | 有未提交内容的 session 在空闲这么多秒后，进入服务端 idle scheduler 的处理范围。idle 触发的 commit 会归档全部积压消息，并忽略 `keep_recent_count`。 |
| `keep_recent_count` | int | 2 | 500 | 阈值触发的自动 commit 后保留（不归档）的最近 live message 数量。idle 超时触发的 commit 会忽略该值并归档所有消息。 |
| `min_commit_interval_seconds` | int | 0 | 604800 | 两次自动 commit 之间的最小间隔秒数（节流）。 |

所有字段最小值为 `0`，会被 clamp 到 `[0, 上限]`。未知字段会以 `InvalidArgumentError` 拒绝。

#### 3. 使用示例

Expand All @@ -63,6 +77,20 @@ curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{"session_id": "my-custom-session-id"}'

# 创建带自定义自动 commit 策略的新会话
curl -X POST http://localhost:1933/api/v1/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: your-key" \
-d '{
"auto_commit_policy": {
"pending_token_threshold": 8000,
"message_count_threshold": 40,
"idle_timeout_seconds": 600,
"keep_recent_count": 10,
"min_commit_interval_seconds": 0
}
}'
```

**Python SDK**
Expand All @@ -80,6 +108,18 @@ print(f"Session ID: {result['session_id']}")
# 创建指定 ID 的新会话
result = await client.create_session(session_id="my-custom-session-id")
print(f"Session ID: {result['session_id']}")

# 创建带自定义自动 commit 策略的新会话
result = await client.create_session(
auto_commit_policy={
"pending_token_threshold": 8000,
"message_count_threshold": 40,
"idle_timeout_seconds": 600,
"keep_recent_count": 10,
"min_commit_interval_seconds": 0,
}
)
print(result["auto_commit_policy"])
```

**TypeScript SDK**
Expand Down Expand Up @@ -118,7 +158,8 @@ ov session new
"user": {
"account_id": "default",
"user_id": "alice"
}
},
"auto_commit_policy": null
},
"time": 0.1
}
Expand Down Expand Up @@ -227,6 +268,7 @@ ov session list
- `commit_count`: 成功提交的次数
- `memories_extracted`: 各类记忆的提取数量统计
- `last_commit_at`: 最后一次提交的时间
- `auto_commit_policy`: 填充默认值后的生效自动 commit 策略；未启用时为 `null`

**代码入口**：
- `openviking/session/session.py:Session.load()` - 会话加载
Expand Down Expand Up @@ -343,13 +385,28 @@ ov session get a1b2c3d4
"account_id": "default",
"user_id": "alice"
},
"pending_tokens": 450
"pending_tokens": 450,
"auto_commit_policy": {
"pending_token_threshold": 10000,
"message_count_threshold": 50,
"idle_timeout_seconds": 86400,
"keep_recent_count": 2,
"min_commit_interval_seconds": 0
}
}
}
```

---

### 更新 Session 配置

自动 commit 策略创建后不可变。请在创建 session 时设置
`auto_commit_policy`，之后通过 `GET /api/v1/sessions/{session_id}` 查看生效配置。
Sessions API 不提供运行期 session 配置更新接口。

---

### list_tool_results()

列出会话中因体积较大而外置保存的工具结果。
Expand Down
Loading
Loading