KokoroMemo / 心忆项目机制介绍

之前已经发过 KokoroMemo / 心忆的项目介绍，这次就不重复聊“它是什么”，主要介绍一下工作原理

https://api.xiaoheihe.cn/v3/bbs/app/api/web/share?h_camp=link&h_src=YXBwX3NoYXJl&link_id=79e071d5b933

https://api.xiaoheihe.cn/v3/bbs/app/api/web/share?h_camp=link&h_src=YXBwX3NoYXJl&link_id=359571da85fb

前排提示，本篇为技术介绍文档，仅供有兴趣的盒友参考（现在退出还来得及

一、项目定位

KokoroMemo 不是一个聊天前端，而是一个中间件。

也就是夹在 AI 客户端和大模型 API 之间的本地代理，用来存储相关记忆信息。

（一）核心工作流程

KokoroMemo 配置好相关 AI 模型后，客户端直接用 OpenAI 兼容协议请求本地 14514 端口。

当请求经过 KokoroMemo 时，它会在中间做几件事：保存对话、维护当前会话状态、判断是否需要召回长期记忆、把必要的记忆注入上下文，然后再把请求转发给云端 AI 。

KokoroMemo 不是“再做一个聊天软件”，而是给现有 AI 角色扮演、AI 游戏、桌宠、类 SillyTavern 轻量客户端补上一层本地长期记忆系统。

（二）常见问题

1.跟酒馆啥区别？

压根就不是一个东西，酒馆是聊天前端，KokoroMemo 是中间件。

2.为什么不做酒馆插件？

酒馆插件无法脱离酒馆环境运行，也就无法应用到其他游戏上。

KokoroMemo 想做的是把长期记忆这个功能进行扩展，做成一个能够适配多种平台的功能。

而且实话说酒馆插件维护，本身就是个吃💩的过程，之前做这个插件踩的坑让我完全不想尝试第二次了

3.为什么不做 AstrBot 插件？

和上面问题一样，插件无法脱离本体运行，而且会受到本体的功能限制。

二、记忆分层

（一）全量处理的弊端

记忆处理不是大杂烩，并不能直接把聊天记录塞进上下文。

如果完全不做筛选直接全量处理，短期看很简单，但是长期必然会遇到如下问题：

1.上下文变脏

角色可能把玩笑、误会、过期设定甚至是幻觉都当成稳定记忆。

比如你发了一句“你是能当我妈妈的女人啊！”，然后这个玩笑写入了聊天记忆。

刚开始的时候可能 AI 还能意识到这是个玩笑，但是在几轮对话之后，AI 注意力降低，它只注意到了要“当妈妈”，然后开始劝你好好学习

2.召回不稳定

随口说一句话，也可能触发一堆不相关历史内容。

比如正在冲刺的时候发了一句“你这个🔥福瑞”，然后向量库把你们之前聊过的猫娘犬娘蜘蛛娘之类的话题全都召回了，接下来 AI 立马开始跟你讨论福瑞这个话题

3.内容不可控

AI 到底记住了什么，用户不一定看得见，也不一定能改。

简单来说就是变成黑箱了，很难针对性地进行改动，即使手动修改上下文也会很麻烦，你需要从一大堆聊天记录里面找出来特定内容

4.token爆炸

这个不用多说了，全量塞的话每一轮都会造成 token膨胀，最后会发现你一轮对话提示词里面90%都是聊天历史。而且上下文过多会导致注意力混乱，越往后面幻觉越严重。

（二）分层方案

KokoroMemo 会采用 3 层记忆分层方案来处理聊天记录。

1.热记忆：当前会话状态板

类似于酒馆记忆表格，可以理解成角色当前状态，它记录的是当前会话里正在发生的事情

比如：当前场景、角色情绪、正在进行的任务、短期承诺、当前关系状态、重要物品、用户刚刚强调的边界

举个例子，当前剧情是你们现在在雨夜的车站，青梅手里拿着一封没拆开的信。她发现了隔壁大姐姐给你的情书，所以她现在要去跟隔壁大姐姐对线。

这些信息对当前几轮对话很重要，但是不值得永久保存。

所以 KokoroMemo 会把这类内容放进“会话状态板”，在每轮请求前注入给模型。

这样模型下一轮回复时就知道：现在在哪里、角色是什么状态、当前任务是什么、刚才发生了什么，不用每次都靠完整聊天记录硬灌。

会话状态板

2.温记忆：长期记忆卡片图谱

这是提炼出来的记忆卡片，负责“长期稳定的事实”。

也就是说，真正需要跨会话保存的内容，会被整理成记忆卡片。

比如：用户希望角色称呼自己为“BAKA”、用户不喜欢过度病娇或威胁式表达、角色曾经答应下次一起去看烟花某条剧情线已经推进到某个阶段用户喜欢轻松撒娇型互动

这些内容不是一整段聊天记录，而是被整理成比较清晰的卡片。

比如一张记忆卡片可能长这样：

称呼：哥哥
类型：偏好
内容：用户希望 Yuki 在亲密场景中称呼自己为“BAKA”
标签：称呼、用户偏好、亲密互动
状态：approved

也就是把聊天记录提炼成可视化卡片，可以一眼看懂 AI 到底记住了什么，也能手动修改或拒绝。

记忆卡片

当然，记忆之间也有关系，不只是“相似”

KokoroMemo 里的记忆卡片不只是孤立保存，还可以有关系。

比如：A 支持 B、A 约束 B、A 与 B 冲突、A 替代 B、A 延续 B、A 属于 B……

举个例子，系统记住了：用户喜欢角色轻微吃醋。

但同时也记住了：用户不喜欢威胁、自伤、病态控制。

这两条就不是简单的“相似关系”，第二条应该约束第一条。

也就是说，当角色想表现“轻微吃醋”时，提示词汇提醒模型：可以吃醋，但不要演变成病娇式威胁、自伤或病态控制。

这就是记忆图谱的意义，不只是帮角色“想起来”，还要帮角色“想对”。

记忆图谱

3.冷记忆：语义向量索引

这是语义索引，负责“需要时去找旧事”，主要用于检索。

比如用户说：你还记得我们X月X日约好的事吗？

这句话本身没有说明“约好的事”是什么，这时候 KokoroMemo 就需要去长期记忆里找相关内容。

它会根据当前发言、角色、会话和已有状态，去检索相关记忆卡片、摘要、标签和图关系。

比如可能召回：之前约定，等穹妹长大就结婚……然后再把这条记忆注入提示词。

这样模型回复时就能接上：当然记得，我们现在去领证吧！

这里有个重点，语义索引的 LanceDB 向量库其实不是记忆本体，真正可信的长期数据保存在本地 SQLite 里。

语义索引只是为了方便搜索，即使坏了也可以通过 SQLite 数据库进行完整重建。

同样重建向量库这个功能也可以用在不同模型上，比如更换其他 Embedding 模型。

三、风控机制

Retrieval Gate：不是每轮都翻旧账

KokoroMemo 里有一个比较关键的机制叫 Retrieval Gate，也就是“召回门控”。

它负责判断：这一轮到底需不需要查长期记忆？

因为不是每句话都值得召回。

比如用户只是说：嗯、继续、好、抱抱……这种时候，当前状态板通常已经足够了。

没必要每轮都查向量库，也没必要把一堆旧记忆塞进上下文。

但如果用户说：你还记得我们第一次见面吗？上次你答应我的事情呢？之前我说过我不喜欢什么？那个角色后来怎么样了？这种就明显需要长期召回。

所以 KokoroMemo 的流程大致是：

接收聊天请求 ➡ 识别用户、角色和会话 ➡ 读取当前会话状态板 ➡ 先注入当前状态 ➡ Retrieval Gate 判断是否需要长期召回 ➡ 如果需要，就检索记忆卡片、图关系和语义索引 ➡ 筛选、去重、排序 ➡ 把少量高相关记忆注入上下文 ➡ 转发给真实大模型 ➡ 返回回复 ➡ 后台更新状态板并提炼候选记忆

这样可以减少两个问题：不必要的检索开销、不必要的上下文污染

角色要记得你，但不能每句话都翻旧账。

本项目含人量约10%，核心代码均由AI贡献

除核心方案工作流全程人工制作，其余均由 AI 参与。

截至 v0.10.0 版本，项目代码量约 3 万行，其中古法编程约 500 行

项目 LOGO 及 GUI 设计由 Gemini 3.1 Pro 实现，后端架构设计、审核由 GPT 5.5 实现，核心功能由 Claude Opus 4.7 实现，部分 BUG 检修由 MiMo V2.5 Pro 及 DeepSeek V4 Pro 执行，累计消耗 token 约 12 亿……token 燃烧器

关于视频教程，因目前的测试版功能变动较快，所以会当 v1.0 稳定版发布的时候制作