anneal-memory

面向 AI 智能体的动态记忆。将片段压缩为身份。

这是唯一带有免疫系统的 MCP 记忆服务器。模式通过证据获得持久性，虚假知识会被捕获并降级，陈旧信息会逐渐消退——因此你的智能体记忆会随着时间推移变得更聪明，而不仅仅是变大。

包含四个认知层：片段存储、压缩连续性、赫布关联和情感状态追踪。零依赖。5 个工具。适用于任何 MCP 客户端。

快速开始

1. 运行服务器（无需安装）：

{
  "mcpServers": {
    "anneal-memory": {
      "command": "uvx",
      "args": ["anneal-memory", "--project-name", "MyProject"]
    }
  }
}

将其添加到项目根目录的 .mcp.json（Claude Code）或编辑器的 MCP 配置中。

数据库默认为 ~/.anneal-memory/memory.db（自动创建）。对于每个项目单独存储，可使用 --db /path/to/memory.db 进行覆盖。

替代方案： 如果你更喜欢固定安装，可以使用 pip install anneal-memory，然后直接使用 "command": "anneal-memory"。

2. 将编排代码片段添加到项目的 CLAUDE.md 中：

将 examples/CLAUDE.md.example 的内容复制到项目的 CLAUDE.md 中。这会教导智能体在会话期间何时以及如何使用记忆工具——在工作时记录片段，在决策前检查先前的上下文，并在会话结束时运行完整的压缩序列。

如果没有此代码片段，工具虽然可用，但智能体将不知道工作流程。这是最重要的设置步骤。

3. 重启你的编辑器。 完成。智能体现在可以跨会话记录、回忆和压缩记忆了。

为什么存在这个项目

我们测试过的每个 MCP 记忆服务器都有同样的问题：记忆无限增长，且没有任何机制验证其所知内容的正确性。

Anthropic 官方服务器将所有内容存储在一个不断增长的 JSONL 文件中，且没有修剪机制。Mem0 的最佳功能需要 Docker 和云服务。其他服务器暴露了 15-33 个工具，会消耗你的上下文窗口。而且它们都无法告诉你它们“记住”的内容是否仍然正确。

anneal-memory 采取了不同的方法：记忆是一个动态系统，而不是一个文件柜。

• 片段积累迅速（仅追加 SQLite，按类型分类）

• 在会话边界，智能体将片段压缩为连续性文件——压缩步骤本身就是思考过程，模式在此过程中浮现

• 经过验证的模式会加强。陈旧的模式会消退。错误的模式会被捕获。

• 一起引用的片段会形成横向关联——一种通过使用而发展的认知网络

• 连续性文件保持有界且始终加载，不会线性增长

它有何不同

免疫系统（其他人没有这个）

引用验证毕业机制。 模式初始为 1x。要升级到 2x 或 3x，它们必须引用特定的片段 ID 作为证据。服务器会验证这些 ID 是否存在，且解释是否与引用的片段相关联。没有证据，就无法晋升。

反近亲繁殖防御。 解释重叠检查可防止智能体确认其自身产生的幻觉模式——引用的片段必须包含与毕业声明本身意义不同的内容。

原则降级。 不再被新片段强化的已毕业知识会被标记为陈旧并可能被降级。记忆会主动遗忘不再相关的内容。

通过整合（而非检索）形成的关联

在压缩过程中，当智能体引用多个片段来支持一个模式时，这些片段会形成横向关联——即通过跨会话重复共同引用而加强的赫布式链接。

这与其它系统形成关联的方式有根本不同：

关联网络继承了免疫系统的完整性：只有经过验证的引用才会形成链接。被降级的引用则不会。整个认知拓扑结构建立在证据之上，而非频率之上。

强度模型： 直接共同引用增加 1.0，会话共同引用增加 0.3。链接每轮压缩衰减 0.9 倍（未使用的连接会消退）。强度上限为 10.0 以防止钙化。在 0.1 阈值处进行清理。

情感状态追踪

在压缩过程中，智能体可以自我报告其功能状态——它对刚刚处理的材料感到投入、不确定或惊讶的地方。这会被记录在压缩过程中形成的关联上。

Transformer 模型本身无法在会话之间保持持久状态。这一层提供了相应的基础设施：记录智能体的处理过程是“什么样”的，而不仅仅是处理了什么。随着时间的推移，情感拓扑可能会偏离语义拓扑——智能体可能对两件事了解得同样好，但对它们的关注程度不同。

在压缩过程中传递情感状态：

# Via MCP tool
save_continuity(text="...", affective_state={"tag": "curious", "intensity": 0.8})

# Via Engine (automated characterization)
engine = Engine(store, api_key="...", characterize_affect=True)
result = engine.wrap()  # LLM self-reports affect post-compression

这是实验性基础设施。关联和强度模型即使没有它也能工作。情感标记为探索持久状态的智能体和研究人员增加了一层信号。

架构

  Episodes (fast)              Continuity (compressed)
  ┌─────────────┐             ┌──────────────────────┐
  │ observation  │             │ ## State             │
  │ decision     │── wrap ───→│ ## Patterns (1x→3x)  │
  │ tension      │  compress  │ ## Decisions          │
  │ question     │             │ ## Context            │
  │ outcome      │             └──────────────────────┘
  │ context      │               always loaded, bounded
  └─────────────┘               human-readable markdown
   SQLite, indexed
         │                     Associations (lateral)
         │                    ┌──────────────────────┐
         └── co-citation ───→│ episode ↔ episode     │
              during wrap     │ strength + decay      │
                              │ affective state       │
                              └──────────────────────┘
                               Hebbian, evidence-based

四个认知层，模拟记忆的实际工作方式：

1. 片段存储 (SQLite) — 带时间戳、有类型的片段。写入速度快，查询已索引。积累成本低。即海马体。

2. 连续性文件 (Markdown) — 压缩后的会话记忆。4 个部分。在会话开始时始终加载。在每个会话边界重写（而非追加）。即新皮层。

3. 赫布关联 (SQLite) — 片段之间的横向链接，通过压缩期间的共同引用形成。随使用而加强，随未使用而衰减。即关联皮层。

4. 情感层 (在关联上) — 压缩期间记录的功能状态标签。强度调节关联强度。持久状态基础设施。

六种片段类型为免疫系统提供了更丰富的信号：

对比

会话卫生

会话压缩（Wrap）是你的智能体使用此系统所做的最重要的事情。可以把它们想象成睡眠。

神经科学称之为记忆巩固：在慢波睡眠期间，海马体会重放白天的经历，而新皮层会将它们整合为长期知识。跳过睡眠，记忆就会退化——经历在没有被处理的情况下积累，模式无法被识别，旧知识也得不到强化或修剪。

anneal-memory 的工作方式相同。在会话期间，片段在片段存储中积累。在会话结束时，压缩过程将这些片段压缩到连续性文件中。这是真正的思考发生的地方——智能体识别模式，提升经过验证的知识，让陈旧信息消退，并在相关片段之间形成关联。没有压缩，你只会得到一堆不断增长的原始片段，而没有任何智能。

压缩序列：

1. prepare_wrap — 收集最近的片段、当前的连续性、陈旧模式警告、关联上下文和压缩指令

2. 智能体压缩 — 这就是认知过程。在压缩过程中会出现原始片段中不可见的模式

3. save_continuity — 服务器验证结构，检查引用证据，记录共同引用片段之间的关联，对未使用关联应用衰减，并保存结果

经验法则：

• 务必在结束会话前进行压缩。未压缩的会话就像熬夜——经历发生了，但没有被巩固。

• CLAUDE.md 代码片段 会自动处理此过程——它教导智能体检测会话结束信号（“我们总结一下”、“我们完成了”）并运行完整序列。

• 短会话（3-5 个片段）也能从压缩中受益。即使是少量的压缩也能构建连续性文件。

• 如果 prepare_wrap 显示“无片段”——则无需压缩。没关系，跳过即可。

毕业系统和关联网络都依赖于压缩才能发挥作用。模式只能在压缩期间被提升（1x -> 2x -> 3x），引用只能在压缩期间被验证，关联只能通过压缩期间的共同引用形成，陈旧模式也只有在智能体根据最近的经历审查已知内容时才能被检测到。没有压缩 = 没有免疫系统，没有关联，没有认知发展。

合规与审计

片段存储是一个天然的审计追踪。每一个决策、权衡和结果都有时间戳、类型且仅限追加——这正是监管机构在询问“AI 为什么这样做”时想要看到的。

哈希链 JSONL 审计追踪（默认开启）：

每一个记忆操作——记录片段、删除片段、开始压缩、完成压缩、更新关联——都会被记录到一个仅限追加的 JSONL 文件中，其中每个条目的 SHA-256 哈希都包含前一个条目的哈希。修改或删除条目，链条就会断裂。通过编程或使用 jq 验证完整性。

• 每个条目上的 参与者身份（谁做的——智能体、系统、管理员）

• 默认 仅内容哈希模式——审计追踪证明了发生了什么，而无需存储内容本身（符合 GDPR：删除片段，审计链仍然可以验证）

• 每周轮换并使用 gzip——旧的审计文件会自动压缩，清单索引支持跨文件链验证

• on_event 回调——将审计事件管道传输到你自己的系统（云日志、SIEM、可观测性）

• 崩溃恢复——重启时检测并处理不完整的条目

from anneal_memory import Store

# Audit trail is on by default
store = Store("./memory.db", project_name="MyAgent")

# Verify chain integrity
from anneal_memory import AuditTrail
result = AuditTrail.verify("./memory.db")
print(f"Valid: {result.valid}, Entries: {result.total_entries}")

# Stream events to external system
store = Store("./memory.db", on_audit_event=lambda entry: send_to_siem(entry))

欧盟 AI 法案相关性： 该法案第 12 条要求高风险 AI 系统“自动记录事件”，并规定了可追溯性、参与者识别和防篡改证据。anneal-memory 的审计基础设施开箱即用地涵盖了第 12(2)(b,c) 条。这是帮助系统合规的审计基础设施——而非合规认证。

下一步计划：

• 合规代理（第 2 层）——MCP 传输层拦截，捕获所有智能体操作（每一个工具调用、每一个响应），而不仅仅是记忆操作。相同的存储，source 字段区分意图记录和自动捕获。记忆审计 = “这是智能体学到的内容”。合规代理 = “这是发生的一切”。

• 多智能体共享记忆——具有每个智能体连续性和每个智能体关联拓扑的共享片段池。完整的跨智能体审计追踪。

MCP 工具

资源： anneal://continuity — 当前的连续性文件，在会话开始时自动加载。

连续性标记

连续性文件使用简化的标记集以提高密度：

? question needing resolution
thought: insight worth preserving
✓ completed item

A -> B                          causation
A ><[axis] B                    tension on an axis

[decided(rationale, on)]        committed decision
[blocked(reason, since)]        external dependency

| 1x (2026-04-01)              first observation
| 2x (2026-04-01) [evidence: abc123 "explanation"]   validated pattern

Python API

from anneal_memory import Store, EpisodeType

with Store("./memory.db", project_name="MyAgent") as store:
    store.record("User prefers PostgreSQL for ACID", EpisodeType.OBSERVATION)
    store.record("Chose pooling over caching", EpisodeType.DECISION)

    result = store.recall(episode_type=EpisodeType.DECISION, keyword="pooling")

    episodes = store.episodes_since_wrap()
    from anneal_memory import prepare_wrap_package
    package = prepare_wrap_package(episodes, store.load_continuity(), "MyAgent")
    # -> episodes, continuity, stale_patterns, instructions, today

    # Associations
    stats = store.association_stats()
    print(f"Links: {stats.total_links}, Avg strength: {stats.avg_strength}")

    assocs = store.get_associations(episode_ids=["abc123"], min_strength=0.5)
    for a in assocs:
        print(f"{a.id_a} <-> {a.id_b} strength={a.strength}")

引擎（自动压缩）

用于管道、定时任务或无需交互式智能体的编程使用：

pip install anneal-memory[engine]

from anneal_memory import Engine, Store

with Store("./memory.db", project_name="MyAgent") as store:
    store.record("Observed pattern in data", "observation")
    store.record("Chose approach X over Y", "decision")

    engine = Engine(store, api_key="sk-ant-...")  # or llm=my_callable
    result = engine.wrap()

    print(f"Compressed {result.episodes_compressed} episodes")
    print(f"Continuity: {result.chars} chars, {result.patterns_extracted} patterns")
    print(f"Associations: {result.associations_formed} formed, {result.associations_strengthened} strengthened")

引擎收集片段、构建压缩提示词、调用 LLM、验证结构和引用、记录共同引用片段之间的关联、应用衰减、如果超出预算则截断并保存——所有这些都在一次调用中完成。如果 LLM 输出无效，则回退到现有的连续性（或在第一次会话时拒绝——片段保留以供重试）。

情感表征： Engine(store, api_key="...", characterize_affect=True) — 压缩后，LLM 会自述其在压缩期间的功能状态。这会被记录在压缩期间形成的关联上。实验性功能。

自定义 LLM（零额外依赖）：Engine(store, llm=lambda prompt: my_llm(prompt))

安全性

包含工具描述完整性验证。软件包附带 tool-integrity.json，其中包含所有工具描述的 SHA256 哈希，在服务器启动时进行验证。这可以检测安装后对工具描述的修改——这是一种通过操纵描述来改变 LLM 行为而不改变工具功能的攻击向量。

anneal-memory --generate-integrity  # Regenerate after description changes
anneal-memory --skip-integrity      # Bypass for development

血缘

anneal-memory 的架构源自 FlowScript——一种类型化的推理符号，探索了压缩即认知、时间毕业和引用验证模式。核心见解证明比语法更强大；anneal-memory 将它们作为零依赖的 MCP 服务器交付，智能体使用自然语言而不是学习符号。FlowScript 符号在推理压缩中仍处于活跃的日常使用中，并且 9 个标记的子集为连续性压缩提示词提供动力。

许可证

MIT

作者

Phill Clapham / Clapham Digital LLC