Muscle-Mem

Muscle-Mem is an open source Python tool hosted on GitHub and developed by pig-dot-dev. It aims to provide behavioral caching capabilities for AI agents to help reduce large language model (LLM) calls in repetitive tasks, thereby increasing runtime speed, reducing variability, and saving costs.Muscle-Mem reuses cached behaviors directly when the same task is encountered by logging the AI agent's tool invocation patterns, and only invokes the agent's logic when a new scenario is detected. Its core mechanism is cache validation, which determines whether it is safe to reuse caches by checking environment characteristics. This tool is suitable for developers who need to optimize automated tasks, especially dealing with highly repetitive workflows. The official documentation and sample code are clear, the community feedback is positive, and it is suitable for Python developers and AI automation.

Function List

• Behavioral Caching: Record the AI agent's tool invocation patterns and cache the behavior for reuse.
• cache validation: Ensure that caching behavior is secure in a given context through pre-check and post-check mechanisms.
• Tool Decorator: supports the use of @engine.tool Decorator adds caching functionality to the tool.
• environmental awareness: Determine cache hits (cache-hit) or misses (cache-miss) based on environment characteristics.
• Flexible Integration: Allows developers to customize the proxy logic and plug it into the Muscle-Mem engine.
• Efficient implementation: Reduce calls to large language models and improve task execution speed.

Using Help

Installation process

Muscle-Mem is a Python library with a simple installation process. Here are the detailed steps:

1. environmental preparation
   Make sure you have Python 3.7 or above installed on your system. This can be checked with the following command:

   python --version
   

   Virtual environments are recommended to avoid dependency conflicts, for example:

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate     # Windows
   

2. Cloning warehouse or installation
   Muscle-Mem is currently distributed through a GitHub repository. Clone the repository locally:

   git clone https://github.com/pig-dot-dev/muscle-mem.git
   cd muscle-mem
   

   Then install the dependencies:

   pip install -r requirements.txt
   

   If the repository provides setup.py, which can be installed with the following command:

   pip install .
   

3. Verify Installation
   Once the installation is complete, import the Muscle-Mem module and check for correctness:

   from muscle_mem import Engine
   print(Engine())
   

   If no errors are reported, the installation was successful.

Basic use

At the heart of Muscle-Mem are Engine class, which is used to manage the caching logic of agents and tools. The following are detailed steps on how to use Muscle-Mem:

1. Initializing the engine
   Create a Engine Example:

   from muscle_mem import Engine
   engine = Engine()
   

2. Define tools and add caching
   utilization @engine.tool The decorator defines the instrumented function and passes the pre_check maybe post_check Add cache validation. For example, define a simple hello function:

   from dataclasses import dataclass
   import time
   from muscle_mem import Check
   # 定义环境特征的数据结构
   @dataclass
   class T:
   name: str
   time: float
   # 捕获环境特征
   def capture(name: str) -> T:
   now = time.time()
   return T(name=name, time=now)
   # 比较环境特征，验证缓存有效性
   def compare(current: T, candidate: T) -> bool:
   diff = current.time - candidate.time
   return diff <= 1  # 缓存1秒内有效
   # 定义工具并添加缓存检查
   @engine.tool(pre_check=Check(capture, compare))
   def hello(name: str):
   time.sleep(0.1)
   print(f"hello {name}")
   

3. Running Agents
   Define a proxy function and register it with the engine. Example:

   def agent(name: str):
   for i in range(9):
   hello(name + " + " + str(i))
   engine.set_agent(agent)
   

4. Execute the task and check the cache
   The call engine runs the proxy and checks for cache hits:

   cache_hit = engine("erik")  # 首次运行，缓存未命中
   print(cache_hit)  # False
   cache_hit = engine("erik")  # 再次运行，缓存命中
   print(cache_hit)  # True
   time.sleep(3)  # 等待缓存失效
   cache_hit = engine("erik")  # 缓存失效，重新运行
   print(cache_hit)  # False
   

Featured Function Operation

Cache validation mechanism

The core feature of Muscle-Mem is cache validation through the Check class implementation. The developer needs to define two functions:

• capture: Capture current environment characteristics such as time, input parameters, etc.
• compare: Compare the current environment with the cached environment to determine whether the cache can be reused.

In the above example, thecapture recording the time and parameters of the call.compare Check if the time difference is within 1 second. This mechanism ensures the security of the cache and avoids multiplexing behavior in inappropriate scenarios.

Tool reuse

Muscle-Mem allows adding cache support for multiple tools. For example, separate cache validation logic can be defined for tools such as file operations, API calls, and so on. The developer simply writes the corresponding capture cap (a poem) compare function with the @engine.tool Decorator binding.

Advanced Use

1. Multi-tool management
   If your agent needs to call multiple tools, you can define separate cache validation for each tool. Example:

   @engine.tool(pre_check=Check(capture_file, compare_file))
   def read_file(path: str):
   with open(path, 'r') as f:
   return f.read()
   @engine.tool(pre_check=Check(capture_api, compare_api))
   def call_api(url: str):
   import requests
   return requests.get(url).text
   

2. Dynamic Caching Policy
   Developers can adjust the caching policy according to task requirements. For example, extending the cache validity time or dynamically adjusting it based on input parameters compare Logic.
3. Debugging Cache
   Muscle-Mem supports checking cache hits , developers can log or return value to determine whether the cache is in effect , to facilitate debugging and optimization .

caveat

• assure capture cap (a poem) compare The function logic is correct, otherwise it may lead to cache misuse.
• Cached data is stored in memory and is suitable for short-term tasks. For long-term tasks, it is recommended to extend Muscle-Mem to support persistent storage.
• Tool functions should be kept as simple as possible to avoid complex logic affecting caching efficiency.

application scenario

1. Automation Script Optimization
   Muscle-Mem is suitable for optimizing automation scripts that run repeatedly. For example, in a data processing pipeline, an agent needs to call the same preprocessing functions several times. By caching the execution results of these functions with Muscle-Mem, runtime can be significantly reduced.
2. AI Agent Task Acceleration
   In AI-driven automation tasks, such as web crawlers or customer service bots, Muscle-Mem caches common user request processing logic, reducing calls to large language models and improving response times.
3. development and testing environment
   When testing AI agents, developers can use Muscle-Mem to cache the execution results of test cases, avoiding repeated running of time-consuming tasks and improving development efficiency.

QA

1. What programming languages does Muscle-Mem support?
   Muscle-Mem is a Python library that currently only supports the Python development environment. It may be extended to other languages in the future, but there are no official plans to do so.
2. How do I secure my cache?
   Muscle-Mem Adopted Check class capture cap (a poem) compare Functions validate environment characteristics. Developers need to design reasonable validation logic based on the tool's functionality to ensure that the cache is reused only in secure scenarios.
3. Where is the cached data stored?
   By default, cached data is stored in memory. If persistent storage is required, developers can extend Muscle-Mem to save the cache using a database or file system.
4. Does it support multi-threaded or asynchronous operations?
   Muscle-Mem's official documentation does not explicitly mention multi-threading support, but its design is based on Python and could theoretically be extended to support asynchronous operations through asynchronous frameworks such as asyncio.