memex-agent-memory — Agent 记忆系统

用嵌入式向量数据库实现轻量级 Agent 记忆系统，以 CLI + Skill 的形式交付。

一句话

Memex 让 Agent 记住一切，实现跨会话的持续学习。

灵感来源：整套 Agent 记忆机制设计受 OpenSwarm 启发。

特性

• 原文存储 — 原文保留，不依赖 LLM 提取摘要
• 向量语义搜索 — 支持自然语言查询记忆
• 六种记忆类型 — constraint / user_model / strategy / system_pattern / belief / journal
• 隐私可控 — recall / purge 用户自主控制
• 多 Agent 支持 — 通过 repo 命名空间隔离
• 便携设计 — ~/.memex/ 打包迁移

Summary

Memex 定位与 MemPalace 不同：

• MemPalace → maximize recall（找回正确答案），适合 benchmark
• Memex Phase 2 → maximize utility（找回最有用的答案），适合真实场景

Memex 已完成 LongMemEval 基准测试（Turn-level）：R@5 ≈ 91.8%（vs MemPalace 96.6%）。差距来自粒度不同，Phase 2 高级机制（蒸馏/混合检索/修订/衰减/合并）没有公开 benchmark，需在真实使用中验证。

详见：docs/comparison.md

📄 详见：docs/comparison.md

快速开始

安装

pip install memex-agent-memory
memex install-skill   # 安装 Skill 到 ~/.agents/skills/memex/

初始化

memex init

存入记忆

memex save --type belief --content "用户喜欢简洁的回复风格" --repo user

搜索记忆

memex search "用户有什么偏好" --repo user --limit 5

返回 JSON（供 Agent 解析）：

{
  "query": "用户有什么偏好",
  "results": [
    {
      "id": "uuid",
      "type": "belief",
      "content": "用户喜欢简洁的回复风格",
      "importance": 0.7,
      "confidence": 0.8,
      "score": 0.92
    }
  ],
  "total": 1
}

更多命令

memex list --repo user              # 列出记忆
memex get <memory-id>               # 获取单条
memex delete <memory-id>            # 删除
memex stats                         # 统计
memex recall                        # 隐私查看
memex purge <memory-id>             # 隐私删除
memex purge --all                   # 清空所有

记忆类型

技术栈

架构

memex/
├── src/memex/
│   ├── _types.py        # MemoryRecord、MemoryType
│   ├── _config.py       # 配置管理
│   ├── _embed.py        # Embedding 生成
│   ├── store/           # 存储抽象层
│   │   ├── interface.py # VectorStore 接口
│   │   ├── lancedb.py   # LanceDB 实现
│   │   └── memory.py    # 内存实现（测试用）
│   └── cli.py           # CLI 命令
├── skills/
│   └── memory-skill/
│       └── SKILL.md     # 通用 Agent Skill
└── tests/

配置

配置文件：~/.memex/config.toml

[memory]
storage_path = "~/.memex/memory"

[vector_store]
provider = "lancedb"

[embedding]
model = "BAAI/bge-base-zh-v1.5"
dimension = 768

[retrieval]
default_limit = 10
min_similarity = 0.4

通用 Agent Skill

将 Memex 接入 Agent：

1. 复制 skill 到 ~/.openclaw/skills/memex/
2. Agent 在合适的时机调用 memex search / memex save

详见 skills/memory-skill/SKILL.md

LongMemEval Benchmark

在 LongMemEval（ICLR 2025, UCLA + 腾讯 AI Lab）上测试了 Memex 的记忆召回能力。

测试配置

• Embedding: BAAI/bge-base-zh-v1.5（768 维）
• 存储: LanceDB 嵌入式向量数据库
• 粒度: Turn-level（每条记录 = 一个对话回合，约 550 条/题）

测试结果

粒度说明

LongMemEval 支持两种评估粒度：

MemPalace 的 96.6% 是 turn-level 的结果。Turn-level 更接近真实场景——你的每一次对话、每一条消息，都可能藏着答案。

Memex 在 turn-level 达到 91.8%（vs MemPalace 96.6%），差距约 5 个百分点。

和 MemPalace 的差异

LanceDB 基于 Apache Arrow 列式存储，查询性能更强，存储更紧凑；BGE 中文 embedding 对中文对话的记忆召回更有优势。

核心发现

1. 原文存储有效：不经过 LLM 提取的原文方案，在记忆召回任务上表现优异
2. Turn-level 优于 Session-level：粒度越细，能找回的细节越多
3. 存储抽象带来灵活性：VectorStore 接口可以切换不同向量数据库后端

项目状态

Phase 1: MVP ✅

• 核心类型定义
• 存储抽象层（VectorStore 接口 + LanceDB 实现）
• CLI 命令（init / save / search / get / list / delete / stats / recall / purge）
• BGE embedding 集成
• 基本测试
• SKILL.md

Phase 2: 借鉴 OpenSwarm 的高级记忆机制 ✅

• 语义蒸馏（Distillation）：存入前过滤闲聊/情绪/依赖上下文的提问，只保留有价值的 insight
• 混合检索（Hybrid Retrieval）：final_score = 0.55×相似度 + 0.20×重要性 + 0.15×新鲜度 + 0.10×频率
• 记忆修订（Revision）：belief 被修订后重新计算 stability，支持不是 append-only
• 衰减遗忘（Decay & Forgetting）： decay ≥ 0.7 则归档，importance → 0.05
• 矛盾检测（Contradiction Detection）：基于关键词对检测语义冲突，importance 下降
• 记忆合并（Consolidation）：相似度 > 0.85 的记忆合并

Phase 3: 发布与分发

• pip install memex-agent-memory — 一键安装 CLI + Skill
• pyproject.toml — 打包配置
• Skill 自动安装到 ~/.agents/skills/memex/（遵守 AgentSkills 规范，通用）

Phase 4: 评测数据

• 创建 memex-benchmarks 仓库
• distillation 数据集：should_store / should_reject 各 20-50 条
• contradiction 数据集：成对矛盾的记忆对 20-30 条
• 其他模块数据集：hybrid / revision / decay / consolidation

License

MIT