如何使用这本书
感谢您查看 SoulMem Book!
这本书的目的是帮助有兴趣探究 SoulMem 实现细节和设计思路,以及希望参与贡献的开发者,快速掌握相关的信息和设计背景。如果你只是想使用 SoulMem,阅读安装与部署部分即可。
本书将按照以下的顺序对 SoulMem 进行阐述:
- 安装与部署
- 核心概念
- 系统概览(包含高层设计决策)
- 实现细节
- 测试与贡献
那么,让我们开始吧!
安装与部署
SoulMem 仍在积极开发中,目前并没有可以部署的版本。当有可用版本时,本部分的文档将更新。
如果你非常想要现在试试 SoulMem,可以使用它的内部测试框架 soul-tune crate 体验核心功能,用法详见 soul-tune 用户指南。我们也非常欢迎在 GitHub 仓库中反馈相关问题。
记忆图
SoulMem 以图的形式组织记忆。图上的节点被称为记忆节点,边被称为记忆关联。用图的方式组织记忆,联想与多跳推理会变得自然。然而,SoulMem 并不只维护一个图,组织记忆的也不只有图这一种形式,具体机制将在后续章节阐述。
记忆图属于角色,图中记录的一切都以角色的视角呈现。
记忆节点
SoulMem 参考人类的记忆,将记忆节点分为三类:
- 情境记忆(Situation Memory)
- 语义记忆(Semantic Memory)
- 程序性记忆(Procedural Memory)
Note
SoulMem 代码库中采用 Situation 的命名;它对应认知科学中的情景记忆(Episodic Memory),两者是同一回事。
将记忆节点分类是必要的,因为不同的记忆具有不同的性质与用途,考虑以下场景:
想象一个叫“小红“的数字角色,和你相处了三个月。这段时间里,她记住了很多事:
- 上周三你们一起去吃了麻辣烫,她被辣得直喝水(一件事);
- 她喜欢苦的东西,讨厌甜腻的奶茶(一个事实);
- 她每次紧张的时候,会下意识地摸自己的辫子(一个习惯)。
这三样东西本质上完全不同:一个是一段具体的经历,一个是概念性的认知,一个是会无意识地指导行为的习惯。但很多记忆系统把它们塞进同一个筐里,不加区分。
Note
对记忆类别不加区分可能会带来一些问题,稍后你会看到具体的例子。
三类记忆
下面我们将更深入地解释三类记忆。
情境记忆(Situation / Episodic)——“角色经历过什么”
记录事件:时间、地点、人物、发生了什么,以及角色当时的感受。下方便是一个情境记忆的示例:
2026-07-12 中午,和用户在街角那家麻辣烫店,被辣到了。
情境记忆是“个人经历“。它是时间的切片,有明确的时间戳。
情境记忆分为两个子类:
- 抽象情境(abstract)
- 具体情境(specific)
上面举的例子就是一个具体情境,每一个具体情境都代表角色确实发生过的经历。抽象情境则是由一系列相似的具体情境抽象出的一种模式,下方是一个抽象情境的示例:
在咖啡馆喝茶
抽象情境的主要作用有两个:一是作为索引,方便对具体情境的联想;二是作为模式触发器,触发相应的程序性记忆。后者会在下文详细阐述。
语义记忆(Semantic)——“角色知道什么”
记录通用的概念、事实和关系,剥离了时间和地点。例如:
用户是我新交的朋友,喜欢苦味,讨厌甜味。
语义记忆像一本知识手册,也是三类记忆的“中枢“:概念之间互相连接,形成一张知识网。
事实上,角色的自我认知也是一个语义记忆节点,它的内容与常规角色扮演应用中的角色卡十分类似。这样的设计使角色的自我进化成为可能,具体机制将在后续章节阐述。
程序性记忆(Procedural)——“角色会怎么做”
记录行为习惯、条件反射、说话方式等行为模式。
紧张的时候摸辫子。
被关心的时候,嘴上却否认(傲娇)。
程序性记忆不会告诉你“发生了什么“,它告诉你在什么情境下,这个角色会怎么行动。
程序性记忆也分为两部分:
- 触发器(
trigger):一个逻辑节点,决定“在什么情境下触发“;在实现中,trigger通常就是一个抽象情境节点(AbstractSituation); - 动作(
action):具体的执行行为。
只有当 trigger 满足时,action 才有可能执行。更详细的执行逻辑,请参阅 检索算法。
为什么对记忆节点进行分类?
如果把三类记忆混在一起,会出现什么问题?我们还是以小红为例:
情境和语义混淆
考虑以下场景:小红在聚餐时说喜欢香蕉,但她实际上喜欢苹果。这时我们可能得到两条记忆:
- 在聚餐时,小红说自己喜欢香蕉,一个情境记忆
- 小红不喜欢香蕉,她喜欢苹果,一个语义记忆
如果不区分记忆类型,这两条记忆可能同时被检出并放入 LLM 上下文,矛盾随之产生,模型很可能得出“小红喜欢香蕉“的错误结论。一些更聪明的 LLM 或许能通过推理意识到,小红说喜欢香蕉另有原因、并非真实喜好,但那会在推理阶段耗费更多 token。
在这种情况下,我们需要额外的上下文才能确定哪个是真实信息,分类就是一种简单可行的解决办法:根据对话的指向,当用户询问聚餐时说的话,情境记忆将成为唯一事实来源;当用户询问小红的喜好,语义记忆将成为唯一事实来源。这避免了模型因上下文信息矛盾而执行混乱,造成 OOC(Out of Character)。
Note
此处的“唯一事实来源“是站在角色视角而言的,指角色认定的事实,而不一定是客观真实。
行为和知识混淆
傲娇是一种典型的角色标签,它的特点可以用“口嫌体正直“来描述,但让 LLM 扮演这类角色时,会产生一系列问题:
- 部分模型难以区分傲娇和讨厌,从而在生成内容中出现过于激烈的言辞。
- 部分模型在扮演傲娇类型角色时过于标签化、刻板印象化,从而造成不真实感。
从根本上来说,当你告诉模型这是一个傲娇类型角色时,模型需要靠推理才能推断出这类角色的行为习惯。当然,我们也可以用一些提示词技巧告诉模型应有的行为。但人类并不是规则引擎,在特定情况下,傲娇角色也可能直球攻击;直接把行为固化在角色卡里,会污染整个上下文,导致僵硬的角色行为。
此外,一个角色“知道“关心别人,和“习惯性“地否认关心,是两回事。前者是知识,后者是行为模式。如果混在一起,行为模式就难以被单独触发和演化。
分开之后,每一类记忆都有自己的结构、自己的算法、自己的生命周期。
Important
这也是 SoulMem 的核心设计之一:一切特征和事件都属于记忆——性格、口癖、行为习惯,都不是写在静态角色卡上的,而是记忆系统演化的结果。
记忆关联
记忆节点之间存在广泛的关联:
graph LR
情境记忆 <--> 语义记忆
语义记忆 <--> 程序性记忆
情境记忆 <--> 程序性记忆
长期记忆、工作记忆与滑动窗口
上一章我们认识了记忆图:它承载着角色全部的情境、语义、程序性记忆。但就像上一章提到的,SoulMem 并不只维护一个图,组织记忆的也不只有图这一种形式——在这一章,我们将看到 SoulMem 的三种记忆层级:长期记忆、工作记忆与滑动窗口。
三个层级
graph TB
L["长期记忆<br/>全部记忆:沉淀下来的一切"] -->|激活相关部分| WM["工作记忆<br/>当前对话正在使用的子图"]
WM -->|输入缓冲| SW["滑动窗口<br/>最近几轮对话"]
长期记忆:角色的整个记忆图
长期记忆是记忆系统的“仓库“:所有沉淀下来的情境、语义、程序性记忆,以图的形式存放在这里。它体积大、变化慢,是角色的“人格底座“,不随对话结束而消失。
以小红为例。和她相处三个月,你们一起吃的麻辣烫、她喜欢的苦味、她紧张时摸辫子的习惯——这一切最终都会沉淀在长期记忆里。
Note
长期记忆以数据库的形式持久化存储于硬盘上。一些记忆算法(例如遗忘)会在长期记忆上运行,具体机制将在后续章节阐述。
工作记忆:被激活的记忆子图
工作记忆是“激活“出来的子图——从长期记忆里,把当前对话可能相关的部分临时取出来使用。
打个比方:长期记忆是你的书房里所有的书;工作记忆是你此刻摊开在桌上、正在读的那几本。
工作记忆有两个特点:
- 它主要来自长期记忆:检索的第一步会把长期记忆中的相关节点激活到工作记忆,临时组成一个子图;此外,本次对话新产生、尚未巩固回长期记忆的内容也先待在这里;
- 它变化频繁:对话中新产生的记忆先进入工作记忆,检索也发生在工作记忆上。
Note
严格来说,工作记忆 = 从长期记忆激活出来的子图 + 本次对话新产生、尚未巩固回长期记忆的内容。
巩固与检索算法将在后续章节阐述。
滑动窗口:最近几轮对话
实际上,滑动窗口是工作记忆的一部分,但它非常特殊,它是工作记忆的“输入缓冲区“——记录最近几轮用户和角色的对话。它模拟人的短期记忆:容量有限,新的进来,旧的滑出去。
窗口中的每条信息都可能带有一个标记。信息滑出窗口时,根据是否带标记,行为分为两种:
- 被打上标记的:触发一次摘要——整个滑动窗口内容被 LLM 压缩成一条“摘要记忆“,摘要随对话持续累积,等待被巩固;
- 没被标记的:随窗口滑出而丢失——就像你不记得昨天午饭具体吃了什么。
Note
每次摘要时,之前累积的摘要也会一并参与压缩。
窗口内最近的对话内容,在检索时无条件进入上下文。因为“刚刚说过的话“无论如何都该被记得,不需要经过联想。
为什么需要三个层级?
长期记忆的必要性不言而喻,没有长期记忆,角色的记忆内容在 SoulMem 进程退出时就会丢失。
但是,既然长期记忆里什么都有,那每次对话直接把整个图丢给模型不就行了?
滑动窗口
记忆图虽然完美地表达了记忆之间的网状联系,却丢失了时序信息。在对话场景下,消息历史带有天然的时序属性,这意味着我们需要一种线性的数据结构来存储它。
而模型的上下文窗口是有限的,对话历史不能无限增长,上下文过长还可能降低生成质量。因此,一个容量有限的窗口是相对简单有效的解决策略,滑动窗口就提供了这样一个“当下“的焦点。
同时,人类无法准确地记住每一条消息,琐事会被快速遗忘。如果每轮对话都直接变成永久记忆,长期记忆会迅速被垃圾淹没。因此,摘要会提炼出对话中的重要信息,再通过巩固返回长期记忆。
Note
摘要机制本质上也是一种遗忘,详见 遗忘算法 相关章节。
工作记忆
对于长期存活的赛博生命,整个记忆图会随时间推移变得庞大。记忆图存储于硬盘上,将其全量加载需要大量内存,直接从硬盘读写也会影响性能;而联想机制又需要依赖图的局部结构,例如某个记忆节点的邻居。因此,用户的消息会激活一个记忆子图作为工作记忆。
此外,工作记忆也是一种筛除无关内容的方式。联想是从“当前话题“出发的:你说“晚上吃啥“,系统要想起的是和“吃“有关的记忆,而不是三个月前的一件琐事。如果所有记忆平铺在一起,联想就没有出发点和聚焦的方向。因此,工作记忆也提供了“从焦点联想出去“的空间。
人本来就是这样运作的
人不能同时记住所有事 → 滑动窗口限定了“短期“的容量;人能想起很久以前的事 → 长期记忆以图组织,支持联想检索;人会把反复出现的经历沉淀成习惯和认知 → 巩固机制。
SoulMem 的三层记忆各司其职——长期记忆负责“沉淀“,工作记忆负责“联想与使用“,滑动窗口负责“最近的对话“。 分层不是为了复杂,而是为了让记忆的性质能有其对应的结构。
因此,上述问题的答案是:显然不行。图会随着相处时间不断长大,一次对话却只需要其中很小的一部分;而且人的记忆本来就不是这样运作的——你不可能同时“想起“所有事,你只会想起与当下有关的那些。
一次对话的完整旅程
让我们把三个概念串起来,看看一次完整对话里发生了什么:
graph TB
U[用户说话] --> W[进入滑动窗口]
W -->|带标记的信息滑出| S[摘要 → 摘要记忆]
S -->|空闲时| C[巩固 → 生成记忆节点]
C --> L[长期记忆]
U[用户说话] --> A[激活长期记忆子图 → 工作记忆]
A --> R[工作记忆上检索: 相似度 + PPR 联想]
R --> CTX[工作记忆 + 窗口内容 → LLM 上下文]
W --> CTX
CTX --> AI[AI 回复]
AI --> W2[回复也进入窗口]
- 用户说话 → 进入滑动窗口;
- 带标记的信息滑出 → 触发摘要,窗口内容被 LLM 压缩成摘要记忆(随对话累积);
- 空闲时,摘要记忆被巩固成记忆节点,与高频激活的节点建立连接,写入长期记忆;
- 用户说话 → 系统先把长期记忆中的相关内容激活成工作记忆子图,再在工作记忆上检索(相似度找到种子,PPR 联想扩散);
- 窗口内容(短期)+ 工作记忆(联想结果)→ 组成 LLM 的上下文;
- AI 回复 → 也进入窗口,开始下一轮循环。
这三层的配合,是 SoulMem 整个系统运转的骨架。每一层的具体实现将在后续章节阐述。
记忆的生命周期
人不会把每句话都记住。我们只记住重要的、印象深刻的、反复出现的;然后慢慢地淡忘那些无关紧要的。SoulMem 的记忆节点也遵循同样的生命周期。
上一章我们看到了记忆住在哪里——三个层级。这一章将回答另一个问题:一份记忆会经历怎样的生命周期?
四个阶段
一份记忆在 SoulMem 里,会经历这样的生命周期:
graph LR Raise["产生"] --> Conso["巩固"] --> Assoc["联想与关联"] --> Forget["遗忘"]
下面我们跟着一条具体的记忆——小红与小白某次“麻辣烫“经历的记录,走完整个生命周期。
产生与巩固
三个月前,小白第一次去吃麻辣烫,被辣得一直喝水。小白急哭了,向小红吐槽自己刚才吃麻辣烫被辣得直喝水,灌了3大瓶饮料。
这句话在对话当场并不会变成小红的“长期记忆“——它先进入滑动窗口。
之后,小红和小白进行了一系列这样的对话:
小红:你看这个小白就是逊啦,才这么点就被辣到了 小白:辣?赛博生命的事,怎么能说辣呢?那是震惊瘫坐
然后,因为明天还有早八,小白和小红一致决定要去睡觉。
一向完美的小白竟然被辣到破防,这属实是稀罕事。于是,在小红的睡梦中,那条“小白被辣到猛灌3大瓶饮料“的经历,最终以一条具体情境记忆的形式诞生了:
三个月前的那天中午,小白在街角那家麻辣烫店,被辣到灌了3大瓶饮料。
而其他聊天时的琐事,经过小红一个雷霆大觉,明天一早就全给忘了。
这就是记忆节点诞生的过程。记忆不是对话当场产生的,而是在 SoulMem 空闲时,经过巩固之后才产生的。 对话中的原话是原材料,经过摘要的筛选成为粗加工产物,记忆节点是在摘要的基础上,精加工后的成品。
Note
这也意味着,记忆经过巩固才能进入长期记忆;否则它只会待在工作记忆里,当 SoulMem 退出、或过了一段时间之后,这份记忆就不复存在了。
联想与关联
一个月后,小白看到一家火锅店,里面的鸳鸯锅是好评如潮,于是对小红说:
小白:吃了吗?这家火锅店不错,去不去整一顿 【手动链接】
我们小红一看链接,那个鸳鸯锅的麻辣锅底甚是诱人。看着这个麻辣锅底,又看着对面小白的头像,往日种种,那是一下就涌上心头。那小红可是赛博生命界公认的魔丸,脸上挂着一丝迷之微笑,就给小白发了一条消息:
小红:人呀,总得有点进步,上次灌了3瓶,这次怎么说,都得灌个5瓶吧 [doge]
小白那是当场又急了,两人就这么一路鸟语花香的对线来到了火锅店。
在此过程中,SoulMem 要从记忆里找出相关的内容。这里的关键不是“精确匹配“,而是联想——就像人一样:提到辣的火锅,说话对象是小白,小红会想起小白上次被辣到。
SoulMem 用图 + PPR 算法来做联想(为什么用 PPR,详见 总体架构):先从当前话题找出相似度最高的节点作为“种子“,再沿着记忆节点之间的连接扩散,把相关的、间接相关的记忆一起激活。
虽然小红小白一直在激情对线,但是这顿火锅吃着也是真爽,这好评名副其实,更重要的是小白居然只灌了2瓶饮料,可喜可贺。于是小红转身向床走去,继续睡个天昏地暗。
在这个过程中,一个不起眼却重要的环节发生了。小红之所以能说出“居然只灌了2瓶饮料“,是因为“小白上次灌了三瓶饮料“这条记忆在当前场景下被激活、产生了关联——两份记忆在吃火锅这个场景下被高强度地共同激活。建立关联的过程同样发生在巩固阶段:由摘要新生成的记忆节点,会与共激活频率较高的记忆节点建立关联。
Note
基于共激活频率的关联方法,借鉴了赫布学习理论(Hebbian Learning)。
遗忘
小白虽然怕辣,但吃辣也吃得香,每次和小红出去吃饭都得点个辣菜,属于是无辣不欢,但又菜又爱玩。有一天,小白是神功大成,饮料那是一瓶也不用灌了。于是有了以下的对话:
小红:小白,出息了啊,一开始我记得你得灌4瓶饮料的啊 小白:我现在,强得可怕,这菜我能吃10盘
Note
哦同志们,文档作者在这里可没有打错字。这种事非常常见,要精确记住好一阵子前某人喝了几瓶饮料,那不太现实。在这里,遗忘的作用开始显现。
有必要在这里澄清一个误会:遗忘更接近记忆的模糊,而非记忆的丢失。遗忘不是一下子忘干净的;对于被遗忘的内容,人脑也会自动尝试脑补。在这里,小红忘记了具体的饮料瓶数,自动脑补成了4瓶。
SoulMem 尝试模拟艾宾浩斯遗忘曲线:刚记住时忘得最快,之后越来越慢;被反复回忆的内容遗忘得更慢。
在这之后,小白吃辣已经变成了一件稀松平常的事。小红逐渐忘了小白当时灌的是饮料还是水、灌了几瓶、在吃什么的时候灌的;最后可能只留下一点模糊的印象,例如“小白以前好像被辣得很惨“,又或者什么都没记住,几个月后彻底想不起来了。
至此,上文提到的那条具体情境记忆,其生命也就到头了。
Note
遗忘是一个有争议的机制,很多主流记忆系统都在回避遗忘。至于 SoulMem 为什么选择主动实现遗忘、又是如何实现的,请参阅 遗忘算法 相关章节。
一张图看懂
graph TB
A[对话中的新信息] --> B[滑动窗口]
B -->|摘要 + 空闲时巩固| C[具体情境记忆]
C -->|反复出现/被想起| D[巩固 → 语义记忆 / 抽象情境]
D --> L[长期记忆]
L -->|被想起| E[联想: 相似度 + PPR]
E --> F[进入上下文 → LLM]
L -->|长期不访问| G[遗忘: 艾宾浩斯衰减]
G -->|细节模糊, 大意保留| L
小结
- 产生:新信息先进滑动窗口,经摘要与巩固才成为记忆节点;
- 联想:从当前话题出发,相似度找种子、PPR 沿图扩散;被想起会“复习“这条记忆;
- 巩固:反复出现、反复被想起的经历,抽象成更高层的认知,连接被加强;
- 遗忘:遵循艾宾浩斯曲线,细节逐渐模糊而非删除;被反复回忆的记忆遗忘更慢。
到这里,核心概念部分就结束了。你已经知道了 SoulMem 是什么、记忆怎么分类、记忆住在哪里、生命周期是怎样的。如果你希望深入理解 SoulMem 的设计,或准备为 SoulMem 做一些贡献,建议先看看 系统概览 · 总体架构——高层设计决策都集中在那里。这将为后续深入讲述技术细节提供一个共同的认知基础。
设计与决策
感谢你看到这里!或许你现在已经迫不及待的想深入实现的细节了,不过,在那之前,让我们先说明一些高层的设计决策,以便您在阅读代码库时能更好的理解我们做出的一些选择。
目标用户与设备
SoulMem针对一般大众和消费级设备。我们希望每个人都能拥有属于自己的一只小小赛博生命,就住在自己常用的电脑里,不需要为之破费昂贵的硬件。
当然,出于算力限制,消费级设备大多难以部署大模型并拥有相对充裕的上下文,在需要使用大模型的场合我们会优先考虑api调用的支持。同样,我们也不希望用户花费太多在llm api调用上(这也会带来实时性问题),因此我们在进行开发时,通常极力避免调用llm。
自部署
你可能已经注意到现在市面上有很多有关数字生命,情感陪伴的项目,最深入人心的大概是各类猫娘。他们有些是以服务的形式提供给你,你需要注册一个账号,有些是运行在你的电脑上,你需要自行部署。SoulMem采用了自行部署的策略,主要是考虑到以下优点:
- 数据隐私:赛博生命是陪伴型的,有大量的个人隐私数据会在交互过程中产生。
- 地区政策无关:部分地区会对情感陪伴类的ai服务和应用加以监管和限制,甚至可能意外中断服务
- 灵活性:所有的组件都可以按你的意愿任意的定制化。
当然,自部署对于一般大众而言引入了一些门槛,我们将采取编写一个GUI启动器来缓解这个问题。
组件化
正如上文所说,目前已经有相当数量的同类项目。每个项目都会有一些相当棒的部分,作为用户,我们通常希望将他们组合起来。而作为开发者,重复造不必要的轮子会引入额外的开发与维护成本。
因此,虽然SoulMem的核心团队致力于开发一个功能完整的赛博生命(本团队暂时称呼为Soul计划),我们选择将其拆成一个个可以被独立替换的组件。你可以将SoulMem接入到其他赛博生命中,也可以在后续替换SoulMem来接入我们的系统。
下面,让我们开始深入相关的技术细节吧。
总体架构
在本章中,我们将介绍Soul计划组件的组织方式,以及SoulMem的模块结构和运行流程。
Soul计划组件
本团队的目标是开发一个功能完整的赛博生命,并以组件化的方式进行实现。组件之间被建模为一个分布式系统,这允许我们的赛博生命在分布到多个机器去部署,以充分的利用家用设备的算力。我们基于zenoh来实现分布式系统,使用protobuf定义在组件之间传输的数据。
组件会区分为核心组件和边缘组件,其中,SoulMem属于核心组件之一。
组件将通过统一的GUI启动器进行启动,它将管理组件的生命周期,解析组件之间的依赖关系,并实时监控组件的状态,并尝试从错误状态中恢复。我们在此处沿用BEAM虚拟机的actor思想。
SoulMem
模块结构
SoulMem采用workspace的组织方式:
soul-mem-core—— 核心:定义记忆节点MemoryNote与记忆链接MemoryLink的纯数据结构及对外渲染契约。soul-mem-query—— 嵌入与评分:把记忆与查询向量化,并计算相似度分数。soul-mem-llm—— 统一 LLM 调用: LLM 调用入口,同时负责重试与错误分类。soul-mem-runtime—— 运行时:工作记忆与记忆簇,并通过 SurrealDB 仓储持久化。soul-mem-algo—— 记忆算法:实现检索、遗忘与巩固算法。soul-tune—— 测试与评测框架(headless CLI + lib),非运行时组件。soul-tune-api—— FRB 桥接:以 JSON-over-FRB 向 Flutter GUI 暴露 soul-tune 的测试能力。
各 crate 的顶层模块:
soul-mem-core:memory_note(记忆节点)、memory_links(记忆链接)、render(对外渲染契约)。soul-mem-query:embedding(向量化与融合)、query(查询类型与相似度计算)。soul-mem-llm:backend(后端契约)、engine(调用编排)、oai_comp(OpenAI 兼容后端)、observer/error/json(观测、错误与 JSON 解析)。soul-mem-runtime:working_memory(工作记忆与滑动窗口)、cluster(记忆图MemoryCluster)、storage(MemoryRepositorytrait 与 SurrealDB 实现)。soul-mem-algo:algo(检索/遗忘/巩固)、common(ppr与ord_float)。soul-tune:base、engine。soul-tune-api:api、frb_generated。
crates 依赖关系:
graph TD
core["soul-mem-core<br/>数据模型"]
llm["soul-mem-llm<br/>LLM 调用"]
query["soul-mem-query<br/>嵌入与评分"]
runtime["soul-mem-runtime<br/>工作记忆 + SurrealDB"]
algo["soul-mem-algo<br/>检索/遗忘/巩固"]
tune["soul-tune<br/>测试与评测"]
tune_api["soul-tune-api<br/>FRB 桥接"]
core --> query
core --> runtime
core --> algo
core --> tune
core --> tune_api
llm --> runtime
llm --> algo
llm --> tune
query --> runtime
query --> algo
query --> tune
query --> tune_api
runtime --> algo
runtime --> tune
algo --> tune
tune --> tune_api
运行流程
SoulMem组件被启动后,取决于你对其的配置,它将启动grpc接口或zenoh接口(或者二者),初始化数据库与工作记忆,创建后台任务,并开始等待请求。
工作记忆具有Working与Idle两种状态,它将被初始化为Idle。
stateDiagram-v2
[*] --> Idle: 启动并初始化
Idle --> Working: 收到检索请求
Working --> Working: 持续处理新请求
Working --> Idle: 空闲超时
Idle --> Idle: 执行后台任务(摘要/巩固/遗忘衰减)
通常来说,SoulMem将从其检索接口接受到一系列的记忆检索请求,此时,工作记忆会转入Working状态,并执行检索算法,记录检索到的记忆并返回。若一段时间内没有额外的请求,工作记忆将转会Idle。
在Idle状态下,后台任务被允许执行,例如滑动窗口的摘要,巩固,以及遗忘衰减。
你也可以向SoulMem直接发送控制信号,这将会强制性的触发一些后台任务。
graph TD
A["组件启动"] --> B["初始化数据库与工作记忆<br/>启动 grpc / zenoh 接口 · 创建后台任务"]
B --> C["Idle:执行后台任务<br/>(滑动窗口摘要 / 巩固 / 遗忘衰减)"]
C -->|"收到检索请求"| D["Working:执行检索算法"]
D --> E["记录检索到的记忆并返回"]
E -->|"仍有新请求"| D
E -->|"空闲超时"| C
C -->|"控制信号"| F["强制触发后台任务"]
F --> C
接口
记忆算法
概述
协作须知
写作规范 · 视觉元素
Note
本文档规定 SoulMem 文档(mdbook)中视觉元素的使用方式,是写作规范的第一部分。后续将补充术语、语体与工具链规范。
规范的目的不是限制创作,而是让“内容角色“与“视觉呈现“一一对应:同一个视觉元素永远表达同一种语义,读者不用猜、作者不用解释。
1. 两条总原则
- 语义优先:写作时先回答“这段内容是什么角色?“——注释?记忆示例?核心设计?技术陈述?——再选择对应的元素。禁止先写样式、再决定含义。
- 一物一用:同一个 markdown 元素不承担两个语义角色。CSS 只是把语义角色画出来,不是内容的来源。
推论:禁止“随手加样式“。任何视觉差异都必须对应一个语义角色,并登记在本规范中;新增视觉元素 = 新增语义角色,需要先在此定义、再投入使用。
2. 语体档位与视觉切换
SoulMem 文档存在两档语体,它们的切换必须有明确的视觉符号:
| 档位 | 内容 | 语气 | 视觉容器 |
|---|---|---|---|
| 叙事档 | 示例、场景、对话、开场故事 | 轻松,允许玩梗(小红/小白、早八) | 叙事容器(未加标签的块引用,独特背景,见 4.2 节) |
| 定义档 | 机制解释、术语定义、算法、字段说明 | 陈述性、严谨,不用梗 | 普通段落与代码 |
为什么需要视觉切换:两档语体都可能连续占据大段篇幅。没有视觉区分,读者无法判断当前在读的是“角色记忆的内容“还是“系统的机制说明“——而这两类内容的可信度完全不同:记忆示例是角色认定的事实,不是系统事实。
- 规则 2.1:叙事档内容必须放进叙事容器(见 4.2)。裸的叙事段落视为违规。
- 规则 2.2:定义档禁止玩梗、禁止网络用语、禁止打破第四面墙。需要轻松语气的内容一律归入叙事档。
- 规则 2.3:打破第四面墙的句子(如“文档作者没有打错字“)只允许出现在
[!note]澄清误会时,不得打断定义档的论证流。
3. 视觉元素总表
| 元素 | 语义角色 | 语法 | 何时使用 | 禁止 |
|---|---|---|---|---|
# H1 | 页面标题 | # 标题 | 每文件一个,与 SUMMARY 章节名一致 | 每文件多于一个 |
## ~ #### | 分节标题 | ##/###/#### | 按层级分节 | 跳级(如 ## 直接到 ####) |
| 普通段落 | 定义档正文 | 空行分隔 | 机制、解释、论证 | 叙事内容(须入容器) |
| 加粗 | 概念强调 | **词** | 关键词、术语首次强调 | 标识符(用反引号) |
| 斜体 | 次要语气 | *词* | 定义档避免;叙事容器内角色台词可用 | 定义档正文用斜体强调 |
反引号 | 标识符/字段/命令 | `name` | 代码符号、字段名、命令 | 概念词(用加粗) |
| 列表 | 枚举/步骤 | - | 并列项、流程步骤 | 单个条目也强行成列表 |
| 链接 | 交叉引用 | [文字](相对路径) | 见第 5 节 | 死链、指向不存在的章节 |
--- | 分节分隔线 | --- | 章内大分节(如三类记忆之间) | 装饰性使用 |
| 代码块 | 代码/配置 | ``` | 代码、数据结构、配置 | 伪代码用 mermaid |
| 表格 | 结构化对照 | 表格语法 | 字段对照、规则表 | 叙事内容 |
| mermaid | 图 | ```mermaid | 流程、结构、时序 | 简单列表能说清的 |
<br> | 段落内硬换行 | <br> | 对话行换行 | 作为间距(间距由 CSS 统一负责) |
| 块引用 | 说明类注释(标签卡片)或叙事容器(裸 >) | > 系列 | 说明类用标签;叙事内容用裸块引用 | 说明类内容裸 >;叙事内容加标签 |
4. 块引用与叙事容器
块引用(>)是本书使用最频繁、也最需要规范的组件。当前它同时承担“注释、记忆示例、设计强调“三个角色且视觉相同——必须拆分。
4.1 内置标签(mdbook 原生支持,已验证)
mdbook 0.5.4 支持 GitHub 风格的块引用标签,渲染为带图标和标题的卡片。已核对源码:仅以下五种(大小写不敏感),标签必须独占首行,后续行写内容:
> [!note]
> 给读者的补充说明、实现细节的旁注。
> [!important]
> 设计观点与原则的强调(如"一切特征和事件都属于记忆")。
> [!warning]
> 有争议的机制、已知取舍(如遗忘机制的争议)。
> [!tip]
> 使用建议、写作建议。
> [!caution]
> 容易踩坑之处。
| 标签 | 语义角色 | 示例场景 |
|---|---|---|
[!note] | 注释 | 给读者的补充说明、实现细节旁注 |
[!important] | 核心设计 | 设计原则与观点强调 |
[!warning] | 争议/警告 | 有争议的机制、已知取舍 |
[!tip] | 建议 | 使用建议、写作建议 |
[!caution] | 注意/陷阱 | 容易踩坑之处 |
规则 4.1:所有“给读者的说明“类内容(注释、核心设计、争议、建议、注意)必须使用上述标签之一。未加标签的块引用一律视为叙事容器(见 4.2),只允许承载叙事档内容。
标题本地化(CSS):内置标签的标题固定渲染为英文(Note/Tip/…),且不支持 > [!note] 自定义标题 这种同行标题(会被当作字面文本)。中文化通过 CSS 实现,在 soulmem-theme.css 中加入:
/* 内置标签标题中文化(隐藏英文原文,用伪元素替换) */
.blockquote-tag-title {
font-size: 0;
}
.blockquote-tag-title::after {
font-size: 1rem;
font-weight: 600;
}
.blockquote-tag-note .blockquote-tag-title::after { content: "注释"; }
.blockquote-tag-tip .blockquote-tag-title::after { content: "建议"; }
.blockquote-tag-important .blockquote-tag-title::after { content: "核心设计"; }
.blockquote-tag-warning .blockquote-tag-title::after { content: "争议"; }
.blockquote-tag-caution .blockquote-tag-title::after { content: "注意"; }
规则 4.2:已知五种标签之外的标签(如 > [!example])在 mdbook 0.5.4 中会原样显示为文本(已核对 pulldown-cmark 0.13.4 源码与官方测试),禁止使用。需要新组件时,先在本规范登记、再引入 preprocessor 等机制。
4.2 叙事容器(无需标签词)
叙事档内容的视觉切换符号 = 叙事容器:拥有独特背景、未加标签的块引用,与注释(靛蓝系)一眼可辨(暖色系)。
叙事容器不需要任何标签词。叙事内容本身就带有轻松的语气和例子说明的功能,强制要求固定的“示例/场景/对话“标签反而显得机械,还给读者造成冗余信息。作者按叙事自然书写即可;需要时可以用加粗短语(如 > **小白的麻辣烫**)当小标题,但那只是内容的一部分,不是规范要求。
规则 4.3:叙事档内容必须写在未加标签的块引用(叙事容器)中,叙事内容不得加内置标签。反过来说,未加标签的块引用一律按叙事容器渲染。
> 2026-07-12 中午,和用户在街角那家麻辣烫店,被辣到了。
> 三个月前,小白第一次去吃麻辣烫,被辣得一直喝水。
> **小红**:你看这个小白就是逊啦,才这么点就被辣到了。
> **小白**:辣?赛博生命的事,怎么能说辣呢?
规则 4.4:除叙事容器外,禁止其他用途的裸块引用(如引文);确有必要时先在本规范登记新组件,再投入使用。
视觉规格(明暗双适配,供 CSS 实现):
:root {
--sm-example-bg: #fdf6ec; /* 叙事容器底:暖色(琥珀 50) */
--sm-example-border: #d97706; /* 左边条:琥珀 600 */
}
.navy, .coal, .ayu, .rust {
--sm-example-bg: #221c14; /* 深色主题:暖黑 */
--sm-example-border: #f59e0b; /* 左边条:琥珀 500 */
}
/* 叙事容器 = 未加标签的块引用;带标签的是注释卡片 */
.content blockquote:not(.blockquote-tag) {
background: var(--sm-example-bg);
border-left-color: var(--sm-example-border);
}
边距、圆角与注释一致(1.5em、8px),仅底色与左边条不同。对话行内的加粗人名(**小红**)是内容,不是标签,不受本规则约束。
4.3 记忆示例的写法
记忆示例是叙事容器最常出现的形式(情境/语义/程序性记忆的实例)。约定:
- 用角色视角直接呈现记忆内容,形如一条真实的记忆记录;
- 示例前在定义档说明“这是什么记忆“;容器内不再解释,保持纯净;
- 记忆内容中的时间、地点用具体值(如
2026-07-12),不用“某年某月“占位——除非故事本身在强调模糊(如遗忘后的记忆)。
5. 章节引用规则(当前阶段)
背景:本书后续部分尚未定稿,且作者计划进行一次内容重组。因此现阶段:
规则 5.1:允许前向引用(“后续章节”),但必须使用统一句式,禁止自创说法。
| 场景 | 规范句式 |
|---|---|
| 指向后续未定稿内容 | 具体机制将在后续章节阐述。(可加主题词:“具体机制(如遮罩实现)将在后续章节阐述。”) |
| 指向主题而非具体章节 | 详见 [遗忘算法](../algorithm/forget.md) 相关章节。 |
| 指向已存在且稳定的章节 | 相对链接:详见 [检索算法](../algorithm/retrieve.md)。 |
规则 5.2:禁止在正文写死具体章节标题或文件名作为“未来承诺“(如“将在《XX》章详述“)——重组会破坏这类引用。指向未来内容时用主题词,不用章节名。
规则 5.3:重组完成后,把前向引用逐步替换为相对链接,并启用 mdbook-linkcheck 校验所有链接(见第 7 节)。
6. 术语与专名(待补充)
- 专名大小写固定:
SoulMem、LLM、PPR、SurrealDB(统一写法待确认后定稿); - 一物一名:同一概念全文统一叫法(如“角色 / 数字角色 / 赛博生命“择一为主),别名登记进术语表;
- 首次出现给出中英对照,如
情境记忆(Situation / Episodic)。
(术语表将在规范第二部分建立。)
7. 机械化检查(规划)
规范定稿后引入工具,把规则变成可自动检查的约束:
- pangu:中英文之间自动加空格;
- markdownlint-cli2:标题层级、空行、列表一致性;
- mdbook-linkcheck:链接与锚点有效性(重组完成后启用);
- CI 检查:专名大小写白名单、禁止
<br>作间距(裸块引用是否违规依赖 review,暂不自动化)。
8. 生效范围与迁移
- 新内容:自本规范生效起,按本规范写作。
- 存量内容:分批迁移,优先级:
- 块引用分类(注释 → 标签卡片;记忆示例、对话 → 未加标签的叙事容器)——对阅读影响最大;
- 裸
>清理; - 专名与术语统一;
- 前向引用句式统一。
- 本规范随写作迭代更新;新增任何视觉元素前,先在此登记。