Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

如何使用这本书

感谢您查看 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[回复也进入窗口]
  1. 用户说话 → 进入滑动窗口;
  2. 带标记的信息滑出 → 触发摘要,窗口内容被 LLM 压缩成摘要记忆(随对话累积);
  3. 空闲时,摘要记忆被巩固成记忆节点,与高频激活的节点建立连接,写入长期记忆;
  4. 用户说话 → 系统先把长期记忆中的相关内容激活成工作记忆子图,再在工作记忆上检索(相似度找到种子,PPR 联想扩散);
  5. 窗口内容(短期)+ 工作记忆(联想结果)→ 组成 LLM 的上下文;
  6. 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(MemoryRepository trait 与 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. 两条总原则

  1. 语义优先:写作时先回答“这段内容是什么角色?“——注释?记忆示例?核心设计?技术陈述?——再选择对应的元素。禁止先写样式、再决定含义。
  2. 一物一用:同一个 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. 生效范围与迁移

  • 新内容:自本规范生效起,按本规范写作。
  • 存量内容:分批迁移,优先级:
    1. 块引用分类(注释 → 标签卡片;记忆示例、对话 → 未加标签的叙事容器)——对阅读影响最大;
    2. 裸 > 清理;
    3. 专名与术语统一;
    4. 前向引用句式统一。
  • 本规范随写作迭代更新;新增任何视觉元素前,先在此登记。

soul-tune