Memory Compass - 记忆罗盘 ⭐⭐⭐⭐⭐

「在数字沧海中，找到你的方向」 Navigate your way through the digital sea.

📖 简介

memory-compass 是一个三层混合记忆系统，为 AI Agent 提供持久化、可搜索、可恢复的记忆管理能力。

核心特性：

• ✅ LanceDB 向量记忆库 - 高速语义搜索（O(log n)）
• ✅ 文件系统 WAL 协议 - 关键信息立即固化
• ✅ 任务续传系统 - API 中断后秒级恢复上下文
• ✅ 统一查询接口 - 自动路由到最佳存储轨道

🔧 安装

# NPM 安装（开发版）
cd ~/AppData/Roaming/npm/node_modules
git clone https://github.com/winde/memory-compass.git skills/memory-compass
npm install --prefix skills/memory-compass

# 或者手动复制到 workspace
cp -r skills/memory-compass ~/.openclaw/workspace/skills/

🚀 快速开始

Python API 使用

from skills.memory_compass import MemoryCompass

# 初始化
compass = MemoryCompass()

# 1. 保存检查点
checkpoint = compass.save_checkpoint(mode="auto")

# 2. 恢复检查点
recovered = compass.recover_checkpoint(latest=True)

# 3. 搜索记忆
results = compass.find_memory(
    query="上次画图的任务进度",
    top_k=5
)

# 4. 获取完整上下文
context = compass.navigate_context(days_back=7)

# 5. 清理过期数据
report = compass.cleanup_old_checkpoints(keep_days=7)

🏗️ 架构设计

三层混合架构

┌─────────────────────────────────────────┐
│          用户输入/对话事件                │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│      【轨道 A: LanceDB 自动捕获】          │
│  └─ ml.capture({                       │
│       content: "对话内容",               │
│       type: "conversation"              │
│     })                                  │
│  ✅ 高速存储，可语义搜索                  │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│      【轨道 B: 文件系统 WAL 协议】           │
│  └─ write_to("SESSION-STATE.md", ...)  │
│  ✅ 关键信息立即固化                     │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│      【轨道 C: 定时检查点】               │
│  └─ save-checkpoint.ps1                │
│  ✅ 15min/45min 自动保存                 │
└─────────────────────────────────────────┘

📦 模块说明

src/core/ - 核心模块

src/checkpoints/ - 检查点管理

tests/ - 单元测试

• test_lancedb_integration.py
• test_checkpoint_recovery.py
• test_unified_search.py

examples/ - 使用示例

• basic_usage.py - 基础用法
• checkpoint_recovery.py - 断点续传演示
• hybrid_architecture.py - 三层架构协同

🎯 高级用法

智能降级策略

results = compass.find_memory(
    query="图像生成失败的原因",
    strategy="hybrid"  # lance_db -> file_system -> checkpoints
)

跨会话上下文迁移

# 导出旧会话记忆
old_memories = compass.export_session(session_key="agent:main:main")

# 导入到新会话
compass.import_memories(old_memories)

定期整理记忆

# 每周压缩 LanceDB 中重要的对话
compass.compress_memories(
    filter_type="important",
    target_file="memory/MEMORY.md"
)

🛠️ PowerShell 工具脚本

保存检查点

# 位置：ai-company/scripts/save-checkpoint.ps1
. .\scripts\save-checkpoint.ps1 -Mode "auto"
. .\scripts\save-checkpoint.ps1 -Mode "manual"

恢复检查点

# 列出所有检查点
.\scripts\recover-from-checkpoint.ps1

# 恢复最近一次
.\scripts\recover-from-checkpoint.ps1 -Latest

# 恢复指定日期
.\scripts\recover-from-checkpoint.ps1 -Date "20260317_065132"

清理过期检查点

# 保留最近 7 天的检查点
.\scripts\cleanup-old-checkpoints.ps1 -KeepDays 7

📊 配置参数

config.json (可选)

{
  "lancedb": {
    "api_provider": "jina-ai",
    "embedding_model": "jina-embeddings-v5-text-small",
    "dimensions": 1024,
    "rerank_model": "jina-reranker-v3"
  },
  "checkpoints": {
    "high_frequency_minutes": 15,
    "low_frequency_minutes": 45,
    "keep_days": 7
  },
  "wal": {
    "session_state_file": "SESSION-STATE.md",
    "memory_file": "MEMORY.md",
    "working_buffer_file": "memory/working-buffer.md"
  }
}

🔍 性能指标

📈 路线图

v1.0.0 (当前版本)

• ✅ 三层混合架构实现
• ✅ LanceDB + 文件系统
• ✅ 检查点保存/恢复
• ✅ 统一查询接口

v1.1.0 (待规划)

• 添加 Web UI 管理界面
• 支持更多存储后端（MongoDB, PostgreSQL）
• 智能记忆压缩算法
• 自动化测试覆盖率 > 80%

v2.0.0 (未来愿景)

• 分布式记忆网络（多实例同步）
• 联邦学习集成
• 情感记忆分析
• 跨平台记忆桥接

👨‍💻 贡献指南

欢迎提交 Issue 和 Pull Request！

开发环境设置：

# 进入技能目录
cd skills/memory-compass

# 安装依赖
pip install -r requirements.txt

# 运行测试
pytest tests/

# 运行示例
python examples/basic_usage.py

📄 许可证

MIT License

🙏 致谢

感谢以下开源项目：

• LanceDB - 向量数据库
• Jina AI - Embedding & Rerank 模型
• OpenClaw - Agent 框架

最后更新： 2026-03-17
作者： Winde (沧海一粟 AI COO)
版本： v1.0.0