适用场景与目标

OptMem 于 2026 年 7 月 25 日开源，24 小时内斩获近 500 星。核心卖点：一段 427 Token 的 Prompt + 一个无依赖的 Python 脚本 = AI Agent 永久记忆。

核心思路

传统 Agent 每次对话都是”失忆”的——新建 session 即遗忘所有历史。OptMem 用追加日志 + 二叉树摘要数据结构，让 Agent 在任何 session、模型、供应商之间持久化记忆：

特性	解决的问题	收益
纯文本日志	无需向量数据库、无需嵌入模型	零运维依赖，单文件 Python
二叉树摘要	日志过长时快速回忆	百万条记忆下 wake 耗时 0.03s
427 Token Prompt	Agent 无需记忆特殊协议	粘贴即用，兼容 Cursor/Claude/Copilot 等
文件系统存储	记忆归属工作区/项目	可 git 提交、可同步到云盘

适用场景

• 使用 Cursor/Claude Code/Copilot 的开发者，希望 Agent 跨 session 记住项目决策
• 自建 Agent 框架（LangChain/CrewAI/AutoGPT），需要轻量持久化记忆层
• 团队多人用同一 Agent（ssh 共享），记忆写在同步目录中
• 需要”审计追踪”的场景——记忆追加不可篡改

不适用场景

• 需要语义向量检索（OptMem 只做正则逐词搜索）
• Agent 会话量极大（> 1 亿条/天），此时文件系统 IO 会成为瓶颈
• 结构化数据库查询需求（如”找 7 月所有包含 ‘API’ 的记忆”需自行解析日志）

---

最小可行方案（MVP）步骤

全程只需 3 个命令：

# 1. 安装（20 秒）
curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh

# 2. 初始化记忆（打印一段 Markdown，粘贴到 AGENTS.md/CLAUDE.md）
~/.optmem/memo init

# 3. 验证
~/.optmem/memo note "Hello OptMem: first memory written"
~/.optmem/memo wake

集成到 Cursor/Claude Code

将 memo init 输出的 ## Memory 块粘贴到项目根目录的 AGENTS.md（Cursor）或 CLAUDE.md（Claude Code）：

## Memory

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

### At startup: activating OptMem (mandatory)

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

...

集成到自定义 Agent

import subprocess

class OptMemMemory:
    def __init__(self, memo_path="~/.optmem/memo"):
        self.memo = memo_path

    def wake(self) -> str:
        """Session 开始时调用，获取历史记忆摘要"""
        result = subprocess.run(
            [self.memo, "wake"], capture_output=True, text=True
        )
        return result.stdout

    def note(self, memory: str) -> None:
        """记录一条记忆（<= 280 字符，单行）"""
        subprocess.run([self.memo, "note", memory])

    def recall(self, query: str) -> str:
        """正则搜索所有记忆"""
        result = subprocess.run(
            [self.memo, "recall", query], capture_output=True, text=True
        )
        return result.stdout

---

关键实现细节

数据结构：追加日志 + 二叉树摘要

OptMem 不存数据库，存储只有两个部分：

~/.optmem/
  memo                    # 工具本身（单文件 Python）
  memory/
    LOG.txt               # 追加日志，每行一条记忆（固定宽度 280B）
    TREE/                 # 二叉树摘要缓存
      0-1.txt             # 第 0,1 条记忆的摘要
      0-3.txt             # 第 0-3 条（即 0-1 + 2-3）的摘要
      ...
    config                # 配置（WAKE_LINES 等）

固定宽度行 = 位置即身份。每次寻址都是 O(1) 文件 seek，无需解析索引。128 条记忆约 35KB，100 万条约 608MB。

wake 做了什么

1. 读取最后 WAKE_LINES（默认 208 行 ≈ 16K tokens）条记忆原文
2. 从二叉树根节点向下遍历，打印各级摘要
3. Agent 通过 memo zoom <lo>-<hi> 展开任一节点

压缩（nap）机制

当 memo note 写入第 128 条记忆时，工具自动触发压缩，将 128 条合并为一颗 7 层二叉树根节点摘要。无需 Agent 手动触发。

PATH 配置

# 将 memo 加进 PATH
echo 'export PATH="$HOME/.optmem:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 或者直接使用全路径
alias memo='~/.optmem/memo'

使用 Git 同步记忆

# 将记忆目录纳入版本控制
cd ~
ln -s ~/.optmem/memory ~/my-project/agent-memory
cd ~/my-project
git add agent-memory/
git commit -m "feat: add agent memory store"

# 团队成员 Pull 后自动共享 Agent 记忆

---

常见坑与规避清单

坑	现象	解决方案
子 Agent 写入记忆	记忆重复，摘要混乱	在子 Agent system prompt 中加入：“You are a subagent. Don’t run memo.”
PATH 未配置	memo: command not found	使用全路径 ~/.optmem/memo，或加入 PATH
日志过大导致 wake 慢	wake 耗时 > 1 秒	调小 WAKE_LINES（默认 208 条 ≈ 16K tokens）：memo config WAKE_LINES=100
多 Agent 并发写入	日志行错乱（flock 保护但 Python 级非原子）	使用 $MEMORY_DIR 分开不同 Agent 的记忆目录
跨机器同步冲突	两台机器同时写入 LOG.txt	不要多机同时写同一个记忆文件；使用 sync 代替实时并发
UTF-8 locale 问题	中文/emoji 导致 crash	工具已内置 sys.stdout.reconfigure(encoding="utf-8")，确认终端 locale
Agent 忘记执行 wake	Agent 认为自己没有记忆	在 Prompt 中强调 “mandatory”，并在每次代码生成模板中预置
变更模型供应商后	新模型不理解 OptMem 格式	OptMem Prompt 是模型无关的——Claude/GPT/Gemini 行为一致
错误的 regex 导致 recall 失败	搜索返回空	memo recall 使用基础 Python re，转义特殊字符：memo recall "SELECT\\*"

---

成本/性能/维护权衡

成本

项目	估算
存储	100 万条记忆 ≈ 608MB 磁盘，全在 ~/.optmem/memory/
计算	wake 0.03s（百万吨级），note 即时（仅追加写）
外部依赖	零——无需数据库、无需向量引擎、无需 LLM 调用
Token 开销	wake 的输出 ≈ 16K tokens/次，计入 session context

性能基准

• 100 万条记忆：wake 0.03s，recall（精确词）< 0.1s，note < 0.01s
• 二叉树深度：128 条 → 7 层，100 万条 → 20 层
• 文件大小上限以磁盘为界：无强制上限

维护

• 无守护进程：没有后台进程、没有定时任务
• 可自愈：memo forget <lo>-<hi> 标记坏摘要，nap 重建
• 可备份：LOG.txt 是唯一不可丢失的文件——TREE/ 可从日志重建
• 迁移友好：复制 memory/ 目录到新机器即可

与竞品对比

方案	依赖	100K 记忆成本	跨 Session	跨模型
OptMem	无	0	✅	✅
Vector DB (Chroma/Pinecone)	嵌入模型 + 数据库	> $5-10/月	✅	需重新嵌入
LangChain Memory	LangChain + 数据库	取决于后端	✅	部分兼容
Memory Bank（手写文件）	无	0	需手动	✅

---

一周内可执行行动清单

Day 1: 快速验证（30 分钟）

• curl -fsSL https://raw.githubusercontent.com/VictorTaelin/OptMem/main/install.sh | sh
• ~/.optmem/memo init → 复制输出到项目 AGENTS.md 或 CLAUDE.md
• 确认 ~/.optmem/memo wake 和 memo note "test" 正常工作

Day 2: 集成到日常 Agent 工作流

• 将 memo 加入 ~/.bashrc 的 PATH
• 在项目 AGENTS.md 首部粘贴 OptMem Prompt
• 开一个新 session，验证 Agent 自动执行 memo wake 并显示历史

Day 3-4: 调优

• 调整 WAKE_LINES（触达上下文窗口上限时减小，想多看历史时增大）
• 测试 memo recall <pattern> 搜索效率
• 配置 $MEMORY_DIR 指向同步目录（Dropbox/iCloud/Syncthing）

Day 5-6: 团队推广

• 将记忆目录纳入项目 Git 仓库（或 symlink 给团队成员）
• 编写团队约定：什么该记、什么不该记（不记冗余、不记子 Agent 内容）
• 验证多人共享时无冲突（使用 $MEMORY_DIR 隔离）

Day 7: 评估

• 统计一周写入的记忆条数
• 评估 wake 响应时间是否满足需求
• 决定是否持续使用 / 自定义扩展

---

总结

OptMem 是当前将持久化记忆嵌入 AI Agent 工作流成本最低的方式。它不是向量数据库的替代品——当你的需求是”让 Agent 记得之前做了什么决定、尝试过什么方案、用户喜欢什么风格”时，它是一个刚刚好的工具。

核心设计哲学值得学习：

1. 追加日志：永不修改历史，天然可审计
2. 二叉树摘要：用对数代价换取近似全量回忆
3. 零依赖：一个 Python 文件 + 一段 Markdown Prompt，不引入任何外部服务

对于已经在用 Cursor/Claude Code/Copilot 的开发者，花 20 分钟装上 OptMem，今天就能看到 Agent 的”持续性”质的提升。

---

参考链接：

• OptMem GitHub
• OptMem README
• HN: OptMem Discussion (as reference)