一、什么是 OptMem？

OptMem 是一个永久、仅追加的记忆程序，专门为 AI Agent 设计。至于主要特点，

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

存储结构

~/.optmem/
├── memo # 工具本体
└── memory/
├── LOG.txt # 原始记忆日志
├── TREE/ # 二叉合并树摘要缓存
├── config # 尺寸配置文件
└── .lock # 并行锁文件

主要原理

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

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

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

二、安装与初始化

前置条件与环境准备

• Pytho​n 必须可用；Windows 上请使用 py *启动器*，不要用 python3 *。老实说，这样可以避免“python3 无法识别”导致的会话中断。
• 使用者痛点1： 多模型切换后记忆丢失？不用担心——OptMem 保持跨模型持久。
• 使用者痛点2： 同一 Agent 多线程写入冲突？OptMem 内置文件锁解决并发写入冲突。
• 使用者痛点3： 会话间无法恢复历史上下文？使用 wake *命令*即可快速唤醒最近内容。
• 如果你正在使用 Windows，请按以下步骤操作：
• - 创建目录：mkdir -p ~/.optmem
• - 下载脚本：curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/memo -o ~/.optmem/memo
• - Windows 使用者需修改 shebang 行：将第一行 `#!/usr/bin/env python3` 改为 `#!按理说，/usr/bin/env py`。
• - 初始化：py ~/.optmem/memo init

  `init` 会创建 `~/.optmem/memory/` 并输出 CLAUDE.md 提示词模板片段。请将其复制到你的 `~/.claude/CLAUDE.md` 的顶部，以便 Claude 在启动时自动加载记忆信息。

  配置到 CLAUDE.md 示例:

  text ## Memory Your memory is OptMem: - The tool is `py ~/.optmem/memo` - Your memories are in `~/.optmem/memory` ...

  三、全部命令详解

  注意这方面，以下所有示例均假设你已把完整方法写为 `py ~/.optmem/memo `。如果你习惯使用别名，请自行替换。

  . `memo wake ` — 唤醒记忆

  `wake` 必须是每个新会话中的第一条命令。用于恢复最近的上下文，并告知你当前可用的信息量。默认读取约 96 行，若记忆较多，你可以分页或指定快照范围以减少带宽消耗。说起来，

  text memo wake # 默认读取全部上下文 ~96 行 memo wake # 指定读取第 N 部分。例如第 1 部分 memo wake # 指定基于 M 条记录进行快照
  • 行为说明：- 输出分为多个 part，每 part 最大20KB或200行。- 如果记忆过多，会提示 “Not awake yet. Run: memo wake ”。需要继续执行直到看到 “You are awake.”。- 若存在未完成的压缩任务，会先提示你执行压缩再唤醒。
    • 示例输出：

      # -- 集成了 OptMem 记忆程序#- 使用者偏好中文，项目用 React + Ant Design#- 各种历史记录的压缩摘要...You are awake.

  . `memo note "..." ` — 写一条新笔记

  `note` 用来记录任何值得保留的新知识或事件。请保持单行且长度不超过约280字节，以保证高效索引和检索。按理说，

  text memo note "使用者偏好中文交流。代码注释用英文" memo note "解决了 RTK 在 Windows 上 python‑占位符的问题"

  • ID 返回值：`Saved as #123.` 给出唯一 ID，可用于后续引用或删除操作。
  • A new compression trigger:If a new block reaches compression threshold,system will prompt you to run `memo nap`.....
    • B. **何时应该记录**：
      • User teaches new skill or preference.
      .
      • A notable fact or insight that impacts future actions.A personal detail about user .An important task completion.An event with lasting influence. • 已经记录过的信息。• 临时无关细节，• 可从代码或文件直接推导出的信息。

        命令工作流示例

        1️⃣ 使用 `note ` 后如果程序提示需要压缩。请先运行 `nap ` 检查待压缩内容，接下来提交摘要。

        至于注意事项，

        • 压缩必须按顺序从最小块开始；一次性提交整个区间即可，
        • 一旦提交摘要，只保留摘要在 TREE/ 中；原始日志仍在 LOG.txt，可通过 zoom 或 recall 查看完整文本。
        • Wake 不展示已被压缩掉的原始文本。仅展示摘要，以控制 token 消耗。

        再看示例。

        text $ memo nap # 查看下一个待压缩块 $ memo nap - "-" "使用者中文交流..."

        ---

        子 Agent 与 Memo 的禁忌

        子 Agent 绝不能直接调用 Memo 工具，因为它们无法判断已知与否，这往往导致笔记重复且不准确信息累积。

        ---

        高级功能概览

        功能	用途	命令
        批量导入	初始同步旧笔记	import memories.txt
        自定义方法	同步多台机器	环境变量 MEMORY_DIR 指向共享目录
        调整 Wake 深度	控制 token 消耗	config WAKE_LINES=200 或降低

        ---

        性能参考表格

        ≈0.08–0.12s+

        Memory Count	Wake Time
        10K	≈0.01s+
        100K	≈0.01–0.02s+
        1M+	≈0.03–0.05s+
        10M+	≈0.05–0.08s+
        100M+

        ---

        常见问题解答

        Q: Windows 上为什么不能使用 python‑?

        A: Windows 的 python‑ 是 Store 占位符，它会直接退出。请改用 py 启动器，

        Q: 多个 Claude Code 会话同时写入安全吗？

        A: 安全。OptMem 使用 Windows 文件锁 来防止冲突。怎么说呢，

        Q: 我的历史笔记会丢失吗？怎么说呢，

        A: 不会。LOG.txt 是追加式，只增不删；TREE/ 缓存可以随时重建；forget 操作只删除缓存，不影响原始日志。怎么说呢，

        Q: 压缩后还能查看完整文本吗？

        A: 能，通过 zoom 或 recall 查看任意子节点或正则搜索结果。

        Q: 是否可以删除某条特定笔记？

        A: 原生不支持，因为设计为追加式。如果必须，可以手动编辑 LOG.txt。但这不推荐，因为可能破坏结构和校验码。

        ---