hipool — 嵌入式 AI Agent 记忆系统 v4.5

海马体-皮层双存储模型 · 纯 C · 零外部依赖 (libc only) 项目代号 hipool (海马体 + 资源池 + 河马)

快速开始

cd skills/memory-c
gcc -O2 memory.c -o memory

# 存储
./memory set "今天天气" "晴天" --tags weather,北京
# 读取
./memory get "今天天气"
# 按标签搜索
./memory search --tag weather
# 时间范围查询
./memory search --range 1717920000 1718006400
# 按日期查询
./memory search --date 2026-06-08
# 列出所有分片
./memory shard list
# 写入指定分片
./memory set key val --shard people
# Fork 快照（BGSAVE 风格）
./memory snapshot
# 查看状态
./memory stats

核心功能 (v4.5)

1. Slab 分配器 (2MB 池)

• 四级: 256B(793 slot) / 1K(406) / 4K(153) / 16K(51)
• Bitmap 空闲追踪 + canary 溢出检测
• 同级满时自动 fallback 更高级别
• 水位 80% 触发 eviction → 写盘后释放

2. 三重索引

• Hash 表 (DJB2, 4096 桶): O(1) 键值查找
• Tag 倒排索引 (512 桶): tag → 条目映射，动态扩容
• SkipList 排序索引 (14 层): 按 created_at + key_hash 复合排序，O(log n) 插入/删除/范围查询

3. WAL 预写日志 (v4.3)

• 二进制追加写 memory_data/wal.log
• 每次 SET/DEL 先写 WAL 再改内存
• 崩溃后自动 wal_replay 恢复未落盘数据
• 加载阶段 wal_disabled=1 防止递归写

4. Shard 命名分片 (v4.4)

• 每个 shard 独立 Pool/Hash/Tag/SkipList/WAL
• 256KB 小池 · 最多 8 个命名分片
• --shard \x3Cname> 路由操作 · 自动发现已有目录
• 独立持久化: data_dir/shard_\x3Cname>/

5. Fork 快照 (v4.5)

• memory snapshot: fork 子进程写快照 (COW)，父进程不阻塞
• 同时 flush 所有 shard
• 多线程模式下安全拒绝 (fork+mutex 不安全)

6. 线程安全 (v4.5)

• 编译 -DHIPOOL_USE_MUTEX -lpthread 激活
• per-ctx 独立 mutex，默认 NOP 零开销
• 所有公开 API 加锁保护

命令参考

# 数据操作
memory set \x3Ckey> \x3Cvalue> [--tags a,b,c] [--ts \x3Cunix_sec>] [--shard \x3Cname>]
memory get \x3Ckey> [--shard \x3Cname>]
memory del \x3Ckey> [--shard \x3Cname>]

# 搜索
memory search \x3C关键词> [--shard \x3Cname>]
memory search --tag \x3C标签> [--shard \x3Cname>]
memory search --date YYYY-MM-DD [--shard \x3Cname>]
memory search --range \x3Cstart_ts> \x3Cend_ts> [--shard \x3Cname>]

# 管理
memory shard list|create \x3Cname>
memory flush           # 全量写快照 (含所有 shard)
memory snapshot        # Fork 快照
memory load            # 从磁盘恢复
memory clean           # 清理过期文件
memory stats           # 查看状态

编译选项

# 标准版 (单线程)
gcc -O2 memory.c -o memory
strip memory  # 52KB → ~42KB

# 多线程版
gcc -O2 -DHIPOOL_USE_MUTEX memory.c -o memory_mt -lpthread

源码结构

skills/memory-c/
├── memory             ← 52KB 单二进制
├── memory.c           ← 1642 行 C 源码
├── memory_data/       ← 运行时数据目录
│   ├── memory_snapshot.json   ← JSON 快照
│   ├── wal.log                ← WAL 预写日志
│   └── shard_\x3Cname>/          ← 命名分片数据
├── CHANGELOG.md       ← 版本日志
├── SKILL.md           ← 本文件
├── benchmark_results.md  ← 性能对比报告
├── ablation_test.sh   ← 消融测试脚本
├── test.sh            ← 原测试套件
├── bench_compare.c    ← 对比基准
└── bench_small.c      ← 池内基准

性能数据 (实测, 腾讯云 AMD EPYC 7K62)

池内 (无 eviction)

与 LMDB/SQLite/Redis 对比 (池内 GET)

规模数据 (N=50000, 含 eviction)

消融实验

40/40 全部通过 ✅：

• SkipList: 同时间戳碰撞 20 条 ✓ · 空范围 ✓ · 超大范围 ✓ · 删光后范围 ✓
• 大量数据: 500 条批量 ✓ · 排序顺序 ✓ · 删 250 查 250 ✓
• WAL: 基本恢复 ✓ · 100 条单进程恢复 ✓ · DEL 恢复 ✓ · 损坏 WAL 不崩溃 ✓
• Shard: 5 个隔离 ✓ · 默认无泄漏 ✓ · 超限拒绝 ✓ · 范围查询 ✓ · flush+reload ✓
• Fork Snapshot: 基本 ✓ · 并发写入 ✓ · shard+snapshot ✓
• 综合边界: 中文 key ✓ · emoji ✓ · 255B key ✓ · 空 value ✓ · 16KB value ✓ · 16 标签 ✓ · 时间范围 ✓ · Mutex 版 ✓

与 OpenClaw 集成

# cron 任务: 定时记忆同步
openclaw cron add --schedule "0 * * * *" \
  --account \x3Cbot_id> --to \x3Cuser_id> \
  --exec 'cd skills/memory-c && ./memory set "YYYY-MM-DD" "摘要" --tags "标签1,标签2"'

# 检索记忆
./memory search --tag \x3C标签> [--shard \x3Cname>]
./memory search --range \x3Cstart> \x3Cend> [--shard \x3Cname>]

配置常量 (编译前修改 memory.c 顶部)

资源占用

版本历史

故障排查

./memory stats               # 查看内存使用率
./memory load                # 从磁盘重新加载
ls memory_data/              # 查看磁盘文件
cat memory_data/memory_snapshot.json  # 查看快照内容
xxd memory_data/wal.log      # 查看 WAL 内容

相关文档

• 性能报告: benchmark_results.md
• 架构图: hipool_architecture_v4.5.jpg
• 消融脚本: ablation_test.sh
• 原测试套件: test.sh

弃用了 Redis v3.2.3 记忆系统 (2026-05-29 清除)，全面切换至 hipool C 内存系统。