Muscle Memory

muscle-mem 是一个专为 AI Agent 设计的行为缓存库。

它是一个 Python SDK，能够在 Agent 执行任务时记录其工具调用模式。当再次遇到相同任务时，它会自动重放这些已学习的轨迹（trajectories）；如果检测到边缘情况（edge cases），则会自动回退到 Agent 模式。

muscle-mem 的目标是将 LLM 从重复性任务的核心路径中移除，从而提高运行速度、降低不确定性，并消除那些“本来写个脚本就能解决”的任务所带来的大量 Token 成本。

这是一个全新的探索领域，欢迎提供任何反馈！

• 阅读 Muscle Mem - 从 Agent 中移除 LLM 调用 以获取更多背景信息
• 加入 Muscle Mem Discord 进行交流

开发日志

• 2025年5月7日 - 首个可用演示
• 2025年5月8日 - 开源
• 2025年6月1日 - 参数化（Parameterization）和标签（Tags）功能合并

工作原理

muscle-mem 不是另一个 Agent 框架。

你可以按需实现自己的 Agent，然后将其接入 muscle-mem 的引擎中。

当给定一个任务时，引擎会：

1. 使用 Checks（检查）来确定环境是否之前出现过（缓存命中），或者是一个新环境（缓存未命中）。
2. 执行任务，方式如下：
   • 如果缓存命中，则使用检索到的轨迹。
   • 如果缓存未命中，则将任务交给你的 Agent 处理。
3. 收集工具调用事件，并将其作为新轨迹添加到缓存中。

核心在于缓存验证

为了向你的 Agent 添加安全的工具复用功能，关键问题在于缓存验证。请问自己：

对于我们提供给 Agent 的每个工具，环境中哪些特征可以用来判断执行该操作是否安全？

如果你能回答这个问题，你的 Agent 就能拥有“肌肉记忆”（Muscle Memory）。

API

安装

pip install muscle-mem

Muscle Mem 的 API 目前处于 v0 版本，小版本更新可能会引入破坏性变更，因此我们强烈建议在生产环境中使用时锁定特定版本。

引擎 (Engine)

引擎封装了你的 Agent，并作为任务的主要执行者。

它管理着自己的历史轨迹缓存，并决定何时调用你的 Agent。

from muscle_mem import Engine

engine = Engine()
engine.set_agent(your_agent).finalize()

# 你的 agent 可以独立调用
your_agent("do some task")

# 引擎提供相同的接口，但具备肌肉记忆功能
engine("do some task")
engine("do some task") # 缓存命中

该引擎要求你的 Agent 是可调用的（callable），即作为一个函数或通过 __call__ 方法实现。传递给 engine() 的任何参数和关键字参数都会直接传递给你的 Agent。我们的示例中使用的是字符串，但它也可以是 ChatCompletion 消息列表或任何你的 Agent 可调用对象所期望的格式。

默认情况下，轨迹存储在单个缓存中。你可以使用任务描述对轨迹进行标签标记，以创建独立的存储桶。

engine("do some task", tags=["some task"]) # 缓存未命中
engine("do some task", tags=["some task"]) # 缓存命中

engine("do some task", tags=["different task"]) # 缓存未命中
engine("do some task", tags=["different task"]) # 缓存命中

工具插桩 (Tool Instrumentation)

装饰器用于对执行动作的工具进行插桩，以便引擎能够在 Agent 执行动作时记录它们。

函数 (Functions)

使用 @engine.function 装饰器对简单的函数工具进行插桩：

from muscle_mem import Engine

engine = Engine()

@engine.function()
def hello(name: str):
	print(f"hello {name}!")
	
hello("world") # hello 的调用被存储，参数为 name="world"

方法 (Methods)

使用 @engine.method 装饰器对绑定到对象的类方法进行插桩。

这允许通过 self 参数进行有状态 API 客户端的依赖注入，例如 self.db.get_user(id) 或 self.model.generate(prompt)。

from muscle_mem import Engine

engine = Engine()

class SomeClient:
   @engine.method()
   def hello(self, name: str):
       print(f"hello {name}!")

client = SomeClient()

client.hello("world") # SomeClient.hello 的调用被存储，参数为 name="world"

请注意，由于运行时对象 (self) 无法序列化，因此 self 不会被包含在轨迹中。

为了让引擎能够重放基于方法（method-based）的工具，必须显式传递该对象的实例，以便在重放时重新注入为 self。

使用 engine.set_context() 向引擎提供运行时对象。

engine = (
    engine
    .set_agent(your_agent)
    .set_context(client) # client 对象将在 SomeClient.hello 中作为 self 被注入
    .finalize()
)
engine("say hello world!")

engine.finalize() 是一个可选的检查，用于确保在调用引擎之前，你已经提供了所有必要的依赖项。

检查 (Check)

Check 是缓存验证的基本构建模块。它们决定了执行给定操作是否安全。

每个 Check 封装了：

• 一个 capture 回调，用于从当前环境中提取相关特征。
• 一个 compare 回调，用于进行判断。