Skip to content

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

feat(memory): add account-scoped memory template configuration (#4770)

agentb7bd0b5d6422
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index d9666cc87..27cde2bdb 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -486,6 +486,10 @@ This catalog follows the routes actually mounted by the server. Each group headi
| PUT | `/api/v1/admin/agent-evolution` | Update the caller account's Agent Evolution status |
| GET | `/api/v1/admin/accounts/{account_id}/settings` | Get effective account settings |
| PATCH | `/api/v1/admin/accounts/{account_id}/settings` | Update allowlisted account settings |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates` | List editable memory templates, defaults and effective values |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Read one memory template |
+| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Complete and publish one memory template |
+| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Remove a memory template override and restore deployment defaults |
| POST | `/api/v1/admin/accounts` | Create an account and its first administrator |
| GET | `/api/v1/admin/accounts` | List accounts |
| POST | `/api/v1/admin/migrate` | Migrate legacy identity data |
diff --git a/docs/en/api/08-admin.md b/docs/en/api/08-admin.md
index 10f77bc4c..c6db772bb 100644
--- a/docs/en/api/08-admin.md
+++ b/docs/en/api/08-admin.md
@@ -157,6 +157,241 @@ ov --sudo admin set-account-settings acme --acl-enabled true
Before an existing setting is replaced, it is backed up to
`/local/{account_id}/_system/setting.backup.json`.
+### account_memory_templates
+
+ROOT can manage any Account; ADMIN can manage only its own Account. Ordinary
+Users cannot use these endpoints. Authorization is role-based, not based on
+whether the User is named `default`.
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates` | List the six editable templates, full defaults and effective values |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Read one template |
+| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Complete and publish one template |
+| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | Remove that override and restore deployment defaults |
+
+The kernel accepts the existing memory YAML structure as a JSON object and enforces
+the following editing allowlist at the API boundary. Only these six types are
+exposed. Experience, Cases, Trajectories and other types are not exposed for reading
+or editing. These APIs cannot create, delete or rename Memory Types; DELETE removes
+only the Account override.
+
+| Type | Editable configuration |
+|------|------------------------|
+| `profile` | `description`; `fields.content.description` |
+| `events` | `description`; `fields.event_name.description`, `fields.summary.description`; `content_template` |
+| `preferences` | `description`; `fields.topic.description`, `fields.content.description` |
+| `entities` | `description`; `fields.category.description`, `fields.name.description`, `fields.content.description` |
+| `soul` | `description`; `fields.core_truths.description`, `fields.boundaries.description`, `fields.vibe.description`, `fields.continuity.description`; `content_template` |
+| `identity` | `description`; `fields.creature.description`, `fields.name.description`, `fields.vibe.description`, `fields.avatar.description`, `fields.emoji.description`, `fields.introduction.description`; `content_template` |
+
+Here `fields.<name>.description` selects an existing entry in the `fields` array
+by `name`; it does not replace that field. JSON keys are case-sensitive: use
+`description`, not `Description`. Profile's `content` field permits only its
+description to change.
+
+All other configuration stays locked to deployment defaults: `memory_type`,
+`enabled`, `operation_mode`, `stage`, `peer_enabled`, `directory`,
+`filename_template`, field names/types/merge operations/initial values,
+`embedding_template`, `overview_template`, and unlisted field descriptions.
+Profile keeps `profile.md` and content's `merge_op=patch`; Events keeps
+`add_only` and the descriptions of `goal` and `ranges`; Identity keeps Name's
+immutable merge rule. Profile, Preferences and Entities cannot edit
+`content_template`. Changing topic/category/name/event_name instructions can
+still indirectly affect future paths/names, without changing their templates.
+
+Example: change only the type description:
+
+```bash
+curl -X PUT "$OV_ENDPOINT/api/v1/admin/accounts/acme/memory-templates/profile" \
+ -H "X-API-Key: $OV_ADMIN_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"description":"Remember business facts in concise English."}'
+```
+
+PUT completes omitted values from **deployment defaults**, not the previous
+Account override, and persists a **complete YAML template**. `fields` updates
+existing entries by name, replacing only permitted descriptions; all omitted
+fields and attributes retain default values. Fields cannot be added, removed or
+renamed, and an empty list does not remove any fields. Full GET `effective`
+objects can be submitted unchanged: locked values matching defaults are accepted.
+Changed locked values, unknown keys/fields and duplicate field names return
+`INVALID_ARGUMENT` without modifying the active file. To edit one description while
+preserving all other customizations, GET `effective`, modify that object, then
+PUT it. An empty object publishes a complete copy of the defaults as custom;
+DELETE removes the custom file. DELETE is idempotent.
+
+Results contain `memory_type`, `status` (`system_default` or `custom`),
+`updated_at` (UTC publication time or null), and full `defaults` / `effective`
+objects using YAML field names such as `fields[].type`. List returns
+`result.account_id` and `result.templates`; single-template operations return
+`result.account_id` plus the template result.
+
+Storage is per Account and per type:
+
+```text
+/local/{account_id}/_system/memory_templates/
+ profile.yaml
+ preferences.yaml
+ events.yaml
+ ...
+```
+
+Only published overrides create files. Each file contains the complete schema
+and an internal `_updated_at` timestamp; no `memory_templates.json` is used.
+The previous content is backed up to `{type}.yaml.backup`. Access goes through
+AGFS, preserving the deployment's encryption/storage configuration. Do not edit
+encrypted backing files directly. `setting.json` and User `user_config.json`
+are unchanged. Personal deployments use the default Account; enterprise
+deployments use the target Account, with no separate kernel storage layout.
+
+Template reads do not acquire locks. Publication writes a unique staging file in
+the same directory, then switches the active path through AGFS: LocalFS uses a
+file rename; S3 copies the complete object over the destination before deleting
+the staging object, without deleting the destination first. Readers may see the
+complete old or new version, or deployment defaults before the first publication
+and after DELETE. This is per-file publication, not a transaction across an
+entire template listing or registry snapshot.
+Writers/DELETE still use cross-process locks; publication locks cover both the
+active and staging paths. Contention uses zero-wait attempts with asynchronous
+backoff for up to 10 seconds, leaving executor threads available for I/O/release.
+A failed staging write leaves the active file unchanged. Post-publication cleanup
+errors only produce warnings, never an in-place rollback. If the move reports an
+error, the destination is checked: a verified publication is retained; an
+unverifiable outcome returns an error without blindly restoring the old version.
+Use GET to confirm its state. Cancellation stops lock retries, but already
+submitted native I/O is drained and locks released before cancellation propagates;
+cancelling an in-progress publication does not guarantee that it is undone.
+Process crashes or cleanup failures can leave `.tmp` files, which readers ignore.
+
+The ordinary Session memory extraction pipeline loads Account templates before
+schema filtering and initial-file generation. The resulting registry snapshot is
+used for extraction, patch merging, and memory-file updates. A later publication
+does not change an in-flight extraction's snapshot. Streaming updates compare the
+current memory type's schema values (including the rendering mode), not the whole
+registry: changes to unrelated types do not split a batch. Different schemas are
+merged/rendered separately. If those groups target the same file, before or after
+patch merging, the updater raises a conflict before applying any memory operations
+in that merge batch. Re-extract with current templates and file contents before
+retrying; replaying the old patches is not a fix. This is fail-fast conflict
+handling, not automatic rebasing or an atomic transaction across a whole Commit;
+other memory-type groups or append-only writes may already have completed.
+Work queued before publication
+uses the configuration at **extraction start**, not at HTTP Commit acceptance.
+All eligible Users/Peers in that Account share the templates; no shared deployment
+registry is mutated. Publishing/resetting does not proactively rewrite existing
+memories; subsequent commits can update them according to the effective rules.
+
+Editable descriptions and content templates must be nonempty strings;
+each serialized file is limited to 1 MiB. Descriptions (both type-level and
+`fields[].description`) share one restricted Jinja contract, whether they come
+from deployment defaults or an Account override. Editing a description does not
+disable rendering, and no description provenance flag is stored or checked.
+Only the existing `language` context variable is available; body fields,
+`extract_context`, and arbitrary objects are not exposed. The syntax subset is
+the same as the restricted bodies below: conditionals, local variables, bounded
+literal loops, safe string methods and tests, but no filters or arbitrary calls.
+For example, <code v-pre>Use {{ language.upper() }}.</code> renders as `Use EN.` when the existing
+schema-rendering context supplies `language=en`. No new language propagation is
+introduced; the Python protocol's existing static field-description path remains
+unchanged. Missing language retains the previous undefined/empty-output behavior;
+use `language or 'English'` for a fallback. Context values are not recursively
+evaluated as Jinja. Invalid custom expressions are rejected before publication,
+and persisted overrides are revalidated before extraction. Deployment descriptions
+also use the restricted renderer, so deployment-specific unsupported syntax must
+be migrated rather than receiving a trust exemption. Descriptions are limited to
+2048 AST nodes and 1 MiB rendered output. `content_template` keeps its separate
+variable/source-size contract and inherited-body compatibility below.
+Each editable `description`
+(type-level or `fields[].description`) is limited to 50,000 Unicode code points,
+including whitespace and template-like text. This is a per-field source-character limit,
+not a UTF-8 byte, rendered-output or combined-description limit. Oversized updates
+return 400 without modifying the active configuration. Publication does not invoke
+an LLM. Storage failures/corrupt files
+are reported, not silently treated as defaults. This change adds no public
+file-browser directory, SDK/CLI commands, drafts or version-history UI.
+
+#### Managed content-template contract
+
+The restricted contract below applies only when the Account body differs from the
+current deployment default. At publication and extraction load, the server compares
+the complete `content_template` string against its own deployment registry. An exact
+match uses the existing deployment renderer, including its filters and helpers;
+there is no client-supplied trust flag. This includes description-only PUT, empty
+PUT, and GET `effective` → PUT when the body is unchanged. The override can still
+have `status=custom` even though its body is inherited. The bundled Events YAML and
+its existing date expression are unchanged.
+
+Equality is exact, including whitespace. A modified body must pass the restricted
+contract even if it was based on a deployment template. If deployment defaults
+later change, the stored body is compared again on the next extraction load; a
+previous match does not grant permanent trust. A nonmatching body outside the
+allowlist must be replaced/reset before extraction can use it. Already-started
+extractions retain their resolved snapshot.
+
+`content_template` formats extracted/merged fields into Markdown. Administrators
+may change headings, order, fixed text and conditional visibility, including
+omitting fields or the Events ChatLog/resource-event branch. Omission does not
+disable extraction, remove stored field metadata or delete Session messages.
+Events' default embedding template consumes the body, so these edits can affect
+retrieval input. Paths, field definitions and merge rules remain locked.
+
+| Type | Content variables |
+| --- | --- |
+| events | event_name, goal, summary, ranges |
+| soul | core_truths, boundaries, vibe, continuity |
+| identity | name, creature, vibe, emoji, avatar, introduction |
+
+`language` is a description variable, not a content variable. Only Events
+may call these read-only `extract_context` helpers with positional arguments:
+`get_resource_event_content(ranges, summary)`,
+`get_first_message_time_from_ranges(ranges)`,
+`get_first_message_time_with_weekday_from_ranges(ranges)`,
+`get_event_content(ranges, summary[, ratio_threshold])`,
+`get_year(ranges)`, `get_month(ranges)`, `get_day(ranges)`.
+The first argument must be `ranges` directly; missing field values are supplied as
+empty strings, so no fallback filter is needed. An explicit ratio must be a numeric
+literal from 0 to 1 (omitted: 0.2; built-in: 0).
+
+Supported Jinja: `if/elif/else`, comparisons/boolean expressions, local `set`, and
+non-nested/non-recursive `for` over an explicit list/tuple of at most 32 items
+(including title/value pairs). `loop.index/index0/first/last/length` are available.
+String methods: `.upper()`, `.lower()`, `.strip()`, with no positional or keyword
+arguments. These use the same method-call syntax as deployment templates; Account
+templates allow only these methods on plain strings. The receiver type is checked
+before attribute lookup, so same-named methods/properties on other objects (including
+string subclasses) are not allowed. Methods can be chained or used on string fields,
+locals, literals, and string results of approved Events helpers. Method references
+cannot be stored or accessed without calling them.
+
+No filters are supported in custom Account bodies, including `| upper`,
+`| lower`, `| trim`, `| default(...)`, or `| length`; this unreleased interface does
+not retain a filter compatibility mode. Use `summary or 'pending'` or an explicit
+conditional for fallbacks, and `summary.strip().upper()` for string formatting.
+Tests: `defined`, `undefined`, `none`, `string` remain supported.
+Built-in field/context names cannot be overwritten. Imports,
+inheritance, macros, arbitrary calls/attributes, subscripts, arithmetic/string
+multiplication/concatenation and reserved `MEMORY_FIELDS` comments are not allowed.
+
+Limits: 64 KiB UTF-8 source, 2048 AST nodes, 1 MiB rendered body excluding system
+metadata. Nonmatching Account bodies are checked at publication and extraction load,
+then rendered with a restricted Jinja environment and only approved fields/helpers.
+Runtime failures on this restricted path stop that file write instead of falling
+back to an empty body. Exact inherited bodies keep the deployment renderer's
+existing behavior, including its error/fallback semantics; they are not subject to
+the restricted renderer's source/AST/output limits. The complete Account YAML file
+is still limited to 1 MiB.
+These guards do not replace Worker resource quotas, evaluate extraction quality or sanitize
+Markdown/HTML for UI display. Descriptions and restricted content templates share
+the syntax sandbox, but expose different variables and use different source limits.
+
+Publication validation failures return `INVALID_ARGUMENT` with `error.details`:
+`field=description`, `fields.<name>.description`, or `content_template`, a controlled
+`reason`, and `line` when available. The
+active configuration remains unchanged. Structurally valid older overrides using
+unsupported Jinja can still be read, replaced or reset, but extraction refuses to
+execute them unchecked. Corrupt YAML remains an explicit error.
+
### user_settings
ROOT can manage any User and ADMIN can manage Users in its own account. The
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index d4d8b0049..779c30f9b 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -481,6 +481,10 @@ JSON 输出 - 错误:
| PUT | `/api/v1/admin/agent-evolution` | 更新调用方 account 的 Agent 进化状态 |
| GET | `/api/v1/admin/accounts/{account_id}/settings` | 获取 account 生效配置 |
| PATCH | `/api/v1/admin/accounts/{account_id}/settings` | 更新白名单内的 account 配置 |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates` | 列出可编辑记忆模板、默认值及生效值 |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 查询单个记忆模板 |
+| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 补齐并发布单个记忆模板 |
+| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 删除记忆模板覆盖,恢复部署默认值 |
| POST | `/api/v1/admin/accounts` | 创建账号及首个管理员 |
| GET | `/api/v1/admin/accounts` | 列出账号 |
| POST | `/api/v1/admin/migrate` | 迁移旧版身份数据 |
diff --git a/docs/zh/api/08-admin.md b/docs/zh/api/08-admin.md
index 741337a3d..954bfe88e 100644
--- a/docs/zh/api/08-admin.md
+++ b/docs/zh/api/08-admin.md
@@ -154,6 +154,194 @@ ov --sudo admin set-account-settings acme --acl-enabled true
覆盖已有配置前,内核会先备份到
`/local/{account_id}/_system/setting.backup.json`。
+### account_memory_templates
+
+ROOT 可管理任意 Account;ADMIN 仅可管理自己 Account 的模板;普通 User 无权调用。
+权限按管理员角色判断,不按 User 是否叫 `default` 判断。
+
+| 方法 | 路径 | 用途 |
+|------|------|------|
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates` | 列出六类开放模板、完整默认值及生效值 |
+| GET | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 查询单个模板 |
+| PUT | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 补齐并发布单个模板 |
+| DELETE | `/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}` | 删除该模板覆盖,恢复部署默认值 |
+
+内核接收原有 Memory YAML 结构对应的 JSON 对象,并在接口层强制校验以下白名单。
+仅开放下列六类模板;Experience、Cases、Trajectories 等其他类型不开放查询或编辑,
+不支持通过接口新增、删除或重命名 Memory Type。DELETE 仅移除自定义覆盖,不删除模板类型。
+
+| 模板 | 可编辑项 | 用途 |
+|------|----------|------|
+| `profile` | `description`;`fields.content.description` | 稳定身份、背景和工作方式的抽取说明;正文内容、语言、Markdown 结构、长度和更新时间要求 |
+| `events` | `description`;`fields.event_name.description`、`fields.summary.description`;`content_template` | 事件范围、原子性与排除项;名称语言、粒度和格式;摘要事实、日期和语言;Summary、时间、ChatLog 的标题、顺序和展示方式 |
+| `preferences` | `description`;`fields.topic.description`、`fields.content.description` | 偏好、习惯、反感及与 Profile/Event 的边界;主题粒度、语言和命名;正文语义、条目和 Markdown 要求 |
+| `entities` | `description`;`fields.category.description`、`fields.name.description`、`fields.content.description` | 实体与关系范围;分类法、语言和粒度;实体命名;卡片事实、章节、语言和长度 |
+| `soul` | `description`;`fields.core_truths.description`、`fields.boundaries.description`、`fields.vibe.description`、`fields.continuity.description`;`content_template` | 核心原则、边界、气质和连续性的抽取表达;四个字段的标题、顺序和固定文案 |
+| `identity` | `description`;`fields.creature.description`、`fields.name.description`、`fields.vibe.description`、`fields.avatar.description`、`fields.emoji.description`、`fields.introduction.description`;`content_template` | 身份信息范围;身份、名称、气质、头像、Emoji、自我介绍的字段要求;正文标签、顺序和固定文案 |
+
+表中 `fields.<name>.description` 表示在 `fields` 数组中按 `name` 定位并修改
+`description`,不是替换整个字段。JSON 属性名统一小写(`description`,不是
+`Description`)。Profile 的 `fields.content` 仅开放其 description,不开放字段本身。
+
+除白名单说明文字和三个正文模板外,所有配置均锁定为部署默认值,包括:
+`memory_type`、`enabled`、`operation_mode`、`stage`、`peer_enabled`、
+`directory`、`filename_template`、所有字段的名称/类型/`merge_op`/`init_value`、
+`embedding_template` 和 `overview_template`,以及未开放的字段说明。
+例如 Profile 保留 `profile.md` 和 content 的 `merge_op=patch`;Events 保留
+`add_only` 以及 `goal/ranges` 的说明;Identity 的 Name immutable 规则不变。
+Profile、Preferences、Entities 不开放 `content_template`。
+改写 topic/category/name/event_name 的生成说明仍可能间接影响未来的目录或文件名,
+但不允许修改目录/文件名模板本身。
+
+例如,仅修改类型说明:
+
+```bash
+curl -X PUT "$OV_ENDPOINT/api/v1/admin/accounts/acme/memory-templates/profile" \
+ -H "X-API-Key: $OV_ADMIN_API_KEY" \
+ -H 'Content-Type: application/json' \
+ -d '{"description":"只记住业务相关事实,用简洁的中文描述。"}'
+```
+
+PUT 从**部署默认模板**补齐未传入的配置,不从上一次 Account 自定义值补齐,最终保存
+**完整 YAML 模板**。`fields` 按已有字段名合并,只覆盖白名单允许的说明文字,
+未传入的字段和属性全部保留默认值;不能新增、删除或重命名字段,提交空列表不会删除字段。
+完整 GET `effective` 对象可以回传:锁定字段值与默认值相同则接受,任何锁定值变更、
+未知配置项、未知字段或重复字段名均返回 `INVALID_ARGUMENT`,当前生效文件不变。
+若仅调整一个 description 且需保留其他自定义内容,应先 GET,修改 `effective` 对象后
+整体 PUT。空对象会发布一份完整默认配置,状态仍为自定义;恢复系统默认应调用 DELETE。
+DELETE 幂等。
+
+返回包含 `memory_type`、`status`(`system_default` / `custom`)、
+`updated_at`(UTC 发布时间,默认状态为 null),以及完整的 `defaults` / `effective`。
+对象使用 YAML 字段名,例如 `fields[].type`。列表接口返回 `result.account_id` 和
+`result.templates`;单模板操作返回 `result.account_id` 及上述模板结果。
+
+按 Account、按模板独立存储:
+
+```text
+/local/{account_id}/_system/memory_templates/
+ profile.yaml
+ preferences.yaml
+ events.yaml
+ ...
+```
+
+仅发布自定义时创建对应文件。文件包含完整 Schema 和内部 `_updated_at` 时间戳,
+不再使用集中式 `memory_templates.json`。更新前备份至 `{type}.yaml.backup`。
+读写经过 AGFS,沿用当前部署的加密和存储配置,不能直接编辑加密后的底层文件。
+不修改 Account 的 `setting.json` 或 User 的 `user_config.json`。
+个人版使用默认 Account;企业版使用指定 Account,内核不区分两套文件结构。
+
+模板读取不加锁。发布先在同目录写完唯一临时文件,再通过 AGFS 切换到正式路径:
+LocalFS 使用文件重命名,S3 使用完整对象复制替换目标后再删除临时对象,不先删除目标。
+读者允许看到完整旧版或新版;首次发布之前、恢复默认之后读取部署默认值,不读取临时文件。
+这是单文件发布语义,不保证一次列表/Registry 读取中的所有模板来自同一发布时刻。
+发布与 DELETE 仍使用跨进程写锁;发布锁同时覆盖正式路径和临时路径。锁冲突采用零等待尝试和
+协程退避,最多等待 10 秒,避免锁等待占满执行后续 I/O 的默认线程池。
+临时写入失败不修改当前文件;切换后清理失败只记警告,不覆盖回滚已发布版本。
+若切换返回错误,会核验目标内容:确认已发布则保留新版本;无法确认则返回错误且不盲目回滚,调用方可 GET 确认状态。
+取消等待锁的请求会停止重试;已下发的 native 操作不能强行中断,会完成收尾并释放锁后再传播取消。
+因此取消已开始发布的请求不保证撤销发布。进程异常退出或清理失败可能留下 `.tmp` 文件,但读取不会使用它们。
+
+普通 Session 记忆抽取在筛选 Schema 和初始化记忆文件之前读取 Account 模板。
+同一份 Registry 快照贯穿模型抽取、补丁合并和记忆文件更新;发布新模板不改变已开始
+抽取的快照。流式更新直接比较当前记忆类型的 Schema 值(含渲染模式),不比较整个
+Registry;无关类型变更不会触发拆批。不同 Schema 分开合并、渲染;若这些组在补丁
+合并前或合并后指向同一文件,会在应用该合并批次的任何记忆操作前抛出冲突。
+此时需按当前模板和文件内容重新抽取后再重试,不能直接重放旧 patch。
+这是冲突提前报错,不是自动 rebase,也不是整个 Commit 的原子事务;其他记忆类型
+或 append-only 路径可能已经完成写入。排队任务按**抽取开始时**取值,
+不是按 HTTP Commit 受理时间取值。同一 Account 下符合记忆策略的 User/Peer 共用模板,
+不同 Account 不串用,也不修改共享的部署 Registry。发布或恢复默认不会主动重写历史
+记忆,后续 Commit 可按生效规则更新已有记忆。
+
+白名单内提交的说明和正文模板必须是非空字符串;单文件序列化后不超过 1 MiB。
+`description`(类型说明及 `fields[].description`)统一支持受限 Jinja,不因来自部署默认值或账户覆盖而改变规则,不再记录或检查说明来源标志。
+仅开放已有上下文中的 `language`,不开放正文变量、`extract_context` 或任意对象。语法复用下节受限正文的条件、局部变量、有界字面量循环、安全字符串方法及测试;不支持过滤器或任意调用。
+例如已有 Schema 渲染上下文提供 `language=en` 时,<code v-pre>请使用 {{ language.upper() }}。</code> 会展开为 `请使用 EN。`,用户修改文字不会让变量停止展开。
+本次不新增语言传递链路,Python 协议原有的静态字段说明展示路径保持不变。缺失语言时保留原来的 undefined/空字符串行为,可用 `language or '中文'` 提供回退;上下文值中的 Jinja 不会被递归执行。
+越界的自定义表达式在保存前拒绝,已保存说明在抽取加载时重新校验;部署说明渲染也受同样限制,已有部署若使用白名单外语法,需要调整,不能凭来源绕过限制。
+每条说明最多 2048 个 AST 节点,渲染结果最多 1 MiB。正文 `content_template` 的变量、源码大小及默认正文兼容规则仍按下节处理。
+每个可编辑 `description` 最多 50,000 个 Unicode 码点,按提交的原文计数,包含空格、换行和模板样式的文字,不按 UTF-8 字节或渲染后的长度计数。各说明独立计数,不合并计算;整个配置仍受 1 MiB 上限约束。超过上限返回 400,不修改当前配置。
+发布不调用 LLM。存储错误或文件损坏明确报错,不伪装成系统默认。本次不增加公共文件浏览目录、SDK/CLI 命令、草稿或历史版本 UI。
+
+#### content_template 的编辑与执行边界
+
+以下受限规则仅用于与当前部署默认正文不同的账户自定义正文。发布和抽取加载时,
+服务器将完整 `content_template` 字符串与自己加载的部署默认值比较;完全相同时,
+沿用原部署渲染器及其过滤器、helper,不采信客户端或持久化文件中的“可信”标记。
+因此,仅改 description、空 PUT、正文未变的 GET `effective` → PUT 都不要求迁移默认正文。
+账户覆盖仍可显示 `status=custom`,但正文走继承路径。内置 Events YAML 及其原有日期表达式不变。
+
+比较是精确字符串比较,包含空白字符;修改过的正文即使以默认模板为基础,也必须通过受限校验。
+部署默认值后续变更时,下次抽取加载会重新比较,旧账户文件不会永久保留信任。
+不再匹配且超出白名单的正文需重新发布或恢复默认后才能参与提取;已开始的提取仍保留原快照。
+
+正文模板用于将已抽取/合并的字段组织为 Markdown,不是抽取 Prompt。
+允许修改标题、顺序、固定文案,按条件显示/隐藏字段。不要求保留默认标题或输出全部字段;
+但隐藏字段不等于停止抽取/删除该字段,也不会删除原始 Session 或系统保存的字段元数据。
+Events 的默认 embedding 模板引用正文,因此正文变化也可能影响后续检索输入。
+路径、文件名、字段定义、merge_op(包括 Identity name 的 immutable)仍锁定。
+
+| 类型 | 正文中可引用的字段 |
+| --- | --- |
+| events | event_name、goal、summary、ranges |
+| soul | core_truths、boundaries、vibe、continuity |
+| identity | name、creature、vibe、emoji、avatar、introduction |
+
+`language` 属于说明模板的变量,不属于上述正文变量。
+正文不要引用其他 Account/User、请求上下文或任意 Python 对象。
+仅 Events 可调用以下 `extract_context` 只读方法(位置参数):
+
+- `get_resource_event_content(ranges, summary)`:资源添加事件正文;非资源事件为空。
+- `get_first_message_time_from_ranges(ranges)`:第一条来源消息日期。
+- `get_first_message_time_with_weekday_from_ranges(ranges)`:日期及星期。
+- `get_event_content(ranges, summary[, ratio_threshold])`:按已有逻辑选择 ChatLog/摘要;省略阈值为 0.2,显式 0 表示存在原文时优先原文。
+- `get_year(ranges)`、`get_month(ranges)`、`get_day(ranges)`:来源日期分量。
+
+首个参数直接使用 `ranges`,不能自行构造消息范围;缺失字段会传入空字符串,无需过滤器兜底。
+阈值只能为 0~1 的数字字面量。
+允许去掉 ChatLog 或资源事件分支,但去掉后不再自动展示这些正文/资源链接;原始 Session 仍保留。
+
+支持的 Jinja 子集:
+
+- `if/elif/else`、比较/布尔条件、`set` 局部变量(不能覆盖内置字段、extract_context、loop)。
+- `for` 遍历模板中显式写出的列表/元组,最多 32 项;支持标题/字段二元组和 `loop.index/index0/first/last/length`。不支持嵌套/递归循环、range() 或遍历消息/长字符串。
+- 字符串方法:`.upper()`、`.lower()`、`.strip()`,均不接受位置参数或关键字参数。可用于字符串字段、局部变量、字面量、Events 白名单方法返回的字符串,并支持链式调用,例如 `summary.strip().upper()`。
+- 方法语法与部署模板一致,但账户正文只开放上述少数方法;读取属性前先检查接收者必须是普通字符串,其他对象(包括字符串子类)的同名方法/属性不能借此被调用。也不允许只取出方法引用、保存后再调用。
+- 自定义正文不支持任何过滤器,包括 `| upper`、`| lower`、`| trim`、`| default(...)`、`| length`;该接口尚未上线,不为自定义正文保留过滤器兼容模式。空值回退使用 `summary or '待补充'` 或条件表达式。
+- 测试:`defined`、`undefined`、`none`、`string`。
+- 不支持模板导入/继承、宏、任意函数/对象属性访问、下标访问、算术或字符串倍增/拼接。不能注入系统保留的 `<!-- MEMORY_FIELDS ... -->` 元数据。
+
+模板 UTF-8 大小 ≤ 64 KiB,AST 节点 ≤ 2048,渲染正文 ≤ 1 MiB(不含系统追加元数据)。
+与部署默认值不同的 Account 正文在发布时和抽取加载时验证,运行时使用受限 Jinja 环境,只提供白名单字段/方法。
+受限路径渲染失败会报告错误并停止该次文件写入,不走旧的空正文 fallback。
+原样继承的正文继续使用部署渲染器,包括原有错误/fallback 语义,不受上述受限渲染器的源码、AST、正文输出上限约束;
+完整账户 YAML 仍受 1 MiB 上限约束。
+这些保护不代替 Worker 的 CPU/内存配额,也不评估记忆效果或做前端 Markdown/HTML 安全过滤。
+说明与受限正文复用语法沙箱,但可用变量及源码大小限制不同。
+
+校验失败返回 `INVALID_ARGUMENT`,`error.details` 含 `field=description`、`fields.<name>.description` 或 `content_template`、受控 `reason` 和可用时的 `line`。
+失败不修改当前发布配置。此前保存的、结构有效但使用不支持 Jinja 的模板仍可读取、重新发布或恢复默认;
+不会绕过新规则继续执行,抽取加载时提示修复。损坏 YAML 仍明确报错。
+
+示例:只展示事件名称和摘要,不输出 ChatLog:
+
+```json
+{"content_template": "# {{ event_name.strip() }}\n\n## 事件摘要\n{{ summary.strip() or '待补充' }}"}
+```
+
+示例:Soul 的分节展示:
+
+```jinja
+{% for title, text in [('核心价值', core_truths), ('边界', boundaries), ('气质', vibe), ('连续性', continuity)] %}
+{% if text.strip() %}
+## {{ title }}
+{{ text.strip() }}
+{% endif %}
+{% endfor %}
+```
+
### user_settings
ROOT 可管理任意 User,ADMIN 仅可管理所属 account 内的 User。User 配置接口当前
diff --git a/openviking/server/routers/admin.py b/openviking/server/routers/admin.py
index 8a9135d4e..7bd419718 100644
--- a/openviking/server/routers/admin.py
+++ b/openviking/server/routers/admin.py
@@ -42,6 +42,13 @@ from openviking.service.task_store import (
from openviking.service.task_tracker import (
get_task_tracker,
)
+from openviking.session.memory.account_templates import (
+ EDITABLE_MEMORY_TEMPLATE_FIELDS,
+ default_memory_template,
+ memory_template_result,
+ read_account_memory_template,
+ update_account_memory_template,
+)
from openviking.session.memory.memory_type_registry import get_default_registry
from openviking.session.memory_policy import MemoryPolicy
from openviking.storage.viking_fs import get_viking_fs
@@ -477,6 +484,113 @@ async def patch_account_settings(
)
+# ---- Account memory templates ----
+
+
+async def _memory_template_service(request: Request, ctx: RequestContext, account_id: str):
+ _check_account_access(ctx, account_id)
+ await _check_account_exists(request, account_id)
+ service = get_service()
+ if service.viking_fs is None:
+ raise FailedPreconditionError("OpenViking service is not initialized.")
+ return service
+
+
[email protected]("/accounts/{account_id}/memory-templates")
+@require_auth_root_or_admin
+async def list_memory_templates(
+ request: Request,
+ account_id: str,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """List full defaults and account overrides for the six editable memory templates."""
+ service = await _memory_template_service(request, ctx, account_id)
+ registry = get_default_registry()
+ names = list(EDITABLE_MEMORY_TEMPLATE_FIELDS)
+ templates = await asyncio.gather(
+ *(read_account_memory_template(service.viking_fs, account_id, name) for name in names)
+ )
+ return Response(
+ status="ok",
+ result={
+ "account_id": account_id,
+ "templates": [
+ memory_template_result(registry, template, name)
+ for name, template in zip(names, templates, strict=True)
+ ],
+ },
+ )
+
+
[email protected]("/accounts/{account_id}/memory-templates/{memory_type}")
+@require_auth_root_or_admin
+async def get_memory_template(
+ request: Request,
+ account_id: str,
+ memory_type: str,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Read one template's full defaults and effective account configuration."""
+ service = await _memory_template_service(request, ctx, account_id)
+ registry = get_default_registry()
+ default_memory_template(registry, memory_type)
+ config = await read_account_memory_template(service.viking_fs, account_id, memory_type)
+ return Response(
+ status="ok",
+ result={
+ "account_id": account_id,
+ **memory_template_result(registry, config, memory_type),
+ },
+ )
+
+
[email protected]("/accounts/{account_id}/memory-templates/{memory_type}")
+@require_auth_root_or_admin
+async def put_memory_template(
+ request: Request,
+ account_id: str,
+ memory_type: str,
+ body: dict = Body(...),
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Fill omitted values from deployment defaults and publish a complete YAML template."""
+ service = await _memory_template_service(request, ctx, account_id)
+ registry = get_default_registry()
+ config = await update_account_memory_template(
+ service.viking_fs, account_id, memory_type, body, registry
+ )
+ return Response(
+ status="ok",
+ result={
+ "account_id": account_id,
+ **memory_template_result(registry, config, memory_type),
+ },
+ )
+
+
[email protected]("/accounts/{account_id}/memory-templates/{memory_type}")
+@require_auth_root_or_admin
+async def reset_memory_template(
+ request: Request,
+ account_id: str,
+ memory_type: str,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ """Remove one template override without rewriting existing memories."""
+ service = await _memory_template_service(request, ctx, account_id)
+ registry = get_default_registry()
+ config = await update_account_memory_template(
+ service.viking_fs, account_id, memory_type, None, registry
+ )
+ return Response(
+ status="ok",
+ result={
+ "account_id": account_id,
+ **memory_template_result(registry, config, memory_type),
+ },
+ )
+
+
# ---- User endpoints ----
diff --git a/openviking/session/compressor_v3.py b/openviking/session/compressor_v3.py
index ae76934c4..b28113b4e 100644
--- a/openviking/session/compressor_v3.py
+++ b/openviking/session/compressor_v3.py
@@ -678,7 +678,11 @@ class SessionCompressorV3:
logger.warning("VikingFS unavailable, skipping v3 memory extraction", exc_info=True)
return _V3ExtractionResult()
- registry = get_default_registry()
+ from openviking.session.memory.account_templates import resolve_account_memory_registry
+
+ registry = await resolve_account_memory_registry(
+ viking_fs, ctx.account_id, get_default_registry()
+ )
if allow_self_memory:
await registry.initialize_memory_files(
ctx,
@@ -692,6 +696,7 @@ class SessionCompressorV3:
ctx=ctx,
viking_fs=viking_fs,
transaction_handle=None,
+ memory_registry=registry,
)
await context_provider.prepare_extraction_messages()
extract_context = context_provider.get_extract_context()
@@ -738,6 +743,7 @@ class SessionCompressorV3:
messages=list(messages),
ctx=ctx,
strict_extract_errors=strict_extract_errors,
+ memory_registry=registry,
isolation_options={
"allowed_memory_types": allowed_memory_types,
"allow_self": allow_self_memory,
diff --git a/openviking/session/memory/account_templates.py b/openviking/session/memory/account_templates.py
new file mode 100644
index 000000000..4816c9cb5
--- /dev/null
+++ b/openviking/session/memory/account_templates.py
@@ -0,0 +1,442 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Account-scoped template files with a restricted public editing contract."""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from collections.abc import Awaitable, Callable, Coroutine
+from copy import deepcopy
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+import yaml
+from jinja2 import Environment, TemplateSyntaxError
+
+from openviking.pyagfs import AGFSAlreadyExistsError, AGFSNotFoundError, AsyncAGFSClient
+from openviking.pyagfs.async_client import fs_ctx_from_agfs_path
+from openviking.session.memory.dataclass import MemoryTypeSchema
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.utils.content_template import (
+ CONTENT_TEMPLATE_FIELDS,
+ ContentTemplateError,
+ validate_content_template,
+)
+from openviking.session.memory.utils.description_template import (
+ MAX_DESCRIPTION_CHARS,
+ DescriptionTemplateError,
+ validate_description_template,
+)
+from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
+from openviking_cli.exceptions import FailedPreconditionError, InvalidArgumentError, NotFoundError
+from openviking_cli.session.user_id import validate_account_id
+from openviking_cli.utils.logger import get_logger
+
+if TYPE_CHECKING:
+ from openviking.storage.viking_fs import VikingFS
+
+logger = get_logger(__name__)
+_MAX_CONFIG_BYTES = 1024 * 1024
+_TEMPLATE_LOCK_TIMEOUT_SECONDS = 10.0
+_TEMPLATE_LOCK_RETRY_SECONDS = 0.05
+
+# Field names select existing fields; only their descriptions are editable.
+EDITABLE_MEMORY_TEMPLATE_FIELDS = {
+ "profile": ("content",),
+ "events": ("event_name", "summary"),
+ "preferences": ("topic", "content"),
+ "entities": ("category", "name", "content"),
+ "soul": ("core_truths", "boundaries", "vibe", "continuity"),
+ "identity": ("creature", "name", "vibe", "avatar", "emoji", "introduction"),
+}
+_EDITABLE_CONTENT_TEMPLATES = set(CONTENT_TEMPLATE_FIELDS)
+
+
+def account_memory_template_path(account_id: str, memory_type: str) -> str:
+ error = validate_account_id(account_id)
+ if error:
+ raise InvalidArgumentError(error)
+ if (
+ not memory_type
+ or any(c in memory_type for c in ("/", "\\", "\0"))
+ or memory_type in {".", ".."}
+ ):
+ raise InvalidArgumentError("memory_type must be a single file name")
+ return f"/local/{account_id}/_system/memory_templates/{memory_type}.yaml"
+
+
+def memory_template_data(schema: MemoryTypeSchema) -> dict[str, Any]:
+ """Serialize using the existing YAML vocabulary, including field 'type'."""
+ data = schema.model_dump(mode="json")
+ for field in data["fields"]:
+ field["type"] = field.pop("field_type")
+ return data
+
+
+def default_memory_template(registry: MemoryTypeRegistry, memory_type: str) -> dict[str, Any]:
+ """Return deployment defaults for a type exposed by the management API."""
+ schema = registry.get(memory_type)
+ if schema is None:
+ raise NotFoundError(f"Memory template not found: {memory_type}")
+ if memory_type not in EDITABLE_MEMORY_TEMPLATE_FIELDS:
+ raise InvalidArgumentError(f"Memory template is not editable: {memory_type}")
+ return memory_template_data(schema)
+
+
+def _validate_template(
+ data: dict,
+ memory_type: str,
+ *,
+ validate_content: bool = True,
+ validate_descriptions: bool = True,
+ deployment_defaults: dict | None = None,
+) -> MemoryTypeSchema:
+ if data.get("memory_type") != memory_type:
+ raise ValueError("memory_type must match the template in the request path")
+ schema = MemoryTypeRegistry(load_schemas=False)._parse_memory_type(data)
+ names = [field.name for field in schema.fields]
+ if any(not name for name in names) or len(names) != len(set(names)):
+ raise ValueError("Template field names must be nonempty and unique")
+ defaults = deployment_defaults or {}
+ if validate_descriptions:
+ validate_description_template(schema.description)
+ for field in schema.fields:
+ validate_description_template(
+ field.description, field=f"fields.{field.name}.description"
+ )
+ if memory_type in _EDITABLE_CONTENT_TEMPLATES and schema.content_template is not None:
+ # Only an exact match to server-owned deployment defaults inherits the
+ # legacy renderer. Never infer trust from persisted/client-supplied flags.
+ schema._account_content_template = schema.content_template != defaults.get(
+ "content_template"
+ )
+ if validate_content and schema._account_content_template:
+ validate_content_template(schema.content_template, memory_type)
+ # Other deployment-owned template fields retain their existing syntax check.
+ env = Environment()
+ for template in (
+ schema.directory,
+ schema.filename_template,
+ schema.content_template,
+ schema.embedding_template,
+ schema.overview_template,
+ ):
+ if template is not None:
+ env.parse(template)
+ return schema
+
+
+def _apply_editable_values(target: dict, supplied: dict, editable: set[str], path: str) -> None:
+ for key, value in supplied.items():
+ location = f"{path}.{key}" if path else key
+ if key not in target:
+ raise ValueError(f"Unknown configuration field: {location}")
+ if key in editable:
+ if not isinstance(value, str) or not value.strip():
+ raise ValueError(f"{location} must be a nonempty string")
+ # Python len(str) counts Unicode code points, not UTF-8 bytes.
+ if key == "description" and len(value) > MAX_DESCRIPTION_CHARS:
+ raise ValueError(f"{location} must not exceed 50000 Unicode characters")
+ target[key] = value
+ elif type(value) is not type(target[key]) or value != target[key]:
+ # Unchanged locked values are accepted so GET effective -> PUT works.
+ raise ValueError(f"{location} is locked and must match the default template")
+
+
+def _complete_template(defaults: dict, supplied: dict, memory_type: str) -> dict:
+ data = deepcopy(defaults)
+ editable = {"description"}
+ if memory_type in _EDITABLE_CONTENT_TEMPLATES:
+ editable.add("content_template")
+ _apply_editable_values(
+ data, {key: value for key, value in supplied.items() if key != "fields"}, editable, ""
+ )
+ if "fields" in supplied:
+ if not isinstance(supplied["fields"], list):
+ raise ValueError("fields must be a list")
+ fields = {field["name"]: field for field in data["fields"]}
+ seen = set()
+ for field in supplied["fields"]:
+ if not isinstance(field, dict) or not isinstance(field.get("name"), str):
+ raise ValueError("Each fields entry must identify an existing field by name")
+ name = field["name"]
+ if name not in fields:
+ raise ValueError(f"Unknown template field: fields.{name}")
+ if name in seen:
+ raise ValueError(f"Duplicate template field: fields.{name}")
+ seen.add(name)
+ editable = (
+ {"description"} if name in EDITABLE_MEMORY_TEMPLATE_FIELDS[memory_type] else set()
+ )
+ _apply_editable_values(fields[name], field, editable, f"fields.{name}")
+ # Never remove, reorder, or replace fields omitted from a partial request.
+ _validate_template(data, memory_type, deployment_defaults=defaults)
+ return data
+
+
+async def _read_raw(client: AsyncAGFSClient, path: str) -> bytes | None:
+ try:
+ result = await client.read(path)
+ except AGFSNotFoundError:
+ return None
+ raw = getattr(result, "content", result)
+ if isinstance(raw, str):
+ raw = raw.encode("utf-8")
+ if not isinstance(raw, bytes) or len(raw) > _MAX_CONFIG_BYTES:
+ raise FailedPreconditionError("Invalid persisted account memory template")
+ return raw
+
+
+def _parse_template(raw: bytes | None, memory_type: str) -> dict | None:
+ if raw is None:
+ return None
+ try:
+ data = yaml.safe_load(raw)
+ if not isinstance(data, dict):
+ raise ValueError("Expected a YAML mapping")
+ # Keep well-formed older configurations readable/resettable even if their
+ # Jinja is outside the new contract. Never execute them unchecked.
+ _validate_template(data, memory_type, validate_content=False, validate_descriptions=False)
+ return data
+ except (ValueError, TypeError, AttributeError, yaml.YAMLError, TemplateSyntaxError) as exc:
+ raise FailedPreconditionError(f"Invalid persisted memory template: {memory_type}") from exc
+
+
+async def _finish_storage_call(
+ operation: Coroutine[Any, Any, Any],
+ *,
+ on_cancel: Callable[[Any], Awaitable[None]] | None = None,
+):
+ """Drain submitted native I/O before propagating cancellation.
+
+ Cancelling an asyncio waiter cannot stop its worker thread. Keep the worker's
+ result reachable, and (for acquisition) release a lease won during cancellation.
+ Locked writes include their own release in a finally block.
+ """
+ task = asyncio.create_task(operation)
+ try:
+ return await asyncio.shield(task)
+ except asyncio.CancelledError:
+
+ async def finish():
+ try:
+ result = await task
+ except Exception:
+ logger.debug("Template storage call failed while cancelling", exc_info=True)
+ else:
+ if on_cancel is not None:
+ await on_cancel(result)
+
+ cleanup = asyncio.create_task(finish())
+ while not cleanup.done():
+ try:
+ await asyncio.shield(cleanup)
+ except asyncio.CancelledError:
+ # Repeated cancellation must not interrupt lease cleanup either.
+ continue
+ cleanup.result()
+ raise
+
+
+async def _acquire_template_lock(
+ client: AsyncAGFSClient, path: str, staging_path: str | None = None
+):
+ # Keep the cross-process lock, but never wait for contention in a worker:
+ # the holder needs that same executor to finish its I/O and release the lease.
+ loop = asyncio.get_running_loop()
+ deadline = loop.time() + _TEMPLATE_LOCK_TIMEOUT_SECONDS
+
+ async def release_cancelled_acquire(lease):
+ await client.pathlock_release(lease, fs_ctx=fs_ctx_from_agfs_path(path))
+
+ while True:
+ try:
+ return await _finish_storage_call(
+ client.pathlock_acquire_exact_batch([path, staging_path], timeout_secs=0.0)
+ if staging_path is not None
+ else client.pathlock_acquire_exact(path, timeout_secs=0.0),
+ on_cancel=release_cancelled_acquire,
+ )
+ except LockAcquisitionError as exc:
+ remaining = deadline - loop.time()
+ if remaining > 0:
+ await asyncio.sleep(min(_TEMPLATE_LOCK_RETRY_SECONDS, remaining))
+ if loop.time() < deadline:
+ continue
+ raise ResourceBusyError(
+ "Another memory template operation is in progress. Please retry.",
+ uri=path,
+ conflict_type="memory_templates_busy",
+ ) from exc
+
+
+async def read_account_memory_template(
+ viking_fs: VikingFS, account_id: str, memory_type: str
+) -> dict | None:
+ path = account_memory_template_path(account_id, memory_type)
+ client = AsyncAGFSClient(viking_fs.agfs)
+ # Publication switches a fully-written staging file into place. Readers may
+ # see either complete version (or no override after DELETE), without a lock.
+ return _parse_template(await _read_raw(client, path), memory_type)
+
+
+def memory_template_result(
+ registry: MemoryTypeRegistry, custom: dict | None, memory_type: str
+) -> dict:
+ defaults = default_memory_template(registry, memory_type)
+ effective = dict(custom) if custom is not None else deepcopy(defaults)
+ updated_at = effective.pop("_updated_at", None)
+ return {
+ "memory_type": memory_type,
+ "status": "custom" if custom is not None else "system_default",
+ "updated_at": updated_at,
+ "defaults": defaults,
+ "effective": effective,
+ }
+
+
+async def update_account_memory_template(
+ viking_fs: VikingFS,
+ account_id: str,
+ memory_type: str,
+ template: dict | None,
+ registry: MemoryTypeRegistry,
+) -> dict | None:
+ """Publish a full template, or delete its override to restore deployment defaults."""
+ defaults = default_memory_template(registry, memory_type)
+ complete = None
+ encoded = None
+ if template is not None:
+ try:
+ complete = _complete_template(defaults, template, memory_type)
+ except DescriptionTemplateError as exc:
+ raise InvalidArgumentError(
+ str(exc),
+ details={"field": exc.field, "reason": exc.reason, "line": exc.line},
+ ) from exc
+ except ContentTemplateError as exc:
+ raise InvalidArgumentError(
+ str(exc),
+ details={"field": "content_template", "reason": exc.reason, "line": exc.line},
+ ) from exc
+ except (ValueError, TypeError, KeyError, AttributeError, TemplateSyntaxError) as exc:
+ raise InvalidArgumentError(f"Invalid memory template: {exc}") from exc
+ complete["_updated_at"] = datetime.now(timezone.utc).isoformat()
+ encoded = yaml.safe_dump(complete, allow_unicode=True, sort_keys=False).encode("utf-8")
+ if len(encoded) > _MAX_CONFIG_BYTES:
+ raise InvalidArgumentError("A memory template must not exceed 1 MiB")
+
+ path = account_memory_template_path(account_id, memory_type)
+ staging_path = f"{path}.{uuid.uuid4().hex}.tmp" if complete is not None else None
+ client = AsyncAGFSClient(viking_fs.agfs)
+ lease = await _acquire_template_lock(client, path, staging_path)
+ return await _finish_storage_call(
+ _update_locked_template(client, path, staging_path, memory_type, complete, encoded, lease)
+ )
+
+
+async def _publish_template(
+ client: AsyncAGFSClient, path: str, staging_path: str, encoded: bytes, fs_ctx: dict
+) -> None:
+ """Publish a complete file through same-mount AGFS rename/object replacement.
+
+ The caller's lease covers BOTH paths. LocalFS renames the staged file; S3
+ copies the whole staged object to the destination before deleting the source.
+ Never overwrite/restore the active file in place, including on failure.
+ """
+ try:
+ await client.write(staging_path, encoded, fs_ctx=fs_ctx)
+ try:
+ await client.mv(staging_path, path, fs_ctx=fs_ctx)
+ except Exception:
+ # An S3 move can publish successfully and then fail deleting its
+ # source. Acknowledge only a verified published version; if state
+ # cannot be verified, propagate the error without a destructive rollback.
+ try:
+ published = await _read_raw(client, path) == encoded
+ except Exception:
+ published = False
+ if not published:
+ raise
+ logger.warning("Template move reported an error after publication: %s", path)
+ finally:
+ try:
+ await client.rm(staging_path, fs_ctx=fs_ctx)
+ except AGFSNotFoundError:
+ pass
+ except Exception:
+ # Cleanup cannot undo a published version or mask the original error.
+ logger.warning(
+ "Failed to clean up staged memory template: %s", staging_path, exc_info=True
+ )
+
+
+async def _update_locked_template(
+ client: AsyncAGFSClient,
+ path: str,
+ staging_path: str | None,
+ memory_type: str,
+ complete: dict | None,
+ encoded: bytes | None,
+ lease,
+):
+ fs_ctx = fs_ctx_from_agfs_path(path)
+ lease_ref = getattr(lease, "lease_ref", None) or getattr(lease, "id", None)
+ if isinstance(lease, dict):
+ lease_ref = lease.get("lease_ref", lease_ref)
+ if lease_ref:
+ fs_ctx["lease_ref"] = lease_ref
+ try:
+ raw = await _read_raw(client, path)
+ current = _parse_template(raw, memory_type)
+ if complete is None and current is None:
+ return None
+ if complete is not None and current is not None:
+ if {k: v for k, v in current.items() if k != "_updated_at"} == {
+ k: v for k, v in complete.items() if k != "_updated_at"
+ }:
+ return current
+ try:
+ await client.ensure_parent_dirs(path)
+ except AGFSAlreadyExistsError:
+ pass
+ if raw is not None:
+ await client.write(path + ".backup", raw)
+ if complete is None:
+ await client.rm(path, fs_ctx=fs_ctx)
+ else:
+ assert staging_path is not None and encoded is not None
+ await _publish_template(client, path, staging_path, encoded, fs_ctx)
+ logger.info("Updated account memory template: %s reset=%s", path, complete is None)
+ return complete
+ finally:
+ await client.pathlock_release(lease, fs_ctx=fs_ctx_from_agfs_path(path))
+
+
+async def resolve_account_memory_registry(
+ viking_fs: VikingFS, account_id: str, registry: MemoryTypeRegistry
+) -> MemoryTypeRegistry:
+ """Snapshot account types over server-owned deployment defaults, without mutating them."""
+ schemas = registry.list_all(include_disabled=True)
+ templates = await asyncio.gather(
+ *(read_account_memory_template(viking_fs, account_id, s.memory_type) for s in schemas)
+ )
+ resolved = MemoryTypeRegistry(load_schemas=False)
+ for schema, template in zip(schemas, templates, strict=True):
+ try:
+ resolved.register(
+ _validate_template(
+ template,
+ schema.memory_type,
+ deployment_defaults=memory_template_data(schema),
+ )
+ if template is not None
+ else schema.model_copy(deep=True)
+ )
+ except (ContentTemplateError, DescriptionTemplateError) as exc:
+ raise FailedPreconditionError(
+ f"Invalid account {getattr(exc, 'field', 'content_template')} "
+ f"for {schema.memory_type}; republish or reset it"
+ ) from exc
+ return resolved
diff --git a/openviking/session/memory/dataclass.py b/openviking/session/memory/dataclass.py
index 08a69cbd2..4a41dd76f 100644
--- a/openviking/session/memory/dataclass.py
+++ b/openviking/session/memory/dataclass.py
@@ -22,7 +22,7 @@ from typing import (
get_type_hints,
)
-from pydantic import BaseModel, Field, WithJsonSchema, model_validator
+from pydantic import BaseModel, Field, PrivateAttr, WithJsonSchema, model_validator
from openviking.session.memory.merge_op.base import (
FieldType,
@@ -222,6 +222,10 @@ class MemoryField(BaseModel):
class MemoryTypeSchema(BaseModel):
"""Memory type schema definition."""
+ # True only for account bodies differing from server-owned deployment defaults.
+ # Recomputed by the loader, never serialized or accepted as a client trust flag.
+ _account_content_template: bool = PrivateAttr(default=False)
+
memory_type: str = Field(..., description="Memory type name")
description: str = Field("", description="Type description")
fields: List[MemoryField] = Field(default_factory=list, description="Field definitions")
diff --git a/openviking/session/memory/memory_type_registry.py b/openviking/session/memory/memory_type_registry.py
index 73d4fe1ef..f471dbc54 100644
--- a/openviking/session/memory/memory_type_registry.py
+++ b/openviking/session/memory/memory_type_registry.py
@@ -302,6 +302,9 @@ class MemoryTypeRegistry:
full_content = MemoryFileUtils.write(
mf,
content_template=schema.content_template,
+ account_content_template_type=(
+ schema.memory_type if schema._account_content_template else None
+ ),
)
# Write the file
diff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.py
index 008ca5561..1910129c0 100644
--- a/openviking/session/memory/memory_updater.py
+++ b/openviking/session/memory/memory_updater.py
@@ -1196,6 +1196,9 @@ class MemoryUpdater:
new_full_content = MemoryFileUtils.write(
mf,
content_template=schema.content_template,
+ account_content_template_type=(
+ schema.memory_type if schema._account_content_template else None
+ ),
extract_context=extract_context,
)
await viking_fs.write_file(
diff --git a/openviking/session/memory/schema_model_generator.py b/openviking/session/memory/schema_model_generator.py
index b36d0d84f..e2f16966e 100644
--- a/openviking/session/memory/schema_model_generator.py
+++ b/openviking/session/memory/schema_model_generator.py
@@ -10,7 +10,7 @@ definitions, with discriminator support for polymorphic fields.
import re
from typing import Annotated, Any, Dict, List, Optional, Tuple, Type, Union
-from pydantic import BaseModel, Field, WithJsonSchema, create_model, model_validator
+from pydantic import BaseModel, Field, WithJsonSchema, create_model
from pydantic.config import ConfigDict
from openviking.session.memory.dataclass import (
@@ -22,7 +22,7 @@ from openviking.session.memory.dataclass import (
from openviking.session.memory.memory_isolation_handler import RoleScope
from openviking.session.memory.merge_op import MergeOp, MergeOpFactory
from openviking.session.memory.merge_op.base import FieldType, get_python_type_for_field
-from openviking.session.memory.utils.template_utils import TemplateUtils
+from openviking.session.memory.utils.description_template import render_description_template
from openviking_cli.utils import get_logger
logger = get_logger(__name__)
@@ -91,15 +91,7 @@ class SchemaModelGenerator:
self._operations_model: Optional[Type[BaseModel]] = None
def _render_description(self, description: str) -> str:
- if not description:
- return description
- if "{{" not in description and "{%" not in description and "{#" not in description:
- return description
- return TemplateUtils.render(
- description,
- self._template_context,
- strip=False,
- )
+ return render_description_template(description, self._template_context, strip=False)
def _map_field_type(self, field_type: FieldType) -> Type[Any]:
"""Map YAML field type to Python type."""
@@ -380,9 +372,7 @@ class SchemaPromptGenerator:
self._template_context = dict(template_context or {})
def _render_description(self, description: str) -> str:
- if not description:
- return description
- return TemplateUtils.render(description, self._template_context)
+ return render_description_template(description, self._template_context)
def generate_type_descriptions(self) -> str:
"""
@@ -395,7 +385,7 @@ class SchemaPromptGenerator:
for mt in self.schemas:
lines.append(f"\n### {mt.memory_type}")
- lines.append(f"{self._render_description(mt.description)}")
+ lines.append(self._render_description(mt.description))
# Add URI format information
if mt.directory or mt.filename_template:
@@ -418,7 +408,8 @@ class SchemaPromptGenerator:
lines.append("\n**Fields:**")
for field in mt.fields:
lines.append(
- f"- `{field.name}` ({field.field_type.value}): {self._render_description(field.description)}"
+ f"- `{field.name}` ({field.field_type.value}): "
+ f"{self._render_description(field.description)}"
)
return "\n".join(lines)
diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.py
index f15dbb650..d9073007a 100644
--- a/openviking/session/memory/session_extract_context_provider.py
+++ b/openviking/session/memory/session_extract_context_provider.py
@@ -66,11 +66,12 @@ class SessionExtractContextProvider(ExtractContextProvider):
ctx: RequestContext = None,
viking_fs: VikingFS = None,
transaction_handle=None,
+ memory_registry: MemoryTypeRegistry | None = None,
):
self.messages = list(messages) if isinstance(messages, list) else messages
self.latest_archive_overview = latest_archive_overview
self._output_language = self._detect_language()
- self._registry = None # 延迟加载
+ self._registry = memory_registry # Lazy defaults if no account snapshot was supplied.
self._schema_directories = None
self._extract_context = None # 缓存 ExtractContext 实例
self._isolation_handler = isolation_handler
diff --git a/openviking/session/memory/streaming_memory_updater.py b/openviking/session/memory/streaming_memory_updater.py
index 42a23bd07..6ca48d5c9 100644
--- a/openviking/session/memory/streaming_memory_updater.py
+++ b/openviking/session/memory/streaming_memory_updater.py
@@ -56,7 +56,7 @@ from openviking.session.memory.utils.streaming_batcher import (
from openviking.storage.viking_fs import get_viking_fs
from openviking.telemetry import tracer
from openviking.telemetry.tracer import get_trace_id
-from openviking_cli.exceptions import NotFoundError
+from openviking_cli.exceptions import ConflictError, NotFoundError
from openviking_cli.utils import get_logger
from openviking_cli.utils.config import get_openviking_config
@@ -110,6 +110,7 @@ class MemoryUpdateRequest:
strict_extract_errors: bool = False
isolation_options: dict[str, Any] = field(default_factory=dict)
metadata: dict[str, Any] = field(default_factory=dict)
+ memory_registry: MemoryTypeRegistry | None = None
@dataclass(slots=True)
@@ -321,7 +322,7 @@ class StreamingMemoryUpdater:
self, request: MemoryUpdateRequest
) -> tuple[MemoryUpdateRequest | None, MemoryUpdateRequest | None]:
operations = request.operations
- registry = self.registry or get_default_registry()
+ registry = request.memory_registry or self.registry or get_default_registry()
append_ops: list[ResolvedOperation] = []
merge_ops: list[ResolvedOperation] = []
for op in list(operations.upsert_operations or []):
@@ -412,6 +413,25 @@ class StreamingMemoryUpdater:
requests: list[MemoryUpdateRequest],
reason: str,
) -> StreamingMemoryUpdateResult:
+ # Compare only this group's schema, not unrelated types in the registry.
+ # Plain value equality is sufficient for these small, transient batches.
+ by_template: list[tuple[dict | None, list[MemoryUpdateRequest]]] = []
+ for request in requests:
+ registry = request.memory_registry or self.registry
+ schema = registry.get(group_key.memory_type) if registry is not None else None
+ template = schema.model_dump() if schema is not None else None
+ if template is not None:
+ # Private rendering provenance is deliberately absent from model_dump.
+ template["_account_content_template"] = schema._account_content_template
+ for existing, batch in by_template:
+ if existing == template:
+ batch.append(request)
+ break
+ else:
+ by_template.append((template, [request]))
+ batches = [batch for _, batch in by_template]
+ _check_template_batch_conflicts(batches)
+
input_operations = sum(_operation_count(request.operations) for request in requests)
input_patches = sum(
len(getattr(request.operations, "upsert_operations", []) or []) for request in requests
@@ -428,24 +448,32 @@ class StreamingMemoryUpdater:
f"input_deletes={input_deletes}",
console=self.config.trace_console,
)
- merged_operations = await self._merge_requests(requests)
- first_request = requests[0]
- apply_result = await self._apply_operations(
- operations=merged_operations,
- request=first_request,
- messages=_combined_request_messages(requests),
- )
- result = StreamingMemoryUpdateResult(
- operations=merged_operations,
- apply_result=apply_result,
- request_count=len(requests),
- metadata={
- "flush_reason": reason,
- "operation_count": _operation_count(merged_operations),
- "merge_group": _merge_group_key_label(group_key),
- },
- )
+ merged_batches = [await self._merge_requests(batch) for batch in batches]
+ # A merge can select a different target URI. Check its output too, before
+ # any template group writes, rather than allowing stale patches to run later.
+ _check_template_batch_conflicts(batches, merged_batches)
+ results = []
+ for batch, merged_operations in zip(batches, merged_batches, strict=True):
+ apply_result = await self._apply_operations(
+ operations=merged_operations,
+ request=batch[0],
+ messages=_combined_request_messages(batch),
+ )
+ results.append(
+ StreamingMemoryUpdateResult(
+ operations=merged_operations,
+ apply_result=apply_result,
+ request_count=len(batch),
+ metadata={
+ "flush_reason": reason,
+ "operation_count": _operation_count(merged_operations),
+ "merge_group": _merge_group_key_label(group_key),
+ },
+ )
+ )
+ result = combine_streaming_memory_results(*results, fallback_request_count=len(requests))
self._last_result = result
+ apply_result = result.apply_result
tracer.info(
"StreamingMemoryUpdater flush finished "
f"group={group_key} reason={reason} request_count={len(requests)} "
@@ -476,7 +504,7 @@ class StreamingMemoryUpdater:
)
try:
updater = MemoryUpdater(
- registry=self.registry,
+ registry=request.memory_registry or self.registry,
vikingdb=self.vikingdb,
transaction_handle=lease,
)
@@ -550,7 +578,9 @@ class StreamingMemoryUpdater:
operations=operations,
messages=_combined_request_messages(kind_requests),
ctx=kind_requests[0].ctx,
- registry=self.registry or get_default_registry(),
+ registry=kind_requests[0].memory_registry
+ or self.registry
+ or get_default_registry(),
strict_extract_errors=any(
request.strict_extract_errors for request in kind_requests
),
@@ -592,6 +622,40 @@ class StreamingMemoryUpdater:
return merged
+def _check_template_batch_conflicts(
+ batches: list[list[MemoryUpdateRequest]],
+ merged_batches: list[ResolvedOperations] | None = None,
+) -> None:
+ """Reject cross-template file conflicts before any batch writes.
+
+ Sequencing or locking writes cannot rebase patches extracted from the same
+ old file. Do not silently pick one template for both requests either: callers
+ must re-extract with consistent templates and current file contents.
+ """
+ if len(batches) < 2:
+ return
+ viking_fs = safe_get_viking_fs()
+ uri_to_path = getattr(viking_fs, "_uri_to_path", None)
+ owners: dict[str, int] = {}
+ for index, batch in enumerate(batches):
+ targets = [(request, _request_uri_set(request)) for request in batch]
+ if merged_batches is not None:
+ targets.append((batch[0], _operation_uri_set(merged_batches[index])))
+ for request, uris in targets:
+ for uri in sorted(uris):
+ path = uri_to_path(uri, ctx=request.ctx) if callable(uri_to_path) else uri
+ # Conservatively cover case-insensitive storage, as apply's
+ # same-batch upsert/delete conflict protection already does.
+ key = path.rstrip("/").casefold()
+ if owners.setdefault(key, index) != index:
+ raise ConflictError(
+ f"Conflicting memory template snapshots for {uri}; "
+ "no memory operations in this merge batch were applied. "
+ "Re-extract with current templates and file contents before retrying.",
+ resource=uri,
+ )
+
+
def split_request_by_merge_group(
request: MemoryUpdateRequest,
) -> list[tuple[MemoryMergeGroupKey, MemoryUpdateRequest]]:
@@ -961,6 +1025,7 @@ async def merge_one_memory_type_operations(
required_file_uris=required_file_uris,
patches=patches,
output_language=merge_output_language_from_messages(messages),
+ memory_registry=registry,
)
provider._ctx = ctx
provider._viking_fs = safe_get_viking_fs()
@@ -1158,6 +1223,9 @@ async def render_operation_after_file_content(
return MemoryFileUtils.write(
mf,
content_template=schema.content_template,
+ account_content_template_type=(
+ schema.memory_type if schema._account_content_template else None
+ ),
extract_context=extract_context,
)
@@ -1587,6 +1655,7 @@ def clone_memory_update_request(
strict_extract_errors=request.strict_extract_errors,
isolation_options=dict(request.isolation_options or {}),
metadata=dict(request.metadata or {}),
+ memory_registry=request.memory_registry,
)
diff --git a/openviking/session/memory/utils/content_template.py b/openviking/session/memory/utils/content_template.py
new file mode 100644
index 000000000..f3fccd0dd
--- /dev/null
+++ b/openviking/session/memory/utils/content_template.py
@@ -0,0 +1,270 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Restricted Markdown templates published through the account management API.
+
+Deployment-owned templates and exact inherited copies keep their existing renderer.
+Only account bodies differing from the current deployment defaults use this contract,
+both at publication and when rendering the extraction snapshot.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Mapping
+
+from jinja2 import StrictUndefined, TemplateError, meta, nodes
+from jinja2.runtime import LoopContext
+from jinja2.sandbox import ImmutableSandboxedEnvironment
+
+MAX_CONTENT_TEMPLATE_BYTES = 64 * 1024
+MAX_CONTENT_OUTPUT_BYTES = 1024 * 1024
+CONTENT_TEMPLATE_FIELDS = {
+ "events": ("event_name", "goal", "summary", "ranges"),
+ "soul": ("core_truths", "boundaries", "vibe", "continuity"),
+ "identity": ("name", "creature", "vibe", "emoji", "avatar", "introduction"),
+}
+# Positional argument counts; these helpers only read the current extraction context.
+_EVENT_METHODS = {
+ "get_resource_event_content": (2,),
+ "get_first_message_time_from_ranges": (1,),
+ "get_first_message_time_with_weekday_from_ranges": (1,),
+ "get_event_content": (2, 3),
+ "get_year": (1,),
+ "get_month": (1,),
+ "get_day": (1,),
+}
+_STRING_METHODS = {"upper", "lower", "strip"}
+_TESTS = {"defined", "undefined", "none", "string"}
+_LOOP_ATTRIBUTES = {"index", "index0", "first", "last", "length"}
+_RESERVED_METADATA = re.compile(r"<!--\s*MEMORY_FIELDS\b")
+_NODES = (
+ nodes.Template,
+ nodes.Output,
+ nodes.TemplateData,
+ nodes.Name,
+ nodes.Const,
+ nodes.If,
+ nodes.For,
+ nodes.Assign,
+ nodes.List,
+ nodes.Tuple,
+ nodes.Getattr,
+ nodes.Call,
+ nodes.Test,
+ nodes.Compare,
+ nodes.Operand,
+ nodes.And,
+ nodes.Or,
+ nodes.Not,
+ nodes.CondExpr,
+)
+
+
+class ContentTemplateError(ValueError):
+ def __init__(self, reason: str, line: int = 0):
+ self.reason = reason
+ self.line = line
+ super().__init__(f"content_template: {reason}" + (f" (line {line})" if line else ""))
+
+
+class _ContentEnvironment(ImmutableSandboxedEnvironment):
+ def getattr(self, obj: Any, attribute: str) -> Any:
+ # Check before Jinja looks up the attribute (or falls back to a mapping
+ # key). A same-named method/property on another object is not trusted.
+ if attribute in _STRING_METHODS and type(obj) is not str:
+ return self.unsafe_undefined(obj, attribute)
+ return super().getattr(obj, attribute)
+
+ def is_safe_attribute(self, obj: Any, attr: str, value: Any) -> bool:
+ return (type(obj) is str and attr in _STRING_METHODS) or (
+ isinstance(obj, LoopContext) and attr in _LOOP_ATTRIBUTES
+ )
+
+
+def _environment() -> _ContentEnvironment:
+ env = _ContentEnvironment(autoescape=False, undefined=StrictUndefined)
+ env.globals.clear()
+ env.filters.clear()
+ env.tests = {name: env.tests[name] for name in _TESTS}
+ return env
+
+
+def _parse(
+ template: str,
+ memory_type: str,
+ env: _ContentEnvironment,
+ *,
+ variables: frozenset[str] | None = None,
+ max_template_bytes: int = MAX_CONTENT_TEMPLATE_BYTES,
+) -> nodes.Template:
+ # Descriptions reuse the same syntax/sandbox with their own variable and
+ # source-size contract. They never receive Events helpers or body fields.
+ if variables is None and memory_type not in CONTENT_TEMPLATE_FIELDS:
+ raise ContentTemplateError("unsupported_memory_type")
+ if not isinstance(template, str) or not template.strip():
+ raise ContentTemplateError("empty_template")
+ if len(template.encode("utf-8")) > max_template_bytes:
+ raise ContentTemplateError("template_too_large")
+ if _RESERVED_METADATA.search(template):
+ raise ContentTemplateError("reserved_metadata")
+ try:
+ tree = env.parse(template)
+ allowed = set(variables if variables is not None else CONTENT_TEMPLATE_FIELDS[memory_type])
+ if memory_type == "events":
+ allowed.add("extract_context")
+ all_nodes = list(tree.find_all(nodes.Node))
+ if len(all_nodes) > 2048:
+ raise ContentTemplateError("template_too_complex")
+ callable_attributes = {id(n.node) for n in all_nodes if isinstance(n, nodes.Call)}
+ attribute_owners = {id(n.node) for n in all_nodes if isinstance(n, nodes.Getattr)}
+ loop_lists = [n.iter for n in all_nodes if isinstance(n, nodes.For)]
+ literal_containers = {id(n) for n in loop_lists}
+ for container in loop_lists:
+ if isinstance(container, (nodes.List, nodes.Tuple)):
+ literal_containers.update(
+ id(n) for n in container.items if isinstance(n, nodes.Tuple)
+ )
+ for node in all_nodes:
+ if isinstance(node, nodes.Filter):
+ raise ContentTemplateError("unsupported_filter", node.lineno)
+ if not isinstance(node, _NODES):
+ raise ContentTemplateError("unsupported_syntax", node.lineno)
+ if isinstance(node, nodes.Name) and node.ctx == "store":
+ if node.name in allowed | {"extract_context", "loop"} or node.name.startswith("_"):
+ raise ContentTemplateError("reserved_variable", node.lineno)
+ if (
+ isinstance(node, nodes.Name)
+ and node.name == "extract_context"
+ and id(node) not in attribute_owners
+ ):
+ raise ContentTemplateError("unsupported_attribute", node.lineno)
+ if (
+ isinstance(node, (nodes.List, nodes.Tuple))
+ and getattr(node, "ctx", "load") != "store"
+ and id(node) not in literal_containers
+ ):
+ raise ContentTemplateError("unsupported_syntax", node.lineno)
+ if isinstance(node, nodes.Getattr):
+ owner = node.node.name if isinstance(node.node, nodes.Name) else None
+ helper = (
+ owner == "extract_context"
+ and node.attr in _EVENT_METHODS
+ and memory_type == "events"
+ and id(node) in callable_attributes
+ )
+ string_method = (
+ node.attr in _STRING_METHODS
+ and owner not in {"extract_context", "loop"}
+ and id(node) in callable_attributes
+ )
+ if not (helper or string_method) and not (
+ owner == "loop" and node.attr in _LOOP_ATTRIBUTES
+ ):
+ raise ContentTemplateError("unsupported_attribute", node.lineno)
+ if isinstance(node, nodes.Call):
+ _validate_call(node, memory_type)
+ if isinstance(node, nodes.Test):
+ if node.name not in _TESTS or node.kwargs or node.dyn_args or node.dyn_kwargs:
+ raise ContentTemplateError("unsupported_test", node.lineno)
+ if node.args:
+ raise ContentTemplateError("invalid_arguments", node.lineno)
+ if isinstance(node, nodes.For):
+ # Iterating over an explicit field list is sufficient for Markdown
+ # sections. No range(), message-sized loops, nesting or recursion.
+ if (
+ node.recursive
+ or not isinstance(node.iter, (nodes.List, nodes.Tuple))
+ or len(node.iter.items) > 32
+ or list(node.find_all(nodes.For))
+ ):
+ raise ContentTemplateError("unsupported_loop", node.lineno)
+ # meta uses Jinja's compiler, which can constant-fold expressions. Only
+ # invoke it after rejecting arithmetic, calls and other unsupported AST.
+ unknown = meta.find_undeclared_variables(tree) - allowed
+ if unknown:
+ line = next(n.lineno for n in tree.find_all(nodes.Name) if n.name in unknown)
+ raise ContentTemplateError("unknown_variable", line)
+ return tree
+ except TemplateError as exc:
+ raise ContentTemplateError("invalid_jinja", getattr(exc, "lineno", 0) or 0) from exc
+ except RecursionError as exc:
+ raise ContentTemplateError("template_too_complex") from exc
+
+
+def _validate_call(node: nodes.Call, memory_type: str) -> None:
+ target = node.node
+ if isinstance(target, nodes.Getattr) and target.attr in _STRING_METHODS:
+ if node.args or node.kwargs or node.dyn_args or node.dyn_kwargs:
+ raise ContentTemplateError("invalid_arguments", node.lineno)
+ # The receiver may be a field, local, literal, or another allowed call.
+ # Its exact runtime type is checked before attribute lookup by the sandbox.
+ return
+ if (
+ memory_type != "events"
+ or not isinstance(target, nodes.Getattr)
+ or not isinstance(target.node, nodes.Name)
+ or target.node.name != "extract_context"
+ or target.attr not in _EVENT_METHODS
+ ):
+ raise ContentTemplateError("unsupported_call", node.lineno)
+ if (
+ node.kwargs
+ or node.dyn_args
+ or node.dyn_kwargs
+ or len(node.args) not in _EVENT_METHODS[target.attr]
+ ):
+ raise ContentTemplateError("invalid_arguments", node.lineno)
+ # Never allow a template to fabricate an unbounded message-index range.
+ ranges = node.args[0]
+ if not isinstance(ranges, nodes.Name) or ranges.name != "ranges":
+ raise ContentTemplateError("invalid_ranges", node.lineno)
+ if len(node.args) == 3:
+ ratio = node.args[2]
+ if (
+ not isinstance(ratio, nodes.Const)
+ or type(ratio.value) not in (int, float)
+ or not 0 <= ratio.value <= 1
+ ):
+ raise ContentTemplateError("invalid_ratio", node.lineno)
+
+
+def validate_content_template(template: str, memory_type: str) -> None:
+ _parse(template, memory_type, _environment())
+
+
+def render_content_template(
+ template: str, memory_type: str, fields: Mapping[str, Any], extract_context: Any = None
+) -> str:
+ env = _environment()
+ tree = _parse(template, memory_type, env)
+ # Do not expose metadata, request context, URI helpers, or arbitrary objects.
+ values: dict[str, Any] = {
+ name: fields.get(name) or "" for name in CONTENT_TEMPLATE_FIELDS[memory_type]
+ }
+ if any(
+ not isinstance(value, str) or len(value.encode("utf-8")) > MAX_CONTENT_OUTPUT_BYTES
+ for value in values.values()
+ ):
+ raise ContentTemplateError("invalid_field_value")
+ if memory_type == "events":
+ values["extract_context"] = {
+ name: getattr(extract_context, name)
+ for name in _EVENT_METHODS
+ if extract_context is not None and hasattr(extract_context, name)
+ }
+ try:
+ compiled = env.from_string(tree)
+ chunks = []
+ size = 0
+ for chunk in compiled.generate(**values):
+ size += len(chunk.encode("utf-8"))
+ if size > MAX_CONTENT_OUTPUT_BYTES:
+ raise ContentTemplateError("output_too_large")
+ chunks.append(chunk)
+ rendered = "".join(chunks).strip()
+ if _RESERVED_METADATA.search(rendered):
+ raise ContentTemplateError("reserved_metadata")
+ return rendered
+ except TemplateError as exc:
+ # A runtime error must fail this write, not silently persist a blank body.
+ raise ContentTemplateError("render_failed") from exc
diff --git a/openviking/session/memory/utils/description_template.py b/openviking/session/memory/utils/description_template.py
new file mode 100644
index 000000000..6d5233dec
--- /dev/null
+++ b/openviking/session/memory/utils/description_template.py
@@ -0,0 +1,84 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""One restricted Jinja contract for deployment and account descriptions."""
+
+from typing import Any, Mapping
+
+from jinja2 import TemplateError, Undefined
+
+from openviking.session.memory.utils.content_template import (
+ ContentTemplateError,
+ _environment,
+ _parse,
+)
+
+MAX_DESCRIPTION_CHARS = 50_000
+MAX_DESCRIPTION_OUTPUT_BYTES = 1024 * 1024
+DESCRIPTION_VARIABLES = frozenset({"language"})
+
+
+class DescriptionTemplateError(ValueError):
+ def __init__(self, reason: str, line: int = 0, field: str = "description"):
+ self.reason = reason
+ self.line = line
+ self.field = field
+ super().__init__(f"{field}: {reason}" + (f" (line {line})" if line else ""))
+
+
+def _parse_description(template: str, env):
+ if not isinstance(template, str):
+ raise DescriptionTemplateError("invalid_template")
+ if len(template) > MAX_DESCRIPTION_CHARS:
+ raise DescriptionTemplateError("template_too_large")
+ # Empty deployment descriptions are valid; the editing API separately
+ # requires nonempty supplied descriptions. Plain text needs no special mode.
+ if not template.strip():
+ return env.parse(template)
+ try:
+ return _parse(
+ template,
+ "description",
+ env,
+ variables=DESCRIPTION_VARIABLES,
+ max_template_bytes=4 * MAX_DESCRIPTION_CHARS,
+ )
+ except ContentTemplateError as exc:
+ raise DescriptionTemplateError(exc.reason, exc.line) from exc
+
+
+def validate_description_template(template: str, *, field: str = "description") -> None:
+ try:
+ _parse_description(template, _environment())
+ except DescriptionTemplateError as exc:
+ raise DescriptionTemplateError(exc.reason, exc.line, field) from exc
+
+
+def render_description_template(
+ template: str, context: Mapping[str, Any], *, strip: bool = True
+) -> str:
+ env = _environment()
+ # Preserve plain schema descriptions byte-for-byte when strip=False, as
+ # before; templated descriptions keep Jinja's existing newline behavior.
+ env.keep_trailing_newline = not any(marker in template for marker in ("{{", "{%", "{#"))
+ tree = _parse_description(template, env)
+ # Preserve the existing optional language context: missing variables retain
+ # Jinja's undefined tests/empty output, without supplying a new language.
+ env.undefined = Undefined
+ values = {name: context[name] for name in DESCRIPTION_VARIABLES if name in context}
+ if any(
+ type(value) is not str or len(value.encode("utf-8")) > MAX_DESCRIPTION_OUTPUT_BYTES
+ for value in values.values()
+ ):
+ raise DescriptionTemplateError("invalid_context_value")
+ try:
+ chunks = []
+ size = 0
+ for chunk in env.from_string(tree).generate(**values):
+ size += len(chunk.encode("utf-8"))
+ if size > MAX_DESCRIPTION_OUTPUT_BYTES:
+ raise DescriptionTemplateError("output_too_large")
+ chunks.append(chunk)
+ result = "".join(chunks)
+ return result.strip() if strip else result
+ except TemplateError as exc:
+ raise DescriptionTemplateError("render_failed") from exc
diff --git a/openviking/session/memory/utils/memory_file_utils.py b/openviking/session/memory/utils/memory_file_utils.py
index 2953a6985..5488409ff 100644
--- a/openviking/session/memory/utils/memory_file_utils.py
+++ b/openviking/session/memory/utils/memory_file_utils.py
@@ -5,6 +5,7 @@ from datetime import datetime
from typing import Any, Dict, Optional
from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.utils.content_template import render_content_template
from openviking.session.memory.utils.link_renderer import LinkRenderer
from openviking.session.memory.utils.messages import parse_memory_file_with_fields
from openviking.session.memory.utils.uri import render_template
@@ -37,9 +38,9 @@ def next_memory_version(old_file: Optional[MemoryFile]) -> int:
def bump_memory_version(memory_file: MemoryFile) -> None:
"""Increment a MemoryFile's persisted MEMORY_FIELDS version in-place."""
- memory_file.extra_fields["version"] = memory_version_from_fields(
- memory_file.extra_fields, default=1
- ) + 1
+ memory_file.extra_fields["version"] = (
+ memory_version_from_fields(memory_file.extra_fields, default=1) + 1
+ )
def _serialize_datetime(obj: Any) -> Any:
@@ -59,8 +60,6 @@ def _deserialize_datetime(metadata: Dict[str, Any]) -> Dict[str, Any]:
return result
-
-
def _uri_basename(uri: str) -> str:
name = str(uri or "").rstrip("/").rsplit("/", 1)[-1]
return name.removesuffix(".md")
@@ -71,16 +70,24 @@ def _template_link_target(source_uri: Optional[str], target_uri: str) -> str:
return LinkRenderer.relative_path(str(source_uri), str(target_uri)) or str(target_uri)
return str(target_uri or "")
+
def _serialize_with_metadata(
metadata: Dict[str, Any],
content_template: str = None,
extract_context: Any = None,
source_uri: Optional[str] = None,
render_links: bool = True,
+ account_content_template_type: Optional[str] = None,
) -> str:
content = metadata.pop("content", "") or ""
- if content_template:
+ if content_template and account_content_template_type:
+ # Managed-template failures must not be swallowed by the legacy plain
+ # content fallback: that could silently overwrite a valid Markdown body.
+ content = render_content_template(
+ content_template, account_content_template_type, metadata, extract_context
+ )
+ elif content_template:
try:
template_vars = metadata.copy()
template_vars["content"] = content
@@ -88,7 +95,9 @@ def _serialize_with_metadata(
template_vars.setdefault("backlinks", [])
template_vars["source_uri"] = source_uri or ""
template_vars["uri_basename"] = _uri_basename
- template_vars["link_target"] = lambda target_uri: _template_link_target(source_uri, target_uri)
+ template_vars["link_target"] = lambda target_uri: _template_link_target(
+ source_uri, target_uri
+ )
content = render_template(content_template, template_vars, extract_context)
except Exception:
logger.exception(
@@ -141,6 +150,8 @@ class MemoryFileUtils:
content_template: Optional[str] = None,
extract_context: Any = None,
render_links: bool = True,
+ *,
+ account_content_template_type: Optional[str] = None,
) -> str:
"""Serialize a MemoryFile as plain-text body plus MEMORY_FIELDS metadata."""
metadata = memory_file.to_metadata()
@@ -150,6 +161,7 @@ class MemoryFileUtils:
extract_context=extract_context,
source_uri=memory_file.uri,
render_links=render_links,
+ account_content_template_type=account_content_template_type,
)
@staticmethod
diff --git a/tests/api_test/filesystem/test_fs_cp.py b/tests/api_test/filesystem/test_fs_cp.py
index c0ad58572..f449ea553 100644
--- a/tests/api_test/filesystem/test_fs_cp.py
+++ b/tests/api_test/filesystem/test_fs_cp.py
@@ -1,6 +1,8 @@
import os
import uuid
+import pytest
+
class TestFsCp:
def test_cp_file_preserves_source_and_content(self, api_client):
@@ -73,20 +75,61 @@ class TestFsCp:
suffix = uuid.uuid4().hex[:8]
source = f"viking://resources/cp-overwrite-source-{suffix}.md"
target = f"viking://resources/cp-overwrite-target-{suffix}.md"
+ source_content = f"new payload {suffix}"
+ target_content = f"old target content must be completely replaced {suffix}"
try:
assert (
- api_client.fs_write(source, "source remains", mode="create", wait=True).status_code
+ api_client.fs_write(source, source_content, mode="create", wait=True).status_code
== 200
)
assert (
- api_client.fs_write(target, "target remains", mode="create", wait=True).status_code
+ api_client.fs_write(target, target_content, mode="create", wait=True).status_code
== 200
)
copied = api_client.fs_cp(source, target)
assert copied.status_code == 200, copied.text
- assert "source remains" in api_client.fs_read(source).json().get("result", "")
- assert "source remains" in api_client.fs_read(target).json().get("result", "")
+ result = copied.json().get("result", {})
+ assert result.get("from") == source
+ assert result.get("to") == target
+ assert result.get("phase") == "completed"
+ assert result.get("recursive") is False
+ for uri in (source, target):
+ read = api_client.fs_read(uri)
+ assert read.status_code == 200, read.text
+ assert read.json().get("result") == source_content
finally:
api_client.fs_rm(source)
api_client.fs_rm(target)
+
+ @pytest.mark.parametrize("source_is_dir", [False, True], ids=["file-to-dir", "dir-to-file"])
+ def test_cp_rejects_file_directory_type_conflicts(self, api_client, source_is_dir):
+ suffix = uuid.uuid4().hex[:8]
+ file_uri = f"viking://resources/cp-type-file-{suffix}.md"
+ directory_uri = f"viking://resources/cp-type-dir-{suffix}"
+ child_uri = f"{directory_uri}/child.md"
+ file_content = f"file remains {suffix}"
+ child_content = f"directory child remains {suffix}"
+ try:
+ assert api_client.fs_mkdir(directory_uri).status_code == 200
+ # mkdir queues a parent refresh; finish it before preparing files so
+ # this test exercises type validation, not a transient refresh lock.
+ settled = api_client.system_wait(timeout=30)
+ assert settled.status_code == 200, settled.text
+ for uri, content in ((file_uri, file_content), (child_uri, child_content)):
+ write = api_client.fs_write(uri, content, mode="create", wait=True)
+ assert write.status_code == 200, write.text
+
+ source, target = (
+ (directory_uri, file_uri) if source_is_dir else (file_uri, directory_uri)
+ )
+ copied = api_client.fs_cp(source, target, recursive=source_is_dir)
+ assert copied.status_code == 400, copied.text
+ assert copied.json().get("error", {}).get("code") == "INVALID_ARGUMENT"
+ for uri, content in ((file_uri, file_content), (child_uri, child_content)):
+ read = api_client.fs_read(uri)
+ assert read.status_code == 200, read.text
+ assert read.json().get("result") == content
+ finally:
+ api_client.fs_rm(file_uri)
+ api_client.fs_rm(directory_uri, recursive=True)
diff --git a/tests/server/test_admin_api.py b/tests/server/test_admin_api.py
index 9efbe19bf..574375046 100644
--- a/tests/server/test_admin_api.py
+++ b/tests/server/test_admin_api.py
@@ -6,11 +6,14 @@
import asyncio
import hashlib
import json
+import threading
import uuid
+from unittest.mock import AsyncMock, Mock
import httpx
import pytest
import pytest_asyncio
+import yaml
from fastapi import FastAPI
from fastapi import Request as FastAPIRequest
from fastapi.responses import JSONResponse
@@ -34,8 +37,22 @@ from openviking.service.task_store import (
)
from openviking.service.task_tracker import get_task_tracker
from openviking.service.user_deletion import setup_user_deletion
+from openviking.session.memory.account_templates import (
+ EDITABLE_MEMORY_TEMPLATE_FIELDS,
+ account_memory_template_path,
+ resolve_account_memory_registry,
+)
+from openviking.session.memory.extract_loop import ExtractLoop
+from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandler
+from openviking.session.memory.memory_type_registry import (
+ MemoryTypeRegistry,
+ get_default_registry,
+)
+from openviking.session.memory.patch_merge_context_provider import PatchMergeContextProvider
+from openviking.session.memory.session_extract_context_provider import SessionExtractContextProvider
from openviking_cli.exceptions import OpenVikingError, PermissionDeniedError
from openviking_cli.session.user_id import UserIdentifier
+from openviking_cli.utils.config import get_openviking_config
def _uid() -> str:
@@ -63,6 +80,12 @@ class _FakeAGFS:
self.ensure_parent_dirs(path)
self._files[path] = content
+ def mv(self, old_path, new_path, **_kwargs):
+ self._files[new_path] = self._files.pop(old_path)
+
+ def rm(self, path, **_kwargs):
+ self._files.pop(path, None)
+
def mkdir(self, path, **_kwargs):
self._dirs.add(path)
@@ -78,6 +101,9 @@ class _FakeAGFS:
def pathlock_acquire_exact(self, ctx, path, timeout_secs=0.0, owner_lease_ref=None):
return {"lease_ref": f"test:{path}"}
+ def pathlock_acquire_exact_batch(self, ctx, paths, timeout_secs=0.0, owner_lease_ref=None):
+ return self.pathlock_acquire_exact(ctx, paths[0], timeout_secs, owner_lease_ref)
+
def pathlock_release(self, ctx, lease):
return None
@@ -282,6 +308,1003 @@ async def _wait_for_task(client: httpx.AsyncClient, task_id: str) -> dict:
# ---- Account CRUD ----
+@pytest_asyncio.fixture
+async def template_account(lightweight_admin_client):
+ account_id = _uid()
+ response = await lightweight_admin_client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": account_id, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+ assert response.status_code == 200, response.text
+ return account_id, {"X-API-Key": response.json()["result"]["user_key"]}
+
+
+ "memory_type",
+ ["profile", "preferences", "entities", "events", "soul", "identity"],
+)
+async def test_account_memory_templates_publish_and_reset(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ memory_type,
+):
+ client = lightweight_admin_client
+ account_id, headers = template_account
+ root = f"/api/v1/admin/accounts/{account_id}/memory-templates"
+ path = account_memory_template_path(account_id, memory_type)
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ settings_path = f"/local/{account_id}/_system/setting.json"
+ fs.agfs._files[settings_path] = b'{"agent_evolution":{"enabled":false}}'
+ registry = get_default_registry()
+ original = {s.memory_type: s.model_dump() for s in registry.list_all(True)}
+ initial = await client.get(root, headers=headers)
+ assert initial.status_code == 200, initial.text
+ assert {item["memory_type"] for item in initial.json()["result"]["templates"]} == {
+ "profile",
+ "events",
+ "preferences",
+ "entities",
+ "soul",
+ "identity",
+ }
+ assert all(item["status"] == "system_default" for item in initial.json()["result"]["templates"])
+ assert path not in fs.agfs._files
+
+ editable_fields = {
+ "profile": ("content",),
+ "events": ("event_name", "summary"),
+ "preferences": ("topic", "content"),
+ "entities": ("category", "name", "content"),
+ "soul": ("core_truths", "boundaries", "vibe", "continuity"),
+ "identity": ("creature", "name", "vibe", "avatar", "emoji", "introduction"),
+ }[memory_type]
+ body = {
+ "description": "Remember business facts in {{ language.lower() }}.",
+ "fields": [
+ {"name": name, "description": f"Business {name}: {{{{ language }}}}"}
+ for name in editable_fields
+ ],
+ }
+ if memory_type in {"events", "soul", "identity"}:
+ variable = {"events": "summary", "soul": "core_truths", "identity": "introduction"}[
+ memory_type
+ ]
+ body["content_template"] = "# Business\n{{ " + variable + " }}"
+ publish = await client.put(f"{root}/{memory_type}", json=body, headers=headers)
+ assert publish.status_code == 200, publish.text
+ result = publish.json()["result"]
+ assert result["status"] == "custom"
+ assert result["updated_at"]
+ assert all(result["effective"][key] == value for key, value in body.items() if key != "fields")
+ assert result["effective"]["fields"][0]["type"] == "string"
+ stored = yaml.safe_load(fs.agfs._files[path])
+ assert stored.pop("_updated_at") == result["updated_at"]
+ assert stored == result["effective"]
+ assert stored["memory_type"] == memory_type
+ assert "stage" in stored and "embedding_template" in stored
+ assert fs.agfs._files[settings_path] == b'{"agent_evolution":{"enabled":false}}'
+ assert (await client.get(f"{root}/{memory_type}", headers=headers)).json()["result"] == result
+ roundtrip = await client.put(f"{root}/{memory_type}", json=result["effective"], headers=headers)
+ assert roundtrip.status_code == 200, roundtrip.text
+ assert roundtrip.json()["result"] == result
+ listed = (await client.get(root, headers=headers)).json()["result"]["templates"]
+ assert (
+ next(item for item in listed if item["memory_type"] == memory_type)["effective"] == stored
+ )
+ resolved = await resolve_account_memory_registry(fs, account_id, registry)
+ assert resolved is not registry
+ assert all(resolved.get(schema.memory_type) is not schema for schema in registry.list_all(True))
+ schema = resolved.get(memory_type)
+ assert schema.description == body["description"]
+ expected = dict(original[memory_type])
+ expected["description"] = body["description"]
+ if "content_template" in body:
+ expected["content_template"] = body["content_template"]
+ expected["fields"] = [
+ {**field, "description": f"Business {field['name']}: {{{{ language }}}}"}
+ if field["name"] in editable_fields
+ else field
+ for field in expected["fields"]
+ ]
+ assert schema.model_dump() == expected
+ # All fields, including Events goal/ranges, survive a partial request.
+ assert [field.name for field in schema.fields] == [
+ field["name"] for field in original[memory_type]["fields"]
+ ]
+ assert {s.memory_type: s.model_dump() for s in registry.list_all(True)} == original
+
+ noop = await client.put(f"{root}/{memory_type}", json=body, headers=headers)
+ assert noop.json()["result"]["updated_at"] == result["updated_at"]
+ replacement = await client.put(
+ f"{root}/{memory_type}", json={"description": "Replacement"}, headers=headers
+ )
+ assert replacement.status_code == 200, replacement.text
+ assert replacement.json()["result"]["effective"]["fields"] == result["defaults"]["fields"]
+ assert yaml.safe_load(fs.agfs._files[path + ".backup"])["description"] == body["description"]
+ # An earlier extraction retains its complete snapshot across publication.
+ assert resolved.get(memory_type).description == body["description"]
+ reset = await client.delete(f"{root}/{memory_type}", headers=headers)
+ assert reset.status_code == 200, reset.text
+ assert reset.json()["result"]["effective"] == result["defaults"]
+ assert reset.json()["result"]["status"] == "system_default"
+ assert path not in fs.agfs._files
+ restored = await resolve_account_memory_registry(fs, account_id, registry)
+ assert {s.memory_type: s.model_dump() for s in restored.list_all(True)} == original
+ assert (await client.delete(f"{root}/{memory_type}", headers=headers)).status_code == 200
+ default_form = await client.put(
+ f"{root}/{memory_type}", json=result["defaults"], headers=headers
+ )
+ assert default_form.status_code == 200, default_form.text
+ assert default_form.json()["result"]["effective"] == result["defaults"]
+
+
+ "body",
+ [
+ {"description": 123},
+ {"description": "{{ language | upper }}"},
+ {"description": "{{ cycler.__init__.__globals__.__builtins__.len('harmless') }}"},
+ {"description": "literal {{ unclosed"},
+ {"fields": [{"name": "summary", "description": "{{ summary }}"}]},
+ {"fields": [{"name": "summary", "description": "{{ language | lower }}"}]},
+ {"fields": [{"name": "summary", "description": "literal {{ unclosed"}]},
+ {"_account_description": False},
+ {"fields": [{"name": "summary", "_account_description": False}]},
+ {"memory_type": "other"},
+ {"fields": None},
+ {"fields": [{}]},
+ {"fields": [{"name": "x", "type": "not-a-type"}]},
+ {"fields": [{"name": "x", "merge_op": "not-an-op"}]},
+ {"fields": [{"name": "x"}, {"name": "x"}]},
+ {"fields": [{"name": "x", "description": "{{"}]},
+ {"content_template": "{{"},
+ {"content_template": "{{ unknown_field }}"},
+ {"content_template": "{{ extract_context.messages }}"},
+ {"content_template": "{{ extract_context.get_year('0-999999999') }}"},
+ {"content_template": "{% include 'private.yaml' %}"},
+ {"content_template": "{{ summary | attr('__class__') }}"},
+ {"content_template": "{{ summary | upper }}"},
+ {"content_template": "{{ summary | default('pending') }}"},
+ {"content_template": "{{ summary.strip('x') }}"},
+ {"content_template": "x" * (64 * 1024 + 1)},
+ ],
+)
+async def test_account_memory_templates_reject_invalid_configuration(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ body,
+):
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/events"
+ assert (
+ await lightweight_admin_client.put(
+ url, json={"description": "Keep current"}, headers=headers
+ )
+ ).status_code == 200
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ original = dict(fs.agfs._files)
+ response = await lightweight_admin_client.put(url, json=body, headers=headers)
+ assert response.status_code in {400, 422}, response.text
+ assert fs.agfs._files == original
+
+
[email protected]("field", ["description", "fields.content.description"])
+ ("text", "reason"),
+ [
+ ("{{ language | upper }}", "unsupported_filter"),
+ ("{{ cycler.__init__.__globals__.__builtins__.len('harmless') }}", "unsupported_call"),
+ ("{{", "invalid_jinja"),
+ ],
+)
+async def test_account_memory_templates_description_diagnostics_and_legacy_recovery(
+ lightweight_admin_client, lightweight_admin_app, template_account, field, text, reason
+):
+ account_id, headers = template_account
+ client = lightweight_admin_client
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ active = await client.put(url, json={"description": "Current"}, headers=headers)
+ assert active.status_code == 200
+ before = dict(fs.agfs._files)
+ body = (
+ {"description": text}
+ if field == "description"
+ else {"fields": [{"name": "content", "description": text}]}
+ )
+ response = await client.put(url, json=body, headers=headers)
+ assert response.status_code == 400, response.text
+ details = response.json()["error"]["details"]
+ assert details["field"] == field
+ assert details["reason"] == reason
+ assert details["line"] == 1
+ assert fs.agfs._files == before
+
+ # An old well-formed YAML override may contain now-unsupported expressions.
+ # Reading/resetting must stay possible, while extraction must reject it.
+ path = account_memory_template_path(account_id, "profile")
+ stored = yaml.safe_load(fs.agfs._files[path])
+ target = stored if field == "description" else stored["fields"][0]
+ target["description"] = text
+ target["_account_description"] = False
+ fs.agfs._files[path] = yaml.safe_dump(stored).encode()
+ assert (await client.get(url, headers=headers)).status_code == 200
+ from openviking_cli.exceptions import FailedPreconditionError
+
+ with pytest.raises(FailedPreconditionError, match="republish or reset"):
+ await resolve_account_memory_registry(fs, account_id, MemoryTypeRegistry())
+ assert (await client.delete(url, headers=headers)).status_code == 200
+ assert path not in fs.agfs._files
+
+
[email protected]("memory_type", list(EDITABLE_MEMORY_TEMPLATE_FIELDS))
[email protected]("character", ["a", "中", "😀"])
+async def test_account_memory_templates_description_character_limit(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ memory_type,
+ character,
+):
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}"
+ text = character * 50_000
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ # Check one field at a time without exceeding the aggregate 1 MiB cap.
+ for field_name in [None, *EDITABLE_MEMORY_TEMPLATE_FIELDS[memory_type]]:
+ body = {"description": text}
+ target = body
+ if field_name is not None:
+ target = {"name": field_name, "description": text}
+ body["fields"] = [target]
+ response = await lightweight_admin_client.put(url, json=body, headers=headers)
+ assert response.status_code == 200, response.text
+ effective = response.json()["result"]["effective"]
+ assert effective["description"] == text
+ if field_name is not None:
+ field = next(field for field in effective["fields"] if field["name"] == field_name)
+ assert field["description"] == text
+ original = dict(fs.agfs._files)
+ target["description"] = text + character
+ response = await lightweight_admin_client.put(url, json=body, headers=headers)
+ assert response.status_code == 400, response.text
+ assert "50000 Unicode characters" in response.json()["error"]["message"]
+ assert fs.agfs._files == original
+ assert (await lightweight_admin_client.get(url, headers=headers)).status_code == 200
+ assert (await lightweight_admin_client.delete(url, headers=headers)).status_code == 200
+
+
+async def test_account_memory_templates_content_validation_error_details(
+ lightweight_admin_client,
+ template_account,
+):
+ account_id, headers = template_account
+ response = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{account_id}/memory-templates/events",
+ json={"content_template": "# Summary\n{{ typo }}"},
+ headers=headers,
+ )
+ assert response.status_code == 400
+ assert response.json()["error"]["details"] == {
+ "field": "content_template",
+ "reason": "unknown_variable",
+ "line": 2,
+ }
+
+
+ "memory_type, field_name",
+ [("events", "summary"), ("soul", "core_truths"), ("identity", "introduction")],
+)
+async def test_account_memory_templates_string_methods_reach_file_body(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ memory_type,
+ field_name,
+):
+ from openviking.session.memory.dataclass import MemoryFile
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}"
+ body = {"content_template": "# {{ " + field_name + ".strip().upper() }}"}
+ response = await lightweight_admin_client.put(url, json=body, headers=headers)
+ assert response.status_code == 200, response.text
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ snapshot = await resolve_account_memory_registry(fs, account_id, MemoryTypeRegistry())
+ schema = snapshot.get(memory_type)
+ assert schema._account_content_template is True
+ rendered = MemoryFileUtils.write(
+ MemoryFile(memory_type=memory_type, extra_fields={field_name: " business fact "}),
+ content_template=schema.content_template,
+ account_content_template_type=schema.memory_type,
+ )
+ assert MemoryFileUtils.read(rendered).content == "# BUSINESS FACT"
+
+
+async def test_account_memory_templates_description_only_keeps_safe_deployment_methods(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ defaults = MemoryTypeRegistry()
+ defaults.get("events").content_template = "# {{ summary.strip().upper() }}"
+ monkeypatch.setattr("openviking.server.routers.admin.get_default_registry", lambda: defaults)
+ response = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{account_id}/memory-templates/events",
+ json={"description": "Capture release decisions"},
+ headers=headers,
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["effective"]["content_template"] == (
+ "# {{ summary.strip().upper() }}"
+ )
+ snapshot = await resolve_account_memory_registry(
+ lightweight_admin_app.state.fake_service.viking_fs, account_id, defaults
+ )
+ assert snapshot.get("events")._account_content_template is False
+ assert snapshot.get("events").content_template == "# {{ summary.strip().upper() }}"
+
+
+ "memory_type, field_name",
+ [("events", "summary"), ("soul", "core_truths"), ("identity", "introduction")],
+)
[email protected]("request_kind", ["description_only", "empty", "roundtrip"])
+async def test_account_memory_templates_inherit_exact_deployment_body(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+ memory_type,
+ field_name,
+ request_kind,
+):
+ from openviking.session.memory.dataclass import MemoryFile
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+
+ account_id, headers = template_account
+ defaults = MemoryTypeRegistry()
+ # Deployment code may use methods/filters that custom Account bodies cannot.
+ deployment_body = "# {{ " + field_name + ".replace('old', 'new') | upper }}"
+ defaults.get(memory_type).content_template = deployment_body
+ monkeypatch.setattr("openviking.server.routers.admin.get_default_registry", lambda: defaults)
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}"
+ body = {"description": "Account instructions"} if request_kind == "description_only" else {}
+ if request_kind == "roundtrip":
+ response = await lightweight_admin_client.get(url, headers=headers)
+ assert response.status_code == 200, response.text
+ body = response.json()["result"]["effective"]
+ body["description"] = "Account instructions"
+ response = await lightweight_admin_client.put(url, json=body, headers=headers)
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["status"] == "custom"
+ assert response.json()["result"]["effective"]["content_template"] == deployment_body
+ # Roundtrip a persisted override too, not only defaults returned before a PUT.
+ response = await lightweight_admin_client.put(
+ url, json=response.json()["result"]["effective"], headers=headers
+ )
+ assert response.status_code == 200, response.text
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ stored = yaml.safe_load(fs.agfs._files[account_memory_template_path(account_id, memory_type)])
+ assert "_account_content_template" not in stored
+ snapshot = await resolve_account_memory_registry(fs, account_id, defaults)
+ schema = snapshot.get(memory_type)
+ assert schema._account_content_template is False
+ assert schema.content_template == deployment_body
+ assert defaults.get(memory_type)._account_content_template is False
+ rendered = MemoryFileUtils.write(
+ MemoryFile(memory_type=memory_type, extra_fields={field_name: "old fact"}),
+ content_template=schema.content_template,
+ account_content_template_type=(
+ schema.memory_type if schema._account_content_template else None
+ ),
+ )
+ assert MemoryFileUtils.read(rendered).content == "# NEW FACT"
+
+
[email protected]("alteration", ["whitespace", "different_body"])
+async def test_account_memory_templates_recheck_persisted_body_without_trusting_flags(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+ alteration,
+):
+ from openviking_cli.exceptions import FailedPreconditionError
+
+ account_id, headers = template_account
+ defaults = MemoryTypeRegistry()
+ deployment_body = "{{ summary | upper }}"
+ defaults.get("events").content_template = deployment_body
+ monkeypatch.setattr("openviking.server.routers.admin.get_default_registry", lambda: defaults)
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/events"
+ assert (await lightweight_admin_client.put(url, json={}, headers=headers)).status_code == 200
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "events")
+ original = fs.agfs._files[path]
+ altered_body = deployment_body + (" " if alteration == "whitespace" else "changed")
+ # Even a whitespace change is custom; equality is exact, not normalized.
+ response = await lightweight_admin_client.put(
+ url, json={"content_template": altered_body}, headers=headers
+ )
+ assert response.status_code == 400, response.text
+ assert fs.agfs._files[path] == original
+ corrupted = yaml.safe_load(original)
+ corrupted["content_template"] = altered_body
+ corrupted["_account_content_template"] = False
+ corrupted["deployment_content_template"] = altered_body
+ fs.agfs._files[path] = yaml.safe_dump(corrupted).encode()
+ with pytest.raises(FailedPreconditionError):
+ await resolve_account_memory_registry(fs, account_id, defaults)
+ # Management reads remain available for recovery; no unsafe body is rendered.
+ assert (await lightweight_admin_client.get(url, headers=headers)).status_code == 200
+
+
+async def test_account_memory_templates_recheck_trust_after_deployment_change(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ from openviking_cli.exceptions import FailedPreconditionError
+
+ account_id, headers = template_account
+ defaults = MemoryTypeRegistry()
+ old_body = "{{ summary | upper }}"
+ defaults.get("events").content_template = old_body
+ monkeypatch.setattr("openviking.server.routers.admin.get_default_registry", lambda: defaults)
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/events"
+ assert (await lightweight_admin_client.put(url, json={}, headers=headers)).status_code == 200
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ old_snapshot = await resolve_account_memory_registry(fs, account_id, defaults)
+ defaults.get("events").content_template = "# {{ summary }}"
+ with pytest.raises(FailedPreconditionError):
+ await resolve_account_memory_registry(fs, account_id, defaults)
+ # Already-started extractions keep their snapshot, not a mutable defaults view.
+ assert old_snapshot.get("events").content_template == old_body
+ assert old_snapshot.get("events")._account_content_template is False
+ response = await lightweight_admin_client.put(
+ url, json={"description": "Use current defaults"}, headers=headers
+ )
+ assert response.status_code == 200, response.text
+ new_snapshot = await resolve_account_memory_registry(fs, account_id, defaults)
+ assert new_snapshot.get("events").content_template == "# {{ summary }}"
+ assert new_snapshot.get("events")._account_content_template is False
+
+
+async def test_account_memory_templates_old_content_can_be_read_replaced_and_reset(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ from openviking_cli.exceptions import FailedPreconditionError
+
+ account_id, headers = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/events"
+ path = account_memory_template_path(account_id, "events")
+ assert (await lightweight_admin_client.put(url, json={}, headers=headers)).status_code == 200
+ legacy = yaml.safe_load(fs.agfs._files[path])
+ legacy["content_template"] = "{{ summary | upper }}"
+ raw = yaml.safe_dump(legacy).encode()
+ for operation in ("PUT", "DELETE"):
+ fs.agfs._files[path] = raw
+ response = await lightweight_admin_client.get(url, headers=headers)
+ assert response.status_code == 200
+ assert (
+ response.json()["result"]["effective"]["content_template"] == legacy["content_template"]
+ )
+ with pytest.raises(FailedPreconditionError):
+ await resolve_account_memory_registry(fs, account_id, MemoryTypeRegistry())
+ response = await lightweight_admin_client.request(
+ operation,
+ url,
+ headers=headers,
+ **(
+ {"json": {"content_template": "{{ summary.upper() }}"}}
+ if operation == "PUT"
+ else {}
+ ),
+ )
+ assert response.status_code == 200, response.text
+ assert fs.agfs._files[path + ".backup"] == raw
+
+
+ "memory_type", ["profile", "events", "preferences", "entities", "soul", "identity"]
+)
+async def test_account_memory_templates_locked_fields_cannot_be_modified(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ memory_type,
+):
+ client = lightweight_admin_client
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}"
+ active = await client.put(url, json={"description": "Active policy"}, headers=headers)
+ assert active.status_code == 200, active.text
+ defaults = active.json()["result"]["defaults"]
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ original = dict(fs.agfs._files)
+ editable = {"description", "fields"}
+ if memory_type in {"events", "soul", "identity"}:
+ editable.add("content_template")
+ invalid = [
+ {key: None if value is not None else "changed"}
+ for key, value in defaults.items()
+ if key not in editable
+ ]
+ invalid.extend(
+ [
+ {"unknown": "ignored?"},
+ {"Description": "wrong key"},
+ {"_updated_at": "forged"},
+ {"_account_content_template": False},
+ {"deployment_content_template": "forged"},
+ {"enabled": 1},
+ {"fields": [{"name": "renamed_field", "description": "changed"}]},
+ {"description": None},
+ {"description": " \n"},
+ {"fields": [None]},
+ ]
+ )
+ for field in defaults["fields"]:
+ invalid.extend(
+ {"fields": [{"name": field["name"], key: None if value is not None else "changed"}]}
+ for key, value in field.items()
+ if key not in {"name", "description"}
+ )
+ invalid.extend(
+ [
+ {"fields": [{"name": field["name"], "unknown": "ignored?"}]},
+ {"fields": [{"name": field["name"], "description": ""}]},
+ {"fields": [{"name": field["name"]}, {"name": field["name"]}]},
+ ]
+ )
+ if memory_type == "events":
+ invalid.extend(
+ {"fields": [{"name": name, "description": "changed"}]} for name in ("goal", "ranges")
+ )
+ if memory_type in {"events", "soul", "identity"}:
+ invalid.extend([{"content_template": None}, {"content_template": " "}])
+ for body in invalid:
+ response = await client.put(url, json=body, headers=headers)
+ assert response.status_code == 400, (memory_type, body, response.text)
+ assert response.json()["error"]["code"] == "INVALID_ARGUMENT"
+ assert fs.agfs._files == original
+ # Partial field lists are updates by name, never a way to remove locked fields.
+ response = await client.put(url, json={"fields": []}, headers=headers)
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["effective"]["fields"] == defaults["fields"]
+ response = await client.put(
+ url, json={"fields": list(reversed(defaults["fields"]))}, headers=headers
+ )
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["effective"]["fields"] == defaults["fields"]
+
+
[email protected]("memory_type", ["experiences", "cases", "trajectories"])
+async def test_account_memory_templates_unexposed_types_rejected(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ memory_type,
+):
+ account_id, headers = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ original = dict(fs.agfs._files)
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/{memory_type}"
+ for method in ("GET", "PUT", "DELETE"):
+ response = await lightweight_admin_client.request(
+ method,
+ url,
+ headers=headers,
+ **({"json": {"description": "New"}} if method == "PUT" else {}),
+ )
+ assert response.status_code == 400, response.text
+ assert fs.agfs._files == original
+
+
+async def test_account_memory_templates_permissions_and_isolation(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ client = lightweight_admin_client
+ account_id, admin_headers = template_account
+ other = _uid()
+ created = await client.post(
+ "/api/v1/admin/accounts",
+ json={"account_id": other, "admin_user_id": "alice"},
+ headers=root_headers(),
+ )
+ assert created.status_code == 200
+ user = await client.post(
+ f"/api/v1/admin/accounts/{account_id}/users", json={"user_id": "bob"}, headers=admin_headers
+ )
+ assert user.status_code == 200
+ user_headers = {"X-API-Key": user.json()["result"]["user_key"]}
+ for method in ("GET", "PUT", "DELETE"):
+ body = {"json": {"description": "custom"}} if method == "PUT" else {}
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ assert (await client.request(method, url, headers=user_headers, **body)).status_code == 403
+ other_url = f"/api/v1/admin/accounts/{other}/memory-templates/profile"
+ assert (
+ await client.request(method, other_url, headers=admin_headers, **body)
+ ).status_code == 403
+ missing_url = "/api/v1/admin/accounts/missing-account/memory-templates/profile"
+ assert (
+ await client.request(method, missing_url, headers=root_headers(), **body)
+ ).status_code == 404
+ assert (
+ await client.request(
+ method, url.replace("/profile", "/missing-template"), headers=admin_headers, **body
+ )
+ ).status_code == 404
+ root = f"/api/v1/admin/accounts/{account_id}/memory-templates"
+ assert (await client.get(root, headers=user_headers)).status_code == 403
+ for memory_type in ("profile", "events"):
+ assert (
+ await client.put(
+ f"{root}/{memory_type}", json={"description": memory_type}, headers=root_headers()
+ )
+ ).status_code == 200
+ await client.delete(f"{root}/profile", headers=admin_headers)
+ assert (await client.get(f"{root}/events", headers=admin_headers)).json()["result"][
+ "effective"
+ ]["description"] == "events"
+ other_result = await client.get(
+ f"/api/v1/admin/accounts/{other}/memory-templates", headers=root_headers()
+ )
+ assert all(
+ item["status"] == "system_default" for item in other_result.json()["result"]["templates"]
+ )
+
+
[email protected]("merge", [False, True], ids=["extraction", "patch-merge"])
[email protected]("output_format", ["python", "json"])
+ "marker",
+ ["{{ language.upper() }}", "{% if language == 'en' %}EN{% else %}OTHER{% endif %}"],
+ ids=["safe-method", "safe-condition"],
+)
+async def test_account_memory_templates_reach_live_prompts(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ merge,
+ output_format,
+ marker,
+ monkeypatch,
+):
+ monkeypatch.setattr(get_openviking_config().memory, "extraction_output_format", output_format)
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ registry = MemoryTypeRegistry()
+ base_description = registry.get("profile").description
+
+ async def prompt_for(account, user, peer=None):
+ snapshot = await resolve_account_memory_registry(fs, account, registry)
+ ctx = RequestContext(user=UserIdentifier(account, user), role=Role.USER, actor_peer_id=peer)
+ if merge:
+ provider = PatchMergeContextProvider(
+ memory_type="profile", patches=[], memory_registry=snapshot
+ )
+ else:
+ provider = SessionExtractContextProvider(
+ messages=[], ctx=ctx, viking_fs=fs, memory_registry=snapshot
+ )
+ provider._output_language = "en"
+ provider.prefetch = AsyncMock(return_value=[])
+ vlm = Mock(
+ model="test-memory-templates",
+ get_completion_async=AsyncMock(
+ return_value="sdk.commit()" if output_format == "python" else '{"delete_ids":[]}'
+ ),
+ )
+ isolation = MemoryIsolationHandler(
+ ctx,
+ provider.get_extract_context(),
+ allowed_memory_types={"profile"},
+ allowed_peer_ids={peer} if peer else None,
+ )
+ isolation.prepare_messages()
+ provider._isolation_handler = isolation
+ loop = ExtractLoop(
+ vlm=vlm, viking_fs=fs, ctx=ctx, context_provider=provider, isolation_handler=isolation
+ )
+ operations, _ = await loop.run()
+ assert not operations.has_errors()
+ return vlm.get_completion_async.await_args.kwargs["messages"][0]["content"]
+
+ initial = await prompt_for(account_id, "alice")
+ # Account descriptions render through the same restricted schema path.
+ body = {
+ "description": "CUSTOM_ACCOUNT_SCOPE " + marker,
+ "fields": [
+ {
+ "name": "content",
+ "description": "ACCOUNT_FIELD " + marker + " {{ language }}",
+ }
+ ],
+ }
+ assert (await lightweight_admin_client.put(url, json=body, headers=headers)).status_code == 200
+ for user, peer in (("alice", None), ("bob", None), ("bob", "customer")):
+ prompt = await prompt_for(account_id, user, peer)
+ assert "CUSTOM_ACCOUNT_SCOPE EN" in prompt
+ # Preserve the Python protocol's existing static field contract. This
+ # change does not add a language context to that separate path.
+ expected_field = (
+ body["fields"][0]["description"]
+ if output_format == "python"
+ else "ACCOUNT_FIELD EN en"
+ )
+ assert expected_field in prompt
+ assert "CUSTOM_ACCOUNT_SCOPE" not in await prompt_for("other-account", "alice")
+ assert registry.get("profile").description == base_description
+ assert (await lightweight_admin_client.delete(url, headers=headers)).status_code == 200
+ assert await prompt_for(account_id, "alice") == initial
+
+
+async def test_account_memory_templates_commit_keeps_snapshot_through_file_write(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ from openviking.message import Message, TextPart
+ from openviking.session.compressor_v3 import SessionCompressorV3
+ from openviking.session.memory.dataclass import ResolvedOperation, ResolvedOperations
+ from openviking.session.memory.streaming_memory_updater import (
+ StreamingMemoryUpdater,
+ StreamingMemoryUpdaterConfig,
+ )
+ from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+
+ account_id, headers = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/soul"
+ template = {
+ "description": "ACCOUNT_DESCRIPTION",
+ "content_template": "# OLD_TEMPLATE\n{{ core_truths }}",
+ "fields": [{"name": "core_truths", "description": "Business core values"}],
+ }
+ assert (
+ await lightweight_admin_client.put(url, json=template, headers=headers)
+ ).status_code == 200
+ for module in (
+ "openviking.session.compressor_v3",
+ "openviking.session.memory.memory_updater",
+ "openviking.session.memory.streaming_memory_updater",
+ "openviking.storage.viking_fs",
+ ):
+ monkeypatch.setattr(f"{module}.get_viking_fs", lambda: fs)
+ initialized = []
+
+ async def initialize(registry, ctx, allowed_memory_types=None):
+ initialized.append(registry.get("soul").filename_template)
+
+ monkeypatch.setattr(MemoryTypeRegistry, "initialize_memory_files", initialize)
+ # Deliberately retain a cached deployment registry: request snapshots must win.
+ updater = StreamingMemoryUpdater(
+ registry=MemoryTypeRegistry(),
+ config=StreamingMemoryUpdaterConfig(max_operations_per_update=1),
+ )
+ monkeypatch.setattr(
+ "openviking.session.compressor_v3.get_streaming_memory_updater",
+ AsyncMock(return_value=updater),
+ )
+ ctx = RequestContext(user=UserIdentifier(account_id, "alice"), role=Role.USER)
+ uri = "viking://user/alice/memories/soul.md"
+
+ def orchestrator(**kwargs):
+ provider = kwargs["context_provider"]
+ assert provider.get_memory_schemas(ctx)[0].description == "ACCOUNT_DESCRIPTION"
+
+ async def run():
+ # A publish during the LLM call must not switch the writer's template.
+ changed = {**template, "content_template": "# NEW_TEMPLATE\n{{ core_truths }}"}
+ assert (
+ await lightweight_admin_client.put(url, json=changed, headers=headers)
+ ).status_code == 200
+ return ResolvedOperations(
+ delete_file_contents=[],
+ errors=[],
+ upsert_operations=[
+ ResolvedOperation(
+ memory_type="soul",
+ uris=[uri],
+ memory_fields={"core_truths": "Business fact"},
+ )
+ ],
+ ), []
+
+ return Mock(run=run)
+
+ compressor = SessionCompressorV3(vikingdb=None)
+ monkeypatch.setattr(compressor, "_get_or_create_react", orchestrator)
+ try:
+ await compressor._extract_user_memories(
+ messages=[Message(id="m1", role="user", parts=[TextPart("Business fact")])],
+ ctx=ctx,
+ allowed_memory_types={"soul"},
+ )
+ finally:
+ await updater.close()
+ assert initialized == ["soul.md"]
+ content = MemoryFileUtils.read(fs.files[uri], uri=uri).content
+ assert "# OLD_TEMPLATE" in content and "Business fact" in content
+ assert "# NEW_TEMPLATE" not in content
+
+
+async def test_account_memory_templates_write_failure_preserves_active_configuration(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ client = lightweight_admin_client
+ assert (
+ await client.put(url, json={"description": "Active"}, headers=headers)
+ ).status_code == 200
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ original = fs.agfs._files[path]
+ write = fs.agfs.write
+ failed = False
+
+ def fail_once(target, content, **kwargs):
+ nonlocal failed
+ if target.startswith(path + ".") and target.endswith(".tmp") and not failed:
+ failed = True
+ fs.agfs._files[target] = b"partial"
+ raise OSError("simulated write failure")
+ return write(target, content, **kwargs)
+
+ monkeypatch.setattr(fs.agfs, "write", fail_once)
+ with pytest.raises(OSError, match="simulated write failure"):
+ await client.put(url, json={"description": "Unpublished"}, headers=headers)
+ assert fs.agfs._files[path] == original
+ assert (await client.get(url, headers=headers)).json()["result"]["effective"][
+ "description"
+ ] == "Active"
+
+
+def template_path_lock(
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, _ = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ lock = threading.Lock()
+
+ def acquire(ctx, target, timeout_secs=0, owner_lease_ref=None):
+ from openviking.storage.errors import LockAcquisitionError
+
+ assert target == path
+ assert ctx["account_id"] == account_id
+ if not lock.acquire(timeout=timeout_secs):
+ raise LockAcquisitionError("publication in progress")
+ return {"lease_ref": "publication-test"}
+
+ def release(ctx, lease):
+ lock.release()
+
+ monkeypatch.setattr(fs.agfs, "pathlock_acquire_exact", acquire)
+ monkeypatch.setattr(fs.agfs, "pathlock_release", release)
+ return lock
+
+
+async def test_account_memory_templates_concurrent_publications_keep_both_types(
+ lightweight_admin_client,
+ template_account,
+):
+ account_id, headers = template_account
+ root = f"/api/v1/admin/accounts/{account_id}/memory-templates"
+ responses = await asyncio.gather(
+ lightweight_admin_client.put(
+ f"{root}/profile", json={"description": "Profile override"}, headers=headers
+ ),
+ lightweight_admin_client.put(
+ f"{root}/events", json={"description": "Events override"}, headers=headers
+ ),
+ )
+ assert [response.status_code for response in responses] == [200, 200]
+ result = (await lightweight_admin_client.get(root, headers=headers)).json()["result"]
+ effective = {item["memory_type"]: item["effective"] for item in result["templates"]}
+ assert effective["profile"]["description"] == "Profile override"
+ assert effective["events"]["description"] == "Events override"
+
+
+async def test_account_memory_templates_read_does_not_wait_for_publication(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ template_path_lock,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ client = lightweight_admin_client
+ assert (
+ await client.put(url, json={"description": "Active"}, headers=headers)
+ ).status_code == 200
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ acquiring = threading.Event()
+ acquire = fs.agfs.pathlock_acquire_exact
+
+ def observe_acquire(*args, **kwargs):
+ acquiring.set()
+ return acquire(*args, **kwargs)
+
+ monkeypatch.setattr(fs.agfs, "pathlock_acquire_exact", observe_acquire)
+ with template_path_lock:
+ # A writer may be preparing a partial staging file, but the active path
+ # remains a complete version and readers never request its lock.
+ fs.agfs._files[path + ".test.tmp"] = b"partial"
+ response = await asyncio.wait_for(client.get(url, headers=headers), timeout=1)
+ assert not acquiring.is_set()
+ assert response.status_code == 200, response.text
+ assert response.json()["result"]["effective"]["description"] == "Active"
+
+
+async def test_account_memory_templates_reject_oversized_serialized_config(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+ monkeypatch,
+):
+ account_id, headers = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ original = dict(fs.agfs._files)
+ monkeypatch.setattr("openviking.session.memory.account_templates._MAX_CONFIG_BYTES", 100)
+ response = await lightweight_admin_client.put(
+ f"/api/v1/admin/accounts/{account_id}/memory-templates/profile",
+ json={"description": "A valid description"},
+ headers=headers,
+ )
+ assert response.status_code == 400, response.text
+ assert fs.agfs._files == original
+
+
+async def test_account_memory_templates_corrupt_storage_is_not_overwritten(
+ lightweight_admin_client,
+ lightweight_admin_app,
+ template_account,
+):
+ account_id, headers = template_account
+ fs = lightweight_admin_app.state.fake_service.viking_fs
+ path = account_memory_template_path(account_id, "profile")
+ fs.agfs._files[path] = b'{"invalid-json"'
+ original = dict(fs.agfs._files)
+ url = f"/api/v1/admin/accounts/{account_id}/memory-templates/profile"
+ for method in ("GET", "PUT", "DELETE"):
+ response = await lightweight_admin_client.request(
+ method,
+ url,
+ headers=headers,
+ **({"json": {"description": "New"}} if method == "PUT" else {}),
+ )
+ assert response.status_code == 412, response.text
+ assert response.json()["error"]["code"] == "FAILED_PRECONDITION"
+ assert fs.agfs._files == original
+
+
async def test_create_account(admin_client: httpx.AsyncClient, admin_service: OpenVikingService):
"""ROOT can create an account with first admin."""
acct = _uid()
diff --git a/tests/session/memory/test_account_descriptions.py b/tests/session/memory/test_account_descriptions.py
new file mode 100644
index 000000000..8203b8da5
--- /dev/null
+++ b/tests/session/memory/test_account_descriptions.py
@@ -0,0 +1,250 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Deployment and account descriptions share one restricted Jinja contract."""
+
+import pytest
+
+from openviking.session.memory.account_templates import (
+ EDITABLE_MEMORY_TEMPLATE_FIELDS,
+ _complete_template,
+ _parse_template,
+ _validate_template,
+ memory_template_data,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.schema_model_generator import (
+ SchemaModelGenerator,
+ SchemaPromptGenerator,
+)
+from openviking.session.memory.utils.description_template import (
+ MAX_DESCRIPTION_CHARS,
+ MAX_DESCRIPTION_OUTPUT_BYTES,
+ DescriptionTemplateError,
+ render_description_template,
+ validate_description_template,
+)
+
+
+ ("generator_type", "plain_expected", "template_expected"),
+ [
+ (SchemaModelGenerator, " plain\n", " EN "),
+ (SchemaPromptGenerator, "plain", "EN"),
+ ],
+)
+def test_generators_render_description_strings(generator_type, plain_expected, template_expected):
+ generator = generator_type([], template_context={"language": "en"})
+
+ assert generator._render_description(" plain\n") == plain_expected
+ assert generator._render_description(" {{ language.upper() }} ") == template_expected
+ assert generator._render_description("") == ""
+ with pytest.raises(DescriptionTemplateError):
+ generator._render_description("{{ language | upper }}")
+
+
[email protected]("memory_type", EDITABLE_MEMORY_TEMPLATE_FIELDS)
[email protected]("origin", ["deployment", "account"])
+ ("text", "expected"),
+ [
+ ("Plain instructions", "Plain instructions"),
+ ("{{ language }}", "en"),
+ (
+ "{% if language == 'en' %}English{% elif language == 'ja' %}日本語{% else %}中文{% endif %}",
+ "English",
+ ),
+ ("{{ language.strip().upper().lower() }}", "en"),
+ ("{% set label = language.upper() %}{{ label }}", "EN"),
+ (
+ "{% for title, value in [('Use', language), ('Also', 'dates')] %}{{ loop.index }} {{ title }} {{ value }};{% endfor %}",
+ "1 Use en;2 Also dates;",
+ ),
+ (
+ "{% if language is defined and language is string and language is not none %}{{ language }}{% endif %}",
+ "en",
+ ),
+ ],
+)
+def test_descriptions_render_identically_in_all_schema_prompts(memory_type, origin, text, expected):
+ defaults = memory_template_data(MemoryTypeRegistry().get(memory_type))
+ editable = EDITABLE_MEMORY_TEMPLATE_FIELDS[memory_type]
+ supplied = {
+ "description": "TYPE: " + text,
+ "fields": [{"name": name, "description": name + ": " + text} for name in editable],
+ }
+ data = _complete_template(defaults, supplied, memory_type)
+ if origin == "deployment":
+ schema = MemoryTypeRegistry(load_schemas=False)._parse_memory_type(data)
+ else:
+ schema = _validate_template(data, memory_type, deployment_defaults=defaults)
+ schema = schema.model_copy(deep=True)
+ assert not hasattr(schema, "_account_description")
+ assert "_account_description" not in memory_template_data(schema)
+ assert schema.description == supplied["description"]
+
+ generator = SchemaModelGenerator([schema], template_context={"language": "en"})
+ operations = generator.create_structured_operations_model()
+ model = generator.create_flat_data_model(schema)
+ prompts = SchemaPromptGenerator([schema], template_context={"language": "en"})
+ type_prompt = prompts.generate_type_descriptions()
+ field_prompt = prompts.generate_field_descriptions(memory_type)
+ assert "TYPE: " + expected in operations.model_fields[memory_type].description
+ assert "TYPE: " + expected in type_prompt
+ for field in schema.fields:
+ if field.name in editable:
+ assert not hasattr(field, "_account_description")
+ assert "_account_description" not in field.model_dump()
+ assert field.name + ": " + expected in model.model_fields[field.name].description
+ assert field.name + ": " + expected in type_prompt
+ assert field.name + ": " + expected in field_prompt
+
+
[email protected]("request_kind", ["empty", "roundtrip", "type_only", "field_only"])
+def test_unchanged_deployment_descriptions_keep_existing_language_rendering(request_kind):
+ deployment = MemoryTypeRegistry().get("profile")
+ deployment.description = "TYPE {{ language.upper() }}"
+ deployment.fields[0].description = "FIELD {{ language.upper() }}"
+ defaults = memory_template_data(deployment)
+ supplied = {
+ "empty": {},
+ "roundtrip": defaults,
+ "type_only": {"description": "CUSTOM {{ language }}"},
+ "field_only": {"fields": [{"name": "content", "description": "CUSTOM {{ language }}"}]},
+ }[request_kind]
+ data = _complete_template(defaults, supplied, "profile")
+ schema = _validate_template(data, "profile", deployment_defaults=defaults)
+ generator = SchemaModelGenerator([schema], template_context={"language": "en"})
+ operations = generator.create_structured_operations_model()
+ field_description = generator.create_flat_data_model(schema).model_fields["content"].description
+ type_description = operations.model_fields["profile"].description
+ assert ("CUSTOM en" if request_kind == "type_only" else "TYPE EN") in type_description
+ assert ("CUSTOM en" if request_kind == "field_only" else "FIELD EN") in field_description
+ assert not hasattr(deployment, "_account_description")
+ assert not hasattr(deployment.fields[0], "_account_description")
+
+
[email protected]("field", ["description", "fields.content.description"])
+ "text",
+ [
+ "{{ cycler.__init__.__globals__.__builtins__.len('harmless') }}",
+ "{% for n in range(3) %}x{% endfor %}",
+ "{% include 'not_a_file' %}",
+ "literal {{ and {% unclosed",
+ "{{ language | upper }}",
+ "{{ summary }}",
+ "{{ extract_context.get_year(ranges) }}",
+ "{{ language[0] }}",
+ "{{ language.__class__ }}",
+ "{{ language.upper }}",
+ "{{ language.strip('x') }}",
+ "{{ language.replace('en', 'zh') }}",
+ "{{ language * 1000000000 }}",
+ "{% set language = 'override' %}{{ language }}",
+ "{% set loop = 'override' %}{{ loop }}",
+ "{% for n in language %}{{ n }}{% endfor %}",
+ "{% for n in [1] %}{% for m in [2] %}x{% endfor %}{% endfor %}",
+ "{% for n in [" + ",".join(["1"] * 33) + "] %}x{% endfor %}",
+ ],
+)
+def test_unsupported_descriptions_rejected_on_publish_load_and_render(text, field):
+ import yaml
+
+ deployment = MemoryTypeRegistry().get("profile")
+ defaults = memory_template_data(deployment)
+ data = memory_template_data(deployment)
+ supplied = (
+ {"description": text}
+ if field == "description"
+ else {"fields": [{"name": "content", "description": text}]}
+ )
+ with pytest.raises(DescriptionTemplateError) as caught:
+ _complete_template(defaults, supplied, "profile")
+ assert caught.value.field == field
+ # Old overrides remain readable/resettable but cannot bypass extraction
+ # validation, even if they contain obsolete client trust flags.
+ if field == "description":
+ data["description"] = text
+ else:
+ data["fields"][0]["description"] = text
+ data["_account_description"] = False
+ data["fields"][0]["_account_description"] = False
+ raw = yaml.safe_dump(data).encode()
+ parsed = _parse_template(raw, "profile")
+ with pytest.raises(DescriptionTemplateError):
+ _validate_template(parsed, "profile", deployment_defaults=defaults)
+ with pytest.raises(DescriptionTemplateError):
+ render_description_template(text, {"language": "en"})
+ # Deployment schemas cannot bypass the same policy by avoiding the Account loader.
+ schema = MemoryTypeRegistry(load_schemas=False)._parse_memory_type(data)
+ with pytest.raises(DescriptionTemplateError):
+ SchemaModelGenerator([schema], {"language": "en"}).create_structured_operations_model()
+ with pytest.raises(DescriptionTemplateError):
+ SchemaPromptGenerator([schema], {"language": "en"}).generate_type_descriptions()
+
+
+def test_deployment_change_does_not_change_old_description_rendering():
+ deployment = MemoryTypeRegistry().get("profile")
+ deployment.description = "TYPE {{ language.upper() }}"
+ deployment.fields[0].description = "FIELD {{ language.upper() }}"
+ stored = memory_template_data(deployment)
+ old = _validate_template(stored, "profile", deployment_defaults=stored)
+ deployment.description = "NEW TYPE {{ language }}"
+ deployment.fields[0].description = "NEW FIELD {{ language }}"
+ new = _validate_template(
+ stored, "profile", deployment_defaults=memory_template_data(deployment)
+ )
+
+ old_prompt = SchemaPromptGenerator([old], {"language": "en"}).generate_type_descriptions()
+ new_prompt = SchemaPromptGenerator([new], {"language": "en"}).generate_type_descriptions()
+ assert "TYPE EN" in old_prompt and "FIELD EN" in old_prompt
+ assert old_prompt == new_prompt
+
+
+def test_missing_context_keeps_existing_undefined_behavior_and_does_not_recurse():
+ assert render_description_template("{{ language }}", {}) == ""
+ assert render_description_template("{{ language or 'unspecified' }}", {}) == "unspecified"
+ assert (
+ render_description_template("{% if language is undefined %}missing{% endif %}", {})
+ == "missing"
+ )
+ assert (
+ render_description_template("{{ language }}", {"language": "{{ unknown }}"})
+ == "{{ unknown }}"
+ )
+ assert render_description_template(" plain\n", {}, strip=False) == " plain\n"
+ assert render_description_template(" plain ", {}) == "plain"
+ assert render_description_template("", {}) == ""
+
+
[email protected]("character", ["a", "中", "😀"])
+def test_description_limits(character):
+ text = character * MAX_DESCRIPTION_CHARS
+ assert render_description_template(text, {}) == text
+ with pytest.raises(DescriptionTemplateError, match="template_too_large"):
+ validate_description_template(text + character)
+ with pytest.raises(DescriptionTemplateError, match="output_too_large"):
+ render_description_template(
+ "{{ language }}{{ language }}", {"language": "x" * MAX_DESCRIPTION_OUTPUT_BYTES}
+ )
+ with pytest.raises(DescriptionTemplateError, match="template_too_complex"):
+ validate_description_template("{{ language }}" * 2050)
+
+
+def test_context_objects_never_reach_the_sandbox():
+ class HostileString(str):
+ def upper(self):
+ pytest.fail("Untrusted method was called")
+
+ for value in (HostileString("en"), {"upper": lambda: pytest.fail("Called mapping")}, object()):
+ with pytest.raises(DescriptionTemplateError, match="invalid_context_value"):
+ render_description_template("{{ language.upper() }}", {"language": value})
+
+
+def test_all_deployment_descriptions_pass_restricted_rendering():
+ schemas = MemoryTypeRegistry().list_all(include_disabled=True)
+ for language in ("en", "zh-CN", "ja"):
+ generator = SchemaModelGenerator(schemas, template_context={"language": language})
+ generator.generate_all_models()
+ generator.create_structured_operations_model()
+ SchemaPromptGenerator(schemas, {"language": language}).generate_type_descriptions()
diff --git a/tests/session/memory/test_account_template_locking.py b/tests/session/memory/test_account_template_locking.py
new file mode 100644
index 000000000..303102fc0
--- /dev/null
+++ b/tests/session/memory/test_account_template_locking.py
@@ -0,0 +1,465 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Template lock contention must not starve storage I/O in the default executor."""
+
+import asyncio
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from types import SimpleNamespace
+
+import pytest
+
+from openviking.pyagfs import AGFSNotFoundError
+from openviking.session.memory.account_templates import (
+ account_memory_template_path,
+ read_account_memory_template,
+ resolve_account_memory_registry,
+ update_account_memory_template,
+)
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.storage.errors import LockAcquisitionError, ResourceBusyError
+
+
+class LockingAGFS:
+ """Blocking sync backend, including the legacy long-wait failure mode."""
+
+ def __init__(self):
+ self.files = {}
+ self.locks = {}
+ self.leases = {}
+ self.timeouts = []
+
+ def pathlock_acquire_exact(self, ctx, path, timeout_secs=0, owner_lease_ref=None):
+ return self.pathlock_acquire_exact_batch(ctx, [path], timeout_secs, owner_lease_ref)
+
+ def pathlock_acquire_exact_batch(self, ctx, paths, timeout_secs=0, owner_lease_ref=None):
+ self.timeouts.append(timeout_secs)
+ held = []
+ for path in sorted(paths):
+ lock = self.locks.setdefault(path, threading.Lock())
+ # Bound failures on the old implementation so the regression is fast.
+ if not lock.acquire(timeout=min(timeout_secs, 0.15)):
+ for previous in held:
+ self.locks[previous].release()
+ raise LockAcquisitionError("test lock conflict")
+ held.append(path)
+ lease = {"lease_ref": paths[0], "paths": held}
+ self.leases[paths[0]] = lease
+ return lease
+
+ def pathlock_release(self, ctx, lease):
+ path = lease["lease_ref"]
+ assert ctx["account_id"] == "locking-test"
+ assert self.leases.pop(path) == lease
+ for locked_path in lease["paths"]:
+ self.locks[locked_path].release()
+
+ def read(self, path, **kwargs):
+ if path not in self.files:
+ raise AGFSNotFoundError(path)
+ return self.files[path]
+
+ def write(self, path, data, *, ctx):
+ if not path.endswith(".backup"):
+ assert path.endswith(".tmp"), "the active file must never be overwritten in place"
+ assert path in self.leases[ctx["lease_ref"]]["paths"]
+ self.files[path] = data
+
+ def mv(self, old_path, new_path, *, ctx):
+ held = self.leases[ctx["lease_ref"]]["paths"]
+ assert old_path in held and new_path in held
+ self.files[new_path] = self.files.pop(old_path)
+
+ def ensure_parent_dirs(self, path, **kwargs):
+ pass
+
+ def rm(self, path, *, ctx):
+ assert path in self.leases[ctx["lease_ref"]]["paths"]
+ self.files.pop(path, None)
+
+
[email protected]("workers", [1, 2])
+def test_template_readers_finish_with_a_small_default_executor(workers):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=workers))
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(read_account_memory_template(fs, "locking-test", "profile") for _ in range(8)),
+ return_exceptions=True,
+ ),
+ timeout=4,
+ )
+ assert results == [None] * 8
+ assert not agfs.leases
+ assert not agfs.timeouts, "readers must not acquire locks at all"
+
+ asyncio.run(run())
+
+
[email protected]("workers", [1, 2])
+def test_concurrent_template_writers_do_not_starve_the_lock_holder(workers):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=workers))
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": f"Writer {index}"}, registry
+ )
+ for index in range(8)
+ )
+ ),
+ timeout=3,
+ )
+ assert [item["description"] for item in results] == [
+ f"Writer {index}" for index in range(8)
+ ]
+ assert not agfs.leases
+ assert set(agfs.timeouts) == {0.0}
+ assert not any(path.endswith(".tmp") for path in agfs.files)
+
+ asyncio.run(run())
+
+
[email protected]("workers", [1, 2])
+def test_template_resolve_and_publish_share_a_small_executor(workers):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=workers))
+ await update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Before"}, registry
+ )
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(resolve_account_memory_registry(fs, "locking-test", registry) for _ in range(8)),
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "After"}, registry
+ ),
+ ),
+ timeout=4,
+ )
+ assert all(
+ result.get("profile").description in {"Before", "After"} for result in results[:-1]
+ )
+ assert results[-1]["description"] == "After"
+ assert not agfs.leases
+
+ asyncio.run(run())
+
+
+async def _wait_for_flag(flag):
+ async def wait():
+ while not flag.is_set():
+ await asyncio.sleep(0.001)
+
+ await asyncio.wait_for(wait(), timeout=2)
+
+
[email protected]("existing", [False, True], ids=["first-publication", "replacement"])
+def test_readers_never_see_a_partial_staging_file(monkeypatch, existing):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+ entered = threading.Event()
+ proceed = threading.Event()
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=2))
+ if existing:
+ await update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Before"}, registry
+ )
+ write = agfs.write
+
+ def slow_write(path, data, **kwargs):
+ if path.endswith(".tmp"):
+ agfs.files[path] = b"partial YAML"
+ entered.set()
+ assert proceed.wait(3)
+ return write(path, data, **kwargs)
+
+ monkeypatch.setattr(agfs, "write", slow_write)
+ writer = asyncio.create_task(
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "After"}, registry
+ )
+ )
+ try:
+ await _wait_for_flag(entered)
+ readers = await asyncio.wait_for(
+ asyncio.gather(
+ *(
+ read_account_memory_template(fs, "locking-test", "profile")
+ for _ in range(16)
+ )
+ ),
+ timeout=1,
+ )
+ assert all(
+ result["description"] == "Before" if existing else result is None
+ for result in readers
+ )
+ finally:
+ proceed.set()
+ await writer
+ assert (await read_account_memory_template(fs, "locking-test", "profile"))[
+ "description"
+ ] == "After"
+ assert not agfs.leases
+ assert not any(path.endswith(".tmp") for path in agfs.files)
+
+ asyncio.run(run())
+
+
[email protected]("phase", ["acquire", "write", "move", "release"])
+def test_cancelled_publication_drains_io_and_releases_leases(monkeypatch, phase):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+ entered = threading.Event()
+ proceed = threading.Event()
+ method = {
+ "acquire": "pathlock_acquire_exact_batch",
+ "write": "write",
+ "move": "mv",
+ "release": "pathlock_release",
+ }[phase]
+ original = getattr(agfs, method)
+
+ def blocked(*args, **kwargs):
+ result = original(*args, **kwargs) if phase != "release" else None
+ entered.set()
+ assert proceed.wait(3)
+ return original(*args, **kwargs) if phase == "release" else result
+
+ monkeypatch.setattr(agfs, method, blocked)
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=1))
+ writer = asyncio.create_task(
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Complete"}, registry
+ )
+ )
+ try:
+ await _wait_for_flag(entered)
+ writer.cancel()
+ await asyncio.sleep(0.01)
+ writer.cancel()
+ await asyncio.sleep(0.01)
+ assert not writer.done(), "cancellation must drain the in-flight native call"
+ assert agfs.leases, "do not release the lease before the worker finishes"
+ finally:
+ proceed.set()
+ with pytest.raises(asyncio.CancelledError):
+ await writer
+ assert not agfs.leases
+ assert all(not lock.locked() for lock in agfs.locks.values())
+ assert not any(path.endswith(".tmp") for path in agfs.files)
+ result = await read_account_memory_template(fs, "locking-test", "profile")
+ assert result is None if phase == "acquire" else result["description"] == "Complete"
+
+ asyncio.run(run())
+
+
[email protected]("cancel", [False, True], ids=["timeout", "cancel"])
+def test_waiting_writer_does_not_block_readers_or_leak_locks(monkeypatch, cancel):
+ import openviking.session.memory.account_templates as templates
+
+ monkeypatch.setattr(templates, "_TEMPLATE_LOCK_TIMEOUT_SECONDS", 0.05)
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+ path = account_memory_template_path("locking-test", "profile")
+ lock = threading.Lock()
+ agfs.locks[path] = lock
+
+ async def run():
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=1))
+ with lock:
+ writer = asyncio.create_task(
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Waiting"}, registry
+ )
+ )
+ while not agfs.timeouts:
+ await asyncio.sleep(0.001)
+ assert await read_account_memory_template(fs, "locking-test", "profile") is None
+ if cancel:
+ writer.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await writer
+ else:
+ with pytest.raises(ResourceBusyError) as exc:
+ await writer
+ assert exc.value.uri == path
+ assert exc.value.conflict_type == "memory_templates_busy"
+ assert agfs.timeouts and set(agfs.timeouts) == {0.0}
+ assert not agfs.leases
+ assert not agfs.files
+ assert all(not held.locked() for held in agfs.locks.values())
+
+ asyncio.run(run())
+
+
[email protected]("existing", [False, True])
[email protected]("failure", ["staging", "before-move", "after-move", "cleanup"])
+def test_publication_failures_never_overwrite_the_active_file(monkeypatch, existing, failure):
+ agfs = LockingAGFS()
+ fs = SimpleNamespace(agfs=agfs)
+ registry = MemoryTypeRegistry()
+ path = account_memory_template_path("locking-test", "profile")
+
+ async def run():
+ if existing:
+ await update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Before"}, registry
+ )
+ old = agfs.files.get(path)
+ write, move, remove = agfs.write, agfs.mv, agfs.rm
+
+ def faulty_write(target, data, **kwargs):
+ if failure == "staging" and target.endswith(".tmp"):
+ agfs.files[target] = b"partial"
+ raise OSError("staging failed")
+ return write(target, data, **kwargs)
+
+ def faulty_move(source, target, **kwargs):
+ if failure == "before-move":
+ raise OSError("publish failed")
+ if failure == "after-move":
+ # S3 CopyObject succeeded but deleting its source failed.
+ agfs.files[target] = agfs.files[source]
+ raise OSError("source cleanup failed")
+ return move(source, target, **kwargs)
+
+ def faulty_cleanup(target, **kwargs):
+ if failure in {"cleanup", "after-move"} and target.endswith(".tmp"):
+ raise OSError("cleanup failed")
+ return remove(target, **kwargs)
+
+ monkeypatch.setattr(agfs, "write", faulty_write)
+ monkeypatch.setattr(agfs, "mv", faulty_move)
+ monkeypatch.setattr(agfs, "rm", faulty_cleanup)
+ update = update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "After"}, registry
+ )
+ if failure in {"staging", "before-move"}:
+ with pytest.raises(OSError):
+ await update
+ assert agfs.files.get(path) == old
+ else:
+ assert (await update)["description"] == "After"
+ assert (await read_account_memory_template(fs, "locking-test", "profile"))[
+ "description"
+ ] == "After"
+ assert not agfs.leases
+ assert all(not held.locked() for held in agfs.locks.values())
+ if existing:
+ assert agfs.files[path + ".backup"] == old
+
+ asyncio.run(run())
+
+
[email protected]("workers", [None, 1], ids=["default-executor", "one-worker"])
[email protected]("encrypted", [False, True], ids=["plaintext", "encrypted"])
+def test_native_template_read_publish_and_reset(tmp_path, workers, encrypted):
+ from openviking.pyagfs import get_binding_client
+ from openviking.utils.agfs_utils import RagfsBindingConfig, mount_agfs_backend
+ from openviking_cli.utils.config.agfs_config import AGFSConfig
+
+ try:
+ client_type, _ = get_binding_client()
+ except ImportError:
+ pytest.skip("RAGFS native binding is not installed")
+ if not hasattr(client_type, "pathlock_acquire_exact_batch"):
+ pytest.skip("RAGFS native binding predates the current PathLock API")
+ config = RagfsBindingConfig(
+ agfs=AGFSConfig(path=str(tmp_path), backend="local"),
+ root_key=b"k" * 32 if encrypted else None,
+ provider_type=1 if encrypted else None,
+ )
+ native = client_type(None, config=config.to_binding_dict())
+ fs = SimpleNamespace(agfs=native)
+ registry = MemoryTypeRegistry()
+
+ async def run():
+ if workers is not None:
+ asyncio.get_running_loop().set_default_executor(ThreadPoolExecutor(max_workers=workers))
+ # Original B2 reproduction: no override, no writer, concurrent registry reads.
+ empty = await asyncio.wait_for(
+ asyncio.gather(
+ *(resolve_account_memory_registry(fs, "locking-test", registry) for _ in range(8))
+ ),
+ timeout=5,
+ )
+ assert all(
+ result.get("profile").description == registry.get("profile").description
+ for result in empty
+ )
+ await update_account_memory_template(
+ fs, "locking-test", "profile", {"description": "Before"}, registry
+ )
+ for index in range(3):
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(
+ read_account_memory_template(fs, "locking-test", "profile")
+ for _ in range(24)
+ ),
+ update_account_memory_template(
+ fs, "locking-test", "profile", {"description": f"Version {index}"}, registry
+ ),
+ ),
+ timeout=5,
+ )
+ expected_old = "Before" if index == 0 else f"Version {index - 1}"
+ assert all(
+ result["description"] in {expected_old, f"Version {index}"} for result in results
+ )
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(
+ update_account_memory_template(
+ fs,
+ "locking-test",
+ "profile",
+ {"description": f"Concurrent {index}"},
+ registry,
+ )
+ for index in range(4)
+ )
+ ),
+ timeout=5,
+ )
+ assert [result["description"] for result in results] == [
+ f"Concurrent {index}" for index in range(4)
+ ]
+ final = await read_account_memory_template(fs, "locking-test", "profile")
+ results = await asyncio.wait_for(
+ asyncio.gather(
+ *(read_account_memory_template(fs, "locking-test", "profile") for _ in range(24)),
+ update_account_memory_template(fs, "locking-test", "profile", None, registry),
+ ),
+ timeout=5,
+ )
+ assert all(
+ result is None or result["description"] == final["description"] for result in results
+ )
+ assert await read_account_memory_template(fs, "locking-test", "profile") is None
+
+ try:
+ mount_agfs_backend(native, config)
+ asyncio.run(run())
+ finally:
+ native.close()
diff --git a/tests/session/memory/test_content_template.py b/tests/session/memory/test_content_template.py
new file mode 100644
index 000000000..7b4dad5f7
--- /dev/null
+++ b/tests/session/memory/test_content_template.py
@@ -0,0 +1,387 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+
+from types import SimpleNamespace
+from unittest.mock import AsyncMock
+
+import pytest
+
+from openviking.message import Message, TextPart
+from openviking.session.memory.account_templates import (
+ _complete_template,
+ _validate_template,
+ memory_template_data,
+)
+from openviking.session.memory.dataclass import MemoryFile
+from openviking.session.memory.memory_type_registry import MemoryTypeRegistry
+from openviking.session.memory.memory_updater import ExtractContext
+from openviking.session.memory.utils.content_template import (
+ MAX_CONTENT_OUTPUT_BYTES,
+ MAX_CONTENT_TEMPLATE_BYTES,
+ ContentTemplateError,
+ render_content_template,
+ validate_content_template,
+)
+from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+from openviking.session.memory.utils.template_utils import TemplateUtils
+
+
[email protected]("memory_type", ["events", "soul", "identity"])
+def test_inherited_builtin_content_templates_keep_deployment_renderer(memory_type):
+ schema = MemoryTypeRegistry().get(memory_type)
+ complete = _complete_template(
+ memory_template_data(schema), {"description": "Account instructions"}, memory_type
+ )
+ inherited = _validate_template(
+ complete, memory_type, deployment_defaults=memory_template_data(schema)
+ )
+ assert inherited._account_content_template is False
+ values = {f.name: f.init_value or "" for f in schema.fields}
+ context = ExtractContext([])
+ rendered = MemoryFileUtils.write(
+ MemoryFile(memory_type=memory_type, extra_fields=values),
+ content_template=inherited.content_template,
+ extract_context=context,
+ account_content_template_type=(
+ inherited.memory_type if inherited._account_content_template else None
+ ),
+ )
+ assert MemoryFileUtils.read(rendered).content == TemplateUtils.render(
+ schema.content_template, values, context
+ )
+
+
[email protected]("resource_event", [False, True])
+def test_events_default_and_custom_render_real_context(resource_event):
+ text = "We agreed to launch on Monday."
+ if resource_event:
+ text = "## Resource Addition\nResource URI: viking://resources/guide\n"
+ context = ExtractContext(
+ [
+ Message(
+ id="m1", role="user", parts=[TextPart(text)], created_at="2026-09-07T08:00:00+00:00"
+ )
+ ]
+ )
+ values = {
+ "event_name": "launch",
+ "goal": "launch",
+ "summary": "Launch agreement",
+ "ranges": "0",
+ }
+ template = MemoryTypeRegistry().get("events").content_template
+ old = TemplateUtils.render(template, values, context)
+ rendered = MemoryFileUtils.write(
+ MemoryFile(memory_type="events", extra_fields=values),
+ content_template=template,
+ extract_context=context,
+ )
+ assert MemoryFileUtils.read(rendered).content == old
+ if resource_event:
+ assert "viking://resources/guide" in old
+ else:
+ assert "2026-09-07" in old and text in old
+ custom = "# {{ event_name }}\n{% set body = extract_context.get_resource_event_content(ranges, summary) %}{% if body %}{{ body }}{% else %}## Decision\n{{ summary }}{% endif %}"
+ result = render_content_template(custom, "events", values, context)
+ assert result.startswith("# launch")
+ assert ("viking://resources/guide" in result) == resource_event
+
+
+def test_content_template_if_set_for_and_string_methods():
+ template = """{% set heading = 'Business rules' %}
+# {{ heading }}
+{% for title, text in [('Values', core_truths), ('Limits', boundaries)] %}
+{% if text.strip() %}## {{ loop.index }}. {{ title }}
+{{ text.strip() }}{% endif %}
+{% endfor %}
+{% if vibe is defined and vibe %}{{ vibe.upper() }}{% else %}{{ continuity or 'pending' }}{% endif %}"""
+ output = render_content_template(
+ template, "soul", {"core_truths": " truth ", "boundaries": "limits"}
+ )
+ assert "## 1. Values\ntruth" in output and "## 2. Limits\nlimits" in output
+ assert "pending" in output
+
+
+ "template, expected",
+ [
+ ("{{ summary.upper() }}", "ABC"),
+ ("{{ summary.lower() }}", "abc"),
+ ("{{ summary.strip() }}", "AbC"),
+ ("{{ summary.strip().upper() }}", "ABC"),
+ ("{{ ' HeLLo '.strip().lower() }}", "hello"),
+ ("{% set text = summary %}{{ text.upper() }}", "ABC"),
+ ("{% if summary.strip().lower() == 'abc' %}match{% endif %}", "match"),
+ (
+ "{% for title, text in [('Title', summary)] %}{{ title.upper() }}: {{ text.strip() }}{% endfor %}",
+ "TITLE: AbC",
+ ),
+ ("{{ (summary or 'pending').upper() }}", "ABC"),
+ ],
+)
+def test_content_template_string_methods_match_deployment_syntax(template, expected):
+ fields = {"summary": " AbC "}
+ assert render_content_template(template, "events", fields) == expected
+ assert TemplateUtils.render(template, fields) == expected
+
+
+def test_content_template_string_methods_on_helper_results_and_empty_fields():
+ context = SimpleNamespace(get_event_content=lambda *args: " details ")
+ assert (
+ render_content_template(
+ "{{ extract_context.get_event_content(ranges, summary).strip().upper() }}",
+ "events",
+ {"ranges": "0"},
+ context,
+ )
+ == "DETAILS"
+ )
+ assert render_content_template("{{ summary.strip() or 'pending' }}", "events", {}) == "pending"
+
+
[email protected]("receiver_kind", ["object", "mapping", "str_subclass", "none", "int"])
+def test_content_template_rejects_same_named_methods_before_attribute_lookup(receiver_kind):
+ touched = []
+
+ class Impostor:
+ @property
+ def upper(self):
+ touched.append("property")
+ return lambda: "unsafe"
+
+ class StringSubclass(str):
+ def upper(self):
+ touched.append("override")
+ return "unsafe"
+
+ receivers = {
+ "object": Impostor(),
+ "mapping": {"upper": lambda: touched.append("mapping")},
+ "str_subclass": StringSubclass("text"),
+ "none": None,
+ "int": 1,
+ }
+ context = SimpleNamespace(get_event_content=lambda *args: receivers[receiver_kind])
+ with pytest.raises(ContentTemplateError, match="render_failed"):
+ render_content_template(
+ "{{ extract_context.get_event_content(ranges, summary).upper() }}",
+ "events",
+ {"ranges": "0"},
+ context,
+ )
+ assert not touched
+
+
+ "expression",
+ [
+ "summary | upper",
+ "summary | lower",
+ "summary | trim",
+ "summary | length",
+ "summary | default('pending', true)",
+ "summary.upper() | upper",
+ ],
+)
+def test_content_template_rejects_all_filter_syntax(expression):
+ template = "{{ " + expression + " }}"
+ with pytest.raises(ContentTemplateError, match="unsupported_filter"):
+ validate_content_template(template, "events")
+ with pytest.raises(ContentTemplateError, match="unsupported_filter"):
+ render_content_template(template, "events", {"summary": "text"})
+
+
+def test_events_builtin_template_keeps_original_date_fallback():
+ template = MemoryTypeRegistry().get("events").content_template
+ assert "ranges|default('')" in template
+ context = ExtractContext([])
+ output = TemplateUtils.render(template, {"summary": "Summary", "ranges": ""}, context)
+ # Preserve existing deployment behavior: default() handles undefined, not None.
+ assert "# None ChatLog:" in output
+
+
+ "template",
+ [
+ "{{ typo }}",
+ "{{ language }}",
+ "{{ user_space }}",
+ "{{ source_uri }}",
+ "{{ extract_context.messages }}",
+ "{{ extract_context }}",
+ "{{ extract_context.__class__ }}",
+ "{{ summary.__class__.__mro__ }}",
+ "{{ extract_context.read_message_ranges(ranges) }}",
+ "{{ extract_context.get_year }}",
+ "{{ extract_context['get_year'](ranges) }}",
+ "{{ summary.upper }}",
+ "{% set method = summary.upper %}{{ method() }}",
+ "{{ summary.upper('x') }}",
+ "{{ summary.strip('x') }}",
+ "{{ summary.strip(chars='x') }}",
+ "{{ summary.upper(*summary) }}",
+ "{{ summary.upper(**summary) }}",
+ "{{ summary.replace('a', 'b') }}",
+ "{{ summary.format() }}",
+ "{{ summary.strip().__class__ }}",
+ "{{ summary.upper.__self__ }}",
+ "{{ extract_context.upper() }}",
+ "{% for x in [1] %}{{ loop.upper() }}{% endfor %}",
+ "{{ cycler.__init__.__globals__ }}",
+ "{{ range(100) }}",
+ "{% include 'private.txt' %}",
+ "{% import 'private.txt' as x %}",
+ "{% macro x() %}hi{% endmacro %}{{ x() }}",
+ "{% set ranges = '0-999' %}",
+ "{{ summary | attr('__class__') }}",
+ "{{ summary | map('upper') }}",
+ "{{ 'x' * 999999999 }}",
+ "{{ 2 ** 100000 }}",
+ "{{ summary ~ summary }}",
+ "{% for x in summary %}x{% endfor %}",
+ "{% for x in [1] %}{% for y in [2] %}x{% endfor %}{% endfor %}",
+ "{% for x in [1] recursive %}x{% endfor %}",
+ "{% set x = [summary, summary] %}{{ x }}",
+ "{{ extract_context.get_event_content() }}",
+ "{{ extract_context.get_year('0-999999999') }}",
+ "{{ extract_context.get_year(ranges|default('0-999', true)) }}",
+ "{{ extract_context.get_year(ranges_str=ranges) }}",
+ "{{ extract_context.get_event_content(ranges, summary, 2) }}",
+ "{{ extract_context.get_event_content(ranges, summary, summary) }}",
+ "{% if summary %}",
+ ],
+)
+def test_content_template_rejects_unsupported_edits(template):
+ with pytest.raises(ContentTemplateError):
+ validate_content_template(template, "events")
+
+
[email protected]("memory_type", ["soul", "identity"])
+def test_content_template_rejects_other_types_fields_and_context(memory_type):
+ for template in ("{{ summary }}", "{{ extract_context.get_year(ranges) }}"):
+ with pytest.raises(ContentTemplateError):
+ validate_content_template(template, memory_type)
+
+
+def test_content_template_limits_and_runtime_failure_no_plain_fallback():
+ with pytest.raises(ContentTemplateError, match="template_too_large"):
+ validate_content_template("中" * (MAX_CONTENT_TEMPLATE_BYTES // 3 + 1), "soul")
+ with pytest.raises(ContentTemplateError, match="output_too_large"):
+ render_content_template(
+ "{{ core_truths }}{{ core_truths }}",
+ "soul",
+ {"core_truths": "a" * MAX_CONTENT_OUTPUT_BYTES},
+ )
+ mf = MemoryFile(
+ memory_type="events",
+ content="original body",
+ extra_fields={"summary": "summary", "ranges": "0"},
+ )
+ with pytest.raises(ContentTemplateError, match="render_failed"):
+ MemoryFileUtils.write(
+ mf,
+ content_template="{{ extract_context.get_year(ranges) }}",
+ account_content_template_type="events",
+ )
+ assert mf.content == "original body"
+ # No account override: existing deployment-owned templates retain their API.
+ assert "SUMMARY" in MemoryFileUtils.write(mf, content_template="{{ summary.upper() }}")
+
+
+def test_content_template_cannot_override_hidden_metadata():
+ with pytest.raises(ContentTemplateError, match="reserved_metadata"):
+ validate_content_template('<!-- MEMORY_FIELDS {"name":"changed"} -->', "identity")
+ with pytest.raises(ContentTemplateError, match="reserved_metadata"):
+ render_content_template(
+ "{{ introduction }}",
+ "identity",
+ {"introduction": '<!-- MEMORY_FIELDS {"name":"changed"} -->'},
+ )
+
+
+async def test_account_content_template_runtime_failure_preserves_existing_file():
+ from openviking.server.identity import RequestContext, Role
+ from openviking.session.memory.dataclass import ResolvedOperation
+ from openviking.session.memory.memory_updater import MemoryUpdater
+ from openviking_cli.session.user_id import UserIdentifier
+
+ registry = MemoryTypeRegistry()
+ schema = registry.get("events")
+ # Valid template, but the extraction context is unavailable at write time.
+ schema.content_template = "{{ extract_context.get_year(ranges) }}"
+ schema._account_content_template = True
+ validate_content_template(schema.content_template, "events")
+ fs = SimpleNamespace(
+ read_file=AsyncMock(return_value="# Existing body"), write_file=AsyncMock()
+ )
+ updater = MemoryUpdater(registry=registry)
+ updater._viking_fs = fs
+ with pytest.raises(ContentTemplateError, match="render_failed"):
+ await updater._apply_upsert(
+ ResolvedOperation(
+ memory_type="events",
+ uris=["viking://user/alice/memories/events/meeting.md"],
+ memory_fields={},
+ ),
+ RequestContext(user=UserIdentifier("space_a", "alice"), role=Role.USER),
+ )
+ fs.write_file.assert_not_awaited()
+
+
+async def test_account_content_template_initialization(monkeypatch):
+ from openviking.server.identity import RequestContext, Role
+ from openviking_cli.session.user_id import UserIdentifier
+
+ class FS:
+ files = {}
+
+ async def read_file(self, uri, **kwargs):
+ raise FileNotFoundError(uri)
+
+ async def write_file(self, uri, content, **kwargs):
+ self.files[uri] = content
+
+ fs = FS()
+ monkeypatch.setattr("openviking.storage.viking_fs.get_viking_fs", lambda: fs)
+ registry = MemoryTypeRegistry()
+ for memory_type, field in [("soul", "core_truths"), ("identity", "creature")]:
+ schema = registry.get(memory_type)
+ schema._account_content_template = True
+ schema.content_template = "# Custom\n{{ " + field + " }}"
+ assert "_account_content_template" not in schema.model_dump()
+ await registry.initialize_memory_files(
+ RequestContext(user=UserIdentifier("space_a", "alice"), role=Role.USER),
+ allowed_memory_types={"soul", "identity"},
+ )
+ assert len(fs.files) == 2
+ assert all(
+ MemoryFileUtils.read(body).content.startswith("# Custom") for body in fs.files.values()
+ )
+
+
+ "method,args",
+ [
+ ("get_resource_event_content", "ranges, summary"),
+ ("get_first_message_time_from_ranges", "ranges"),
+ ("get_first_message_time_with_weekday_from_ranges", "ranges"),
+ ("get_event_content", "ranges, summary"),
+ ("get_event_content", "ranges, summary, 0"),
+ ("get_year", "ranges"),
+ ("get_month", "ranges"),
+ ("get_day", "ranges"),
+ ],
+)
+def test_content_template_all_documented_helpers(method, args):
+ context = SimpleNamespace(**{method: lambda *args: "ok"})
+ assert (
+ render_content_template(
+ "{{ extract_context." + method + "(" + args + ") }}",
+ "events",
+ {"ranges": "0", "summary": "summary"},
+ context,
+ )
+ == "ok"
+ )
diff --git a/tests/session/memory/test_streaming_memory_updater.py b/tests/session/memory/test_streaming_memory_updater.py
index 8750206bc..1b9236d1c 100644
--- a/tests/session/memory/test_streaming_memory_updater.py
+++ b/tests/session/memory/test_streaming_memory_updater.py
@@ -40,6 +40,7 @@ from openviking.session.memory.streaming_memory_updater import (
split_request_by_merge_group,
)
from openviking.session.memory.utils.memory_file_utils import MemoryFileUtils
+from openviking_cli.exceptions import ConflictError
from openviking_cli.session.user_id import UserIdentifier
@@ -1040,6 +1041,277 @@ def test_enforce_merge_group_peer_enabled_false_keeps_self_scope():
assert op.uris == ["viking://user/u/memories/cases/case_note.md"]
+ "template_change",
+ [
+ "none",
+ "unrelated_type",
+ "description",
+ "field_description",
+ "body",
+ "renderer",
+ ],
+)
+async def test_template_snapshot_updates_same_uri(monkeypatch, template_change):
+ uri = "viking://user/u/memories/notes/profile.md"
+ original = "City: Beijing\nRole: engineer"
+ expected = "City: Shanghai\nRole: scientist"
+ old = MemoryFile(uri=uri, memory_type="notes", content=original)
+ raw = MemoryFileUtils.write(old)
+ fs = InMemoryVikingFS({uri: raw})
+ for module in ("streaming_memory_updater", "memory_updater"):
+ monkeypatch.setattr(f"openviking.session.memory.{module}.get_viking_fs", lambda: fs)
+ requests = []
+ for index, replacement in enumerate(
+ ("City: Shanghai\nRole: engineer", "City: Beijing\nRole: scientist")
+ ):
+ registry = _registry()
+ if index == 1:
+ schema = registry.get("notes")
+ if template_change == "unrelated_type":
+ registry.get("cases").description = "Unrelated new description"
+ elif template_change == "description":
+ schema.description = "New description"
+ elif template_change == "field_description":
+ schema.fields[-1].description = "New field description"
+ elif template_change == "body":
+ schema.content_template = "# New body\n{{ content }}"
+ elif template_change == "renderer":
+ schema._account_content_template = True
+ requests.append(
+ MemoryUpdateRequest(
+ operations=ResolvedOperations(
+ upsert_operations=[
+ ResolvedOperation(
+ memory_type="notes",
+ uris=[uri],
+ old_memory_file_content=old.model_copy(deep=True),
+ memory_fields={
+ "content": StrPatch(
+ blocks=[
+ SearchReplaceBlock(search=original, replace=replacement)
+ ]
+ )
+ },
+ )
+ ],
+ delete_file_contents=[],
+ errors=[],
+ ),
+ messages=[],
+ ctx=_ctx(),
+ memory_registry=registry,
+ metadata={"session_id": f"s{index}"},
+ )
+ )
+
+ async def coordinated_merge(**kwargs):
+ # Deterministic substitute for the LLM; the real updater still writes the file.
+ assert kwargs["registry"] is requests[0].memory_registry
+ assert len(kwargs["operations"].upsert_operations) == 2
+ op = requests[0].operations.upsert_operations[0].model_copy(deep=True)
+ op.memory_fields["content"] = StrPatch(
+ blocks=[SearchReplaceBlock(search=original, replace=expected)]
+ )
+ return ResolvedOperations(upsert_operations=[op], delete_file_contents=[], errors=[])
+
+ merge = AsyncMock(side_effect=coordinated_merge)
+ monkeypatch.setattr(
+ "openviking.session.memory.streaming_memory_updater.merge_memory_operations", merge
+ )
+ updater = StreamingMemoryUpdater(
+ registry=_registry(),
+ config=StreamingMemoryUpdaterConfig(max_operations_per_update=2),
+ )
+ try:
+ results = await asyncio.gather(
+ *(updater.submit(request) for request in requests), return_exceptions=True
+ )
+ if template_change in {"none", "unrelated_type"}:
+ merge.assert_awaited_once()
+ assert all(not result.apply_result.errors for result in results)
+ assert MemoryFileUtils.read(fs.files[uri]).plain_content() == expected
+ else:
+ assert all(isinstance(result, ConflictError) for result in results)
+ assert all(uri in str(result) and "Re-extract" in str(result) for result in results)
+ merge.assert_not_awaited()
+ assert fs.files == {uri: raw}
+ assert not fs.writes
+ # A new extraction with consistent current templates can be retried.
+ requests[0].memory_registry = requests[1].memory_registry = _registry()
+ retried = await asyncio.gather(*(updater.submit(request) for request in requests))
+ assert all(not result.apply_result.errors for result in retried)
+ assert MemoryFileUtils.read(fs.files[uri]).plain_content() == expected
+ finally:
+ await updater.close()
+
+
+ "kinds", [("add", "add"), ("update", "delete"), ("delete", "update"), ("delete", "delete")]
+)
+async def test_template_snapshot_conflicts_cover_adds_and_deletes(monkeypatch, kinds):
+ uri = "viking://user/u/memories/notes/profile.md"
+ old = MemoryFile(uri=uri, memory_type="notes", content="Original")
+ fs = InMemoryVikingFS({uri: MemoryFileUtils.write(old)} if "add" not in kinds else {})
+ original_files = dict(fs.files)
+ for module in ("streaming_memory_updater", "memory_updater"):
+ monkeypatch.setattr(f"openviking.session.memory.{module}.get_viking_fs", lambda: fs)
+ requests = []
+ for index, kind in enumerate(kinds):
+ registry = _registry()
+ registry.get("notes").description = f"Version {index}"
+ op = _note_op("profile")
+ if kind == "update":
+ op.old_memory_file_content = old.model_copy(deep=True)
+ requests.append(
+ MemoryUpdateRequest(
+ operations=ResolvedOperations(
+ upsert_operations=[] if kind == "delete" else [op],
+ delete_file_contents=[old] if kind == "delete" else [],
+ errors=[],
+ ),
+ messages=[],
+ ctx=_ctx(),
+ memory_registry=registry,
+ metadata={"session_id": f"s{index}"},
+ )
+ )
+ updater = StreamingMemoryUpdater(
+ registry=_registry(), config=StreamingMemoryUpdaterConfig(max_operations_per_update=2)
+ )
+ try:
+ results = await asyncio.gather(
+ *(updater.submit(request) for request in requests), return_exceptions=True
+ )
+ assert all(isinstance(result, ConflictError) for result in results)
+ assert fs.files == original_files
+ assert not fs.writes
+ finally:
+ await updater.close()
+
+
[email protected]("alias", ["viking://user/memories/notes/profile.md", "case_variant"])
+async def test_template_snapshot_conflicts_compare_storage_paths(monkeypatch, alias):
+ fs = PathlockedInMemoryVikingFS()
+ monkeypatch.setattr(
+ "openviking.session.memory.streaming_memory_updater.get_viking_fs", lambda: fs
+ )
+ requests = []
+ for index in range(2):
+ registry = _registry()
+ registry.get("notes").description = f"Version {index}"
+ op = _note_op("profile")
+ if index:
+ op.uris = [
+ op.uris[0].replace("profile.md", "PROFILE.md") if alias == "case_variant" else alias
+ ]
+ requests.append(
+ MemoryUpdateRequest(
+ operations=ResolvedOperations(
+ upsert_operations=[op], delete_file_contents=[], errors=[]
+ ),
+ messages=[],
+ ctx=_ctx(),
+ memory_registry=registry,
+ )
+ )
+ merge = AsyncMock()
+ monkeypatch.setattr(StreamingMemoryUpdater, "_merge_requests", merge)
+ updater = StreamingMemoryUpdater(registry=_registry())
+ try:
+ with pytest.raises(ConflictError):
+ await updater._process_batch(MemoryMergeGroupKey(None, "notes"), requests, "count")
+ merge.assert_not_awaited()
+ assert not fs.writes
+ finally:
+ await updater.close()
+
+
[email protected]("target", ["shared_new_target", "note0"])
+async def test_template_snapshot_conflicts_check_merged_targets_before_writes(monkeypatch, target):
+ requests = []
+ for index in range(2):
+ registry = _registry()
+ registry.get("notes").description = f"Version {index}"
+ requests.append(
+ MemoryUpdateRequest(
+ operations=ResolvedOperations(
+ upsert_operations=[_note_op(f"note{index}")], delete_file_contents=[], errors=[]
+ ),
+ messages=[],
+ ctx=_ctx(),
+ memory_registry=registry,
+ )
+ )
+
+ async def retarget_merge(batch):
+ merged = batch[0].operations.model_copy(deep=True)
+ merged.upsert_operations[0].uris = [f"viking://user/u/memories/notes/{target}.md"]
+ return merged
+
+ merge = AsyncMock(side_effect=retarget_merge)
+ apply = AsyncMock()
+ monkeypatch.setattr(StreamingMemoryUpdater, "_merge_requests", merge)
+ monkeypatch.setattr(StreamingMemoryUpdater, "_apply_operations", apply)
+ monkeypatch.setattr(
+ "openviking.session.memory.streaming_memory_updater.get_viking_fs", lambda: None
+ )
+ updater = StreamingMemoryUpdater(registry=_registry())
+ try:
+ with pytest.raises(ConflictError):
+ await updater._process_batch(MemoryMergeGroupKey(None, "notes"), requests, "count")
+ assert merge.await_count == 2
+ apply.assert_not_awaited()
+ finally:
+ await updater.close()
+
+
+async def test_streaming_memory_updater_separates_template_snapshots(monkeypatch):
+ fs = InMemoryVikingFS({})
+ for module in ("streaming_memory_updater", "memory_updater"):
+ monkeypatch.setattr(f"openviking.session.memory.{module}.get_viking_fs", lambda: fs)
+ updater = StreamingMemoryUpdater(
+ registry=_registry(),
+ config=StreamingMemoryUpdaterConfig(
+ max_operations_per_update=2,
+ max_wait_seconds=0.05,
+ timer_check_interval_seconds=0.01,
+ ),
+ )
+ requests = []
+ for index in (1, 2):
+ registry = _registry()
+ registry.get("notes").content_template = f"# Version {index}\n{{{{ content }}}}"
+ requests.append(
+ MemoryUpdateRequest(
+ operations=ResolvedOperations(
+ upsert_operations=[_note_op(f"note{index}")],
+ delete_file_contents=[],
+ errors=[],
+ ),
+ messages=[],
+ ctx=_ctx(),
+ memory_registry=registry,
+ metadata={"session_id": f"s{index}"},
+ )
+ )
+ try:
+ results = await asyncio.gather(*(updater.submit(request) for request in requests))
+ finally:
+ await updater.close()
+ for index, result in enumerate(results, 1):
+ assert not result.apply_result.errors
+ uri = f"viking://user/u/memories/notes/note{index}.md"
+ content = MemoryFileUtils.read(fs.files[uri], uri=uri).content
+ assert f"# Version {index}" in content
+ assert f"# Version {3 - index}" not in content
+
+
@pytest.mark.asyncio
async def test_streaming_memory_updater_batches_per_merge_group(monkeypatch):
fs = InMemoryVikingFS({})
diff --git a/tests/session/test_compressor_v3.py b/tests/session/test_compressor_v3.py
index 00cd3a29a..7f8da7ca5 100644
--- a/tests/session/test_compressor_v3.py
+++ b/tests/session/test_compressor_v3.py
@@ -48,6 +48,7 @@ from openviking.session.train import (
)
from openviking.session.train.components.session_commit import _case_spec_message_to_request
from openviking.telemetry import OperationTelemetry, bind_telemetry
+from openviking_cli.exceptions import ConflictError
from openviking_cli.session.user_id import UserIdentifier
@@ -90,6 +91,26 @@ def test_factory_defaults_to_v3():
assert isinstance(compressor, SessionCompressorV3)
+async def test_commit_extraction_propagates_template_conflict():
+ compressor = SessionCompressorV3(vikingdb=None, rollout_analyzer=SimpleNamespace())
+ conflict = ConflictError("Conflicting memory template snapshots; Re-extract before retrying")
+ compressor._extract_user_memories = AsyncMock(side_effect=conflict)
+ compressor._write_final_memory_diff = AsyncMock()
+
+ with pytest.raises(ConflictError) as raised:
+ await compressor.extract_long_term_memories(
+ messages=_messages(),
+ ctx=_ctx(),
+ allowed_memory_types={"profile"},
+ # The Session commit worker uses this mode: a conflict must reach it,
+ # not turn into an empty successful extraction or memory diff.
+ strict_extract_errors=True,
+ )
+ assert raised.value is conflict
+ compressor._write_final_memory_diff.assert_not_awaited()
+
+
def test_factory_ignores_deprecated_memory_version():
assert isinstance(
create_session_compressor(vikingdb=None, memory_version="v2"), SessionCompressorV3