通用机器人记忆核心及框架适配器，当前版本 0.1.1。核心独立运行，通过统一接口接入各机器人框架。此次修复问句误写、检索顺序、话题混入和引用来源问题，详见 版本记录。
提供本地 HTTP 服务和 Node 模块入口，Python 与 Node 机器人可共享同一核心。支持原消息来源、本人事实、新旧版本、遗忘禁记、本人解锁、过期和会话隔离。
- 核心与适配器实现已完成：提供独立记忆核心、HTTP 服务、Node/Python 客户端，以及 AstrBot、NoneBot2、Koishi 和 QQ 官方机器人四条接入路线。
- 自动验证已完成：2026-10-14 通过 58 项 Node 核心/HTTP/映射测试及 22 项 Python 检查。测试范围见 验证记录。
- 真实框架联调待补充：四条路线已提供适配代码和接入示例，尚未完成在真实框架、QQ 与模型调用链中的端到端联调。
围绕消息来源核验、本人事实管理和遗忘控制，项目形成三种交付形态。本仓库公开通用版，三种形态的实现边界与取舍见 交付形态说明。
| 形态 | 分发与使用 | 实现边界 |
|---|---|---|
| 配套版 | 本地自用 | 插件配合指定版本宿主补丁，保留消息来源及工具回执；随宿主升级维护补丁 |
| 市场版 | QQ Agent 插件市场已上架；上架当日下载量 40+ 次 | 使用宿主扩展接口，在插件内完成兼容检查与来源证据管理，不覆盖宿主源码 |
| 通用版 | 本 GitHub 仓库开源 | 核心独立运行，通过框架适配器接入；自动测试已通过，真实框架联调待补充 |
市场数据由维护者提供，统计截至 2026-10-07，市场版于当日上架。下载次数不代表独立使用人数；市场版的使用与验收情况不代表通用版四条路线已经实测通过。三版围绕相同能力目标演进，并非同一安装包，也不承诺数据直接互换。
| 框架 | 本仓库提供 | 安装后的自动能力 | 验证情况 |
|---|---|---|---|
| AstrBot | 插件入口、配置、消息映射、默认 LLM 请求钩子 | 本人陈述记录、命令、答前本人事实召回 | 合成事件与钩子测试；真实框架/QQ 联调待完成 |
| NoneBot2 + OneBot v11 | 可加载插件、协议映射、memory_for() |
记录和命令；AI 插件需调用 memory_for() |
合成协议事件测试；真实联调待完成 |
| Koishi 4 | 中间件、配置、memoryFor() |
记录和命令；AI 插件需调用 memoryFor() |
合成会话映射测试；真实联调待完成 |
| QQ 官方机器人 | 腾讯 botpy 群、C2C、频道消息桥 | 在现有 SDK 回调调用 memory_for() |
合成 OpenID、时区与引用事件测试；真实联调待完成 |
这不是“下载后自动兼容任何机器人”的单一插件。AstrBot 插件、NoneBot 插件和 Koishi 插件的目录不同；没有统一 AI 钩子的框架还需在其 AI 插件中接一处调用。QQ 官方平台是协议，AstrBot 的 QQ 官方适配器可以先走 AstrBot 路线。
Node.js >=20；核心与服务无第三方 npm 依赖。第一次启动，在 PowerShell 中运行：
cd D:\universal-memory-keeper
$env:MEMORY_TOKEN = node -p 'require("node:crypto").randomBytes(32).toString("hex")'
# 将生成的令牌填到框架插件配置；此命令只生成你本机使用的凭证。
node server.mjs默认监听 127.0.0.1:8765，数据写在本项目的 data/。重启服务时使用同一个令牌；可用启动脚本设置环境变量，但不要提交含令牌的脚本。可选变量：MEMORY_PORT、MEMORY_DATA_DIR。容器内插件访问宿主需要自行配置地址与安全转发，不能把容器自身的 127.0.0.1 当成宿主。
核心采用单进程、每会话 JSON 原子写入。单文件上限64MiB；大群长期运行或多进程部署需要替换存储接口。不要让多个进程同时写同一数据目录。
每个已接入框架都使用同样的维护命令：
我的饮料偏好是绿茶
我的饮料偏好改为红茶
/memory search 饮料偏好
/memory history 饮料偏好
/memory note 工作安排 | 我的工作安排是周三下午开会
/memory forget 饮料偏好
/memory unlock 饮料偏好
/memory status
自动记忆仅识别明确的“我的事项是/改为某值”陈述；其他事实需用 note 指令，仍以本条本人原文为依据。自然中文的明确遗忘/解锁也可识别；“忘记这件事”等模糊指代不会执行。默认检索只返回当前发送者的核验事实，历史模式不会绕过禁记。
普通问句不会自动写为事实。相关历史默认从近到远；例如“我最初说的饮料偏好是什么”才从最早版本开始。完整话题不以部分关键词代替；可用 /memory history “饮料偏好”，截止到2026-10-06 明确话题和日期。截止结果保留历史状态，不改变当前有效事实。
引用消息的结构化 ID 单独核验，保留原作者。实际引用一条已经记录的文字消息并发送“只复述原句”时，注册的处理路径直接返回原文；来源未记录或不可用则说明无法核验。它不会自动补齐所有机器人发出的消息；不能仅凭一张引用卡片推断核心库里已有原消息。
遗忘停止本核心的召回和再记忆，不物理删除原消息。解锁后重新开放仍有效的旧事实；期间重提不会自动解除禁记或写入新事实。没有文本明确日期时不猜过期时间；日期截止和检索日界用北京时间。
详细步骤与 AI 接口例子见 框架安装。整个 AstrBot 插件目录包含入口、配置和独立客户端，复制到 AstrBot data/plugins/astrbot_plugin_universal_memory_keeper/ 后重启加载；不要将仓库根目录当成 AstrBot 插件。
AstrBot 首版在默认 LLM 请求钩子中每轮清空本次请求旧上下文，仅保留当前问题与经核验的本人记忆。这样群成员旧回答和禁记话题不会从框架历史直接补回；代价是普通多轮闲聊上下文减少。聊天数据库不会由插件删除。其他 AI 插件若另行注入旧记忆、人设事实或工具结果，需要自行执行相同来源政策；本版不保证拦截任意模型措辞、其他插件注入或自定义调用链。
node --test tests/core.test.mjs tests/http.test.mjs tests/retrieval.test.mjs
python -B tests/test_adapters.py本仓库58项 Node 核心/HTTP/映射测试及22项 Python 检查（21项合成适配器检查、1项真实环回HTTP客户端检查）。测试不发真实 QQ 消息、不调用模型、不读取真实聊天。
源码入口、信任边界和存储契约见 源码说明，实际验证记录见 验证范围。核心公开方法也可用于程序内接入，适配器是已认证事件与核心之间的桥。
本仓库不包含真实聊天、真实记忆库、账号配置或 API 密钥。运行时数据和环境文件被 .gitignore 排除。
本项目采用 MIT 许可证，版权与许可条款见 LICENSE。各框架本身遵循其各自许可证。