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

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

快速开始#

bash

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 <name> 路由操作 · 自动发现已有目录
• 独立持久化: data_dir/shard_<name>/

5. Fork 快照 (v4.5)#

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

6. 线程安全 (v4.5)#

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

命令参考#

bash

# 数据操作
memory set <key> <value> [--tags a,b,c] [--ts <unix_sec>] [--shard <name>]
memory get <key> [--shard <name>]
memory del <key> [--shard <name>]

# 搜索
memory search <关键词> [--shard <name>]
memory search --tag <标签> [--shard <name>]
memory search --date YYYY-MM-DD [--shard <name>]
memory search --range <start_ts> <end_ts> [--shard <name>]

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

编译选项#

bash

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

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

源码结构#

text

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

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

池内 (无 eviction)#

operation32B256B1KB4KBSET avg1.7μs1.9μs3.2μs4.4μsSET p501.5μs1.5μs2.7μs4.1μsGET avg55ns62ns55ns67nsGET p5050ns60ns50ns60ns

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

database32B256B1KB4KBhipool55ns62ns55ns67nsLMDB936ns937ns1.0μs1.4μsSQLite6.6μs6.8μs10μs8.8μsRedis326μs332μs332μs352μs

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

databaseSET 32B avgGET 32B avgbinresidentmemoryhipool8.8μs337μs52KB****2MBLMDB1.5μs0.9μs2MB+1GBSQLite2.9μs7.1μsDLLfileRedis327μs326μs20MBmemory

消融实验#

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 集成#

bash

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

# 检索记忆
./memory search --tag <标签> [--shard <name>]
./memory search --range <start> <end> [--shard <name>]

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

常量默认值说明POOL_SIZE2MB主内存池大小SHARD_POOL_SIZE256KB每个 shard 池大小MAX_KEY_LEN256最大 key 长度MAX_VAL_LEN16320最大 value 长度MAX_TAGS16最大标签数MAX_TAG_LEN64单个标签最大长度EVICT_WATER80%触发逐出水位FILE_TTL_DAYS7磁盘文件保留天数SL_PROB4 (1/4)SkipList 层级概率MAX_SHARDS8最大命名分片数

资源占用#

指标值二进制大小52KB (strip 后 42KB)运行时内存2MB 固定 (+ shard × 256KB)线程安全版58KB (+6KB pthread)代码行数1642 行 C外部依赖0 (libc only)写入延迟 (池内)1.5-4.4μs读取延迟 (池内)50-67ns 🔥池内容量1400 条 (32B) / ~610 条 (256B) / ~200 条 (1KB) / 50 条 (4KB)磁盘占用1-2KB/条目 (JSON)

版本历史#

版本日期新增v4.52026-06-08线程安全 (per-ctx mutex) · Fork 快照 (BGSAVE) · eviction 修复(sl_remove)v4.42026-06-08Shard 命名分片 · --shard <name> 路由 · 自动发现 · stats 增强v4.32026-06-08SkipList 排序索引 · --range 范围查询 · WAL 预写日志 · 崩溃恢复v4.22026-06-02--ts 自定义时间戳v4.12026-05-30崩溃安全写入 · 可选多线程 · canary 检测 · 去重优化v4.02026-05-28首次稳定版: Slab · Hash · Tag · 日文件溢出 · 惰性加载

故障排查#

bash

./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 内存系统。