openclaw/0range-x/triple-layer-memory

Triple-Layer Memory System

三层记忆系统 - 解决 AI Agent 长对话记忆丢失和上下文管理问题

概述

这是一个完整的三层记忆管理系统，包含：

• Layer 1: Mem0（向量检索）- 跨会话召回
• Layer 2: 文件层（结构化存储）- 索引/项目/经验/日志四层
• Layer 3: Session 管理层（智能压缩）- 自动压缩、智能加载

核心功能

1. Session 自动压缩 + 自动切换（兼容版）

• token 达到 150k 或上下文占用达到 80% 时触发
• 先总结关键信息并写入记忆文件（可用时）
• 再触发新会话切换提示，避免上下文爆满
• 保留最近 50k tokens 原始对话

2. 记忆写入时机优化

• 关键时机立即写入（完成任务、做出决策、变更配置）
• 不等 session 结束，减少记忆丢失风险

3. 跨 Session 记忆连续性

• 新 session 启动时自动加载相关记忆
• 根据频道和任务智能检索
• 避免重复询问已知信息

4. 记忆遗忘机制

• 语义去重（相似度 > 0.88 拒绝写入）
• 高频命中自动升权
• 低权记忆自动归档
• 关键记忆永久保护（importance >= 8）

5. 频道级记忆隔离

• boss 频道：全量记忆访问
• 子频道：独立命名空间（userId::channelKey）

安装

# 使用 clawhub 安装
clawhub install triple-layer-memory

# 或手动安装
cd ~/Desktop/openclaw-workspace/skills
git clone https://github.com/0range-x/triple-layer-memory.git

初始化

安装后，运行初始化脚本：

cd ~/Desktop/openclaw-workspace
bash skills/triple-layer-memory/scripts/init.sh

这会创建：

• MEMORY.md - 核心索引
• memory/projects.md - 项目状态追踪
• memory/lessons.md - 经验教训库
• memory/YYYY-MM-DD.md - 日志文件
• MEMORY_ARCHITECTURE.md - 架构文档

使用

自动功能（无需手动调用）

1. Session 启动时：自动加载最近 2 天的日志和核心索引
2. 关键时机：自动写入记忆（完成任务、做出决策等）
3. Token 达到 150k 或上下文达到 80%：自动压缩并触发会话切换
4. 每周一次：自动执行记忆衰减和归档

手动功能

写入记忆

from scripts.auto_memory_write import auto_write_memory

auto_write_memory(
    summary="完成了某个重要任务",
    importance=8,
    channel="boss",
    tags=["任务完成", "部署"],
    project="项目名称",
    files=["path/to/file.py"],
    lessons="遇到的问题和解决方案"
)

压缩 Session

from scripts.session_compress import compress_session

compress_session(
    session_summary="本次对话的关键信息总结",
    channel="boss"
)

记忆衰减和归档

python scripts/memory_decay.py

配置

AGENTS.md

在你的 workspace 根目录创建或更新 AGENTS.md，添加：

## Session 启动流程

每次会话开始时，按以下顺序自动执行：

1. 读取 `SOUL.md` - 加载性格和行为风格
2. 读取 `USER.md` - 了解用户背景和偏好
3. 读取 `memory/YYYY-MM-DD.md` - 加载今天和昨天的日志
4. 如果是主会话：额外读取 `MEMORY.md` - 加载核心记忆索引
5. **智能记忆加载**：
   - 根据频道名称，优先加载该频道的相关记忆
   - 如果用户提到具体项目或任务，调用 `memory_search` 检索相关记忆
   - 如果是新 session 但延续之前的工作，自动加载最近的相关上下文

HEARTBEAT.md

在你的 workspace 根目录创建或更新 HEARTBEAT.md，添加：

## Session Token 检查（每次心跳执行）

检查当前 session 的 token 使用量（从 system warning 中获取）。

如果达到 150k tokens 或上下文达到 80%：
1. 调用 `scripts/session_compress.py` 获取压缩提示
2. 使用 LLM 总结对话历史中的关键信息
3. 将总结写入 `memory/YYYY-MM-DD.md`（若无记忆系统则至少生成交接摘要）
4. 调用 `scripts/session_rotate.py <used_tokens> <max_tokens> <channel>` 判断是否触发轮换
5. 若触发，输出 `[NEW_SESSION] 上下文达到80%，自动切换新会话`

Mem0 频道隔离

如果使用 Mem0，需要配置频道级命名空间隔离。

编辑 ~/.openclaw/extensions/openclaw-mem0/index.ts，参考 docs/mem0-channel-isolation.md。

文件结构

workspace/
├── MEMORY.md                    # 核心索引
├── MEMORY_ARCHITECTURE.md       # 架构文档
├── AGENTS.md                    # 启动流程和规范
├── HEARTBEAT.md                 # 心跳检查逻辑
├── memory/
│   ├── projects.md              # 项目状态追踪
│   ├── lessons.md               # 经验教训库
│   ├── 2026-03-04.md           # 日志文件
│   ├── heartbeat-state.json    # 心跳状态
│   ├── pinned.json             # 白名单记忆
│   └── .archive/               # 归档目录
└── scripts/
    ├── session_compress.py      # Session 自动压缩
    ├── session_rotate.py        # 80%上下文触发会话轮换
    ├── auto_memory_write.py     # 自动记忆写入
    ├── memory_decay.py          # 记忆衰减和归档
    ├── memory_meta.py           # 元数据管理
    ├── memory_consistency.py    # 一致性校验
    └── channel_memory.py        # 频道记忆路由

记忆格式

日志格式（memory/YYYY-MM-DD.md）

## HH:MM 项目名称

【项目：名称】 事件标题
结果：一句话概括
相关文件：文件路径
经验教训：要点（如有）
检索标签：#tag1 #tag2
<!-- meta: importance=N access=0 created=YYYY-MM-DD last_accessed=YYYY-MM-DD channel=CHANNEL -->

项目格式（memory/projects.md）

### 项目名称
**状态**：运行中/已完成/归档
**最后更新**：YYYY-MM-DD
**描述**：项目简介
**关键文件**：
- 文件路径1
- 文件路径2
**待办**：待办事项列表
**备注**：其他说明

经验格式（memory/lessons.md）

### 问题标题
**问题**：问题描述
**原因**：根本原因
**解决方案**：解决方法
**相关文件**：文件路径
**日期**：YYYY-MM-DD
**标签**：#tag1 #tag2

性能指标

• Session 寿命：从 ~100k tokens 提升到 ~150k tokens
• 记忆丢失率：从 ~30% 降低到 ~5%
• 新 session 启动时间：从 ~10s 降低到 ~3s
• 记忆检索准确率：从 ~60% 提升到 ~85%

最佳实践

1. 日志写入：记录结论而非过程
2. 项目变更：同步更新 memory/projects.md
3. 遇到问题：记录到 memory/lessons.md
4. 索引变化：更新 MEMORY.md
5. 元数据必填：每条记忆必须带 importance、channel、tags
6. 关键时机写入：不等 session 结束，立即写入
7. 定期维护：每周执行记忆衰减和归档

故障排查

Session 没有自动压缩或自动切换

• 检查 HEARTBEAT.md 是否包含 token 与上下文占用检查逻辑
• 检查 scripts/session_compress.py 与 scripts/session_rotate.py 是否存在
• 查看 system warning 中的 token 使用量和上下文占用率

记忆没有自动写入

• 检查 scripts/auto_memory_write.py 是否存在
• 确认 importance >= 7 或满足其他触发条件
• 查看 memory/YYYY-MM-DD.md 是否有新条目

新 session 没有加载记忆

• 检查 AGENTS.md 是否包含启动流程
• 确认 memory/YYYY-MM-DD.md 文件存在
• 查看 MEMORY.md 是否有内容

记忆被错误归档

• 检查 importance 是否 >= 8（永久保护）
• 查看 memory/pinned.json 白名单
• 运行 python scripts/memory_decay.py 查看权重计算

贡献

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

作者

小橘 (vulcanx_14970)

致谢

• Mem0 - 向量检索框架
• OpenClaw - AI Agent 框架