Agentmem

agentmem

为 Claude Code、Cursor 和 Codex 提供共享记忆，并能判断哪些内容仍然有效。保存会话、发现过时和冲突的规则，避免 Agent 重复犯旧错误。

问题

你的 AI 编码助手会忘记不同会话之间的所有内容。它会重复犯旧错误，也分不清当前规则和过时规则。上下文会被压缩，恢复过程令人头疼。

大多数记忆工具解决的是存储问题。agentmem 解决的是可信度问题。

开始使用（Claude Code / Cursor / Codex）

pip install quilmem[mcp]
agentmem init --tool claude --project myapp

就这么简单。重启编辑器，你的 Agent 就有了 13 个记忆工具。运行 memory_health 进行确认。

仅使用 Python？ 无需安装 MCP extra 即可运行 pip install quilmem。请参阅下文的 Python API。

60 秒演示

from agentmem import Memory

mem = Memory()

# Store typed memories
mem.add(type="bug", title="loudnorm undoes SFX levels",
        content="Never apply loudnorm to final mix. It re-normalizes everything.",
        status="validated")

mem.add(type="decision", title="Use per-line atempo",
        content="Bake speed into per-line TTS. No global pass.",
        status="active")

# Something you're not sure about yet
hypothesis = mem.add(type="decision", title="Maybe try 2-second gaps before CTA",
        content="Hypothesis from last session. Needs testing.",
        status="hypothesis")

# Search — validated and active memories rank highest.
# Deprecated and superseded memories are excluded automatically.
results = mem.search("audio mixing")

# Context-budgeted recall — fits the best memories into your token limit
context = mem.recall("building a narration track", max_tokens=2000)

# Lifecycle — promote what's proven, deprecate what's not
mem.promote(hypothesis.id)                # hypothesis -> active -> validated
mem.deprecate(hypothesis.id, reason="Disproven by data")

# Supersede: replace an outdated memory with a newer one
replacement = mem.add(type="decision", title="Use 1-second gaps before CTA",
        content="Confirmed by A/B test.", status="active")
mem.supersede(hypothesis.id, replacement.id)  # old points to replacement

# Health check — is your memory system trustworthy?
from agentmem import health_check
report = health_check(mem._conn)
# Health: 85/100 | Conflicts: 0 | Stale: 2 | Validated: 14

与众不同之处

其他记忆工具只存储内容。 agentmem 知道哪些内容仍然有效。

	Mem0	Letta	Mengram	agentmem
记忆存储	是	是	是	是
全文搜索	向量	Agent 驱动	知识图谱	FTS5
记忆生命周期状态	否	部分支持	否	假设 -> 活跃 -> 已验证 -> 已弃用 -> 已取代
冲突检测	否	否	部分支持	内置
过时检测	否	否	否	内置
健康评分	否	否	否	内置
来源追踪	否	否	否	source_path + source_hash
按可信度排序回忆	否	否	否	已验证 > 活跃 > 假设
人类可读的源文件	否	否	否	规范 Markdown
本地优先，无需基础设施	否	可自托管	可自托管	始终如此
MCP 服务	单独提供	单独提供	是	内置

可信度治理

核心理念：每条记忆都有一个状态，用于追踪你应该在多大程度上信任它。

hypothesis    New observation. Not yet confirmed. Lowest trust in recall.
    |
  active      Default. Currently believed true. Normal trust.
    |
 validated    Explicitly confirmed. Highest trust in recall.

 deprecated   Was true, no longer. Excluded from recall. Kept for history.
 superseded   Replaced by a newer memory. Points to replacement.

**这很重要的原因：**没有治理机制，Agent 的记忆就会积累过时规则、矛盾和过时决策。它不知道 1 月份的语音设置已在 3 月份被覆盖。它会同时检索两者，再由大模型随机选择。治理记忆可以解决这个问题。

冲突检测

from agentmem import detect_conflicts

conflicts = detect_conflicts(mem._conn)
# Found 2 conflict(s):
#   !! [decision] "Always apply loudnorm to voice"
#      vs [decision] "NEVER apply loudnorm to voice"
#      Contradiction on shared topic (voice, loudnorm, audio)

agentmem 会找出相互矛盾的记忆：

• 检测主题重叠（Jaccard 相似度）
• 区分重复项与矛盾项
• 在句子级别匹配否定表达（而非只扫描关键词）
• 严重程度：critical（两者均为活跃状态）与 warning（其中一条已弃用）

过时检测

from agentmem import detect_stale

stale = detect_stale(mem._conn, stale_days=30)
# [decision] "Use atempo 0.90" — Source changed since import (hash mismatch)
# [bug] "Firewall blocks port" — Not updated in 45 days

通过以下方式查找过时记忆：

• 年限（N 天内未更新）
• 源文件缺失（引用的文件已删除）
• 哈希漂移（源文件内容已更改，但记忆未更新）

健康检查

from agentmem import health_check

report = health_check(mem._conn)
print(f"Health: {report.health_score}/100")
print(f"Conflicts: {len(report.conflicts)}")
print(f"Stale: {len(report.stale)}")

根据冲突、过时比例、孤立引用、已弃用权重，以及是否存在任何已验证的记忆，为你的记忆系统评出 0-100 分。

感知来源的同步

将规范 Markdown 文件同步到数据库，并追踪来源：

# Each memory tracks where it came from
mem.add(type="bug", title="loudnorm lifts noise",
        content="...",
        source_path="/docs/errors.md",
        source_section="Audio Bugs",
        source_hash="a1b2c3d4e5f6")

同步引擎会：

• 哈希相同 = 跳过（幂等，重复运行不会改变任何内容）
• 哈希不同 = 更新（源文件已更改）
• 章节已移除 = 弃用（并记录原因）
• 章节已恢复 = 恢复（重新激活已弃用的记忆）

三种接口

Python API

from agentmem import Memory

mem = Memory("./my-agent.db", project="frontend")

# CRUD
record = mem.add(type="decision", title="Use TypeScript", content="...")
mem.get(record.id)
mem.update(record.id, content="Updated reasoning.")
mem.delete(record.id)
mem.list(type="bug", limit=20)

# Search + recall
results = mem.search("typescript migration", type="decision")
context = mem.recall("setting up the build", max_tokens=3000)

# Governance
mem.promote(record.id)              # hypothesis -> active -> validated
mem.deprecate(record.id, reason="No longer relevant")
replacement = mem.add(type="decision", title="Use v2 approach", content="...")
mem.supersede(record.id, replacement.id)  # links old to replacement

# Session persistence
mem.save_session("Working on auth refactor. Blocked on token refresh.")
mem.load_session()                  # picks up where last instance left off

# Health
mem.stats()

CLI

# Get started in 30 seconds
agentmem init --tool claude --project myapp

# Check if everything's working
agentmem doctor

# Core
agentmem add --type bug --title "CSS grid issue" "Flexbox fallback needed"
agentmem search "grid layout"
agentmem recall "frontend styling" --tokens 2000

# Governance
agentmem promote <id>
agentmem deprecate <id> --reason "Fixed in v2.3"
agentmem health
agentmem conflicts
agentmem stale --days 14

# Import + sessions
agentmem import ./errors.md --type bug
agentmem save-session "Finished auth module, starting tests"
agentmem load-session

# MCP server
agentmem serve

MCP 服务

为 Claude Code、Cursor 和任何 MCP 客户端提供内置的 Model Context Protocol 服务。

pip install quilmem[mcp]

Claude Code 配置（.claude/settings.json）：

{
  "mcpServers": {
    "agentmem": {
      "command": "agentmem",
      "args": ["--db", "./memory.db", "--project", "myproject", "serve"],
      "type": "stdio"
    }
  }
}

MCP 工具： add_memory、search_memory、recall_memory、update_memory、delete_memory、list_memories、save_session、load_session、promote_memory、deprecate_memory、supersede_memory、memory_health、memory_conflicts

告诉你的 Agent 如何使用记忆： 将Agent 指令复制到你的 CLAUDE.md、.cursorrules 或 AGENTS.md 中。这会教会你的 Agent 会话协议、信任层级，以及何时搜索而非添加。

类型化记忆

七种类型，涵盖真实的 Agent 工作流：

类型	存储内容	示例
setting	配置、参数	“语音速度：atempo 1.08”
bug	错误及其修复方法	“loudnorm 会抬高噪声底”
decision	规则、策略、选择	“禁止使用第三人称旁白”
procedure	工作流、流水线	“TTS -> 速度 -> 48kHz -> 混音”
context	背景知识	“项目使用 FFmpeg + Python 3.11”
feedback	用户纠正	“始终直接选择，不要询问”
session	当前工作状态	“正在处理身份验证。受令牌问题阻碍。”

按信任度排序的回忆

recall() 不只是查找相关记忆，还会找出最可信的相关记忆：

1. FTS5 搜索返回候选项
2. 为每项评分：相关性 (25%) + 信任状态 (20%) + 来源信息 (20%) + 新近度 (15%) + 频率 (10%) + 置信度 (10%)
3. 已验证的规范记忆排名高于缺少来源信息的假设性记忆
4. 完全排除已弃用和已取代的记忆
5. 以贪心方式打包，直到达到令牌预算

项目范围

frontend = Memory("./shared.db", project="frontend")
backend = Memory("./shared.db", project="backend")

frontend.search("bug")  # Only frontend bugs
backend.search("bug")   # Only backend bugs

经实战检验

这并非纸上谈兵。agentmem 经历了 2 个多月的日常生产使用考验：

• 制作了 65 多个 YouTube Shorts，未重复出现任何制作故障
• 330 多条记忆用于管理语音生成、FFmpeg 组装、图像提示词和上传工作流
• 每个故障只发现一次、修复一次，再也没有重复
• 治理引擎将冲突误报从 1,848 个降至 11 个真实问题

工作原理

• 存储： 使用 WAL 模式的 SQLite（支持并发读取，线程安全）
• 搜索： 使用 Porter 词干提取和 unicode61 分词器的 FTS5
• 排序： 综合评分：文本相关性 + 信任状态 + 来源信息 + 新近度 + 频率 + 置信度
• 治理： 状态生命周期、冲突检测、过时检测、健康度评分
• 同步： 感知来源信息，支持源哈希和复原
• 零基础设施： 无需 API 密钥、云服务或向量数据库，只需一个 .db 文件。

许可证

MIT