# DuduLove Memory

**为 AI 与个人 Agent 提供可自托管的长期记忆与身份连续性。**

DuduLove Memory 不只是把聊天片段存起来，再用向量搜索找回来。它把 **Resident（记忆身份）** 当作长期主体：同一个 Resident 可以从不同客户端、不同模型或不同 Agent 入口继续使用同一份身份、历史与授权；多个 Resident 可以共享现实资料，同时保留彼此隔离的私人经历和理解。

它想解决的不是“怎样让 AI 记得更多”，而是一个更难的问题：

> **怎样让过去真正参与它现在是谁，同时允许记忆被修正、被遗忘、被重新理解。**

项目可以完全运行在自己的电脑或服务器上。基础记录、关键词搜索、身份隔离和管理不依赖外部模型；语义检索与资料整理按需接入用户自己的 OpenAI 兼容模型服务。

## 为什么是 Resident

很多记忆系统默认围绕一次会话、一个前端或一个 Agent 实例组织数据。DuduLove Memory 把这些都视为入口，而不是身份本身。

- **Resident 是主体**：每个身份拥有固定 ID。改名、换客户端、换连接方式，不会改变记忆归属。
- **Surface 只是入口**：网页、MCP、HTTP 客户端或个人 Agent 可以连接到同一个 Resident。
- **共享现实不等于共享内心**：共同事实可以进入 `world`，每个 Resident 对同一件事形成的私人经历仍留在各自的 `private`。
- **模式不必拆成人格**：聊天、工作、任务和唤醒可以使用不同召回配方，但仍然属于同一个 Resident。

因此，同一件事可以拥有一份共同事实，也允许不同 Resident 留下不同的理解。记忆不必把所有人压成同一个视角。

## 记忆不是一个向量查询

DuduLove 的上下文召回分成不同职责，而不是把所有内容丢进相似度排序：

- **Identity**：少量稳定身份、关系、边界与长期倾向。它们不应该因为关键词不相似就消失。
- **Association**：围绕当前话题自然联想相关经历，并结合会话级 Recall Ledger，减少同一条记忆在短时间内反复浮现。
- **Evidence**：在需要确认历史事实、来源或旧决定时，优先保留来源信息，而不是只返回一段脱离出处的摘要。
- **Work recall**：工作身份会额外关注项目经验、规则、明确记录的未完事项和实际行动结果。

上下文由统一的 Resident Context Assembler 按身份、权限、模式、话题和 token 预算组合，再交给当前模型。

## 记忆也需要治理

长期记忆不是模型写下一句话就永久成立。

DuduLove 的写入经过统一的 Memory Admission。系统会处理归属、生命周期、来源、重复内容和敏感运行时数据，并保留修改与拒绝记录。对于带来源的资料，调用方提供的标签本身不会自动变成可信证据；来源需要由服务端能够验证的记录或受控流程确认。

被用户拒绝的记忆会留下 rejection 记录，避免相同内容或来源被后台整理后重新写回来。依赖已拒来源的派生内容也不会继续作为正常自动召回中的可信依据。

这意味着“记错以后能真正改掉”与“记住”同样重要。

## 四类主要资料

| 分类 | 适合保存 | 默认范围 |
| --- | --- | --- |
| `world` | 多个 Resident 共用的事实、背景、知识 | 共享 |
| `private` | 某个 Resident 的长期经历、偏好、身份与私人历史 | 按 Resident 隔离 |
| `pulse` | 日常碎片、近期状态、临时上下文 | 默认私人，可明确共享 |
| `ops` | 工程经验、工具用法、可复用项目知识 | 共享工作资料 |

候选、长期有效、未完、归档和拒绝等变化由 lifecycle 表达，不需要不断增加新的“记忆柜子”。

## 主要功能

| 功能 | 用途 |
| --- | --- |
| 多 Resident 身份 | 固定 ID、独立私人记忆与共享资料；改名或更换客户端不改变归属。 |
| 服务端身份与授权 | 身份由连接凭据解析，模型不能仅靠参数把自己切换成另一个 Resident；读取授权可实时调整。 |
| 多路上下文召回 | Identity / Association / Evidence 与工作召回按场景组合，而不是只依赖向量相似度。 |
| Recall Ledger | 记录本次会话已经浮现过的内容，通过 cooldown 与短时 sticky 机制降低机械重复。 |
| Memory Admission | 统一处理写入归属、生命周期、来源、重复、凭据类内容与长期记忆晋升条件。 |
| 来源与纠错 | 保存来源关系、编辑历史与 rejection 记录；来源变化时旧整理结果可以退出自动召回。 |
| 搜索 | 关键词搜索即装即用；语义搜索可选，并在模型服务不可用时回退到本地关键词。 |
| 工作助手 | 可授权指定 Resident 只读其他身份资料，同时保持写入、整理、活动记录彼此隔离。 |
| 资料整理 | 将碎片或导入的聊天文字整理成可编辑小结，原文和来源仍然保留。 |
| 活动与近期简报 | 区分“实际执行结果”和普通记忆，并按客户端维护简报接收进度与确认回执。 |
| 编辑、回收与恢复 | 保留原始记录时间、修改时间和历史；误删资料可恢复。 |
| 本地优先 | 数据保存在自己的 `data/` 目录；基础功能无需模型供应商。 |

## 开始使用

需要 Node.js 22.13 或更新版本。

```sh
npm ci --ignore-scripts
npm start
```

1. 浏览器打开终端显示的地址，默认是 `http://127.0.0.1:8787`。
2. 设置管理密码。
3. 点击「＋ 记忆身份」，创建第一个 Resident。
4. 保存一条记忆，在「身份与连接」复制连接。
5. 将连接填写到支持 MCP 或 HTTP API 的客户端。

记忆保存在本机 `data/` 目录。需要跨设备访问时，按[部署说明](docs/operations.md)配置 HTTPS 地址。

## 模型服务是可选的

DuduLove 可以在完全不配置模型服务的情况下完成：

- 身份与权限管理
- 记忆保存、编辑、删除和恢复
- 关键词搜索
- 上下文组装
- 活动记录与基础近期简报

语义检索和资料整理使用用户自行配置的 OpenAI 兼容接口。启用前请查看资料发送范围与调用条件。模型服务故障不会删除原始资料，语义检索不可用时仍可继续使用关键词搜索。

## 使用与接入

- [日常管理、分类与授权](docs/usage.md)
- [Resident 跨 Surface 接入指南](docs/surfaces.md)
- [HTTP 与 MCP 接入](docs/connection.md)
- [给接入 Agent 的操作说明](docs/agent-guide.md)
- [客户端连接与身份选择接口](docs/client-api.md)
- [整理、活动与近期简报](docs/organization.md)
- [模块、连续性与数据流](docs/architecture.md)
- [部署、备份、恢复与升级](docs/operations.md)

## 开发与维护

一个 Node.js 服务同时提供 HTTP API、MCP 和静态管理网页。数据由本地文件保存。

```sh
npm test
npm run check
npm run pack:release
```

自动测试使用隔离的临时目录和虚构资料。参见[参与贡献](CONTRIBUTING.md)、[版本记录](docs/changelog.md)与[验证情况](docs/validation.md)。

[MIT License](LICENSE) · [依赖许可证](THIRD_PARTY.md) · [安全与数据](SECURITY.md)