织忆 WaveMemory 使用文档

01织忆是什么

织忆是一个跨平台的 AI 记忆工作区。你和 AI 的每次协作，都会沉淀进一个记忆库——一棵由 Markdown 文件组成的目录树。AI 读写这些文件来"记住"事情，你也可以直接查看、编辑、回滚它们。

它由三部分组成：

• AgentFS 虚拟磁盘：所有记忆、会话和设置都存放在一个基于 SQLite 的虚拟文件系统里，与真实磁盘隔离，跨平台行为一致。
• AI 运行时：负责对话、工具调用、上下文压缩、本地检索、工作流和子代理。
• Memory MCP 服务：把记忆以标准 MCP 协议提供给外部 Agent，例如 Claude Code、Codex 和 ChatGPT。

02安装

安装包内已经带有本地嵌入模型，所以体积比普通聊天客户端稍大——换来的是开箱即用的离线语义检索。

无头服务

在 Linux 服务器上解压无头服务包并启动后，用浏览器访问它提供的地址即可使用完整界面。适合放在家里的小主机上常驻，作为同步中心和 Memory MCP 服务。

03配置模型

首次启动后打开 设置 → 模型配置，点击「添加」创建服务商：

1. 选择服务商类型：OpenAI、Anthropic、Google、DeepSeek、智谱、OpenRouter、Ollama，或任意 OpenAI 兼容接口。
2. 填写 API 地址与 API 密钥。密钥只保存在本机的虚拟磁盘中。
3. 从远程列表勾选要添加的模型，或手动填写模型 ID、上下文窗口、最大输出 Tokens，并标注能力（推理、工具、视觉）。
4. 在聊天输入框下方切换模型。

每个会话还可以在右上角 会话参数 中单独设置温度、Top P、Top K 与最大回复长度，只对当前会话生效。

04记忆库

左侧「记忆」页列出你的所有记忆库，交互方式和聊天软件的联系人列表一样：每个记忆库是一个独立的"分身"，工作、生活、不同项目之间互不干扰。

新建与导入

• 点击 + → 创建新记忆，输入唯一的记忆名称和会话名称。
• 选择 使用已存在的记忆，可以把设备上已有、但不在列表中的记忆文件夹重新导入。
• 长按或右键记忆库，可以置顶、复制记忆、复制记忆名称。

父子记忆

可以把一个记忆库挂到另一个记忆库下，它会以 @名称 的形式出现在目录里。适合把大项目按模块拆成多个记忆库，在总项目里统一检索。挂载的是引用而不是副本，修改会同时体现在两边。

05文件、笔记与脑图

文件管理器

「文件」页可以浏览当前记忆库的目录树：新建、重命名、剪切、复制、删除，上传导入本机文件，或选择多个目录合并导出。Markdown 文件支持编辑与预览，代码块、表格与 Mermaid 图都能直接渲染。

笔记与脑图

「笔记」页把知识组织成可以层层深入的脑图：

• 右键（移动端长按）节点，可添加子节点、Markdown 文档或子脑图；双击打开，拖动画布浏览。
• Markdown 编辑器支持编辑 / 预览 / 分屏三种模式，可直接粘贴图片。
• 打开 笔记 Agent 面板，可以让 AI 直接整理当前脑图：生成子节点、重命名或移动节点、新建文档并写入内容。

06记忆规范与自进化

"AI 应该怎样整理记忆、用什么语气回复你"本身也是文件，保存在每个记忆库的 .env 目录中：

设置中内置了几套预设：Wiki 记忆、编程代码记忆格式、自增长索引记忆格式，也可以完全自己写。

允许自进化

在 会话参数 → 允许自进化 打开后，AI 的文件工具可以读取并修改当前记忆库 .env 里的规范与风格提示词。它会把你的习惯、明确提出的要求、踩过的坑写进去，之后的每个会话都会自动加载。外部 Agent 也能通过 update_myself 方法触发这一过程。

07Loop、工作流与子代理

三种记忆形态

提示词工作流

把固定流程或好的经验用自然语言写下来，就成了可复用的工作流。工作流分全局级与记忆级（记忆级可以覆盖全局的启用状态），并可以分别设为：

• 默认发送工作流——每次发送消息时执行；
• 默认 query_memory 工作流——外部 Agent 查询记忆时执行；
• 默认全局上下文构建工作流——buildContext 时执行。

快捷发送与子代理

常用提示词可以存进 快捷发送 列表，一键发出。复杂任务可以拆给 Subagent 并行处理；在 会话参数 → Subagent 中可以为子代理单独指定一个模型，不开启时沿用主模型。Loop 过程与子代理状态都有独立存储，中断后可以恢复执行。

08版本与回滚

记忆库的每一次修改都会形成版本记录。打开会话右上角的版本历史面板可以：

• 逐个查看版本及其变更的文件与差异；
• 恢复版本：整个记忆库回到某个时间点；
• 撤销版本变更：只撤回某一次修改，保留之后的其他改动；
• 手工添加版本：在大改之前自己打一个存档点。

外部 Agent 通过 MCP 直接写文件时，也遵循同样的规则：先调用 backup_memory_before_update 备份，写完后调用 commit_memory_update 提交。

09记忆核查与定时任务

AI 会出错，错误的记忆会被反复引用。会话参数 → 记忆核查 用来控制这个风险：

1. 打开「启用记忆核查」，在「记忆主目录」中勾选需要核查的文件夹（默认关闭）。
2. 之后 AI 写入这些目录的内容会自动带上未核查标签。
3. 点击「启动核查」，AI 会逐条核对事实，确认无误后移除标签。可以追加自定义核查提示词，与系统预设拼接执行；「任务历史」中可以查看每次结果。

在 会话参数 → 定时 中可以把核查（或任何提示词）设成周期任务：设置执行周期、有限次数或无限执行。桌面端的定时任务与其他后台会话会显示在 后台任务 面板里，可以随时查看输出或停止。

10本地 RAG

织忆内置 multilingual-e5-small 嵌入模型（ONNX 量化版），向量保存在本机 SQLite（sqlite-vec）中。桌面端与移动端都在本地完成嵌入与检索，中英文均可。

• 在 会话参数 → Embedding 数据库 中可以为当前记忆库创建索引，或清空后重建。
• 文件按内容哈希去重，未变化的文件不会重复计算。
• 开启「首条消息携带目录树」后，每轮新对话的第一条消息会附带当前工作目录的文件树，帮助模型快速定位。
• 外部 Agent 可以通过 memory_filesystem_query_rag 使用同一份索引（需开启外部 AI 虚拟磁盘）。

11上下文构建与记忆索引

上下文构建（buildContext）

针对一个问题，让 AI 通读记忆并输出一份执行上下文：背景、相关逻辑、工作机制、经验教训、风险与注意事项、建议步骤。适合在开始一个新任务之前使用。可以在会话参数中为当前记忆库自定义构建提示词。

记忆索引上下文

在聊天界面右上角打开 上下文构建 面板，开启「记忆索引上下文」并选择若干目录（可跨记忆库，多选）。织忆会把它们合并成一份只读 Markdown 快照：

• 文件顶部是树状索引，每个文件标注正文在快照中的起止行号；
• 外部 Agent 可以按索引分段读取，跨多个上下文窗口消化大量记忆；
• 快照文件出现在已挂载磁盘的 temp_memory/ 目录下（macOS 桌面端），每次构建原子覆盖同一个文件。

上下文压缩

对话变长时，织忆会自动压缩较早的历史，保留决策和关键结果。输入框旁的用量指示会实时显示当前上下文窗口的占用。

12Memory MCP

Memory MCP 把本地记忆以 MCP（Streamable HTTP）协议对外提供。在 设置 → Memory MCP 服务 中启用：

同一页面可以查看实际暴露的方法列表和每一次调用记录。健康检查：GET http://127.0.0.1:3901/mcp/health，返回 "ok": true 即表示服务在运行。

方法

调用示例

curl -s http://127.0.0.1:3901/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "query_memory",
      "arguments": {
        "memory_name": "my-project",
        "query": "上次对登录模块做了哪些修改？",
        "wait_for_result": true
      }
    }
  }'

curl -s http://127.0.0.1:3901/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
       "name":"quick_update_memory",
       "arguments":{"memory_name":"my-project",
                    "updatecontent":"登录接口统一改为返回 401，前端据此跳转登录页。"}}}'

MCP 客户端（如 Claude Desktop、Cursor）中添加一个 HTTP 类型的服务器，地址填 http://127.0.0.1:3901/mcp 即可。返回体可能是 JSON，也可能是 text/event-stream，标准 MCP SDK 都能处理。

局域网访问

同一局域网内的其他设备可以用 http://<本机局域网 IP>:3901/mcp 访问。不要把这个端口直接暴露到公网；需要从外网访问时，请使用下面的外网远程访问。

13接入 Claude Code / Codex

在 设置 → Memory MCP 服务 → 第三方客户端中的 Skill 功能启用 里，可以一键把 wavememory-generic Skill 写入本机的 AI 编程工具：

• Skill 告诉 Agent 如何连接服务、先做健康检查、只调用 tools/list 中真实存在的方法，以及必须使用精确的 memory_name。
• 织忆只管理自己创建的 Skill 与 MCP 登记：遇到同名但不是织忆创建的目录或配置，会跳过而不是覆盖。关闭时也只删除自己创建的部分。
• Codex 新登记的 MCP 服务器通常需要重启 Codex 或新开任务后才会出现。

启用后，在 Claude Code 里直接说"查一下 my-project 记忆里关于部署的约定"，Agent 就会通过 Skill 调用 Memory MCP。

14外网远程访问

想让 ChatGPT 等云端 AI 使用你本机的记忆，但又不想开放端口？在 设置 → Memory MCP 服务 → 外网远程访问 中开启：

1. 客户端会连接官方桥接服务，并得到一个固定且唯一的连接地址（…/{客户端 UUID}/mcp）。这个地址不在设备间同步。
2. 点击「一键生成访问密码」。密码默认 30 分钟后失效，可以调整有效期，或在明确需要时设为永不过期。
3. 勾选要开放的记忆库，点击「一键复制连接信息」，把地址、记忆名称和访问密码交给云端 AI。
4. 云端 AI 先用访问密码调用 open_space 打开记忆空间，再调用 Memory MCP 方法。

• 桥接服务只转发数据；是否允许访问由你本机的客户端校验。
• 重新生成、停用密码或关闭远程访问后，旧密码以及它打开的记忆空间立即失效。连续输错密码会被限流。
• 「外部调用记录」只记录方法名、记忆名称与结果摘要，不记录参数和密码。
• 单个会话的右上角也有「远程访问」入口，可以一键复制本会话的连接配置。

15在访达中挂载（macOS）

在 设置 → 挂载设置 中填写磁盘显示名称并点击「挂载磁盘」，整个虚拟文件系统就会作为一块磁盘出现在 Finder 中，你可以用任何编辑器打开记忆文件。

• 默认只读：可以浏览和复制，不会修改织忆的数据。
• 单独打开「允许读写」后，在磁盘中的修改会直接写回织忆（包括设置和记忆文件），请谨慎开启。
• 修改名称或读写权限前需要先卸载。挂载状态会被记住，下次启动自动恢复；在设置中主动卸载则停止自动挂载。
• 单个文件传输上限 256 MiB。挂载服务只监听本机回环地址。

把记忆文件夹链接进项目

在会话右上角 会话设置 → 挂载 中点击「新增挂载」：左边选记忆里的一个文件夹，右边选本机的一个文件夹。织忆会在本机文件夹里创建一个同名链接，指向磁盘中的记忆目录。删除挂载只移除链接本身；遇到同名文件或文件夹时会拒绝创建，不会覆盖。

自动挂载目前支持 macOS 桌面端；Windows、Linux 与移动端不显示该入口。

16跨设备同步

同步采用中心化方式：一台电脑（或无头服务）作为主机，其他设备作为客户端接入。打开 设置 → 设备同步：

1. 在主机上设置同步密钥，页面会显示主机地址（默认端口 46653）和二维码。
2. 手机端点击「扫码」扫描主机二维码；其他电脑直接输入 http://192.168.x.x:46653 这样的地址，并填写主机的同步密钥。
3. 点击「连接」后即可「立即同步」，之后按同步间隔自动进行（默认 1 分钟）。

• 索引分为 32 个分片增量更新，文件按 MD5 去重，大批量数据分批传输，断线后自动续传。
• 写入缓存可调：手机端默认 128 MB，电脑端默认 1 GB；单批事务默认 16 MB / 50 个文件。缓存满时会暂停接收，避免内存溢出。
• 跨网络同步时，推荐用 Tailscale 等加密组网工具让设备处在同一个虚拟局域网中。

17Bimanus 与外部 Agent

织忆的虚拟磁盘与真实磁盘隔离，这是安全边界。需要读写真实项目、执行命令时，交给配对的 Bimanus（基于 Pi 的桌面端 AI 客户端）：织忆是大脑，Bimanus 是手和脚。

1. 在目标电脑上安装并启动 Bimanus，记下它的 IP、端口和 Token。
2. 在织忆 设置 → 外部 Agent 设置 中新增设备，填写设备名称、IP、端口、Token，以及允许访问的项目路径（每行一个，也可以浏览选择）。
3. 点击「连接」测试；之后对话里 AI 可以调用远程 Agent、导入远程文件、执行远程 Shell，并把结果写回记忆。

反过来，在 Memory MCP 设置中点击「复制记忆通道」，把地址粘贴到 Bimanus 的外部记忆通道设置里，Bimanus 也能读写织忆的记忆。

连接第三方 MCP 服务器

在 设置 → MCP 配置 中可以添加外部 MCP 服务器（HTTP 或 SSE），支持自定义请求头与 OAuth 授权，添加后其工具即可在对话中使用。

18数据与隐私

• 记忆、会话、设置和向量索引保存在你自己的设备上（AgentFS 虚拟磁盘与本地 SQLite）。
• 对话时，织忆会把你的问题和相关记忆片段发送给你自己配置的模型服务商，处理方式受该服务商的条款约束。
• 嵌入与语义检索在本地完成，不调用云端嵌入服务。
• 局域网同步只在你的设备之间传输；外网远程访问由你主动开启、用临时密码授权，可以随时停用。
• Debug 日志默认关闭；开启后日志只写在本机，由你决定是否导出。

完整说明请阅读隐私政策。

19常见问题

外部 Agent 说找不到记忆？

检查 memory_name 是否与记忆库名称完全一致（大小写、空格都要一致），不要翻译或改写。

Memory MCP 连不上？

• 先请求 /mcp/health：返回 200 说明服务正常，问题在客户端配置。
• 确认 设置 → Memory MCP 服务 已启用，端口 3901 没有被其他程序占用。
• 某个方法调用失败时，先看 tools/list 里是否有它——没有说明该方法未开放，而不是服务断开。

虚拟磁盘里能直接运行本地脚本吗？

不能。虚拟磁盘中的 Shell 是受限环境，不会触碰真实系统。需要真实环境时请配对 Bimanus。

如何自定义 AI 的记忆方式？

编辑记忆库 .env 中的规范与风格文件，或开启自进化让 AI 在使用中自己调整，详见记忆规范与自进化。

改坏了怎么办？

打开版本面板，恢复到之前的版本，或只撤销出问题的那次变更。