@avantf/dsh-mem 0.6.4 → 0.7.0

package/lib/dsh-build.json

@@ -1,7 +1,7 @@
 {
-  "@deepseek-ai/dsh-system-prompt": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-tools": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-protocol": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-typert-registry": "0.2.0-rc.2",
-  "@deepseek-ai/dsh-util-values": "0.2.0-rc.2"
+  "@deepseek-ai/dsh-system-prompt": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-tools": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-protocol": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-typert-registry": "0.2.1-rc.2",
+  "@deepseek-ai/dsh-util-values": "0.2.1-rc.2"
 }

package/lib/engine/mem/config/config_files.d.ts

@@ -15,7 +15,7 @@ import type { AvantfLogger } from '../../mem-contract/index.js';
  * UNCOMMENTED line is warned about by the loader, so a wrong name here would be a trap rather than a
  * hint. `config_files.spec.ts` pins the ones this template names.
  */
-export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u6216 CLI --data-home\u3001\u63D2\u4EF6 profile \u7684 dataHome\uFF09\u51B3\u5B9A \u2014\u2014\n# \u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u7684\u65F6\u5019\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   auto_migrate: true                # \u6362\u6A21\u578B/\u5BBD\u5EA6\u540E\u81EA\u52A8\u5206\u6279\u91CD\u7B97\u65E7\u7A7A\u95F4\u7684\u5411\u91CF\uFF08\u9ED8\u8BA4\u5F00\uFF09\uFF1B\u5173\u6389\u53EA\u5269\u542F\u52A8\u544A\u8B66 + vectors --fix\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F\uFF1A\u951A\u70B9\u5B9E\u4F53\u7684 Jaccard\uFF08\u4E8B\u5B9E\u5BBD\u5EA6\u9971\u548C\uFF09\uFF1B2 \u5B9E\u4F53\u547D\u4E2D 1 \u4E2A\u6B63\u597D 0.2\n#   # P-11 \u4E2D\u6587\u65F6\u95F4\u7A97\u817F\uFF08\u9ED8\u8BA4\u5173\uFF09\uFF1A\u5F00\u542F\u540E\uFF0C\u5E26\u4E2D\u6587\u65F6\u95F4\u8868\u8FBE\u7684\u67E5\u8BE2\uFF08\u4E0A\u4E2A\u6708 / \u6700\u8FD1\u4E09\u5929 / 2026\u5E749\u6708 \u2026\uFF09\n#   # \u4F1A\u989D\u5916\u628A\"\u4E8B\u4EF6\u65F6\u95F4 valid_from \u843D\u5728\u8BE5\u7A97\u53E3\"\u7684\u6D3B\u8DC3\u4E8B\u5B9E\u4F5C\u4E3A\u4E00\u6761\u817F\u53C2\u4E0E\u878D\u5408\u3002\u5B83\u662F**\u52A0\u4E00\u6761\u817F\u3001\u4E0D\u662F\u8FC7\u6EE4\u5668**\uFF1A\n#   # \u53EA\u589E\u52A0\u5019\u9009\uFF0C\u7EDD\u4E0D\u5220\u6389\u8BED\u4E49 / FTS / \u5B9E\u4F53\u817F\u5DF2\u7ECF\u627E\u5230\u7684\u4E8B\u5B9E\uFF1B\u6CA1\u6709\u4E8B\u4EF6\u65F6\u95F4\u7684\u4E8B\u5B9E\u4E0D\u4F5C\u4E3A\u8BE5\u817F\u5019\u9009\uFF0C\n#   # \u4E5F**\u4E0D\u56DE\u9000\u5230\u5199\u5165\u65F6\u95F4 created_at**\u3002\u5B83\u5171\u7528 jaccard \u6743\u91CD\u4F4D\uFF08\u5BF9\u5916\u7684\u4E09\u952E\u6743\u91CD\u4E0D\u53D8\uFF09\u3002\n#   # \u4EC0\u4E48\u65F6\u5019\u8BE5\u5F00\uFF1A\u5148\u7528 mem_admin stats \u770B validity.coverage\uFF08\u6709\u591A\u5C11\u6D3B\u8DC3\u4E8B\u5B9E\u5E26\u4E8B\u4EF6\u65F6\u95F4\uFF09\uFF0C\n#   # \u518D\u7528\u56DE\u5F52\u7F51\u786E\u8BA4\u5B83\u786E\u5B9E\u6539\u5584\u65F6\u95F4\u7C7B\u67E5\u8BE2\u2014\u2014\u8986\u76D6\u7387\u22480 \u65F6\u5B83\u7B49\u4E8E\u6CA1\u5F00\u3002\u5199\u5165\u4E8B\u4EF6\u65F6\u95F4\u7528 mem_remember \u7684 event_date\u3002\n#   time_window: false\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
+export declare const DEFAULT_COMMON_CONFIG = "# avantf-mem \u516C\u5171\u914D\u7F6E\uFF08\u5206\u5C42\u7B2C\u2461\u5C42\uFF09\u3002\u8FD9\u91CC\u5168\u662F\u6CE8\u91CA\uFF1A\u5220\u6389/\u7559\u7A7A = \u7528\u5185\u5EFA\u9ED8\u8BA4\uFF0C\u53D6\u6D88\u6CE8\u91CA\u5373\u751F\u6548\u3002\n# \u5206\u5C42\uFF08\u4F4E\u2192\u9AD8\uFF09\uFF1A\u2460 \u5185\u5EFA\u9ED8\u8BA4 \u2192 \u2461 \u672C\u6587\u4EF6 \u2192 \u2462 \u540C\u76EE\u5F55\u7684 memory.yaml / knowledge.yaml\uFF08\u7F3A\u5931=\u4E0D\u8986\u76D6\uFF09\n#               \u2192 \u2463 \u73AF\u5883\u53D8\u91CF \u2192 \u2464 \u63D2\u4EF6/CLI \u663E\u5F0F\u4F20\u53C2\n# \u6240\u6709\u53EF\u7F16\u8F91\u6587\u672C\u90FD\u5728 ~/.avantf \u4E0B\uFF1Aconfigs/*.yaml\uFF08\u672C\u76EE\u5F55\uFF09\u4E0E prompts/*.md\uFF08\u6A21\u578B\u63D0\u793A\u8BCD\uFF09\u3002\n\n# \u6570\u636E\u6839\u4E0D\u5728\u8FD9\u91CC\u914D\uFF1A\u5B83\u7531 \u2463 AVANTF_HOME\uFF08\u5BB6\u65CF\u6839\uFF1A\u540C\u65F6\u51B3\u5B9A\u6570\u636E\u6839\u4E0E models/tools\uFF09\u51B3\u5B9A \u2014\u2014\n# \u53EA\u60F3\u6362\u6570\u636E\u6839\u3001\u4E0D\u642C\u6A21\u578B\u7F13\u5B58\u65F6\u7528 CLI \u7684 \u2464 \u663E\u5F0F\u53C2\u6570 avantf-mem --data-home <path>\uFF08\u63D2\u4EF6\u5219\u662F profile \u7684\n# dataHome\uFF0C\u5C5E \u2461\uFF09\u3002\u672C\u6587\u4EF6\u5C31\u5728\u6570\u636E\u6839\u91CC\u9762\uFF0C\u89E3\u6790\u6839\u65F6\u8FD8\u6CA1\u8BFB\u5230\u5B83\uFF0C\u6240\u4EE5\u5199\u5728\u8FD9\u91CC\u7684 dataHome \u5BF9\u6570\u636E\u6839\u65E0\u6548\uFF08DESIGN \u00A73\uFF09\u3002\n\n# semantic:                           # \u5D4C\u5165\u540E\u7AEF\uFF08\u8BB0\u5FC6\u4E0E\u77E5\u8BC6\u5171\u7528\uFF0C\u8DE8\u5E93\u5206\u6570\u624D\u53EF\u6BD4\uFF09\n#   backend: local_bge\n#   local_model: Xenova/bge-base-zh-v1.5    # \u5FC5\u987B\u662F ONNX \u4ED3\u5E93\n#   dim: 768\n#   auto_download: true\n#   auto_migrate: true                # \u6362\u6A21\u578B/\u5BBD\u5EA6\u540E\u81EA\u52A8\u5206\u6279\u91CD\u7B97\u65E7\u7A7A\u95F4\u7684\u5411\u91CF\uFF08\u9ED8\u8BA4\u5F00\uFF09\uFF1B\u5173\u6389\u53EA\u5269\u542F\u52A8\u544A\u8B66 + vectors --fix\n#   \u26A0\uFE0F cache_dir / mirror \u7531\u5BB6\u65CF\u5E95\u5EA7 @avantf/dsh-plugin-base \u7BA1\u7406\uFF1A\u5199\u5728\u8FD9\u91CC\u4F1A\u88AB\u5FFD\u7565\u5E76\u544A\u8B66\u3002\n#      \u7F13\u5B58\u76EE\u5F55\u7528\u73AF\u5883\u53D8\u91CF AVANTF_MEM_MODEL_CACHE\uFF0C\u955C\u50CF\u7528 AVANTF_MEM_MODEL_MIRROR\uFF08\u6216 HF_ENDPOINT\uFF09\u3002\n\n# vectorStore:\n#   backend: auto                     # auto = \u8D8A\u8FC7\u9608\u503C\u81EA\u52A8\u4ECE local_numpy \u8FC1\u5230 hnswlib\n#   auto_thresholds:\n#     hnswlib: 2000\n#   hnswlib_ef_search: 256            # ANN \u7684\u53EC\u56DE/\u901F\u5EA6\u65CB\u94AE\uFF0C\u8BED\u6599\u53D8\u5927\u5148\u8C03\u5B83\n\n# retriever:                          # \u4E09\u6761\u68C0\u7D22\u817F\u5728\u878D\u5408\u91CC\u7684\u6743\u91CD\u4E0E\"\u76F8\u5173\u6027\u95E8\u69DB\"\n#   weight_semantic: 0.55\n#   weight_fts: 0.30\n#   weight_jaccard: 0.15\n#   # \u7EDD\u5BF9\u95E8\u69DB\u6253\u5728\u6BCF\u6761\u817F\u7684\u539F\u59CB\u5206\u4E0A\u3001fuse() \u4E4B\u524D\uFF08\u878D\u5408\u5206\u53EA\u5728\u4E00\u6B21\u67E5\u8BE2\u5185\u53EF\u6BD4\uFF0C\u4E0D\u80FD\u5F53\u95E8\u69DB\uFF09\u3002\n#   # 0 = \u5173\u95ED\u8BE5\u95E8\u69DB\uFF1B\u5206\u6570\u7B49\u4E8E\u95E8\u69DB\u4FDD\u7559\u3002\u8BED\u4E49\u540E\u7AEF\u4E0D\u53EF\u7528\u65F6 min_fts_terms \u7684\u751F\u6548\u503C\u653E\u5BBD\u5230 1\u3002\n#   min_semantic_similarity: 0.5      # \u8BED\u4E49\u817F\u4F59\u5F26\uFF1B0.5 \u53EA\u5BF9 bge-base-zh-v1.5/768\uFF08mean pooling\uFF09\u6807\u5B9A\u8FC7\uFF0C\u6362\u6A21\u578B\u8981\u91CD\u6807\n#   min_fts_terms: 2                  # FTS \u817F\uFF1A\u8FD9\u4E00\u884C\u547D\u4E2D\u51E0\u4E2A\u4E0D\u540C\u7684\u67E5\u8BE2\u8BCD\u5143\uFF08\u62C9\u4E01\u8BCD\u22655\u5B57\u7B26 + CJK 3-gram\uFF09\n#   min_jaccard: 0.2                  # \u5B9E\u4F53\u817F\uFF1A\u951A\u70B9\u5B9E\u4F53\u7684 Jaccard\uFF08\u4E8B\u5B9E\u5BBD\u5EA6\u9971\u548C\uFF09\uFF1B2 \u5B9E\u4F53\u547D\u4E2D 1 \u4E2A\u6B63\u597D 0.2\n#   # P-11 \u4E2D\u6587\u65F6\u95F4\u7A97\u817F\uFF08\u9ED8\u8BA4\u5173\uFF09\uFF1A\u5F00\u542F\u540E\uFF0C\u5E26\u4E2D\u6587\u65F6\u95F4\u8868\u8FBE\u7684\u67E5\u8BE2\uFF08\u4E0A\u4E2A\u6708 / \u6700\u8FD1\u4E09\u5929 / 2026\u5E749\u6708 \u2026\uFF09\n#   # \u4F1A\u989D\u5916\u628A\"\u4E8B\u4EF6\u65F6\u95F4 valid_from \u843D\u5728\u8BE5\u7A97\u53E3\"\u7684\u6D3B\u8DC3\u4E8B\u5B9E\u4F5C\u4E3A\u4E00\u6761\u817F\u53C2\u4E0E\u878D\u5408\u3002\u5B83\u662F**\u52A0\u4E00\u6761\u817F\u3001\u4E0D\u662F\u8FC7\u6EE4\u5668**\uFF1A\n#   # \u53EA\u589E\u52A0\u5019\u9009\uFF0C\u7EDD\u4E0D\u5220\u6389\u8BED\u4E49 / FTS / \u5B9E\u4F53\u817F\u5DF2\u7ECF\u627E\u5230\u7684\u4E8B\u5B9E\uFF1B\u6CA1\u6709\u4E8B\u4EF6\u65F6\u95F4\u7684\u4E8B\u5B9E\u4E0D\u4F5C\u4E3A\u8BE5\u817F\u5019\u9009\uFF0C\n#   # \u4E5F**\u4E0D\u56DE\u9000\u5230\u5199\u5165\u65F6\u95F4 created_at**\u3002\u5B83\u5171\u7528 jaccard \u6743\u91CD\u4F4D\uFF08\u5BF9\u5916\u7684\u4E09\u952E\u6743\u91CD\u4E0D\u53D8\uFF09\u3002\n#   # \u4EC0\u4E48\u65F6\u5019\u8BE5\u5F00\uFF1A\u5148\u7528 mem_admin stats \u770B validity.coverage\uFF08\u6709\u591A\u5C11\u6D3B\u8DC3\u4E8B\u5B9E\u5E26\u4E8B\u4EF6\u65F6\u95F4\uFF09\uFF0C\n#   # \u518D\u7528\u56DE\u5F52\u7F51\u786E\u8BA4\u5B83\u786E\u5B9E\u6539\u5584\u65F6\u95F4\u7C7B\u67E5\u8BE2\u2014\u2014\u8986\u76D6\u7387\u22480 \u65F6\u5B83\u7B49\u4E8E\u6CA1\u5F00\u3002\u5199\u5165\u4E8B\u4EF6\u65F6\u95F4\u7528 mem_remember \u7684 event_date\u3002\n#   time_window: false\n\n# lifecycle:\n#   purge_after_archived_days: 365    # \u5F52\u6863\u4E8B\u5B9E\u7684\u7269\u7406\u6E05\u7406\u7A97\u53E3\uFF08\u6D3B\u8DC3\u65E5\uFF09\n#   contradiction_threshold: 0.6\n\n# trust:\n#   decay_per_day: 0.0055\u2026\n#   presence:\n#     heartbeat_minutes: 60           # \u5E38\u9A7B\u8FDB\u7A0B\u7684\u5FC3\u8DF3\uFF08\u6D3B\u8DC3\u65E5\u65F6\u949F\u4E0E\u751F\u547D\u5468\u671F\u626B\u63CF\uFF09\n\n# tools:                              # \u5916\u90E8\u4E8C\u8FDB\u5236\uFF08pandoc\uFF09\u7684\u53D7\u7BA1\u76EE\u5F55\n#   dir: ''                           # \u7559\u7A7A = \u5BB6\u65CF\u6839 tools\uFF08~/.avantf/env/tools\uFF09\uFF1BAVANTF_TOOLS_DIR \u53EF\u8986\u76D6\n#   auto_install: true\n";
 /**
  * Ensure the common config exists with content, and hand back the path either way.
  *

package/lib/engine/mem/facts_io.d.ts

@@ -0,0 +1,288 @@
+import { EXPORT_STATUSES, type ExportStatus, type RememberRequest } from '../mem-contract/index.js';
+/**
+ * The runtime slice these flows actually touch.
+ *
+ * Narrow on purpose: export reads two config fields, import/merge also call the store's `add` path.
+ * Keeping the parameter structural (rather than the whole `AvantfRuntime`) is what lets the admin
+ * dispatcher — an object literal whose `closed` getter is attached only at return time — pass
+ * itself in without a cast, and it documents that these flows cannot reach any other store face.
+ */
+export interface FactsIoRuntime {
+    config: {
+        home: string;
+        memory: {
+            db: {
+                path: string;
+            };
+        };
+    };
+    remember(req: RememberRequest): Promise<unknown>;
+}
+/** The document's discriminator. A file without it is not an export of this tool. */
+export declare const FACTS_EXPORT_FORMAT = "avantf-mem-facts";
+/**
+ * The version THIS build writes: 2 (v1 + the facts columns v1 did not carry).
+ *
+ * Versions are additive by design: v2 adds OPTIONAL fields, so a v1 document is still the same
+ * shape minus the new keys. A version outside {@link FACTS_EXPORT_VERSIONS} must be refused, never
+ * guessed at.
+ */
+export declare const FACTS_EXPORT_VERSION = 2;
+/** A version this build can READ. v1 documents are what users already have on disk. */
+export declare const FACTS_EXPORT_VERSIONS: readonly [1, 2];
+/** The version literal, so a parsed document can say which field set it came from. */
+export type FactsExportVersion = (typeof FACTS_EXPORT_VERSIONS)[number];
+/**
+ * `--status` values accepted by `export` (the whole DB, or one status).
+ *
+ * Re-exported from the contract, where the admin action and the CLI flag read the same set. The
+ * engine's public face keeps the name its callers already import.
+ */
+export { EXPORT_STATUSES, type ExportStatus };
+/** One `fact_sources` row, copied verbatim. */
+export interface ExportedFactSource {
+    kind: string;
+    ref: string;
+}
+/**
+ * One fact, as it stands in the source database.
+ *
+ * Every field is part of the documented format even when v1 import ignores it — the point of the
+ * document is that a later restore does not have to invent what was never written down.
+ */
+export interface ExportedFact {
+    /** Source-local row id. For reports/debugging ONLY; content is the identity. */
+    source_id: number;
+    content: string;
+    category: string;
+    status: string;
+    created_at: string | null;
+    updated_at: string | null;
+    ttl_days: number;
+    pinned: boolean;
+    pinned_at: string | null;
+    trust_score: number;
+    assert_count: number;
+    helpful_count: number;
+    last_reinforced_at: string | null;
+    sources: ExportedFactSource[];
+    valid_from: string | null;
+    valid_to: string | null;
+    supersedes_source_id: number | null;
+    /** `null` for an active row; the archive bookkeeping for an archived one. */
+    archive: {
+        at: string | null;
+        reason: string | null;
+    } | null;
+    /** Active-day clock at the last trust settle — the decay baseline. v1 had no such column. */
+    settle_clock?: number | null;
+    /** Reinforcement events inside the current 24h window. */
+    bonus_count?: number | null;
+    /** Calendar start of that window. */
+    bonus_window_at?: string | null;
+    /** How many times this fact was RETURNED by a retrieval leg (local usage stat, still stored). */
+    retrieval_count?: number | null;
+    last_retrieved_at?: string | null;
+    /** Mirror bookkeeping (a fact copied between libraries); informational, restored verbatim. */
+    mirror_source?: string | null;
+    mirror_target?: string | null;
+    /**
+     * The DERIVED-STATE stamps. Exported for completeness/diagnostics, but restore deliberately does
+     * not trust them: it stamps `entities_version = 0` (so the entity sweep rebuilds) and
+     * `conflict_checked = 1` (no corpus-wide conflict re-scan after a rebuild).
+     */
+    entities_version?: number | null;
+    conflict_checked?: number | null;
+}
+/** The single JSON document `export` writes (and `import`/`restore` read). */
+export interface FactsExportDocument {
+    format: typeof FACTS_EXPORT_FORMAT;
+    /** The version the document was WRITTEN as (1 or 2); this build writes 2. */
+    version: FactsExportVersion;
+    exported_at: string;
+    source: {
+        data_home: string;
+        db: string;
+        /** The SOURCE database's whole-DB status counts, independent of `--status`. */
+        counts: {
+            active: number;
+            archived: number;
+        };
+    };
+    facts: ExportedFact[];
+}
+/** How v1 import may treat the provenance embedded in the document. */
+export interface ImportOptions {
+    /** Plan only: no write, and the report gets `would_import`. */
+    dryRun?: boolean;
+    /** Fallback provenance when the document has none (the CLI passes `import:<file>`). */
+    sourceRef?: string;
+    /**
+     * Use `sources[0].ref` when present (the default, and the import contract).
+     *
+     * `merge` turns this OFF: its documented provenance is `merge:<absolute source path>` for every
+     * imported row, so a merge must not start attributing rows to whatever the other host recorded.
+     */
+    preferEmbeddedSources?: boolean;
+}
+/** One row the store refused; the rest of the import continues. */
+export interface ImportFailure {
+    /** The document's `source_id`, or `null` when the row was too malformed to have one. */
+    source_id: number | null;
+    error: string;
+}
+/** Source id → target id for one fact this invocation actually CREATED. */
+export interface ImportNewId {
+    source_id: number | null;
+    new_fact_id: number;
+}
+/**
+ * Counts of values v1 could not carry, over the facts this invocation imported (or, for a dry run,
+ * planned to import). `1` per fact that actually carried the value; `0` when there was nothing to
+ * lose. See the module doc for why these are losses rather than silent successes.
+ */
+export interface MetadataDropped {
+    timestamps: number;
+    trust: number;
+    assert_count: number;
+    helpful_count: number;
+    pinned: number;
+    supersedes: number;
+}
+/** The single JSON object `import` prints (`file` is added by the CLI, which knows the argument). */
+export interface ImportReport {
+    /** The input form this run detected: an export document. */
+    mode: 'json';
+    version: number;
+    total: number;
+    imported: number;
+    /** Present on `--dry-run` only; the number of facts that WOULD be written. */
+    would_import?: number;
+    skipped_existing: number;
+    skipped_archived: number;
+    failed: ImportFailure[];
+    new_ids: ImportNewId[];
+    metadata_dropped: MetadataDropped;
+}
+/** The db→db variant's report. Field names kept from the original `merge` output. */
+export interface MergeReport {
+    /** The input form this run detected: a SQLite source database. */
+    mode: 'db';
+    source: string;
+    source_active: number;
+    added: number;
+    would_add: number;
+    skipped_existing: number;
+    skipped_archived: number;
+    failed: {
+        source_fact_id: number | null;
+        error: string;
+    }[];
+    new_ids: {
+        source_fact_id: number | null;
+        new_fact_id: number;
+    }[];
+}
+export interface MergeOptions {
+    /** Provenance for rows without an embedded source; default `merge:<absolute source path>`. */
+    sourceRef?: string;
+    /** Plan only: no model warmup, no write, `added` stays 0. */
+    dryRun?: boolean;
+}
+/**
+ * Export THIS runtime's memory facts. Read-only: the store's own connection is never asked to write
+ * (and this command needs no embedding model — the rows are already there).
+ */
+export declare function exportFacts(rt: FactsIoRuntime, options?: {
+    status?: ExportStatus;
+}): FactsExportDocument;
+/**
+ * The compression containers `export` can write. `none` is plain minified JSON (the format's
+ * canonical text, and what stdout always carries).
+ */
+export type FactsExportCodec = 'brotli' | 'gzip' | 'none';
+/**
+ * The one serialization. MINIFIED by default: the document is a machine artifact that gets
+ * compressed, and indentation only makes the uncompressed fallback bigger. `pretty` exists for
+ * debugging (a human reading a diff), never as the default — and it is the ONLY mode that appends
+ * the trailing newline that used to be unconditional.
+ */
+export declare function serializeFactsExport(doc: FactsExportDocument, options?: {
+    pretty?: boolean;
+}): string;
+/**
+ * Serialize + compress in one step. gzip uses level 9; brotli uses quality 11 and tells the encoder
+ * the input size, which is the smallest output either library produces for a one-shot export.
+ *
+ * `codec` defaults to `none` so a caller that says nothing gets the canonical minified JSON.
+ */
+export declare function encodeFactsExport(doc: FactsExportDocument, options?: {
+    codec?: FactsExportCodec;
+    pretty?: boolean;
+}): Buffer;
+/** The document an encoded file carries, plus the container it actually turned out to be. */
+export interface DecodedFactsExport {
+    doc: FactsExportDocument;
+    codec: FactsExportCodec;
+}
+/**
+ * Whether these bytes are a SQLite database, decided by the FILE HEADER.
+ *
+ * `mem_admin import` takes either an export document or another host's `memory.db`, and the only
+ * honest discriminator is the content: the export containers (plain / gzip / brotli) never start with
+ * the SQLite header, and a `.db` file renamed to `.json` still is one. Kept here, beside
+ * {@link decodeFactsExport}, so both content sniffers live together.
+ */
+export declare function isSqliteDatabase(bytes: Buffer): boolean;
+/**
+ * The same check for a PATH, reading only the 16-byte header.
+ *
+ * A `memory.db` can be hundreds of MiB; deciding which flow to take must not read it into memory
+ * first. The JSON path still reads the whole document (it has to decode it), but the db path hands the
+ * path straight to the read-only opener.
+ */
+export declare function isSqliteDatabaseFile(path: string): boolean;
+/**
+ * Decode one export file from its BYTES. The file name is deliberately not an input: gzip has a
+ * magic header, brotli does not, and a pre-compression export is plain JSON — so the only reliable
+ * discriminator is the content itself (a brotli file renamed to `.json` still imports, and a plain
+ * JSON file renamed to `.json.br` does too).
+ *
+ * Order, and why: gzip magic → gunzip (a corrupt gzip is refused as gzip, not silently "JSON");
+ * otherwise UTF-8 JSON (the backward-compatible path for every old pretty file); only when JSON
+ * parsing fails, brotli (its decoder rejects non-brotli input, so this cannot shadow a JSON
+ * document). A document that IS JSON but has the wrong format/version throws its own error right
+ * away — {@link parseFactsExport} is the format gate, not a fallback.
+ */
+export declare function decodeFactsExport(bytes: Buffer): DecodedFactsExport;
+/**
+ * Resolve the container for a file export: an explicit flag wins, then the extension (`.br` /
+ * `.gz`), then plain minified JSON. Shared by the CLI and `/mem` so the two surfaces cannot
+ * disagree about what `--out backup.json.gz` means.
+ */
+export declare function codecForExportPath(path: string, explicit?: FactsExportCodec): FactsExportCodec;
+/**
+ * Parse and validate an export document TEXT (the stdin entry point). Top-level format errors are
+ * FATAL (the caller must write nothing); a malformed individual fact is NOT — {@link importFacts}
+ * collects it in `failed` and keeps going. Restore is STRICTER by construction: it validates every
+ * row before opening its transaction, because skipping a row would produce a different history.
+ */
+export declare function parseFactsExport(text: string): FactsExportDocument;
+/**
+ * Import one export document into `rt`'s memory store.
+ *
+ * Order of decisions per fact: archived → skipped_archived (v1 never revives); content already in
+ * the target (or planned by an earlier row of this same document) → skipped_existing; otherwise the
+ * store's add path runs. A row the store refuses is collected in `failed` and the loop continues.
+ */
+export declare function importFacts(rt: FactsIoRuntime, doc: FactsExportDocument, options?: ImportOptions): Promise<ImportReport>;
+/**
+ * `merge` — the db→document→import form of the same union.
+ *
+ * The source is another host's file: opened read-only, never migrated, never written. The document is
+ * built in memory and handed to {@link importFacts}, so merge and `import` share one per-fact add
+ * path (and one failure-collection rule). Its provenance stays `merge:<absolute source path>` even
+ * when the source rows carry their own sources — that is the documented merge contract and the
+ * reason {@link ImportOptions.preferEmbeddedSources} can be turned off.
+ */
+export declare function mergeDb(rt: FactsIoRuntime, dbPath: string, options?: MergeOptions): Promise<MergeReport>;

package/lib/engine/mem/index.d.ts

@@ -21,6 +21,10 @@ export * from './trustHeartbeat.js';
 export * from './runtime.js';
 export * from './store/memory.js';
 export * from './store/knowledge.js';
+export { normalizeWrite } from './store/common.js';
+export * from './facts_io.js';
+export * from './maintenance_paths.js';
+export * from './store/facts_restore.js';
 export * from './store/vector_repair.js';
 export * from './store/hybrid.js';
 export * from './store/source_picker.js';

package/lib/engine/mem/maintenance_paths.d.ts

@@ -0,0 +1,41 @@
+import type { FactsExportCodec } from './facts_io.js';
+/** Hard cap on a file a maintenance action will read (import / merge / restore_snapshot). */
+export declare const MAINTENANCE_MAX_FILE_BYTES: number;
+/** Where an export lands when the caller does not name a file. */
+export declare const MAINTENANCE_BACKUP_DIRNAME = "backups";
+/**
+ * `<data home>/backups/memory-YYYYMMDD-HHMMSS.<ext>` — never inside `memory/`.
+ *
+ * Brotli is the default because it is the smallest (measured: 70.6 KiB vs 92.3 gzip vs 300.0 plain
+ * for 233 facts). A caller that passes another codec keeps the file name truthful by changing the
+ * suffix along with the bytes.
+ */
+export declare function defaultFactsExportPath(home: string, now?: Date, codec?: FactsExportCodec): string;
+/** A resolved export destination, plus whether this call will overwrite an existing file. */
+export interface MaintenanceExportTarget {
+    file: string;
+    existed: boolean;
+}
+/**
+ * Resolve an export destination inside the data root.
+ *
+ * The TARGET may not exist yet (that is the normal case), so containment is established on the
+ * nearest existing ancestor: every component below it is one this call will create, and a
+ * not-yet-created component cannot be a symlink. When the target DOES exist, its realpath is
+ * checked — a symlink pointing outside is refused rather than followed.
+ */
+export declare function resolveMaintenanceExportTarget(home: string, input?: string): MaintenanceExportTarget;
+/**
+ * Resolve an INPUT file (import / merge / restore_snapshot) inside the data root.
+ *
+ * The file must exist, be a regular file, and be no larger than {@link MAINTENANCE_MAX_FILE_BYTES}.
+ * A symlink to a regular file INSIDE the root is usable; a symlink that escapes it is refused before
+ * the size or existence of the outside target is examined.
+ */
+export declare function resolveMaintenanceInputFile(home: string, input: string): string;
+/**
+ * Write a file atomically: a sibling temp file, then one `rename` (same directory, so the rename
+ * cannot cross a filesystem). An overwrite is therefore either the old bytes or the new bytes, never
+ * a truncated export. The temp file is removed when anything fails.
+ */
+export declare function writeFileAtomic(path: string, bytes: Buffer | string): void;

package/lib/engine/mem/runtime.d.ts

@@ -6,6 +6,8 @@ import { type Db } from './db/conn.js';
 import { type RelevanceHit } from './store/lexical.js';
 import { MemoryStore } from './store/memory.js';
 import { KnowledgeStore } from './store/knowledge.js';
+import { type FactsExportCodec, type ImportReport, type MergeReport } from './facts_io.js';
+import type { RestoreReport } from './store/facts_restore.js';
 export interface RuntimeOptions {
     dataHome?: string;
     memoryDbPath?: string;
@@ -35,6 +37,22 @@ export interface RuntimeOptions {
         readonly tools?: string;
         readonly models?: string;
     };
+    /**
+     * Skip the adapters' eager constructor warm even when the caller passes no {@link managedRoots}:
+     * the caller owns the warm schedule and will warm explicitly.
+     *
+     * There are exactly TWO ways to get a deferred warm, and both are requests of the same thing:
+     *
+     *   - {@link managedRoots} — the DSH plugin's path. The framework owns the model root and may still
+     *     be installing into it, so the backends must not warm themselves (that would race the install
+     *     and fetch a second copy).
+     *   - `deferWarm: true` — the CLI's path. The flag exists because the CLI is one-shot and its
+     *     READ-ONLY commands (`stats`, `list`, `export`, …) must not load or download the model at all;
+     *     it warms explicitly, and only from `needsModels` (the command table in `cli/src/index.ts`).
+     *
+     * A first `encode()` still warms lazily, so deferring never costs the commands that do encode.
+     */
+    deferWarm?: boolean;
 }
 /**
  * The awaited result of a store method — what a dispatch overload promises.
@@ -65,6 +83,28 @@ export type DispatchError = {
  * admin payload no store method produces, because the runtime composes it.
  */
 export type AdminStatsResult = StatsSummary;
+/**
+ * `admin export`: the file THIS call wrote and its container. Deliberately carries NO document body
+ * — the model gets a receipt, not the library (the file is the artifact; whoever needs the facts
+ * reads it with the CLI or imports it back).
+ */
+export interface AdminExportReport {
+    file: string;
+    codec: FactsExportCodec;
+    bytes: number;
+    plain_bytes: number;
+    counts: {
+        active: number;
+        archived: number;
+    };
+    /** True when an existing file was replaced (the atomic write is the same either way). */
+    overwritten: boolean;
+}
+/** `admin restore_snapshot`: the engine's restore report plus the container it came from. */
+export type AdminRestoreSnapshotReport = RestoreReport & {
+    file: string;
+    codec: FactsExportCodec;
+};
 /**
  * The payload of the four hits-returning recall actions, which one overload groups because a
  * caller may hold them as a union (`action: 'chain' | 'reason'`).
@@ -119,9 +159,10 @@ export type RecallDispatch = {
     (req: RecallRequest): Promise<unknown>;
 };
 /**
- * `admin` is the widest dispatcher: counts, a fact page, a detail, flags, and five diagnostic
- * reports. `ReturnType<…>` keeps each member tied to the store method that actually produces it,
- * so a change there propagates instead of leaving callers with a cast they invented.
+ * `admin` is the widest dispatcher: counts, a fact page, a detail, flags, five diagnostic
+ * reports, and the four data-root maintenance actions (export / import / merge / restore_snapshot).
+ * `ReturnType<…>` keeps each member tied to the store method that actually produces it, so a change
+ * there propagates instead of leaving callers with a cast they invented.
  */
 export type AdminDispatch = {
     (req: Extract<AdminRequest, {
@@ -163,6 +204,19 @@ export type AdminDispatch = {
     (req: Extract<AdminRequest, {
         action: 'maintenance';
     }>): StoreResult<MemoryStore, 'maintenance'>;
+    (req: Extract<AdminRequest, {
+        action: 'export';
+    }>): AdminExportReport;
+    /** Content-detected: a SQLite source answers with the db report, an export document with the JSON one. */
+    (req: Extract<AdminRequest, {
+        action: 'import';
+    }>): Promise<ImportReport | MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'merge';
+    }>): Promise<MergeReport>;
+    (req: Extract<AdminRequest, {
+        action: 'restore_snapshot';
+    }>): Promise<AdminRestoreSnapshotReport>;
     (req: AdminRequest): unknown;
 };
 /**

package/lib/engine/mem/store/facts_restore.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Full-fidelity REBUILD of a memory library from an export document — the ONE owner of
+ * `avantf-mem restore <file>`.
+ *
+ * RESTORE IS NOT IMPORT. `import` / `merge` (see `facts_io.ts`) are CONTENT-IDENTITY UNIONS: new
+ * rows get new ids, only ACTIVE facts travel, and every value the document carries beyond
+ * category/ttl/sources/validity is counted as dropped. Restore is the opposite promise — "put this
+ * library back exactly as it was" — which is only answerable if the target is EMPTY:
+ *
+ *   - `facts` is written DIRECTLY, one transaction, keeping `fact_id`, status, timestamps,
+ *     `trust_score`, `settle_clock`, counters, pin state, TTL, validity, the supersedes pointer and
+ *     the mirror bookkeeping. A non-empty target is REFUSED (never merged into), because "restore"
+ *     that silently unions two histories is a different, unreviewable operation.
+ *   - Rows are inserted in `source_id` ASCENDING order, so the row a `supersedes` pointer names
+ *     already exists when the pointer is written. v1 documents carry the same pointer as
+ *     `supersedes_source_id`, so both versions resolve identically.
+ *   - `fact_sources` is restored IN FULL (a fact may carry several rows); the identity `import`
+ *     is forced to collapse into one `ref` string is not a limitation restore inherits.
+ *   - FTS is NOT written by hand. `facts_fts` is an external-content FTS5 table with AFTER INSERT /
+ *     DELETE / UPDATE triggers (`db/schema.ts`), so inserting into `facts` indexes the row. That is
+ *     the whole reason this path can bypass `MemoryStore.add` without losing lexical recall.
+ *   - The DERIVED state is re-derived, not restored. `entities_version = 0` marks every row for the
+ *     entity sweep, which rebuilds `fact_entities`, `triples` and the HRR bundle in bounded passes
+ *     after the commit; `conflict_checked = 1` keeps a restored corpus from queueing a whole-library
+ *     conflict re-scan (the log is not exported — see below).
+ *   - VECTORS ARE NOT RESTORED (`semantic_vector`, `embedding_model` stay NULL, `hrr_vector` stays
+ *     NULL until the sweep writes it). They are machine-local encodings of a specific model revision;
+ *     copying them between hosts would create a vector space the live index cannot serve. The report
+ *     says so and points at `avantf-mem vectors --fix` / a host restart.
+ *
+ * WHAT IS DELIBERATELY NOT RESTORED: `contradiction_log`, the retrieval-stat meta table, `tags`
+ * (not exported), and `archived_clock`. The last one is a TRUST-CLOCK value ("active days at archive
+ * time"); the document only carries `archived_at` (a wall-clock timestamp), and converting one into
+ * the other would invent data. Leaving it NULL sends restored archived rows down
+ * `purgeArchived`'s CALENDAR branch, which reads the restored `archived_at` — the honest
+ * approximation, and the reason a restore does not restart every purge countdown at zero.
+ *
+ * V1 DOCUMENTS ARE READ. v2 only ADDED optional facts columns, so a v1 row simply lacks them; each
+ * absence is counted per field in `metadata_missing` and resolved with the documented fallback. The
+ * one fallback with a real decision behind it: `settle_clock` becomes the CURRENT active-day clock.
+ * Zero would make every restored fact decay by the host's whole clock in one settlement; the current
+ * clock is the "no decay has happened yet" baseline, which is what a fresh restore means.
+ *
+ * @module store/facts_restore
+ */
+import type { FactsExportDocument } from '../facts_io.js';
+import type { Db } from '../db/conn.js';
+import { type EntitySweepReport } from './entity_sweep.js';
+/** The one operator hint about the data restore cannot carry. */
+export declare const RESTORE_VECTOR_HINT: string;
+/**
+ * Every metadata field the report accounts for.
+ *
+ * The list is the DOCUMENT's, not the table's: it includes the v2 additions (so a v1 file shows
+ * exactly which columns it could not carry) and the derived-state stamps (which restore re-derives
+ * rather than trust). A field counts as missing when the document does not carry the key at all —
+ * `null` is a value the document states ("unknown"), not an absence.
+ */
+export declare const RESTORE_METADATA_FIELDS: readonly ["category", "created_at", "updated_at", "trust_score", "pinned", "pinned_at", "assert_count", "helpful_count", "last_reinforced_at", "ttl_days", "valid_from", "valid_to", "supersedes_source_id", "archive", "sources", "settle_clock", "bonus_count", "bonus_window_at", "retrieval_count", "last_retrieved_at", "mirror_source", "mirror_target", "entities_version", "conflict_checked"];
+export type RestoreMetadataField = (typeof RESTORE_METADATA_FIELDS)[number];
+/** Per-field count of facts whose document did not carry that field. */
+export type RestoreMetadataMissing = Record<RestoreMetadataField, number>;
+export interface RestoreOptions {
+    /** Plan only: no write, no entity rebuild; the report carries `would_restore` + `target_facts`. */
+    dryRun?: boolean;
+}
+/**
+ * The store's half of the contract, narrow on purpose: the ONE write connection, plus the bounded
+ * entity sweep this flow reuses after the commit. Nothing here knows about `MemoryStore`.
+ */
+export interface RestoreTarget {
+    db: Db;
+    reindexEntities(budget?: number): Promise<EntitySweepReport>;
+}
+/** How many facts a document would restore, split by status. */
+export interface RestoreCounts {
+    total: number;
+    active: number;
+    archived: number;
+}
+/** The single JSON object the CLI prints (it adds `file` / `codec`, which are argv facts). */
+export interface RestoreReport {
+    /** The DOCUMENT's version, echoed as-is (1 or 2). */
+    version: number;
+    /** Present on `--dry-run` only. */
+    dry_run?: true;
+    /** Present on `--dry-run` only: what a real run would write. */
+    would_restore?: RestoreCounts;
+    /**
+     * Present on `--dry-run` only: the target's CURRENT fact count. Non-zero means the real run would
+     * be refused (restore only rebuilds into an empty table).
+     */
+    target_facts?: number;
+    /** Facts actually written (0 on a dry run). */
+    restored: number;
+    active: number;
+    archived: number;
+    metadata_missing: RestoreMetadataMissing;
+    /** FTS5 rows after the commit — the trigger's work, asserted equal to `restored` by the tests. */
+    fts_rows: number;
+    entities: EntitySweepReport;
+    vectors: {
+        restored: 0;
+        hint: string;
+    };
+}
+/**
+ * Rebuild the target library from `doc`.
+ *
+ * Order of guarantees: the document is validated COMPLETELY first (no writes on a bad file), then one
+ * `BEGIN IMMEDIATE` transaction re-checks emptiness and inserts facts + sources (a failure anywhere
+ * rolls the whole thing back), and only after that commit does the derived state get rebuilt. The
+ * entity sweep is deliberately OUTSIDE the transaction: it is bounded, resumable work, and holding
+ * the write lock for a whole-corpus re-extraction is exactly what its batch exists to avoid.
+ */
+export declare function restoreFactsDocument(target: RestoreTarget, doc: FactsExportDocument, options?: RestoreOptions): Promise<RestoreReport>;

package/lib/engine/mem/store/memory.d.ts

@@ -1,6 +1,8 @@
 import { type Config, type ContradictionRecord, type FactDetail, type FactPage, type FloorProfile, type RecallResult, type RememberResult, type SourceCoverage, type TrustDiagnostic, type ValidityCoverage, type VectorMigrationOutcome, type VectorMigrationProgress, type VectorSpaceHealth, type VectorsDiagnostic, type VectorsFixStoreReport } from '../../mem-contract/index.js';
 import type { SemanticBackend, VectorStore } from '../../mem-retrieval/index.js';
 import { ENTITY_SWEEP_BATCH, type EntitySweepReport } from './entity_sweep.js';
+import { type RestoreOptions, type RestoreReport } from './facts_restore.js';
+import type { FactsExportDocument } from '../facts_io.js';
 import { DEFAULT_VECTOR_MIGRATION_BATCH, type VectorRepairTarget } from './vector_repair.js';
 import type { Db } from '../db/conn.js';
 import { type LexicalProbe } from './lexical.js';
@@ -487,6 +489,20 @@ export declare class MemoryStore {
      * selection (`facts.staleEntityRows`, ACTIVE facts only) and the per-fact write below.
      */
     reindexEntities(budget?: number): Promise<EntitySweepReport>;
+    /**
+     * Rebuild this library from an export document — the engine half of `avantf-mem restore <file>`.
+     *
+     * A THIN adapter on purpose: the empty-table rule, the insert order, the SQL and the report all
+     * live in `store/facts_restore.ts`, because this class is a hub and a rebuild of the whole facts
+     * table must not become another reason to grow it. What it contributes is the two things only the
+     * store has: the ONE write connection (so the restored rows are immediately visible to every
+     * reader here) and the derived-state entity sweep that runs after the commit.
+     *
+     * Reachable from `mem_admin restore_snapshot` (and from the CLI): after a real restore this
+     * method refreshes the live vector index and resets the conflict-drain cursor, so a host that
+     * rebuilt its library from a tool call answers from the NEW rows without a restart.
+     */
+    restoreFacts(doc: FactsExportDocument, options?: RestoreOptions): Promise<RestoreReport>;
     /**
      * A fact left the ACTIVE corpus: retire the open conflicts that name it, so
      * `contradict` never reports a pair whose revision is archived and repeated