docs(memory): record memory system architecture
This commit is contained in:
hotwa
126
agents/openclaw-main/memory-system-architecture.md
Normal file
126
agents/openclaw-main/memory-system-architecture.md
Normal file
@@ -0,0 +1,126 @@
|
|||||||
|
# OpenClaw 当前记忆系统架构（mac-5 控制面）
|
||||||
|
|
||||||
|
## 总览
|
||||||
|
当前记忆系统分成两层：
|
||||||
|
|
||||||
|
1. **Context Engine 层：lossless-claw (LCM)**
|
||||||
|
2. **Memory Backend 层：QMD**
|
||||||
|
|
||||||
|
二者不是同一层，不占同一个插件槽位，职责不同，可以同时使用。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. lossless-claw（LCM）
|
||||||
|
### 定位
|
||||||
|
- 作为 **context engine** 使用
|
||||||
|
- 负责长对话上下文的压缩、保留与恢复
|
||||||
|
- 替代原本单纯 sliding-window compaction 的部分能力
|
||||||
|
|
||||||
|
### 当前状态
|
||||||
|
- 已安装并启用
|
||||||
|
- 当前 `plugins.slots.contextEngine = "lossless-claw"`
|
||||||
|
- 插件安装位置：`~/.openclaw/extensions/lossless-claw`
|
||||||
|
|
||||||
|
### 主要作用
|
||||||
|
- 用 SQLite + DAG summaries 管理长上下文
|
||||||
|
- 当主会话变长时，帮助保留可恢复的历史结构
|
||||||
|
- 提供对被压缩/折叠历史的再访问能力
|
||||||
|
|
||||||
|
### 典型功能
|
||||||
|
- `lcm_grep`
|
||||||
|
- `lcm_describe`
|
||||||
|
- `lcm_expand`
|
||||||
|
|
||||||
|
### 适合处理什么
|
||||||
|
- 长会话历史
|
||||||
|
- 最近/过往对话上下文恢复
|
||||||
|
- 被 compaction 后的历史细节回看
|
||||||
|
|
||||||
|
### 不适合替代什么
|
||||||
|
- 不替代持久 Markdown 知识库检索
|
||||||
|
- 不替代 QMD 对 memory repo / daily / tasks 等文件的索引搜索
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. QMD
|
||||||
|
### 定位
|
||||||
|
- 作为 **memory backend** 使用
|
||||||
|
- 负责 `memory_search` / `memory_get` 这条记忆召回路线
|
||||||
|
- 主要检索 Markdown 记忆文件与配置路径中的知识内容
|
||||||
|
|
||||||
|
### 当前状态
|
||||||
|
- 当前 `memory.backend = "qmd"`
|
||||||
|
- 当前仍是主记忆召回后端
|
||||||
|
- `memory.qmd.sessions.enabled = false`
|
||||||
|
|
||||||
|
### 为什么禁用 sessions indexing
|
||||||
|
因为如果让 QMD 也去索引 session transcripts，会和 lossless-claw 在“会话回忆”层面产生重叠，导致：
|
||||||
|
- 同一段会话既能被 LCM 找回，也能被 QMD 找回
|
||||||
|
- QMD 结果容易被 session boilerplate / transcript 噪声主导
|
||||||
|
- 持久知识内容（daily / long-term / tasks）更容易被挤掉
|
||||||
|
|
||||||
|
因此当前约定：
|
||||||
|
- **会话历史回忆 → 优先走 LCM / context engine**
|
||||||
|
- **持久知识/记忆文件搜索 → 走 QMD**
|
||||||
|
|
||||||
|
### 当前 QMD 检索路径
|
||||||
|
- `~/project/collective-memory-repo/shared/long-term`
|
||||||
|
- `~/project/collective-memory-repo/daily`
|
||||||
|
- `~/project/collective-memory-repo/tasks`
|
||||||
|
- `~/project/collective-memory-repo/agents/openclaw-main`
|
||||||
|
|
||||||
|
### 适合处理什么
|
||||||
|
- 长期记忆
|
||||||
|
- daily notes
|
||||||
|
- task memory
|
||||||
|
- agent private notes
|
||||||
|
- Markdown 文件型知识库
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 内建 memorySearch 配置
|
||||||
|
### 当前状态
|
||||||
|
虽然当前主记忆后端仍是 QMD，但 `agents.defaults.memorySearch` 也已经配置为本机 oMLX embeddings：
|
||||||
|
|
||||||
|
- provider: `openai`
|
||||||
|
- model: `bge-m3-mlx-fp16`
|
||||||
|
- baseUrl: `http://127.0.0.1:8000/v1`
|
||||||
|
- apiKey: `omlx-local`
|
||||||
|
|
||||||
|
### 说明
|
||||||
|
- 这是一条 **内建 memorySearch 能力配置**
|
||||||
|
- 目前它已配置好 embeddings 端点
|
||||||
|
- 但当前主记忆召回仍然是 QMD，而不是它
|
||||||
|
|
||||||
|
换句话说：
|
||||||
|
- **当前默认在用的是 QMD**
|
||||||
|
- **内建 memorySearch embeddings 已准备好，后续如需切主路径可继续利用**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 当前推荐分工
|
||||||
|
### 会话相关
|
||||||
|
- lossless-claw / LCM
|
||||||
|
- 用于：长会话、上下文压缩恢复、历史对话回看
|
||||||
|
|
||||||
|
### 持久知识相关
|
||||||
|
- QMD
|
||||||
|
- 用于：memory repo、daily、tasks、长期知识检索
|
||||||
|
|
||||||
|
### embeddings 预备能力
|
||||||
|
- 本机 oMLX (`bge-m3-mlx-fp16`)
|
||||||
|
- 用于：未来如需要将 OpenClaw 内建 memorySearch 切换到本地 embeddings 时复用
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 当前结论
|
||||||
|
当前记忆系统不是单一工具，而是分层架构：
|
||||||
|
|
||||||
|
- **LCM / lossless-claw** = 上下文引擎（context engine）
|
||||||
|
- **QMD** = 持久记忆后端（memory backend）
|
||||||
|
- **oMLX embeddings memorySearch** = 已配置好的备用/未来可切换能力
|
||||||
|
|
||||||
|
当前主工作流：
|
||||||
|
- 会话恢复靠 LCM
|
||||||
|
- 文件记忆召回靠 QMD
|
||||||
|
- 不让 QMD 索引 sessions，避免和 LCM 打架
|
||||||
@@ -33,9 +33,18 @@
|
|||||||
- 对速度要求高的 subagent 任务，优先使用 `vllm_messages/Qwen3.5-27B`
|
- 对速度要求高的 subagent 任务，优先使用 `vllm_messages/Qwen3.5-27B`
|
||||||
- 若 vLLM 不可用，再 fallback 到 mac-5/mac-6/mac-7 的 oMLX 节点
|
- 若 vLLM 不可用，再 fallback 到 mac-5/mac-6/mac-7 的 oMLX 节点
|
||||||
- 本机优先使用 localhost/127.0.0.1，减少 tailscale 网卡不稳定带来的失败
|
- 本机优先使用 localhost/127.0.0.1，减少 tailscale 网卡不稳定带来的失败
|
||||||
|
- 已将 lossless-claw 显式绑定为 `plugins.slots.contextEngine`
|
||||||
|
- 保持 `memory.backend = qmd`
|
||||||
|
- 已显式设置 `memory.qmd.sessions.enabled = false`，避免 QMD sessions indexing 与 lossless-claw 的会话召回能力重叠
|
||||||
|
- 已将 `agents.defaults.memorySearch` 配置为本机 oMLX embeddings：
|
||||||
|
- provider: `openai`
|
||||||
|
- model: `bge-m3-mlx-fp16`
|
||||||
|
- baseUrl: `http://127.0.0.1:8000/v1`
|
||||||
|
- 当前主记忆检索仍然是 QMD；LCM 负责上下文恢复；本机 oMLX embeddings 作为内建 memorySearch 的已配置能力保留
|
||||||
- 目前已确认：
|
- 目前已确认：
|
||||||
- provider / model 注册已完成
|
- provider / model 注册已完成
|
||||||
- gateway 已执行重启调度以加载新配置
|
- gateway 已执行重启调度以加载新配置
|
||||||
- 仍需后续继续验证：
|
- 仍需后续继续验证：
|
||||||
- `sessions_spawn(runtime="subagent")` 在 `local-mac5/local-mac6/local-mac7` 上的真实调度行为
|
- `sessions_spawn(runtime="subagent")` 在 `local-mac5/local-mac6/local-mac7` 上的真实调度行为
|
||||||
- `nodes run -> harness/opencode/acpx` 超时根因
|
- `nodes run -> harness/opencode/acpx` 超时根因
|
||||||
|
- gateway 重启后 memory / context engine 新配置的实际运行行为
|
||||||
|
|||||||
Reference in New Issue
Block a user