记忆 API

前缀： /api/memory

这是主服务器为记忆浏览器和设置页面提供的 API，涵盖近期记忆编辑、记忆功能开关、角色记忆重命名，以及由用户主动触发的遗留存储清理。它不是进程内 记忆服务器 API 的通用代理。

所有路由都不带末尾斜杠。云存储处于维护态或只读态时，写操作可能返回 409。

端点一览

方法	路径	用途
GET	/api/memory/recent_files	列出近期记忆的逻辑文件名
GET	/api/memory/recent_file	读取一个近期记忆文件
POST	/api/memory/recent_file/save	替换一个角色的近期记忆历史
POST	/api/memory/update_catgirl_name	完整角色改名事务的兼容别名
GET	/api/memory/review_config	读取近期记忆自动复核开关
POST	/api/memory/review_config	更新近期记忆自动复核开关
GET	/api/memory/powerful_memory_config	读取强力记忆开关
POST	/api/memory/powerful_memory_config	更新强力记忆开关，并执行必要迁移
GET	/api/memory/legacy/scan	只读扫描用户可见的遗留记忆根目录
POST	/api/memory/legacy/purge	删除从遗留根目录中明确选中的条目

近期记忆文件

为兼容旧版记忆浏览器，API 仍使用逻辑文件名 recent_<角色>.json。当前存储会把它解析到 memory/<角色>/recent.json；迁移期间仍可读取旧的扁平文件。

GET /api/memory/recent_files

无参数。

该路由会搜索活动记忆根目录和项目记忆根目录，去重逻辑文件名并排序返回。

{
  "files": ["recent_小天.json", "recent_小夜.json"]
}

GET /api/memory/recent_file

查询参数

名称	类型	必填	说明
filename	字符串	是	例如 recent_小天.json；拒绝路径分隔符和 ..

content 是文件中的 UTF-8 JSON 文本，不是已经解析的消息数组。

{
  "content": "[{\"type\":\"human\",\"data\":{...}}]",
  "fingerprint": "b4c1000000000000000000000000000000000000000000000000000000000000",
  "identity_token": "a7e3111111111111111111111111111111111111111111111111111111111111"
}

fingerprint 与 identity_token 是不透明的快照令牌。客户端编辑内容时必须保留二者，并在对应的保存请求中原样回传。

错误响应为 {"success": false, "error": "..."}：文件名非法返回 400，逻辑文件无法解析返回 404。

POST /api/memory/recent_file/save

替换所选角色的近期历史，并取消该角色正在执行的复核任务，使手动编辑立即生效。

请求体

{
  "filename": "recent_小天.json",
  "fingerprint": "b4c1000000000000000000000000000000000000000000000000000000000000",
  "identity_token": "a7e3111111111111111111111111111111111111111111111111111111111111",
  "chat": [
    { "role": "human", "text": "你好！" },
    { "role": "ai", "text": "晚上好！" }
  ]
}

字段	类型	必填	说明
filename	字符串	是	必须匹配 recent_<角色>.json；角色名从该字段推导
fingerprint	字符串	是	用于载入本次编辑的 GET 所返回的不透明内容令牌
identity_token	字符串	是	同一次 GET 所返回的不透明文件身份令牌
chat	数组	是	替换后的历史，最多 10,000 条
chat[].role	字符串	是	写入的消息类型，通常为 human、ai 或 system
chat[].text	字符串	否	消息文本；默认为空字符串
chat[].source_index	整数	否	该条目在 GET 返回数组中的下标，只用于定位
chat[].theater	布尔	否	标记该条目代表剧场记忆消息；它不会以普通文本写回

单条消息文本上限为 32,768 个字符，请求中全部消息文本合计上限为 2,097,152 个字符。聊天条目中的未知字段不会持久化。

剧场记忆消息（小剧场单集胶囊）在这里只读。无论提交的 chat 如何表示它们，当前快照里的每条剧场消息都会连同元数据按原位置原样保留，只替换普通消息。若不带 source_index 的客户端提交了对不上任何已存消息的条目，同时又有剧场消息没被对上，保存会以 409 和 code: "RECENT_FILE_THEATER_READONLY" 拒绝。

成功响应：

{
  "success": true,
  "need_refresh": true,
  "catgirl_name": "小天",
  "fingerprint": "d8f2222222222222222222222222222222222222222222222222222222222222",
  "identity_token": "a7e3111111111111111111111111111111111111111111111111111111111111"
}

校验失败返回 400 和 success: false。缺少快照令牌，或文件内容/身份已经并发变化时返回 409；冲突响应带有 code: "RECENT_FILE_CONFLICT" 和当前令牌。发生冲突后必须重新 GET 文件、合并用户编辑再保存，不能仅替换为响应中的新令牌后重放旧 chat。成功响应会返回下一次编辑要使用的令牌。存储失败返回 success: false 及 error；云存储维护态同样返回 409。

角色记忆重命名

POST /api/memory/update_catgirl_name

这是规范接口 POST /api/characters/catgirl/{old_name}/rename 的兼容别名。它会排空记忆复核/压缩任务、发布角色改名、迁移全部记忆与卡面状态、重载 memory server，并在失败时回滚。若旧客户端在该事务已经提交后重复调用，本接口会以幂等 no-op 成功返回。

{
  "old_name": "旧名字",
  "new_name": "新名字"
}

两个字段都是必填字符串。历史 old_name 可以包含点号；new_name 使用当前角色名规则，且不能是保留路由名。

{
  "success": true,
  "memory_renamed": true,
  "memory_server_reloaded": true
}

幂等重复调用返回 changed: false、already_renamed: true 和 exists_after。只有配置已经包含新名称且旧存储已经消失时才允许该 no-op；若配置已发布但旧存储仍残留，接口返回 409，不会掩盖部分改名，需通过规范的角色管理接口修复。名称缺失或非法返回 400；存储不可写时也可能返回 409。

记忆功能开关

GET /api/memory/review_config

返回是否启用近期记忆的自动复核和修正。配置不存在时默认为 true。

{ "enabled": true }

读取会等待正在进行的记忆开关保存结束，再返回落盘值。文件或设置项缺失时默认 true。文件不可读、JSON 损坏、配置不是对象或设置值不是布尔值时，返回 HTTP 503 和 {"error": "..."}，不返回 enabled。如果仅该设置值无效，响应还包含 "code": "invalid_memory_setting"，页面会提供明确的开启/关闭修复选项；合法布尔值 POST 可修复该设置并保留其他字段。

POST /api/memory/review_config

请求体必须是 JSON 对象，且包含必填的布尔字段 enabled；JSON 损坏、字段缺失或类型错误返回 HTTP 400 和 {"success": false, "error": "..."}。读取或保存失败返回 success: false，不会用新配置覆盖不可读、JSON 损坏或根类型不是对象的配置文件；只有文件不存在时才创建新配置。两个记忆开关的更新在必要迁移和文件保存完成前串行执行。将强力记忆保存为 false 时，只有存量值已为布尔 false 才跳过迁移；非法旧值按未知状态处理。

{ "enabled": false }

该路由把 recent_memory_auto_review 写入 core_config.json。

{ "success": true, "enabled": false }

失败响应为 {"success": false, "error": "..."}。存储维护态可能返回 409。

GET /api/memory/powerful_memory_config

返回 powerful_memory_enabled 设置。已有安装没有显式配置时默认为 true。

{ "enabled": true }

读取会等待正在进行的记忆开关保存结束，再返回落盘值。文件或设置项缺失时默认 true。文件不可读、JSON 损坏、配置不是对象或设置值不是布尔值时，返回 HTTP 503 和 {"error": "..."}，不返回 enabled。如果仅该设置值无效，响应还包含 "code": "invalid_memory_setting"，页面会提供明确的开启/关闭修复选项；合法布尔值 POST 可修复该设置并保留其他字段。

POST /api/memory/powerful_memory_config

请求体必须是 JSON 对象，且包含必填的布尔字段 enabled；JSON 损坏、字段缺失或类型错误返回 HTTP 400 和 {"success": false, "error": "..."}。读取或保存失败返回 success: false，不会用新配置覆盖不可读、JSON 损坏或根类型不是对象的配置文件；只有文件不存在时才创建新配置。两个记忆开关的更新在必要迁移和文件保存完成前串行执行。将强力记忆保存为 false 时，只有存量值已为布尔 false 才跳过迁移；非法旧值按未知状态处理。

{ "enabled": false }

强力记忆开关控制证据驱动的 LLM 路径，包括信号分析、晋升时合并、反驳检查、负向目标检查、事实去重和 persona 修正。关闭强力记忆后，轻量反馈路径仍可用。

从 ON 切换到 OFF 时，会先请求记忆服务器进程重置已确认反思的计时锚点，避免旧的 confirmed 条目被时间驱动的降级路径立即晋升。只有迁移成功后才保存配置。

成功响应：

{ "success": true, "enabled": false }

迁移或持久化失败：

{ "success": false, "error": "migration HTTP 409" }

遗留记忆清理

遗留清理是明确的两步操作：先扫描，再提交选中的绝对路径。扫描不会迁移或删除任何数据。

GET /api/memory/legacy/scan

无参数。

响应会标识活动运行时记忆目录之外的候选根目录，并描述每个根目录的直接子项。无法计算大小或超过安全扫描上限时，size_bytes 为 -1。

{
  "success": true,
  "runtime_memory_dir": "C:\\...\\memory",
  "legacy_roots": [
    {
      "root": "C:\\...\\old-root\\memory",
      "source": "legacy_app_root",
      "exists": true,
      "entries": [
        {
          "name": "小天",
          "path": "C:\\...\\old-root\\memory\\小天",
          "is_dir": true,
          "size_bytes": 12345,
          "is_unlinked": false,
          "runtime_has_same_name": true
        }
      ]
    }
  ],
  "total_entries": 1,
  "total_size_bytes": 12345
}

意外的扫描失败返回 500 和 success: false。

POST /api/memory/legacy/purge

这是破坏性操作。只应提交最近一次扫描作为条目返回的路径。

{
  "paths": [
    "C:\\...\\old-root\\memory\\小天"
  ]
}

paths 必须是非空的绝对路径数组。每个路径都必须严格位于当前识别出的遗留根目录之下。该路由拒绝相对路径、.. 段、根目录本身和活动运行时记忆目录。目标不存在会被视为已删除，因此重试是幂等的。

删除按条目尽力执行，因此成功请求可以同时包含 removed 和 errors：

{
  "success": true,
  "removed": ["C:\\...\\old-root\\memory\\小天"],
  "errors": [
    { "path": "C:\\...\\not-allowed", "error": "..." }
  ]
}

请求体非法返回 400；没有可识别的遗留根目录返回 409；初始化失败返回 500。