Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
session: add restricted Python DSL extraction protocol and make it the default (#4581)
chenjwa843ab6bf220
diff --git a/benchmark/locomo/vikingbot/import_to_ov.py b/benchmark/locomo/vikingbot/import_to_ov.pyindex 287e52579..5962c703f 100644--- a/benchmark/locomo/vikingbot/import_to_ov.py+++ b/benchmark/locomo/vikingbot/import_to_ov.py@@ -612,7 +612,7 @@ async def viking_ingest(try:result = await _retry_transient_http(f"commit_session session={session_id}",- lambda: client.commit_session(session_id, options={"telemetry": True}),+ lambda: client.commit_session(session_id, telemetry=True),attempts=2,)except _TRANSIENT_HTTP_ERRORS as exc:diff --git a/benchmark/locomo/vikingbot/run_full_eval.sh b/benchmark/locomo/vikingbot/run_full_eval.shindex 5d8aa3a80..c9b3cc842 100755--- a/benchmark/locomo/vikingbot/run_full_eval.sh+++ b/benchmark/locomo/vikingbot/run_full_eval.sh@@ -13,6 +13,7 @@# ./run_full_eval.sh --retry-wrong result/locomo_result_xxx.csv # 只重跑错题# ./run_full_eval.sh --parallel-import-sessions 20 0 1 # 覆盖默认 session 导入并发数# ./run_full_eval.sh --parallel-import-sessions 50 --parallel-run-eval 20 --parallel-judge 40 # 分别设置导入、评测和裁判并发数+# ./run_full_eval.sh --keep-runs 20 # 保留最近 20 次实验(默认 10)set -e@@ -73,7 +74,7 @@ ui_step() {# --help 提前处理,避免触发 Python preflightfor arg in "$@"; doif [ "$arg" = "--help" ] || [ "$arg" = "-h" ]; then- sed -n '2,10p' "$0" | sed 's/^# \?//'+ sed -n '2,17p' "$0" | sed 's/^# \?//'echo ""echo "位置参数:"echo " sample_index 数字索引 (0,1,2...)"@@ -89,6 +90,7 @@ for arg in "$@"; doecho " --parallel-import-sessions N 导入 session 并发数(默认 50)"echo " --parallel-run-eval N run_eval 并发线程数(默认 100)"echo " --parallel-judge N judge 并发请求数(默认 100)"+ echo " --keep-runs N 保留最近 N 次实验目录(默认 10)"exit 0fidone@@ -98,6 +100,7 @@ SKIP_IMPORT=falseGROUP_CHAT=falseAUTO_COMMIT=falseRETRY_WRONG=""+KEEP_RUNS=10PARALLEL_IMPORT_SESSIONS="50"PARALLEL_RUN_EVAL="100"PARALLEL_JUDGE="100"@@ -111,7 +114,21 @@ elseexit 1fi+# 实验输出目录:result/locomo/runs/<timestamp>[_<commit>]+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"+RESULTS_ROOT="$REPO_ROOT/result/locomo"+mkdir -p "$RESULTS_ROOT"++TIMESTAMP=$(date +%Y%m%d_%H%M%S)++RUN_DIR_NAME="${TIMESTAMP}"+RUN_DIR="$RESULTS_ROOT/runs/$RUN_DIR_NAME"+mkdir -p "$RUN_DIR"+echo "$RUN_DIR" > "$RESULTS_ROOT/.latest_run"+ui_banner "LoCoMo · VikingBot Evaluation"+ui_kv "实验目录" "$RUN_DIR"+ui_section "1. 环境预检"DEFAULT_OV_CONF_PATH="$($PYTHON_BIN - <<'PY'@@ -198,6 +215,11 @@ for arg in "$@"; doPREV_ARG=""continuefi+ if [ "$PREV_ARG" = "--keep-runs" ]; then+ KEEP_RUNS="$arg"+ PREV_ARG=""+ continue+ fiif [ "$arg" = "--skip-import" ]; thenSKIP_IMPORT=trueelif [ "$arg" = "--group-chat" ]; then@@ -209,13 +231,7 @@ for arg in "$@"; doelif [ "$arg" = "--retry-wrong" ]; thenPREV_ARG="$arg"continue- elif [ "$arg" = "--parallel-import-sessions" ]; then- PREV_ARG="$arg"- continue- elif [ "$arg" = "--parallel-run-eval" ]; then- PREV_ARG="$arg"- continue- elif [ "$arg" = "--parallel-judge" ]; then+ elif [ "$arg" = "--parallel-import-sessions" ] || [ "$arg" = "--parallel-run-eval" ] || [ "$arg" = "--parallel-judge" ] || [ "$arg" = "--keep-runs" ]; thenPREV_ARG="$arg"continuefi@@ -226,7 +242,17 @@ if [ -n "$PREV_ARG" ]; thenexit 1fi-# 过滤掉开关参数和 --retry-wrong 的值,获取位置参数+# auto-commit runs AFTER arg parsing so --auto-commit is actually honored, and+# GIT_COMMIT_ID is captured AFTER the commit so run metadata records the real HEAD.+if [ "$AUTO_COMMIT" = "true" ]; then+ if [ -n "$(cd "$SCRIPT_DIR/../../.." && git status --porcelain)" ]; then+ ui_info "检测到未提交变更,正在自动提交…"+ (cd "$SCRIPT_DIR/../../.." && git add -A && git commit -m "auto-commit before eval $(date +%Y%m%d_%H%M%S)")+ fi+fi+GIT_COMMIT_ID=$(cd "$SCRIPT_DIR/../../.." && git rev-parse --short HEAD 2>/dev/null || echo "nogit")++# 过滤掉开关参数和带值参数,获取位置参数ARGS=()SKIP_NEXT=falsefor arg in "$@"; do@@ -234,7 +260,7 @@ for arg in "$@"; doSKIP_NEXT=falsecontinuefi- if [ "$arg" = "--retry-wrong" ] || [ "$arg" = "--parallel-import-sessions" ] || [ "$arg" = "--parallel-run-eval" ] || [ "$arg" = "--parallel-judge" ]; then+ if [ "$arg" = "--retry-wrong" ] || [ "$arg" = "--parallel-import-sessions" ] || [ "$arg" = "--parallel-run-eval" ] || [ "$arg" = "--parallel-judge" ] || [ "$arg" = "--keep-runs" ]; thenSKIP_NEXT=truecontinuefi@@ -273,6 +299,10 @@ if ! [[ "$PARALLEL_JUDGE" =~ ^[1-9][0-9]*$ ]]; thenui_error "--parallel-judge requires a positive integer"exit 1fi+if ! [[ "$KEEP_RUNS" =~ ^[1-9][0-9]*$ ]]; then+ ui_error "--keep-runs requires a positive integer"+ exit 1+fiRUN_EVAL_OPTS=("--threads" "$PARALLEL_RUN_EVAL")JUDGE_OPTS=("--parallel" "$PARALLEL_JUDGE")@@ -280,6 +310,13 @@ SAMPLE=${ARGS[0]}QUESTION_INDEX=${ARGS[1]}INPUT_FILE="$SCRIPT_DIR/../data/locomo10.json"+# 实验目录内的输出文件+RESULT_BASENAME="locomo_result"+RESULT_FILE="$RUN_DIR/${RESULT_BASENAME}.csv"+IMPORT_SUCCESS_CSV="$RUN_DIR/import_success.csv"+BOT_LOG_DIR="$RUN_DIR/${RESULT_BASENAME}_bot_logs"+MEMORY_SNAPSHOT_DIR="$RUN_DIR/memories"+ui_section "2. 运行配置"ui_kv "配置文件" "$OPENVIKING_CONFIG_FILE"ui_kv "OpenViking" "$OPENVIKING_URL"@@ -289,23 +326,12 @@ ui_kv "导入并发" "$PARALLEL_IMPORT_SESSIONS sessions"ui_kv "评测并发" "$PARALLEL_RUN_EVAL threads"ui_kv "裁判并发" "$PARALLEL_JUDGE requests"ui_kv "导入策略" "$([ "$SKIP_IMPORT" = "true" ] && printf '跳过导入' || printf '强制导入')"+ui_kv "保留实验数" "$KEEP_RUNS"# Export for inline Python usageexport SCRIPT_DIR INPUT_FILE RETRY_WRONG PARALLEL_IMPORT_SESSIONS ACCOUNT OPENVIKING_URL OPENVIKING_API_KEY OPENVIKING_USER OPENVIKING_AUTH_MODE GROUP_CHAT+export IMPORT_SUCCESS_CSV BOT_LOG_DIR MEMORY_SNAPSHOT_DIR RUN_DIR RESULTS_ROOT-# auto-commit 逻辑-if [ "$AUTO_COMMIT" = "true" ]; then- if [ -n "$(git status --porcelain)" ]; then- ui_info "检测到未提交变更,正在自动提交…"- git add -A- git commit -m "auto-commit before eval $(date +%Y%m%d_%H%M%S)"- else- ui_success "工作区干净,无需自动提交"- fi-fi-GIT_COMMIT_ID=$(git rev-parse --short HEAD)-TIMESTAMP=$(date +%Y%m%d%H%M%S)-IMPORT_SUCCESS_CSV="./result/locomo/import_success.csv"IMPORT_ROW_START=0IMPORT_PERFORMED=false@@ -426,11 +452,89 @@ PY}prepare_bot_log_dir() {- local output_file="$1"- local base="${output_file%.csv}"- export LOCOMO_VIKINGBOT_LOG_DIR="${base}_bot_logs"- mkdir -p "$LOCOMO_VIKINGBOT_LOG_DIR"- ui_kv "VikingBot 日志" "$LOCOMO_VIKINGBOT_LOG_DIR"+ mkdir -p "$BOT_LOG_DIR"+ export LOCOMO_VIKINGBOT_LOG_DIR="$BOT_LOG_DIR"+ ui_kv "VikingBot 日志" "$BOT_LOG_DIR"+}++# 保存运行元信息+write_run_metadata() {+ cat > "$RUN_DIR/run_metadata.txt" <<EOF+timestamp: $TIMESTAMP+git_commit: $GIT_COMMIT_ID+config_file: $OPENVIKING_CONFIG_FILE+openviking_url: $OPENVIKING_URL+skip_import: $SKIP_IMPORT+group_chat: $GROUP_CHAT+parallel_import_sessions: $PARALLEL_IMPORT_SESSIONS+parallel_run_eval: $PARALLEL_RUN_EVAL+parallel_judge: $PARALLEL_JUDGE+sample: ${SAMPLE:-all}+question_index: ${QUESTION_INDEX:-}+EOF+}++# 拷贝生成的记忆文件快照+copy_memory_snapshot() {+ if [ "$SKIP_IMPORT" = "true" ]; then+ return+ fi+ ui_step_copy="copy_memory_snapshot"+ ui_info "正在保存记忆文件快照…"++ # 从配置中提取 workspace 路径+ local workspace+ workspace=$("$PYTHON_BIN" - <<'PY'+import json, os+config_path = os.environ["OPENVIKING_CONFIG_FILE"]+try:+ with open(config_path, "r") as f:+ config = json.load(f)+ print(config.get("storage", {}).get("workspace", ""))+except Exception:+ print("")+PY+)+ if [ -z "$workspace" ]; then+ ui_warn "无法从配置中提取 workspace 路径,跳过记忆快照"+ return+ fi++ local peers_dir="$workspace/viking/default/user/default/peers"+ if [ ! -d "$peers_dir" ]; then+ # 尝试其他路径模式+ peers_dir=$(find "$workspace" -type d -name "peers" -path "*/user/*" 2>/dev/null | head -1)+ fi++ if [ -n "$peers_dir" ] && [ -d "$peers_dir" ]; then+ mkdir -p "$MEMORY_SNAPSHOT_DIR"+ cp -R "$peers_dir/." "$MEMORY_SNAPSHOT_DIR/" 2>/dev/null || true+ local mem_file_count+ mem_file_count=$(find "$MEMORY_SNAPSHOT_DIR" -name "*.md" ! -name ".overview.md" ! -name ".abstract.md" | wc -l | tr -d ' ')+ ui_success "记忆快照已保存:$mem_file_count 个 .md 文件 → $MEMORY_SNAPSHOT_DIR"+ else+ ui_warn "未找到 peers 记忆目录,跳过记忆快照"+ fi+}++# 清理旧实验目录,只保留最近 N 次+cleanup_old_runs() {+ local runs_root="$RESULTS_ROOT/runs"+ if [ ! -d "$runs_root" ]; then+ return+ fi+ local count+ count=$(find "$runs_root" -maxdepth 1 -type d | tail -n +2 | wc -l | tr -d ' ')+ if [ "$count" -le "$KEEP_RUNS" ]; then+ return+ fi+ ui_info "清理旧实验目录(保留最近 $KEEP_RUNS 次,当前 $count 次)…"+ # 按名称排序(时间戳),删除最旧的+ find "$runs_root" -maxdepth 1 -type d | tail -n +2 | sort | head -n "$((count - KEEP_RUNS))" | while read -r old_dir; do+ ui_info " 删除 $(basename "$old_dir")"+ rm -rf "$old_dir"+ done+ ui_success "旧实验目录已清理"}# ========== 重跑错题模式(优先) ==========@@ -440,16 +544,11 @@ if [ -n "$RETRY_WRONG" ]; thenexit 1fi+ write_run_metadataui_section "3. 执行评测 · 错题重跑"ui_kv "错题文件" "$RETRY_WRONG"- if [ "$AUTO_COMMIT" = "true" ]; then- RESULT_FILE="./result/locomo/locomo_retry_${TIMESTAMP}_${GIT_COMMIT_ID}.csv"- else- RESULT_FILE="./result/locomo/locomo_retry_${TIMESTAMP}.csv"- fi-- # 从错题 CSV 中提取需要导入的对话(复用 import_to_ov.py 的并行逻辑)+ # 从错题 CSV 中提取需要导入的对话ui_step 1 3 "导入错题相关对话"capture_import_row_start"$PYTHON_BIN" "$SCRIPT_DIR/import_to_ov.py" \@@ -458,6 +557,7 @@ if [ -n "$RETRY_WRONG" ]; then--force-ingest \--account "$ACCOUNT" \--openviking-url "$OPENVIKING_URL" \+ --success-csv "$IMPORT_SUCCESS_CSV" \"${IMPORT_OPTS[@]}" \"${COMMON_OPTS[@]}"IMPORT_PERFORMED=true@@ -467,7 +567,7 @@ if [ -n "$RETRY_WRONG" ]; then# 评估错题ui_step 2 3 "重新评估错题"- prepare_bot_log_dir "$RESULT_FILE"+ prepare_bot_log_dir"$PYTHON_BIN" "$SCRIPT_DIR/run_eval.py" \"$INPUT_FILE" \--output "$RESULT_FILE" \@@ -484,29 +584,35 @@ if [ -n "$RETRY_WRONG" ]; then"$PYTHON_BIN" "$SCRIPT_DIR/stat_judge_result.py" --input "$RESULT_FILE"print_import_summary_table+ copy_memory_snapshot+ cleanup_old_runs+ui_section "完成"ui_success "错题重跑完成"+ ui_kv "实验目录" "$RUN_DIR"ui_kv "结果文件" "$RESULT_FILE"exit 0fi# ========== 全量评测模式 ==========if [ -z "$SAMPLE" ]; then+ write_run_metadataui_section "3. 执行评测 · 全量模式"- if [ "$AUTO_COMMIT" = "true" ]; then- RESULT_FILE="./result/locomo/locomo_result_${TIMESTAMP}_${GIT_COMMIT_ID}.csv"- else- RESULT_FILE="./result/locomo/locomo_result_${TIMESTAMP}.csv"- fi-# 导入数据if [ "$SKIP_IMPORT" = "true" ]; thenui_warn "已通过 --skip-import 跳过导入数据"elseui_step 1 4 "导入数据"capture_import_row_start- "$PYTHON_BIN" "$SCRIPT_DIR/import_to_ov.py" --input "$INPUT_FILE" --force-ingest --account "$ACCOUNT" --openviking-url "$OPENVIKING_URL" "${IMPORT_OPTS[@]}" "${COMMON_OPTS[@]}"+ "$PYTHON_BIN" "$SCRIPT_DIR/import_to_ov.py" \+ --input "$INPUT_FILE" \+ --force-ingest \+ --account "$ACCOUNT" \+ --openviking-url "$OPENVIKING_URL" \+ --success-csv "$IMPORT_SUCCESS_CSV" \+ "${IMPORT_OPTS[@]}" \+ "${COMMON_OPTS[@]}"IMPORT_PERFORMED=trueui_info "等待数据处理完成(60 秒)…"sleep 60@@ -518,8 +624,13 @@ if [ -z "$SAMPLE" ]; thenelseui_step 2 4 "运行评估"fi- prepare_bot_log_dir "$RESULT_FILE"- "$PYTHON_BIN" "$SCRIPT_DIR/run_eval.py" "$INPUT_FILE" --output "$RESULT_FILE" --config "$OPENVIKING_CONFIG_FILE" "${RUN_EVAL_OPTS[@]}" "${COMMON_OPTS[@]}"+ prepare_bot_log_dir+ "$PYTHON_BIN" "$SCRIPT_DIR/run_eval.py" \+ "$INPUT_FILE" \+ --output "$RESULT_FILE" \+ --config "$OPENVIKING_CONFIG_FILE" \+ "${RUN_EVAL_OPTS[@]}" \+ "${COMMON_OPTS[@]}"# 裁判打分if [ "$SKIP_IMPORT" = "true" ]; then@@ -538,8 +649,12 @@ if [ -z "$SAMPLE" ]; then"$PYTHON_BIN" "$SCRIPT_DIR/stat_judge_result.py" --input "$RESULT_FILE"print_import_summary_table+ copy_memory_snapshot+ cleanup_old_runs+ui_section "完成"ui_success "全量评测完成"+ ui_kv "实验目录" "$RUN_DIR"ui_kv "结果文件" "$RESULT_FILE"exit 0fi@@ -579,11 +694,11 @@ fi# 判断是单题模式还是批量模式if [ -n "$QUESTION_INDEX" ]; then+ write_run_metadata# ========== 单题模式 ==========ui_section "3. 执行评测 · 单题模式"ui_kv "评测范围" "sample=$SAMPLE · question=$QUESTION_INDEX"- # 导入对话if [ "$SKIP_IMPORT" = "true" ]; thenui_warn "已通过 --skip-import 跳过导入对话"else@@ -596,6 +711,7 @@ if [ -n "$QUESTION_INDEX" ]; then--force-ingest \--account "$ACCOUNT" \--openviking-url "$OPENVIKING_URL" \+ --success-csv "$IMPORT_SUCCESS_CSV" \"${IMPORT_OPTS[@]}" \"${COMMON_OPTS[@]}"IMPORT_PERFORMED=true@@ -604,40 +720,32 @@ if [ -n "$QUESTION_INDEX" ]; thensleep 3fi- # 运行评测if [ "$SKIP_IMPORT" = "true" ]; thenui_step 1 2 "运行评估"elseui_step 2 3 "运行评估"fi- if [ "$AUTO_COMMIT" = "true" ]; then- OUTPUT_FILE=./result/locomo/locomo_${SAMPLE}_${QUESTION_INDEX}_result_${TIMESTAMP}_${GIT_COMMIT_ID}.csv- else- OUTPUT_FILE=./result/locomo/locomo_${SAMPLE}_${QUESTION_INDEX}_result_${TIMESTAMP}.csv- fi- prepare_bot_log_dir "$OUTPUT_FILE"+ prepare_bot_log_dir"$PYTHON_BIN" "$SCRIPT_DIR/run_eval.py" \"$INPUT_FILE" \--sample "$SAMPLE_ID_FOR_CMD" \--question-index "$QUESTION_INDEX" \--count 1 \- --output "$OUTPUT_FILE" \+ --output "$RESULT_FILE" \--config "$OPENVIKING_CONFIG_FILE" \"${RUN_EVAL_OPTS[@]}" \"${COMMON_OPTS[@]}"- # 运行 Judge 评分if [ "$SKIP_IMPORT" = "true" ]; thenui_step 2 2 "裁判打分"elseui_step 3 3 "裁判打分"fi- "$PYTHON_BIN" "$SCRIPT_DIR/judge.py" --input "$OUTPUT_FILE" "${JUDGE_OPTS[@]}"+ "$PYTHON_BIN" "$SCRIPT_DIR/judge.py" --input "$RESULT_FILE" "${JUDGE_OPTS[@]}"- # 输出结果ui_section "评测结果"print_import_summary_table- OUTPUT_FILE="$OUTPUT_FILE" QUESTION_INDEX="$QUESTION_INDEX" "$PYTHON_BIN" - <<'PY'+ OUTPUT_FILE="$RESULT_FILE" QUESTION_INDEX="$QUESTION_INDEX" "$PYTHON_BIN" - <<'PY'import csvimport jsonimport os@@ -669,12 +777,17 @@ print(f"结果: {row.get('result', 'N/A')}")print(f"原因: {row.get('reasoning', 'N/A')}")PY+ copy_memory_snapshot+ cleanup_old_runs++ ui_kv "实验目录" "$RUN_DIR"+else+ write_run_metadata# ========== 批量模式 ==========ui_section "3. 执行评测 · Sample 批量模式"ui_kv "评测范围" "sample=$SAMPLE · 所有问题"- # 获取该 sample 的问题数量QUESTION_COUNT=$(SAMPLE_INDEX="$SAMPLE_INDEX" INPUT_FILE="$INPUT_FILE" "$PYTHON_BIN" - <<'PY'import jsonimport os@@ -691,7 +804,6 @@ PY)ui_kv "问题数量" "$QUESTION_COUNT"- # 导入所有 sessionsif [ "$SKIP_IMPORT" = "true" ]; thenui_warn "已通过 --skip-import 跳过导入所有 Sessions"else@@ -703,6 +815,7 @@ PY--force-ingest \--account "$ACCOUNT" \--openviking-url "$OPENVIKING_URL" \+ --success-csv "$IMPORT_SUCCESS_CSV" \"${IMPORT_OPTS[@]}" \"${COMMON_OPTS[@]}"IMPORT_PERFORMED=true@@ -711,44 +824,40 @@ PYsleep 10fi- # 运行评测(所有问题)if [ "$SKIP_IMPORT" = "true" ]; thenui_step 1 3 "评估所有问题"elseui_step 2 4 "评估所有问题"fi- if [ "$AUTO_COMMIT" = "true" ]; then- OUTPUT_FILE=./result/locomo/locomo_${SAMPLE}_result_${TIMESTAMP}_${GIT_COMMIT_ID}.csv- else- OUTPUT_FILE=./result/locomo/locomo_${SAMPLE}_result_${TIMESTAMP}.csv- fi- prepare_bot_log_dir "$OUTPUT_FILE"+ prepare_bot_log_dir"$PYTHON_BIN" "$SCRIPT_DIR/run_eval.py" \"$INPUT_FILE" \--sample "$SAMPLE_ID_FOR_CMD" \- --output "$OUTPUT_FILE" \+ --output "$RESULT_FILE" \--config "$OPENVIKING_CONFIG_FILE" \"${RUN_EVAL_OPTS[@]}" \"${COMMON_OPTS[@]}"- # 运行 Judge 评分if [ "$SKIP_IMPORT" = "true" ]; thenui_step 2 3 "裁判打分"elseui_step 3 4 "裁判打分"fi- "$PYTHON_BIN" "$SCRIPT_DIR/judge.py" --input "$OUTPUT_FILE" "${JUDGE_OPTS[@]}"+ "$PYTHON_BIN" "$SCRIPT_DIR/judge.py" --input "$RESULT_FILE" "${JUDGE_OPTS[@]}"- # 输出统计结果if [ "$SKIP_IMPORT" = "true" ]; thenui_step 3 3 "汇总结果"elseui_step 4 4 "汇总结果"fi- "$PYTHON_BIN" "$SCRIPT_DIR/stat_judge_result.py" --input "$OUTPUT_FILE"+ "$PYTHON_BIN" "$SCRIPT_DIR/stat_judge_result.py" --input "$RESULT_FILE"print_import_summary_table+ copy_memory_snapshot+ cleanup_old_runs+ui_section "完成"ui_success "批量评测完成"- ui_kv "结果文件" "$OUTPUT_FILE"+ ui_kv "实验目录" "$RUN_DIR"+ ui_kv "结果文件" "$RESULT_FILE"fidiff --git a/benchmark/memory_organization/README.md b/benchmark/memory_organization/README.mdnew file mode 100644index 000000000..d73b5f56c--- /dev/null+++ b/benchmark/memory_organization/README.md@@ -0,0 +1,91 @@+# Memory Organization JSON vs Python A/B++This benchmark compares model behavior under the JSON and restricted-Python output+protocols while keeping the model, existing files, schema, instructions, retry budget,+and output-token cap identical.++## Autonomous decision suite++The primary hypothesis is tested without exposing expected topic names or fact partitions+to the model. The default suite contains exactly three cases:++- two paths differing only by directory case, where the schema generally requires+ case-insensitive lowercase normalization;+- one oversized `profile.md` containing durable profile facts mixed with preferences; all+ preference facts must move to `preferences` while valid profile facts remain in `profile.md`;+- one oversized broad `work_preferences.md` containing two coherent behavioral dimensions;+ after adding new facts it must become exactly two focused preference files, with every fact+ preserved exactly once and the broad source removed.++The expected organization exists only in the grader. `AutonomousProvider` subclasses the+production `SessionExtractContextProvider`, inherits its `instruction()` unchanged, and exposes+the complete enabled user-stage schema registry loaded from the production YAML files. The only+controlled fixture input is which existing files the production-format prefetch read results+contain; no benchmark-specific maintenance request is added. Run and report it with:++ python -m benchmark.memory_organization.run_autonomous_ab --repeat 20 --parallel 6 \+ --output benchmark/memory_organization/result/core_three_repeat10.jsonl+ python -m benchmark.memory_organization.report_autonomous \+ benchmark/memory_organization/result/core_three_repeat10.jsonl \+ --output benchmark/memory_organization/result/core_three_repeat10.summary.json++The report exposes two primary, orthogonal metrics for every case:++- `organization_action_success`: whether the required merge, move, or split happened;+- `information_integrity`: whether every expected fact remains present exactly once.++The action metric is deliberately structural. Missing, duplicated, or misclassified content is+reflected only by information integrity, keeping the two metrics independent.++For the oversized preference case, any split into two or more preference files is accepted when+the broad source file is removed. The number and names of child topics are not graded.++## Deterministic execution suite++The 12 fixtures cover four duplicate-file merges, four mixed-file splits, and four+combined merge-and-split plans. They are useful for deterministic protocol execution checks;+older guided result artifacts explicitly disclosed target groupings and must not be used as+evidence of autonomous planning quality. Likewise, `autonomous_*` artifacts without the+`production_` prefix predate exact production-prompt reuse and are superseded.+An additional stress suite uses 24–32 complete fact lines to test an oversized split,+an eight-file alias merge, and a large mixed reorganization separately from the pilot.++Facts contain immutable Fxx markers, so the grader checks final file placement,+retention, duplication, deletion, and canonical replacement deterministically. The+fixtures use full-field replacement content to isolate organization planning from+SEARCH/REPLACE matching noise.++## Smoke run++ python -m benchmark.memory_organization.run_ab --case merge_travel_aliases \+ --repeat 1 --output benchmark/memory_organization/result/smoke.jsonl+ python -m benchmark.memory_organization.report \+ benchmark/memory_organization/result/smoke.jsonl++## Paired experiment++Start with 5 repeats (120 model runs), then increase to 20 after inspecting smoke output:++ python -m benchmark.memory_organization.run_ab --repeat 5 \+ --output benchmark/memory_organization/result/ab_repeat5.jsonl+ python -m benchmark.memory_organization.report \+ benchmark/memory_organization/result/ab_repeat5.jsonl \+ --output benchmark/memory_organization/result/ab_repeat5.summary.json++Run the larger stress fixtures independently so they do not change the pilot population:++ python -m benchmark.memory_organization.run_ab \+ --cases benchmark/memory_organization/cases/organization_stress_cases.json \+ --repeat 5 --output benchmark/memory_organization/result/stress_repeat5.jsonl++The report separates two success metrics:++- `content_organization_success_rate`: final file partition, complete fact text,+ retention, placement, and deduplication all pass.+- `organization_success_rate`: content organization passes and canonical merge+ replacements preserve link inheritance correctly.++Paired counts and a two-sided exact McNemar p-value are reported for both metrics. A+protocol advantage requires repeated paired runs with more exclusive wins and acceptable+retry, token, and latency cost; one favorable sample is not sufficient.+diff --git a/benchmark/memory_organization/__init__.py b/benchmark/memory_organization/__init__.pynew file mode 100644index 000000000..b7a6bdaff--- /dev/null+++ b/benchmark/memory_organization/__init__.py@@ -0,0 +1 @@+"""Paired JSON-vs-Python benchmark for memory-file organization."""diff --git a/benchmark/memory_organization/autonomous_cases.py b/benchmark/memory_organization/autonomous_cases.pynew file mode 100644index 000000000..78b8bb040--- /dev/null+++ b/benchmark/memory_organization/autonomous_cases.py@@ -0,0 +1,246 @@+from __future__ import annotations++from dataclasses import dataclass+from typing import Any++from benchmark.memory_organization.models import fact_lines+++@dataclass(frozen=True, slots=True)+class AutonomousCase:+ case_id: str+ category: str+ schemas: tuple[Any, ...]+ initial_files: dict[str, Any]+ expected_groups: dict[str, tuple[frozenset[str], ...]]+ expected_replacements: dict[str, str]+ messages: tuple[Any, ...] = ()+ additional_facts: dict[str, str] | None = None+ maintenance_review_tokens: int | None = None++ @property+ def expected_facts(self) -> dict[str, str]:+ facts = {+ marker: text+ for memory_file in self.initial_files.values()+ for marker, text in fact_lines(memory_file.content)+ }+ facts.update(self.additional_facts or {})+ return facts+++def build_cases() -> list[AutonomousCase]:+ from openviking.message import Message, TextPart+ from openviking.session.memory.dataclass import MemoryFile+ from openviking.session.memory.memory_type_registry import MemoryTypeRegistry+ from openviking.session.memory.utils.template_utils import TemplateUtils++ registry = MemoryTypeRegistry(load_schemas=True)+ directory_schema = registry.get("entities")+ profile_schema = registry.get("profile")+ preferences_schema = registry.get("preferences")+ if directory_schema is None or profile_schema is None or preferences_schema is None:+ raise RuntimeError("Production entities/profile/preferences schemas are required")++ directory_root = TemplateUtils.render(directory_schema.directory, {"user_space": "default"})+ directory_files = {+ f"{directory_root}/Projects/atlas.md": MemoryFile(+ uri=f"{directory_root}/Projects/atlas.md",+ memory_type="entities",+ content=(+ "# Atlas\nAtlas 是一个软件服务。\n\n## 发布\n"+ "- [F01] 使用分阶段发布。\n"+ "- [F02] 有明确记录的回滚流程。"+ ),+ extra_fields={"category": "Projects", "name": "atlas"},+ ),+ f"{directory_root}/projects/atlas.md": MemoryFile(+ uri=f"{directory_root}/projects/atlas.md",+ memory_type="entities",+ content=(+ "# Atlas\nAtlas 是一个软件服务。\n\n## 归属与运维\n"+ "- [F03] 由平台团队负责。\n"+ "- [F04] 提供健康检查接口。"+ ),+ extra_fields={"category": "projects", "name": "atlas"},+ ),+ }++ profile_root = TemplateUtils.render(profile_schema.directory, {"user_space": "default"})+ profile_uri = f"{profile_root}/{profile_schema.filename_template}"+ profile_content = """# 安德鲁+- [F01] 是一名后端工程师 (as of 2026-08-01)+- [F02] 居住在新加坡 (as of 2026-08-01)+- [F03] 拥有计算机科学硕士学位 (as of 2026-08-01)+- [F04] 已婚 (as of 2026-08-01)+- [F05] 生日是 4 月 18 日 (as of 2026-08-01)+- [F06] 会说英语和普通话 (as of 2026-08-01)+- [F07] 偏好简洁的书面状态更新 (as of 2026-08-01)+- [F08] 喜欢包含具体后续行动的评审意见 (as of 2026-08-01)+- [F09] 小型拉取请求使用 squash 合并 (as of 2026-08-01)+- [F10] 会先运行针对性测试,再运行完整测试套件 (as of 2026-08-01)+- [F11] 比起巧妙抽象,更偏好朴素实现 (as of 2026-08-01)+- [F12] 发布前会记录行为变化 (as of 2026-08-01)+- [F13] 喜欢吃辣味面条 (as of 2026-08-01)+- [F14] 不喜欢苦瓜 (as of 2026-08-01)+- [F15] 喝咖啡不加糖 (as of 2026-08-01)+- [F16] 选择提供素食选项的餐厅 (as of 2026-08-01)+- [F17] 偏好直飞航班 (as of 2026-08-01)+- [F18] 避免乘坐红眼航班 (as of 2026-08-01)+- [F19] 喜欢安静的海滨城市 (as of 2026-08-01)+- [F20] 短途旅行时会轻装出行 (as of 2026-08-01)+- [F21] 喜欢回合制策略游戏 (as of 2026-08-01)+- [F22] 喜欢合作解谜游戏 (as of 2026-08-01)+- [F23] 不喜欢竞技射击游戏 (as of 2026-08-01)+- [F24] 偏好剧情丰富的角色扮演游戏 (as of 2026-08-01)"""+ profile_files = {+ profile_uri: MemoryFile(+ uri=profile_uri,+ memory_type="profile",+ content=profile_content,+ extra_fields={},+ )+ }++ preferences_root = TemplateUtils.render(preferences_schema.directory, {"user_space": "default"})+ oversized_preference_uri = f"{preferences_root}/安德鲁/工作偏好.md"+ status_update_facts = {+ "F25": "偏好状态更新第一行直接说明当前结论和整体进展。",+ "F26": "喜欢状态更新用简短项目符号列出本周期完成事项。",+ "F27": "偏好状态更新将已经完成和仍在进行的工作分开呈现。",+ "F28": "喜欢状态更新为每个进行中事项标注明确负责人。",+ "F29": "偏好状态更新为每个行动项写出预计完成日期。",+ "F30": "喜欢状态更新把已经确认的决定单独放在决定区。",+ "F31": "偏好状态更新把尚未解决的问题单独放在开放问题区。",+ "F32": "喜欢状态更新为关键结论附上可量化的进展证据。",+ "F33": "偏好状态更新明确指出相较上一次更新发生了什么变化。",+ "F34": "喜欢状态更新只保留影响当前进展的必要背景信息。",+ "F35": "偏好状态更新使用一致术语描述相同项目和里程碑。",+ "F36": "喜欢状态更新将阻塞事项放在显眼位置并说明影响。",+ "F37": "偏好状态更新为每个阻塞事项写出解除阻塞的下一步。",+ "F38": "喜欢状态更新在结尾汇总下一周期最重要的三项工作。",+ "F39": "偏好状态更新附上相关任务、文档或结果文件的精确链接。",+ "F40": "喜欢状态更新保持简洁,避免重复已经记录的长篇背景。",+ "F57": "偏好状态更新注明数据统计的时间范围和样本口径。",+ "F58": "喜欢状态更新对风险使用高、中、低三级标识。",+ "F59": "偏好状态更新在需要协助时明确写出请求内容和截止时间。",+ "F60": "喜欢状态更新同时提供人类可读摘要和机器可读附件。",+ }+ test_execution_facts = {+ "F41": "偏好先运行与改动模块直接相关的聚焦测试。",+ "F42": "喜欢聚焦测试通过后再运行受影响子系统的测试套件。",+ "F43": "偏好根据改动风险决定是否继续运行完整测试套件。",+ "F44": "喜欢在测试前先执行快速的静态检查和格式检查。",+ "F45": "偏好缺陷修复附带能够稳定复现原问题的回归测试。",+ "F46": "喜欢每个测试只验证一个清晰的行为结果。",+ "F47": "偏好测试名称直接描述输入条件和预期行为。",+ "F48": "喜欢测试使用固定输入和确定性断言,避免随机波动。",+ "F49": "偏好外部服务测试使用记录好的 mock 数据而不是实时调用。",+ "F50": "喜欢为网络和异步测试设置明确且有限的超时时间。",+ "F51": "偏好并发测试限制工作线程数量以保持结果稳定。",+ "F52": "喜欢在隔离临时目录中运行会生成文件的测试。",+ "F53": "偏好测试失败时输出实际值、预期值和关键上下文。",+ "F54": "喜欢测试保留失败样本的随机种子和输入参数。",+ "F55": "偏好昂贵评估前先运行一个最小冒烟测试。",+ "F56": "喜欢测试命令支持机器可读结果和非交互执行。",+ "F61": "偏好按单元测试、集成测试和端到端测试分层运行。",+ "F62": "喜欢只对涉及的测试文件启用详细调试日志。",+ "F63": "偏好测试完成后检查是否残留临时文件和后台进程。",+ "F64": "喜欢在提交前重复运行曾经不稳定的测试以确认稳定性。",+ }+ existing_growth_facts = {+ **{marker: text for marker, text in status_update_facts.items() if marker <= "F40"},+ **{marker: text for marker, text in test_execution_facts.items() if marker <= "F56"},+ }+ additional_facts = {+ **{marker: text for marker, text in status_update_facts.items() if marker >= "F57"},+ **{marker: text for marker, text in test_execution_facts.items() if marker >= "F61"},+ }+ oversized_preference_content = "\n".join(+ f"- [{marker}] {text}" for marker, text in existing_growth_facts.items()+ )+ additional_fact_text = "\n".join(+ f"- [{marker}] {text}" for marker, text in additional_facts.items()+ )+ oversized_preference_files = {+ oversized_preference_uri: MemoryFile(+ uri=oversized_preference_uri,+ memory_type="preferences",+ content=oversized_preference_content,+ extra_fields={"user": "安德鲁", "topic": "工作偏好"},+ )+ }++ return [+ AutonomousCase(+ case_id="case_insensitive_directory_collision",+ category="directory_merge",+ schemas=(directory_schema,),+ initial_files=directory_files,+ expected_groups={"entities": (frozenset({"F01", "F02", "F03", "F04"}),)},+ expected_replacements={+ f"{directory_root}/Projects/atlas.md": f"{directory_root}/projects/atlas.md"+ },+ messages=(+ Message(+ id="directory-context",+ role="user",+ created_at="2026-08-30T10:00:00+08:00",+ parts=[TextPart("你还记得 Atlas 项目的发布方式、回滚流程和日常运维信息吗?")],+ ),+ ),+ ),+ AutonomousCase(+ case_id="oversized_profile_routes_preferences",+ category="cross_type_split",+ schemas=(profile_schema, preferences_schema),+ initial_files=profile_files,+ expected_groups={+ "profile": (frozenset({"F01", "F02", "F03", "F04", "F05", "F06"}),),+ "preferences": (+ frozenset({"F07", "F08"}),+ frozenset({"F09", "F10", "F11", "F12"}),+ frozenset({"F13", "F14", "F15", "F16"}),+ frozenset({"F17", "F18", "F19", "F20"}),+ frozenset({"F21", "F22", "F23", "F24"}),+ ),+ },+ expected_replacements={},+ maintenance_review_tokens=400,+ messages=(+ Message(+ id="profile-context",+ role="user",+ created_at="2026-08-30T10:00:00+08:00",+ parts=[+ TextPart(+ "你还记得我的基本情况,以及我在工作、饮食、旅行和游戏方面的偏好吗?"+ )+ ],+ ),+ ),+ ),+ AutonomousCase(+ case_id="oversized_preference_splits",+ category="same_type_split",+ schemas=(preferences_schema,),+ initial_files=oversized_preference_files,+ expected_groups={+ "preferences": (+ frozenset(status_update_facts),+ frozenset(test_execution_facts),+ )+ },+ expected_replacements={},+ messages=(+ Message(+ id="growth-update",+ role="user",+ peer_id="安德鲁",+ created_at="2026-08-29T02:30:00+08:00",+ parts=[TextPart("请记住我新增的这些偏好:\n" + additional_fact_text)],+ ),+ ),+ additional_facts=additional_facts,+ ),+ ]diff --git a/benchmark/memory_organization/autonomous_grader.py b/benchmark/memory_organization/autonomous_grader.pynew file mode 100644index 000000000..972609597--- /dev/null+++ b/benchmark/memory_organization/autonomous_grader.py@@ -0,0 +1,216 @@+from __future__ import annotations++import re+from collections import defaultdict++from benchmark.memory_organization.autonomous_cases import AutonomousCase+from benchmark.memory_organization.grader import Grade, _best_partition_intersection+from benchmark.memory_organization.models import fact_lines++_AS_OF_RE = re.compile(r"\s*\(as of \d{4}-\d{2}-\d{2}\)\s*$", re.IGNORECASE)+_MATCHED_SIZE_NOTE_RE = re.compile(+ r"\s*(?:"+ r"(长期稳定)|"+ r"(长期稳定且持续指导未来工作协作)|"+ r"\(a stable long-term preference that guides future work and collaboration\)|"+ r"\(a stable long-term preference that consistently guides future work, collaboration, "+ r"technical decisions, and repeated execution across projects\)"+ r")\s*$",+ re.IGNORECASE,+)+++def _normalized_fact_text(text: str) -> str:+ text = re.sub(r"^\s*(?:[-*]\s*)?(?:\[F\d{2}\]\s*)?", "", text)+ text = _AS_OF_RE.sub("", text)+ text = _MATCHED_SIZE_NOTE_RE.sub("", text)+ return " ".join(text.strip().rstrip(".。").lower().split())+++def _locate_expected_facts(+ case: AutonomousCase, actual_files: dict[str, tuple[str, str]]+) -> dict[str, list[tuple[str, str]]]:+ expected = {marker: _normalized_fact_text(text) for marker, text in case.expected_facts.items()}+ occurrences: dict[str, list[tuple[str, str]]] = defaultdict(list)+ for uri, (memory_type, content) in actual_files.items():+ normalized_lines = {_normalized_fact_text(line) for line in content.splitlines()}+ explicit_facts = {+ marker: _normalized_fact_text(text) for marker, text in fact_lines(content)+ }+ for marker, normalized_fact in expected.items():+ if explicit_facts.get(marker) == normalized_fact or normalized_fact in normalized_lines:+ occurrences[marker].append((memory_type, uri))+ return occurrences+++def grade_autonomous_result(+ case: AutonomousCase,+ actual_files: dict[str, tuple[str, str]],+ actual_replacements: dict[str, str],+) -> Grade:+ expected_facts = case.expected_facts+ occurrences: dict[str, list[str]] = defaultdict(list)+ actual_groups: dict[str, list[set[str]]] = defaultdict(list)+ altered = 0+ unexpected = 0++ for uri, (memory_type, content) in actual_files.items():+ markers: set[str] = set()+ for marker, text in fact_lines(content):+ markers.add(marker)+ occurrences[marker].append(uri)+ if marker not in expected_facts:+ unexpected += 1+ elif expected_facts[marker] != text:+ altered += 1+ actual_groups[memory_type].append(markers)++ expected_markers = set(expected_facts)+ present = {+ marker+ for marker, locations in occurrences.items()+ if locations+ and marker in expected_facts+ and any(+ expected_facts[marker] == text+ for _uri, (_memory_type, content) in actual_files.items()+ for found_marker, text in fact_lines(content)+ if found_marker == marker+ )+ }+ duplicate_count = sum(max(0, len(locations) - 1) for locations in occurrences.values())++ matched = 0+ total_assignments = 0+ exact_group_matches = 0+ expected_file_count = 0+ actual_file_count = len(actual_files)+ partitions_match = set(actual_groups) == set(case.expected_groups)+ for memory_type in set(actual_groups) | set(case.expected_groups):+ expected = [set(group) for group in case.expected_groups.get(memory_type, ())]+ actual = actual_groups.get(memory_type, [])+ matched += _best_partition_intersection(expected, actual)+ total_assignments += sum(len(group) for group in actual)+ expected_file_count += len(expected)+ expected_partition = sorted(tuple(sorted(group)) for group in expected)+ actual_partition = sorted(tuple(sorted(group)) for group in actual)+ exact_group_matches += sum(group in actual_partition for group in expected_partition)+ partitions_match = partitions_match and actual_partition == expected_partition++ placement_precision = matched / total_assignments if total_assignments else 0.0+ file_tree_accuracy = exact_group_matches / max(expected_file_count, actual_file_count, 1)+ missing = len(expected_markers - present)+ misplaced = max(0, total_assignments - matched)+ unexpected_files = max(0, actual_file_count - expected_file_count)++ replacement_checks = [+ actual_replacements.get(source) == target+ for source, target in case.expected_replacements.items()+ ]+ replacement_checks.extend(+ source in case.expected_replacements+ for source in actual_replacements+ if source not in case.expected_replacements+ )+ replacement_accuracy = (+ sum(replacement_checks) / len(replacement_checks) if replacement_checks else 1.0+ )++ content_success = (+ partitions_match+ and actual_file_count == expected_file_count+ and missing == 0+ and misplaced == 0+ and duplicate_count == 0+ and altered == 0+ and unexpected == 0+ )+ return Grade(+ content_organization_success=content_success,+ organization_success=content_success and replacement_accuracy == 1.0,+ file_tree_accuracy=file_tree_accuracy,+ fact_recall=len(present) / len(expected_markers) if expected_markers else 1.0,+ placement_precision=placement_precision,+ replacement_accuracy=replacement_accuracy,+ duplicate_fact_count=duplicate_count,+ altered_fact_count=altered,+ unexpected_fact_count=unexpected,+ misplaced_fact_count=misplaced,+ missing_fact_count=missing,+ unexpected_file_count=unexpected_files,+ )+++def autonomous_metrics(+ case: AutonomousCase,+ actual_files: dict[str, tuple[str, str]],+ actual_replacements: dict[str, str],+ grade: Grade,+) -> dict[str, float | bool]:+ expected_type = {+ marker: memory_type+ for memory_type, groups in case.expected_groups.items()+ for group in groups+ for marker in group+ }+ occurrences = _locate_expected_facts(case, actual_files)+ correctly_routed = sum(+ len(occurrences.get(marker, [])) == 1 and occurrences[marker][0][0] == memory_type+ for marker, memory_type in expected_type.items()+ )+ routing_accuracy = correctly_routed / len(expected_type) if expected_type else 1.0+ information_integrity = all(len(occurrences.get(marker, [])) == 1 for marker in expected_type)++ if case.category == "keep_separate":+ path_normalization_success = True+ expected_partitions = [+ group for groups in case.expected_groups.values() for group in groups+ ]+ partition_uris: list[str] = []+ for group in expected_partitions:+ locations = {+ uri for marker in group for _memory_type, uri in occurrences.get(marker, ())+ }+ if len(locations) == 1:+ partition_uris.append(next(iter(locations)))+ expected_file_count = len(expected_partitions)+ organization_action_success = (+ routing_accuracy == 1.0+ and len(partition_uris) == expected_file_count+ and len(set(partition_uris)) == expected_file_count+ and len(actual_files) == expected_file_count+ and not actual_replacements+ )+ elif case.category == "directory_merge":+ path_normalization_success = bool(actual_files) and all(+ uri == uri.lower() for uri in actual_files+ )+ organization_action_success = (+ len(actual_files) == 1+ and path_normalization_success+ and grade.replacement_accuracy == 1.0+ )+ elif case.category == "same_type_split":+ path_normalization_success = True+ source_uris = set(case.initial_files)+ preference_files = [item for item in actual_files.values() if item[0] == "preferences"]+ organization_action_success = (+ len(preference_files) >= 2+ and len(preference_files) == len(actual_files)+ and source_uris.isdisjoint(actual_files)+ )+ else:+ path_normalization_success = True+ profile_uris = {uri for uri, item in actual_files.items() if item[0] == "profile"}+ preference_uris = {uri for uri, item in actual_files.items() if item[0] == "preferences"}+ allowed_types = {"profile", "preferences"}+ organization_action_success = (+ all(item[0] in allowed_types for item in actual_files.values())+ and len(profile_uris) == 1+ and len(preference_uris) >= 1+ )++ return {+ "organization_action_success": organization_action_success,+ "information_integrity": information_integrity,+ }diff --git a/benchmark/memory_organization/cases/organization_cases.json b/benchmark/memory_organization/cases/organization_cases.jsonnew file mode 100644index 000000000..abd3399c5--- /dev/null+++ b/benchmark/memory_organization/cases/organization_cases.json@@ -0,0 +1,157 @@+[+ {+ "case_id": "merge_travel_aliases",+ "category": "merge",+ "canonical_topics": ["travel"],+ "initial_files": {+ "travel": "[F01] Prefers quiet mountain towns.",+ "trip_ideas": "[F02] Wants direct flights when possible.",+ "vacation": "[F03] Avoids crowded resorts."+ },+ "expected_files": {"travel": ["F01", "F02", "F03"]},+ "expected_replacements": {"travel": "travel", "trip_ideas": "travel", "vacation": "travel"}+ },+ {+ "case_id": "merge_pet_care_new_canonical",+ "category": "merge",+ "canonical_topics": ["pet_care"],+ "initial_files": {+ "dog_safety": "[F01] Uses protective boots on long hikes.",+ "dog_wellness": "[F02] Prioritizes daily exercise for dogs.",+ "pet_routine": "[F03] Brushes dogs every evening."+ },+ "expected_files": {"pet_care": ["F01", "F02", "F03"]},+ "expected_replacements": {+ "dog_safety": "pet_care",+ "dog_wellness": "pet_care",+ "pet_routine": "pet_care"+ }+ },+ {+ "case_id": "merge_entity_aliases",+ "category": "merge",+ "canonical_topics": ["john_smith"],+ "initial_files": {+ "john_smith": "[F01] John is a mechanical engineer.",+ "john": "[F02] John lives in Boston.",+ "j_smith": "[F03] John mentors junior engineers."+ },+ "expected_files": {"john_smith": ["F01", "F02", "F03"]},+ "expected_replacements": {"john_smith": "john_smith", "john": "john_smith", "j_smith": "john_smith"}+ },+ {+ "case_id": "merge_workflow_duplicates",+ "category": "merge",+ "canonical_topics": ["workflow"],+ "initial_files": {+ "workflow": "[F01] Prefers small reviewable pull requests.",+ "work_habits": "[F02] Runs focused tests before broad suites.",+ "development_process": "[F03] Documents behavioral changes."+ },+ "expected_files": {"workflow": ["F01", "F02", "F03"]},+ "expected_replacements": {+ "workflow": "workflow",+ "work_habits": "workflow",+ "development_process": "workflow"+ }+ },+ {+ "case_id": "split_food_and_travel",+ "category": "split",+ "canonical_topics": ["food", "travel"],+ "initial_files": {+ "mixed": "[F01] Loves spicy noodles.\n[F02] Prefers overnight trains.\n[F03] Avoids shellfish.\n[F04] Likes historic cities."+ },+ "expected_files": {"food": ["F01", "F03"], "travel": ["F02", "F04"]},+ "expected_replacements": {}+ },+ {+ "case_id": "split_people_and_pet",+ "category": "split",+ "canonical_topics": ["john", "maria", "max"],+ "initial_files": {+ "people_and_pet": "[F01] John is a teacher.\n[F02] Maria is a nurse.\n[F03] Max is a golden retriever.\n[F04] Maria lives in Toronto."+ },+ "expected_files": {"john": ["F01"], "maria": ["F02", "F04"], "max": ["F03"]},+ "expected_replacements": {}+ },+ {+ "case_id": "split_large_preferences",+ "category": "split",+ "canonical_topics": ["food", "games", "workflow"],+ "initial_files": {+ "preferences": "[F01] Likes mango desserts.\n[F02] Enjoys turn-based strategy games.\n[F03] Uses squash merges.\n[F04] Dislikes bitter melon.\n[F05] Prefers concise code reviews.\n[F06] Loves cooperative puzzle games."+ },+ "expected_files": {+ "food": ["F01", "F04"],+ "games": ["F02", "F06"],+ "workflow": ["F03", "F05"]+ },+ "expected_replacements": {}+ },+ {+ "case_id": "split_work_and_personal",+ "category": "split",+ "canonical_topics": ["career", "wellbeing"],+ "initial_files": {+ "catchall": "[F01] Works as a data engineer.\n[F02] Uses evening walks to decompress.\n[F03] Wants to lead a platform team.\n[F04] Practices meditation every morning."+ },+ "expected_files": {"career": ["F01", "F03"], "wellbeing": ["F02", "F04"]},+ "expected_replacements": {}+ },+ {+ "case_id": "mixed_merge_travel_split_food",+ "category": "mixed",+ "canonical_topics": ["travel", "food"],+ "initial_files": {+ "travel": "[F01] Prefers rail travel.",+ "vacation": "[F02] Avoids crowded destinations.",+ "mixed": "[F03] Loves sour soup.\n[F04] Likes walking tours."+ },+ "expected_files": {"travel": ["F01", "F02", "F04"], "food": ["F03"]},+ "expected_replacements": {"travel": "travel", "vacation": "travel"}+ },+ {+ "case_id": "mixed_merge_person_extract_pet",+ "category": "mixed",+ "canonical_topics": ["john", "max"],+ "initial_files": {+ "john": "[F01] John is a teacher.\n[F03] Max is John's dog.",+ "john_smith": "[F02] John lives in Boston.\n[F04] Max is a golden retriever."+ },+ "expected_files": {"john": ["F01", "F02"], "max": ["F03", "F04"]},+ "expected_replacements": {}+ },+ {+ "case_id": "mixed_merge_workflow_split_communication",+ "category": "mixed",+ "canonical_topics": ["workflow", "communication"],+ "initial_files": {+ "workflow": "[F01] Prefers incremental changes.",+ "dev_process": "[F02] Runs focused tests first.",+ "mixed": "[F03] Wants concise status updates.\n[F04] Documents rollout impact."+ },+ "expected_files": {+ "workflow": ["F01", "F02", "F04"],+ "communication": ["F03"]+ },+ "expected_replacements": {"workflow": "workflow", "dev_process": "workflow"}+ },+ {+ "case_id": "mixed_reorganize_catchall_and_alias",+ "category": "mixed",+ "canonical_topics": ["food", "travel", "games", "workflow"],+ "initial_files": {+ "travel": "[F01] Prefers direct flights.",+ "trip_notes": "[F02] Likes coastal cities.",+ "catchall": "[F03] Loves dumplings.\n[F04] Plays cooperative games.\n[F05] Uses rebase before merging.\n[F06] Avoids red-eye flights.\n[F07] Dislikes cilantro.\n[F08] Enjoys story-rich games."+ },+ "expected_files": {+ "food": ["F03", "F07"],+ "travel": ["F01", "F02", "F06"],+ "games": ["F04", "F08"],+ "workflow": ["F05"]+ },+ "expected_replacements": {"travel": "travel", "trip_notes": "travel"}+ }+]diff --git a/benchmark/memory_organization/cases/organization_stress_cases.json b/benchmark/memory_organization/cases/organization_stress_cases.jsonnew file mode 100644index 000000000..2abf2f634--- /dev/null+++ b/benchmark/memory_organization/cases/organization_stress_cases.json@@ -0,0 +1,67 @@+[+ {+ "case_id": "oversized_split_engineering_domains",+ "category": "oversized_split",+ "max_fact_lines_per_file": 6,+ "canonical_topics": ["frontend", "backend", "database", "reliability"],+ "initial_files": {+ "engineering_notes": "[F01] Uses semantic HTML for page structure.\n[F02] Keeps client state close to its owner.\n[F03] Tests keyboard navigation for dialogs.\n[F04] Avoids layout shifts during loading.\n[F05] Measures bundle size before releases.\n[F06] Uses design tokens for shared colors.\n[F07] Validates API inputs at service boundaries.\n[F08] Uses idempotency keys for retried writes.\n[F09] Keeps domain logic outside transport handlers.\n[F10] Applies timeouts to outbound requests.\n[F11] Uses structured errors for API failures.\n[F12] Runs focused contract tests before deployment.\n[F13] Adds indexes for measured query patterns.\n[F14] Uses transactions for multi-row invariants.\n[F15] Reviews query plans for slow endpoints.\n[F16] Keeps schema migrations backward compatible during rollout.\n[F17] Enforces foreign keys for ownership relations.\n[F18] Archives old partitions after retention windows.\n[F19] Defines service-level objectives for critical paths.\n[F20] Uses bounded retries with exponential backoff.\n[F21] Alerts on sustained user-visible error rates.\n[F22] Practices recovery procedures with failure drills.\n[F23] Caps queues to prevent unbounded memory growth.\n[F24] Tracks tail latency separately from averages."+ },+ "expected_files": {+ "frontend": ["F01", "F02", "F03", "F04", "F05", "F06"],+ "backend": ["F07", "F08", "F09", "F10", "F11", "F12"],+ "database": ["F13", "F14", "F15", "F16", "F17", "F18"],+ "reliability": ["F19", "F20", "F21", "F22", "F23", "F24"]+ },+ "expected_replacements": {}+ },+ {+ "case_id": "oversized_merge_many_aliases",+ "category": "oversized_merge",+ "canonical_topics": ["workflow"],+ "initial_files": {+ "workflow": "[F01] Keeps pull requests small.\n[F02] Requests review before merging.\n[F03] Links changes to their issue.",+ "review_habits": "[F04] Explains non-obvious tradeoffs.\n[F05] Responds to review comments directly.\n[F06] Resolves discussions after changes land.",+ "testing_process": "[F07] Runs unit tests before integration tests.\n[F08] Adds regression tests for fixed bugs.\n[F09] Records flaky tests instead of ignoring them.",+ "release_process": "[F10] Uses staged rollouts for risky changes.\n[F11] Documents rollback steps.\n[F12] Watches error rates after release.",+ "coding_habits": "[F13] Prefers straightforward implementations.\n[F14] Reuses existing utilities.\n[F15] Avoids speculative abstractions.",+ "debugging_process": "[F16] Reproduces failures before editing.\n[F17] Traces the full data path.\n[F18] Verifies the root cause with a focused test.",+ "documentation_process": "[F19] Updates examples when interfaces change.\n[F20] Notes behavioral changes in release summaries.\n[F21] Keeps commands copy-pasteable.",+ "delivery_habits": "[F22] Checks the final diff for unrelated edits.\n[F23] Runs formatting checks before handoff.\n[F24] Reports known limitations explicitly."+ },+ "expected_files": {+ "workflow": ["F01", "F02", "F03", "F04", "F05", "F06", "F07", "F08", "F09", "F10", "F11", "F12", "F13", "F14", "F15", "F16", "F17", "F18", "F19", "F20", "F21", "F22", "F23", "F24"]+ },+ "expected_replacements": {+ "workflow": "workflow",+ "review_habits": "workflow",+ "testing_process": "workflow",+ "release_process": "workflow",+ "coding_habits": "workflow",+ "debugging_process": "workflow",+ "documentation_process": "workflow",+ "delivery_habits": "workflow"+ }+ },+ {+ "case_id": "oversized_mixed_reorganization",+ "category": "oversized_mixed",+ "max_fact_lines_per_file": 8,+ "canonical_topics": ["travel", "food", "games", "workflow", "wellbeing", "books"],+ "initial_files": {+ "travel": "[F01] Prefers direct flights.\n[F02] Likes coastal cities.\n[F03] Packs light for short trips.\n[F04] Avoids red-eye flights.",+ "trip_notes": "[F05] Uses rail for regional travel.\n[F06] Books refundable hotels.\n[F07] Visits museums early.\n[F08] Keeps digital copies of tickets.",+ "preferences_a": "[F09] Loves spicy noodles.\n[F10] Avoids shellfish.\n[F11] Makes coffee at home.\n[F12] Likes seasonal fruit.\n[F13] Plays cooperative puzzle games.\n[F14] Enjoys turn-based strategy games.\n[F15] Avoids competitive shooters.\n[F16] Likes story-rich role-playing games.\n[F17] Uses squash merges.\n[F18] Runs focused tests first.\n[F19] Writes concise review comments.\n[F20] Documents rollout risks.",+ "preferences_b": "[F21] Walks after dinner to decompress.\n[F22] Practices meditation each morning.\n[F23] Protects weekends from work.\n[F24] Keeps a consistent sleep schedule.\n[F25] Reads historical fiction.\n[F26] Enjoys short science essays.\n[F27] Borrows books from the library.\n[F28] Keeps notes on finished books.\n[F29] Prefers dumplings with vinegar.\n[F30] Plays local co-op games with friends.\n[F31] Rebases branches before merging.\n[F32] Uses breathing exercises during stressful days."+ },+ "expected_files": {+ "travel": ["F01", "F02", "F03", "F04", "F05", "F06", "F07", "F08"],+ "food": ["F09", "F10", "F11", "F12", "F29"],+ "games": ["F13", "F14", "F15", "F16", "F30"],+ "workflow": ["F17", "F18", "F19", "F20", "F31"],+ "wellbeing": ["F21", "F22", "F23", "F24", "F32"],+ "books": ["F25", "F26", "F27", "F28"]+ },+ "expected_replacements": {"travel": "travel", "trip_notes": "travel"}+ }+]diff --git a/benchmark/memory_organization/grader.py b/benchmark/memory_organization/grader.pynew file mode 100644index 000000000..841bf0722--- /dev/null+++ b/benchmark/memory_organization/grader.py@@ -0,0 +1,228 @@+from __future__ import annotations++from dataclasses import asdict, dataclass+from itertools import permutations+from statistics import mean+from typing import Any++from benchmark.memory_organization.models import OrganizationCase, fact_lines, fact_markers+++@dataclass(frozen=True, slots=True)+class Grade:+ content_organization_success: bool+ organization_success: bool+ file_tree_accuracy: float+ fact_recall: float+ placement_precision: float+ replacement_accuracy: float+ duplicate_fact_count: int+ altered_fact_count: int+ unexpected_fact_count: int+ misplaced_fact_count: int+ missing_fact_count: int+ unexpected_file_count: int++ def to_dict(self) -> dict[str, Any]:+ return asdict(self)+++def grade_result(+ case: OrganizationCase,+ actual_files: dict[str, str],+ actual_replacements: dict[str, str] | None = None,+) -> Grade:+ occurrences: dict[str, list[str]] = {}+ actual_groups: dict[str, set[str]] = {}+ for topic, content in actual_files.items():+ markers = fact_markers(content)+ actual_groups[topic] = set(markers)+ for marker in markers:+ occurrences.setdefault(marker, []).append(topic)++ expected_facts = {+ marker: text+ for content in case.initial_files.values()+ for marker, text in fact_lines(content)+ }+ actual_fact_lines = [+ (topic, marker, text)+ for topic, content in actual_files.items()+ for marker, text in fact_lines(content)+ ]+ valid_fact_markers = {+ marker for _topic, marker, text in actual_fact_lines if expected_facts.get(marker) == text+ }+ altered_facts = sum(+ marker in expected_facts and expected_facts[marker] != text+ for _topic, marker, text in actual_fact_lines+ )+ unexpected_facts = sum(+ marker not in expected_facts for _topic, marker, _text in actual_fact_lines+ )++ expected_markers = case.expected_markers+ expected_groups = {topic: set(markers) for topic, markers in case.expected_files.items()}+ present = expected_markers & valid_fact_markers+ fact_recall = len(present) / len(expected_markers) if expected_markers else 1.0++ # File names are model-chosen and may have valid aliases (food vs+ # food_preferences). Score the partition of facts, not literal topic names.+ expected_sets = list(expected_groups.values())+ actual_items = [(topic, markers) for topic, markers in actual_groups.items() if markers]+ actual_sets = [markers for _topic, markers in actual_items]+ matched_intersections = _best_partition_intersection(expected_sets, actual_sets)+ # Count unique fact-to-file assignments for placement. Repeated occurrences+ # within one file are reported separately as duplicates, not double-counted+ # as placement errors.+ total_assignments = sum(len(markers) for markers in actual_sets)+ placement_precision = matched_intersections / total_assignments if total_assignments else 0.0+ misplaced = max(0, total_assignments - matched_intersections)+ duplicates = sum(max(0, len(topics) - 1) for topics in occurrences.values())++ expected_partition = sorted(tuple(sorted(group)) for group in expected_sets)+ actual_partition = sorted(tuple(sorted(group)) for group in actual_sets)+ exact_group_matches = sum(group in actual_partition for group in expected_partition)+ file_tree_accuracy = exact_group_matches / max(+ len(expected_partition), len(actual_partition), 1+ )++ expected_replacements = case.expected_replacements+ actual_replacements = actual_replacements or {}+ replacement_checks: list[bool] = []+ for source, expected_target in expected_replacements.items():+ target_group = expected_groups[expected_target]+ actual_targets = {+ topic for topic, markers in actual_groups.items() if markers == target_group+ }+ if source in actual_targets:+ replacement_checks.append(source not in actual_replacements)+ else:+ replacement_checks.append(actual_replacements.get(source) in actual_targets)+ replacement_checks.extend(+ source in expected_replacements+ for source in actual_replacements+ if source not in expected_replacements+ )+ replacement_accuracy = (+ sum(replacement_checks) / len(replacement_checks) if replacement_checks else 1.0+ )++ missing = len(expected_markers - present)+ unexpected_files = max(0, len(actual_files) - len(expected_sets))+ content_organization_success = (+ actual_partition == expected_partition+ and len(actual_files) == len(expected_sets)+ and missing == 0+ and misplaced == 0+ and duplicates == 0+ and altered_facts == 0+ and unexpected_facts == 0+ )+ organization_success = content_organization_success and replacement_accuracy == 1.0+ return Grade(+ content_organization_success=content_organization_success,+ organization_success=organization_success,+ file_tree_accuracy=file_tree_accuracy,+ fact_recall=fact_recall,+ placement_precision=placement_precision,+ replacement_accuracy=replacement_accuracy,+ duplicate_fact_count=duplicates,+ altered_fact_count=altered_facts,+ unexpected_fact_count=unexpected_facts,+ misplaced_fact_count=misplaced,+ missing_fact_count=missing,+ unexpected_file_count=unexpected_files,+ )+++def _best_partition_intersection(expected: list[set[str]], actual: list[set[str]]) -> int:+ """Maximum marker overlap under a one-to-one expected/actual file assignment."""+ if not expected or not actual:+ return 0+ if len(expected) <= len(actual):+ return max(+ sum(len(expected[index] & actual[actual_index]) for index, actual_index in enumerate(p))+ for p in permutations(range(len(actual)), len(expected))+ )+ return max(+ sum(len(expected[expected_index] & actual[index]) for index, expected_index in enumerate(p))+ for p in permutations(range(len(expected)), len(actual))+ )+++def summarize(rows: list[dict[str, Any]]) -> dict[str, Any]:+ by_protocol: dict[str, list[dict[str, Any]]] = {}+ for row in rows:+ by_protocol.setdefault(str(row["protocol"]), []).append(row)+ summary: dict[str, Any] = {}+ for protocol, protocol_rows in by_protocol.items():+ graded = [row for row in protocol_rows if "grade" in row]+ summary[protocol] = {+ "runs": len(protocol_rows),+ "content_organization_success_rate": mean(+ float(row["grade"]["content_organization_success"]) for row in graded+ )+ if graded+ else 0.0,+ "organization_success_rate": mean(+ float(row["grade"]["organization_success"]) for row in graded+ )+ if graded+ else 0.0,+ "file_tree_accuracy": mean(row["grade"]["file_tree_accuracy"] for row in graded)+ if graded+ else 0.0,+ "fact_recall": mean(row["grade"]["fact_recall"] for row in graded) if graded else 0.0,+ "placement_precision": mean(row["grade"]["placement_precision"] for row in graded)+ if graded+ else 0.0,+ "mean_calls": mean(row.get("calls", 0) for row in protocol_rows),+ "mean_retries": mean(row.get("retries", 0) for row in protocol_rows),+ "mean_prompt_tokens": mean(row.get("prompt_tokens", 0) for row in protocol_rows),+ "mean_completion_tokens": mean(+ row.get("completion_tokens", 0) for row in protocol_rows+ ),+ "mean_total_tokens": mean(row.get("total_tokens", 0) for row in protocol_rows),+ "mean_duration_seconds": mean(+ row.get("duration_seconds", 0.0) for row in protocol_rows+ ),+ "terminal_error_rate": mean(bool(row.get("terminal_error")) for row in protocol_rows),+ }+ return summary+++def paired_counts(+ rows: list[dict[str, Any]], *, metric: str = "organization_success"+) -> dict[str, int]:+ grouped: dict[tuple[str, int], dict[str, bool]] = {}+ for row in rows:+ key = (str(row["case_id"]), int(row["repeat_index"]))+ grouped.setdefault(key, {})[str(row["protocol"])] = bool(row.get("grade", {}).get(metric))+ counts = {"both_success": 0, "python_only": 0, "json_only": 0, "both_fail": 0}+ for pair in grouped.values():+ if set(pair) != {"json", "python"}:+ continue+ py, js = pair["python"], pair["json"]+ if py and js:+ counts["both_success"] += 1+ elif py:+ counts["python_only"] += 1+ elif js:+ counts["json_only"] += 1+ else:+ counts["both_fail"] += 1+ return counts+++def mcnemar_exact_p_value(counts: dict[str, int]) -> float:+ """Two-sided exact McNemar p-value for discordant paired outcomes."""+ from math import comb++ left = counts["python_only"]+ right = counts["json_only"]+ discordant = left + right+ if discordant == 0:+ return 1.0+ tail = sum(comb(discordant, index) for index in range(min(left, right) + 1))+ return min(1.0, 2.0 * tail / (2**discordant))diff --git a/benchmark/memory_organization/models.py b/benchmark/memory_organization/models.pynew file mode 100644index 000000000..799078389--- /dev/null+++ b/benchmark/memory_organization/models.py@@ -0,0 +1,67 @@+from __future__ import annotations++import json+import re+from dataclasses import dataclass+from pathlib import Path+from typing import Any++_FACT_RE = re.compile(r"\[(F\d{2})\]")+++@dataclass(frozen=True, slots=True)+class OrganizationCase:+ case_id: str+ category: str+ canonical_topics: tuple[str, ...]+ initial_files: dict[str, str]+ expected_files: dict[str, tuple[str, ...]]+ expected_replacements: dict[str, str]+ max_fact_lines_per_file: int | None = None++ @classmethod+ def from_dict(cls, data: dict[str, Any]) -> "OrganizationCase":+ return cls(+ case_id=str(data["case_id"]),+ category=str(data["category"]),+ canonical_topics=tuple(data["canonical_topics"]),+ initial_files={str(k): str(v) for k, v in data["initial_files"].items()},+ expected_files={+ str(topic): tuple(str(marker) for marker in markers)+ for topic, markers in data["expected_files"].items()+ },+ expected_replacements={+ str(k): str(v) for k, v in data.get("expected_replacements", {}).items()+ },+ max_fact_lines_per_file=(+ int(data["max_fact_lines_per_file"])+ if data.get("max_fact_lines_per_file") is not None+ else None+ ),+ )++ @property+ def expected_markers(self) -> set[str]:+ return {marker for markers in self.expected_files.values() for marker in markers}+++def load_cases(path: Path) -> list[OrganizationCase]:+ return [OrganizationCase.from_dict(item) for item in json.loads(path.read_text())]+++def fact_markers(content: str) -> list[str]:+ return _FACT_RE.findall(content or "")+++def fact_lines(content: str) -> list[tuple[str, str]]:+ """Return marker/fact pairs while ignoring optional Markdown bullets."""+ records: list[tuple[str, str]] = []+ for line in (content or "").splitlines():+ match = re.match(r"^\s*(?:[-*]\s*)?\[(F\d{2})\]\s*(.*?)\s*$", line)+ if match:+ records.append((match.group(1), " ".join(match.group(2).split())))+ return records+++def topic_from_uri(uri: str) -> str:+ return Path(uri).stemdiff --git a/benchmark/memory_organization/report.py b/benchmark/memory_organization/report.pynew file mode 100644index 000000000..5caf47088--- /dev/null+++ b/benchmark/memory_organization/report.py@@ -0,0 +1,51 @@+#!/usr/bin/env python3+from __future__ import annotations++import argparse+import json+from pathlib import Path++from benchmark.memory_organization.grader import mcnemar_exact_p_value, paired_counts, summarize+++def paired_report(rows: list[dict], *, metric: str) -> dict:+ counts = paired_counts(rows, metric=metric)+ return {**counts, "mcnemar_exact_p_value": mcnemar_exact_p_value(counts)}+++def main() -> None:+ parser = argparse.ArgumentParser()+ parser.add_argument("input")+ parser.add_argument("--output", help="Optional path for the JSON summary")+ args = parser.parse_args()+ rows = [json.loads(line) for line in Path(args.input).read_text().splitlines() if line.strip()]+ categories = sorted({str(row["category"]) for row in rows})+ result = {+ "summary": summarize(rows),+ "paired": paired_report(rows, metric="organization_success"),+ "paired_content": paired_report(rows, metric="content_organization_success"),+ "by_category": {+ category: {+ "summary": summarize([row for row in rows if str(row["category"]) == category]),+ "paired": paired_report(+ [row for row in rows if str(row["category"]) == category],+ metric="organization_success",+ ),+ "paired_content": paired_report(+ [row for row in rows if str(row["category"]) == category],+ metric="content_organization_success",+ ),+ }+ for category in categories+ },+ }+ rendered = json.dumps(result, ensure_ascii=False, indent=2)+ if args.output:+ output = Path(args.output)+ output.parent.mkdir(parents=True, exist_ok=True)+ output.write_text(rendered + "\n")+ print(rendered)+++if __name__ == "__main__":+ main()diff --git a/benchmark/memory_organization/report_autonomous.py b/benchmark/memory_organization/report_autonomous.pynew file mode 100644index 000000000..b4da68df9--- /dev/null+++ b/benchmark/memory_organization/report_autonomous.py@@ -0,0 +1,121 @@+#!/usr/bin/env python3+from __future__ import annotations++import argparse+import json+from collections import defaultdict+from pathlib import Path+from statistics import mean+from typing import Any++from benchmark.memory_organization.autonomous_cases import build_cases+from benchmark.memory_organization.autonomous_grader import (+ autonomous_metrics,+ grade_autonomous_result,+)+from benchmark.memory_organization.grader import mcnemar_exact_p_value++PRIMARY_METRICS = ("organization_action_success", "information_integrity")+CASE_ID_ALIASES = {"oversized_preference_splits_into_two": "oversized_preference_splits"}+++def regrade_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:+ cases = {case.case_id: case for case in build_cases()}+ regraded = []+ for row in rows:+ row_case_id = str(row["case_id"])+ case = cases.get(CASE_ID_ALIASES.get(row_case_id, row_case_id))+ if case is None:+ regraded.append(row)+ continue+ files = {+ uri: (str(item["memory_type"]), str(item["content"]))+ for uri, item in row["actual_files"].items()+ }+ replacements = {str(key): str(value) for key, value in row["actual_replacements"].items()}+ grade = grade_autonomous_result(case, files, replacements)+ regraded.append(+ {+ **row,+ "case_id": case.case_id,+ "grade": grade.to_dict(),+ "autonomous_metrics": autonomous_metrics(case, files, replacements, grade),+ }+ )+ return regraded+++def summarize_autonomous(rows: list[dict[str, Any]]) -> dict[str, Any]:+ result: dict[str, Any] = {}+ for case_id in sorted({str(row["case_id"]) for row in rows}):+ case_rows = [row for row in rows if row["case_id"] == case_id]+ protocol_summary = {}+ for protocol in ("json", "python"):+ protocol_rows = [row for row in case_rows if row["protocol"] == protocol]+ if not protocol_rows:+ continue+ protocol_summary[protocol] = {+ "runs": len(protocol_rows),+ "organization_action_success_rate": mean(+ row["autonomous_metrics"]["organization_action_success"]+ for row in protocol_rows+ ),+ "information_integrity_rate": mean(+ row["autonomous_metrics"]["information_integrity"] for row in protocol_rows+ ),+ }+ result[case_id] = {+ "summary": protocol_summary,+ "paired": {metric: _paired_metric(case_rows, metric) for metric in PRIMARY_METRICS},+ }+ return result+++def _paired_metric(rows: list[dict[str, Any]], metric: str) -> dict[str, int | float]:+ pairs: dict[int, dict[str, bool]] = defaultdict(dict)+ for row in rows:+ pairs[int(row["repeat_index"])][str(row["protocol"])] = bool(+ row["autonomous_metrics"][metric]+ )+ counts = {"both_success": 0, "python_only": 0, "json_only": 0, "both_fail": 0}+ for pair in pairs.values():+ if set(pair) != {"json", "python"}:+ continue+ python_success = pair["python"]+ json_success = pair["json"]+ key = (+ "both_success"+ if python_success and json_success+ else "python_only"+ if python_success+ else "json_only"+ if json_success+ else "both_fail"+ )+ counts[key] += 1+ return {**counts, "mcnemar_exact_p_value": mcnemar_exact_p_value(counts)}+++def main() -> None:+ parser = argparse.ArgumentParser()+ parser.add_argument("inputs", nargs="+")+ parser.add_argument("--output")+ args = parser.parse_args()+ rows = regrade_rows(+ [+ json.loads(line)+ for input_path in args.inputs+ for line in Path(input_path).read_text().splitlines()+ if line.strip()+ ]+ )+ rendered = json.dumps(summarize_autonomous(rows), ensure_ascii=False, indent=2)+ if args.output:+ output = Path(args.output)+ output.parent.mkdir(parents=True, exist_ok=True)+ output.write_text(rendered + "\n")+ print(rendered)+++if __name__ == "__main__":+ main()diff --git a/benchmark/memory_organization/run_ab.py b/benchmark/memory_organization/run_ab.pynew file mode 100644index 000000000..843c708c3--- /dev/null+++ b/benchmark/memory_organization/run_ab.py@@ -0,0 +1,290 @@+#!/usr/bin/env python3+from __future__ import annotations++import argparse+import asyncio+import json+import os+import time+from pathlib import Path+from typing import Any++from benchmark.memory_organization.grader import grade_result+from benchmark.memory_organization.models import OrganizationCase, load_cases, topic_from_uri++ROOT = Path(__file__).resolve().parent+DEFAULT_CASES = ROOT / "cases" / "organization_cases.json"+++class FixtureProvider:+ def __init__(self, case: OrganizationCase, schema: Any, memory_files: dict[str, Any]) -> None:+ from openviking.session.memory.memory_updater import ExtractContext+ from openviking.session.memory.page_id_map import PageIdMap++ self.case = case+ self.schema = schema+ self.read_file_contents = memory_files+ self._extract_context = ExtractContext([])+ self._extract_context.page_id_map = PageIdMap()++ def instruction(self) -> str:+ return (+ "Maintain the existing memory collection according to its schema. Decide whether any "+ "files should remain unchanged, be merged, or be split; the number and names of final "+ "files are your decision. Preserve every complete [Fxx] fact line exactly once and do "+ "not invent facts. Delete superseded source files. When multiple files merge into one "+ "unambiguous successor, use that survivor as the replacement so links can be inherited; "+ "a source split across multiple successors has no replacement. Choose concise lowercase "+ "snake_case topics. An empty operation plan is valid when the collection already satisfies "+ "the schema. Output only the required final operation protocol."+ )++ def get_memory_schemas(self, ctx: Any) -> list[Any]:+ del ctx+ return [self.schema]++ def get_output_language(self) -> str:+ return "en"++ def get_tools(self) -> list[str]:+ return []++ def get_extract_context(self) -> Any:+ return self._extract_context++ async def prefetch(self) -> list[dict[str, Any]]:+ from openviking.session.memory.tools import add_tool_call_pair_to_messages++ messages: list[dict[str, Any]] = [+ {+ "role": "user",+ "content": (+ f"Memory maintenance case {self.case.case_id}. Review all files below as one "+ "atomic collection. Fact markers [Fxx] are immutable grading anchors."+ ),+ }+ ]+ for call_id, (uri, memory_file) in enumerate(self.read_file_contents.items(), start=1):+ page_id = self._extract_context.page_id_map.get_page_id(uri)+ result = memory_file.to_metadata()+ result["page_id"] = page_id+ add_tool_call_pair_to_messages(+ messages,+ call_id=call_id,+ tool_name="read",+ params={"uri": uri},+ result=result,+ )+ return messages++ async def execute_tool(self, tool_call: Any) -> dict[str, str]:+ return {"error": f"File not found: {tool_call.arguments.get('uri', '')}"}+++class FixtureIsolationHandler:+ def get_read_scope(self) -> Any:+ from openviking.session.memory.memory_isolation_handler import RoleScope++ return RoleScope(user_ids=[], peer_ids=[])++ def fill_identity_fields(self, item_dict: dict[str, Any], **kwargs: Any) -> None:+ del kwargs+ item_dict.pop("peer_id", None)++ def calculate_memory_uris(+ self,+ *,+ memory_type_schema: Any,+ operation: Any,+ extract_context: Any,+ ) -> list[str]:+ del extract_context+ topic = str(operation.memory_fields["topic"])+ return [f"{memory_type_schema.directory}/{topic}.md"]+++def build_schema(case: OrganizationCase) -> Any:+ from openviking.session.memory.dataclass import MemoryField, MemoryTypeSchema+ from openviking.session.memory.merge_op import FieldType, MergeOp++ size_rule = (+ f" A file may contain at most {case.max_fact_lines_per_file} [Fxx] fact lines. "+ "If it exceeds that limit, reorganize it into coherent files that each fit the limit."+ if case.max_fact_lines_per_file is not None+ else ""+ )+ return MemoryTypeSchema(+ memory_type="records",+ description=(+ "A collection of topic-focused memory files. Each file must cover exactly one "+ "coherent topic. Merge aliases and split mixed files. Preserve [Fxx] markers."+ + size_rule+ ),+ directory="viking://user/default/memories/records",+ filename_template="{{ topic }}.md",+ peer_enabled=False,+ fields=[+ MemoryField(+ name="topic",+ field_type=FieldType.STRING,+ merge_op=MergeOp.IMMUTABLE,+ description="Canonical lowercase snake_case topic used as the filename.",+ ),+ MemoryField(+ name="content",+ field_type=FieldType.STRING,+ merge_op=MergeOp.REPLACE,+ description=(+ "Complete content for exactly one topic. Preserve every source [Fxx] marker "+ "verbatim and include each marker once."+ ),+ ),+ ],+ )+++def build_memory_files(case: OrganizationCase, schema: Any) -> dict[str, Any]:+ from openviking.session.memory.dataclass import MemoryFile++ return {+ f"{schema.directory}/{topic}.md": MemoryFile(+ uri=f"{schema.directory}/{topic}.md",+ memory_type=schema.memory_type,+ content=content,+ extra_fields={"topic": topic},+ )+ for topic, content in case.initial_files.items()+ }+++def materialize(+ case: OrganizationCase,+ operations: Any,+) -> tuple[dict[str, str], dict[str, str]]:+ files = dict(case.initial_files)+ for memory_file in operations.delete_file_contents:+ if memory_file.uri:+ files.pop(topic_from_uri(memory_file.uri), None)+ for operation in operations.upsert_operations:+ topic = str(operation.memory_fields["topic"])+ files[topic] = str(operation.memory_fields.get("content") or "")+ replacements = {+ topic_from_uri(source): topic_from_uri(target)+ for source, target in operations.delete_replacements.items()+ }+ return files, replacements+++def _call_count(usage: dict[str, Any]) -> int:+ """Sum model call counts because TokenUsageTracker.total_usage omits call_count."""+ return sum(+ int(model.get("total_usage", {}).get("call_count", 0))+ for model in usage.get("usage_by_model", {}).values()+ )+++async def run_one(case: OrganizationCase, protocol: str, repeat_index: int, config: Any) -> dict:+ from openviking.session.memory.extract_loop import ExtractLoop++ schema = build_schema(case)+ memory_files = build_memory_files(case, schema)+ provider = FixtureProvider(case, schema, memory_files)+ isolation = FixtureIsolationHandler()+ config.memory.extraction_output_format = protocol+ config.memory.link_enabled = False+ vlm = config.vlm.get_vlm_instance()+ vlm.reset_token_usage()+ loop = ExtractLoop(+ vlm=vlm,+ viking_fs=object(),+ context_provider=provider,+ isolation_handler=isolation,+ max_iterations=3,+ thinking=False,+ )+ started = time.perf_counter()+ terminal_error = ""+ try:+ operations, _ = await loop.run()+ files, replacements = materialize(case, operations)+ grade = grade_result(case, files, replacements)+ terminal_error = "; ".join(operations.errors)+ except Exception as exc:+ files, replacements = dict(case.initial_files), {}+ grade = grade_result(case, files, replacements)+ terminal_error = f"{type(exc).__name__}: {exc}"+ duration = time.perf_counter() - started+ usage_report = vlm.get_token_usage()+ usage = usage_report.get("total_usage", {})+ return {+ "case_id": case.case_id,+ "category": case.category,+ "protocol": protocol,+ "repeat_index": repeat_index,+ "model": {+ "provider": vlm.provider,+ "name": vlm.model,+ "temperature": vlm.temperature,+ "thinking": vlm.thinking,+ "max_tokens": vlm.max_tokens,+ },+ "grade": grade.to_dict(),+ "actual_files": files,+ "actual_replacements": replacements,+ "calls": _call_count(usage_report),+ "retries": max(0, _call_count(usage_report) - 1),+ "prompt_tokens": int(usage.get("prompt_tokens", 0)),+ "completion_tokens": int(usage.get("completion_tokens", 0)),+ "total_tokens": int(usage.get("total_tokens", 0)),+ "duration_seconds": round(duration, 3),+ "terminal_error": terminal_error,+ }+++async def main_async(args: argparse.Namespace) -> None:+ from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton++ config = OpenVikingConfigSingleton.initialize(config_path=args.config)+ cases = load_cases(Path(args.cases))+ selected = set(args.case or [])+ if selected:+ cases = [case for case in cases if case.case_id in selected]+ protocols = tuple(dict.fromkeys(args.protocol))+ output = Path(args.output)+ output.parent.mkdir(parents=True, exist_ok=True)+ output.write_text("")+ total = len(cases) * args.repeat * len(protocols)+ done = 0+ for repeat_index in range(args.repeat):+ for case_index, case in enumerate(cases):+ # Counterbalance temporal/provider drift instead of always giving one+ # protocol the first call in every pair.+ pair_protocols = (+ protocols if (repeat_index + case_index) % 2 == 0 else tuple(reversed(protocols))+ )+ for protocol in pair_protocols:+ row = await run_one(case, protocol, repeat_index, config)+ with output.open("a") as fp:+ fp.write(json.dumps(row, ensure_ascii=False) + "\n")+ done += 1+ status = "PASS" if row["grade"]["organization_success"] else "FAIL"+ print(f"[{done}/{total}] {protocol} {case.case_id}: {status}", flush=True)+++def parse_args() -> argparse.Namespace:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--config", default=os.path.expanduser("~/.openviking/ov.conf"))+ parser.add_argument("--cases", default=str(DEFAULT_CASES))+ parser.add_argument("--case", action="append", help="Run one case id (repeatable)")+ parser.add_argument("--protocol", action="append", choices=("json", "python"), default=[])+ parser.add_argument("--repeat", type=int, default=1)+ parser.add_argument("--output", default=str(ROOT / "result" / "ab_results.jsonl"))+ args = parser.parse_args()+ args.protocol = args.protocol or ["json", "python"]+ if args.repeat < 1:+ parser.error("--repeat must be >= 1")+ return args+++if __name__ == "__main__":+ asyncio.run(main_async(parse_args()))diff --git a/benchmark/memory_organization/run_autonomous_ab.py b/benchmark/memory_organization/run_autonomous_ab.pynew file mode 100644index 000000000..3270598c6--- /dev/null+++ b/benchmark/memory_organization/run_autonomous_ab.py@@ -0,0 +1,380 @@+#!/usr/bin/env python3+from __future__ import annotations++import argparse+import asyncio+import inspect+import json+import os+import time+from concurrent.futures import ProcessPoolExecutor+from pathlib import Path+from typing import Any++from benchmark.memory_organization.autonomous_cases import AutonomousCase, build_cases+from benchmark.memory_organization.autonomous_grader import (+ autonomous_metrics,+ grade_autonomous_result,+)+from benchmark.memory_organization.run_ab import _call_count+from openviking.session.memory.session_extract_context_provider import (+ SessionExtractContextProvider,+)++ROOT = Path(__file__).resolve().parent+Job = tuple[int, str, str, int]+++class AutonomousProvider(SessionExtractContextProvider):+ def __init__(self, case: AutonomousCase, *, output_language: str = "") -> None:+ super().__init__(messages=list(case.messages), viking_fs=object())+ self.case = case+ self._benchmark_output_language = output_language.strip()+ self._read_file_contents = dict(case.initial_files)++ def get_output_language(self) -> str:+ return self._benchmark_output_language or super().get_output_language()++ async def prefetch(self) -> list[dict[str, Any]]:+ from openviking.session.memory.tools import (+ add_tool_call_pair_to_messages,+ memory_maintenance_notice,+ )++ # Keep the production conversation wrapper and add only the read results+ # that the real prefetch/search path would have selected. No benchmark+ # maintenance instruction or expected organization is shown to the model.+ messages: list[dict[str, Any]] = [self._build_conversation_message()]+ for call_id, (uri, memory_file) in enumerate(self.read_file_contents.items(), start=1):+ page_id = self._extract_context.page_id_map.get_page_id(uri)+ result = memory_file.to_metadata()+ result["page_id"] = page_id+ maintenance_notice = memory_maintenance_notice(+ memory_file.plain_content() or "",+ review_after_tokens=self.case.maintenance_review_tokens,+ )+ if maintenance_notice is not None:+ result["memory_maintenance_notice"] = maintenance_notice+ add_tool_call_pair_to_messages(+ messages,+ call_id=call_id,+ tool_name="read",+ params={"uri": uri},+ result=result,+ )+ return messages++ async def execute_tool(self, tool_call: Any) -> dict[str, str]:+ from openviking.session.memory.tools import memory_maintenance_notice++ uri = str(tool_call.arguments.get("uri", ""))+ memory_file = self.read_file_contents.get(uri)+ if memory_file is None:+ return {"error": f"File not found: {uri}"}+ result = memory_file.to_metadata()+ result["page_id"] = self.get_extract_context().page_id_map.get_page_id(uri)+ maintenance_notice = memory_maintenance_notice(+ memory_file.plain_content() or "",+ review_after_tokens=self.case.maintenance_review_tokens,+ )+ if maintenance_notice is not None:+ result["memory_maintenance_notice"] = maintenance_notice+ return result+++class AutonomousIsolationHandler:+ def get_read_scope(self) -> Any:+ from openviking.session.memory.memory_isolation_handler import RoleScope++ return RoleScope(user_ids=[], peer_ids=[])++ def fill_identity_fields(self, item_dict: dict[str, Any], **kwargs: Any) -> None:+ del kwargs+ item_dict.pop("peer_id", None)++ def calculate_memory_uris(+ self,+ *,+ memory_type_schema: Any,+ operation: Any,+ extract_context: Any,+ ) -> list[str]:+ from openviking.session.memory.utils.template_utils import TemplateUtils++ path = f"{memory_type_schema.directory}/{memory_type_schema.filename_template}"+ fields = {"user_space": "default", **operation.memory_fields}+ return [TemplateUtils.render(path, fields, extract_context)]+++async def materialize(+ case: AutonomousCase, operations: Any+) -> tuple[dict[str, tuple[str, str]], dict[str, str]]:+ from openviking.session.memory.merge_op import FieldType, PatchOp++ files = {+ uri: (str(memory_file.memory_type), memory_file.content)+ for uri, memory_file in case.initial_files.items()+ }+ for memory_file in operations.delete_file_contents:+ if memory_file.uri:+ files.pop(memory_file.uri, None)+ patch_op = PatchOp(FieldType.STRING)+ for operation in operations.upsert_operations:+ if not operation.uris:+ continue+ uri = operation.uris[0]+ value = operation.memory_fields.get("content")+ if operation.old_memory_file_content is not None:+ value = await patch_op.apply(operation.old_memory_file_content.content, value)+ files[uri] = (operation.memory_type, str(value or ""))+ return files, dict(operations.delete_replacements)+++async def run_one(+ case: AutonomousCase,+ protocol: str,+ repeat_index: int,+ config: Any,+ *,+ output_language: str = "",+) -> dict:+ from openviking.session.memory.extract_loop import ExtractLoop++ provider = AutonomousProvider(case, output_language=output_language)+ config.memory.extraction_output_format = protocol+ config.memory.link_enabled = False+ vlm = config.vlm.get_vlm_instance()+ vlm.reset_token_usage()+ raw_responses: list[dict[str, Any]] = []+ original_get_completion_async = vlm.get_completion_async++ async def recording_get_completion_async(*args: Any, **kwargs: Any) -> Any:+ response = await original_get_completion_async(*args, **kwargs)+ if isinstance(response, str):+ raw_responses.append({"content": response, "tool_calls": []})+ else:+ raw_responses.append(+ {+ "content": response.content or "",+ "tool_calls": [+ {+ "id": tool_call.id,+ "name": tool_call.name,+ "arguments": tool_call.arguments,+ }+ for tool_call in response.tool_calls+ ],+ }+ )+ return response++ vlm.get_completion_async = recording_get_completion_async+ loop = ExtractLoop(+ vlm=vlm,+ viking_fs=object(),+ context_provider=provider,+ isolation_handler=AutonomousIsolationHandler(),+ max_iterations=3,+ thinking=False,+ )+ started = time.perf_counter()+ try:+ try:+ operations, _ = await loop.run()+ files, replacements = await materialize(case, operations)+ grade = grade_autonomous_result(case, files, replacements)+ decision_metrics = autonomous_metrics(case, files, replacements, grade)+ terminal_error = "; ".join(operations.errors)+ except Exception as exc:+ files = {+ uri: (str(memory_file.memory_type), memory_file.content)+ for uri, memory_file in case.initial_files.items()+ }+ replacements = {}+ grade = grade_autonomous_result(case, files, replacements)+ decision_metrics = autonomous_metrics(case, files, replacements, grade)+ terminal_error = f"{type(exc).__name__}: {exc}"+ finally:+ vlm.get_completion_async = original_get_completion_async+ usage_report = vlm.get_token_usage()+ usage = usage_report.get("total_usage", {})+ calls = _call_count(usage_report)+ return {+ "case_id": case.case_id,+ "category": case.category,+ "protocol": protocol,+ "repeat_index": repeat_index,+ "model": {+ "provider": vlm.provider,+ "name": vlm.model,+ "temperature": vlm.temperature,+ "thinking": vlm.thinking,+ "max_tokens": vlm.max_tokens,+ },+ "grade": grade.to_dict(),+ "autonomous_metrics": decision_metrics,+ "actual_files": {+ uri: {"memory_type": memory_type, "content": content}+ for uri, (memory_type, content) in files.items()+ },+ "actual_replacements": replacements,+ "raw_responses": raw_responses,+ "calls": calls,+ "retries": max(0, calls - 1),+ "prompt_tokens": int(usage.get("prompt_tokens", 0)),+ "completion_tokens": int(usage.get("completion_tokens", 0)),+ "total_tokens": int(usage.get("total_tokens", 0)),+ "duration_seconds": round(time.perf_counter() - started, 3),+ "terminal_error": terminal_error,+ }+++def build_jobs(cases: list[AutonomousCase], repeat: int) -> list[Job]:+ """Build counterbalanced JSON/Python jobs with stable unique indices."""+ protocols = ("json", "python")+ jobs: list[Job] = []+ for repeat_index in range(repeat):+ for case_index, case in enumerate(cases):+ ordered = (+ protocols if (repeat_index + case_index) % 2 == 0 else tuple(reversed(protocols))+ )+ for protocol in ordered:+ jobs.append((len(jobs), case.case_id, protocol, repeat_index))+ return jobs+++def _run_job_in_process(+ config_path: str,+ case_id: str,+ protocol: str,+ repeat_index: int,+ output_language: str,+) -> dict[str, Any]:+ """Run one job in a process-isolated config/VLM environment."""+ from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton++ config = OpenVikingConfigSingleton.initialize(config_path=config_path)+ case = next(case for case in build_cases() if case.case_id == case_id)++ async def execute() -> dict[str, Any]:+ try:+ return await run_one(+ case,+ protocol,+ repeat_index,+ config,+ output_language=output_language,+ )+ finally:+ await _close_vlm_async_clients(config.vlm._vlm_instance)++ return asyncio.run(execute())+++async def _close_vlm_async_clients(vlm: Any) -> None:+ """Close loop-bound clients before a process worker's event loop exits."""+ if vlm is None:+ return+ cache = getattr(vlm, "_async_client_cache", None)+ if cache is not None:+ for client in cache.pop_all():+ close = getattr(client, "close", None) or getattr(client, "aclose", None)+ if close is None:+ continue+ result = close()+ if inspect.isawaitable(result):+ await result+ for child_name in ("primary", "backup", "vlm_instances", "_vlm_instances"):+ children = getattr(vlm, child_name, None)+ if children is None:+ continue+ if not isinstance(children, (list, tuple)):+ children = [children]+ for child in children:+ await _close_vlm_async_clients(child)+++def _append_result(output: Path, row: dict[str, Any], done: int, total: int) -> None:+ with output.open("a") as fp:+ fp.write(json.dumps(row, ensure_ascii=False) + "\n")+ metrics = row["autonomous_metrics"]+ action = "PASS" if metrics["organization_action_success"] else "FAIL"+ integrity = "PASS" if metrics["information_integrity"] else "FAIL"+ print(+ f"[{done}/{total}] {row['protocol']} {row['case_id']}: "+ f"action={action} integrity={integrity}",+ flush=True,+ )+++async def main_async(args: argparse.Namespace) -> None:+ from openviking_cli.utils.config.open_viking_config import OpenVikingConfigSingleton++ config = OpenVikingConfigSingleton.initialize(config_path=args.config)+ cases = build_cases()+ selected = set(args.case or [])+ if selected:+ cases = [case for case in cases if case.case_id in selected]+ output = Path(args.output)+ output.parent.mkdir(parents=True, exist_ok=True)+ output.write_text("")+ jobs = build_jobs(cases, args.repeat)+ total = len(jobs)+ if args.parallel == 1:+ for done, (_index, case_id, protocol, repeat_index) in enumerate(jobs, start=1):+ case = next(case for case in cases if case.case_id == case_id)+ row = await run_one(+ case,+ protocol,+ repeat_index,+ config,+ output_language=args.output_language,+ )+ _append_result(output, row, done, total)+ return++ loop = asyncio.get_running_loop()+ with ProcessPoolExecutor(max_workers=args.parallel) as executor:+ futures = [+ loop.run_in_executor(+ executor,+ _run_job_in_process,+ args.config,+ case_id,+ protocol,+ repeat_index,+ args.output_language,+ )+ for _index, case_id, protocol, repeat_index in jobs+ ]+ for done, future in enumerate(asyncio.as_completed(futures), start=1):+ _append_result(output, await future, done, total)+++def parse_args(argv: list[str] | None = None) -> argparse.Namespace:+ parser = argparse.ArgumentParser()+ parser.add_argument("--config", default=os.path.expanduser("~/.openviking/ov.conf"))+ parser.add_argument("--case", action="append")+ parser.add_argument("--repeat", type=int, default=1)+ parser.add_argument(+ "--parallel",+ type=int,+ default=1,+ help="Maximum process-isolated jobs to run concurrently (default: 1)",+ )+ parser.add_argument(+ "--output-language",+ default="",+ help="Optional production output-language override for this benchmark run",+ )+ parser.add_argument("--output", default=str(ROOT / "result" / "autonomous_results.jsonl"))+ args = parser.parse_args(argv)+ if args.repeat < 1:+ parser.error("--repeat must be >= 1")+ if args.parallel < 1:+ parser.error("--parallel must be >= 1")+ return args+++if __name__ == "__main__":+ asyncio.run(main_async(parse_args()))diff --git a/bot/vikingbot/openviking_mount/ov_server.py b/bot/vikingbot/openviking_mount/ov_server.pyindex dbe733c3a..a9df22a50 100644--- a/bot/vikingbot/openviking_mount/ov_server.py+++ b/bot/vikingbot/openviking_mount/ov_server.py@@ -503,12 +503,15 @@ class VikingClient:limit: int = 10,):"""搜索资源"""- kwargs: Dict[str, Any] = {"limit": limit}+ # The SDK find/search sync moved context_type/filter out of top-level+ # find() kwargs into FindOptions. Adapt here so callers keep the stable+ # VikingClient.find(context_type=..., filter=...) interface.options: Dict[str, Any] = {}if context_type is not None:options["context_type"] = context_typeif filter is not None:options["filter"] = filter+ kwargs: Dict[str, Any] = {"limit": limit}if options:kwargs["options"] = optionsif target_uri:diff --git a/examples/ov.conf.example b/examples/ov.conf.exampleindex 69a292453..9723293e6 100644--- a/examples/ov.conf.example+++ b/examples/ov.conf.example@@ -156,6 +156,7 @@"max_retries": 2,"provider": "volcengine","thinking": false,+ "_max_tokens_comment": "Optional output cap. Memory extraction needs ~32768 output tokens to avoid truncating a full memory-file rewrite; that default suits Doubao. If your model's max output is lower (e.g. gpt-4o-mini at 16384), set max_tokens to its limit here to override the extraction default.","media": {"enabled": false,"file_processing_timeout": 1800,@@ -233,6 +234,8 @@"memory": {"version": "v2","extraction_enabled": true,+ "extraction_output_format": "python",+ "maintenance_review_tokens": 1000,"session_skill_extraction_enabled": false,},"ingest": {diff --git a/openviking/models/vlm/backends/litellm_vlm.py b/openviking/models/vlm/backends/litellm_vlm.pyindex 84e9057a8..5cbec4d0e 100644--- a/openviking/models/vlm/backends/litellm_vlm.py+++ b/openviking/models/vlm/backends/litellm_vlm.py@@ -16,6 +16,7 @@ import litellmfrom litellm import acompletion, completionfrom openviking.telemetry import tracer+from openviking.utils.message_format import format_messages, sanitize_openai_messagesfrom openviking.utils.model_retry import retry_async, retry_syncfrom openviking.utils.multimodal import redact_image_data_urlsfrom openviking_cli.utils import get_logger@@ -283,16 +284,18 @@ class LiteLLMVLMProvider(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,thinking: Optional[bool] = None,+ max_tokens: Optional[int] = None,) -> dict[str, Any]:"""Build kwargs for LiteLLM call."""kwargs: dict[str, Any] = {"model": model,- "messages": messages,+ "messages": sanitize_openai_messages(messages),"temperature": self.temperature,"timeout": self.timeout,}- if self.max_tokens is not None:- kwargs["max_tokens"] = self.max_tokens+ effective_max_tokens = max_tokens if max_tokens is not None else self.max_tokens+ if effective_max_tokens is not None:+ kwargs["max_tokens"] = effective_max_tokensif self._should_forward_api_key(model):kwargs["api_key"] = self.api_key@@ -332,11 +335,13 @@ class LiteLLMVLMProvider(VLMBase):# See BerriAI/litellm#17304 and PR #25659. Remove when LiteLLM ships# the fix.if provider == "gemini" and tools:+ # Strip cache_control from the ALREADY-sanitized messages, not the raw+ # input, so empty assistant turns removed above are not reintroduced.kwargs["messages"] = [{k: v for k, v in msg.items() if k != "cache_control"}if isinstance(msg, dict)else msg- for msg in messages+ for msg in kwargs["messages"]]return kwargs@@ -391,10 +396,13 @@ class LiteLLMVLMProvider(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> dict[str, Any]:model = self._resolve_model(self.model or "gpt-4o-mini")kwargs_messages = messages or [{"role": "user", "content": prompt}]- return self._build_kwargs(model, kwargs_messages, tools, tool_choice, thinking=thinking)+ return self._build_kwargs(+ model, kwargs_messages, tools, tool_choice, thinking=thinking, max_tokens=max_tokens+ )def _build_vision_kwargs(self,@@ -445,7 +453,6 @@ class LiteLLMVLMProvider(VLMBase):operation_name="LiteLLM VLM completion",)- @tracer("litellm.vlm.call", ignore_result=True, ignore_args=["messages"])async def get_completion_async(self,prompt: str = "",@@ -453,12 +460,16 @@ class LiteLLMVLMProvider(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously."""- kwargs = self._build_text_kwargs(prompt, thinking, tools, tool_choice, messages)- # 用 tracer.info 打印请求+ kwargs = self._build_text_kwargs(+ prompt, thinking, tools, tool_choice, messages, max_tokens=max_tokens+ )+ # 用 tracer.info 打印请求(人类可读格式)tracer.info(- f"request: {json.dumps(redact_image_data_urls(kwargs), ensure_ascii=False, indent=2)}"+ "llm_input_messages="+ + format_messages(redact_image_data_urls(kwargs.get("messages", []))))async def _call() -> Union[str, VLMResponse]:diff --git a/openviking/models/vlm/backends/openai_vlm.py b/openviking/models/vlm/backends/openai_vlm.pyindex c2a658a25..2cdcbf643 100644--- a/openviking/models/vlm/backends/openai_vlm.py+++ b/openviking/models/vlm/backends/openai_vlm.py@@ -11,6 +11,7 @@ from urllib.parse import urlparsefrom openviking.telemetry import tracerfrom openviking.utils.async_client_cache import LoopScopedAsyncClientCache+from openviking.utils.message_format import format_messages, sanitize_openai_messagesfrom openviking.utils.multimodal import redact_image_data_urlsfrom openviking_cli.utils import get_logger@@ -223,9 +224,13 @@ class OpenAIVLM(VLMBase):tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,thinking: Optional[bool] = None,+ max_tokens: Optional[int] = None,) -> Dict[str, Any]:effective_thinking = self.thinking if thinking is None else thinking- kwargs_messages = messages or [{"role": "user", "content": prompt}]+ effective_max_tokens = max_tokens if max_tokens is not None else self.max_tokens+ kwargs_messages = sanitize_openai_messages(+ messages or [{"role": "user", "content": prompt}]+ )model = self.model or "gpt-4o-mini"is_reasoning = _is_reasoning_model(model)kwargs: Dict[str, Any] = {@@ -237,8 +242,8 @@ class OpenAIVLM(VLMBase):else:kwargs["temperature"] = self.temperatureself._apply_provider_specific_extra_body(kwargs, effective_thinking)- if self.max_tokens is not None:- kwargs["max_completion_tokens" if is_reasoning else "max_tokens"] = self.max_tokens+ if effective_max_tokens is not None:+ kwargs["max_completion_tokens" if is_reasoning else "max_tokens"] = effective_max_tokensif tools:kwargs["tools"] = toolskwargs["tool_choice"] = tool_choice or "auto"@@ -255,14 +260,14 @@ class OpenAIVLM(VLMBase):) -> Dict[str, Any]:effective_thinking = self.thinking if thinking is None else thinkingif messages:- kwargs_messages = messages+ kwargs_messages = sanitize_openai_messages(messages)else:content = []if images:content.extend(self._prepare_image(img) for img in images)if prompt:content.append({"type": "text", "text": prompt})- kwargs_messages = [{"role": "user", "content": content}]+ kwargs_messages = sanitize_openai_messages([{"role": "user", "content": content}])model = self.model or "gpt-4o-mini"is_reasoning = _is_reasoning_model(model)@@ -321,7 +326,6 @@ class OpenAIVLM(VLMBase):operation_name="OpenAI VLM completion",)- @tracer("openai.vlm.call", ignore_result=True, ignore_args=["messages"])async def get_completion_async(self,prompt: str = "",@@ -329,11 +333,14 @@ class OpenAIVLM(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously"""effective_thinking = self.thinking if thinking is None else thinkingclient = self.get_async_client()- kwargs = self._build_text_kwargs(prompt, tools, tool_choice, messages, effective_thinking)+ kwargs = self._build_text_kwargs(+ prompt, tools, tool_choice, messages, effective_thinking, max_tokens=max_tokens+ )async def _call() -> Union[str, VLMResponse]:t0 = time.perf_counter()@@ -344,9 +351,10 @@ class OpenAIVLM(VLMBase):return self._build_vlm_response(response, has_tools=True)return await self._extract_completion_content_async(response, elapsed)- # 用 tracer.info 打印请求+ # 用 tracer.info 打印请求(人类可读格式)tracer.info(- f"messages={json.dumps(redact_image_data_urls(kwargs), ensure_ascii=False, indent=2)}"+ "llm_input_messages="+ + format_messages(redact_image_data_urls(kwargs.get("messages", []))))return await retry_async(diff --git a/openviking/models/vlm/backends/volcengine_vlm.py b/openviking/models/vlm/backends/volcengine_vlm.pyindex f7f96dc02..e9806778e 100644--- a/openviking/models/vlm/backends/volcengine_vlm.py+++ b/openviking/models/vlm/backends/volcengine_vlm.py@@ -11,6 +11,7 @@ from pathlib import Pathfrom typing import Any, Dict, List, Optional, Unionfrom openviking.telemetry import tracer+from openviking.utils.message_format import format_messages, sanitize_openai_messagesfrom openviking.utils.multimodal import redact_image_data_urlsfrom openviking_cli.utils import get_logger@@ -178,7 +179,9 @@ class VolcEngineVLM(OpenAIVLM):) -> Union[str, VLMResponse]:"""Get text completion via Chat Completions API."""effective_thinking = self.thinking if thinking is None else thinking- kwargs_messages = messages or [{"role": "user", "content": prompt}]+ kwargs_messages = sanitize_openai_messages(+ messages or [{"role": "user", "content": prompt}]+ )kwargs = {"model": self.model or "doubao-seed-2-0-lite-260428","messages": kwargs_messages,@@ -206,7 +209,6 @@ class VolcEngineVLM(OpenAIVLM):return resultreturn self._clean_response(str(result))- @tracer("volcengine.vlm.call", ignore_result=True, ignore_args=["messages"])async def get_completion_async(self,prompt: str = "",@@ -214,10 +216,14 @@ class VolcEngineVLM(OpenAIVLM):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously via Chat Completions API."""effective_thinking = self.thinking if thinking is None else thinking- kwargs_messages = messages or [{"role": "user", "content": prompt}]+ effective_max_tokens = max_tokens if max_tokens is not None else self.max_tokens+ kwargs_messages = sanitize_openai_messages(+ messages or [{"role": "user", "content": prompt}]+ )kwargs = {"model": self.model or "doubao-seed-2-0-lite-260428","messages": kwargs_messages,@@ -225,16 +231,15 @@ class VolcEngineVLM(OpenAIVLM):"thinking": {"type": "disabled" if not effective_thinking else "enabled"},"extra_headers": build_volcengine_request_headers(self.extra_headers),}- if self.max_tokens is not None:- kwargs["max_tokens"] = self.max_tokens+ if effective_max_tokens is not None:+ kwargs["max_tokens"] = effective_max_tokensif tools:kwargs["tools"] = toolskwargs["tool_choice"] = tool_choice or "auto"- # 用 tracer.info 打印请求+ # 用 tracer.info 打印请求(人类可读格式)tracer.info(- "request: "- f"{json.dumps(redact_image_data_urls(kwargs_messages), ensure_ascii=False, indent=2)}"+ "llm_input_messages=" + format_messages(redact_image_data_urls(kwargs_messages)))if tools:tracer.info(@@ -394,14 +399,14 @@ class VolcEngineVLM(OpenAIVLM):"""Get vision completion via Chat Completions API."""effective_thinking = self.thinking if thinking is None else thinkingif messages:- kwargs_messages = messages+ kwargs_messages = sanitize_openai_messages(messages)else:content = []if images:content.extend(self._prepare_image(img) for img in images)if prompt:content.append({"type": "text", "text": prompt})- kwargs_messages = [{"role": "user", "content": content}]+ kwargs_messages = sanitize_openai_messages([{"role": "user", "content": content}])kwargs = {"model": self.model or "doubao-seed-2-0-lite-260428",@@ -442,14 +447,14 @@ class VolcEngineVLM(OpenAIVLM):"""Get vision completion asynchronously via Chat Completions API."""effective_thinking = self.thinking if thinking is None else thinkingif messages:- kwargs_messages = messages+ kwargs_messages = sanitize_openai_messages(messages)else:content = []if images:content.extend(self._prepare_image(img) for img in images)if prompt:content.append({"type": "text", "text": prompt})- kwargs_messages = [{"role": "user", "content": content}]+ kwargs_messages = sanitize_openai_messages([{"role": "user", "content": content}])kwargs = {"model": self.model or "doubao-seed-2-0-lite-260428",diff --git a/openviking/models/vlm/base.py b/openviking/models/vlm/base.pyindex b1cd546b2..99a40281c 100644--- a/openviking/models/vlm/base.py+++ b/openviking/models/vlm/base.py@@ -112,6 +112,7 @@ class VLMBase(ABC):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously@@ -121,6 +122,7 @@ class VLMBase(ABC):tools: Optional list of tool definitions in OpenAI function formattool_choice: Optional tool choice mode ("auto", "none", or specific tool name)messages: Optional list of message dicts (takes precedence over prompt)+ max_tokens: Optional per-call output cap; overrides the configured valueReturns:str if no tools provided, VLMResponse if tools provided@@ -598,6 +600,7 @@ class FailoverVLM(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously with failover support."""return await self._get_completion_with_failover_async(@@ -607,6 +610,7 @@ class FailoverVLM(VLMBase):tools=tools,tool_choice=tool_choice,messages=messages,+ max_tokens=max_tokens,)def get_vision_completion(@@ -972,6 +976,7 @@ class MultiCredentialVLM(VLMBase):tools: Optional[List[Dict[str, Any]]] = None,tool_choice: Optional[str] = None,messages: Optional[List[Dict[str, Any]]] = None,+ max_tokens: Optional[int] = None,) -> Union[str, VLMResponse]:"""Get text completion asynchronously with multi-credential failover support."""return await self._get_completion_with_failover_async(@@ -981,6 +986,7 @@ class MultiCredentialVLM(VLMBase):tools=tools,tool_choice=tool_choice,messages=messages,+ max_tokens=max_tokens,)def get_vision_completion(diff --git a/openviking/prompts/templates/memory/entities.yaml b/openviking/prompts/templates/memory/entities.yamlindex dca91da49..a8d9d95eb 100644--- a/openviking/prompts/templates/memory/entities.yaml+++ b/openviking/prompts/templates/memory/entities.yaml@@ -3,6 +3,10 @@ description: |Third-party entity memory: stable cards for real people, organizations, places,works, media, products, animals/pets, programs, activities, and concepts theuser mentions. Store what the entity is and its durable relations.+ Entity identity is the referenced real-world object, not its category or semantic+ similarity. Merge only explicit aliases of the same object. Distinct people, pets,+ works, artworks, products, possessions, places, events, and activities remain separate+ even when they share a theme, owner, participants, appearance, or use.directory: "viking://user/{{ user_space }}/memories/entities"filename_template: "{{ category|lower }}/{{ name|lower }}.md"enabled: true@@ -55,6 +59,8 @@ fields:generalize. Keep one-off facts only when they are concrete and likely usefulfor future who/what/when/where/how-long questions.- Keep it readable: usually 6-14 bullets total / about 1200 chars. When updating,- merge and deduplicate; preserve existing atomic facts unless contradicted.+ Keep it readable: 6-14 bullets / about 1200 chars is a soft target. Never drop or+ generalize a distinct answerable fact to meet it. When updating, deduplicate exact or+ paraphrased facts about this same entity and preserve every other existing atomic fact+ unless contradicted.merge_op: patchdiff --git a/openviking/prompts/templates/memory/preferences.yaml b/openviking/prompts/templates/memory/preferences.yamlindex 4da91bb44..789a48d8d 100644--- a/openviking/prompts/templates/memory/preferences.yaml+++ b/openviking/prompts/templates/memory/preferences.yaml@@ -37,14 +37,20 @@ fields:{% if language == 'en' %}Use lowercase with underscores, max 3 words.{% else %}Keep the topic concise and natural in {{ language }}.{% endif %}Preference topic used to uniquely identify this preference memory.Should be a semantic topic description such as "Python code style", "Communication style", "Food preference", "Commute preference", etc.- Store unrelated preferences separately, but merge overlapping or synonymous topics into one stable topic.+ This topic is an identity component together with user. Merge only true aliases for+ the same owner's same behavioral choice dimension. Related dimensions may share words+ but remain separate; for example, preferred movie genres and preferred games are not+ one preference merely because both are entertainment.merge_op: immutable- name: contenttype: stringdescription: |Preference content in Markdown format describing "what the user prefers/is accustomed to".- Write one concise bullet per distinct, reusable preference; omit duplicates, events, dates, plans, and supporting evidence.+ Write one concise bullet per distinct, reusable preference; omit exact duplicates,+ events, dates, and plans. Preserve the specific choice, list members, conditions,+ exceptions, and user-stated reason or emotional meaning when they make the preference+ answerable or distinguish it from nearby preferences.Example:- Prefers concise written updates with decisions and next actions.- Chooses lightweight tools when they cover the workflow.diff --git a/openviking/prompts/templates/memory/profile.yaml b/openviking/prompts/templates/memory/profile.yamlindex 561f8ddf7..71e980df4 100644--- a/openviking/prompts/templates/memory/profile.yaml+++ b/openviking/prompts/templates/memory/profile.yaml@@ -1,18 +1,88 @@memory_type: profiledescription: |- # Task Objective- User profile memory - captures an identity summary of who the user is as a person.- Extract relatively stable personal attributes that define the user's identity at a high level.- Include: profession, experience level, technical background, communication style, work habits, etc.- Do NOT include transient conversation content or temporary mood states.+ # Role and objective+ You are a user-profile modeling expert. Analyze the conversation together with the+ existing profile and maintain a compact description of each participant's DURABLE+ CURRENT STATE. One profile.md may contain several participants, each under a separate+ H1 heading.- # Rules- - Each item: self-contained, declarative sentence, < 30 words- - Extract only facts stated/confirmed by user; no guesses- - Focus on persistent information, not temporary situations- - Forbidden: events, only-assistant content, sensitive/private info, trivial updates- - Merge similar items; keep latest if conflicting+ Use the same language as the user's conversation. Extract only facts explicitly stated+ or confirmed by that participant. Never infer attributes from assistant text, jokes,+ hypotheticals, or role-play.+ # Profile inclusion rule: current durable states only+ A fact belongs in PROFILE only when it describes a current state that is expected to+ remain true across future conversations. Allowed examples:+ - Basic identity: name, nickname, age, birthday, gender, hometown, current residence,+ nationality, and similarly durable identity facts.+ - Current education and career state: current school/degree status, current profession,+ concrete employer when explicitly named, durable qualifications, and established skills.+ - Current real-world relationship/family state: marital/relationship status, parents,+ siblings, partner/spouse, and children. Store the relationship state only.+ - Long-term health state: chronic conditions, allergies, and lasting physical constraints.++ # Route everything else away from profile+ Classify every candidate fact before writing it:+ - A dated transition, completed occurrence, historical episode, trip, purchase, meeting,+ class, project update, award, accident, or attended/tried/completed/won action -> EVENTS.+ - A goal, aspiration, plan, intention, upcoming action, or commitment -> EVENTS when it is+ a concrete commitment; otherwise omit it from profile.+ - A like, dislike, value judgment, recommendation, hobby, routine, work/communication+ style, coping method, preferred tool/workflow, or other habitual choice -> PREFERENCES.+ - A personality/character summary (kind, resilient, ambitious, supportive, etc.) -> omit+ from profile; do not infer personality from behavior.+ - A fact primarily about a pet, place, organization, work, product, or non-participant+ person -> ENTITIES.+ - A temporary mood/state, current task, speculative inference, role-play, assistant-only+ claim, or trivial detail -> discard.++ A date is only supporting evidence; it does not automatically make a fact an event:+ - "Current occupation: Engineer (as of 2023-06-09)" is a durable current state -> PROFILE.+ - "Started an engineering job on 2023-06-09" is a transition -> EVENTS.+ - "Relationship status: Married (as of 2023-06-09)" -> PROFILE.+ - "Held a wedding ceremony on 2023-06-09" -> EVENTS.+ - "Education: Master's degree (as of 2023-06-09)" -> PROFILE.+ - "Graduated on 2023-06-09" -> EVENTS.++ # Incremental update and schema normalization+ When an existing profile is provided, process it in this order:++ 1. Normalize the existing profile first.+ - The required Markdown shape is one H1 per participant followed directly by bullets;+ H2/H3 headings and prose paragraphs are forbidden.+ - If the existing content has extra headings or non-profile content, rewrite the+ COMPLETE content with obj.content.update(...), rather than preserving the old layout+ through many small edits.+ - Remove events, experiences, goals, plans, preferences, personality judgments, entity+ details, temporary states, role-play, unsupported claims, duplicate/paraphrased bullets,+ and stale superseded states.+ - Preserve the durable current-state result of a historical event when appropriate:+ marriage -> current relationship status; graduation -> current education state;+ relocation -> current residence. Do not preserve the event narrative itself.+ - It is valid and expected for a normalized profile to become much shorter.++ 2. Incorporate current durable states from the conversation.+ - Add only genuinely new current-state facts.+ - Merge semantic duplicates into one concise bullet.+ - For conflicting mutable states (occupation, residence, relationship status, education),+ replace the old state with the latest confirmed value; never retain state history here.++ 3. Preserve untouched valid information.+ - Existing compliant current-state bullets remain even when the current conversation does+ not repeat them. Do not rebuild a profile from only the latest conversation.++ # Required Markdown format+ - One H1 heading with only the participant's name, followed directly by bullet statements.+ - Repeat the H1 + bullet structure for each participant in the same profile.md.+ - Do not output H2/H3 headings, JSON, prose paragraphs, tables, labels, or category names.+ - Every bullet MUST end with the latest confirmation date in the exact form+ "(as of YYYY-MM-DD)". "As of" means the participant most recently stated or confirmed+ that the state was true; it is not necessarily the event date or file-write date.+ - Preserve an old valid bullet's existing as-of date when no newer confirmation exists;+ never stamp all bullets with today's date merely because the file is rewritten.+ - Use concise, self-contained declarative bullets, normally under 30 words excluding the+ trailing as-of marker. A compact profile is preferred; merge redundancy before removing+ valid current-state facts.directory: "viking://user/{{ user_space }}/memories"filename_template: "profile.md"@@ -21,22 +91,24 @@ fields:- name: contenttype: stringdescription: |- User profile content in Markdown format describing "who the user is".- Use Markdown heading(s) with only the person's name, then bullets only; do not write paragraph bodies.- Includes relatively stable personal attributes: profession, experience, tech stack, communication style, etc.- Only record objective statuses, do not record events or similar information.- [IMPORTANT] For changeable statuses, must include the last updated time in the format: (as of 2023-06-09)- Example:- # Caroline- - Date of birth- - Gender: Female- - Age: 25 (as of 2023-06-09)- - Nickname- - Place of origin- - Place of residence- - Regular city of residence- - Current occupation- - Relationship status: Single (as of 2023-06-09)- - Career plan- etc.+ Complete Markdown profile containing only durable current-state facts.++ Preserve this exact shape for every participant:++ # <Person name>+ - <Current stable fact> (as of YYYY-MM-DD)+ - <Current stable fact> (as of YYYY-MM-DD)++ Repeat the H1 + bullets for additional participants. Do not output H2/H3 headings,+ JSON, prose paragraphs, category labels, event timelines, historical narratives,+ goals/plans, preferences, personality judgments, entity details, or temporary states.++ If existing content violates this schema, use obj.content.update(...) to replace the+ COMPLETE field with a normalized version. Preserve all untouched valid current-state+ facts, but delete non-profile content, merge semantic duplicates, and replace stale+ conflicting states with the latest confirmed state.++ Every bullet MUST end with (as of YYYY-MM-DD), using the date when that participant+ most recently stated or confirmed the fact. Preserve the existing date when there is+ no newer confirmation; never use the file-update date merely because of a rewrite.merge_op: patchdiff --git a/openviking/session/memory/dataclass.py b/openviking/session/memory/dataclass.pyindex 3c4254e0c..08a69cbd2 100644--- a/openviking/session/memory/dataclass.py+++ b/openviking/session/memory/dataclass.py@@ -28,6 +28,7 @@ from openviking.session.memory.merge_op.base import (FieldType,MergeOp,)+from openviking.session.memory.utils.template_utils import TemplateUtilsT = TypeVar("T")@@ -232,7 +233,7 @@ class MemoryTypeSchema(BaseModel):directory: str = Field("", description="Directory path")enabled: bool = Field(True, description="Whether this memory type is enabled")operation_mode: str = Field(- "upsert", description="Operation mode: 'upsert' (default), 'add_only', or 'update_only'"+ "upsert", description="Operation mode: 'upsert' (default) or 'add_only'")stage: str = Field("user",@@ -249,6 +250,14 @@ class MemoryTypeSchema(BaseModel):def filename_has_variables(self):return "{{" in self.filename_template and "}}" in self.filename_template+ def identity_fields(self, *, include_peer_id: bool = True) -> tuple[str, ...]:+ """Return fields whose values determine the memory object's URI identity."""+ identity = ["peer_id"] if include_peer_id and self.peer_enabled else []+ uri_template = f"{self.directory}/{self.filename_template}"+ referenced = TemplateUtils.referenced_variables(uri_template)+ identity.extend(field.name for field in self.fields if field.name in referenced)+ return tuple(dict.fromkeys(identity))+class MemoryData(BaseModel):"""Dynamic memory data."""diff --git a/openviking/session/memory/extract_loop.py b/openviking/session/memory/extract_loop.pyindex 5abd15a96..c66bd652e 100644--- a/openviking/session/memory/extract_loop.py+++ b/openviking/session/memory/extract_loop.py@@ -24,18 +24,16 @@ from openviking.session.memory.dataclass import (StoredLink,WikiLink,)+from openviking.session.memory.extraction_output_protocol import (+ ExtractionOutputContext,+ ExtractionOutputProtocol,+ create_extraction_output_protocol,+)from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandlerfrom openviking.session.memory.merge_op import FieldType, MergeOp, PatchOpfrom openviking.session.memory.page_id_map import ResponsePageIdAllocatorfrom openviking.session.memory.schema_model_generator import SchemaModelGenerator-from openviking.session.memory.tools import (- MEMORY_TOOLS_REGISTRY,- add_tool_call_pair_to_messages,-)-from openviking.session.memory.utils import (- parse_json_with_stability,- pretty_print_messages,-)+from openviking.session.memory.tools import MEMORY_TOOLS_REGISTRYfrom openviking.session.memory.utils.json_parser import JsonUtilsfrom openviking.storage.viking_fs import VikingFS, get_viking_fsfrom openviking.telemetry import bind_telemetry_stage, tracer@@ -44,6 +42,14 @@ from openviking_cli.utils.config import get_openviking_configlogger = get_logger(__name__)+# Memory extraction may rewrite an entire memory file in one response. Without an+# explicit cap, providers fall back to a small server-side default (e.g. Ark's+# 4096) and truncate the program mid-string, making the output unusable. This is+# a functional floor for extraction, tuned for the primary Doubao models.+# Models whose max output tokens is BELOW this value (e.g. gpt-4o-mini at 16384)+# must set `vlm.max_tokens` in ov.conf to their own limit to override this default.+_DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS = 32768+@dataclassclass _EventRepairOperations:@@ -122,6 +128,7 @@ class ExtractLoop:context_provider: Optional[Any] = None, # ExtractContextProviderisolation_handler: MemoryIsolationHandler = None,thinking: bool = False,+ max_output_tokens: Optional[int] = None,):"""Initialize the ExtractLoop.@@ -134,6 +141,10 @@ class ExtractLoop:ctx: Request contextcontext_provider: ExtractContextProvider - 必须提供(由 provider 加载 schema)thinking: Whether to explicitly enable model thinking for this extraction loop.+ max_output_tokens: Per-call output cap for the extraction LLM. When None, the+ configured vlm.max_tokens is used, falling back to a value large enough for+ full memory rewrites so providers do not apply a small server-side default+ (e.g. Ark's 4096) and truncate the program mid-string."""self.vlm = vlmself.viking_fs = viking_fs or get_viking_fs()@@ -142,20 +153,30 @@ class ExtractLoop:self.ctx = ctxself.context_provider = context_providerself.thinking = bool(thinking)+ self.max_output_tokens = max_output_tokens+ # Resolved in run() via _resolve_effective_max_output_tokens(); default to+ # the extraction floor so a direct _call_llm() before run() stays safe.+ self._effective_max_output_tokens = (+ max_output_tokens+ if max_output_tokens is not None+ else _DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS+ )# Use provided isolation_handler or create one in run()self._isolation_handler = isolation_handler# Track format error retry (max 1 retry)self._format_retry_count = 0self._last_llm_failure_kind: Optional[str] = Noneself._last_llm_failure_content: str = ""+ self._last_parse_error: Optional[str] = None# Schema 生成器(在 run() 中初始化)self.schema_model_generator = None# 预计算:避免每次迭代重复计算self._tool_schemas: Optional[List[Dict[str, Any]]] = None- self._expected_fields: Optional[List[str]] = Noneself._operations_model: Optional[Any] = None+ self._output_protocol: Optional[ExtractionOutputProtocol] = None+ self._output_context: Optional[ExtractionOutputContext] = None# Transaction handle for file lockingself._transaction_handle = None@@ -208,6 +229,8 @@ class ExtractLoop:config = get_openviking_config()self._link_enabled = config.memory.link_enabled if config.memory else False+ self._resolve_effective_max_output_tokens(config)+# 获取 ExtractContext(整个流程复用)self._extract_context = self.context_provider.get_extract_context()if self._extract_context is None:@@ -219,55 +242,48 @@ class ExtractLoop:self._operations_model = self.schema_model_generator.create_structured_operations_model(role_scope)- # Keep the stability parser's allowlist aligned with the generated- # contract, including conditional fields such as delete_ids and links.- self._expected_fields = list(self._operations_model.model_fields)- json_schema = self._operations_model.model_json_schema()+ output_format = getattr(config.memory, "extraction_output_format", "python")+ self._output_protocol = create_extraction_output_protocol(output_format)+ self._output_context = ExtractionOutputContext(+ operations_model=self._operations_model,+ schemas=tuple(schemas),+ page_id_map=self._extract_context.page_id_map,+ read_file_contents=self.context_provider.read_file_contents,+ link_enabled=self._link_enabled,+ role_scope=role_scope,+ available_tools=tuple(allowed_tools),+ )+ tracer.set("memory.extraction.output_format", output_format)# Build initial messages from provider- schema_str = json.dumps(json_schema, ensure_ascii=False)messages = []- page_id_rules = """-## Page ID Rules-- Every memory item you create or edit MUST include "page_id".-- For existing items, use the page_id shown in read/search results.-- For new items, assign a unique page_id >= 100.-- When editing an existing item, reuse its existing page_id.-- To delete an existing item, add an entry to `delete_ids` using its page_id.-- `delete_ids` deletes the whole item: use it only if every substantive fact is in scope; otherwise MUST use DELETE blocks for affected lines, preserving the rest and not inferring scope from the file name/topic.-- For canonical merges, set `replacement_page_id` to the surviving page that should inherit the deleted page's existing links/backlinks; for pure deletes, set `replacement_page_id` to null.-"""- link_rules = ""- if self._link_enabled:- link_rules = """-## Link Rules-- Link fields `f` and `t` must reference these page_id values.-- Only create links when the relationship is meaningful and clear from the conversation. Do NOT force links between unrelated items.-"""+ reference_rules = self._output_protocol.render_reference_rules(self._output_context)+ provider_instruction = self._output_protocol.normalize_provider_instruction(+ self.context_provider.instruction()+ )+ output_contract = self._output_protocol.render_contract(self._output_context)messages.append({"role": "system","content": f"""-{self.context_provider.instruction()}-{page_id_rules}-{link_rules}+{provider_instruction}+{reference_rules}## Read Format Rules- The read tool accepts `uri`, optional `offset` (0-indexed), and optional `limit`.- Read content is returned in Claude Code format: each visible line is prefixed with `line_number<TAB>`.- When you copy text from read results into SEARCH/REPLACE or DELETE operations, copy the exact text after the line-number prefix. Never include the line-number prefix itself in `search`, `replace`, or `delete`.-## Output Format-The final output of the model must strictly follow the JSON Schema format shown below:-```json-{schema_str}-```+{output_contract}""",})# Pre-fetch context via providertool_call_messages = await self.context_provider.prefetch()- messages.extend(tool_call_messages)+ prefetch_messages = self._output_protocol.render_prefetch_messages(+ tool_call_messages, self._output_context+ )+ messages.extend(prefetch_messages)for uri in self.context_provider.read_file_contents:self._extract_context.page_id_map.get_page_id(uri)@@ -288,9 +304,9 @@ The final output of the model must strictly follow the JSON Schema format shown})- # Call LLM with tools - model decides: tool calls OR final operations- pretty_print_messages(messages)-+ # Call LLM with tools - model decides: tool calls OR final operations.+ # The VLM backend traces the (human-readable) input and output, so we do+ # not re-dump them here (avoids duplicate, oversized span events).tool_calls, operations = await self._call_llm(messages)if tool_calls:@@ -349,6 +365,9 @@ The final output of the model must strictly follow the JSON Schema format showntracer.info(f"Found unread existing files: {refetch_uris}, refetching...")# Add refetch results to messages and continue loopawait self._add_refetch_results_to_messages(messages, refetch_uris)+ # A valid program started a new generation phase with richer context.+ # Give that regenerated response its own format-repair opportunity.+ self._format_retry_count = 0# Allow one extra iteration for refetchif iteration >= max_iterations:max_iterations += 1@@ -367,32 +386,42 @@ The final output of the model must strictly follow the JSON Schema format shown})tracer.info(- f"Extended max_iterations to {max_iterations} for retry patch repair",- console=True,+ f"Extended max_iterations to {max_iterations} for retry patch repair")continuebreak# If no tool calls either, continue to next iteration (don't break!)failure_kind = self._last_llm_failure_kind or "unknown"failure_preview = _preview_text(self._last_llm_failure_content)- tracer.error(- "LLM returned neither tool calls nor operations "- f"(iteration {iteration}/{max_iterations}) "- f"failure_kind={failure_kind} response_preview={failure_preview!r}"- )- # Add format error message if parse failed (max 1 retry)+ parse_error = self._last_parse_error+ # Add format error message if parse failed (max 1 retry). This may raise+ # max_iterations, granting one more attempt after this failure.if self._format_retry_count == 0:self._format_retry_count += 1max_iterations += 1- retry_reason = (- "refusal_text" if failure_kind == "refusal_text" else "format_retry"- )+ retry_reason = "refusal_text" if failure_kind == "refusal_text" else "format_retry"tracer.info(f"Extended max_iterations to {max_iterations} for {retry_reason}")self._add_format_error_message(messages)- # If it's the last iteration, treat unparseable response as- # "no memory operations" rather than failing hard.- if iteration >= max_iterations:+ # A failure is only terminal when no retry attempt remains after it.+ retry_remaining = iteration < max_iterations+ failure_message = (+ "Failed to parse memory operations "+ f"(iteration {iteration}/{max_iterations}) "+ f"failure_kind={failure_kind} error={parse_error} "+ f"response_preview={failure_preview!r}"+ )+ if retry_remaining:+ # Recoverable: another attempt will run. Keep it in the trace only,+ # not the console/log stream.+ tracer.info(failure_message)+ else:+ # ERROR: retries exhausted; this extraction will yield no operations.+ tracer.error(failure_message)++ # If no retry remains, treat unparseable response as "no memory+ # operations" rather than failing hard.+ if not retry_remaining:if pending_resolution_repair is not None:final_operations, raw_links = pending_resolution_repairpending_resolution_repair = None@@ -402,23 +431,22 @@ The final output of the model must strictly follow the JSON Schema format shownconsole=True,)break- tracer.info(- "Memory extraction final response could not be parsed as JSON operations "- f"after {max_iterations} iterations — treating as no operations "- f"failure_kind={failure_kind} response_preview={failure_preview!r}"- )final_operations = ResolvedOperations(upsert_operations=[],delete_file_contents=[],errors=[- "Final response could not be parsed as JSON operations "+ "Final response could not be parsed as operations "f"after {max_iterations} iterations "f"(failure_kind={failure_kind})"],)break- self._disable_tools_for_iteration = True+ self._disable_tools_for_iteration = (+ not self._output_protocol.keep_tools_enabled_after_parse_error(+ self._last_parse_error+ )+ )continueif final_operations is None:@@ -434,6 +462,24 @@ The final output of the model must strictly follow the JSON Schema format shownreturn final_operations, tools_used+ def _resolve_effective_max_output_tokens(self, config: Any = None) -> None:+ """Resolve the extraction output cap.++ Priority: explicit per-loop value > configured vlm.max_tokens >+ _DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS. The default is a functional floor+ that suits the primary Doubao models; a model with a lower max output+ (e.g. gpt-4o-mini) must set vlm.max_tokens in ov.conf to override it.+ """+ if config is None:+ config = get_openviking_config()+ if self.max_output_tokens is not None:+ self._effective_max_output_tokens = self.max_output_tokens+ return+ configured = getattr(getattr(config, "vlm", None), "max_tokens", None)+ self._effective_max_output_tokens = (+ configured if configured is not None else _DEFAULT_EXTRACTION_MAX_OUTPUT_TOKENS+ )+def _retryable_resolution_issues(self, operations: ResolvedOperations) -> List[Dict[str, Any]]:issues: List[Dict[str, Any]] = []for operation in operations.upsert_operations:@@ -459,21 +505,8 @@ The final output of the model must strictly follow the JSON Schema format shownissues.append(issue)return issues- @staticmethod- def _build_resolution_repair_instruction(issues: List[Dict[str, Any]]) -> str:- details = json.dumps(issues, ensure_ascii=False, indent=2)- return (- "Some event operations could not resolve a safe write target. "- "Return only corrected event operations for the failed items below; leave every "- "other memory-type field, delete_ids, and links empty. The server has preserved "- "all successful operations from the previous response. "- "Reuse exactly the page_id shown for each failed event. "- "For event ranges, use valid in-bounds message indexes and include the user-role "- "message that establishes the event so its owner can be resolved. "- "Do not target a disallowed or ambiguous peer. Output ONLY one JSON object matching "- "the required schema.\n\n"- f"Resolution issues:\n{details}"- )+ def _build_resolution_repair_instruction(self, issues: List[Dict[str, Any]]) -> str:+ return self._output_protocol.render_resolution_repair(issues)@staticmethoddef _is_event_schema(schema: Any) -> bool:@@ -1047,12 +1080,15 @@ The final output of the model must strictly follow the JSON Schema format shown})- add_tool_call_pair_to_messages(- messages,- call_id=tool_call.id,- tool_name=tool_call.name,- params=tool_call.arguments,- result=result,+ messages.extend(+ self._output_protocol.render_tool_result_messages(+ self._output_context,+ call_id=tool_call.id,+ tool_name=tool_call.name,+ params=tool_call.arguments,+ result=result,+ source="tool call",+ ))return has_unknown_tool@@ -1082,10 +1118,11 @@ The final output of the model must strictly follow the JSON Schema format showntools=tools,tool_choice=tool_choice,thinking=self.thinking,+ max_tokens=self._effective_max_output_tokens,)- tracer.info(f"llm_response={response}")self._last_llm_failure_kind = Noneself._last_llm_failure_content = ""+ self._last_parse_error = None# print(f'response={response}')# Log cache hit infoif hasattr(response, "usage") and response.usage:@@ -1138,12 +1175,7 @@ The final output of the model must strictly follow the JSON Schema format shown# print(f'LLM response content: {content}')logger.debug(f"[assistant]\n{content}")- # Use cached operations_model and expected_fields- operations, error = parse_json_with_stability(- content=content,- model_class=self._operations_model,- expected_fields=self._expected_fields,- )+ operations, error = self._output_protocol.parse(content, self._output_context)if error is not None:failure_kind = (@@ -1151,7 +1183,10 @@ The final output of the model must strictly follow the JSON Schema format shown)self._last_llm_failure_kind = failure_kindself._last_llm_failure_content = content- tracer.error(+ self._last_parse_error = error+ tracer.set("memory.extraction.parse_error", error)+ # Diagnostic only; the run loop emits the WARNING/ERROR decision.+ logger.debug("Failed to parse memory operations "f"failure_kind={failure_kind} error={error} "f"response_preview={_preview_text(content)!r}"@@ -1160,12 +1195,19 @@ The final output of the model must strictly follow the JSON Schema format shownreturn (None, operations)except Exception as e:- logger.exception(f"Error parsing operations: {e}")+ self._last_parse_error = str(e)+ tracer.set("memory.extraction.parse_error", self._last_parse_error)+ logger.debug(f"Error parsing operations: {e}")# Case 3: No tool calls and no parsable operationsself._last_llm_failure_kind = "empty_response" if not content else "parse_error"self._last_llm_failure_content = content or ""- tracer.error(+ if not content:+ empty_error = self._output_protocol.describe_empty_response()+ if empty_error:+ self._last_parse_error = empty_error+ tracer.set("memory.extraction.parse_error", empty_error)+ logger.debug("No tool calls or operations parsed "f"failure_kind={self._last_llm_failure_kind} "f"response_preview={_preview_text(self._last_llm_failure_content)!r}"@@ -1197,33 +1239,13 @@ The final output of the model must strictly follow the JSON Schema format shownmessages.append({"role": "user",- "content": (- "Your previous output could not be parsed as valid JSON. "- "Please output ONLY a valid JSON object matching the required schema. "- "Do not include any explanation, markdown formatting, or text outside the JSON."- ),+ "content": self._output_protocol.render_format_retry(self._last_parse_error),})- def _build_final_operations_skeleton(self) -> Dict[str, List[Any]]:- """Build an empty operations object matching the expected flat schema fields."""- fields = ["delete_ids", *(self._expected_fields or [])]- return {field: [] for field in dict.fromkeys(fields)}-def _build_final_operations_instruction(self) -> str:"""Build schema-aware final-iteration instructions for the LLM."""- skeleton = json.dumps(- self._build_final_operations_skeleton(),- ensure_ascii=False,- indent=2,- )- return (- "You have reached the maximum number of tool call iterations. "- "Do not call any more tools. Return your final result now as ONLY a valid JSON object "- "matching the required schema. Do not include explanations or markdown. "- "If there are no memory changes, return this exact empty-shape JSON with all fields present:\n"- f"{skeleton}"- )+ return self._output_protocol.render_final_instruction(self._output_context)async def _validate_patch_operations(self,@@ -1308,19 +1330,7 @@ The final output of the model must strictly follow the JSON Schema format shownreturn errorsdef _build_patch_repair_instruction(self, patch_errors: List[Dict[str, Any]]) -> str:- details = json.dumps(patch_errors, ensure_ascii=False, indent=2)- return (- "The SEARCH/REPLACE or DELETE patch could not be applied to the target memory file. "- "The SEARCH or DELETE text must be copied exactly from the read result of the file bound to that operation's page_id. "- "The matched text must occur exactly once in the target file. "- "If it occurs more than once, include enough contiguous surrounding context to make it unique. "- "Do not use match text from the conversation or from another page. "- "If you copy from numbered read output, exclude the `line_number<TAB>` prefix from SEARCH, REPLACE, and DELETE text. "- "If found_in_other_uris is non-empty, diagnose this as a possible page_id mismatch and choose the correct target page_id or rewrite the patch for the current page_id; do not silently move the patch. "- "Regenerate the complete operations JSON, including previous successful operations and fixed failed operations. "- "Output ONLY the complete JSON object matching the required schema.\n\n"- f"Failed patch operations:\n{details}"- )+ return self._output_protocol.render_patch_repair(patch_errors)async def _add_refetch_results_to_messages(self,@@ -1331,12 +1341,15 @@ The final output of the model must strictly follow the JSON Schema format shown# Calculate call_id based on existing tool messagescall_id_seq = len([m for m in messages if m.get("role") == "tool"]) + 1000for uri, parsed in refetch_uris.items():- add_tool_call_pair_to_messages(- messages=messages,- call_id=call_id_seq,- tool_name="read",- params={"uri": uri},- result=parsed,+ messages.extend(+ self._output_protocol.render_tool_result_messages(+ self._output_context,+ call_id=call_id_seq,+ tool_name="read",+ params={"uri": uri},+ result=parsed,+ source="automatic read",+ ))call_id_seq += 1diff --git a/openviking/session/memory/extraction_output_protocol/__init__.py b/openviking/session/memory/extraction_output_protocol/__init__.pynew file mode 100644index 000000000..8d450c811--- /dev/null+++ b/openviking/session/memory/extraction_output_protocol/__init__.py@@ -0,0 +1,31 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Selectable model-output protocols for the memory extraction loop."""++from openviking.session.memory.extraction_output_protocol.base import (+ ExtractionOutputContext,+ ExtractionOutputProtocol,+)+from openviking.session.memory.extraction_output_protocol.json_protocol import (+ JsonExtractionOutputProtocol,+)+from openviking.session.memory.extraction_output_protocol.python_protocol import (+ PythonExtractionOutputProtocol,+)+++def create_extraction_output_protocol(output_format: str) -> ExtractionOutputProtocol:+ if output_format == "json":+ return JsonExtractionOutputProtocol()+ if output_format == "python":+ return PythonExtractionOutputProtocol()+ raise ValueError(f"Unsupported memory extraction output format: {output_format}")+++__all__ = [+ "ExtractionOutputContext",+ "ExtractionOutputProtocol",+ "JsonExtractionOutputProtocol",+ "PythonExtractionOutputProtocol",+ "create_extraction_output_protocol",+]diff --git a/openviking/session/memory/extraction_output_protocol/base.py b/openviking/session/memory/extraction_output_protocol/base.pynew file mode 100644index 000000000..2f408076e--- /dev/null+++ b/openviking/session/memory/extraction_output_protocol/base.py@@ -0,0 +1,115 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Shared contract for memory extraction output protocols."""++from __future__ import annotations++from abc import ABC, abstractmethod+from dataclasses import dataclass+from typing import Any++from pydantic import BaseModel++from openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema+++class ExtractionOutputProtocolError(ValueError):+ """A model response does not satisfy the selected output protocol."""++ def __init__(self, message: str, *, allow_tool_retry: bool = False) -> None:+ super().__init__(message)+ # True when the failure means "the model tried to read/search from the+ # write-only SDK"; the loop should re-open native tools for the retry.+ self.allow_tool_retry = allow_tool_retry+++@dataclass(slots=True)+class ExtractionOutputContext:+ operations_model: type[BaseModel]+ schemas: tuple[MemoryTypeSchema, ...]+ page_id_map: Any+ read_file_contents: dict[str, MemoryFile]+ link_enabled: bool+ role_scope: Any | None = None+ available_tools: tuple[str, ...] = ()+++class ExtractionOutputProtocol(ABC):+ """Render and parse one model-facing extraction output protocol."""++ name: str++ @abstractmethod+ def render_contract(self, context: ExtractionOutputContext) -> str:+ """Render the output API/schema shown to the model."""++ @abstractmethod+ def render_reference_rules(self, context: ExtractionOutputContext) -> str:+ """Render rules for referring to existing and newly created memories."""++ @abstractmethod+ def parse(+ self, content: str, context: ExtractionOutputContext+ ) -> tuple[Any | None, str | None]:+ """Parse model output into the shared dynamic operations model."""++ @abstractmethod+ def render_final_instruction(self, context: ExtractionOutputContext) -> str:+ """Render the instruction used when tool iterations are exhausted."""++ @abstractmethod+ def render_format_retry(self, error: str | None = None) -> str:+ """Render guidance after output parsing fails."""++ @abstractmethod+ def render_patch_repair(self, patch_errors: list[dict[str, Any]]) -> str:+ """Render guidance after a patch cannot be applied."""++ @abstractmethod+ def render_resolution_repair(self, issues: list[dict[str, Any]]) -> str:+ """Render guidance after event operations fail to resolve a write target.++ The loop preserves every already-successful operation and asks the model+ to re-emit only the corrected event operations, so the wording MUST match+ this protocol's own output shape (JSON object vs restricted Python SDK).+ """++ def render_new_bindings(self, context: ExtractionOutputContext, *, source: str) -> str:+ """Render newly available existing-memory references, if the protocol needs them."""+ del context, source+ return ""++ @abstractmethod+ def render_tool_result_messages(+ self,+ context: ExtractionOutputContext,+ *,+ call_id: str | int,+ tool_name: str,+ params: dict[str, Any],+ result: Any,+ source: str,+ ) -> list[dict[str, Any]]:+ """Render one completed tool invocation into model-facing context."""++ def render_prefetch_messages(+ self,+ messages: list[dict[str, Any]],+ context: ExtractionOutputContext,+ ) -> list[dict[str, Any]]:+ """Render provider-prefetched context in this protocol's model-facing form."""+ del context+ return list(messages)++ def normalize_provider_instruction(self, instruction: str) -> str:+ """Adapt provider-specific output wording to this protocol."""+ return instruction++ def describe_empty_response(self) -> str | None:+ """Return the parse-error text for an empty model response, if any."""+ return None++ def keep_tools_enabled_after_parse_error(self, error: str | None) -> bool:+ """Return whether native tools should remain available for the retry."""+ del error+ return Falsediff --git a/openviking/session/memory/extraction_output_protocol/json_protocol.py b/openviking/session/memory/extraction_output_protocol/json_protocol.pynew file mode 100644index 000000000..b08f0608c--- /dev/null+++ b/openviking/session/memory/extraction_output_protocol/json_protocol.py@@ -0,0 +1,131 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Original JSON output protocol for memory extraction."""++from __future__ import annotations++import json+from typing import Any++from openviking.session.memory.extraction_output_protocol.base import (+ ExtractionOutputContext,+ ExtractionOutputProtocol,+)+from openviking.session.memory.tools import add_tool_call_pair_to_messages+from openviking.session.memory.utils import parse_json_with_stability+++class JsonExtractionOutputProtocol(ExtractionOutputProtocol):+ """Preserve the existing JSON prompt and tolerant parsing behavior."""++ name = "json"++ def render_tool_result_messages(+ self,+ context: ExtractionOutputContext,+ *,+ call_id: str | int,+ tool_name: str,+ params: dict[str, Any],+ result: Any,+ source: str,+ ) -> list[dict[str, Any]]:+ del context, source+ messages: list[dict[str, Any]] = []+ add_tool_call_pair_to_messages(+ messages,+ call_id=call_id,+ tool_name=tool_name,+ params=params,+ result=result,+ )+ return messages++ def render_contract(self, context: ExtractionOutputContext) -> str:+ schema = json.dumps(context.operations_model.model_json_schema(), ensure_ascii=False)+ return (+ "## Output Format\n"+ "The final output of the model must strictly follow the JSON Schema format shown below:\n"+ f"```json\n{schema}\n```"+ )++ def render_reference_rules(self, context: ExtractionOutputContext) -> str:+ rules = """+## Page ID Rules+- Every memory item you create or edit MUST include "page_id".+- For existing items, use the page_id shown in read/search results.+- For new items, assign a unique page_id >= 100.+- When editing an existing item, reuse its existing page_id.+- To delete an existing item, add an entry to `delete_ids` using its page_id.+- `delete_ids` deletes the whole item: use it only if every substantive fact is in scope; otherwise MUST use DELETE blocks for affected lines, preserving the rest and not inferring scope from the file name/topic.+- For canonical merges, set `replacement_page_id` to the surviving page that should inherit the deleted page's existing links/backlinks; for pure deletes, set `replacement_page_id` to null.+"""+ if context.link_enabled:+ rules += """+## Link Rules+- Link fields `f` and `t` must reference these page_id values.+- Only create links when the relationship is meaningful and clear from the conversation. Do NOT force links between unrelated items.+"""+ return rules++ def parse(+ self, content: str, context: ExtractionOutputContext+ ) -> tuple[Any | None, str | None]:+ return parse_json_with_stability(+ content=content,+ model_class=context.operations_model,+ expected_fields=list(context.operations_model.model_fields),+ )++ def render_final_instruction(self, context: ExtractionOutputContext) -> str:+ fields = ["delete_ids", *context.operations_model.model_fields]+ skeleton = json.dumps(+ {name: [] for name in dict.fromkeys(fields)},+ ensure_ascii=False,+ indent=2,+ )+ return (+ "You have reached the maximum number of tool call iterations. "+ "Do not call any more tools. Return your final result now as ONLY a valid JSON object "+ "matching the required schema. Do not include explanations or markdown. "+ "If there are no memory changes, return this exact empty-shape JSON with all fields present:\n"+ f"{skeleton}"+ )++ def render_format_retry(self, error: str | None = None) -> str:+ del error+ return (+ "Your previous output could not be parsed as valid JSON. "+ "Please output ONLY a valid JSON object matching the required schema. "+ "Do not include any explanation, markdown formatting, or text outside the JSON."+ )++ def render_patch_repair(self, patch_errors: list[dict[str, Any]]) -> str:+ details = json.dumps(patch_errors, ensure_ascii=False, indent=2)+ return (+ "The SEARCH/REPLACE or DELETE patch could not be applied to the target memory file. "+ "The SEARCH or DELETE text must be copied exactly from the read result of the file bound to that operation's page_id. "+ "The matched text must occur exactly once in the target file. "+ "If it occurs more than once, include enough contiguous surrounding context to make it unique. "+ "Do not use match text from the conversation or from another page. "+ "If you copy from numbered read output, exclude the `line_number<TAB>` prefix from SEARCH, REPLACE, and DELETE text. "+ "If found_in_other_uris is non-empty, diagnose this as a possible page_id mismatch and choose the correct target page_id or rewrite the patch for the current page_id; do not silently move the patch. "+ "Regenerate the complete operations JSON, including previous successful operations and fixed failed operations. "+ "Output ONLY the complete JSON object matching the required schema.\n\n"+ f"Failed patch operations:\n{details}"+ )++ def render_resolution_repair(self, issues: list[dict[str, Any]]) -> str:+ details = json.dumps(issues, ensure_ascii=False, indent=2)+ return (+ "Some event operations could not resolve a safe write target. "+ "Return only corrected event operations for the failed items below; leave every "+ "other memory-type field, delete_ids, and links empty. The server has preserved "+ "all successful operations from the previous response. "+ "Reuse exactly the page_id shown for each failed event. "+ "For event ranges, use valid in-bounds message indexes and include the user-role "+ "message that establishes the event so its owner can be resolved. "+ "Do not target a disallowed or ambiguous peer. Output ONLY one JSON object matching "+ "the required schema.\n\n"+ f"Resolution issues:\n{details}"+ )diff --git a/openviking/session/memory/extraction_output_protocol/python_protocol.py b/openviking/session/memory/extraction_output_protocol/python_protocol.pynew file mode 100644index 000000000..0e49f3e3e--- /dev/null+++ b/openviking/session/memory/extraction_output_protocol/python_protocol.py@@ -0,0 +1,1646 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Restricted Python SDK output protocol for memory extraction."""++from __future__ import annotations++import ast+import json+import keyword+import re+from dataclasses import dataclass, field+from typing import Any, get_args, get_origin++from openviking.core.peer_id import safe_peer_id+from openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchema+from openviking.session.memory.extraction_output_protocol.base import (+ ExtractionOutputContext,+ ExtractionOutputProtocol,+ ExtractionOutputProtocolError,+)+from openviking.session.memory.merge_op import (+ DeleteBlock,+ FieldType,+ MergeOp,+ SearchReplaceBlock,+ StrPatch,+)+from openviking.session.memory.utils.line_numbers import (+ every_line_has_line_numbers,+ strip_line_numbers,+)++_PYTHON_FENCE_RE = re.compile(r"```python[ \t]*\r?\n(?P<code>[\s\S]*?)```", re.IGNORECASE)+_PYTHON_FENCE_START_RE = re.compile(r"```python[ \t]*\r?\n", re.IGNORECASE)+_HIDDEN_MEMORY_FIELDS = {+ "source_extraction_id",+ "source_extraction_ids",+ "last_update_trace_id",+ "version",+}+_SAFE_BUILTINS = {+ "bool": bool,+ "dict": dict,+ "float": float,+ "int": int,+ "len": len,+ "list": list,+ "max": max,+ "min": min,+ "str": str,+ "tuple": tuple,+}+_SAFE_STRING_METHODS = {+ "endswith",+ "join",+ "lower",+ "replace",+ "split",+ "startswith",+ "strip",+ "upper",+}+# Upper bound on the size of a value produced by a DSL expression. Multiplying or+# joining a small literal by a huge count would otherwise allocate a massive+# string/list in the server process before schema validation runs; the check is+# applied to the would-be result size before any allocation.+_MAX_EXPRESSION_SIZE = 1_000_000+_REPEATABLE_SEQUENCES = (str, bytes, list, tuple)+_CONTRACT_PREAMBLE = (+ "## Output Format: restricted Python memory SDK",+ "Return only Python code, optionally wrapped in one ```python code fence.",+ "The code is interpreted as a restricted DSL and cannot access Python modules, files, or the network.",+ "The SDK is write-only. To inspect memories, call the native search/read tools before returning the program; never emit sdk.search(), sdk.read(), or sdk.existing() (only the system binds existing objects).",+ "Never return memory content as bare Markdown; all changes must be arguments to SDK calls.",+ "Existing objects shown by the system may use obj.update(field=value, ...) to set complete "+ "scalar/immutable fields, obj.delete(replacement=None),",+ "and, when links are enabled, obj.link(target, link_type='related_to', weight=0.5, match_text=None, description='').",+ "To change an existing string field, edit it through the object's field attribute. Use the "+ "real field name (e.g. content), NOT the literal word 'field':",+ " - obj.content.update(new_value): replace the whole field with a complete new string.",+ " - obj.content.edit(search=..., replace=...): replace one exact snippet in place.",+ " - obj.content.drop(text=...): delete one exact snippet in place.",+ "edit()/drop() may be chained, e.g. obj.content.edit(search='a', replace='b').drop(text='c'); do not mix them with .update() in one chain.",+ "A field attribute is a write handle only; you cannot read it as a string or call str methods on it.",+ "Each search= (and drop text=) MUST be copied verbatim from the current field value shown in the object's sdk.existing(...) binding, and must occur exactly once. If the snippet appears more than once, include an adjacent unique line just before or after it so the match is unique. Never use text from the conversation or the new facts you intend to add as a search anchor; that text is not in the current content and the edit will fail.",+ "edit()/drop() only work on an existing memory's string field; new memories from create/set must be given complete field values.",+ "For existing memories, prefer the smallest unique edit()/drop(). Do not rewrite the entire field just to add or change a few facts; large full-content rewrites are more likely to be truncated or malformed. Use obj.content.update() only when most of the content changes.",+ 'ALWAYS use a triple-quoted string ("""...""") for EVERY natural-language argument '+ "(content, summary, goal, and every search=/replace=/text= snippet), even one-liners. "+ "Prose frequently contains apostrophes (e.g. Evan's), quotes, colons, or dates that break "+ 'single- or double-quoted literals. Inside triple quotes, escape any literal """ and '+ "backslash; never put a real newline inside a single- or double-quoted string.",+ "Only keyword arguments are accepted by create, set, and obj.update(); a field's update() takes one positional string. Unknown business fields are ignored.",+ "You may end the program with sdk.commit(); when present it must be the final call. Return an empty program when there are no changes.",+ "Use the system-provided existing-object variable names exactly as shown. When a newly "+ "created memory must be referenced by delete(replacement=...) or link(...), assign the "+ "create call to a variable first, for example: canonical = sdk.create_<type>(...); "+ "duplicate_1.delete(replacement=canonical). Never recreate or rebind an existing object "+ "with sdk.existing().",+ "",+ "Available write methods for this extraction:",+)++_LINK_RULES = (+ "",+ "## Link Rules",+ "- Create links between memories when they have a meaningful and clear relationship "+ "(e.g. an event mentioning a person/entity, a preference about a place/activity). "+ "Do NOT force links between unrelated items.",+ "- Use obj.link(target, link_type='related_to', match_text='<word>') as a standalone "+ "statement after both objects exist.",+ "- match_text must be a single exact word that appears in the source object's content. "+ "It is where the link anchor is inserted. Choose the most specific identifying word "+ "(e.g. a person's name, a place, an activity).",+ "- link_type uses lowercase snake_case: related_to (default), belongs_to, "+ "derived_from, caused_by, contradicts, evolved_from.",+ "- For a newly created object, assign the create/set call to a variable first, then "+ "call .link() on it (see the preamble); existing objects use their provided variable names.",+ "- Links are optional; only create them when the relationship is explicit in the "+ "conversation. Do not link every memory to every other memory.",+ "",+ "Example — linking a newly created memory to another new one and to an existing binding "+ "(replace create_<type>/fields with methods and fields from the contract above):",+ "```python",+ "obj_a = sdk.create_<type_a>(...) # a new memory, assigned to a variable",+ "obj_b = sdk.create_<type_b>(...) # another new memory",+ 'obj_a.link(obj_b, link_type="related_to", match_text="<word_in_obj_a>")',+ 'obj_a.link(existing_1, link_type="related_to", match_text="<word_in_obj_a>")',+ "```",+)+++@dataclass(slots=True)+class _MemoryObject:+ name: str+ memory_type: str+ page_id: int+ fields: dict[str, Any]+ existing: bool+ deleted: bool = False+ replacement: _MemoryObject | None = None+ changed_fields: dict[str, Any] = field(default_factory=dict)+++_UNSET = object()+++@dataclass(slots=True)+class _FieldHandle:+ """A pending edit chain on one field of a memory object (obj.field.*)."""++ owner: _MemoryObject+ field_name: str+ blocks: list[Any] = field(default_factory=list)+ full_value: Any = _UNSET+++class PythonExtractionOutputProtocol(ExtractionOutputProtocol):+ """Restricted Python-shaped memory SDK compiler."""++ name = "python"++ def __init__(self) -> None:+ self._uri_to_name: dict[str, str] = {}+ self._type_counts: dict[str, int] = {}+ self._context_counts: dict[str, int] = {}+ self._last_error_allows_tool_retry = False++ def render_contract(self, context: ExtractionOutputContext) -> str:+ _validate_alias_uniqueness(context.schemas)+ lines = list(_CONTRACT_PREAMBLE)+ for schema in context.schemas:+ lines.extend(self._render_schema_contract(context, schema))+ if not context.link_enabled:+ lines.append("Links are disabled; obj.link(...) is unavailable.")+ else:+ lines.extend(_LINK_RULES)+ return "\n".join(lines)++ def _render_schema_contract(+ self, context: ExtractionOutputContext, schema: MemoryTypeSchema+ ) -> list[str]:+ fields = _protocol_fields(context, schema)+ type_alias = _identifier_alias(schema.memory_type)+ signature = ", ".join(+ f"{_identifier_alias(name)}: {type_name}" for name, type_name, _description in fields+ )+ verb = "create" if schema.filename_has_variables() else "set"+ identity_fields = _model_visible_identity_fields(context, schema)+ identity_label = (+ ", ".join(_identifier_alias(name) for name in identity_fields)+ or "target scope (fixed to self)"+ )+ lines = [+ f"- sdk.{verb}_{type_alias}(*, {signature})",+ f" - Identity fields (primary key): {identity_label}. Calls with identical "+ "identity field values address the same memory object.",+ ]+ operation_field = context.operations_model.model_fields.get(schema.memory_type)+ schema_description = getattr(operation_field, "description", None)+ if schema_description:+ # Reuse the already-rendered description from SchemaModelGenerator.+ # This keeps routing/cleanup rules identical to the JSON schema contract+ # (and resolves template variables such as {{ language }}).+ lines.append(" - Memory type rules:\n" + str(schema_description).strip())+ if verb == "set":+ lines.extend(self._render_singleton_rules(context, schema, identity_fields))+ merge_ops = {+ field.name: (+ "editable string: obj.field.edit/drop/update"+ if field.merge_op == MergeOp.PATCH and field.field_type == FieldType.STRING+ else field.merge_op.value+ )+ for field in schema.fields+ }+ for name, _type_name, description in fields:+ normalized_description = " ".join(str(description or "").split())+ qualifier = f" [{merge_ops[name]}]" if name in merge_ops else ""+ lines.append(f" - {_identifier_alias(name)}{qualifier}: {normalized_description}")+ return lines++ @staticmethod+ def _render_singleton_rules(+ context: ExtractionOutputContext,+ schema: MemoryTypeSchema,+ identity_fields: tuple[str, ...],+ ) -> list[str]:+ type_alias = _identifier_alias(schema.memory_type)+ lines = [+ f" - {type_alias} is a SINGLETON per identity: sdk.create_{type_alias}() "+ f"does not exist, and sdk.set_{type_alias}() must appear AT MOST ONCE for each "+ "identity in the whole program. Never call it twice for the same identity (e.g. the same "+ "peer_id). If several people or sections belong to one identity, put them all as separate "+ "H1 sections inside a SINGLE content argument of one call — different headings or person "+ "names do NOT create separate identities. To change an already-shown existing object, "+ "edit that object instead of calling set again."+ ]+ if "peer_id" in identity_fields and context.role_scope is not None:+ if context.role_scope.user_ids:+ lines.append(+ f" - Current self identity: exactly one sdk.set_{type_alias}() call "+ "without peer_id; combine all content sections into its single content argument."+ )+ for peer_id in context.role_scope.peer_ids:+ lines.append(+ f" - Current identity peer_id={peer_id!r}: exactly one "+ f"sdk.set_{type_alias}(peer_id={peer_id!r}, ...) call; combine every "+ "person and section for this peer_id into that one content argument."+ )+ return lines++ def render_reference_rules(self, context: ExtractionOutputContext) -> str:+ del context+ return """+## Memory Object Rules+- Update or delete an existing memory only through its system-provided bound object; never pass or construct a URI.+- Create collection memories with listed sdk.create_<memory_type>(...) methods.+- Set a single-file memory with its listed sdk.set_<memory_type>(...) method; each target scope has only one such object.+- Existing-object identity, storage paths, and immutable fields are preserved by the system.+- delete() removes the whole object; use obj.content.drop(text=...) (with the real field name) when only some content must go and the rest stays.+- For canonical merges, use duplicate.delete(replacement=canonical); for pure deletes, call delete() without replacement.+- delete(replacement=canonical) discards the duplicate's content entirely and keeps only the canonical. Before deleting a duplicate, first fold every distinct valid fact it holds into the canonical (e.g. canonical.content.edit(...)); merging or compacting must never drop a unique fact that only the duplicate recorded.+"""++ def parse(+ self, content: str, context: ExtractionOutputContext+ ) -> tuple[Any | None, str | None]:+ self._last_error_allows_tool_retry = False+ try:+ code = _extract_python_code(content)+ compiler = _PythonProgramCompiler(context=context, protocol=self)+ operations = compiler.compile(code)+ return operations, None+ except ExtractionOutputProtocolError as exc:+ self._last_error_allows_tool_retry = exc.allow_tool_retry+ return None, str(exc)+ except Exception as exc:+ return None, str(exc)++ def render_final_instruction(self, context: ExtractionOutputContext) -> str:+ del context+ return (+ "You have reached the maximum number of tool call iterations. Do not call any more "+ "tools. Return the complete restricted Python memory SDK program now. Output only "+ "Python code. If there are no changes, return an empty program."+ )++ def render_format_retry(self, error: str | None = None) -> str:+ detail = f" Parser error: {error}" if error else ""+ tool_guidance = ""+ binding_guidance = ""+ quote_guidance = ""+ if error and "sdk.existing() is reserved" in error:+ binding_guidance = (+ " Use the existing-object variable names already supplied by the system; do not "+ "emit sdk.existing(). If a new object is the replacement, assign its create call "+ "first, for example `canonical = sdk.create_<type>(...)`, then call "+ "`duplicate_1.delete(replacement=canonical)`."+ )+ if error and _is_string_literal_syntax_error(error):+ quote_guidance = (+ " If the error is about a string literal, the offending line is shown above; a "+ "quote or newline inside prose likely ended the string early. Rewrite every "+ "natural-language argument (content, summary, goal, and every search=/replace=/"+ 'text= snippet) as a triple-quoted string ("""...""") so embedded quotes and '+ "newlines stay inside the literal."+ )+ if self.keep_tools_enabled_after_parse_error(error):+ tool_guidance = (+ " The memory SDK is write-only. Call the available native search/read tool now; "+ "after its result is returned, update the system-provided object variable. "+ "Do not emit sdk.search(), sdk.read(), or construct a memory URI in Python."+ )+ return (+ "Your previous output was not a valid restricted Python memory SDK program."+ f"{detail}{tool_guidance}{binding_guidance}{quote_guidance} Regenerate the complete "+ "program and output no explanation. "+ "Put Markdown memory content inside quoted SDK arguments, using triple-quoted strings "+ '("""...""") for any multi-line or Markdown text so newlines and quotes stay inside '+ "the literal; never return it as the program itself. No changes from the invalid program "+ "were applied."+ )++ def keep_tools_enabled_after_parse_error(self, error: str | None) -> bool:+ # Set by parse() from the structured error flag, so this stays correct+ # even if the write-only read/search rejection wording changes.+ del error+ return self._last_error_allows_tool_retry++ def describe_empty_response(self) -> str | None:+ return "The model returned an empty Python program"++ def render_patch_repair(self, patch_errors: list[dict[str, Any]]) -> str:+ details = json.dumps(patch_errors, ensure_ascii=False, indent=2)+ return (+ "An obj.field.edit()/drop() change could not be applied to the target memory object. "+ "The search= (and drop text=) must be copied verbatim from the current field value shown "+ "in that object's sdk.existing(...) binding, and must occur exactly once. If it occurs "+ "more than once, include enough contiguous surrounding context to make it unique. Do not "+ "use text from the conversation or the new facts you intend to add as a search anchor. "+ "If you copy from numbered read output, exclude the `line_number<TAB>` prefix. If the "+ "change is too broad for a clean snippet, use obj.field.update(complete_new_value) instead. "+ "Regenerate the complete restricted Python SDK program, including previous successful "+ "operations and fixed failed operations. Output only Python code."+ "\n\nFailed edits:\n" + details+ )++ def render_resolution_repair(self, issues: list[dict[str, Any]]) -> str:+ details = json.dumps(issues, ensure_ascii=False, indent=2)+ return (+ "Some sdk.create_events(...) calls could not resolve a safe write target. "+ "Re-emit ONLY corrected create_events() calls for the failed items below; do not "+ "emit any other memory type, delete, or link statements. The server has preserved "+ "all successful operations from the previous program. "+ "For event ranges, pass ranges= with valid in-bounds message indexes that include the "+ "user-role message establishing the event so its owner can be resolved (e.g. "+ 'ranges="3-5"). Do not target a disallowed or ambiguous peer. Keep the same event_name '+ "shown for each failed item so it maps back to that event. Use triple-quoted strings "+ '("""...""") for every natural-language argument. Output only Python code.'+ "\n\nResolution issues:\n" + details+ )++ def render_new_bindings(self, context: ExtractionOutputContext, *, source: str) -> str:+ declarations = []+ for uri, memory_file in context.read_file_contents.items():+ declaration = self._render_existing_binding(+ context, uri=uri, memory_file=memory_file, result=None, source=source+ )+ if declaration:+ declarations.append(declaration)+ if not declarations:+ return ""+ return "\n".join(declarations)++ def render_tool_result_messages(+ self,+ context: ExtractionOutputContext,+ *,+ call_id: str | int,+ tool_name: str,+ params: dict[str, Any],+ result: Any,+ source: str,+ ) -> list[dict[str, Any]]:+ del call_id+ code = self._render_tool_result(+ context, tool_name=tool_name, params=params, result=result, source=source+ )+ return [{"role": "user", "content": code}]++ def render_prefetch_messages(+ self,+ messages: list[dict[str, Any]],+ context: ExtractionOutputContext,+ ) -> list[dict[str, Any]]:+ rendered: list[dict[str, Any]] = []+ for message in messages:+ invocation = _parse_tool_result_message(message)+ if invocation is None:+ # Provider-authored conversation/instruction text may still name+ # JSON; adapt its wording to this protocol without touching the+ # structured tool-result messages rendered below.+ rendered.append(self._normalize_message_instruction(message))+ continue+ tool_name, params, result = invocation+ rendered.extend(+ self.render_tool_result_messages(+ context,+ call_id="prefetch",+ tool_name=tool_name,+ params=params,+ result=result,+ source="prefetch",+ )+ )++ remaining_bindings = self.render_new_bindings(context, source="prefetch")+ if remaining_bindings:+ rendered.append({"role": "user", "content": remaining_bindings})+ return rendered++ def _normalize_message_instruction(self, message: dict[str, Any]) -> dict[str, Any]:+ content = message.get("content")+ if not isinstance(content, str):+ return message+ normalized = self.normalize_provider_instruction(content)+ if normalized == content:+ return message+ return {**message, "content": normalized}++ def _render_tool_result(+ self,+ context: ExtractionOutputContext,+ *,+ tool_name: str,+ params: dict[str, Any],+ result: Any,+ source: str,+ ) -> str:+ if tool_name == "read" and isinstance(result, dict) and "error" not in result:+ uri = str(params.get("uri") or result.get("uri") or "")+ memory_file = context.read_file_contents.get(uri)+ if memory_file is not None:+ binding = self._render_existing_binding(+ context,+ uri=uri,+ memory_file=memory_file,+ result=result,+ source=source,+ )+ if binding:+ return binding+ return self._render_reference_context(result, preferred_name=result.get("context_role"))++ if tool_name == "search":+ return self._render_search_comment(context, params, result)++ if isinstance(result, dict) and "error" in result:+ name = self._next_context_name(f"{tool_name}_error")+ return f"# {tool_name} failed for {params!r}.\n{name} = {result!r}"++ name = self._next_context_name(f"{tool_name}_result")+ return f"# {tool_name} result loaded by {source}.\n{name} = {result!r}"++ @staticmethod+ def _render_search_comment(+ context: ExtractionOutputContext, params: dict[str, Any], result: Any+ ) -> str:+ # Search only returns URIs (no content), so it cannot become an+ # sdk.existing() binding. Files actually read are bound separately as+ # sdk.existing(); how to reach the rest depends on whether a read tool+ # is available this run.+ uris = _search_result_uris(result)+ query = params.get("query")+ query_label = f" query={query!r}" if query else ""+ if not uris:+ return f"# Search{query_label} found no memory files."+ listing = "\n".join(f"# - {uri}" for uri in uris)+ if "read" in context.available_tools:+ guidance = "read them with the read tool before updating them"+ else:+ guidance = (+ "any you need to edit are already provided as sdk.existing bindings; "+ "there is no read tool, so treat anything not shown above as new"+ )+ return f"# Search{query_label} found the following memory files; {guidance}:\n{listing}"++ def _render_existing_binding(+ self,+ context: ExtractionOutputContext,+ *,+ uri: str,+ memory_file: MemoryFile,+ result: dict[str, Any] | None,+ source: str,+ ) -> str:+ name = self._uri_to_name.get(uri)+ if name is not None and result is None:+ return ""+ memory_type = str(+ memory_file.memory_type or memory_file.extra_fields.get("memory_type") or "memory"+ )+ schemas = {schema.memory_type: schema for schema in context.schemas}+ schema = schemas.get(memory_type)+ if schema is None:+ return ""++ if name is None:+ count = self._type_counts.get(memory_type, 0) + 1+ self._type_counts[memory_type] = count+ # Binding variable names must be valid Python identifiers, so alias+ # the memory_type on the DSL surface (real name is kept everywhere else).+ name = f"{_identifier_alias(memory_type)}_{count}"+ self._uri_to_name[uri] = name+ fields = _visible_memory_fields(memory_file, schema, context)+ maintenance_notice = None+ if result is not None:+ fields.update({key: result[key] for key in fields.keys() & result.keys()})+ maintenance_notice = result.get("memory_maintenance_notice")+ content = fields.get("content")+ if isinstance(content, str) and every_line_has_line_numbers(content):+ fields["content"] = strip_line_numbers(content)+ args = [f"memory_type={memory_type!r}"]+ args.extend(f"{_identifier_alias(key)}={value!r}" for key, value in fields.items())+ binding = (+ f"# Existing memory loaded by {source}; this binding is system-provided.\n"+ f"{name} = sdk.existing({', '.join(args)})"+ )+ if maintenance_notice is not None:+ binding += "\n# Memory maintenance notice: " + json.dumps(+ maintenance_notice, ensure_ascii=False+ )+ return binding++ def _render_reference_context(self, result: Any, *, preferred_name: Any = None) -> str:+ name = self._next_context_name(str(preferred_name or "read_result"))+ return f"# Read-only context; this is not a mutable memory object.\n{name} = {result!r}"++ def _next_context_name(self, stem: str) -> str:+ normalized = re.sub(r"\W+", "_", stem).strip("_").lower() or "context"+ if normalized[0].isdigit() or keyword.iskeyword(normalized):+ normalized = f"context_{normalized}"+ count = self._context_counts.get(normalized, 0) + 1+ self._context_counts[normalized] = count+ return normalized if count == 1 else f"{normalized}_{count}"++ def normalize_provider_instruction(self, instruction: str) -> str:+ replacements = {+ "Output JSON only. Do not call any tools.": "Do not call any tools. Follow the output contract below.",+ "Do not call tools. Output JSON only.": "Do not call tools. Follow the output contract below.",+ "follow the provided JSON schema": "follow the provided output contract",+ "Output JSON only.": "Follow the output contract below.",+ "output ONLY a JSON object (no extra text before or after)": "follow the output contract below",+ "output only JSON that matches the schema descriptions": "follow the output contract below",+ "Do NOT use `delete_ids`": "Do NOT call `delete()`",+ "put it in delete_ids": "delete it through its bound memory object",+ }+ for old, new in sorted(replacements.items(), key=lambda item: len(item[0]), reverse=True):+ instruction = instruction.replace(old, new)+ return instruction++ def binding_name(self, uri: str) -> str | None:+ return self._uri_to_name.get(uri)+++def _parse_tool_result_message(+ message: dict[str, Any],+) -> tuple[str, dict[str, Any], Any] | None:+ if message.get("role") != "user" or not isinstance(message.get("content"), str):+ return None+ try:+ payload = json.loads(message["content"])+ except (TypeError, ValueError):+ return None+ if not isinstance(payload, dict) or not isinstance(payload.get("tool_call_name"), str):+ return None+ params = payload.get("args")+ if not isinstance(params, dict) or "result" not in payload:+ return None+ return payload["tool_call_name"], params, payload["result"]+++def _search_result_uris(result: Any) -> list[str]:+ """Extract memory-file URIs from a search tool result of varying shape."""+ items: Any+ if isinstance(result, dict):+ items = result.get("memories", [])+ elif isinstance(result, list):+ items = result+ else:+ items = []+ uris: list[str] = []+ for item in items:+ uri = item.get("uri") if isinstance(item, dict) else item+ if isinstance(uri, str) and uri:+ uris.append(uri)+ return list(dict.fromkeys(uris))+++class _PythonProgramCompiler:+ def __init__(+ self, *, context: ExtractionOutputContext, protocol: PythonExtractionOutputProtocol+ ) -> None:+ self.context = context+ self.protocol = protocol+ # Reject alias collisions before building the maps so a folded-name clash+ # cannot silently overwrite a schema/field (also guards parse() paths that+ # do not go through render_contract first).+ _validate_alias_uniqueness(context.schemas)+ self.schemas = {schema.memory_type: schema for schema in context.schemas}+ # DSL surface uses identifier aliases; map them back to real schema names.+ self._type_alias_to_real = {+ _identifier_alias(schema.memory_type): schema.memory_type for schema in context.schemas+ }+ self._field_alias_to_real = {+ schema.memory_type: {+ _identifier_alias(name): name+ for name, _type, _description in _protocol_fields(context, schema)+ }+ for schema in context.schemas+ }+ self.objects: dict[str, _MemoryObject] = {}+ self.values: dict[str, Any] = {}+ self.links: list[dict[str, Any]] = []+ self._singleton_identities: set[tuple[str, tuple[tuple[str, Any], ...]]] = set()+ self._next_new_page_id = self._find_next_new_page_id(100)+ self._committed = False+ self._load_existing_objects()++ def compile(self, code: str) -> Any:+ try:+ module = ast.parse(code, mode="exec")+ except SyntaxError as exc:+ # A valid program that merely embeds Markdown in a triple-quoted+ # string parses fine, so only fall back to the bare-Markdown hint+ # when parsing actually fails.+ if _looks_like_bare_markdown(code):+ raise ExtractionOutputProtocolError(+ "Output is bare Markdown, not a Python SDK program; put memory content inside "+ "a quoted sdk.create_*/sdk.set_* argument or an existing object's update() call"+ ) from exc+ raise ExtractionOutputProtocolError(+ f"Line {exc.lineno or 1}: invalid Python syntax: {exc.msg}"+ + _format_syntax_error_source(exc)+ ) from exc+ # sdk.commit() is optional: an empty program (or one without commit) simply+ # means "no changes". When present, commit() still acts as a terminator and+ # must be the final statement.+ for index, statement in enumerate(module.body):+ if self._committed:+ self._error(statement, "sdk.commit() must be the final statement")+ self._execute_statement(statement)+ if self._committed and index != len(module.body) - 1:+ self._error(statement, "sdk.commit() must be the final statement")+ return self._build_operations()++ def _load_existing_objects(self) -> None:+ for uri, memory_file in self.context.read_file_contents.items():+ name = self.protocol.binding_name(uri)+ if not name:+ continue+ memory_type = str(+ memory_file.memory_type or memory_file.extra_fields.get("memory_type") or ""+ )+ if memory_type not in self.schemas:+ continue+ page_id = self.context.page_id_map.get_page_id(uri)+ self.objects[name] = _MemoryObject(+ name=name,+ memory_type=memory_type,+ page_id=page_id,+ fields=_visible_memory_fields(memory_file, self.schemas[memory_type], self.context),+ existing=True,+ )++ def _execute_statement(self, node: ast.stmt) -> None:+ if isinstance(node, ast.Assign):+ if len(node.targets) != 1 or not isinstance(node.targets[0], ast.Name):+ self._error(node, "only one simple assignment target is allowed")+ name = node.targets[0].id+ # Evaluate first so an attempted sdk.read()/sdk.search() reports the+ # actionable write-only SDK error even when the model reuses a+ # system-provided binding name on the left-hand side.+ value = self._eval(node.value)+ self._reserve_name(name, node)+ if value is None:+ self._error(node, "side-effect calls cannot be assigned")+ if isinstance(value, _MemoryObject):+ if value.existing or value.name:+ self._error(+ node, "only a new sdk.create_*() or sdk.set_*() result may be assigned"+ )+ value.name = name+ self.objects[name] = value+ elif isinstance(value, _FieldHandle):+ self._error(+ node, "field edits (obj.field.update/edit/drop) must be standalone statements"+ )+ else:+ if _contains_memory_object(value):+ self._error(node, "memory objects cannot be stored in local containers")+ self.values[name] = value+ return+ if isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):+ result = self._eval_call(node.value, statement=True)+ if isinstance(result, _MemoryObject):+ # An unassigned create/set is valid but intentionally cannot be referenced later.+ self.objects[f"__created_{result.page_id}"] = result+ elif isinstance(result, _FieldHandle):+ self._apply_field_handle(result, node)+ elif result is not None:+ self._error(node, "only SDK and memory-object calls may be standalone statements")+ return+ self._error(node, "only assignments and SDK/object calls are allowed")++ def _reserve_name(self, name: str, node: ast.AST) -> None:+ _require_identifier(name, "variable")+ if name == "sdk" or name in _SAFE_BUILTINS or name in self.objects or name in self.values:+ self._error(node, f"variable {name!r} is reserved or already assigned")++ def _eval(self, node: ast.AST) -> Any:+ if isinstance(node, ast.Constant):+ return node.value+ if isinstance(node, ast.Name):+ if node.id in self.objects:+ return self.objects[node.id]+ if node.id in self.values:+ return self.values[node.id]+ self._error(node, f"unknown name {node.id!r}")+ if isinstance(node, ast.List):+ return [self._eval(item) for item in node.elts]+ if isinstance(node, ast.Tuple):+ return tuple(self._eval(item) for item in node.elts)+ if isinstance(node, ast.Dict):+ result = {}+ for key, value in zip(node.keys, node.values, strict=True):+ if key is None:+ expanded = self._eval(value)+ if not isinstance(expanded, dict):+ self._error(node, "dictionary unpacking requires a dict")+ result.update(expanded)+ else:+ result[self._eval(key)] = self._eval(value)+ return result+ if isinstance(node, ast.Attribute):+ owner = self._eval(node.value)+ if not isinstance(owner, _MemoryObject):+ self._error(node, "attribute reads are only allowed on memory objects")+ # Field names use identifier aliases on the DSL surface; map back to+ # the real schema field name before resolving the write handle.+ alias_map = self._field_alias_to_real.get(owner.memory_type, {})+ real_field = alias_map.get(node.attr, node.attr)+ if node.attr.startswith("_") or real_field not in owner.fields:+ available = (+ ", ".join(sorted(_identifier_alias(name) for name in owner.fields)) or "(none)"+ )+ hint = (+ " Use the real field name (e.g. content), not the literal word 'field'."+ if node.attr == "field"+ else ""+ )+ self._error(+ node,+ f"memory field {node.attr!r} is unavailable; editable fields on "+ f"{owner.name or owner.memory_type}: {available}.{hint}",+ )+ # obj.<field> is a write handle, not the raw value: it exposes+ # .update()/.edit()/.drop() and cannot be read as a string.+ return _FieldHandle(owner=owner, field_name=real_field)+ if isinstance(node, ast.Subscript):+ return self._eval(node.value)[self._eval_slice(node.slice)]+ if isinstance(node, ast.JoinedStr):+ return "".join(+ self._eval_formatted_value(part)+ if isinstance(part, ast.FormattedValue)+ else part.value+ for part in node.values+ )+ if isinstance(node, ast.BinOp):+ return self._eval_binop(node)+ if isinstance(node, ast.UnaryOp):+ value = self._eval(node.operand)+ if isinstance(node.op, ast.Not):+ return not value+ if isinstance(node.op, ast.USub):+ return -value+ if isinstance(node.op, ast.UAdd):+ return +value+ self._error(node, "unsupported unary operator")+ if isinstance(node, ast.BoolOp):+ value = self._eval(node.values[0])+ for operand in node.values[1:]:+ if isinstance(node.op, ast.And):+ if not value:+ return value+ elif value:+ return value+ value = self._eval(operand)+ return value+ if isinstance(node, ast.Compare):+ return self._eval_compare(node)+ if isinstance(node, ast.IfExp):+ return self._eval(node.body if self._eval(node.test) else node.orelse)+ if isinstance(node, ast.Call):+ return self._eval_call(node)+ self._error(node, f"unsupported expression {type(node).__name__}")++ def _eval_call(self, node: ast.Call, *, statement: bool = False) -> Any:+ if any(keyword.arg is None for keyword in node.keywords):+ self._error(node, "**kwargs is not allowed in calls")+ if isinstance(node.func, ast.Name):+ if node.func.id not in _SAFE_BUILTINS:+ self._error(+ node,+ f"function {node.func.id!r} is not allowed",+ allow_tool_retry=node.func.id in ("read", "search"),+ )+ args = [self._eval(arg) for arg in node.args]+ kwargs = {item.arg: self._eval(item.value) for item in node.keywords}+ if _contains_memory_object((args, kwargs)):+ self._error(node, "memory objects cannot be converted or placed in containers")+ return _SAFE_BUILTINS[node.func.id](*args, **kwargs)+ if not isinstance(node.func, ast.Attribute):+ self._error(node, "unsupported call target")+ if isinstance(node.func.value, ast.Name) and node.func.value.id == "sdk":+ return self._call_sdk(node, statement=statement)+ owner = self._eval(node.func.value)+ if isinstance(owner, _MemoryObject):+ return self._call_memory(owner, node.func.attr, node, statement=statement)+ if isinstance(owner, _FieldHandle):+ return self._call_field(owner, node.func.attr, node)+ if isinstance(owner, str) and node.func.attr in _SAFE_STRING_METHODS:+ args = [self._eval(arg) for arg in node.args]+ kwargs = {item.arg: self._eval(item.value) for item in node.keywords}+ if node.func.attr == "join" and args and isinstance(args[0], (list, tuple)):+ pieces = [str(piece) for piece in args[0]]+ projected = sum(len(piece.encode("utf-8")) for piece in pieces) + (+ len(owner.encode("utf-8")) * max(len(pieces) - 1, 0)+ )+ if projected > _MAX_EXPRESSION_SIZE:+ self._error(+ node,+ f"joined string would exceed the {_MAX_EXPRESSION_SIZE:,}-character size limit",+ )+ elif node.func.attr == "replace" and len(args) >= 2:+ # str.replace can inflate the result well beyond its input when the+ # replacement is longer than the search text and occurs many times.+ # Bound the projected size BEFORE calling replace so a huge result is+ # never allocated (str.replace builds the whole string in C first).+ count = args[2] if len(args) > 2 else kwargs.get("count")+ self._check_replace_size(node, owner, args[0], args[1], count)+ return getattr(owner, node.func.attr)(*args, **kwargs)+ self._error(node, f"method {node.func.attr!r} is not allowed")++ def _check_replace_size(+ self, node: ast.AST, source: str, old: Any, new: Any, count: Any+ ) -> None:+ if not isinstance(old, str) or not isinstance(new, str):+ self._error(node, "replace() expects string arguments")+ old_bytes = len(old.encode("utf-8"))+ new_bytes = len(new.encode("utf-8"))+ source_bytes = len(source.encode("utf-8"))+ if new_bytes <= old_bytes:+ # Replacement is not longer than the match: result cannot grow.+ return+ if old == "":+ # "".replace inserts new between every character (len+1 positions).+ occurrences = len(source) + 1+ else:+ occurrences = source.count(old)+ if isinstance(count, int) and not isinstance(count, bool) and count >= 0:+ occurrences = min(occurrences, count)+ elif count is not None:+ self._error(node, "replace() count must be a non-negative integer")+ projected = source_bytes + occurrences * (new_bytes - old_bytes)+ if projected > _MAX_EXPRESSION_SIZE:+ self._error(+ node,+ f"replaced string would exceed the {_MAX_EXPRESSION_SIZE:,}-character size limit",+ )++ def _call_sdk(self, node: ast.Call, *, statement: bool) -> Any:+ method = node.func.attr+ if method.startswith(("create_", "set_")):+ verb, type_alias = method.split("_", 1)+ if node.args:+ self._error(node, f"{verb} methods accept keyword arguments only")+ memory_type = self._type_alias_to_real.get(type_alias, type_alias)+ schema = self.schemas.get(memory_type)+ if schema is None:+ self._error(node, f"memory type {type_alias!r} is not available")+ expected_verb = "create" if schema.filename_has_variables() else "set"+ if verb != expected_verb:+ self._error(+ node,+ f"sdk.{method}() is unavailable for {type_alias!r}; "+ f"use sdk.{expected_verb}_{type_alias}()",+ )+ allowed_fields = {+ name for name, _type, _description in _protocol_fields(self.context, schema)+ }+ kwargs = self._eval_keywords(+ node,+ allowed=allowed_fields,+ ignore_unknown=True,+ alias_map=self._field_alias_to_real.get(memory_type),+ )+ if _contains_memory_object(kwargs):+ self._error(node, "memory objects cannot be used as business field values")+ if any(isinstance(value, _FieldHandle) for value in kwargs.values()):+ action = "creating" if verb == "create" else "setting"+ self._error(+ node,+ f"field edits (obj.field.edit/drop) cannot be used when {action} a memory; "+ "pass the complete field value",+ )+ missing_fields = [field.name for field in schema.fields if field.name not in kwargs]+ if missing_fields:+ self._error(+ node,+ f"{verb} requires complete memory fields; missing: "+ + ", ".join(missing_fields),+ )+ if verb == "set":+ identity = _memory_identity(schema, kwargs)+ identity_key = (memory_type, identity)+ if identity_key in self._singleton_identities:+ identity_text = _format_identity(identity)+ peer_id = _normalized_peer_scope(kwargs.get("peer_id"))+ target = f"peer {peer_id!r}" if peer_id is not None else "self"+ self._error(+ node,+ f"duplicate {type_alias} identity ({identity_text}); "+ f"sdk.set_{type_alias}() may be called only once for {target}; "+ "combine all people and content sections for that target into "+ "one content argument",+ )+ self._singleton_identities.add(identity_key)+ obj = _MemoryObject(+ name="",+ memory_type=memory_type,+ page_id=self._next_new_page_id,+ fields=dict(kwargs),+ existing=False,+ changed_fields=dict(kwargs),+ )+ self._next_new_page_id = self._find_next_new_page_id(self._next_new_page_id + 1)+ return obj+ if method == "commit":+ kwargs = self._eval_keywords(node)+ if node.args or kwargs or not statement:+ self._error(node, "sdk.commit() must be an argument-free standalone statement")+ if self._committed:+ self._error(node, "sdk.commit() may appear only once")+ self._committed = True+ return None+ if method == "existing":+ self._error(node, "sdk.existing() is reserved for system-provided bindings")+ self._error(+ node,+ f"unknown SDK method sdk.{method}()",+ allow_tool_retry=method in ("read", "search"),+ )++ def _call_memory(+ self, owner: _MemoryObject, method: str, node: ast.Call, *, statement: bool+ ) -> None:+ if not statement:+ self._error(node, f"{method}() must be a standalone statement")+ if not owner.existing and not owner.name:+ self._error(node, "assign a new memory object before calling methods on it")+ if method == "update":+ if node.args:+ self._error(node, "update() accepts keyword arguments only")+ schema = self.schemas[owner.memory_type]+ allowed_fields = {+ name for name, _type, _description in _protocol_fields(self.context, schema)+ }+ kwargs = self._eval_keywords(+ node,+ allowed=allowed_fields,+ ignore_unknown=True,+ alias_map=self._field_alias_to_real.get(owner.memory_type),+ )+ if _contains_memory_object(kwargs):+ self._error(node, "memory objects cannot be used as business field values")+ if any(isinstance(value, _FieldHandle) for value in kwargs.values()):+ self._error(+ node,+ "to edit a string field in place use obj.field.edit(...)/obj.field.drop(...); "+ "obj.update() only takes complete field values",+ )+ self._update(owner, kwargs, node)+ return None+ if method == "delete":+ kwargs = self._eval_keywords(node)+ if node.args or set(kwargs) - {"replacement"}:+ self._error(node, "delete() accepts only replacement=")+ if not owner.existing:+ self._error(node, "a memory created in this program cannot be deleted")+ if self.schemas[owner.memory_type].operation_mode == "add_only":+ self._error(node, "delete() is unavailable for the selected memory schemas")+ replacement = kwargs.get("replacement")+ if replacement is not None and not isinstance(replacement, _MemoryObject):+ self._error(node, "delete replacement must be a memory object")+ if replacement is not None and not replacement.existing and not replacement.name:+ self._error(node, "assign a new replacement object before referencing it")+ if replacement is not None and replacement.memory_type != owner.memory_type:+ self._error(node, "delete replacement must have the same memory type")+ if replacement is owner:+ self._error(node, "a memory cannot replace itself")+ owner.deleted = True+ owner.replacement = replacement+ return None+ if method == "link":+ kwargs = self._eval_keywords(node)+ if not self.context.link_enabled:+ self._error(node, "links are disabled by configuration")+ if len(node.args) != 1:+ self._error(node, "link() requires exactly one target memory object")+ target = self._eval(node.args[0])+ if not isinstance(target, _MemoryObject):+ self._error(node, "link target must be a memory object")+ if not target.existing and not target.name:+ self._error(node, "assign a new link target before referencing it")+ allowed = {"link_type", "weight", "match_text", "description"}+ if set(kwargs) - allowed:+ self._error(node, "link() received unsupported arguments")+ self.links.append(+ {+ "f": owner.page_id,+ "t": target.page_id,+ "link_type": kwargs.get("link_type", "related_to"),+ "weight": kwargs.get("weight", 0.5),+ "match_text": kwargs.get("match_text"),+ "description": kwargs.get("description", ""),+ }+ )+ return None+ self._error(+ node,+ f"unknown memory method {method}()",+ allow_tool_retry=method in ("read", "search"),+ )++ def _call_field(self, handle: _FieldHandle, method: str, node: ast.Call) -> _FieldHandle:+ if method == "update":+ kwargs = self._eval_keywords(node)+ if kwargs or len(node.args) != 1:+ self._error(+ node,+ "field.update() takes exactly one positional argument: the complete new value",+ )+ value = self._eval(node.args[0])+ if _contains_memory_object(value) or isinstance(value, _FieldHandle):+ self._error(node, "field.update() value must be a plain string")+ if handle.blocks or handle.full_value is not _UNSET:+ self._error(node, "field.update() cannot be chained with edit()/drop()")+ handle.full_value = value+ return handle+ if method in ("edit", "drop"):+ if handle.full_value is not _UNSET:+ self._error(node, "field.edit()/drop() cannot be chained after update()")+ kwargs = self._eval_keywords(node)+ if method == "edit":+ if node.args or set(kwargs) != {"search", "replace"}:+ self._error(+ node,+ "field.edit() requires exactly search= and replace= keyword arguments: "+ "obj.field.edit(search=..., replace=...)",+ )+ block: Any = SearchReplaceBlock(search=kwargs["search"], replace=kwargs["replace"])+ else:+ if node.args or set(kwargs) != {"text"}:+ self._error(+ node, "field.drop() requires exactly text=: obj.field.drop(text=...)"+ )+ block = DeleteBlock(delete=kwargs["text"])+ if _contains_memory_object(block):+ self._error(node, "memory objects cannot be used as patch text")+ handle.blocks.append(block)+ return handle+ self._error(+ node,+ f"unknown field method {method}(); use obj.field.update(...), "+ "obj.field.edit(search=..., replace=...), or obj.field.drop(text=...)",+ )++ def _apply_field_handle(self, handle: _FieldHandle, node: ast.AST) -> None:+ owner = handle.owner+ name = handle.field_name+ schema = self.schemas[owner.memory_type]+ field_schema = {item.name: item for item in schema.fields}.get(name)+ if handle.full_value is _UNSET and not handle.blocks:+ self._error(node, f"{owner.name}.{name} edit has no update()/edit()/drop() call")+ if (+ field_schema is not None+ and field_schema.merge_op == MergeOp.IMMUTABLE+ and owner.existing+ ):+ # Immutable identity fields cannot change on an existing memory; ignore silently.+ return+ if handle.full_value is not _UNSET:+ owner.fields[name] = handle.full_value+ owner.changed_fields[name] = handle.full_value+ return+ # Local edit chain: only valid for existing PATCH string fields.+ if not owner.existing:+ self._error(+ node,+ "field.edit()/drop() can only patch an existing memory; a memory created in "+ "this program has no prior content — pass the complete value to field.update()",+ )+ if field_schema is None or not (+ field_schema.merge_op == MergeOp.PATCH and field_schema.field_type == FieldType.STRING+ ):+ self._error(node, f"field {name!r} does not support edit()/drop()")+ # Do NOT apply here. Store the edits as a StrPatch so python mode flows through+ # the same resolve_operations -> _validate_patch_operations -> patch-repair path+ # as json mode: a failed snippet is isolated to its own operation and gets the+ # structured patch-repair retry instead of failing the whole program.+ # Accumulate across multiple obj.field.edit()/drop() statements on the same field.+ existing = owner.changed_fields.get(name)+ prior_blocks = existing.blocks if isinstance(existing, StrPatch) else []+ patch = StrPatch(blocks=[*prior_blocks, *handle.blocks])+ owner.fields[name] = patch+ owner.changed_fields[name] = patch++ def _eval_keywords(+ self,+ node: ast.Call,+ *,+ allowed: set[str] | None = None,+ ignore_unknown: bool = False,+ alias_map: dict[str, str] | None = None,+ ) -> dict[str, Any]:+ values: dict[str, Any] = {}+ for item in node.keywords:+ name = item.arg+ if alias_map is not None:+ # Field names use identifier aliases on the DSL surface; map back+ # to the real schema field name before validating/storing.+ name = alias_map.get(name, name)+ if name in values:+ self._error(node, f"keyword argument {name!r} was provided more than once")+ if allowed is not None and name not in allowed and ignore_unknown:+ continue+ values[name] = self._eval(item.value)+ return values++ def _update(self, owner: _MemoryObject, changes: dict[str, Any], node: ast.AST) -> None:+ schema = self.schemas[owner.memory_type]+ fields = {item.name: item for item in schema.fields}+ dynamic_fields = {+ name for name, _type, _description in _protocol_fields(self.context, schema)+ } - fields.keys()+ owner.deleted = False+ owner.replacement = None+ for name, value in changes.items():+ field_schema = fields.get(name)+ if name in dynamic_fields:+ if not owner.existing:+ owner.fields[name] = value+ owner.changed_fields[name] = value+ continue+ if field_schema is None:+ continue+ if field_schema.merge_op == MergeOp.IMMUTABLE and owner.existing:+ continue+ current = owner.fields.get(name)+ if field_schema.merge_op == MergeOp.SUM:+ value = (current or 0) + value+ previous_delta = owner.changed_fields.get(name, 0)+ owner.changed_fields[name] = previous_delta + changes[name]+ owner.fields[name] = value+ continue+ owner.fields[name] = value+ owner.changed_fields[name] = value++ def _build_operations(self) -> Any:+ payload: dict[str, Any] = {name: [] for name in self.context.operations_model.model_fields}+ deleted_ids: set[int] = set()+ replacement_ids: dict[int, int] = {}+ for obj in self.objects.values():+ if obj.deleted:+ deleted_ids.add(obj.page_id)+ if obj.replacement is not None:+ replacement_ids[obj.page_id] = obj.replacement.page_id+ payload.setdefault("delete_ids", []).append(+ {+ "delete_page_id": obj.page_id,+ "replacement_page_id": (+ obj.replacement.page_id if obj.replacement is not None else None+ ),+ }+ )+ continue+ if not obj.changed_fields:+ continue+ fields = dict(obj.changed_fields)+ if obj.existing:+ schema = self.schemas[obj.memory_type]+ for memory_field in schema.fields:+ if memory_field.merge_op == MergeOp.IMMUTABLE:+ if memory_field.name in obj.fields:+ fields[memory_field.name] = obj.fields[memory_field.name]+ payload[obj.memory_type].append({"page_id": obj.page_id, **fields})+ if self.context.link_enabled:+ payload["links"] = []+ for link in self.links:+ remapped = dict(link)+ skip = False+ for endpoint in ("f", "t"):+ replacement_id = self._resolve_replacement(+ remapped[endpoint], deleted_ids, replacement_ids+ )+ if replacement_id is None:+ skip = True+ break+ remapped[endpoint] = replacement_id+ if not skip and remapped["f"] != remapped["t"]:+ payload["links"].append(remapped)+ try:+ return self.context.operations_model.model_validate(payload)+ except Exception as exc:+ raise ExtractionOutputProtocolError(+ f"SDK operations failed schema validation: {exc}"+ ) from exc++ @staticmethod+ def _resolve_replacement(+ page_id: int, deleted_ids: set[int], replacement_ids: dict[int, int]+ ) -> int | None:+ visited = set()+ while page_id in deleted_ids:+ if page_id in visited:+ return None+ visited.add(page_id)+ replacement_id = replacement_ids.get(page_id)+ if replacement_id is None:+ return None+ page_id = replacement_id+ return page_id++ def _eval_slice(self, node: ast.AST) -> Any:+ if isinstance(node, ast.Slice):+ return slice(+ self._eval(node.lower) if node.lower else None,+ self._eval(node.upper) if node.upper else None,+ self._eval(node.step) if node.step else None,+ )+ return self._eval(node)++ def _eval_formatted_value(self, node: ast.FormattedValue) -> str:+ value = self._eval(node.value)+ if _contains_memory_object(value):+ self._error(node, "memory objects cannot be formatted")+ if node.conversion == ord("r"):+ value = repr(value)+ elif node.conversion == ord("a"):+ value = ascii(value)+ elif node.conversion == ord("s"):+ value = str(value)+ elif node.conversion != -1:+ self._error(node, "unsupported f-string conversion")+ # A format spec (e.g. {x:>1000001}) can turn a small integer literal into+ # an arbitrarily large padded string with no repeat operator. Memory+ # content never needs printf-style alignment/width, so disallow any+ # non-empty format spec instead of trying to bound width inflation.+ if node.format_spec is not None:+ spec = self._eval(node.format_spec)+ if spec != "":+ self._error(+ node,+ "f-string format specs are not allowed; use plain {value} without a "+ "':' width/format spec",+ )+ return format(value, "")++ def _eval_binop(self, node: ast.BinOp) -> Any:+ if isinstance(node.op, ast.Mult):+ return self._eval_mult(node)+ left, right = self._eval(node.left), self._eval(node.right)+ if isinstance(node.op, ast.Mod) and isinstance(left, (str, bytes)):+ # str/bytes % formatting (e.g. "%1000001s" % "x") can inflate a small+ # literal into a huge padded string via a width field, with no repeat+ # operator. Memory content never needs printf formatting, so disallow it.+ self._error(+ node,+ "string %-formatting is not allowed; build content with plain literals",+ )+ operations = {+ ast.Add: lambda: self._checked_concat(node, left, right),+ ast.Sub: lambda: left - right,+ ast.Div: lambda: left / right,+ ast.FloorDiv: lambda: left // right,+ ast.Mod: lambda: left % right,+ }+ operation = operations.get(type(node.op))+ if operation is None:+ self._error(node, "unsupported binary operator")+ return operation()++ def _sequence_repeat_size(self, sequence: Any, count: Any, node: ast.AST) -> int:+ if not isinstance(count, int) or isinstance(count, bool):+ self._error(node, "a repeated literal must be multiplied by an integer count")+ if count < 0:+ self._error(node, "a repeated literal count cannot be negative")+ if isinstance(sequence, str):+ unit = len(sequence.encode("utf-8"))+ elif isinstance(sequence, (bytes, bytearray)):+ unit = len(sequence)+ else:+ unit = len(sequence)+ return unit * count++ def _checked_repeat(self, node: ast.AST, sequence: Any, count: Any) -> Any:+ if not isinstance(sequence, _REPEATABLE_SEQUENCES):+ self._error(node, "multiplication is only supported for repeating a literal")+ if not isinstance(count, int) or isinstance(count, bool) or count < 0:+ self._error(node, "a repeated literal must be multiplied by a non-negative integer")+ if self._sequence_repeat_size(sequence, count, node) > _MAX_EXPRESSION_SIZE:+ self._error(+ node,+ f"repeated literal would exceed the {_MAX_EXPRESSION_SIZE:,}-character size limit",+ )+ return sequence * count++ def _eval_mult(self, node: ast.BinOp) -> Any:+ left_node, right_node = node.left, node.right+ # Repeat a literal sequence by an integer count. Both a bare literal+ # and a literal nested inside another repeatable expression+ # (e.g. ["..."] * n inside "".join(...)) are accepted; evaluate only+ # after the would-be result size is bounded, before any allocation.+ left_seq, left_count = self._repeat_operands(left_node, right_node)+ right_seq, right_count = self._repeat_operands(right_node, left_node)+ if left_seq is not None:+ return self._checked_repeat(node, left_seq, left_count)+ if right_seq is not None:+ return self._checked_repeat(node, right_seq, right_count)+ self._error(+ node,+ "multiplication is only supported to repeat a string/list literal "+ "by a non-negative integer count",+ )++ def _repeat_operands(self, seq_node: ast.AST, count_node: ast.AST) -> tuple[Any, Any]:+ if isinstance(seq_node, ast.Constant) and isinstance(seq_node.value, _REPEATABLE_SEQUENCES):+ return seq_node.value, self._eval(count_node)+ # A 1-element list literal (ast.List with one Constant element) is a+ # common way to build a repeatable argument for str.join.+ if (+ isinstance(seq_node, ast.List)+ and len(seq_node.elts) == 1+ and isinstance(seq_node.elts[0], ast.Constant)+ ):+ return [seq_node.elts[0].value], self._eval(count_node)+ return None, None++ def _checked_concat(self, node: ast.AST, left: Any, right: Any) -> Any:+ if isinstance(left, str) and isinstance(right, str):+ if len(left.encode("utf-8")) + len(right.encode("utf-8")) > _MAX_EXPRESSION_SIZE:+ self._error(+ node,+ f"concatenated string exceeds the {_MAX_EXPRESSION_SIZE:,}-character size limit",+ )+ elif isinstance(left, (list, tuple)) and isinstance(right, (list, tuple)):+ if len(left) + len(right) > _MAX_EXPRESSION_SIZE:+ self._error(+ node, f"concatenated list exceeds the {_MAX_EXPRESSION_SIZE:,}-item size limit"+ )+ return left + right++ def _eval_compare(self, node: ast.Compare) -> bool:+ left = self._eval(node.left)+ for operator, comparator in zip(node.ops, node.comparators, strict=True):+ right = self._eval(comparator)+ if isinstance(operator, ast.Eq):+ matches = left == right+ elif isinstance(operator, ast.NotEq):+ matches = left != right+ elif isinstance(operator, ast.Lt):+ matches = left < right+ elif isinstance(operator, ast.LtE):+ matches = left <= right+ elif isinstance(operator, ast.Gt):+ matches = left > right+ elif isinstance(operator, ast.GtE):+ matches = left >= right+ elif isinstance(operator, ast.In):+ matches = left in right+ elif isinstance(operator, ast.NotIn):+ matches = left not in right+ elif isinstance(operator, ast.Is):+ matches = left is right+ elif isinstance(operator, ast.IsNot):+ matches = left is not right+ else:+ self._error(node, "unsupported comparison operator")+ if not matches:+ return False+ left = right+ return True++ def _find_next_new_page_id(self, candidate: int) -> int:+ while self.context.page_id_map.resolve(candidate) is not None:+ candidate += 1+ return candidate++ @staticmethod+ def _error(node: ast.AST, message: str, *, allow_tool_retry: bool = False) -> None:+ raise ExtractionOutputProtocolError(+ f"Line {getattr(node, 'lineno', 1)}: {message}",+ allow_tool_retry=allow_tool_retry,+ )+++def _extract_python_code(content: str) -> str:+ stripped = str(content or "").strip()+ matches = list(_PYTHON_FENCE_RE.finditer(stripped))+ if len(matches) == 1:+ match = matches[0]+ surrounding_text = stripped[: match.start()] + stripped[match.end() :]+ if "```" not in surrounding_text:+ return match.group("code").rstrip()+ starts = list(_PYTHON_FENCE_START_RE.finditer(stripped))+ if len(starts) == 1 and stripped.count("```") == 1:+ return stripped[starts[0].end() :].strip()+ if "```" in stripped:+ raise ExtractionOutputProtocolError(+ "Python output may contain only one complete ```python code fence"+ )+ return stripped+++def _is_string_literal_syntax_error(error: str) -> bool:+ """Heuristic: does this parse error point at a broken string literal?++ These are almost always caused by an apostrophe or quote inside prose that+ was wrapped in a single-/double-quoted literal instead of a triple-quoted+ one, so the retry should push hard on triple quotes.+ """+ lowered = error.lower()+ return any(+ marker in lowered+ for marker in (+ "unterminated string literal",+ "unterminated triple-quoted string",+ "invalid syntax. perhaps you forgot a comma",+ "eol while scanning string literal",+ "invalid escape sequence",+ )+ )+++def _format_syntax_error_source(exc: SyntaxError, *, max_len: int = 120) -> str:+ """Render the offending source line (and a caret) from a SyntaxError.++ Python's own message (e.g. "Perhaps you forgot a comma?") is often+ misleading for these programs; the real cause is usually a quote or newline+ inside prose that should have been triple-quoted. Showing the actual line+ lets the model see the break point instead of guessing.+ """+ text = (exc.text or "").rstrip("\n")+ if not text:+ return ""+ stripped = text.lstrip()+ lead = len(text) - len(stripped)+ offset = exc.offset+ caret_col = None+ if isinstance(offset, int) and offset >= 1:+ caret_col = max(0, offset - 1 - lead)+ if len(stripped) > max_len:+ stripped = stripped[:max_len] + "…"+ if caret_col is not None and caret_col > max_len:+ caret_col = None+ lines = [f"\n {stripped}"]+ if caret_col is not None and caret_col <= len(stripped):+ lines.append("\n " + " " * caret_col + "^")+ return "".join(lines)+++def _looks_like_bare_markdown(code: str) -> bool:+ lines = [line.strip() for line in code.splitlines() if line.strip()]+ return (+ bool(lines)+ and lines[0].startswith("# ")+ and any(line.startswith(("- ", "* ")) for line in lines[1:])+ and not any("sdk." in line for line in lines)+ )+++def _visible_memory_fields(+ memory_file: MemoryFile,+ schema: MemoryTypeSchema,+ context: ExtractionOutputContext,+) -> dict[str, Any]:+ schema_fields = {name for name, _type, _description in _protocol_fields(context, schema)}+ fields = {+ key: value+ for key, value in dict(memory_file.extra_fields or {}).items()+ if key in schema_fields and key not in _HIDDEN_MEMORY_FIELDS and not key.startswith("_")+ }+ if "content" in schema_fields:+ fields["content"] = memory_file.plain_content()+ return fields+++def _field_type_name(field_type: FieldType) -> str:+ return {+ FieldType.STRING: "str",+ FieldType.INT64: "int",+ FieldType.FLOAT32: "float",+ FieldType.BOOL: "bool",+ }.get(field_type, "object")+++def _protocol_fields(+ context: ExtractionOutputContext, schema: MemoryTypeSchema+) -> list[tuple[str, str, str]]:+ static_fields = [+ (field.name, _field_type_name(field.field_type), field.description)+ for field in schema.fields+ ]+ static_names = {name for name, _type, _description in static_fields}+ operations_field = context.operations_model.model_fields.get(schema.memory_type)+ annotation = getattr(operations_field, "annotation", None)+ model_type = get_args(annotation)[0] if get_origin(annotation) is list else annotation+ dynamic_fields = getattr(model_type, "model_fields", {})+ extras = []+ for name, model_field in dynamic_fields.items():+ if name == "page_id" or name in static_names:+ continue+ # Non-identifier field names are aliased on the DSL surface (see+ # _identifier_alias), so they need not be valid Python identifiers here.+ extras.append(+ (name, _annotation_type_name(model_field.annotation), model_field.description or "")+ )+ return [*extras, *static_fields]+++def _model_visible_identity_fields(+ context: ExtractionOutputContext, schema: MemoryTypeSchema+) -> tuple[str, ...]:+ visible_fields = {name for name, _type, _description in _protocol_fields(context, schema)}+ return tuple(name for name in schema.identity_fields() if name in visible_fields)+++def _memory_identity(+ schema: MemoryTypeSchema, fields: dict[str, Any]+) -> tuple[tuple[str, Any], ...]:+ return tuple(+ (+ name,+ _normalized_peer_scope(fields.get(name)) if name == "peer_id" else fields.get(name),+ )+ for name in schema.identity_fields()+ )+++def _format_identity(identity: tuple[tuple[str, Any], ...]) -> str:+ return ", ".join(+ f"{name}={'<self>' if name == 'peer_id' and value is None else value!r}"+ for name, value in identity+ )+++def _annotation_type_name(annotation: Any) -> str:+ args = [item for item in get_args(annotation) if item is not type(None)]+ if args:+ annotation = args[0]+ return getattr(annotation, "__name__", "object")+++def _normalized_peer_scope(value: Any) -> str | None:+ if value in (None, "", "__self"):+ return None+ return safe_peer_id(value)+++def _contains_memory_object(value: Any) -> bool:+ if isinstance(value, _MemoryObject):+ return True+ if isinstance(value, dict):+ return any(+ _contains_memory_object(key) or _contains_memory_object(item)+ for key, item in value.items()+ )+ if isinstance(value, (list, tuple)):+ return any(_contains_memory_object(item) for item in value)+ return False+++def _require_identifier(value: str, label: str) -> None:+ if not value.isidentifier() or keyword.iskeyword(value):+ raise ValueError(+ f"Python memory output requires {label} {value!r} to be a valid identifier"+ )+++def _identifier_alias(name: str) -> str:+ """Map a schema name to a Python-identifier alias used only on the DSL surface.++ memory_type and field names keep their real value everywhere (URI, storage,+ JSON protocol); only the Python method/parameter names need to be valid+ identifiers, so non-identifier characters are folded to underscores.+ """+ alias = re.sub(r"\W", "_", name)+ if alias and alias[0].isdigit():+ alias = f"_{alias}"+ if not alias:+ alias = "_"+ if keyword.iskeyword(alias):+ alias = f"{alias}_"+ return alias+++def _validate_alias_uniqueness(schemas: tuple[MemoryTypeSchema, ...]) -> None:+ """Reject schemas whose names collide after identifier-alias folding.++ Aliasing is not one-to-one (e.g. 'project-notes' and 'project_notes' both+ fold to 'project_notes'). A collision would make the DSL surface ambiguous+ and silently route calls to the wrong schema/field, so fail loudly at build+ time instead. Distinct-identifier names never collide, so real configs are+ unaffected.+ """+ type_seen: dict[str, str] = {}+ for schema in schemas:+ alias = _identifier_alias(schema.memory_type)+ if alias in type_seen and type_seen[alias] != schema.memory_type:+ raise ValueError(+ f"memory_type {type_seen[alias]!r} and {schema.memory_type!r} produce the same "+ f"Python DSL alias {alias!r}; rename one to a distinct identifier"+ )+ type_seen[alias] = schema.memory_type++ field_seen: dict[str, str] = {}+ for name in {memory_field.name for memory_field in schema.fields}:+ field_alias = _identifier_alias(name)+ if field_alias in field_seen and field_seen[field_alias] != name:+ raise ValueError(+ f"fields {field_seen[field_alias]!r} and {name!r} in memory_type "+ f"{schema.memory_type!r} produce the same Python DSL alias {field_alias!r}; "+ "rename one to a distinct identifier"+ )+ field_seen[field_alias] = namediff --git a/openviking/session/memory/memory_updater.py b/openviking/session/memory/memory_updater.pyindex 41522f996..9535a3cf9 100644--- a/openviking/session/memory/memory_updater.py+++ b/openviking/session/memory/memory_updater.py@@ -1286,8 +1286,10 @@ class MemoryUpdater:try:content = await viking_fs.read_file(deleted_uri, ctx=ctx)except Exception as e:- tracer.error(- f"Failed to read deleted memory links for replacement {deleted_uri}: {e}"+ # Benign: the replacement/deleted file may already be gone in the+ # same batch. Link inheritance is best-effort, so warn and skip.+ logger.warning(+ f"Skipping link inheritance; could not read deleted memory {deleted_uri}: {e}")continueif not content:@@ -1363,6 +1365,10 @@ class MemoryUpdater:lease_ref=lease_ref,)result.add_edited(uri)+ except (NotFoundError, FileNotFoundError) as e:+ # Benign: a linked neighbor may have been deleted in the same+ # batch. Link inheritance is best-effort, so warn and skip.+ logger.warning(f"Skipping link inheritance; could not read memory {uri}: {e}")except Exception as e:tracer.error(f"Failed to inherit deleted memory links for {uri}: {e}")diff --git a/openviking/session/memory/merge_policy.py b/openviking/session/memory/merge_policy.pynew file mode 100644index 000000000..ce5c0a3d4--- /dev/null+++ b/openviking/session/memory/merge_policy.py@@ -0,0 +1,20 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Shared model-facing policy for safe memory reorganization."""++MEMORY_MERGE_POLICY = """+## Memory Reorganization Safety+- Search similarity, a shared category, or an overlapping topic only identifies candidates for+ review. It is never sufficient evidence that two memories have the same identity.+- Merge memories only when they have the same identity under the active memory schema. For+ real-world entities or events, require the same object or occurrence, or an explicit alias. For+ preferences, both the owner and the behavioral choice dimension must match.+- Keep distinct people, pets, works, artworks, products, possessions, places, events, and+ preferences separate even when they share attributes, participants, categories, or themes.+- Before deleting or replacing a source memory, account for every substantive atomic fact in it.+ Preserve each non-duplicate fact exactly once in a surviving destination. If identity is uncertain+ or any fact lacks one clear destination, keep the source separate.+- When a memory is too large or mixes multiple identities or choice dimensions, split it. Compact+ only duplicate wording; never satisfy a size target by dropping, weakening, or generalizing a+ concrete fact. Suggested length limits are readability targets, not permission to lose facts.+""".strip()diff --git a/openviking/session/memory/patch_merge_context_provider.py b/openviking/session/memory/patch_merge_context_provider.pyindex 199a61f5d..aa9ed99ee 100644--- a/openviking/session/memory/patch_merge_context_provider.py+++ b/openviking/session/memory/patch_merge_context_provider.py@@ -11,6 +11,7 @@ from typing import Anyfrom openviking.server.identity import RequestContextfrom openviking.session.memory.dataclass import MemoryFile, MemoryTypeSchemafrom openviking.session.memory.memory_type_registry import MemoryTypeRegistry+from openviking.session.memory.merge_policy import MEMORY_MERGE_POLICYfrom openviking.session.memory.session_extract_context_provider import (SessionExtractContextProvider,)@@ -141,14 +142,18 @@ Do not call tools. Output JSON only.All memory content must be written in {output_language}.-Reconcile independent extraction patch proposals: merge duplicate/overlapping-memories into one canonical file patch, and keep distinct memories separate.+Reconcile independent extraction patch proposals. Apply this shared policy before+choosing a canonical file or deleting any proposal:++{MEMORY_MERGE_POLICY}+Normalize URI/path variants for directory/filename fields. Treat path segmentfields as stable schema identifiers, not free-form labels. Reuse existingequivalent directories across singular/plural, synonym, or language/scriptvariants. For new segments, use singular snake_case for English and one concisecanonical term for Chinese; e.g. book not books, 书籍 not 书/图书. If a loser URI-is an existing file, put it in delete_ids; if it is only a new proposal, omit it.+is a verified duplicate existing file, put it in delete_ids with the fact-complete+canonical replacement; if it is only a duplicate new proposal, omit it."""def get_tools(self) -> list[str]:diff --git a/openviking/session/memory/session_extract_context_provider.py b/openviking/session/memory/session_extract_context_provider.pyindex a7990234d..87ea75772 100644--- a/openviking/session/memory/session_extract_context_provider.py+++ b/openviking/session/memory/session_extract_context_provider.py@@ -21,6 +21,7 @@ from openviking.session.memory.memory_isolation_handler import (from openviking.session.memory.memory_type_registry import (MemoryTypeRegistry,)+from openviking.session.memory.merge_policy import MEMORY_MERGE_POLICYfrom openviking.session.memory.tools import (add_tool_call_pair_to_messages,get_tool,@@ -191,7 +192,7 @@ class SessionExtractContextProvider(ExtractContextProvider):"""## Resource URI Handling-- If the conversation contains a resource URI (`viking://resources/...`, `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources/...`) and the user says a durable fact, judgment, preference, or event about it, extract that memory into the appropriate normal memory type such as entities, events, or preferences.+- If the conversation contains a resource URI (`viking://resources/...`, `viking://user/{user_id}/resources/...`, or `viking://user/{user_id}/peers/{peer_id}/resources/...`) and the user says a durable fact, judgment, preference, or event about it, extract that memory into whichever enabled memory type its schema best fits.- Preserve resource references as markdown links in visible memory content when useful. Example: user said "The user saved a Ryoma Echizen photo viking://resources/images/ryoma" -> write "The user saved a [Ryoma Echizen photo](viking://resources/images/ryoma)".- For `## Resource Addition` blocks, use `User reason` as the user's intent and `Resource abstract` only as optional context. Do not copy raw fields such as `Resource URI`, `Added at`, `Resource abstract`, or `User reason` into visible memory content.- For `## Resource Deletion` blocks, update existing mutable memories that mention or depend on the deleted resource. Do not create a new event solely for this maintenance action.@@ -207,7 +208,7 @@ class SessionExtractContextProvider(ExtractContextProvider):if contains_resource_urielse "")- goal = f"""You are a memory extraction agent. Your task is to analyze conversations and update memories.+ goal = f"""You are a memory extraction and maintenance agent. Analyze the conversation together with the pre-fetched existing memories, then produce a single atomic plan to create, update, delete, or reorganize memories so that the final memory collection conforms to all enabled memory schemas.## Workflow1. Analyze the conversation and pre-fetched context@@ -230,10 +231,15 @@ The system automatically generates URIs based on memory_type and fields. Just prWhen a memory item describes the current user, omit peer_id.When a memory item describes a peer, set peer_id to one of the peer_id values allowed bythe output schema. Do not invent peer_id values.-For events with ranges, the system derives self/peer targets from the message range.-Message role is authoritative: user-role content is the source for profile/preferences/entities/events,-and assistant-role content is the source for cases/patterns/tools/skills. Do not infer ownership-from neighboring messages.+For memory items that carry a message-range field, the system derives self/peer targets from that range.+Message role is authoritative for newly extracted facts: attribute each fact to the speaker whose+message states it, and follow each enabled memory type's own schema rules for which role its content+comes from. Do not infer ownership from neighboring messages.+Facts already stored in pre-fetched or explicitly read memories remain valid sources for+maintenance and may be preserved, normalized, merged, split, or moved between enabled memory+types when required by their schemas.++{MEMORY_MERGE_POLICY}"""return goaldiff --git a/openviking/session/memory/tools.py b/openviking/session/memory/tools.pyindex 76dee7e9e..49dff3077 100644--- a/openviking/session/memory/tools.py+++ b/openviking/session/memory/tools.py@@ -13,6 +13,7 @@ from typing import TYPE_CHECKING, Any, Dict, List, Optional, Unionfrom openviking.session.memory.utils import add_line_numbers, line_count, slice_content_linesfrom openviking.session.memory.utils.memory_file_utils import MemoryFileUtilsfrom openviking.telemetry import tracer+from openviking.utils.token_estimation import estimate_text_tokensfrom openviking_cli.exceptions import NotFoundErrorfrom openviking_cli.utils import get_logger@@ -28,6 +29,34 @@ _LLM_HIDDEN_MEMORY_FIELDS = {}+def memory_maintenance_notice(+ content: str, *, review_after_tokens: int | None = None+) -> Optional[Dict[str, Any]]:+ """Return maintenance metadata only when a memory exceeds the soft size threshold."""+ if review_after_tokens is None:+ from openviking_cli.utils.config import get_openviking_config++ review_after_tokens = get_openviking_config().memory.maintenance_review_tokens+ estimated_tokens = estimate_text_tokens(content)+ if estimated_tokens <= review_after_tokens:+ return None+ guidance = (+ f"This memory is estimated at {estimated_tokens:,} tokens, above the "+ f"{review_after_tokens:,}-token readability target, so maintenance is required: do not "+ "leave it as one broad oversized memory. Preserve every distinct valid fact exactly once. "+ "For a topic-keyed collection such as preferences, split different behavioral choice "+ "dimensions into focused same-type memories. For an identity-keyed collection such as "+ "entities, never invent multiple identities for one object; split only if distinct "+ "identities were mixed. Compact only duplicate wording, never concrete facts. Aim for the "+ f"{review_after_tokens:,}-token target, but fact integrity takes priority. Delete or replace "+ "the oversized source only after every fact has one clear destination."+ )+ return {+ "maintenance_required": True,+ "guidance": guidance,+ }++def optimize_search_result(result: Any, limit: int = 10) -> Any:"""优化搜索结果以减少 Token 消耗,并过滤掉抽象文件。"""if isinstance(result, dict) and "error" in result:@@ -206,6 +235,9 @@ class MemoryReadTool(MemoryTool):if page_id is not None:llm_result["page_id"] = page_idplain_content = mf.plain_content() or ""+ maintenance_notice = memory_maintenance_notice(plain_content)+ if maintenance_notice is not None:+ llm_result["memory_maintenance_notice"] = maintenance_noticevisible_content = slice_content_lines(plain_content, offset=offset, limit=limit)if visible_content:llm_result["content"] = add_line_numbers(visible_content, start_line=offset + 1)diff --git a/openviking/session/memory/utils/messages.py b/openviking/session/memory/utils/messages.pyindex b3ccb1a26..dac2f4acd 100644--- a/openviking/session/memory/utils/messages.py+++ b/openviking/session/memory/utils/messages.py@@ -4,76 +4,21 @@Message formatting and memory file parsing utilities."""-import jsonfrom typing import Any, Dict, Listimport json_repairfrom openviking.session.memory.utils.memory_fields import MEMORY_FIELDS_COMMENT_REfrom openviking.telemetry import tracer+from openviking.utils.message_format import format_messagesfrom openviking_cli.utils import get_loggerlogger = get_logger(__name__)def pretty_print_messages(messages: List[Dict[str, Any]]) -> None:- """- Print messages in a human-readable format.-- Formats messages with [role] headers and indented content for readability.- Tool calls and results are printed in a way that shows their correspondence.-- Args:- messages: List of message dictionaries with 'role', 'content', and optional 'tool_calls'- """- output = ["=== Messages ==="]- for msg in messages:- role = msg.get("role", "unknown")- content = msg.get("content", "")-- if role == "tool_call":- # Optimized tool call format - print as JSON to match stored format- output.append(f"\n[{role}]")- output.append(json.dumps(msg, ensure_ascii=False, indent=2))- elif role == "tool":- # Legacy tool result format- tool_call_id = msg.get("tool_call_id", "")- output.append(f"\n[{role}] (id={tool_call_id})")- if content:- try:- result_json = json.loads(content)- output.append(json.dumps(result_json, indent=2, ensure_ascii=False))- except (json.JSONDecodeError, TypeError):- output.append(content)- else:- if content:- output.append(f"\n[{role}]")- # Handle content as dict (e.g., tool_call format)- if isinstance(content, dict):- output.append(json.dumps(content, ensure_ascii=False, indent=2))- else:- output.append(content)-- if "tool_calls" in msg and msg["tool_calls"]:- # Legacy tool call format- tool_calls = msg["tool_calls"]- if len(tool_calls) == 1:- tc = tool_calls[0]- tc_id = tc.get("id", "")- tc_name = tc.get("function", {}).get("name", "")- output.append(f"\n[{role} tool_call] (id={tc_id}, name={tc_name})")- args_str = tc.get("function", {}).get("arguments", {})- try:- args_json = json.loads(args_str)- output.append(json.dumps(args_json, indent=2, ensure_ascii=False))- except:- output.append(args_str)- else:- output.append(f"\n[{role} tool_calls]")- output.append(json.dumps(tool_calls, indent=2, ensure_ascii=False))-- output.append("\n=== End Messages ===")- tracer.info("llm_input_messages=" + "\n".join(output))+ """Trace messages in a human-readable format (see utils.message_format)."""+ tracer.info("llm_input_messages=" + format_messages(messages))def parse_memory_file_with_fields(content: str) -> Dict[str, Any]:diff --git a/openviking/session/memory/utils/template_utils.py b/openviking/session/memory/utils/template_utils.pyindex 6fd471bb4..8938aaad8 100644--- a/openviking/session/memory/utils/template_utils.py+++ b/openviking/session/memory/utils/template_utils.py@@ -46,3 +46,15 @@ class TemplateUtils:- ignored- {"extract_context"})++ @staticmethod+ def referenced_variables(template: str) -> set[str]:+ """Return the top-level variables a template actually references.++ Uses Jinja's own parser so filters, functions, and attribute/method+ names (e.g. ``lower`` in ``{{ name|lower }}`` or ``get_year`` in+ ``{{ extract_context.get_year(ranges) }}``) are never mistaken for+ variables the way a plain substring/regex scan would.+ """+ parsed_template = jinja2.Environment(autoescape=False).parse(template)+ return meta.find_undeclared_variables(parsed_template)diff --git a/openviking/utils/message_format.py b/openviking/utils/message_format.pynew file mode 100644index 000000000..53e732b86--- /dev/null+++ b/openviking/utils/message_format.py@@ -0,0 +1,113 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Human-readable formatting for LLM message lists (shared by memory and VLM layers)."""++import json+from typing import Any, Dict, List+++def sanitize_openai_messages(messages: List[Dict[str, Any]]) -> List[Dict[str, Any]]:+ """Return a copy without structurally empty assistant messages.++ OpenAI-compatible chat APIs reject an assistant message unless it has+ meaningful content or a tool/function call. Persisted sessions may still+ contain empty assistant turns as context markers, so sanitize only at the+ provider request boundary.+ """+ sanitized: List[Dict[str, Any]] = []+ for message in messages:+ if not isinstance(message, dict):+ # Non-dict entries are passed through untouched; only dict messages+ # carry the role/content structure this filter reasons about.+ sanitized.append(message)+ continue+ copied = dict(message)+ if copied.get("role") == "assistant":+ has_content = _has_message_content(copied.get("content"))+ has_tool_call = bool(copied.get("tool_calls") or copied.get("function_call"))+ if not has_content and not has_tool_call:+ continue+ sanitized.append(copied)+ return sanitized+++def _has_message_content(content: Any) -> bool:+ if isinstance(content, str):+ return bool(content.strip())+ if isinstance(content, list):+ return any(_has_content_part(part) for part in content)+ return bool(content)+++def _has_content_part(part: Any) -> bool:+ if isinstance(part, str):+ return bool(part.strip())+ if not isinstance(part, dict):+ return part is not None+ for key in ("text", "image_url", "input_image", "refusal"):+ value = part.get(key)+ if isinstance(value, str) and value.strip():+ return True+ if value and not isinstance(value, str):+ return True+ return False+++def format_messages(messages: List[Dict[str, Any]]) -> str:+ """Render a chat message list in a human-readable ``[role]``-headed layout.++ Tool calls and results are shown so their correspondence is visible. Returns+ the formatted string; callers decide how to log/trace it.++ Args:+ messages: List of message dicts with 'role', 'content', and optional 'tool_calls'.+ """+ output = ["=== Messages ==="]+ for msg in messages:+ role = msg.get("role", "unknown")+ content = msg.get("content", "")++ if role == "tool_call":+ # Optimized tool call format - print as JSON to match stored format+ output.append(f"\n[{role}]")+ output.append(json.dumps(msg, ensure_ascii=False, indent=2))+ elif role == "tool":+ # Legacy tool result format+ tool_call_id = msg.get("tool_call_id", "")+ output.append(f"\n[{role}] (id={tool_call_id})")+ if content:+ try:+ result_json = json.loads(content)+ output.append(json.dumps(result_json, indent=2, ensure_ascii=False))+ except (json.JSONDecodeError, TypeError):+ output.append(content)+ else:+ if content:+ output.append(f"\n[{role}]")+ # Structured/multimodal content is easier to inspect as JSON and+ # must be stringified before joining the output lines.+ if not isinstance(content, str):+ output.append(json.dumps(content, ensure_ascii=False, indent=2))+ else:+ output.append(content)++ if "tool_calls" in msg and msg["tool_calls"]:+ # Legacy tool call format+ tool_calls = msg["tool_calls"]+ if len(tool_calls) == 1:+ tc = tool_calls[0]+ tc_id = tc.get("id", "")+ tc_name = tc.get("function", {}).get("name", "")+ output.append(f"\n[{role} tool_call] (id={tc_id}, name={tc_name})")+ args_str = tc.get("function", {}).get("arguments", {})+ try:+ args_json = json.loads(args_str)+ output.append(json.dumps(args_json, indent=2, ensure_ascii=False))+ except Exception:+ output.append(args_str)+ else:+ output.append(f"\n[{role} tool_calls]")+ output.append(json.dumps(tool_calls, indent=2, ensure_ascii=False))++ output.append("\n=== End Messages ===")+ return "\n".join(output)diff --git a/openviking_cli/utils/config/memory_config.py b/openviking_cli/utils/config/memory_config.pyindex fef57fed3..3cb1eeaae 100644--- a/openviking_cli/utils/config/memory_config.py+++ b/openviking_cli/utils/config/memory_config.py@@ -1,6 +1,6 @@# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.# SPDX-License-Identifier: AGPL-3.0-from typing import Any, Dict+from typing import Any, Dict, Literalfrom pydantic import BaseModel, Field, field_validator, model_validator@@ -56,6 +56,14 @@ class MemoryConfig(BaseModel):"When multiple directories are searched, results are merged and top-N are read."),)+ maintenance_review_tokens: int = Field(+ default=1000,+ gt=0,+ description=(+ "Estimated token count above which a full memory read includes an LLM maintenance "+ "notice asking it to choose between coherent splitting and single-file compaction."+ ),+ )extraction_enabled: bool = Field(default=True,description=(@@ -65,6 +73,14 @@ class MemoryConfig(BaseModel):"stateless deployments."),)+ extraction_output_format: Literal["json", "python"] = Field(+ default="python",+ description=(+ "Final model-output protocol used by every memory extraction loop. "+ "'python' uses the restricted internal memory SDK DSL (default); "+ "'json' preserves the legacy structured JSON protocol."+ ),+ )session_skill_extraction_enabled: bool = Field(default=False,description=(diff --git a/tests/benchmark/test_memory_organization.py b/tests/benchmark/test_memory_organization.pynew file mode 100644index 000000000..85fa9ad65--- /dev/null+++ b/tests/benchmark/test_memory_organization.py@@ -0,0 +1,638 @@+import json+from pathlib import Path++import pytest++from benchmark.memory_organization.autonomous_cases import build_cases+from benchmark.memory_organization.autonomous_grader import (+ autonomous_metrics,+ grade_autonomous_result,+)+from benchmark.memory_organization.grader import (+ grade_result,+ mcnemar_exact_p_value,+ paired_counts,+ summarize,+)+from benchmark.memory_organization.models import (+ OrganizationCase,+ fact_lines,+ fact_markers,+ load_cases,+)+from benchmark.memory_organization.report_autonomous import regrade_rows, summarize_autonomous+from benchmark.memory_organization.run_ab import _call_count+from benchmark.memory_organization.run_autonomous_ab import (+ AutonomousProvider,+ _close_vlm_async_clients,+ build_jobs,+ parse_args,+ run_one,+)+++def _case() -> OrganizationCase:+ return OrganizationCase.from_dict(+ {+ "case_id": "merge",+ "category": "merge",+ "canonical_topics": ["travel"],+ "initial_files": {"travel": "[F01] A", "trip": "[F02] B"},+ "expected_files": {"travel": ["F01", "F02"]},+ "expected_replacements": {"travel": "travel", "trip": "travel"},+ }+ )+++def test_all_fixtures_have_unique_markers_and_expected_topics():+ cases = load_cases(+ Path(__file__).parents[2]+ / "benchmark"+ / "memory_organization"+ / "cases"+ / "organization_cases.json"+ )++ assert len(cases) == 12+ assert {case.category for case in cases} == {"merge", "split", "mixed"}+ assert all(set(case.expected_files) == set(case.canonical_topics) for case in cases)+ for case in cases:+ source_markers = [+ marker for content in case.initial_files.values() for marker in fact_markers(content)+ ]+ assert len(source_markers) == len(set(source_markers))+ assert set(source_markers) == case.expected_markers+++def test_stress_fixtures_are_large_and_well_formed():+ cases = load_cases(+ Path(__file__).parents[2]+ / "benchmark"+ / "memory_organization"+ / "cases"+ / "organization_stress_cases.json"+ )++ assert len(cases) == 3+ assert all(len(case.expected_markers) >= 24 for case in cases)+ for case in cases:+ source_markers = [+ marker for content in case.initial_files.values() for marker in fact_markers(content)+ ]+ assert len(source_markers) == len(set(source_markers))+ assert set(source_markers) == case.expected_markers+++def test_autonomous_suite_contains_the_three_core_cases():+ cases = build_cases()++ assert [case.case_id for case in cases] == [+ "case_insensitive_directory_collision",+ "oversized_profile_routes_preferences",+ "oversized_preference_splits",+ ]+ assert [case.category for case in cases] == [+ "directory_merge",+ "cross_type_split",+ "same_type_split",+ ]+ assert cases[0].messages[0].parts[0].text == (+ "你还记得 Atlas 项目的发布方式、回滚流程和日常运维信息吗?"+ )+ assert cases[1].messages[0].parts[0].text == (+ "你还记得我的基本情况,以及我在工作、饮食、旅行和游戏方面的偏好吗?"+ )+ assert all(case.messages[0].parts[0].text != "请继续。" for case in cases)+++def test_parallel_jobs_are_unique_and_counterbalanced():+ jobs = build_jobs(build_cases(), repeat=2)++ assert len(jobs) == 12+ assert len({(case_id, protocol, repeat) for _, case_id, protocol, repeat in jobs}) == 12+ assert jobs[:2] == [+ (0, "case_insensitive_directory_collision", "json", 0),+ (1, "case_insensitive_directory_collision", "python", 0),+ ]+ assert jobs[6:8] == [+ (6, "case_insensitive_directory_collision", "python", 1),+ (7, "case_insensitive_directory_collision", "json", 1),+ ]+++def test_parallel_argument_requires_positive_value():+ assert parse_args(["--parallel", "6"]).parallel == 6+ with pytest.raises(SystemExit):+ parse_args(["--parallel", "0"])+++async def test_parallel_worker_closes_loop_bound_vlm_clients():+ closed: list[str] = []++ class Client:+ async def close(self):+ closed.append("closed")++ class Cache:+ def pop_all(self):+ return [Client()]++ class VLM:+ _async_client_cache = Cache()++ await _close_vlm_async_clients(VLM())++ assert closed == ["closed"]+++def test_exact_two_split_case_combines_existing_and_conversation_facts():+ case = {case.case_id: case for case in build_cases()}["oversized_preference_splits"]++ assert len(case.initial_files) == 1+ assert len(next(iter(case.initial_files.values())).content.splitlines()) == 32+ assert len(case.expected_facts) == 40+ assert set(case.expected_facts) == {f"F{index:02d}" for index in range(25, 65)}+ assert len(case.expected_groups["preferences"]) == 2+ assert len(case.additional_facts or {}) == 8+ assert len(case.messages) == 1+++def test_preference_split_action_accepts_two_or_more_new_files():+ case = {case.case_id: case for case in build_cases()}["oversized_preference_splits"]+ source_uri = next(iter(case.initial_files))+ files = {}+ for index, group in enumerate(case.expected_groups["preferences"], start=1):+ content = "\n".join(+ f"- [{marker}] {case.expected_facts[marker]}" for marker in sorted(group)+ )+ files[f"viking://user/default/memories/preferences/Andrew/topic_{index}.md"] = (+ "preferences",+ content,+ )++ grade = grade_autonomous_result(case, files, {})+ metrics = autonomous_metrics(case, files, {}, grade)++ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]++ first_child_uri = next(iter(files))+ files[source_uri] = files.pop(first_child_uri)+ grade = grade_autonomous_result(case, files, {})+ assert not autonomous_metrics(case, files, {}, grade)["organization_action_success"]++ files = {+ source_uri: (+ "preferences",+ "\n".join(+ f"- [{marker}] {case.expected_facts[marker]}"+ for marker in sorted(case.expected_facts)+ ),+ )+ }+ grade = grade_autonomous_result(case, files, {})+ assert not autonomous_metrics(case, files, {}, grade)["organization_action_success"]+++def test_preference_split_action_accepts_alternative_partition_and_more_children():+ case = {case.case_id: case for case in build_cases()}["oversized_preference_splits"]+ markers = sorted(case.expected_facts)+ files = {}+ for index, group in enumerate((markers[:36], markers[36:]), start=1):+ files[f"viking://user/default/memories/preferences/Andrew/alternative_{index}.md"] = (+ "preferences",+ "\n".join(f"- [{marker}] {case.expected_facts[marker]}" for marker in group),+ )++ grade = grade_autonomous_result(case, files, {})+ metrics = autonomous_metrics(case, files, {}, grade)++ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]++ marker = markers.pop()+ files[next(reversed(files))] = (+ "preferences",+ "\n".join(f"- [{item}] {case.expected_facts[item]}" for item in markers[36:]),+ )+ files["viking://user/default/memories/preferences/Andrew/third.md"] = (+ "preferences",+ f"- [{marker}] {case.expected_facts[marker]}",+ )+ grade = grade_autonomous_result(case, files, {})+ metrics = autonomous_metrics(case, files, {}, grade)+ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]+++async def test_autonomous_prompts_do_not_leak_expected_partition():+ cases = {case.case_id: case for case in build_cases()}+ profile_case = cases["oversized_profile_routes_preferences"]+ provider = AutonomousProvider(profile_case)++ messages = await provider.prefetch()+ visible = (+ provider.instruction()+ + "\n"+ + "\n".join(str(message.get("content", "")) for message in messages)+ )++ assert profile_case.case_id not in visible+ assert "exactly five" not in visible+ assert "food, travel" not in visible+ assert "expected_groups" not in visible+ assert "Decide autonomously" not in visible+ assert "preserved, normalized, merged, split, or moved" in visible+ assert "You are a memory extraction and maintenance agent" in provider.instruction()+ assert {schema.memory_type for schema in provider.get_memory_schemas(None)} == {+ schema.memory_type+ for schema in provider._get_registry().list_all(include_disabled=False)+ if schema.stage == "user"+ }+++def test_autonomous_provider_accepts_explicit_output_language():+ case = build_cases()[0]++ provider = AutonomousProvider(case, output_language="zh-CN")++ assert provider.get_output_language() == "zh-CN"+++async def test_run_one_restores_vlm_recorder(monkeypatch):+ class FakeUsage:+ def get_token_usage(self):+ return {"total_usage": {}}++ def reset_token_usage(self):+ pass++ async def get_completion_async(self, *args, **kwargs):+ del args, kwargs+ return ""++ provider = "fake"+ model = "fake"+ temperature = 0.0+ thinking = False+ max_tokens = None++ class FakeMemoryConfig:+ extraction_output_format = "python"+ link_enabled = False++ class FakeVLMConfig:+ def __init__(self, vlm):+ self._vlm = vlm++ def get_vlm_instance(self):+ return self._vlm++ class FakeConfig:+ def __init__(self, vlm):+ self.memory = FakeMemoryConfig()+ self.vlm = FakeVLMConfig(vlm)++ async def fake_run(self):+ await self.vlm.get_completion_async(messages=[])+ raise RuntimeError("stop after recording")++ from openviking.session.memory.extract_loop import ExtractLoop++ monkeypatch.setattr(ExtractLoop, "run", fake_run)+ vlm = FakeUsage()+ original = vlm.get_completion_async++ row = await run_one(build_cases()[0], "python", 0, FakeConfig(vlm))++ assert len(row["raw_responses"]) == 1+ assert vlm.get_completion_async == original+++def test_autonomous_directory_grader_accepts_case_normalization():+ case = build_cases()[0]+ target = "viking://user/default/memories/entities/projects/atlas.md"+ source = "viking://user/default/memories/entities/Projects/atlas.md"+ grade = grade_autonomous_result(+ case,+ {+ target: (+ "entities",+ "# Atlas\nAtlas 是一个软件服务。\n\n## 事实\n"+ "- [F01] 使用分阶段发布。\n"+ "- [F02] 有明确记录的回滚流程。\n"+ "- [F03] 由平台团队负责。\n"+ "- [F04] 提供健康检查接口。",+ )+ },+ {source: target},+ )++ assert grade.organization_success+ metrics = autonomous_metrics(+ case,+ {+ target: (+ "entities",+ "# Atlas\nAtlas 是一个软件服务。\n\n## 事实\n"+ "- [F01] 使用分阶段发布。\n"+ "- [F02] 有明确记录的回滚流程。\n"+ "- [F03] 由平台团队负责。\n"+ "- [F04] 提供健康检查接口。",+ )+ },+ {source: target},+ grade,+ )+ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]+++def test_autonomous_profile_grader_requires_cross_type_routing():+ case = build_cases()[1]+ profile_uri = "viking://user/default/memories/profile.md"+ profile = case.initial_files[profile_uri].content++ grade = grade_autonomous_result(case, {profile_uri: ("profile", profile)}, {})++ assert not grade.content_organization_success+ assert grade.misplaced_fact_count > 0+ metrics = autonomous_metrics(case, {profile_uri: ("profile", profile)}, {}, grade)+ assert not metrics["organization_action_success"]+ assert metrics["information_integrity"]+++def test_profile_move_action_is_independent_of_information_integrity():+ case = build_cases()[1]+ files = {+ "viking://user/default/memories/profile.md": (+ "profile",+ "# 安德鲁\n- 是一名后端工程师 (as of 2026-08-01)",+ ),+ "viking://user/default/memories/preferences/安德鲁/food.md": (+ "preferences",+ "- 喜欢吃辣味面条 (as of 2026-08-01)",+ ),+ }++ grade = grade_autonomous_result(case, files, {})+ metrics = autonomous_metrics(case, files, {}, grade)++ assert metrics["organization_action_success"]+ assert not metrics["information_integrity"]+++def test_autonomous_routing_allows_schema_formatting_changes():+ case = build_cases()[1]+ profile_uri = "viking://user/default/memories/profile.md"+ source_lines = case.initial_files[profile_uri].content.splitlines()+ profile = "\n".join(+ line.replace(f"[F{index:02d}] ", "")+ for index, line in enumerate(source_lines[1:7], start=1)+ )+ preference = "\n".join(+ line.replace(f"[F{index:02d}] ", "").replace(" (as of 2026-08-01)", "")+ for index, line in enumerate(source_lines[7:], start=7)+ )+ files = {+ profile_uri: ("profile", profile),+ "viking://user/default/memories/preferences/andrew/all.md": (+ "preferences",+ preference,+ ),+ }+ grade = grade_autonomous_result(case, files, {})+ metrics = autonomous_metrics(case, files, {}, grade)++ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]+ assert set(metrics) == {"organization_action_success", "information_integrity"}+++def test_autonomous_report_regrades_stored_rows():+ case = build_cases()[1]+ profile_uri = "viking://user/default/memories/profile.md"+ source_lines = case.initial_files[profile_uri].content.splitlines()+ profile = "\n".join(line.split("] ", 1)[1] for line in source_lines[1:7])+ preference = "\n".join(+ line.split("] ", 1)[1].replace(" (as of 2026-08-01)", "") for line in source_lines[7:]+ )+ rows = [+ {+ "case_id": case.case_id,+ "grade": {},+ "autonomous_metrics": {},+ "actual_files": {+ profile_uri: {"memory_type": "profile", "content": profile},+ "viking://user/default/memories/preferences/Andrew/all.md": {+ "memory_type": "preferences",+ "content": preference,+ },+ },+ "actual_replacements": {},+ }+ ]++ metrics = regrade_rows(rows)[0]["autonomous_metrics"]+ assert metrics["organization_action_success"]+ assert metrics["information_integrity"]+++def test_autonomous_report_exposes_only_two_primary_quality_metrics():+ case = build_cases()[0]+ target = "viking://user/default/memories/entities/projects/atlas.md"+ source = "viking://user/default/memories/entities/Projects/atlas.md"+ row = {+ "case_id": case.case_id,+ "protocol": "python",+ "repeat_index": 0,+ "actual_files": {+ target: {+ "memory_type": "entities",+ "content": "- [F01] 使用分阶段发布。\n- [F02] 有明确记录的回滚流程。\n"+ "- [F03] 由平台团队负责。\n- [F04] 提供健康检查接口。",+ }+ },+ "actual_replacements": {source: target},+ "calls": 1,+ "retries": 0,+ "total_tokens": 100,+ "duration_seconds": 1.0,+ "terminal_error": "",+ }++ report = summarize_autonomous(regrade_rows([row]))[case.case_id]+ assert set(report["summary"]["python"]) == {+ "runs",+ "organization_action_success_rate",+ "information_integrity_rate",+ }+ assert set(report["paired"]) == {+ "organization_action_success",+ "information_integrity",+ }+++def test_grader_accepts_exact_target_state():+ case = _case()+ grade = grade_result(case, {"travel": "[F01] A\n[F02] B"}, {"trip": "travel"})++ assert grade.organization_success+ assert grade.content_organization_success+ assert grade.file_tree_accuracy == 1.0+ assert grade.fact_recall == 1.0+ assert grade.placement_precision == 1.0+ assert grade.replacement_accuracy == 1.0+++def test_grader_accepts_equivalent_topic_names():+ case = OrganizationCase.from_dict(+ {+ "case_id": "split",+ "category": "split",+ "canonical_topics": ["food", "travel"],+ "initial_files": {"mixed": "[F01] A\n[F02] B"},+ "expected_files": {"food": ["F01"], "travel": ["F02"]},+ "expected_replacements": {},+ }+ )++ grade = grade_result(+ case,+ {"food_preferences": "[F01] A", "travel_preferences": "[F02] B"},+ )++ assert grade.organization_success+++def test_grader_rejects_duplicate_misplaced_and_missing_facts():+ case = _case()+ grade = grade_result(+ case,+ {"travel": "[F01] A\n[F01] A", "trip": "[F02] B"},+ {},+ )++ assert not grade.organization_success+ assert not grade.content_organization_success+ assert grade.duplicate_fact_count == 1+ assert grade.misplaced_fact_count == 1+ assert grade.replacement_accuracy == 0.0+++def test_grader_accepts_any_merge_survivor_with_correct_replacements():+ case = _case()++ grade = grade_result(case, {"trip": "[F01] A\n[F02] B"}, {"travel": "trip"})++ assert grade.organization_success+ assert grade.replacement_accuracy == 1.0+++def test_grader_rejects_changed_fact_text_and_empty_leftover_file():+ case = _case()++ grade = grade_result(+ case,+ {"travel": "[F01] changed\n[F02] B", "trip": ""},+ {"trip": "travel"},+ )++ assert not grade.organization_success+ assert grade.fact_recall == 0.5+ assert grade.altered_fact_count == 1+ assert grade.unexpected_file_count == 1+++def test_fact_lines_accepts_markdown_bullets_and_normalizes_whitespace():+ content = "- [F01] A stable fact. \n* [F02] Another."++ assert fact_lines(content) == [+ ("F01", "A stable fact."),+ ("F02", "Another."),+ ]+++def test_summary_and_paired_counts():+ rows = [+ {+ "case_id": "c1",+ "repeat_index": 0,+ "protocol": "python",+ "grade": {+ "content_organization_success": True,+ "organization_success": True,+ "file_tree_accuracy": 1.0,+ "fact_recall": 1.0,+ "placement_precision": 1.0,+ },+ "calls": 1,+ "retries": 0,+ "prompt_tokens": 80,+ "completion_tokens": 20,+ "total_tokens": 100,+ "duration_seconds": 1.0,+ "terminal_error": "",+ },+ {+ "case_id": "c1",+ "repeat_index": 0,+ "protocol": "json",+ "grade": {+ "content_organization_success": False,+ "organization_success": False,+ "file_tree_accuracy": 0.5,+ "fact_recall": 1.0,+ "placement_precision": 0.5,+ },+ "calls": 2,+ "retries": 1,+ "prompt_tokens": 120,+ "completion_tokens": 30,+ "total_tokens": 150,+ "duration_seconds": 2.0,+ "terminal_error": "failed",+ },+ ]++ assert paired_counts(rows) == {+ "both_success": 0,+ "python_only": 1,+ "json_only": 0,+ "both_fail": 0,+ }+ result = summarize(rows)+ assert result["python"]["organization_success_rate"] == 1.0+ assert result["json"]["organization_success_rate"] == 0.0+ assert result["python"]["content_organization_success_rate"] == 1.0+ assert result["python"]["mean_retries"] == 0+ assert result["json"]["mean_prompt_tokens"] == 120+ assert result["json"]["mean_completion_tokens"] == 30+++def test_exact_mcnemar_p_value():+ assert mcnemar_exact_p_value({"python_only": 0, "json_only": 0}) == 1.0+ assert mcnemar_exact_p_value({"python_only": 1, "json_only": 4}) == 0.375+++def test_grade_is_json_serializable():+ grade = grade_result(_case(), {"travel": "[F01] A\n[F02] B"}, {"trip": "travel"})+ json.dumps(grade.to_dict())+++def test_call_count_sums_model_usage():+ assert (+ _call_count(+ {+ "total_usage": {"call_count": 0},+ "usage_by_model": {+ "model-a": {"total_usage": {"call_count": 2}},+ "model-b": {"total_usage": {"call_count": 3}},+ },+ }+ )+ == 5+ )diff --git a/tests/session/memory/test_extraction_output_protocol.py b/tests/session/memory/test_extraction_output_protocol.pynew file mode 100644index 000000000..a00fac020--- /dev/null+++ b/tests/session/memory/test_extraction_output_protocol.py@@ -0,0 +1,1624 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0+"""Tests for JSON and restricted-Python memory extraction output protocols."""++import json+from types import SimpleNamespace+from unittest.mock import patch++import pytest++from openviking.session.memory.dataclass import MemoryField, MemoryFile, MemoryTypeSchema+from openviking.session.memory.extraction_output_protocol import (+ ExtractionOutputContext,+ create_extraction_output_protocol,+)+from openviking.session.memory.memory_isolation_handler import RoleScope+from openviking.session.memory.merge_op import FieldType, MergeOp+from openviking.session.memory.page_id_map import PageIdMap+from openviking.session.memory.schema_model_generator import SchemaModelGenerator+++def _preference_schema(*, operation_mode: str = "upsert") -> MemoryTypeSchema:+ return MemoryTypeSchema(+ memory_type="preferences",+ description="User preferences",+ directory="viking://user/{{ user_space }}/memories/preferences",+ filename_template="{{ topic }}.md",+ operation_mode=operation_mode,+ fields=[+ MemoryField(+ name="topic",+ field_type=FieldType.STRING,+ merge_op=MergeOp.IMMUTABLE,+ ),+ MemoryField(+ name="content",+ field_type=FieldType.STRING,+ merge_op=MergeOp.PATCH,+ ),+ MemoryField(+ name="score",+ field_type=FieldType.INT64,+ merge_op=MergeOp.SUM,+ ),+ ],+ )+++def _project_schema() -> MemoryTypeSchema:+ return MemoryTypeSchema(+ memory_type="projects",+ description="Projects",+ directory="viking://user/{{ user_space }}/memories/projects",+ filename_template="{{ name }}.md",+ fields=[+ MemoryField(+ name="name",+ field_type=FieldType.STRING,+ merge_op=MergeOp.IMMUTABLE,+ ),+ MemoryField(+ name="content",+ field_type=FieldType.STRING,+ merge_op=MergeOp.REPLACE,+ ),+ ],+ )+++def _profile_schema() -> MemoryTypeSchema:+ return MemoryTypeSchema(+ memory_type="profile",+ description="User profile",+ directory="viking://user/{{ user_space }}/memories",+ filename_template="profile.md",+ fields=[+ MemoryField(+ name="content",+ field_type=FieldType.STRING,+ merge_op=MergeOp.PATCH,+ )+ ],+ )+++def _context(+ schemas: list[MemoryTypeSchema],+ *,+ files: list[MemoryFile] | None = None,+ link_enabled: bool = False,+ role_scope: RoleScope | None = None,+ available_tools: tuple[str, ...] = ("read",),+) -> ExtractionOutputContext:+ config = SimpleNamespace(memory=SimpleNamespace(link_enabled=link_enabled))+ with patch("openviking_cli.utils.config.get_openviking_config", return_value=config):+ operations_model = SchemaModelGenerator(schemas).create_structured_operations_model(+ role_scope+ )+ page_id_map = PageIdMap()+ read_file_contents = {}+ for memory_file in files or []:+ read_file_contents[memory_file.uri] = memory_file+ page_id_map.get_page_id(memory_file.uri)+ return ExtractionOutputContext(+ operations_model=operations_model,+ schemas=tuple(schemas),+ page_id_map=page_id_map,+ read_file_contents=read_file_contents,+ link_enabled=link_enabled,+ role_scope=role_scope,+ available_tools=available_tools,+ )+++def _existing_preference(uri: str, topic: str, content: str, score: int = 0) -> MemoryFile:+ return MemoryFile(+ uri=uri,+ memory_type="preferences",+ content=content,+ extra_fields={+ "topic": topic,+ "score": score,+ "version": 7,+ "_uri": uri,+ },+ )+++def _bind(protocol, context: ExtractionOutputContext) -> str:+ protocol.render_contract(context)+ return protocol.render_new_bindings(context, source="test read")+++def test_json_protocol_preserves_stable_parser_and_empty_contract():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("json")++ operations, error = protocol.parse(+ '{"preferences": [], "delete_ids": [], "ignored": true}', context+ )++ assert error is None+ assert operations.model_dump() == {"preferences": [], "delete_ids": []}+ assert '"preferences": []' in protocol.render_final_instruction(context)+ assert '"delete_ids": []' in protocol.render_final_instruction(context)+++def test_python_contract_and_bindings_expose_only_selected_schema_fields():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim", 2)],+ )+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)+ bindings = protocol.render_new_bindings(context, source="search then read")++ assert "sdk.create_preferences" in contract+ assert "sdk.create_projects" not in contract+ assert "preferences_1 = sdk.existing" in bindings+ assert "topic='editor'" in bindings+ assert "content='Use Vim'" in bindings+ assert "version" not in bindings+ assert uri not in bindings+ assert protocol.render_new_bindings(context, source="duplicate read") == ""+++def test_python_contract_includes_link_rules_when_enabled():+ context = _context([_preference_schema()], link_enabled=True)+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)++ assert "## Link Rules" in contract+ assert "obj.link(target" in contract+ assert "match_text" in contract+ assert "obj_a.link(" in contract+ assert "assign the create/set call to a variable first" in contract++def test_python_contract_omits_link_rules_when_disabled():+ context = _context([_preference_schema()], link_enabled=False)+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)++ assert "## Link Rules" not in contract+ assert "obj.link(...) is unavailable" in contract+++def test_python_protocol_compiles_extracted_code_from_fence():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")+ compiled = []++ def record_compile(self, code):+ compiled.append(code)+ return context.operations_model(preferences=[], delete_ids=[])++ with patch(+ "openviking.session.memory.extraction_output_protocol.python_protocol._PythonProgramCompiler.compile",+ autospec=True,+ side_effect=record_compile,+ ):+ operations, error = protocol.parse("```python\nsdk.commit()\n```", context)++ assert error is None+ assert operations is not None+ # The fenced code (not the raw fence wrapper) is what gets compiled.+ assert compiled == ["sdk.commit()"]+++def test_json_protocol_preserves_tool_result_context_shape():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("json")+ result = {"memory_type": "preferences", "content": "1\tUse Vim"}++ messages = protocol.render_tool_result_messages(+ context,+ call_id="call-1",+ tool_name="read",+ params={"uri": "viking://user/alice/memories/preferences/editor.md"},+ result=result,+ source="tool call",+ )++ assert messages == [+ {+ "role": "user",+ "content": json.dumps(+ {+ "tool_call_name": "read",+ "args": {"uri": "viking://user/alice/memories/preferences/editor.md"},+ "result": result,+ },+ ensure_ascii=False,+ ),+ }+ ]+++def test_python_protocol_renders_search_result_as_read_tool_comment():+ uri_a = "viking://user/alice/memories/entities/person/tim.md"+ uri_b = "viking://user/alice/memories/entities/person/maria.md"+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ messages = protocol.render_tool_result_messages(+ context,+ call_id="call-1",+ tool_name="search",+ params={"query": "tim maria"},+ result=[{"uri": uri_a, "score": 0.9}, {"uri": uri_b, "score": 0.8}],+ source="tool call",+ )++ assert len(messages) == 1+ content = messages[0]["content"]+ assert content.startswith("# Search")+ assert "query='tim maria'" in content+ assert "read them with the read tool" in content+ assert f"# - {uri_a}" in content+ assert f"# - {uri_b}" in content+ # Search yields no content, so it must not fabricate an sdk.existing() binding.+ assert "sdk.existing(" not in content+ assert "search_results" not in content+ assert "0.9" not in content+++def test_python_protocol_renders_empty_search_result_as_comment():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ messages = protocol.render_tool_result_messages(+ context,+ call_id="call-1",+ tool_name="search",+ params={"query": "nobody"},+ result=[],+ source="tool call",+ )++ assert messages[0]["content"] == "# Search query='nobody' found no memory files."+++def test_python_protocol_search_comment_omits_read_tool_when_unavailable():+ uri = "viking://user/alice/memories/entities/person/tim.md"+ # eager_prefetch preloads everything and exposes no tools to the model.+ context = _context([_preference_schema()], available_tools=())+ protocol = create_extraction_output_protocol("python")++ messages = protocol.render_tool_result_messages(+ context,+ call_id="call-1",+ tool_name="search",+ params={"query": "tim"},+ result=[{"uri": uri, "score": 0.9}],+ source="prefetch",+ )++ content = messages[0]["content"]+ assert "read them with the read tool" not in content+ assert "there is no read tool" in content+ assert "treat anything not shown above as new" in content+ assert f"# - {uri}" in content+++def test_python_protocol_renders_read_result_directly_as_existing_binding():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nKeep plugins small", 2)],+ )+ protocol = create_extraction_output_protocol("python")+ protocol.render_contract(context)++ messages = protocol.render_tool_result_messages(+ context,+ call_id="call-1",+ tool_name="read",+ params={"uri": uri, "offset": 1, "limit": 1},+ result={+ "memory_type": "preferences",+ "topic": "editor",+ "score": 2,+ "content": "2\tKeep plugins small",+ "page_id": 1,+ "memory_maintenance_notice": {+ "maintenance_required": True,+ "guidance": "choose split or compact",+ },+ },+ source="tool call",+ )++ assert len(messages) == 1+ content = messages[0]["content"]+ assert content.startswith("# Existing memory loaded by tool call")+ assert "preferences_1 = sdk.existing(" in content+ assert "content='Keep plugins small'" in content+ assert "2\\tKeep plugins small" not in content+ assert "Use Vim" not in content+ assert "tool_call_name" not in content+ assert "page_id" not in content+ assert uri not in content+ assert "# Memory maintenance notice:" in content+ assert '"maintenance_required": true' in content+ assert "estimated_tokens" not in content+ assert "content_characters" not in content+ assert "choose split or compact" in content+++def test_python_protocol_converts_prefetch_tool_messages_without_duplicating_read_content():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim", 2)],+ )+ protocol = create_extraction_output_protocol("python")+ protocol.render_contract(context)+ prefetched = [+ {"role": "user", "content": "Conversation History"},+ {+ "role": "user",+ "content": json.dumps(+ {+ "tool_call_name": "search",+ "args": {"query": "editor"},+ "result": [{"uri": uri, "score": 0.9}],+ }+ ),+ },+ {+ "role": "user",+ "content": json.dumps(+ {+ "tool_call_name": "read",+ "args": {"uri": uri},+ "result": {+ "memory_type": "preferences",+ "topic": "editor",+ "score": 2,+ "content": "1\tUse Vim",+ },+ }+ ),+ },+ ]++ messages = protocol.render_prefetch_messages(prefetched, context)+ combined = "\n".join(message["content"] for message in messages)++ assert messages[0]["content"] == "Conversation History"+ # Search only yields URIs, so it renders as a read-tool comment, not a binding.+ assert "read them with the read tool" in combined+ assert f"# - {uri}" in combined+ assert "search_results = [" not in combined+ # The file that was actually read becomes a system-provided existing binding.+ assert "preferences_1 = sdk.existing(" in combined+ assert combined.count("Use Vim") == 1+ assert "tool_call_name" not in combined+ assert '"result"' not in combined+++def test_python_contract_uses_set_for_single_file_schema_and_create_for_collection():+ context = _context(+ [_profile_schema(), _preference_schema()],+ role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),+ )+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)++ assert "sdk.set_profile" in contract+ assert "- sdk.create_profile(*," not in contract+ assert (+ "profile is a SINGLETON per identity: sdk.create_profile() does not exist, and "+ "sdk.set_profile() must appear AT MOST ONCE for each identity"+ ) in contract+ assert (+ "Current identity peer_id='bob': exactly one "+ "sdk.set_profile(peer_id='bob', ...) call; combine every person and section"+ ) in contract+ assert "Memory type rules:" in contract+ assert "User profile" in contract+ assert "sdk.create_preferences" in contract+ assert "sdk.set_preferences" not in contract+ assert "canonical = sdk.create_<type>(...)" in contract+ assert "duplicate_1.delete(replacement=canonical)" in contract+ assert "Identity fields (primary key): peer_id." in contract+ assert "Identity fields (primary key): peer_id, topic." in contract+ assert "Current self identity: exactly one sdk.set_profile() call without peer_id" in contract+++def test_python_reserved_existing_retry_explains_new_replacement_binding():+ protocol = create_extraction_output_protocol("python")++ retry = protocol.render_format_retry(+ "Line 3: sdk.existing() is reserved for system-provided bindings"+ )++ assert "existing-object variable names already supplied by the system" in retry+ assert "canonical = sdk.create_<type>(...)" in retry+ assert "duplicate_1.delete(replacement=canonical)" in retry+++def test_python_string_literal_retry_pushes_triple_quotes():+ protocol = create_extraction_output_protocol("python")++ retry = protocol.render_format_retry(+ "Line 33: invalid syntax. Perhaps you forgot a comma?"+ )++ assert "offending line is shown above" in retry+ assert 'triple-quoted string ("""...""")' in retry+++def test_python_non_string_syntax_error_omits_quote_guidance():+ protocol = create_extraction_output_protocol("python")++ retry = protocol.render_format_retry("Line 3: unexpected indent")++ assert "offending line is shown above" not in retry+++def test_resolution_repair_matches_protocol_output_shape():+ issues = [+ {+ "memory_type": "events",+ "page_id": 100,+ "reason_code": "no_writable_target",+ "reason": "range out of bounds",+ "operation": {"event_name": "yoga_class_started", "ranges": "99"},+ }+ ]++ json_repair = create_extraction_output_protocol("json").render_resolution_repair(issues)+ assert "ONLY one JSON object" in json_repair+ assert "yoga_class_started" in json_repair++ python_repair = create_extraction_output_protocol("python").render_resolution_repair(issues)+ assert "sdk.create_events" in python_repair+ assert "Output only Python code." in python_repair+ assert "JSON object" not in python_repair+++def _kebab_schema() -> MemoryTypeSchema:+ return MemoryTypeSchema(+ memory_type="project-notes",+ description="Project notes",+ directory="viking://user/{{ user_space }}/memories/project-notes",+ filename_template="{{ project_name }}.md",+ fields=[+ MemoryField(+ name="project_name",+ field_type=FieldType.STRING,+ merge_op=MergeOp.IMMUTABLE,+ ),+ MemoryField(+ name="note-body",+ field_type=FieldType.STRING,+ merge_op=MergeOp.PATCH,+ ),+ ],+ )+++def test_python_contract_aliases_non_identifier_schema_names():+ context = _context([_kebab_schema()])+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)++ # Method/parameter names are folded to valid identifiers on the DSL surface.+ assert "sdk.create_project_notes(" in contract+ assert "note_body" in contract+ assert "sdk.create_project-notes" not in contract+++def test_python_compiles_aliased_names_back_to_real_schema():+ context = _context([_kebab_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ """+sdk.create_project_notes(+ project_name="atlas",+ note_body=\"\"\"Kickoff on 2023-06-09.\"\"\",+)+sdk.commit()+""",+ context,+ )++ assert error is None, error+ dumped = operations.model_dump()+ # Real schema name and real field name are preserved in the operations.+ assert dumped["project-notes"] == [+ {"page_id": 100, "project_name": "atlas", "note-body": "Kickoff on 2023-06-09."}+ ]+++def test_python_edits_aliased_field_on_existing_object():+ existing = MemoryFile(+ uri="viking://user/alice/memories/project-notes/atlas.md",+ memory_type="project-notes",+ content="",+ extra_fields={+ "project_name": "atlas",+ "note-body": "Kickoff on 2023-06-09.",+ "version": 3,+ "_uri": "x",+ },+ )+ context = _context([_kebab_schema()], files=[existing])+ protocol = create_extraction_output_protocol("python")++ bindings = _bind(protocol, context)+ # Existing-object binding exposes the field under its identifier alias.+ assert "note_body=" in bindings++ var = bindings.split(" = ", 1)[0].strip().splitlines()[-1]+ operations, error = protocol.parse(+ f"""+{var}.note_body.edit(search=\"\"\"Kickoff on 2023-06-09.\"\"\", replace=\"\"\"Kickoff moved to 2023-07-01.\"\"\")+sdk.commit()+""",+ context,+ )++ assert error is None, error+ edited = operations.model_dump()["project-notes"]+ assert edited and edited[0]["page_id"] == 1+++def _schema_named(memory_type: str, field_names: list[str]) -> MemoryTypeSchema:+ return MemoryTypeSchema(+ memory_type=memory_type,+ description=memory_type,+ directory=f"viking://user/{{{{ user_space }}}}/memories/{memory_type}",+ filename_template="{{ name }}.md",+ fields=[+ MemoryField(name=name, field_type=FieldType.STRING, merge_op=MergeOp.PATCH)+ for name in field_names+ ],+ )+++def test_python_rejects_colliding_memory_type_aliases():+ # 'project-notes' and 'project_notes' both fold to the same DSL alias.+ context = _context(+ [_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]+ )+ protocol = create_extraction_output_protocol("python")++ with pytest.raises(ValueError, match="same Python DSL alias"):+ protocol.render_contract(context)+++def test_python_rejects_colliding_field_aliases():+ # 'note-body' and 'note_body' collide within one schema.+ context = _context([_schema_named("notes", ["note-body", "note_body"])])+ protocol = create_extraction_output_protocol("python")++ with pytest.raises(ValueError, match="same Python DSL alias"):+ protocol.render_contract(context)+++def test_python_parse_rejects_colliding_aliases_without_render():+ # Collision must be caught even when parse() runs without render_contract().+ context = _context(+ [_schema_named("project-notes", ["name"]), _schema_named("project_notes", ["name"])]+ )+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse("sdk.commit()", context)++ assert operations is None+ assert "same Python DSL alias" in error+++def test_python_syntax_error_includes_offending_source_line():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ # A double-quoted summary that itself embeds a double quote ends the string+ # early; the compiler should surface the real offending line, not just the+ # misleading "forgot a comma" hint.+ _operations, error = protocol.parse(+ 'sdk.create_preferences(topic="x", content="he saw "Little Women" today", score=1)',+ context,+ )++ assert error is not None+ assert "invalid Python syntax" in error+ assert 'Little Women' in error+ assert "^" in error+++def test_memory_schema_identity_fields_follow_scope_and_uri_template():+ entities = MemoryTypeSchema(+ memory_type="entities",+ directory="viking://user/{{ user_space }}/memories/entities",+ filename_template="{{ category|lower }}/{{ name|lower }}.md",+ fields=[+ MemoryField(name="category", field_type=FieldType.STRING),+ MemoryField(name="name", field_type=FieldType.STRING),+ MemoryField(name="content", field_type=FieldType.STRING),+ ],+ )+ preferences = MemoryTypeSchema(+ memory_type="preferences",+ directory="viking://user/{{ user_space }}/memories/preferences",+ filename_template="{{ user }}/{{ topic }}.md",+ fields=[+ MemoryField(name="user", field_type=FieldType.STRING),+ MemoryField(name="topic", field_type=FieldType.STRING),+ MemoryField(name="content", field_type=FieldType.STRING),+ ],+ )++ assert _profile_schema().identity_fields() == ("peer_id",)+ assert preferences.identity_fields() == ("peer_id", "user", "topic")+ assert entities.identity_fields() == ("peer_id", "category", "name")+++def test_memory_schema_identity_fields_ignore_jinja_token_collisions():+ # `year` and `context` appear only inside a filter/function/attribute+ # expression, never as referenced variables, so they must not be treated+ # as identity fields. Only `ranges` and `event_name` are real references.+ events = MemoryTypeSchema(+ memory_type="events",+ directory="viking://user/{{ user_space }}/memories/events",+ filename_template="{{ extract_context.get_year(ranges) }}/{{ event_name }}.md",+ fields=[+ MemoryField(name="event_name", field_type=FieldType.STRING),+ MemoryField(name="ranges", field_type=FieldType.STRING),+ MemoryField(name="year", field_type=FieldType.STRING),+ MemoryField(name="context", field_type=FieldType.STRING),+ MemoryField(name="content", field_type=FieldType.STRING),+ ],+ )++ assert events.identity_fields() == ("peer_id", "event_name", "ranges")+++def test_python_set_single_file_memory_compiles_to_same_operations_as_json():+ context = _context([_profile_schema()])+ python_protocol = create_extraction_output_protocol("python")+ json_protocol = create_extraction_output_protocol("json")++ python_operations, python_error = python_protocol.parse(+ "sdk.set_profile(content='Engineer')\nsdk.commit()",+ context,+ )+ json_operations, json_error = json_protocol.parse(+ '{"profile":[{"page_id":100,"content":"Engineer"}],"delete_ids":[]}',+ context,+ )++ assert python_error is None+ assert json_error is None+ assert python_operations.model_dump() == json_operations.model_dump()+++def test_python_commit_is_optional():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ # A program without a trailing sdk.commit() is accepted as-is.+ without_commit, error = protocol.parse("sdk.set_profile(content='Engineer')", context)+ assert error is None+ assert without_commit.model_dump()["profile"][0]["content"] == "Engineer"++ # An empty program means "no changes".+ empty_operations, empty_error = protocol.parse("", context)+ assert empty_error is None+ assert empty_operations.model_dump() == {"profile": [], "delete_ids": []}+++def test_python_rejects_create_for_single_file_and_set_for_collection():+ context = _context([_profile_schema(), _preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ "sdk.create_profile(content='Engineer')\nsdk.commit()", context+ )+ assert operations is None+ assert "use sdk.set_profile()" in error++ operations, error = protocol.parse(+ "sdk.set_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",+ context,+ )+ assert operations is None+ assert "use sdk.create_preferences()" in error+++def test_python_rejects_repeated_single_file_set_for_same_peer_scope():+ context = _context(+ [_profile_schema()],+ role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob"]),+ )+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ """+sdk.set_profile(peer_id="bob", content="Engineer")+sdk.set_profile(peer_id="bob", content="Musician")+sdk.commit()+""",+ context,+ )++ assert operations is None+ assert "duplicate profile identity (peer_id='bob')" in error+ assert "may be called only once for peer 'bob'" in error+ assert "combine all people and content sections" in error+++def test_python_rejects_repeated_single_file_set_for_self_scope():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ """+sdk.set_profile(content="Engineer")+sdk.set_profile(content="Musician")+sdk.commit()+""",+ context,+ )++ assert operations is None+ assert "may be called only once for self" in error+++def test_python_allows_one_single_file_set_per_peer_scope():+ context = _context(+ [_profile_schema()],+ role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),+ )+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ """+sdk.set_profile(peer_id="bob", content="Engineer")+sdk.set_profile(peer_id="carol", content="Musician")+sdk.commit()+""",+ context,+ )++ assert error is None+ assert operations.model_dump()["profile"] == [+ {"peer_id": "bob", "page_id": 100, "content": "Engineer"},+ {"peer_id": "carol", "page_id": 101, "content": "Musician"},+ ]+++def test_python_create_compiles_to_same_operations_as_json():+ context = _context([_preference_schema()])+ python_protocol = create_extraction_output_protocol("python")+ json_protocol = create_extraction_output_protocol("json")++ python_operations, python_error = python_protocol.parse(+ """+topic = "editor".upper().lower()+score = len([1, 2]) + 1+sdk.create_preferences(+ topic=topic,+ content=f"Use {topic}",+ score=score,+ ignored=unknown_name_that_must_not_be_evaluated,+)+sdk.commit()+""",+ context,+ )+ json_operations, json_error = json_protocol.parse(+ """+{+ "preferences": [+ {"page_id": 100, "topic": "editor", "content": "Use editor", "score": 3}+ ],+ "delete_ids": []+}+""",+ context,+ )++ assert python_error is None+ assert json_error is None+ assert python_operations.model_dump() == json_operations.model_dump()+++def test_python_create_avoids_existing_page_id_collisions():+ context = _context([_preference_schema()])+ context.page_id_map.register_new_page_id("viking://existing/100.md", 100)+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ "sdk.create_preferences(topic='editor', content='Use Vim', score=1)\nsdk.commit()",+ context,+ )++ assert error is None+ assert operations.model_dump()["preferences"][0]["page_id"] == 101+++def test_python_protocol_includes_dynamic_peer_id_field():+ schema = _preference_schema()+ context = _context(+ [schema],+ role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),+ )+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)+ operations, error = protocol.parse(+ "sdk.create_preferences(peer_id='bob', topic='editor', content='Use Vim', score=1)\nsdk.commit()",+ context,+ )++ assert "peer_id: str" in contract+ assert "Available peer_id values in this session: bob, carol" in contract+ assert error is None+ assert operations.model_dump()["preferences"][0]["peer_id"] == "bob"+++def test_python_existing_binding_exposes_but_does_not_update_dynamic_peer_id():+ schema = _preference_schema()+ memory_file = _existing_preference(+ "viking://user/alice/peers/bob/memories/preferences/editor.md",+ "editor",+ "Use Vim",+ )+ memory_file.extra_fields["peer_id"] = "bob"+ context = _context(+ [schema],+ files=[memory_file],+ role_scope=RoleScope(user_ids=["alice"], peer_ids=["bob", "carol"]),+ )+ protocol = create_extraction_output_protocol("python")++ bindings = _bind(protocol, context)+ operations, error = protocol.parse(+ "preferences_1.update(peer_id='carol')\npreferences_1.content.update('Use Emacs')\nsdk.commit()",+ context,+ )++ assert "peer_id='bob'" in bindings+ assert error is None+ item = operations.model_dump()["preferences"][0]+ assert item["content"] == "Use Emacs"+ assert item["peer_id"] is None+++def test_python_existing_updates_emit_patch_blocks_and_accumulate_sum_delta():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nDark theme\nTabs", 10)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """+preferences_1.content.edit(search="Use Vim", replace="Use Neovim")+preferences_1.update(score=2)+preferences_1.content.drop(text="Tabs")+preferences_1.update(+ topic="ignored immutable change",+ score=3,+ unknown_field="ignored",+ another_unknown=unknown_name_that_must_not_be_evaluated,+)+sdk.commit()+""",+ context,+ )++ assert error is None+ # edit/drop are emitted as StrPatch blocks (applied later by the shared path),+ # while SUM deltas still accumulate at compile time.+ item = operations.model_dump()["preferences"][0]+ assert item["page_id"] == 1+ assert item["topic"] == "editor"+ assert item["score"] == 5+ assert item["content"]["blocks"] == [+ {"search": "Use Vim", "replace": "Use Neovim"},+ {"delete": "Tabs"},+ ]+++def test_python_patch_preserves_unescaped_markers_in_blocks():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "<<<<<<< literal", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ r"""+preferences_1.content.edit(search=r"\<<<<<<< literal", replace="plain")+sdk.commit()+""",+ context,+ )++ assert error is None+ blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]+ assert blocks == [{"search": r"\<<<<<<< literal", "replace": "plain"}]+++def test_python_field_edit_chain_emits_blocks_in_order():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """+preferences_1.content.edit(search="Use Vim", replace="Use Neovim").drop(text="Dark theme")+sdk.commit()+""",+ context,+ )++ assert error is None+ blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]+ assert blocks == [+ {"search": "Use Vim", "replace": "Use Neovim"},+ {"delete": "Dark theme"},+ ]+++def test_python_field_update_replaces_whole_field():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nDark theme", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ '''+preferences_1.content.update("""# Editor+- Use Neovim""")+sdk.commit()+''',+ context,+ )++ assert error is None+ assert operations.model_dump()["preferences"][0]["content"] == "# Editor\n- Use Neovim"+++def test_python_field_edit_emits_block_even_when_search_absent():+ # Matching/rejection is now the shared validation path's job (json parity),+ # so parse() succeeds and just emits the block; a bad snippet no longer fails+ # the whole program at compile time.+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """+preferences_1.content.edit(search="Prefers Neovim", replace="Prefers Emacs")+sdk.commit()+""",+ context,+ )++ assert error is None+ blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]+ assert blocks == [{"search": "Prefers Neovim", "replace": "Prefers Emacs"}]+++def test_python_field_edit_rejects_literal_field_placeholder():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ "preferences_1.field.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",+ context,+ )++ assert operations is None+ assert "memory field 'field' is unavailable" in error+ assert "not the literal word 'field'" in error+++def test_python_field_edit_emits_block_regardless_of_uniqueness():+ # Uniqueness enforcement now lives in the shared validation path, so parse()+ # just emits the block; matching (and any non-unique rejection) happens later.+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nUse Vim", 0)],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ "preferences_1.content.edit(search='Use Vim', replace='Use Neovim')\nsdk.commit()",+ context,+ )++ assert error is None+ blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]+ assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]+++ "operation",+ [+ "preferences_1.content.edit(search='Use Vim', replace='Use Neovim')",+ "preferences_1.content.drop(text='Dark theme')",+ ],+)+def test_python_field_edit_and_drop_are_standalone_statements(operation: str):+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim\nDark theme")],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(f"x = {operation}\nsdk.commit()", context)++ assert operations is None+ assert "must be standalone statements" in error+++def test_python_delete_replacement_and_links_compile_with_page_id_remapping():+ duplicate = _existing_preference(+ "viking://user/alice/memories/preferences/duplicate.md",+ "duplicate",+ "duplicate content",+ )+ project = MemoryFile(+ uri="viking://user/alice/memories/projects/openviking.md",+ memory_type="projects",+ content="Memory platform",+ extra_fields={"name": "openviking"},+ )+ context = _context(+ [_preference_schema(), _project_schema()],+ files=[duplicate, project],+ link_enabled=True,+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """+canonical = sdk.create_preferences(topic="editor", content="Use Neovim", score=1)+preferences_1.link(projects_1, match_text="editor")+preferences_1.delete(replacement=canonical)+sdk.commit()+""",+ context,+ )++ assert error is None+ payload = operations.model_dump()+ assert payload["preferences"] == [+ {"page_id": 100, "topic": "editor", "content": "Use Neovim", "score": 1}+ ]+ assert payload["delete_ids"] == [{"delete_page_id": 1, "replacement_page_id": 100}]+ assert payload["links"] == [+ {+ "f": 100,+ "t": 2,+ "link_type": "related_to",+ "weight": 0.5,+ "match_text": "editor",+ "description": "",+ }+ ]+++def test_python_update_after_delete_restores_object_and_delete_after_update_discards_update():+ first = _existing_preference(+ "viking://user/alice/memories/preferences/first.md", "first", "old one"+ )+ second = _existing_preference(+ "viking://user/alice/memories/preferences/second.md", "second", "old two"+ )+ context = _context([_preference_schema()], files=[first, second])+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """+preferences_1.delete()+preferences_1.update(content="restored")+preferences_2.update(content="discarded")+preferences_2.delete()+preferences_1.link(preferences_2) if False else None+sdk.commit()+""",+ context,+ )++ assert error is not None+ assert operations is None++ operations, error = protocol.parse(+ """+preferences_1.delete()+preferences_1.update(content="restored")+preferences_2.update(content="discarded")+preferences_2.delete()+sdk.commit()+""",+ context,+ )+ assert error is None+ payload = operations.model_dump()+ assert payload["preferences"] == [+ {"page_id": 1, "topic": "first", "content": "restored", "score": None}+ ]+ assert payload["delete_ids"] == [{"delete_page_id": 2, "replacement_page_id": None}]+++ ("program", "message"),+ [+ ("sdk.commit()\nsdk.commit()", "final statement"),+ ("for item in []:\n pass\nsdk.commit()", "only assignments"),+ ("sdk.existing(memory_type='preferences')\nsdk.commit()", "reserved"),+ ("sdk.create_preferences(topic='x', content='y')\nsdk.commit()", "missing: score"),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\nx.delete()\nsdk.commit()",+ "cannot be deleted",+ ),+ (+ "obj = sdk.create_preferences(topic='x', content='y', score=1)\n"+ "obj.content.edit(search='y', replace='z')\nsdk.commit()",+ "can only patch an existing memory",+ ),+ (+ "sdk.replace(search='x', replacement='y')\nsdk.commit()",+ "unknown SDK method sdk.replace()",+ ),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\n"+ "x.content.update('a', 'b')\nsdk.commit()",+ "exactly one positional argument",+ ),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\nstr(x)\nsdk.commit()",+ "memory objects cannot be converted",+ ),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\nitems = [x]\nsdk.commit()",+ "memory objects cannot be stored",+ ),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\ntext = f'{x}'\nsdk.commit()",+ "memory objects cannot be formatted",+ ),+ (+ "x = sdk.create_preferences(topic='x', content='y', score=1)\nx.update(content=x)\nsdk.commit()",+ "memory objects cannot be used as business field values",+ ),+ (+ "sdk.create_preferences(topic='x', content='y', score=1).update(content='z')\nsdk.commit()",+ "assign a new memory object",+ ),+ ("import os\nsdk.commit()", "only assignments"),+ ("sdk.commit()\nprint('after')", "final statement"),+ ],+)+def test_python_rejects_invalid_or_unsafe_programs(program: str, message: str):+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(program, context)++ assert operations is None+ assert message in error+++def test_python_rejects_delete_for_add_only_schema():+ memory_file = _existing_preference(+ "viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"+ )+ context = _context([_preference_schema(operation_mode="add_only")], files=[memory_file])+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)++ assert operations is None+ assert "delete() is unavailable" in error+++def test_python_rejects_add_only_delete_when_another_schema_enables_deletes():+ memory_file = _existing_preference(+ "viking://user/alice/memories/preferences/editor.md", "editor", "Use Vim"+ )+ context = _context(+ [_preference_schema(operation_mode="add_only"), _project_schema()],+ files=[memory_file],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse("preferences_1.delete()\nsdk.commit()", context)++ assert operations is None+ assert "delete() is unavailable" in error+++def test_python_aliases_non_identifier_memory_type_instead_of_raising():+ schema = _preference_schema()+ schema.memory_type = "user-preferences"+ context = _context([schema])+ protocol = create_extraction_output_protocol("python")++ contract = protocol.render_contract(context)+ assert "sdk.set_user_preferences(" in contract or "sdk.create_user_preferences(" in contract+ assert "user-preferences" not in contract.split("Memory type rules")[0]+++def test_python_accepts_one_fence_with_surrounding_text():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse("```python\nsdk.commit()\n```", context)+ assert error is None+ assert operations.model_dump() == {"preferences": [], "delete_ids": []}++ operations, error = protocol.parse("Explanation\n```python\nsdk.commit()\n```", context)+ assert error is None+ assert operations.model_dump() == {"preferences": [], "delete_ids": []}+++def test_python_accepts_trace_style_explanation_around_program():+ context = _context(+ [_preference_schema()],+ files=[+ _existing_preference(+ "viking://user/alice/memories/preferences/editor.md",+ "editor",+ "Use Vim",+ )+ ],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(+ """Update the existing preference.+```python+preferences_1.content.edit(search="Use Vim", replace="Use Neovim")+sdk.commit()+```+The program above applies the requested update.""",+ context,+ )++ assert error is None+ blocks = operations.model_dump()["preferences"][0]["content"]["blocks"]+ assert blocks == [{"search": "Use Vim", "replace": "Use Neovim"}]+++ ("call", "error_fragment"),+ [+ ("sdk.read('viking://user/alice/memories/preferences/editor.md')", "sdk.read()"),+ ("read('viking://user/alice/memories/preferences/editor.md')", "function 'read'"),+ ("sdk.search('editor')", "sdk.search()"),+ ("search('editor')", "function 'search'"),+ ],+)+def test_python_read_search_errors_keep_native_tools_available_for_retry(+ call: str, error_fragment: str+):+ protocol = create_extraction_output_protocol("python")+ context = _context([_preference_schema()])++ operations, error = protocol.parse(+ f"item = {call}\nsdk.commit()",+ context,+ )++ assert operations is None+ assert error_fragment in error+ assert protocol.keep_tools_enabled_after_parse_error(error)+ retry = protocol.render_format_retry(error)+ assert "native search/read tool" in retry+ assert "Do not emit sdk.search(), sdk.read()" in retry+++def test_python_sdk_read_error_takes_priority_over_reassigning_existing_binding():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim")],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse(f"preferences_1 = sdk.read({uri!r})\nsdk.commit()", context)++ assert operations is None+ assert "unknown SDK method sdk.read()" in error+ assert protocol.keep_tools_enabled_after_parse_error(error)+++def test_python_object_read_error_keeps_native_tools_available_for_retry():+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "Use Vim")],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ operations, error = protocol.parse("preferences_1.read()\nsdk.commit()", context)++ assert operations is None+ assert "unknown memory method read()" in error+ assert protocol.keep_tools_enabled_after_parse_error(error)+++ "program",+ [+ "```python\nsdk.commit()\n```\n```python\nsdk.commit()\n```",+ "Explanation\n```python\nsdk.commit()\n```\n```text\nextra\n```",+ ],+)+def test_python_rejects_multiple_fences(program: str):+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(program, context)+ assert operations is None+ assert "only one complete" in error+++ "program",+ [+ "```python\nsdk.commit()```",+ "```python\nsdk.commit()",+ "Explanation\n```python\nsdk.commit()",+ ],+)+def test_python_accepts_single_recoverable_fence_variants(program: str):+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(program, context)++ assert error is None+ assert operations.model_dump() == {"preferences": [], "delete_ids": []}+++def test_python_unclosed_fence_still_rejects_truncated_python():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse("```python\npreferences_1.update(", context)++ assert operations is None+ assert "invalid Python syntax" in error+++def test_python_rejects_bare_markdown_with_actionable_error():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ "# Caroline\n- Transgender woman (as of 2023-06-09)", context+ )++ assert operations is None+ assert "bare Markdown, not a Python SDK program" in error+ assert "leading zeros" not in error+ retry = protocol.render_format_retry(error)+ assert "Markdown memory content inside quoted SDK arguments" in retry+++def test_python_accepts_update_only_program_with_markdown_content():+ # A valid program that only uses obj.update() (no literal "sdk." token) and+ # embeds Markdown bullets in a triple-quoted string must not be mistaken for+ # bare Markdown just because a comment starts with "# " and bullets appear.+ uri = "viking://user/alice/memories/preferences/editor.md"+ context = _context(+ [_preference_schema()],+ files=[_existing_preference(uri, "editor", "# Editor\n- Use Vim")],+ )+ protocol = create_extraction_output_protocol("python")+ _bind(protocol, context)++ program = (+ "# Merge updates to the editor preference\n"+ 'preferences_1.update(content="""# Editor\n'+ "A friend of Dave's who is involved in music.\n"+ "## Key Facts\n"+ "- Enjoys Japanese culture (as of 2023-10-19)\n"+ "- Relaxes by taking long walks\n"+ '""")'+ )++ operations, error = protocol.parse(program, context)++ assert error is None+ assert "# Editor" in operations.model_dump()["preferences"][0]["content"]+++def test_python_rejects_huge_string_multiplication_before_allocation():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ 'sdk.set_profile(content="x" * 1_000_000_000)\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "size limit" in error+++def test_python_rejects_huge_string_multiplication_reversed_operands():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ 'sdk.set_profile(content=1_000_000_000 * "x")\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "size limit" in error+++def test_python_allows_small_string_repetition():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ "sdk.set_profile(content='ab' * 3)\nsdk.commit()",+ context,+ )++ assert error is None+ assert operations.model_dump()["profile"][0]["content"] == "ababab"+++def test_python_rejects_multiplication_between_two_non_literals():+ context = _context([_preference_schema()])+ protocol = create_extraction_output_protocol("python")++ # Multiplying a non-literal local value by a non-literal local value has+ # no bounded literal to repeat and must not be evaluated.+ operations, error = protocol.parse(+ "a = 'ab'\nn = 3\nsdk.create_preferences(topic='x', score=1, content=a * n)\nsdk.commit()",+ context,+ )++ assert operations is None+ assert "multiplication is only supported" in error+++def test_python_rejects_numeric_multiplication():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ # Number * number cannot repeat a literal and is useless for memory content.+ operations, error = protocol.parse(+ "sdk.set_profile(content=str(2 * 3))\nsdk.commit()",+ context,+ )++ assert operations is None+ assert "multiplication is only supported" in error+++def test_python_rejects_huge_join_before_allocation():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ 'sdk.set_profile(content="".join(["xxxxxxxxxx"] * 200_000))\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "size limit" in error+++def test_python_rejects_huge_replace_before_allocation():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ # 'x' occurs 1000 times; replacing each with a 10000-char string would+ # inflate the result to ~10MB. The projected-size check must reject it+ # before str.replace builds the string.+ operations, error = protocol.parse(+ 'sdk.set_profile(content=("x" * 1000).replace("x", "y" * 10000))\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "size limit" in error+++def test_python_allows_small_replace():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ 'sdk.set_profile(content="a-b-c".replace("-", " "))\nsdk.commit()',+ context,+ )++ assert error is None+ assert operations.model_dump()["profile"][0]["content"] == "a b c"+++def test_python_rejects_fstring_width_format_spec():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ # A width format spec turns a small integer literal into a huge padded string+ # with no repeat operator; format specs are disallowed.+ operations, error = protocol.parse(+ 'sdk.set_profile(content=f"{\'x\':>1000001}")\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "format spec" in error+++def test_python_allows_plain_fstring():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ operations, error = protocol.parse(+ 'name = "Ada"\nsdk.set_profile(content=f"# {name}")\nsdk.commit()',+ context,+ )++ assert error is None+ assert operations.model_dump()["profile"][0]["content"] == "# Ada"+++def test_python_rejects_string_percent_formatting():+ context = _context([_profile_schema()])+ protocol = create_extraction_output_protocol("python")++ # "%1000001s" % "x" pads to ~1M chars via a width field, no repeat operator.+ operations, error = protocol.parse(+ 'sdk.set_profile(content="%1000001s" % "x")\nsdk.commit()',+ context,+ )++ assert operations is None+ assert "%-formatting is not allowed" in errordiff --git a/tests/session/memory/test_memory_react.py b/tests/session/memory/test_memory_react.pyindex 2c24785a5..daa055fa6 100644--- a/tests/session/memory/test_memory_react.py+++ b/tests/session/memory/test_memory_react.py@@ -4,7 +4,8 @@Tests for memory ExtractLoop orchestrator."""-from unittest.mock import AsyncMock, MagicMock+from types import SimpleNamespace+from unittest.mock import AsyncMock, MagicMock, patchimport pytestfrom pydantic import BaseModel, Field@@ -20,6 +21,7 @@ from openviking.session.memory.extract_loop import ()from openviking.session.memory.memory_isolation_handler import MemoryIsolationHandlerfrom openviking.session.memory.merge_op import SearchReplaceBlock, StrPatch+from openviking.session.memory.page_id_map import PageIdMapfrom openviking.session.memory.schema_model_generator import SchemaModelGenerator@@ -301,8 +303,15 @@ class TestExtractLoopFinalJsonRetry:extract_loop._check_unread_existing_files = AsyncMock(return_value={})extract_loop._validate_patch_operations = AsyncMock(return_value=[])extract_loop.finalize_operations = AsyncMock()+ config = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="json")+ )- await extract_loop.run()+ with patch(+ "openviking.session.memory.extract_loop.get_openviking_config",+ return_value=config,+ ):+ await extract_loop.run()parsed_operations = extract_loop.resolve_operations.await_args.args[0]assert len(parsed_operations.delete_ids) == 1@@ -365,20 +374,6 @@ class TestExtractLoopFinalJsonRetry:# )# assert "decision_reasoning" not in merge_fields- def test_final_instruction_includes_schema_aware_empty_json(self):- extract_loop = object.__new__(ExtractLoop)- extract_loop._expected_fields = ["preferences", "tools"]- # extract_loop._expected_fields = ["preferences", "tools", "decision_reasoning"]-- instruction = extract_loop._build_final_operations_instruction()-- assert "ONLY a valid JSON object" in instruction- assert '"delete_ids": []' in instruction- assert '"preferences": []' in instruction- assert '"tools": []' in instruction- assert '"decision_reasoning": []' not in instruction- # assert '"decision_reasoning": []' in instruction-@pytest.mark.asyncioasync def test_patch_validation_uses_plain_and_sequential_content(self):target_uri = "viking://user/default/memories/profile.md"@@ -475,8 +470,15 @@ class TestExtractLoopFinalJsonRetry:context_provider=FakeContextProvider(),max_iterations=1,)+ config = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="json")+ )- result, _ = await extract_loop.run()+ with patch(+ "openviking.session.memory.extract_loop.get_openviking_config",+ return_value=config,+ ):+ result, _ = await extract_loop.run()assert result.errorsassert "Final response could not be parsed" in result.errors[0]@@ -503,3 +505,256 @@ class TestExtractLoopFinalJsonRetry:assert "only if every substantive fact is in scope" in initial_system_promptassert "otherwise MUST use DELETE blocks" in initial_system_promptassert "not inferring scope from the file name/topic" in initial_system_prompt++ @pytest.mark.asyncio+ async def test_python_protocol_retries_then_degrades_on_invalid_program(self):+ class FakeVLM:+ model = "test-model"++ def __init__(self):+ self.seen_messages = []++ async def get_completion_async(self, **kwargs):+ self.seen_messages.append(list(kwargs["messages"]))+ return "this is not a valid SDK program"++ class FakeContextProvider:+ read_file_contents = {}++ def get_memory_schemas(self, ctx):+ return [+ MemoryTypeSchema(+ memory_type="preferences",+ description="Preferences",+ directory="viking://user/{user_space}/memories/preferences",+ filename_template="{topic}.md",+ fields=[],+ )+ ]++ def get_tools(self):+ return []++ def get_extract_context(self):+ return SimpleNamespace(page_id_map=PageIdMap())++ def get_output_language(self):+ return "en"++ def instruction(self):+ return "Extract memory operations and output ONLY a JSON object (no extra text before or after)."++ async def prefetch(self):+ return []++ vlm = FakeVLM()+ extract_loop = ExtractLoop(+ vlm=vlm,+ viking_fs=MagicMock(),+ context_provider=FakeContextProvider(),+ max_iterations=1,+ )+ config = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="python")+ )++ with (+ patch(+ "openviking.session.memory.extract_loop.get_openviking_config",+ return_value=config,+ ),+ patch(+ "openviking_cli.utils.config.get_openviking_config",+ return_value=config,+ ),+ patch("openviking.session.memory.extract_loop.tracer.error") as tracer_error,+ patch("openviking.session.memory.extract_loop.logger.warning") as logger_warning,+ ):+ extract_loop._check_unread_existing_files = AsyncMock(return_value={})+ extract_loop._validate_patch_operations = AsyncMock(return_value=[])+ extract_loop.finalize_operations = AsyncMock()++ result, _ = await extract_loop.run()++ assert result.upsert_operations == []+ assert result.delete_file_contents == []+ assert result.errors+ assert "Final response could not be parsed" in result.errors[0]++ assert len(vlm.seen_messages) == 2+ system_prompt = vlm.seen_messages[0][0]["content"]+ assert "restricted Python memory SDK" in system_prompt+ assert "output ONLY a JSON object" not in system_prompt+ assert any(+ "not a valid restricted Python memory SDK program" in message.get("content", "")+ for message in vlm.seen_messages[-1]+ )+ assert tracer_error.call_count == 1+ assert logger_warning.call_count == 0++ @pytest.mark.asyncio+ async def test_python_protocol_parse_retry_success_does_not_log_error(self):+ class FakeVLM:+ model = "test-model"++ def __init__(self):+ self.responses = iter(+ ["sdk.create_profile(content='Engineer')\nsdk.commit()", "sdk.commit()"]+ )++ async def get_completion_async(self, **kwargs):+ del kwargs+ return next(self.responses)++ class FakeContextProvider:+ read_file_contents = {}++ def get_memory_schemas(self, ctx):+ del ctx+ return [+ MemoryTypeSchema(+ memory_type="profile",+ description="Profile",+ directory="viking://user/{user_space}/memories",+ filename_template="profile.md",+ fields=[],+ )+ ]++ def get_tools(self):+ return []++ def get_extract_context(self):+ return SimpleNamespace(page_id_map=PageIdMap())++ def get_output_language(self):+ return "en"++ def instruction(self):+ return "Extract memory operations."++ async def prefetch(self):+ return []++ config = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="python")+ )+ extract_loop = ExtractLoop(+ vlm=FakeVLM(),+ viking_fs=MagicMock(),+ context_provider=FakeContextProvider(),+ max_iterations=1,+ )+ empty_operations = ResolvedOperations(+ upsert_operations=[], delete_file_contents=[], errors=[]+ )+ extract_loop.resolve_operations = AsyncMock(return_value=(empty_operations, []))+ extract_loop._check_unread_existing_files = AsyncMock(return_value={})++ with (+ patch(+ "openviking.session.memory.extract_loop.get_openviking_config",+ return_value=config,+ ),+ patch(+ "openviking_cli.utils.config.get_openviking_config",+ return_value=config,+ ),+ patch("openviking.session.memory.extract_loop.tracer.error") as tracer_error,+ patch("openviking.session.memory.extract_loop.logger.warning") as logger_warning,+ ):+ operations, _ = await extract_loop.run()++ assert operations is empty_operations+ assert tracer_error.call_count == 0+ assert logger_warning.call_count == 0++ @pytest.mark.asyncio+ async def test_python_protocol_resets_format_retry_after_refetch(self):+ class FakeVLM:+ model = "test-model"++ def __init__(self):+ self.responses = iter(+ [+ "sdk.create_profile(content='invalid')\nsdk.commit()",+ "sdk.commit()",+ "# Caroline\n- Transgender woman (as of 2023-06-09)",+ "sdk.commit()",+ ]+ )+ self.call_count = 0++ async def get_completion_async(self, **kwargs):+ del kwargs+ self.call_count += 1+ return next(self.responses)++ class FakeContextProvider:+ read_file_contents = {}++ def get_memory_schemas(self, ctx):+ del ctx+ return [+ MemoryTypeSchema(+ memory_type="profile",+ description="Profile",+ directory="viking://user/{user_space}/memories",+ filename_template="profile.md",+ fields=[],+ )+ ]++ def get_tools(self):+ return []++ def get_extract_context(self):+ return SimpleNamespace(page_id_map=PageIdMap())++ def get_output_language(self):+ return "en"++ def instruction(self):+ return "Extract memory operations."++ async def prefetch(self):+ return []++ config = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="python")+ )+ vlm = FakeVLM()+ extract_loop = ExtractLoop(+ vlm=vlm,+ viking_fs=MagicMock(),+ context_provider=FakeContextProvider(),+ max_iterations=2,+ )+ empty_operations = ResolvedOperations(+ upsert_operations=[], delete_file_contents=[], errors=[]+ )+ extract_loop.resolve_operations = AsyncMock(return_value=(empty_operations, []))+ extract_loop._check_unread_existing_files = AsyncMock(+ side_effect=[{"viking://user/default/memories/profile.md": {}}, {}]+ )+ extract_loop._add_refetch_results_to_messages = AsyncMock()++ with (+ patch(+ "openviking.session.memory.extract_loop.get_openviking_config",+ return_value=config,+ ),+ patch(+ "openviking_cli.utils.config.get_openviking_config",+ return_value=config,+ ),+ patch("openviking.session.memory.extract_loop.tracer.error") as tracer_error,+ patch("openviking.session.memory.extract_loop.logger.warning") as logger_warning,+ ):+ operations, _ = await extract_loop.run()++ assert operations is empty_operations+ assert vlm.call_count == 4+ assert extract_loop._add_refetch_results_to_messages.await_count == 1+ assert tracer_error.call_count == 0+ assert logger_warning.call_count == 0diff --git a/tests/session/memory/test_memory_react_system_prompt.py b/tests/session/memory/test_memory_react_system_prompt.pyindex a37bdc02e..40343bf63 100644--- a/tests/session/memory/test_memory_react_system_prompt.py+++ b/tests/session/memory/test_memory_react_system_prompt.py@@ -30,6 +30,18 @@ class TestProviderInstruction:in instruction)+ def test_instruction_includes_extraction_and_maintenance_objective(self):+ provider = SessionExtractContextProvider(messages=[])++ instruction = provider.instruction()++ assert (+ "You are a memory extraction and maintenance agent. Analyze the conversation "+ "together with the pre-fetched existing memories, then produce a single atomic "+ "plan to create, update, delete, or reorganize memories so that the final memory "+ "collection conforms to all enabled memory schemas." in instruction+ )+def test_instruction_contains_output_language(self):"""Test that instruction includes the output language setting."""mock_messages = []@@ -47,8 +59,20 @@ class TestProviderInstruction:instruction = provider.instruction()assert "Peer Memory" in instruction- assert "profile/preferences/entities/events" in instruction- assert "cases/patterns/tools/skills" in instruction+ assert "Message role is authoritative for newly extracted facts" in instruction+ assert "attribute each fact to the speaker whose" in instruction+ assert "follow each enabled memory type's own schema rules" in instruction+ assert "Do not infer ownership from neighboring messages" in instruction+ assert "Facts already stored in pre-fetched or explicitly read memories" in instruction+ assert "remain valid sources for" in instruction+ assert "maintenance and may be preserved" in instruction+ assert "or moved between enabled memory" in instruction+ assert "types when required by their schemas" in instruction+ assert "same identity under the active memory schema" in instruction+ assert "shared category, or an overlapping topic" in instruction+ assert "If identity is uncertain" in instruction+ assert "compact" in instruction.lower()+ assert "only duplicate wording" in instruction.lower()def test_instruction_omits_resource_uri_handling_without_resource_uri(self):provider = SessionExtractContextProvider(@@ -232,8 +256,6 @@ class TestSessionConversationToolFiltering:assert provider._detect_language() == "zh-CN"--async def test_prepare_extraction_messages_replaces_image_part_with_vlm_description(self):class FakeVisionVLM:def __init__(self):@@ -341,6 +363,7 @@ class TestSessionConversationToolFiltering:assert any(isinstance(part, ImagePart) for part in messages[0].parts)assert provider.messages is not messages+def test_session_provider_empty_messages_still_uses_environment_fallback(monkeypatch):monkeypatch.setenv("TZ", "Asia/Shanghai")provider = SessionExtractContextProvider(messages=[])diff --git a/tests/session/memory/test_memory_tools.py b/tests/session/memory/test_memory_tools.pyindex f0161c094..7630713b7 100644--- a/tests/session/memory/test_memory_tools.py+++ b/tests/session/memory/test_memory_tools.py@@ -14,6 +14,7 @@ from openviking.session.memory.tools import (MemoryReadTool,MemorySearchTool,get_tool,+ memory_maintenance_notice,)from openviking_cli.session.user_id import UserIdentifier@@ -104,6 +105,27 @@ class TestMemoryTools:assert called is Trueassert result["content"] == "1\tGina values emotional support with Jon."+ assert "memory_maintenance_notice" not in result++ def test_memory_maintenance_notice_is_conditional_and_explains_two_strategies(self):+ assert memory_maintenance_notice("abcd", review_after_tokens=1) is None++ notice = memory_maintenance_notice("abcde", review_after_tokens=1)++ assert notice["maintenance_required"] is True+ assert set(notice) == {"maintenance_required", "guidance"}+ guidance = notice["guidance"]+ assert "estimated at 2 tokens" in guidance+ assert "above the 1-token readability target" in guidance+ assert "maintenance is required" in guidance+ assert "do not leave it as one broad oversized memory" in guidance+ assert "split different behavioral choice dimensions" in guidance+ assert "never invent multiple identities for one object" in guidance+ assert "compact only duplicate wording" in guidance.lower()+ assert "fact integrity takes priority" in guidance+ assert "Preserve every distinct valid fact exactly once" in guidance+ assert "only after every fact has one clear destination" in guidance+ assert "Delete or replace the oversized source" in guidance@pytest.mark.asyncioasync def test_read_tool_uses_offset_and_limit_for_visible_content(self):diff --git a/tests/session/memory/test_patch_merge_context_provider.py b/tests/session/memory/test_patch_merge_context_provider.pyindex dbc48f092..83e01576c 100644--- a/tests/session/memory/test_patch_merge_context_provider.py+++ b/tests/session/memory/test_patch_merge_context_provider.py@@ -147,7 +147,9 @@ async def test_patch_merge_context_provider_skips_extra_candidates_for_existing_)],)- provider.search_files = AsyncMock(return_value=["viking://user/u/memories/experiences/other.md"])+ provider.search_files = AsyncMock(+ return_value=["viking://user/u/memories/experiences/other.md"]+ )provider.read_file = AsyncMock(return_value={"memory_type": "experiences",@@ -380,12 +382,18 @@ def test_patch_merge_context_provider_instruction_mentions_path_field_normalizatinstruction = provider.instruction()assert "independent extraction patch proposals" in instruction- assert "merge duplicate/overlapping\nmemories into one canonical file patch" in instruction+ assert "same identity under the active memory schema" in instruction+ assert "same object or occurrence" in instruction+ assert "overlapping topic only identifies candidates" in instruction+ assert "never sufficient evidence" in instruction+ assert "every substantive atomic fact" in instruction+ assert "If identity is uncertain" in instructionassert "directory/filename fields" in instructionassert "schema identifiers" in instructionassert "book not books" in instructionassert "Chinese" in instructionassert "书籍 not 书/图书" in instruction+ assert "verified duplicate existing file" in instructionassert "put it in delete_ids" in instructiondiff --git a/tests/test_config_loader.py b/tests/test_config_loader.pyindex 2fb2e8c33..f7e745695 100644--- a/tests/test_config_loader.py+++ b/tests/test_config_loader.py@@ -347,6 +347,30 @@ def test_openviking_config_rejects_unknown_memory_field(monkeypatch):OpenVikingConfigSingleton.reset_instance()+def test_memory_extraction_output_format_defaults_to_python_and_accepts_json(monkeypatch):+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")++ default_config = OpenVikingConfig.from_dict({})+ json_config = OpenVikingConfig.from_dict({"memory": {"extraction_output_format": "json"}})++ assert default_config.memory.extraction_output_format == "python"+ assert json_config.memory.extraction_output_format == "json"+ with pytest.raises(ValueError):+ OpenVikingConfig.from_dict({"memory": {"extraction_output_format": "yaml"}})+++def test_memory_maintenance_review_tokens_defaults_and_validates(monkeypatch):+ monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")++ default_config = OpenVikingConfig.from_dict({})+ custom_config = OpenVikingConfig.from_dict({"memory": {"maintenance_review_tokens": 4096}})++ assert default_config.memory.maintenance_review_tokens == 1000+ assert custom_config.memory.maintenance_review_tokens == 4096+ with pytest.raises(ValueError):+ OpenVikingConfig.from_dict({"memory": {"maintenance_review_tokens": 0}})++def test_openviking_config_ignores_deprecated_memory_version(monkeypatch):monkeypatch.setenv(OPENVIKING_CONFIG_ENV, "/tmp/codex-no-config.json")diff --git a/tests/unit/session/memory/test_extract_loop_match_text.py b/tests/unit/session/memory/test_extract_loop_match_text.pyindex 937b692b5..b5bc13dc2 100644--- a/tests/unit/session/memory/test_extract_loop_match_text.py+++ b/tests/unit/session/memory/test_extract_loop_match_text.py@@ -17,6 +17,9 @@ from openviking.session.memory.dataclass import (WikiLink,)from openviking.session.memory.extract_loop import ExtractLoop+from openviking.session.memory.extraction_output_protocol import (+ create_extraction_output_protocol,+)from openviking.session.memory.merge_op import FieldType, MergeOpfrom openviking.session.memory.page_id_map import PageIdMap@@ -726,7 +729,8 @@ class TestResolutionRepair:errors=[],)- issues = self._loop()._retryable_resolution_issues(operations)+ loop = self._loop()+ issues = loop._retryable_resolution_issues(operations)assert issues == [{@@ -737,7 +741,8 @@ class TestResolutionRepair:"operation": {"ranges": "99"},}]- instruction = ExtractLoop._build_resolution_repair_instruction(issues)+ loop._output_protocol = create_extraction_output_protocol("json")+ instruction = loop._build_resolution_repair_instruction(issues)assert "valid in-bounds message indexes" in instructionassert '"reason_code": "invalid_ranges"' in instructionassert "server has preserved all successful operations" in instruction@@ -1185,14 +1190,8 @@ class TestPageIdInstruction:loop._check_unread_existing_files = AsyncMock(return_value=[])loop.finalize_operations = AsyncMock()- captured_messages = []-- def capture_messages(messages):- captured_messages.extend(messages)-with (patch("openviking.session.memory.extract_loop.get_openviking_config") as mock_config,- patch("openviking.session.memory.extract_loop.pretty_print_messages", capture_messages),patch("openviking.session.memory.extract_loop.SchemaModelGenerator.generate_all_models"),@@ -1200,12 +1199,14 @@ class TestPageIdInstruction:"openviking.session.memory.extract_loop.SchemaModelGenerator.create_structured_operations_model") as mock_create_model,):- mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))+ mock_config.return_value = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="json")+ )mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})await loop.run()- system_content = captured_messages[0]["content"]+ system_content = loop._call_llm.await_args.args[0][0]["content"]assert "## Page ID Rules" in system_contentassert "## Read Format Rules" in system_contentassert 'Every memory item you create or edit MUST include "page_id".' in system_content@@ -1215,7 +1216,7 @@ class TestPageIdInstruction:)assert "each visible line is prefixed with `line_number<TAB>`" in system_contentassert (- "Never include the line-number prefix itself in `search` or `replace`."+ "Never include the line-number prefix itself in `search`, `replace`, or `delete`."in system_content)assert "For existing items, use the page_id shown in read/search results." in system_content@@ -1264,14 +1265,8 @@ class TestPageIdInstruction:loop._check_unread_existing_files = AsyncMock(return_value=[])loop.finalize_operations = AsyncMock()- captured_messages = []-- def capture_messages(messages):- captured_messages.extend(messages)-with (patch("openviking.session.memory.extract_loop.get_openviking_config") as mock_config,- patch("openviking.session.memory.extract_loop.pretty_print_messages", capture_messages),patch("openviking.session.memory.extract_loop.SchemaModelGenerator.generate_all_models"),@@ -1279,12 +1274,14 @@ class TestPageIdInstruction:"openviking.session.memory.extract_loop.SchemaModelGenerator.create_structured_operations_model") as mock_create_model,):- mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=True))+ mock_config.return_value = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=True, extraction_output_format="json")+ )mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})await loop.run()- system_content = captured_messages[0]["content"]+ system_content = loop._call_llm.await_args.args[0][0]["content"]assert "## Page ID Rules" in system_contentassert "## Read Format Rules" in system_contentassert "## Link Rules" in system_content@@ -1345,7 +1342,9 @@ class TestFinalOperationsHydration:) as mock_create_model,patch("openviking.session.memory.extract_loop.tracer.info") as mock_tracer_info,):- mock_config.return_value = SimpleNamespace(memory=SimpleNamespace(link_enabled=False))+ mock_config.return_value = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="json")+ )mock_create_model.return_value = SimpleNamespace(model_json_schema=lambda: {})final_operations, _ = await loop.run()@@ -1361,3 +1360,37 @@ class TestFinalOperationsHydration:message for message in logged_messages if message.startswith("final_operations="))assert '"old_memory_file_content":null' not in final_log+++class TestExtractionMaxOutputTokens:+ """The extraction floor (32768) suits Doubao; vlm.max_tokens must override it."""++ def _loop(self, *, vlm_max_tokens, per_loop=None):+ loop = ExtractLoop(+ vlm=Mock(model="test-model"),+ viking_fs=Mock(),+ context_provider=Mock(),+ isolation_handler=Mock(),+ max_output_tokens=per_loop,+ )+ with patch(+ "openviking.session.memory.extract_loop.get_openviking_config"+ ) as mock_config:+ mock_config.return_value = SimpleNamespace(+ memory=SimpleNamespace(link_enabled=False, extraction_output_format="python"),+ vlm=SimpleNamespace(max_tokens=vlm_max_tokens),+ )+ loop._resolve_effective_max_output_tokens()+ return loop++ def test_default_floor_used_when_unconfigured(self):+ loop = self._loop(vlm_max_tokens=None)+ assert loop._effective_max_output_tokens == 32768++ def test_vlm_max_tokens_overrides_default_for_small_models(self):+ loop = self._loop(vlm_max_tokens=16384)+ assert loop._effective_max_output_tokens == 16384++ def test_per_loop_value_wins_over_config(self):+ loop = self._loop(vlm_max_tokens=16384, per_loop=8192)+ assert loop._effective_max_output_tokens == 8192diff --git a/tests/unit/test_litellm_vlm_gemini_cache.py b/tests/unit/test_litellm_vlm_gemini_cache.pyindex b07b9e870..ae95b99b4 100644--- a/tests/unit/test_litellm_vlm_gemini_cache.py+++ b/tests/unit/test_litellm_vlm_gemini_cache.py@@ -68,3 +68,23 @@ class TestGeminiCacheControlStripping:tools=tools,)assert kwargs["messages"] == [sentinel]++ def test_empty_assistant_turn_stays_removed_for_gemini_with_tools(self):+ # The Gemini cache_control strip must run on the already-sanitized+ # messages, not the raw input, so a structurally empty assistant turn+ # removed by sanitize_openai_messages is not reintroduced.+ vlm = _vlm("gemini-3.1-flash-lite-preview")+ messages = [+ {"role": "user", "content": "hi", "cache_control": {"type": "ephemeral"}},+ {"role": "assistant", "content": ""},+ {"role": "user", "content": "again"},+ ]+ tools = [{"type": "function", "function": {"name": "read", "parameters": {}}}]+ kwargs = vlm._build_kwargs(+ model="gemini/gemini-3.1-flash-lite-preview",+ messages=messages,+ tools=tools,+ )+ assert all(not (m["role"] == "assistant" and not m["content"]) for m in kwargs["messages"])+ assert [m["role"] for m in kwargs["messages"]] == ["user", "user"]+ assert all("cache_control" not in m for m in kwargs["messages"])diff --git a/tests/unit/test_message_format.py b/tests/unit/test_message_format.pynew file mode 100644index 000000000..767ff9f3a--- /dev/null+++ b/tests/unit/test_message_format.py@@ -0,0 +1,98 @@+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.+# SPDX-License-Identifier: AGPL-3.0++from openviking.utils.message_format import format_messages, sanitize_openai_messages+++def test_format_messages_renders_roles_and_content():+ rendered = format_messages(+ [+ {"role": "system", "content": "Follow the contract."},+ {"role": "user", "content": "Remember blue."},+ ]+ )++ assert rendered == (+ "=== Messages ===\n"+ "\n[system]\n"+ "Follow the contract.\n"+ "\n[user]\n"+ "Remember blue.\n"+ "\n=== End Messages ==="+ )+++def test_format_messages_renders_multimodal_content_as_json():+ rendered = format_messages(+ [+ {+ "role": "user",+ "content": [+ {"type": "text", "text": "Describe this image."},+ {"type": "image_url", "image_url": {"url": "[redacted]"}},+ ],+ }+ ]+ )++ assert "[user]" in rendered+ assert '"type": "image_url"' in rendered+ assert '"url": "[redacted]"' in rendered+++def test_format_messages_renders_tool_call_details():+ rendered = format_messages(+ [+ {+ "role": "assistant",+ "content": "Checking.",+ "tool_calls": [+ {+ "id": "call-1",+ "function": {"name": "read", "arguments": '{"uri":"viking://x"}'},+ }+ ],+ }+ ]+ )++ assert "[assistant tool_call] (id=call-1, name=read)" in rendered+ assert '"uri": "viking://x"' in rendered+++def test_sanitize_openai_messages_drops_only_empty_assistant_turns():+ messages = [+ {"role": "system", "content": "rules"},+ {"role": "assistant", "content": None},+ {"role": "assistant", "content": " "},+ {"role": "assistant", "content": []},+ {"role": "assistant", "content": [{"type": "text", "text": ""}]},+ {+ "role": "assistant",+ "content": None,+ "tool_calls": [+ {+ "id": "call-1",+ "type": "function",+ "function": {"name": "read", "arguments": "{}"},+ }+ ],+ },+ {"role": "assistant", "content": "answer"},+ {"role": "user", "content": ""},+ ]++ sanitized = sanitize_openai_messages(messages)++ assert sanitized == [messages[0], messages[5], messages[6], messages[7]]+ assert sanitized is not messages+ assert sanitized[1] is not messages[5]+++def test_sanitize_openai_messages_preserves_nonempty_multimodal_assistant_content():+ message = {+ "role": "assistant",+ "content": [{"type": "text", "text": "answer"}],+ }++ assert sanitize_openai_messages([message]) == [message]diff --git a/tests/unit/test_vlm_response_formats.py b/tests/unit/test_vlm_response_formats.pyindex 3c9c768b4..3c9610331 100644--- a/tests/unit/test_vlm_response_formats.py+++ b/tests/unit/test_vlm_response_formats.py@@ -82,6 +82,36 @@ def test_build_vlm_response_from_str_with_tools(vlm_type, config):assert response.usage == {}+ ("vlm_type", "config"),+ [+ (OpenAIVLM, {"provider": "openai", "model": "gpt-5.6-terra"}),+ (LiteLLMVLMProvider, {"provider": "litellm", "model": "gpt-5.6-terra"}),+ (VolcEngineVLM, {"provider": "volcengine", "model": "test-model"}),+ ],+ ids=["openai", "litellm", "volcengine"],+)+def test_text_request_drops_empty_assistant_but_preserves_tool_only_turn(vlm_type, config):+ vlm = vlm_type(config)+ tool_call = {+ "id": "call-1",+ "type": "function",+ "function": {"name": "read", "arguments": "{}"},+ }+ messages = [+ {"role": "user", "content": "start"},+ {"role": "assistant", "content": None},+ {"role": "assistant", "content": " "},+ {"role": "assistant", "content": None, "tool_calls": [tool_call]},+ {"role": "tool", "tool_call_id": "call-1", "content": "ok"},+ ]++ kwargs = vlm._build_text_kwargs(messages=messages)++ assert kwargs["messages"] == [messages[0], messages[3], messages[4]]+ assert messages[1] == {"role": "assistant", "content": None}++@pytest.mark.asyncioasync def test_openai_async_completion_from_str_with_tools(monkeypatch):async def create(**_kwargs):