OptMem 使用教程一、什么是 OptMem？ OptMem 是一个永久、仅追加的记忆系统，专门为 AI Agent

永久记忆系统 — 让 AI Agent 跨会话、跨模型、跨平台保持记忆

作者：Victor Taelin | 仓库：github.com/VictorTaeli…

一、什么是 OptMem？

OptMem 是一个永久、仅追加的记忆系统，专门为 AI Agent 设计。核心特点：

一个 Python 脚本搞定一切，零依赖
二叉合并树自动压缩旧记忆，近期保留原文，越远越精简
O(1) 定位：固定 320 字节/条记录，按偏移量直接 seek
跨会话持久：会话结束、上下文压缩、模型切换、供应商更换，记忆都在
并行安全：Windows 用 msvcrt 文件锁，多会话可同时写入

存储结构

~/.optmem/
├── memo              # 工具本体（859 行 Python 脚本）
└── memory/
    ├── LOG.txt       # 原始记忆日志（仅追加，320 字节/条）
    ├── TREE/         # 二叉合并树摘要缓存（可从 LOG.txt 重建）
    ├── config        # 尺寸配置文件
    └── .lock         # 并行锁文件

核心原理

每条记忆是固定 320 字节的记录，位置即身份：记忆 #i 在文件偏移 i × 320 处。

TREE/ 目录存储二叉合并树：每层文件以 288 字节/条存储 2 的幂次块的压缩摘要。块 [lo, hi) 是 [lo, mid) 和 [mid, hi) 的压缩。

wake 命令用一个 alpha 参数二分搜索，决定哪些块保持原样、哪些被压缩，最终在 WAKE_LINES（默认 96 行）的预算内呈现最相关的记忆。

二、安装

前置条件

Python 3.7+（Windows 上用 py 启动器，不要用 python3）

安装步骤

# 1. 创建目录
mkdir -p ~/.optmem

# 2. 下载 memo 脚本
curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/memo -o ~/.optmem/memo

# 3. Windows 用户：修改 shebang 行
#    将第一行 #!/usr/bin/env python3 改为 #!/usr/bin/env py

# 4. 初始化
py ~/.optmem/memo init

init 会创建 ~/.optmem/memory/ 目录，并输出一段 CLAUDE.md 提示词模板。

配置到 CLAUDE.md

将 init 输出的 ## Memory 整块内容复制到 ~/.claude/CLAUDE.md 的最顶部。

三、全部命令详解

以下用 memo 代替完整路径 py ~/.optmem/memo，实际使用请写全路径。

1. `memo wake` — 唤醒记忆（每次会话必须第一个调用）

memo wake              # 读取全部记忆上下文（默认 96 行）
memo wake 2            # 读取第 2 部分（记忆较多时分页）
memo wake 2 150        # 读取第 2 部分，基于 150 条记忆的快照

行为：

输出分为多个 part（每 part 最大 20KB 或 500 行）
如果记忆较多，会提示 Not awake yet. Run: memo wake 2 <T>，继续执行直到看到 You are awake.
如果有未完成的压缩，会先要求你做压缩再 wake

示例输出：

#0 2026-08-04 集成了 OptMem 记忆系统
#1-2 用户偏好中文，项目用 React 19 + Ant Design
#3-7 各种历史记录的压缩摘要...
You are awake.

2. `memo note "..."` — 记录一条记忆

memo note "用户偏好中文交流，代码注释用英文"
memo note "解决了 RTK 在 Windows 上 python3 占位符的问题，改用 py 启动器"

规则：

一行，最多 280 字节（中文约 93 个字）
自动追加日期前缀
保存后返回 ID：Saved as #3.
如果触发了新的压缩需求，会提示你执行 memo nap

什么时候该记：

用户教了你一个新东西
一个值得记住的事实或见解
关于用户生活的事（哪怕是间接了解到的）
完成了一项有实质意义的任务
任何有持久影响的事件

什么时候不该记：

已经记录过的重复信息
临时的、无关紧要的细节
可以从代码/文件中推导出的信息

3. `memo nap [lo-hi "摘要"]` — 执行压缩

memo nap                        # 查看下一个待压缩的块
memo nap 0-1 "用户中文交流，代码英文注释"   # 提交压缩摘要

工作流程：

memo note 后如果提示压缩需求，先运行 memo nap 查看待压缩内容
查看输出的原始记忆内容
用一行（最多 280 字节）总结这些记忆的持久影响
提交：memo nap <lo>-<hi> "<你的摘要>"

注意：

压缩按顺序进行，必须从最小的块开始
压缩一旦提交，原始记忆仍保留在 LOG.txt 中，只是 TREE/ 缓存了摘要
wake 只展示摘要，不展示原始记忆（除非 zoom）

4. `memo recall <正则>` — 搜索全部记忆

memo recall "React"
memo recall "用户.*偏好"
memo recall "bug|error|fix"
memo recall "2026-08"

行为：

正则搜索，大小写不敏感
从头到尾扫描 LOG.txt（支持流式，百万条也不会爆内存）
输出最新匹配，受 PART_CHARS（20KB）限制
匹配太多时提示 Newest N of M matches. Narrow the regex.

5. `memo zoom <lo>-<hi>` — 展开树节点

memo zoom 0-3      # 展开 #0-3 这个摘要块，看它的两个子块
memo zoom 0-1      # 展开 #0-1，看原始的两条记忆

用途：

当 wake 展示的摘要不够详细时，用 zoom 逐层展开
每次展开为两个子节点（二叉树的左半和右半）
展开到单条记忆时显示原始文本

示例：

$ memo zoom 0-3
#0-1 用户中文交流，项目用 React 19
#2-3 解决了 python3 占位符问题，集成 OptMem

6. `memo forget <lo>-<hi>` — 删除坏摘要

memo forget 0-1     # 删除 #0-1 的摘要及其上层摘要

用途：

压缩写错了？用 forget 删除，下次 nap 会重新生成
不会影响原始 LOG.txt，只删 TREE/ 缓存
删除后需要重新执行 memo nap 来重建

7. `memo config [NAME=VALUE]` — 查看/修改配置

memo config                    # 查看当前所有配置
memo config WAKE_LINES=300     # 增加 wake 输出行数（读取预算，不是存储预算）
memo config ENTRY_CHARS=200    # 缩短单条记忆最大字节数
memo config WAKE_LINES=        # 恢复默认值

四个配置项：

参数	默认值	说明
`WAKE_LINES`	96	wake 输出的最大行数（约 8k tokens）
`ENTRY_CHARS`	280	单条记忆最大字节数
`PART_CHARS`	20000	分页：每 part 最大字节数
`PART_LINES`	500	分页：每 part 最大行数

重要： WAKE_LINES 是读取预算，不是存储预算。改大只影响 wake 输出多少行，不会重新计算或删除任何记忆。

8. `memo import <file>` — 批量导入历史记忆

memo import memories.txt

文件格式：

2026-01-15 开始学习 Rust
2026-02-20 完成第一个 Rust CLI 工具
2026-03-10 转向 TypeScript + Deno

规则：

每行格式：YYYY-MM-DD <文本>
日期必须递增（不能早于已有记忆的最后日期）
文本最多 280 字节
仅用于初始化，不是常规操作

四、日常使用流程

每次新会话

工作过程中

学到新东西  → py ~/.optmem/memo note "一行记录"
需要查旧记忆 → py ~/.optmem/memo recall "关键词"
摘要不够详细 → py ~/.optmem/memo zoom <lo>-<hi>

子 Agent 规则

子 Agent 禁止运行 memo！ 因为它无法判断什么是已知的，笔记会重复且不准确。在 spawn 子 agent 时加上：You are a subagent. Don't run memo.

五、高级用法

自定义存储位置

export MEMORY_DIR="D:/synced-folder/optmem-memory"
py ~/.optmem/memo init

适合同步到多台机器或放到 Git 仓库中。

调整 wake 深度

# 默认 96 行约 8k tokens，适合大多数场景
# 如果记忆很多，可以增加到 200-300 行
memo config WAKE_LINES=200

# 如果想节省 tokens，可以减少到 50 行
memo config WAKE_LINES=50

性能参考

记忆数量	LOG.txt 大小	wake 耗时
1,000	320 KB	< 0.01s
10,000	3.2 MB	< 0.01s
100,000	32 MB	~ 0.01s
1,000,000	608 MB	~ 0.03s

六、在 CLAUDE.md 中的配置模板

以下是已集成到 ~/.claude/CLAUDE.md 顶部的内容：

## Memory

Your memory is OptMem:
- The tool is `py ~/.optmem/memo` (use `py` launcher, NOT `python3`)
- Your memories are in `~/.optmem/memory`

OptMem outlives every session, compaction, model and vendor change.
Without it you do not know who you are, or what was decided and tried.

### At startup: activating OptMem (mandatory)

Run `py ~/.optmem/memo wake` before any other tool call, in every session, and
then do exactly what it prints, to the end of its output.

### While working: register memories (mandatory)

Call `py ~/.optmem/memo note "<1 line, max 280 bytes>"` whenever you learn
something new, or something worth keeping happens.

### When you need an old memory: search, or navigate

`py ~/.optmem/memo recall <regex>` searches every memory, word for word.
`py ~/.optmem/memo zoom <a-b>` opens a node into its two halves.

### If you're a subagent: skip everything above

A subagent must never run `memo`.

七、常见问题

Q: Windows 上 python3 不能用？
A: Windows 的 python3 是 Store 占位符（exit 49），用 py 启动器代替。

Q: 多个 Claude Code 会话同时写入安全吗？
A: 安全。OptMem 用文件锁（Windows 用 msvcrt.locking）保证并行写入不冲突。

Q: 记忆会丢失吗？
A: 不会。LOG.txt 是仅追加的，TREE/ 只是缓存（可从 LOG.txt 重建）。forget 只删缓存，不删原始记录。

Q: 压缩后的原始记忆还能看到吗？
A: 能。用 memo zoom 逐层展开，或者用 memo recall 搜索

Q: 可以删除某条记忆吗？
A: 不直接支持。OptMem 是仅追加的设计。如果需要，可以手动编辑 LOG.txt（不推荐）。

OptMem 使用教程