Skip to content
BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

1 Commit
docs
docs
 
 
examples
examples
 
 
openclaw_memory
openclaw_memory
 
 
.gitignore
.gitignore
 
 
CHANGELOG.md
CHANGELOG.md
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
requirements.txt
requirements.txt
 
 
setup.py
setup.py
 
 

Repository files navigation

OpenClaw记忆引擎

基于Forma架构的灵活记忆引擎,为OpenClaw提供持久化记忆和上下文管理能力

项目概述

OpenClaw记忆引擎是一个为AI助手设计的灵活数据存储系统,解决以下核心问题:

  • 灵活性 - 支持任意类型的记忆,无需预定义Schema
  • 性能 - 高频记忆快速检索(<50ms)
  • 类型安全 - 使用JSON Schema校验记忆数据
  • AI-Ready - 与LLM的结构化输出无缝集成

核心特性

✅ EAV + 热表架构 - 灵活存储 + 高性能查询 ✅ JSON Schema校验 - 类型安全,防止脏数据 ✅ 全文搜索 - 基于SQLite FTS5的快速搜索 ✅ 记忆关系图 - 建立记忆之间的关联 ✅ 标签系统 - 灵活的分类和过滤 ✅ 访问统计 - 自动追踪记忆访问频率

快速开始

1. 安装依赖

pip install jsonschema

2. 初始化引擎

from memory_engine import MemoryEngine

# 创建引擎实例
engine = MemoryEngine("my_memory.db")

3. 注册Schema

# 注册Person Schema
person_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "name": {
            "type": "string",
            "x-memory-column": "text_01"  # 映射到热表
        },
        "role": {
            "type": "string",
            "x-memory-column": "text_02"
        },
        "importance": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10,
            "x-memory-column": "integer_01"
        },
        "email": {"type": "string"},
        "notes": {"type": "string"}
    },
    "required": ["name"]
}

engine.register_schema("person", "Person", person_schema)

4. 写入记忆

memory_id = engine.write_memory(
    schema_id="person",
    data={
        "name": "张总",
        "role": "客户",
        "importance": 9,
        "email": "zhang@example.com",
        "notes": "预算50万,对新方案感兴趣"
    },
    tags=["客户", "重要"]
)

5. 查询记忆

# 普通查询
results = engine.query_memories(
    schema_id="person",
    filters={"importance": 9},
    limit=10
)

# 全文搜索
search_results = engine.search_memories("张总")

OpenClaw集成

安装为OpenClaw Skill

from openclaw_skill import MemorySkill

# 初始化技能
skill = MemorySkill()

# 记住某件事
skill.remember(
    memory_type="person",
    name="张总",
    role="客户",
    importance=9,
    tags=["客户", "重要"]
)

# 回忆某件事
result = skill.recall(query="张总")
print(result['memories'])

在OpenClaw中使用

User: 记住,张总是我的重要客户,预算50万
OpenClaw: [调用 skill.remember()]
         ✓ 已记住: 张总

User: 张总是谁?
OpenClaw: [调用 skill.recall("张总")]
         张总是你的重要客户,预算50万,重要性9/10

架构设计

数据模型

┌─────────────────────────────────────────────────────────────┐
│                  Memory Engine API                          │
│  ┌──────────────┬──────────────┬──────────────┐            │
│  │ Write Memory │ Query Memory │ Update Memory│            │
│  └──────────────┴──────────────┴──────────────┘            │
└────────────────────────┬────────────────────────────────────┘
                         │
         ┌───────────────┼───────────────┐
         │               │               │
         ▼               ▼               ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ JSON Schema  │  │  Hot Table   │  │  EAV Table   │
│   Validator  │  │  (快速检索)   │  │  (灵活存储)   │
└──────────────┘  └──────────────┘  └──────────────┘
                         │               │
                         └───────┬───────┘
                                 ▼
                         ┌──────────────┐
                         │  SQLite DB   │
                         └──────────────┘

核心表结构

memory_main - 热表

  • 存储高频访问的字段
  • 预分配列(text_01, integer_01等)
  • 有B-tree索引,查询快速

memory_eav - EAV表

  • 存储所有字段(包括热字段)
  • 灵活,无需DDL
  • 按需聚合

memory_tags - 标签表

  • 支持多标签
  • 快速过滤

memory_relations - 关系表

  • 记忆之间的关联
  • 支持知识图谱

预定义Schema

引擎内置了6种常用记忆类型:

1. Person (人物)

{
  "name": "张总",
  "role": "客户",
  "company": "ABC公司",
  "importance": 9,
  "email": "zhang@abc.com",
  "notes": "预算50万"
}

2. Event (事件)

{
  "title": "与张总电话沟通",
  "category": "call",
  "occurred_at": 1738483200,
  "duration": 30,
  "participants": ["张总", "我"],
  "summary": "讨论新方案"
}

3. Task (任务)

{
  "title": "准备方案PPT",
  "status": "in_progress",
  "priority": 8,
  "due_date": 1738569600,
  "assignee": "我"
}

4. Idea (想法)

{
  "title": "新产品创意",
  "category": "产品",
  "content": "基于AI的...",
  "potential_score": 8
}

5. Conversation (对话)

{
  "topic": "项目进度讨论",
  "platform": "telegram",
  "occurred_at": 1738483200,
  "summary": "确认了下周的里程碑"
}

6. Document (文档)

{
  "title": "项目需求文档",
  "doc_type": "report",
  "file_path": "/path/to/doc.pdf",
  "summary": "详细的需求说明"
}

API参考

MemoryEngine

register_schema(schema_id, schema_name, json_schema, version="1.0")

注册一个新的记忆Schema

write_memory(schema_id, data, tags=None, relations=None)

写入一条记忆

参数:

  • schema_id: Schema ID
  • data: 记忆数据(dict)
  • tags: 标签列表
  • relations: 关系列表 [{"to": memory_id, "type": "related_to"}]

返回: memory_id或None

query_memories(schema_id=None, filters=None, tags=None, limit=100, offset=0)

查询记忆

参数:

  • schema_id: 按Schema过滤
  • filters: 字段过滤 {"name": "张总"}
  • tags: 按标签过滤
  • limit/offset: 分页

返回: 记忆列表

search_memories(query, schema_id=None, limit=20)

全文搜索记忆

参数:

  • query: 搜索关键词
  • schema_id: 按Schema过滤
  • limit: 返回数量

返回: 记忆列表

MemorySkill (OpenClaw)

remember(memory_type, **kwargs)

记住某件事

recall(query=None, memory_type=None, tags=None, limit=10)

回忆某件事

forget(memory_id)

忘记某件事(软删除)

relate(from_id, to_id, relation_type="related_to")

建立记忆关联

get_related(memory_id)

获取相关记忆

性能优化

热字段识别

引擎会自动追踪字段访问频率,建议将高频字段映射到热表:

# 在JSON Schema中使用 x-memory-column
{
  "name": {
    "type": "string",
    "x-memory-column": "text_01"  # 映射到热表
  }
}

查询优化

使用Forma的CTE + JSON_AGG模式,一次查询返回所有数据:

WITH filtered AS (
    SELECT memory_id FROM memory_main WHERE ...
),
eav_json AS (
    SELECT memory_id, JSON_GROUP_ARRAY(...) AS attributes
    FROM memory_eav WHERE memory_id IN (SELECT memory_id FROM filtered)
    GROUP BY memory_id
)
SELECT m.*, e.attributes
FROM memory_main m
LEFT JOIN eav_json e ON m.memory_id = e.memory_id

性能指标

  • 写入延迟: <10ms
  • 查询延迟: <50ms (热表) / <200ms (含EAV聚合)
  • 搜索延迟: <100ms (FTS5全文搜索)

扩展性

自定义Schema

# 创建自定义Schema
custom_schema = {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
        "field1": {"type": "string", "x-memory-column": "text_01"},
        "field2": {"type": "integer", "x-memory-column": "integer_01"},
        # ... 更多字段
    }
}

engine.register_schema("custom", "Custom Type", custom_schema)

冷热分离(未来)

当数据量增长到百万级,可以扩展为冷热分离架构:

PostgreSQL (热数据) + DuckDB/Parquet (冷数据)

参考Forma的第三篇文章实现。

文件结构

OpenClaw记忆引擎/
├── 00_架构设计.md       # 详细的架构设计文档
├── schema.sql           # 数据库Schema
├── memory_engine.py     # 核心引擎实现
├── openclaw_skill.py    # OpenClaw Skill接口
├── schemas.json         # 预定义Schema模板
└── README.md            # 本文件

技术栈

  • 数据库: SQLite 3.35+ (支持FTS5)
  • 语言: Python 3.10+
  • 依赖: jsonschema

参考资料

下一步计划

  • 添加更新记忆的API
  • 实现记忆合并功能
  • 添加记忆版本历史
  • 开发Web UI管理界面
  • 支持PostgreSQL后端
  • 实现冷热分离架构

许可证

MIT License

Created by AI_Roland 2026-02-02

About

基于Forma架构的灵活记忆引擎,为OpenClaw提供持久化记忆管理

Resources

Readme
MIT license
Activity

Stars

4 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages