Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
feat(session): let deployments default automatic commits (#4425)
czyyyy071ac184eb51
diff --git a/docs/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex de510d7e6..4ced0aadf 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -146,12 +146,12 @@ Core modules at a glance (detailed further in the per-dimension sections):- **Implicit session creation**: Plugins generally do not call `POST /sessions` explicitly (with `dsh` being the only exception, as it sends a creation request carrying only `session_id`). Instead, the server creates the session using `auto_create=True` upon receiving the first `POST /sessions/{id}/messages(/batch)` request. On the recall side, calling `_load_session(auto_create=True)` under `mode="context"` also creates a session, meaning the very first recall action will initialize the session on the server.- **Two-phase commit**: `POST /sessions/{id}/commit` returns only after Phase 1 (archiving) has completed synchronously. Phase 2 (memory extraction) runs as a background task, returning a `task_id`. The server default for `keep_recent_count` is **0** (meaning it archives everything, leaving no live tail).-- **Server-side auto-commit is disabled by default, and the session creation paths used by plugins never enable it**:+- **Server-side auto-commit is disabled by default unless an explicit or deployment-default policy enables it**:- `memory.session_auto_commit.default_enabled = false` and `idle_enabled = false` (`memory_config.py:15-16`). Auto-commit is disabled for sessions lacking a storage policy (`session_service.py:637-638`). Furthermore, the idle scanner isn't even instantiated when `idle_enabled=false` (`core.py:440-448`), effectively acting as a double gate.- - The `auto_create` path triggered by `POST /messages` accepts no policy arguments; only `POST /sessions` (creation) and `PATCH /sessions/{id}/config` can set the `auto_commit_policy`.+ - The `auto_create` path triggered by `POST /messages` accepts no policy arguments, but it inherits `server.user_config_defaults.auto_commit_policy` when configured. `POST /sessions` and `PATCH /sessions/{id}/config` remain the explicit per-session controls.- Currently, no plugin sends an `auto_commit_policy`. Among first-party clients, only the **ov CLI** does this (`ov session new --auto-commit-policy-json` / `--no-auto-commit`, `ov session config set`).- When a policy is explicitly enabled, the server defaults are: `pending_token_threshold=150000` (strictly greater than), `message_count_threshold=100`, `idle_timeout_seconds=86400`, `keep_recent_count=0`, and `min_commit_interval_seconds=0`. Note that this set of server defaults operates independently of the plugin clients' configuration (which is typically 20000/10).-- **Consequence**: As it stands, every auto-commit relies on threshold logic implemented individually by each client ([§3.3](#_3-3-session-and-commit-lifecycle)), with no server-side fallback. If a process dies abnormally, any lingering pending messages are only archived and extracted when a subsequent commit is manually triggered in that same session.+- **Consequence**: Plugins can rely on `server.user_config_defaults.auto_commit_policy` for new-session token/message thresholds; idle-timeout recovery additionally requires `memory.session_auto_commit.idle_enabled=true`. Without that fallback, clients must still arrange their own commit path ([§3.3](#_3-3-session-and-commit-lifecycle)).- **Externalized tool output**: The server sets `tool_output_externalization.enabled=True` with `threshold_chars=20000` (`server/config.py:257-258`). Clients commonly raise `captureToolMaxChars` to 1000000 purely as a fallback mechanism, since the actual truncation and externalization occur on the server. Externalized results are then referenced via `tool_output_ref` (for context, openclaw provides three dedicated tools specifically for reading these references).- **Server-side recall timeout fuses**: Configured via `retrieval.recall_intent_timeout_s=5.0` (for query expansion), `recall_rewrite_timeout_s=30.0` (for digests, [§3.2.5](#_3-2-5-recall-digest)), and `enable_intent=true`. Client timeout budgets are derived directly from these two timeout values ([§3.2.4](#_3-2-4-timeout-and-budget-chain)).@@ -698,7 +698,7 @@ The last three headers are optional; however, omitting them disables workspace p## 6.3 Path ②: Programmatic integration-- **Direct REST**: Trigger recall via `POST /api/v1/search/search` (note that expansion and deduplication require `mode:"context"` alongside a `session_id`, as per [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths); pass `rewrite` to generate a server-side digest, see [§3.2.5](#_3-2-5-recall-digest)). Write data using `POST /api/v1/sessions/{id}/messages/batch` (supports up to 100 messages per batch with `auto_create`). Finalize sessions via `POST /api/v1/sessions/{id}/commit`, and retrieve content using `GET /api/v1/content/read` and related endpoints. To enable server-side auto-commits, explicitly pass the `auto_commit_policy` during `POST /api/v1/sessions`, or modify it later via `PATCH /{id}/config` ([§2.3](#_2-3-server-side-session-and-commit-semantics)).+- **Direct REST**: Trigger recall via `POST /api/v1/search/search` (note that expansion and deduplication require `mode:"context"` alongside a `session_id`, as per [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths); pass `rewrite` to generate a server-side digest, see [§3.2.5](#_3-2-5-recall-digest)). Write data using `POST /api/v1/sessions/{id}/messages/batch` (supports up to 100 messages per batch with `auto_create`). Finalize sessions via `POST /api/v1/sessions/{id}/commit`, and retrieve content using `GET /api/v1/content/read` and related endpoints. Auto-commit can come from `server.user_config_defaults.auto_commit_policy`, `POST /api/v1/sessions`, or `PATCH /{id}/config` ([§2.3](#_2-3-server-side-session-and-commit-semantics)).- **LangChain / LangGraph SDK** (`pip install langchain-openviking`): The `OpenVikingContextMiddleware` provides `wrap_model_call` (which injects recalled content into `<openviking_context>`) and `after_agent` (handling capture and commit actions according to the `CommitPolicy`, which defaults to `never`). Within this group, this is the only out-of-the-box automatic recall solution that includes both session management and a token budget. Its fault-tolerance strategy is to retry read-only methods once and never retry writes. Partial successes raise an `OpenVikingPartialWriteError`, allowing you to retry a specific slice based on `input_messages_consumed`. See [§7](#_7-appendix-non-coding-integrations-at-a-glance) B for more details.- **Open WebUI** (OpenAPI tool server): Running `python -m openviking_openwebui` launches a standalone process. By adding the resulting Tool Server URL to Open WebUI, you gain access to 7 tools (note that deletion and hooks are unsupported). See [§7](#_7-appendix-non-coding-integrations-at-a-glance) A for more details.## 6.4 Path ③: Reuse a Reference Implementation for Automatic Hooks@@ -708,7 +708,7 @@ If you need the full spectrum of automation—recall, capture, commit, and pendi- **`examples/memory-plugin-shared/lib/`** (Node): This provides a complete set of core modules. These include `recall-core` (three-tier degradation recall), `profile-inject`, `capture-utils` (message normalization and injection-echo protection), `pending-queue` (offline replay), `batch-send`, `mcp-proxy-core` (stdio↔HTTP proxy), `session-model` (session ID derivation), and `credentials`. To build a lightweight integration harness, you only need to implement an adapter layer that maps host lifecycle events to these modules. For example, `agent-hook-runtime.mjs` is a ready-made, all-in-one runtime shared by Cursor, Trae, and zcode. Wiring up a new host is usually just a matter of parsing its stdin JSON field names.- **The Agent Plugins 1.0 Portable Package** (under `agent-plugins/`): This offers a standardized portable format comprising `plugin.json`, the `skills/` directory, and `mcp.json` (stdio→HTTP proxy). It intentionally excludes automatic hooks—instead, recall and persistence rely on a skill that teaches the model to invoke the tools autonomously. This design makes it highly suitable for clients that follow the Agent Plugins specification for direct loading. Additionally, `plugin.test.mjs` defines spec-conformance checks (such as schema URL validation, naming rules, ensuring no secrets in static headers, and preventing `mcp.json` references from escaping the plugin root), which you can use as a linting baseline when packaging your own plugin.-**Three conventions you must follow** (to ensure behavior remains consistent with existing harnesses): ① The recall call site must forward the `session_id`, which enables server-side expansion and cross-turn deduplication (see [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths)); ② Do not allow the adapter's own timeout to override the deadline dictated by the helper; ③ You must arrange a commit path at shutdown. Otherwise, any remaining conversation tail that falls below the threshold will remain unarchived until a subsequent trigger occurs (see [§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). If the host does not provide a shutdown event, rely on the server-side idle fallback (enable `memory.session_auto_commit.idle_enabled` on the server and pass down a per-session policy). These three rules are exactly what `recall-session-wiring.test.mjs` enforces using cross-plugin regexes.+**Three conventions you must follow** (to ensure behavior remains consistent with existing harnesses): ① The recall call site must forward the `session_id`, which enables server-side expansion and cross-turn deduplication (see [§3.2.1](#_3-2-1-mechanism-foundation-one-shared-pipeline-two-server-side-paths)); ② Do not allow the adapter's own timeout to override the deadline dictated by the helper; ③ You must arrange a commit path at shutdown. Otherwise, any remaining conversation tail that falls below the threshold will remain unarchived until a subsequent trigger occurs (see [§3.3.3](#_3-3-3-shutdown-method-×-harness-outcome-matrix)). If the host has no shutdown event, enable `memory.session_auto_commit.idle_enabled` and provide a per-session or deployment-default policy. These three rules are exactly what `recall-session-wiring.test.mjs` enforces using cross-plugin regexes.---diff --git a/docs/en/api/05-sessions.md b/docs/en/api/05-sessions.mdindex 1500e7fdb..dd87f129c 100644--- a/docs/en/api/05-sessions.md+++ b/docs/en/api/05-sessions.md@@ -44,7 +44,7 @@ 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. Including `experiences` automatically activates `cases` and `trajectories`; without `experiences`, explicitly supplied `cases` and `trajectories` are ignored. 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 can later be partially updated or disabled through `update_session_config()`. |+| 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 omitted, the new Session inherits `server.user_config_defaults.auto_commit_policy`, then the existing `memory.session_auto_commit.default_enabled` behavior. The policy can later be partially updated or disabled through `update_session_config()`. |`auto_commit_policy` fields (all optional; omitted fields fall back to the defaults when a policy is present):diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.mdindex be58323e2..cb7d1b1d8 100644--- a/docs/en/guides/01-configuration.md+++ b/docs/en/guides/01-configuration.md@@ -1360,8 +1360,8 @@ 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). Set it when creating a session with `POST /api/v1/sessions`, or partially update it through `PATCH /api/v1/sessions/{session_id}/config`. Omitting `auto_commit_policy` from a PATCH preserves it; sending `null` disables automatic commits. Use `GET /api/v1/sessions/{session_id}` to inspect the effective policy.-- 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 `default_enabled=false`, sessions created without an explicit or `server.user_config_defaults.auto_commit_policy` policy keep auto commit disabled and return `auto_commit_policy: null`. Providing either policy enables auto commit and fills missing fields from the defaults below.+- When `default_enabled=true`, sessions without an explicit or deployment-default policy get the built-in policy below.- When `idle_enabled=false`:- `SessionAutoCommitScheduler` is not started- When `idle_enabled=true`:@@ -1730,6 +1730,7 @@ When running OpenViking as an HTTP service, add a `server` section to `ov.conf`:| `user_config_defaults.add_targets.resource_uri` | str | Deployment default resource add directory used when `add_resource` omits both `to` and `parent`. `viking://~/...` resolves per request user. | `null` || `user_config_defaults.add_targets.skill_uri` | str | Deployment default skill add root used when `add_skill` omits `target_uri`. Only `viking://~/skills` and `viking://agent/skills` are accepted. | `null` || `user_config_defaults.memory_policy` | object | Deployment default memory extraction policy used when neither the Session nor the User has an explicit policy. | `null` |+| `user_config_defaults.auto_commit_policy` | object | Deployment default auto-commit policy for newly created sessions without an explicit policy. | `null` || `agent_evolution.enabled` | bool | Startup cluster default for Agent Evolution. Account and Cluster Admin settings may override it at runtime. When enabled, session commits may generate or update cases, trajectories, and experiences according to the session `memory_policy`. Existing memories remain readable and searchable when disabled. | `false` |Omitting `auth_mode` (or setting it to `null`) selects `api_key` when a non-empty `root_api_key` is configured, and `dev` otherwise. `dev` is allowed only on localhost and accepts requests without authentication. An empty-string `root_api_key` is invalid.diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex b389f1270..d44c0bba6 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -147,12 +147,12 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章- **会话隐式创建**:插件普遍不显式调用 `POST /sessions`(dsh 例外,它会发一个只含 `session_id` 的 create);首次 `POST /sessions/{id}/messages(/batch)` 时由服务端 `auto_create=True` 建会话。召回侧 `mode="context"` 的 `_load_session(auto_create=True)` 也会建(第一次召回即在服务端创建会话)。- **commit 两阶段**:`POST /sessions/{id}/commit` 的 Phase 1(归档 archive)同步完成后才返回,Phase 2(记忆抽取)作为后台任务返回 `task_id`。`keep_recent_count` 服务端默认 **0**(全量归档,不留 live tail)。-- **服务端自动 commit 默认关闭,且插件建会话的路径不会打开它**:+- **服务端自动 commit 默认关闭,除非显式策略或部署级默认策略将其启用**:- `memory.session_auto_commit.default_enabled = false`、`idle_enabled = false`(`memory_config.py:15-16`);无存储 policy 的会话自动 commit 关闭(`session_service.py:637-638`);idle 扫描器在 `idle_enabled=false` 时根本不创建(`core.py:440-448`),构成双重门控。- - `POST /messages` 的 auto_create 不接受 policy 参数;只有 `POST /sessions`(create)与 `PATCH /sessions/{id}/config` 能设 `auto_commit_policy`。+ - `POST /messages` 的 auto_create 不接受 policy 参数,但配置后会继承 `server.user_config_defaults.auto_commit_policy`;`POST /sessions`(create)与 `PATCH /sessions/{id}/config` 仍是显式的 Session 级控制面。- 当前没有插件下发 `auto_commit_policy`;第一方客户端中会下发该字段的是 **ov CLI**(`ov session new --auto-commit-policy-json` / `--no-auto-commit`、`ov session config set`)。- policy 显式启用时,服务端默认阈值是 `pending_token_threshold=150000(严格大于)/ message_count_threshold=100 / idle_timeout_seconds=86400 / keep_recent_count=0 / min_commit_interval_seconds=0`。注意这组服务端默认值与各插件客户端的 20000/10 是相互独立的两层配置。-- **由此**:现状下所有自动 commit 都是客户端各自实现的阈值逻辑([§3.3](#_3-3-会话与-commit-生命周期)),服务端不做兜底;进程异常终止后遗留的 pending 消息,需在同一会话后续再触发 commit 才会归档与抽取。+- **由此**:插件可通过 `server.user_config_defaults.auto_commit_policy` 继承新 Session 的 token/message 阈值;idle timeout 兜底还需开启 `memory.session_auto_commit.idle_enabled=true`。未配置该 fallback 时,客户端仍需自行安排 commit 路径([§3.3](#_3-3-会话与-commit-生命周期))。- **tool output 外置**:服务端 `tool_output_externalization.enabled=True`、`threshold_chars=20000`(`server/config.py:257-258`)——客户端普遍把 `captureToolMaxChars` 设到 1000000 仅作兜底,真正的截断/外置在服务端做,externalized 结果通过 `tool_output_ref` 引用(openclaw 有三个专门工具读它)。- **服务端召回相关熔断**:`retrieval.recall_intent_timeout_s=5.0`(query expansion)、`recall_rewrite_timeout_s=30.0`(digest,[§3.2.5](#_3-2-5-召回再摘要))、`enable_intent=true`。客户端超时预算按这两条推导([§3.2.4](#_3-2-4-超时与预算链))。@@ -681,7 +681,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可## 6.3 路径②:程序化接入-- **直连 REST**:召回用 `POST /api/v1/search/search`(必须 `mode:"context"` + `session_id` 才有 expansion/去重,[§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径);可传 `rewrite` 获得服务端 digest,[§3.2.5](#_3-2-5-召回再摘要));写入用 `POST /api/v1/sessions/{id}/messages/batch`(≤100 条/批,auto_create);提交用 `POST /api/v1/sessions/{id}/commit`;读取用 `GET /api/v1/content/read` 等。要用服务端自动 commit,需在 `POST /api/v1/sessions` 时显式带 `auto_commit_policy`,或通过 `PATCH /{id}/config` 修改([§2.3](#_2-3-服务端会话与-commit-语义))。+- **直连 REST**:召回用 `POST /api/v1/search/search`(必须 `mode:"context"` + `session_id` 才有 expansion/去重,[§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径);可传 `rewrite` 获得服务端 digest,[§3.2.5](#_3-2-5-召回再摘要));写入用 `POST /api/v1/sessions/{id}/messages/batch`(≤100 条/批,auto_create);提交用 `POST /api/v1/sessions/{id}/commit`;读取用 `GET /api/v1/content/read` 等。自动 commit policy 可来自 `server.user_config_defaults.auto_commit_policy`、`POST /api/v1/sessions` 或 `PATCH /{id}/config`([§2.3](#_2-3-服务端会话与-commit-语义))。- **LangChain / LangGraph SDK**(`pip install langchain-openviking`):`OpenVikingContextMiddleware` 提供 `wrap_model_call`(把召回内容注入 `<openviking_context>`)与 `after_agent`(捕获 + 按 `CommitPolicy` 提交,默认 `never`)。这是本组唯一带 session + token 预算的现成自动召回;容错是"只读方法重试一次、写方法不重试",部分成功时抛 `OpenVikingPartialWriteError`(可按 `input_messages_consumed` 切片重试)。参考 [§7](#_7-附录-非-coding-集成速览) B。- **Open WebUI**(OpenAPI 工具服务器):`python -m openviking_openwebui` 起独立进程,在 Open WebUI 里添加 Tool Server URL,即可得 7 个工具(无删除、无 hook)。参考 [§7](#_7-附录-非-coding-集成速览) A。## 6.4 路径③:要自动 hook 面时复用参考实现@@ -691,7 +691,7 @@ MCP `write` / REST `content/write` 的三道 guard(`content_write.py`):可- **`examples/memory-plugin-shared/lib/`**(Node):包含完整的核心功能模块,例如 `recall-core`(三级降级召回)、`profile-inject`、`capture-utils`(消息归一 + 注入回流防护)、`pending-queue`(离线重放)、`batch-send`、`mcp-proxy-core`(stdio↔HTTP 代理)、`session-model`(会话 id 派生)以及 `credentials`。构建瘦 harness 时,只需实现一个适配层,把宿主生命周期事件映射到这些模块即可(例如 `agent-hook-runtime.mjs` 就是 cursor、trae、zcode 共用的现成一体化运行时,接新宿主时的主要工作只是解析其 stdin JSON 字段名)。- **Agent Plugins 1.0 便携包**(位于 `agent-plugins/`):采用 `plugin.json` + `skills/` + `mcp.json`(stdio→HTTP 代理)的规范化便携格式。该方案刻意不含 hooks(召回/沉淀靠 skill 教模型自调工具),非常适合符合 Agent Plugins 规范的客户端直接加载;此外,`plugin.test.mjs` 定义了规范一致性校验(schema URL、name 规则、静态 headers 不含机密、`mcp.json` 引用不逃逸插件根等),可作为自行打包的 lint 依据。-**接入时务必对齐的三个约定**(与现有 harness 保持一致的行为):① 召回调用点必须转发 `session_id`,这样才有服务端 expansion + 跨轮去重(详见 [§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径));② 适配器不要用自己的超时压过 helper 下发的 deadline;③ 关闭时要安排一条 commit 路径,否则未达阈值的尾部对话需等待后续触发才能归档(详见 [§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))——若宿主不提供关闭事件,可依赖服务端 idle 兜底(在服务端开 `memory.session_auto_commit.idle_enabled` 并下发 per-session policy)。这三条正是 `recall-session-wiring.test.mjs` 用跨插件正则钉死的。+**接入时务必对齐的三个约定**(与现有 harness 保持一致的行为):① 召回调用点必须转发 `session_id`,这样才有服务端 expansion + 跨轮去重(详见 [§3.2.1](#_3-2-1-机制底座-一条共享管线-两条服务端路径));② 适配器不要用自己的超时压过 helper 下发的 deadline;③ 关闭时要安排一条 commit 路径,否则未达阈值的尾部对话需等待后续触发才能归档(详见 [§3.3.3](#_3-3-3-关闭方式-×-harness-终局矩阵))——若宿主没有关闭事件,需开启 `memory.session_auto_commit.idle_enabled`,并提供 Session 级或部署级默认 policy。这三条正是 `recall-session-wiring.test.mjs` 用跨插件正则钉死的。---diff --git a/docs/zh/api/05-sessions.md b/docs/zh/api/05-sessions.mdindex 61c04e14f..527d046d4 100644--- a/docs/zh/api/05-sessions.md+++ b/docs/zh/api/05-sessions.md@@ -44,7 +44,7 @@ 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。包含 `experiences` 时会自动激活 `cases` 和 `trajectories`;不包含 `experiences` 时,显式传入的 `cases` 和 `trajectories` 会被忽略。所有 `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`。之后可通过 `update_session_config()` 部分更新或禁用该策略。 |+| auto_commit_policy | object | 否 | None | 可选的自动 commit 策略(见下表)。传入的字段会被校验并 clamp 到取值范围,然后合并到默认值之上;最终生效的策略会在响应的 `result.auto_commit_policy` 中返回,并持久化到 session meta。省略时,新 Session 先继承 `server.user_config_defaults.auto_commit_policy`,再沿用现有 `memory.session_auto_commit.default_enabled` 行为。之后可通过 `update_session_config()` 部分更新或禁用该策略。 |`auto_commit_policy` 字段(均为可选;存在 policy 时,未传字段回退到默认值):diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.mdindex 8feb3fb77..4157b6f1c 100644--- a/docs/zh/guides/01-configuration.md+++ b/docs/zh/guides/01-configuration.md@@ -1335,8 +1335,8 @@ RAGFS 默认使用 Rust binding 模式,通过 Rust 实现直接访问文件系- `memory.session_auto_commit` 是服务端全局配置,不是单个 session 的业务 policy。- session 级别的自动触发参数通过 session 级 `auto_commit_policy` 设置(见下表)。可以在创建 session 时通过 `POST /api/v1/sessions` 设置,也可以通过 `PATCH /api/v1/sessions/{session_id}/config` 部分更新。PATCH 时省略 `auto_commit_policy` 会保留现有策略,传 `null` 会禁用自动 commit;通过 `GET /api/v1/sessions/{session_id}` 查看生效策略。-- `default_enabled=false` 时,未传 `auto_commit_policy` 创建的 session 保持 auto commit 关闭,返回 `auto_commit_policy: null`。显式传 `{}` 或任意 policy 字段会为该 session 开启 auto commit,并用下方默认值补齐缺失字段。-- `default_enabled=true` 时,未传 `auto_commit_policy` 创建的 session 会带上下方默认 policy。+- `default_enabled=false` 时,既无显式 policy、也无 `server.user_config_defaults.auto_commit_policy` 的新 Session 保持 auto commit 关闭,并返回 `auto_commit_policy: null`。任一 policy 存在时都会启用自动 Commit,并用下方默认值补齐缺失字段。+- `default_enabled=true` 时,既无显式 policy、也无部署级默认 policy 的新 Session 会带上下方内置 policy。- `idle_enabled=false` 时:- 不会启动 `SessionAutoCommitScheduler`- `idle_enabled=true` 时:@@ -1702,6 +1702,7 @@ ov add-resource ./docs --exclude "*.tmp"| `user_config_defaults.add_targets.resource_uri` | str | `add_resource` 未传 `to` 和 `parent` 时使用的部署级默认资源添加目录。`viking://~/...` 会按请求用户解析。 | `null` || `user_config_defaults.add_targets.skill_uri` | str | `add_skill` 未传 `target_uri` 时使用的部署级默认技能添加根目录。仅允许 `viking://~/skills` 和 `viking://agent/skills`。 | `null` || `user_config_defaults.memory_policy` | object | Session 和 User 都未显式配置策略时使用的部署级默认记忆抽取策略。 | `null` |+| `user_config_defaults.auto_commit_policy` | object | 新建 Session 未显式指定策略时使用的部署级自动 Commit 默认策略。 | `null` || `agent_evolution.enabled` | bool | Agent 进化的集群启动默认值,运行时可由 Account 或 Cluster Admin settings 覆盖。开启时,session commit 可按 session `memory_policy` 生成或更新 cases、trajectories 和 experiences;关闭后已有记忆仍可读取和检索。 | `false` |省略 `auth_mode`(或设为 `null`)时,配置了非空 `root_api_key` 则选择 `api_key`,否则选择 `dev`。`dev` 仅允许监听 localhost,不进行身份认证。`root_api_key` 不能配置为空字符串。diff --git a/openviking/server/app.py b/openviking/server/app.pyindex e99cfd3e4..835adfdfd 100644--- a/openviking/server/app.py+++ b/openviking/server/app.py@@ -305,6 +305,10 @@ def create_app(if callable(user_memory_policy_setter):user_memory_policy_setter(config.user_config_defaults.memory_policy)+ auto_commit_setter = getattr(sessions, "set_default_user_auto_commit_policy", None)+ if callable(auto_commit_setter):+ auto_commit_setter(config.user_config_defaults.auto_commit_policy)+if service is not None:_configure_session_runtime(service)diff --git a/openviking/server/config.py b/openviking/server/config.pyindex 55495160f..99e2a7e2d 100644--- a/openviking/server/config.py+++ b/openviking/server/config.py@@ -151,6 +151,19 @@ class UserConfig(BaseModel):return MemoryPolicy.from_dict(value).to_dict()+class UserConfigDefaults(UserConfig):+ """Deployment defaults for users without persisted overrides."""++ auto_commit_policy: Optional[Dict[str, Any]] = None++ @field_validator("auto_commit_policy", mode="before")+ @classmethod+ def validate_auto_commit_policy(cls, value: Any) -> Optional[Dict[str, Any]]:+ from openviking.session.auto_commit_policy import AutoCommitPolicy++ return None if value is None else AutoCommitPolicy.from_dict(value).to_dict()++class MetricsAccountDimensionConfig(BaseModel):"""Account-dimension configuration for metrics label injection."""@@ -335,12 +348,17 @@ class ServerConfig(BaseModel):public_base_url: Optional[str] = Noneupload_signed_ttl_seconds: int = 600temp_upload: TempUploadConfig = Field(default_factory=TempUploadConfig)- user_config_defaults: UserConfig = Field(default_factory=UserConfig)+ user_config_defaults: UserConfigDefaults = Field(default_factory=UserConfigDefaults)agent_evolution: AgentEvolutionConfig = Field(default_factory=AgentEvolutionConfig)tool_output_externalization: ToolOutputExternalizationConfig = Field(default_factory=ToolOutputExternalizationConfig)+ @field_validator("user_config_defaults", mode="before")+ @classmethod+ def normalize_user_config_defaults(cls, value: Any) -> Any:+ return value.model_dump() if isinstance(value, UserConfig) else value+def get_effective_auth_mode(self) -> str:"""Get effective auth mode, auto-detecting if not explicitly set.diff --git a/openviking/service/session_service.py b/openviking/service/session_service.pyindex 0be910e29..161a40be9 100644--- a/openviking/service/session_service.py+++ b/openviking/service/session_service.py@@ -67,6 +67,7 @@ class SessionService:self._agent_evolution_default_enabled = AgentEvolutionConfig().enabledself._runtime_config_manager: Optional[Any] = Noneself._default_user_memory_policy: Optional[Dict[str, Any]] = None+ self._default_user_auto_commit_policy: Optional[Dict[str, Any]] = Noneself._usage_reporter: Optional["UsageReporter"] = None# Server-wide controls remain disabled until configured during app setup.self._session_auto_commit_config = SessionAutoCommitConfig()@@ -103,6 +104,11 @@ class SessionService:policy.validate_memory_types(set(get_default_registry().list_names(include_disabled=False)))self._default_user_memory_policy = policy.to_dict()+ def set_default_user_auto_commit_policy(self, policy: Optional[Dict[str, Any]]) -> None:+ self._default_user_auto_commit_policy = (+ None if policy is None else AutoCommitPolicy.from_dict(policy).to_dict()+ )+def set_agent_evolution_config(self, config: AgentEvolutionConfig) -> None:"""Set the default used when an account has no persisted override."""self._agent_evolution_default_enabled = config.enabled@@ -129,6 +135,13 @@ class SessionService:"""Set server-wide controls for automatic session commits."""self._session_auto_commit_config = config.model_copy(deep=True)+ def _new_session_auto_commit_policy(self) -> Optional[Dict[str, Any]]:+ if self._default_user_auto_commit_policy is not None:+ return dict(self._default_user_auto_commit_policy)+ if self._session_auto_commit_config.default_enabled:+ return AutoCommitPolicy.from_dict(None).to_dict()+ return None+def _ensure_initialized(self) -> None:"""Ensure all dependencies are initialized."""if not self._viking_fs:@@ -251,12 +264,12 @@ class SessionService:# the server default turns it on. Absent both, it stays disabled.if update_auto_commit_policy and auto_commit_policy is None:session.meta.auto_commit_policy = None- elif auto_commit_policy is not None or self._session_auto_commit_config.default_enabled:+ elif auto_commit_policy is not None:session.meta.auto_commit_policy = AutoCommitPolicy.from_dict(auto_commit_policy).to_dict()else:- session.meta.auto_commit_policy = None+ session.meta.auto_commit_policy = self._new_session_auto_commit_policy()if event_tags is not None:session.meta.event_search_tags = normalize_search_tags(event_tags,@@ -285,8 +298,7 @@ class SessionService:if not await session.exists():if not auto_create:raise NotFoundError(session_id, "session")- if self._session_auto_commit_config.default_enabled:- session.meta.auto_commit_policy = AutoCommitPolicy.from_dict(None).to_dict()+ session.meta.auto_commit_policy = self._new_session_auto_commit_policy()await session.ensure_exists()await session.load()self._record_lifecycle_metric("get", "ok")diff --git a/tests/server/test_agent_evolution_global_setting.py b/tests/server/test_agent_evolution_global_setting.pyindex 811622abc..e3b26d63b 100644--- a/tests/server/test_agent_evolution_global_setting.py+++ b/tests/server/test_agent_evolution_global_setting.py@@ -222,6 +222,34 @@ def test_server_default_memory_policy_is_configured_on_session_service(}+async def test_auto_commit_defaults_apply_to_new_sessions(fake_viking_fs, monkeypatch):+ sessions = SessionService(viking_fs=fake_viking_fs)+ config = ServerConfig(+ user_config_defaults={"auto_commit_policy": {"idle_timeout_seconds": 7200}}+ )+ create_app(+ config=config,+ service=SimpleNamespace(sessions=sessions),+ )+ expected = config.user_config_defaults.auto_commit_policy++ session = SimpleNamespace(+ meta=SimpleNamespace(auto_commit_policy=None),+ exists=AsyncMock(return_value=False),+ ensure_exists=AsyncMock(),+ load=AsyncMock(),+ )+ monkeypatch.setattr(sessions, "session", lambda *_args, **_kwargs: session)+ ctx = RequestContext(user=UserIdentifier.the_default_user(), role=Role.ROOT)++ await sessions.create(ctx, "created")+ assert session.meta.auto_commit_policy == expected++ session.meta.auto_commit_policy = None+ await sessions.get("auto-created", ctx, auto_create=True)+ assert session.meta.auto_commit_policy == expected++async def test_existing_session_observes_updated_account_value(fake_viking_fs):runtime_config = _FakeRuntimeConfig()service = SessionService(viking_fs=fake_viking_fs)