astrbot_plugin_memory_compa.../docs/记忆插件源码审计与优化档案.md

19 KiB

运维版记忆插件源码审计与优化档案

审计日期:2026-07-24
审计对象:astrbot_plugin_memory_companion_ops(工作目录:astrbot_plugin_memory_companion-main)
当前分支:ops-main
当前版本:1.6.2-ops.2
审计性质:源码、数据模型、运行链路、面板 API、测试与部署文档的全量结构化复盘;本档案不替代生产验收记录。

1. 结论摘要

这个插件已经具备“可投入运维场景”的完整骨架:长期记忆、时间线、分层检索、Embedding/Rerank、权限隔离、自然衰减、导入导出、LivingMemory 迁移、Archivist Bridge、Q3 运维事实合同和 Q4 时间感知均已落地,并有较完整的回归测试与 VM 验收证据。

当前最值得优化的不是再堆一个“记忆类型”,而是把已有能力从“能运行”提升为“可解释、可纠错、可治理”:

  1. 重要性、置信度、新鲜度和人格价值仍然共同影响一个排序分数,缺少独立的事实可信度与召回解释层。
  2. 记忆可以被 supersedes_id 标记,但没有形成完整的冲突检测、版本链、当前有效版本查询和用户可见纠错流程。
  3. 动态时间元数据已实现,但检索缓存命中后只做权限复验,不重新计算年龄、过期状态或排序分数。
  4. 维护、导入、导出、迁移能力很丰富,但缺少统一的 dry-run、校验和、分页/流式处理、失败恢复与审计结果模型。
  5. 观测面板能展示不少运行指标,但还没有“召回质量、误召回、过期事实命中、冲突记忆、注入收益”的闭环指标。

总体评级:架构能力强,生产边界清晰;数据治理和质量度量处于下一阶段建设期。

2. 审计范围与证据

2.1 主要源码范围

  • 数据模型与规范化:core/models.py、core/config.py
  • 记忆价值评估:core/importance.py
  • 检索与重排:core/retrieval.py
  • Prompt 注入:core/injection.py
  • 服务编排与维护:core/service.py
  • SQLite 持久化:core/store.py
  • Bridge/Archivist:core/bridge.py、core/archive_contract.py
  • 运维合同:core/ops_domain.py、core/operations.py
  • 历史导入与 LivingMemory 迁移:core/chat_import.py、core/migration_livingmemory.py
  • 面板 HTTP API:page_api.py、pages/记忆面板/app.js
  • 测试:tests/ 全部测试模块

2.2 版本和验收证据

  • Q4 时间感知实现:提交 8d21776
  • Q4 VM 验收文档:提交 b227a7e
  • Q4 完整回归证据:提交 efd6fab
  • 现有验收记录显示:VM 服务 active、NRestarts=0、定向测试 20 passed、完整回归 155 passed, 1 warning,Archivist 发现运维版 1.6.2-ops.2。
  • 本次审计以源码为准;README 或验收文档中未能由源码、测试或实机证据互相印证的内容,均标记为“需补证”。

3. 整体架构与数据流

AstrBot 事件
  -> identity/session 解析
  -> classifier / time_intent / reply_chain
  -> timeline 原始事件
  -> summarizer / importance evaluator
  -> memories + relationship_edges + knowledge graph
  -> retrieval: 当前窗口 / 时间窗口 / FTS / 关键词 / 向量 / 图扩展
  -> visibility + ACL + mutable-fact collapse + source dedupe
  -> slot orchestration
  -> injection composer + temporal metadata
  -> LLM 请求

外部路径:
  Controller 事实 -> Q3 OpsFactRef/OpsEvent -> Bridge/人格层
  LivingMemory/QQ 历史 -> preview -> import batch -> 记忆/时间线/关系
  面板 -> page_api -> service/store -> 维护、导出、审查、修复

3.1 数据模型优点

MemoryRecord 已明确区分 occurred_at、created_at、updated_at、last_accessed_at,并保存 confidence、importance、visibility、lifecycle、review_status、supersedes_id 和 metadata(core/models.py:97-167)。这为时间感知、事实等级和后续版本链提供了正确基础。

SQLite 层启用 WAL、外键和 busy timeout,并有事务、连接恢复、删除级联和 revision 机制(core/store.py:35-45、core/store.py:184-236)。这是生产稳定性的良好基础。

4. 能力矩阵

能力 状态 证据/说明
长期记忆与时间线 已实现 MemoryRecord、timeline 表、阶段总结链路
重要性评估 已实现但需治理 core/importance.py:15-78,多维人格价值评分
置信度与审查队列 部分实现 字段和 review queue 存在,但缺少统一人工校准流程
分层检索 已实现 core/retrieval.py:878-1025,当前窗口/时间窗口/FTS/关键词/向量
Rerank/Embedding 已实现 配置、候选缓存、超时与降级路径存在
权限与 ACL 已实现 可见性、scope、session、group、ACL 复验和缓存失效测试
记忆去重 部分实现 fingerprint、mutable fact collapse、LivingMemory source dedupe;通用语义去重不足
冲突/替代 部分实现 supersedes_id、归档原因存在,但没有完整冲突图和当前版本查询
时间感知 已实现 core/temporal_context.py,动态 age/stale/relative label
Prompt 注入预算 已实现 slot 编排、compact 模式、字符上限;缺少 token 级质量度量
自然衰减 已实现但有误伤风险 core/service.py:3760-3880,按保护类型/标签/权重筛选
LivingMemory 迁移 已实现 preview、批次、修复路径和回滚能力存在
JSONL 迁移 已实现但规模有限 core/operations.py:303-631,64 MiB 上限、整批载入
运维事实合同 已实现 core/ops_domain.py:37-325,只校验不执行外部操作
运行时兼容 已实现 capability probe 与降级状态
面板管理 已实现 page_api.py:68-113,记忆、维护、导入、ACL、Bridge 路由
可观测性 部分实现 有耗时、Token、缓存、WAL、路径诊断;缺少质量指标

5. 已实现且建议保留的设计

5.1 时间与事实边界

Q4 的动态时间合同是正确方向:年龄、相对标签、跨日、过期原因在输出时计算,不写死到数据库;MemoryRecord.ensure_defaults() 只写入来源、时区、精度和估算标记(core/models.py:129-146)。build_temporal_memory_meta() 输出 age_seconds、age_label、relative_label、stale、time_source 等字段(core/temporal_context.py:166-197)。

Q3 规定 Controller 事实优先于记忆,且合同层不执行 Shell/SSH/Docker,是运维插件必须坚持的安全边界。

5.2 权限与跨窗口隔离

检索前做 visibility/ACL 过滤,缓存命中后还会重新读取当前记录并复验权限(core/retrieval.py:94-142)。跨窗口、群聊/私聊和 Bot 自我时间线已有专门测试,明显优于“把所有历史拼成一个 prompt”的实现。

5.3 存储一致性与可恢复性

删除记忆有级联和事务回滚测试;WAL、busy timeout、连接恢复、revision 和 embedding 表设计较完整。tests/test_store_consistency.py 与 tests/test_security_cache.py 已覆盖多项高风险边界。

5.4 迁移可逆性

LivingMemory 和历史聊天导入都带批次概念;JSONL 导入前备份,历史聊天有 rollback 路由。这使插件具备从旧生态迁移而不直接破坏主库的能力。

6. 重点欠缺与优化清单

优先级定义:P0=会造成严重数据/权限/生产风险;P1=会造成明显事实错误或维护成本;P2=质量、效率和产品体验提升。

P1-01:重要性分数承担了过多语义

  • 现象:一个 importance 同时承载长期价值、人格意义、内容类型、生命周期和部分新鲜度;检索又直接把 importance 乘以 0.55,同时叠加 confidence*0.25、recency、persona、dynamics(core/importance.py:49-78、core/retrieval.py:2191-2254)。
  • 根因:没有把“是否值得记住”“是否可信”“是否适合当前提及”“是否仍是当前事实”拆成独立可解释信号。
  • 影响:高重要但过期的服务状态可能仍有较强召回;低重要但与当前问题高度匹配的事实可能被压下去;分数变化难以向用户解释。
  • 建议:新增 memory_value、fact_confidence、mentionability、freshness_state 四个逻辑维度;保留旧 importance 作为兼容字段,检索改用可解释的分桶/门控。
  • 可实施性:可以立即做合同和评分单元测试,下一阶段再替换排序公式。

P1-02:人工重要性修改没有形成“覆盖层”

  • 证据:面板更新接口直接接受 importance、confidence、lifecycle 等字段(page_api.py:454-470);评估器在 calibrate() 中用 metadata.setdefault("base_importance", ...) 保存基线(core/importance.py:15-47)。
  • 风险:人工调整与自动重算的关系不清楚;重跑校准时可能继续使用旧基线,用户无法知道“手动 0.9”是否被模型覆盖或只影响一次。
  • 建议:增加 manual_importance_override、override_reason、override_by、override_at、calibration_version;UI 显示“自动分/人工分/最终分”。
  • 可实施性:中等,属于数据契约扩展,可先只写 metadata,无需立即迁移表结构。

P1-03:缓存命中后不重新计算时间状态和排序

  • 证据:服务把结果按 revision/config/query/time intent 缓存(core/service.py:1450-1516),命中后调用 revalidate_cached_results(),该函数只刷新记录并复验权限,不重新跑 _score()、过期门控或 temporal(core/retrieval.py:94-116;core/service.py:1618-1628)。
  • 影响:短 TTL 内跨过天气/服务状态 TTL 时,旧结果仍可能保留;缓存中的 score 和 reason 反映命中时刻而不是当前时刻。
  • 建议:缓存命中后至少执行:动态 stale 门控、age bucket 变化检查、可变事实 collapse;若 age bucket 或 stale 状态变化则重新排序或放弃缓存。
  • 可实施性:高,优先级高,风险低。

P1-04:冲突与版本链不完整

  • 现状:模型有 supersedes_id,维护归档会写入 decay_archived(core/models.py:127、core/store.py:4853-4888),检索对 mutable fact 有特定 collapse,但这不是通用事实冲突治理。
  • 欠缺:没有统一的 conflict_set_id、superseded_by、生效时间区间、冲突原因和当前版本查询;无法可靠回答“哪个是最新事实、旧事实为什么失效”。
  • 建议:为偏好、账号、地址、服务状态、计划等可变事实建立 conflict family;写入时检测同 owner/subject/key 的候选,旧版本标记 superseded,保留证据和替代关系;检索默认只返回当前有效版本,历史查询显式展开。
  • 可实施性:中高;先覆盖运维服务状态、计划和联系方式,避免一次性推广到所有文本记忆。

P1-05:衰减策略保护规则偏硬,缺少 dry-run 与人工复核

  • 证据:_decay_candidate() 通过类型、标签、权重、phase、visibility 直接跳过或纳入衰减(core/service.py:3760-3804);分组后达到最小条数才调用摘要(core/service.py:3718-3758)。
  • 风险:保护类型列表与 metadata 可能漂移;低频但重要的关系/创作片段可能因分类错误进入压缩;摘要失败时只能记录错误,缺少逐组重试和人工预览。
  • 建议:维护接口增加 dry_run=true,返回候选、排除原因、预计摘要内容和影响范围;实际执行使用确认 token;每个摘要保留 source_memory_ids、摘要版本和可逆恢复入口。
  • 可实施性:高,先做 dry-run 和报告即可明显降低运维风险。

P1-06:导入/导出路径适合中小库,不适合大库

  • 证据:JSONL 导出一次性读取最多 1_000_000 条记忆、时间线、关系和 ACL(core/operations.py:309-315);单文件上限为 64 MiB,导入读取后把全部记录放进内存(core/operations.py:15-17、602-631)。
  • 影响:库变大后内存峰值、导出耗时和失败重试成本明显上升;导入没有逐段 checkpoint,长任务中断后只能整体重来。
  • 建议:改为分页/游标式导出;JSONL 按块写入并带 SHA-256、记录数和 schema 版本;导入按 record_type 分批提交,保存 checkpoint,支持断点续传和单类回滚。
  • 可实施性:中等,适合下一阶段数据治理版本。

P1-07:迁移/导入的“选择哪一个源库”仍较隐式

  • 证据:LivingMemory preview() 枚举候选路径,import_data() 使用 preview["candidates"][0] 作为导入源(core/migration_livingmemory.py:72-95)。
  • 风险:同一环境存在多个旧库、备份库或测试库时,可能导入错误候选;用户只能在事后从批次记录发现来源。
  • 建议:预览返回候选排序依据、文件大小、mtime、表计数和健康检查;导入必须携带明确 source_path 或候选 ID,默认拒绝隐式第一项。
  • 可实施性:高。

P1-08:外部事实的 TTL 已有合同,但通用记忆检索没有统一 stale gate

  • 证据:Q3 OpsFactRef 有 expires_at/stale_after_seconds;Q4 temporal_context 能判断天气、服务状态等主题过期;但核心 _score() 主要使用 recency bonus,未把 stale 作为通用硬门控(core/retrieval.py:2237-2247)。
  • 影响:Bridge 出口能告诉调用方“过期”,主检索路径仍可能先选出再注入,取决于上层是否额外处理。
  • 建议:把 stale_policy 写入检索结果:exclude、background_only、allow_with_warning;运维状态、天气、人体状态默认为 exclude/background-only。
  • 可实施性:高,先在运维记忆类型和 topic_expiry 上启用。

P2-01:检索解释还不够面向运维排查

  • 现状:reason 字符串包含 hits、bm25、vector、importance、persona、recency(core/retrieval.py:2250-2254),但没有显示“为何被过滤、为何比另一个候选高、是否因 stale/冲突被降级”。
  • 建议:输出结构化 score_breakdown、filter_decisions、source_path、freshness_decision,字符串只作为兼容展示。

P2-02:注入预算以字符为主,缺少真实 token 预算与收益统计

  • 证据:注入器使用 max_chars、section 限额和 compact 模式控制包大小(core/injection.py:15-100)。
  • 欠缺:中文、代码、表格、不同模型 tokenizer 的实际 token 成本不同;没有记录每个 slot 的 token 占用、命中后是否被模型使用或造成重复。
  • 建议:增加 tokenizer 可选适配;至少记录估算 token、slot、被截断原因和最终响应任务类型,建立“每 1k token 带来的有效命中”指标。

P2-03:通用语义去重弱于特定场景去重

  • 现状:有 content fingerprint、mutable fact collapse 和 LivingMemory source dedupe,但不是通用语义级 merge;同一事实来自消息、导入摘要、人工笔记和外部插件时,可能保留多份。
  • 建议:建立 canonical fact key、来源优先级和合并策略;保留证据列表,不直接覆盖原文。

P2-04:关系阶段状态是文件级 JSON,缺少数据库治理

  • 证据:关系阶段状态从文件加载并原子替换保存(core/service.py:7465-7484)。
  • 风险:多进程/多实例同时写入时没有锁、版本号或合并策略;备份、迁移和按用户清理也不随 SQLite 事务统一完成。
  • 建议:迁移到 SQLite 独立表或至少增加 file lock、revision、冲突恢复和备份纳入范围。

P2-05:面板危险操作需要更强的二次确认与审计

  • 证据:页面直接暴露 /maintenance/clear_all、/maintenance/clear_scope、/memory/delete 等路由(page_api.py:68-113)。
  • 建议:所有清空/批量归档/导入/恢复操作使用 preview -> confirm token -> execute;记录 actor、scope、数量、备份路径、结果和失败原因;默认禁止跨 scope 的管理请求。

P2-06:测试偏合同和单元,缺少规模、故障和质量回归

  • 已有:时间合同、权限缓存、存储一致性、历史导入、运维合同、运行时兼容、面板回归等测试。
  • 欠缺:没有稳定的真实数据集评测召回 precision/recall;没有 10 万级 SQLite 压测、长时间衰减、导入中断恢复、多进程写入、WAL 膨胀、Embedding provider 慢/挂的故障矩阵。
  • 建议:建立脱敏 fixture 和基准集;每次评分/过滤规则修改自动输出 top-k 命中、过期命中、跨 scope 泄露、注入 token 和 p95 延迟。

7. 按阶段的优化队列

阶段 A:低风险、立即可做

  1. 缓存命中时重新检查 stale、age bucket 和 mutable fact。
  2. LivingMemory 导入必须显式选择候选源库。
  3. 维护增加 dry-run、候选排除原因和确认 token。
  4. 检索结果增加结构化 score_breakdown 与 freshness_decision。
  5. 面板危险操作增加 preview/confirm/audit。
  6. 为上述行为补齐单元测试和一条 VM 回归脚本。

阶段 B:事实治理增强

  1. 引入人工重要性覆盖层和版本化校准元数据。
  2. 建立 conflict family、superseded 状态、有效期和当前版本查询。
  3. 为服务状态、天气、身体状态、临时计划启用 stale gate。
  4. 将摘要压缩结果与源记忆建立可恢复的证据链。

阶段 C:规模化与质量度量

  1. JSONL 导入导出分页化、校验和、断点续传。
  2. SQLite 大库基准、WAL/备份/恢复演练和多进程写入测试。
  3. 脱敏召回基准集,追踪 precision@k、stale hit rate、conflict hit rate、cross-scope block rate、injection token p95。
  4. 评估将关系阶段状态迁移到数据库。

8. 不能在本次源码审计中确认的事项

  • 生产环境真实记忆规模、每日增长量和 WAL 膨胀曲线未在本地源码中确认。
  • 当前配置是否启用 Embedding/Rerank、各 Provider 实际 p95 和失败率,需要从 VM 运行指标或日志取证。
  • 真实用户数据下的召回准确率、过期事实命中率和注入收益没有基准集,不能由单元测试推断。
  • 面板路由是否由宿主统一鉴权、是否存在反向代理层 CSRF 防护,需结合 AstrBot/部署配置审计。

9. 最终判断

运维版记忆插件的核心方向是正确的:它已经不是简单的“聊天记录检索器”,而是一个带权限、时间、事实边界、迁移和跨插件合同的记忆中枢。

下一阶段的关键不是继续增加更多记忆类型,而是完成三件事:

  1. 让每次召回都能解释:为什么选中、为什么过滤、为什么过期、为什么当前不能当事实。
  2. 让每条事实都能纠错:谁写入、来自哪里、何时生效、被谁替代、如何恢复。
  3. 让维护操作可预演可回滚:先看影响,再确认执行,结果有审计,失败可恢复。

完成阶段 A 后,插件的生产可运维性会有明显提升;完成阶段 B/C 后,才适合把它作为长期的个人运维知识与陪伴记忆底座。

10. 参考文件

  • README.md
  • core/models.py
  • core/importance.py
  • core/retrieval.py
  • core/injection.py
  • core/temporal_context.py
  • core/store.py
  • core/service.py
  • core/operations.py
  • core/migration_livingmemory.py
  • core/ops_domain.py
  • core/archive_contract.py
  • core/bridge.py
  • page_api.py
  • tests/
  • 项目根目录:Q3_运维事件与数据模型说明.md、Q4_记忆插件时间感知改造要求.md、Q4_VM部署验收记录.md

本档案只记录源码审计发现,不自动修改业务代码;实施优化前应以阶段 A 的合同测试和 dry-run 结果为准。