tiered-memory

🧠 LLM驱动的智能分层记忆架构

EvoClaw 框架下的三层记忆系统,通过 Hot/Warm/Cold 分级存储与树形索引,实现 LLM 代理的长期记忆管理,支持元数据提取与云同步,解决上下文窗口限制。

收藏
16.2k
安装
4k
版本
v2.1.0
CLS 安全性认证2026-04-30
点击查看完整报告 >

使用说明

核心用法

Tiered Memory System 采用仿生学设计,模拟人类记忆的三层架构:Hot Memory(5KB,核心身份与活跃上下文)、Warm Memory(50KB,30天内蒸馏事实)、Cold Memory(云端 Turso 数据库,十年存档)。系统通过 LLM 驱动的树形索引(Tree Index)实现 O(log n) 的高效检索,而非传统的向量相似度搜索。

使用流程包含四个关键环节:首先通过 distill 命令将原始对话压缩为结构化事实;接着使用 store 命令按分类路径存储;随后利用 retrieve 进行基于 LLM 推理的语义检索;最后通过 consolidate 执行定期维护(快速/每日/每月模式)。v2.1.0 新增元数据自动提取功能,可识别并保留 URL、命令行和文件路径,确保技术细节在蒸馏过程中不丢失。

显著优点

恒定上下文开销:无论运行多久,每次会话仅需加载 8-15KB 上下文(Hot + Tree + 检索结果),相比传统扁平化 MEMORY.md 的线性增长,极大节省 Token 消耗。

可解释的树形检索:基于 PageIndex 的树形结构支持推理式搜索,可追踪 "Projects → EvoClaw → BSC" 的完整路径,准确率可达 98%,远超向量相似度方案的 70-80%。

云优先架构:支持 Turso 云端冷存储,设备丢失后可在 2 分钟内完成全量恢复,实现真正的跨设备同步。

智能记忆衰减:基于重要性 × 时间衰减 × 访问频率的评分算法,自动将低价值记忆归档或删除,实现"战略性遗忘"。

潜在缺点与局限

基础设施依赖:Cold Storage 功能强制依赖外部 Turso 数据库(或自建 SQLite),需要用户自行管理数据库凭证和网络连接;LLM 检索模式需配置外部端点(Claude/GPT 等),增加部署复杂度。

安全风险:当前版本存在 SQL 注入漏洞(cold_query 函数使用字符串拼接),在处理不可信查询输入时可能导致数据泄露。

来源可信度:作为 T3 级社区项目(GitHub: clawinfra/evoclaw),虽代码结构良好,但缺乏企业级安全审计,不建议用于处理高度敏感数据的生产环境。

维护开销:需要配置定时任务(cron)执行日常/月度整合,树形索引需要人工干预修剪(max 50 节点限制)。

适合的目标群体

AI 代理开发者:特别是基于 EvoClaw/OpenClaw 框架构建长期记忆能力的开发者;需要实现数月/数年长期记忆的对话系统;对上下文成本控制敏感的 LLM 应用。

知识管理场景:个人知识库构建、研究笔记管理、项目决策追踪等需要结构化归档的场景。

技术爱好者:理解树形索引、分层存储原理,愿意配置数据库和 LLM 端点的进阶用户。

使用风险

数据安全风险:除已识别的 SQL 注入外,云端同步功能将核心记忆上传至 Turso,虽数据加密但仍存在第三方服务风险;建议对敏感信息(密码、API 密钥)进行额外加密或避免存储。

依赖稳定性:系统依赖 libsql_client 连接 Turso,以及外部 LLM 端点可用性,网络中断或服务商故障会影响 Cold 存储检索和语义搜索功能。

数据一致性:自动蒸馏可能丢失语境细节,尽管 v2.1.0 改进了 URL 保留,但复杂技术讨论仍存在信息压缩损失;建议对关键决策人工验证 validate 命令的输出。

迁移成本:一旦积累大量 Warm/Cold 记忆,更换存储方案或清理历史数据需要执行完整的月度整合流程。

安全解读

核心定位

Tiered Memory 是一款专为 AI Agent 设计的长期记忆管理系统,借鉴人类认知的"巩固-遗忘"机制与 PageIndex 的树形检索架构,通过三层记忆架构(Hot 5KB / Warm 50KB / Cold 无限)实现恒定上下文成本与高效检索。

核心用法

三层架构运作

  • Hot Memory(5KB):核心身份、用户画像、活跃项目、关键教训,常驻上下文
  • Warm Memory(50KB):近 30 天蒸馏事实,含衰减评分机制,按重要性动态升降级
  • Cold Memory(Turso DB):10 年长期归档,按需查询永不加载

关键工作流
1. 蒸馏(Distillation):对话 → 结构化事实 → 单行摘要,三级压缩(500B→80B→20B)

2. 树形检索:LLM 推理遍历分类树,O(log n) 定位 vs 向量相似度扫描

3. 智能巩固:每小时/每日/每月自动维护,评分淘汰 + 归档 + 重建索引

4. 关键同步:对话后自动备份 Hot+Tree 至 Turso,<2 分钟灾难恢复

v2.1.0 增强功能:结构化元数据提取(URL/命令/路径)、完整性验证、URL 片段搜索、蒸馏过程 URL 保活机制。

显著优点

1. 成本恒定:5 年代理运行后单次会话上下文仍仅 8-15KB,对比平铺 MEMORY.md 的线性膨胀
2. 检索精准:PageIndex 基准测试显示 98%+ 准确率 vs 向量 RAG 的 70-80%

3. 可解释性:"Projects → EvoClaw → BSC" 路径可追溯,非黑盒相似度

4. 云原生:设备可替换,Agent 灵魂存于 Turso,跨终端一致体验

5. 零依赖:纯 Python 标准库实现,无供应链攻击面

潜在局限

1. 架构复杂度:三层状态机 + 评分算法 + 树维护,调试门槛高于简单向量库
2. LLM 依赖:精准检索需 LLM 推理,增加延迟(300-600ms)与 token 成本

3. Turso 锁定:冷存储深度绑定 Turso(libsql),迁移需数据导出

4. 评分调参:重要性/衰减/强化系数需针对场景校准,默认配置可能不适用高频变更场景

5. 树深度限制:4 层 50 节点上限约束超复杂领域建模

适合人群

  • 需要 数月/数年连续对话记忆 的个人 Agent 开发者
  • 受困于 RAG 上下文膨胀成本 的生产环境
  • 重视 检索可解释性 的企业合规场景
  • 追求 设备无关的 Agent 持续性 的多端用户

常规风险

1. Turso 凭据泄露:TURSO_TOKEN 需环境变量管理,硬编码可导致记忆数据未授权访问
2. LLM 端点劫持:用户自定义端点若指向恶意服务,提示词可能泄露

3. 明文存储:本地 JSON 无加密,设备物理丢失即数据暴露

4. 评分漂移:长期运行后评分公式可能产生意外淘汰,需定期人工审计 MEMORY.md 重建质量

技术亮点

  • 向量无关架构:LLM 推理替代嵌入相似度,规避向量数据库成本与维度灾难
  • 原子写入:temp+rename 模式防止 JSON 损坏
  • 多 Agent 隔离:agent-id 作用域完整隔离记忆空间

tiered-memory 内容

scripts文件夹
手动下载zip · 49.1 kB
distiller.pytext/plain
请选择文件