永久记忆系统 --- 让 AI Agent 跨会话、跨模型、跨平台保持记忆
作者：Victor Taelin | 仓库：github.com/VictorTaeli...
一、什么是 OptMem？
OptMem 是一个永久、仅追加的记忆系统，专门为 AI Agent 设计。核心特点：
- 一个 Python 脚本搞定一切，零依赖
- 二叉合并树自动压缩旧记忆，近期保留原文，越远越精简
- O(1) 定位：固定 320 字节/条记录，按偏移量直接 seek
- 跨会话持久：会话结束、上下文压缩、模型切换、供应商更换，记忆都在
- 并行安全 ：Windows 用
msvcrt文件锁，多会话可同时写入
存储结构
bash
~/.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）
安装步骤
bash
# 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 initinit 会创建 ~/.optmem/memory/ 目录，并输出一段 CLAUDE.md 提示词模板。
配置到 CLAUDE.md
将 init 输出的 ## Memory 整块内容复制到 ~/.claude/CLAUDE.md 的最顶部。
三、全部命令详解
以下用
memo代替完整路径py ~/.optmem/memo，实际使用请写全路径。
1. memo wake --- 唤醒记忆（每次会话必须第一个调用）
bash
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
示例输出：
bash
#0 2026-08-04 集成了 OptMem 记忆系统
#1-2 用户偏好中文，项目用 React 19 + Ant Design
#3-7 各种历史记录的压缩摘要...
You are awake.2. memo note "..." --- 记录一条记忆
bash
memo note "用户偏好中文交流，代码注释用英文"
memo note "解决了 RTK 在 Windows 上 python3 占位符的问题，改用 py 启动器"规则：
- 一行，最多 280 字节（中文约 93 个字）
- 自动追加日期前缀
- 保存后返回 ID：
Saved as #3. - 如果触发了新的压缩需求，会提示你执行
memo nap
什么时候该记：
- 用户教了你一个新东西
- 一个值得记住的事实或见解
- 关于用户生活的事（哪怕是间接了解到的）
- 完成了一项有实质意义的任务
- 任何有持久影响的事件
什么时候不该记：
- 已经记录过的重复信息
- 临时的、无关紧要的细节
- 可以从代码/文件中推导出的信息
3. memo nap [lo-hi "摘要"] --- 执行压缩
bash
memo nap # 查看下一个待压缩的块
memo nap 0-1 "用户中文交流，代码英文注释" # 提交压缩摘要工作流程：
memo note后如果提示压缩需求，先运行memo nap查看待压缩内容- 查看输出的原始记忆内容
- 用一行（最多 280 字节）总结这些记忆的持久影响
- 提交：
memo nap <lo>-<hi> "<你的摘要>"
注意：
- 压缩按顺序进行，必须从最小的块开始
- 压缩一旦提交，原始记忆仍保留在 LOG.txt 中，只是 TREE/ 缓存了摘要
wake只展示摘要，不展示原始记忆（除非 zoom）
4. memo recall <正则> --- 搜索全部记忆
bash
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> --- 展开树节点
bash
memo zoom 0-3 # 展开 #0-3 这个摘要块，看它的两个子块
memo zoom 0-1 # 展开 #0-1，看原始的两条记忆用途：
- 当
wake展示的摘要不够详细时，用 zoom 逐层展开 - 每次展开为两个子节点（二叉树的左半和右半）
- 展开到单条记忆时显示原始文本
示例：
bash
$ memo zoom 0-3
#0-1 用户中文交流，项目用 React 19
#2-3 解决了 python3 占位符问题，集成 OptMem6. memo forget <lo>-<hi> --- 删除坏摘要
bash
memo forget 0-1 # 删除 #0-1 的摘要及其上层摘要用途：
- 压缩写错了？用 forget 删除，下次 nap 会重新生成
- 不会影响原始 LOG.txt，只删 TREE/ 缓存
- 删除后需要重新执行
memo nap来重建
7. memo config [NAME=VALUE] --- 查看/修改配置
bash
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> --- 批量导入历史记忆
bash
memo import memories.txt文件格式：
bash
2026-01-15 开始学习 Rust
2026-02-20 完成第一个 Rust CLI 工具
2026-03-10 转向 TypeScript + Deno规则：
- 每行格式：
YYYY-MM-DD <文本> - 日期必须递增（不能早于已有记忆的最后日期）
- 文本最多 280 字节
- 仅用于初始化，不是常规操作
四、日常使用流程
每次新会话
工作过程中
bash
学到新东西 → 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.
五、高级用法
自定义存储位置
bash
export MEMORY_DIR="D:/synced-folder/optmem-memory"
py ~/.optmem/memo init适合同步到多台机器或放到 Git 仓库中。
调整 wake 深度
bash
# 默认 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 顶部的内容：
markdown
## 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（不推荐）。