Muscle Memory

muscle-mem는 AI 에이전트를 위한 행동 캐시입니다.

이는 에이전트의 툴 호출 패턴을 해결하는 과정에서 기록하고, 해당 작업이 다시 등장할 때 학습된 궤적을 결정론적으로 재연하며, 에지 케이스가 감지되면 에이전트 모드로 후퇴하는 Python SDK 입니다.

muscle-mem의 목표는 반복적인 작업을 위해 LLM 을 핫패스 (hotpath) 에서 제거하고, 속도 향상, 변동성 감소, 그리고 그냥 스크립트가 될 수 있었을 많은 경우를 위한 토큰 비용 절감입니다.

이는 아직 탐험되지 않은 영역이므로 모든 피드백을 환영합니다!

• Muscle Mem - Removing LLM calls from Agents 를 더 읽으세요
• Muscle Mem discord 에 참여하세요

Dev Log

• 2025 년 5 월 7 일 - 첫 번째 작동하는 데모
• 2025 년 5 월 8 일 - 오픈 소스화
• 2025 년 6 월 1 일 - 파라미터화와 태그 병합 <br>

<br>

동작 원리

muscle-mem는 다른 에이전트 프레임워크가 아닙니다.

원래대로 에이전트를 구현한 후, muscle-mem의 엔진에 플러그인합니다.

작업이 주어지면 엔진은:

1. Checks 를 사용하여 환경이 이전에 본 바 (캐시 히트) 인지 새로운 것 (캐시 미스) 인지 결정합니다
2. 작업을 수행하며,
   • 캐시 히트 시 검색된 궤적을 사용하거나,
   • 캐시 미스 시 작업을 에이전트에 전달합니다.
3. 툴 호출 이벤트를 수집하여 새로운 궤적으로 캐시에 추가합니다

모든 것이 캐시 유효성 검증에 관한 것입니다

에이전트에 안전한 도구 재사용을 추가하기 위한 핵심 질문은 캐시 유효성 검증입니다. 다음을 스스로에게 물어보세요:

우리가 에이전트에 제공하는 각 도구에 대해, 환경의 어떤 기능이 해당 행동을 수행하는 것이 안전한지 여부를 나타낼 수 있는지를 알 수 있습니까?

이를 답변할 수 있다면, 당신의 에이전트는 Muscle Memory 를 가질 수 있습니다.
<br>
<br>

API

설치

pip install muscle-mem

Muscle Mem 의 API 는 v0 이며 소수 버전에서 깨질 수 있으므로 프로덕션 사용에는 특정 버전을 고정하는 것을 강력히 권장합니다.

엔진

엔진은 에이전트를 감싸고 작업을 실행하는 주요 실행자 역할을 합니다.

이것은 이전 궤적의 자체 캐시를 관리하고, 에이전트를 호출할 때를 결정합니다.

from muscle_mem import Engine

engine = Engine()
...

에이전트가 callable 해야 함을 예상하며, 함수 또는 __call__ 메서드로 할 수 있습니다. engine() 에 전달된 모든 인수와 키워드 인수는 에이전트에 직접 전달됩니다. 예제에서는 문자열을 사용하지만, 이는 ChatCompletion 메시지 목록이나 에이전트 callable 이 기대하는 것이 될 수 있습니다.

기본적으로 궤적은 단일 캐시에 저장됩니다. 작업을 설명하는 태그로 궤적을 태그하여 고유한 버킷을 생성할 수 있습니다.

engine("do some task", tags=["some task"]) # cache miss
engine("do some task", tags=["some task"]) # cache hit

...

도구 인스트루멘테이션

엔진이 에이전트가 취하는 행동을 기록할 수 있도록 행동 수행 도구를 장식기 (decorator) 를 사용하여 악용합니다.

함수

단순 함수 도구를 악용하기 위해 @engine.function 장식기를 사용하세요:

from muscle_mem import Engine

engine = Engine()
...

메서드

객체에 부착된 메서드를 악용하기 위해 @engine.method 장식기를 사용하세요.

이를 통해 self.db.get_user(id) 또는 self.model.generate(prompt) 와 같은 상태ful API 클라이언트를 self 인수를 통해 의존성 주입할 수 있습니다.

from muscle_mem import Engine

engine = Engine()
...

runtime 객체 (self) 는 직렬화할 수 없으므로, trajectory 에서 self 가 생략됩니다.

엔진이 메서드 기반 도구를 재생하려면, 재 주입할 self 인스턴스를 명시적으로 전달해야 합니다.

엔진에 runtime 객체를 제공하려면 engine.set_context() 를 사용하세요.

enGINE = (
    ENGINE
    .set_agent(your_agent)
...

engine.finalize() 는 엔진을 사용하기 전에 모든 의존성을 제공했는지 확인하는 선택적 체크입니다.

Check

Check 는 캐시 유효성 검증의 기본 구성 요소입니다. 이는 주어진 행동을 실행할 수 있는지 여부를 결정합니다.

각 Check 는 다음을 캡슐화합니다:

• 현재 환경에서 관련 기능을 추출하기 위한 capture 콜백
• 현재 환경이 캐시된 환경과 일치하는지 결정하기 위한 compare 콜백

Check(
    capture: Callable[P, T],
    compare: Callable[[T, T], Union[bool, float]],
...

각 도구에 Check 를 연결하여 캐시 유효성 검증을 강제할 수 있습니다. @engine.function (또는 @engine.method) 에 이를 할 수 있습니다.

이것은 도구 호출 전에 사전 체크로 수행될 수 있으며 (쿼리 시간 유효성 검증에도 사용됨), 또는 도구 호출 후 사후 체크로 수행될 수도 있습니다.

아래는 hello 도구의 사용을 캡처하고, 타임스탬프와 1 초의 만료 시간을 캐시 유효성 검증 Check 메커니즘으로 사용하는 가상의 예제입니다.

# our capture implementation, taking params and returning T
def capture(name: str) -> T:
    now = time.time()
...

Top Level Parameters

Muscle Mem 은 기본적으로 도구 호출의 모든 인수를 정적 값으로 저장합니다.

이는 항상 바람직하지 않을 수 있으며, 일부 인수는 실행마다 동적으로 변경될 수 있습니다. 예를 들어, First Name 텍스트 필드를 채우는 폼 입력 봇은 type("John") 도구 호출을 수행하지만, 향후 실행에서는 다른 이름을 사용하려는 방법을 원할 수 있습니다.

Muscle Mem 은 top level params 시스템을 통해 이를 해결하며, 이는 실행마다 동적으로 변경될 수 있는 인수를 지정할 수 있게 합니다.

여러 에이전트를 호출하기 전에 runtime 에서 값이 알려지면 (아마도 이미 프롬프트 템플릿으로 작성되었을 것입니다), engine() 의 선택적 params 인수로 top level 파라미터로 표시할 수 있습니다.

@engine.function()
def type(text: str):
    print(text)
...

트랙터 기록 중, 기본 도구 호출이 top level 파라미터와 직접적으로 일치하는 인수를 볼 경우, 엔진은 이를 동적으로 표시하고 키에 따라 top level 파라미터로 매핑합니다.

현재 구현은 도구 인수의 정확한 문자열 매칭을 사용하여 top level 파라미터에서 유래했는지 식별합니다. 모든 도구 인수는 LLM 에서 왔으므로 문자열 직렬화 가능이라고 가정합니다.

Putting it all together

아래는 위의 모든 코드 스니펫을 결합한 스크립트입니다.

from dataclasses import dataclass
from muscle_mem import Check, Engine
import time
...

더 현실적인 예제는 컴퓨터 사용 에이전트 구현을 참조하세요:

https://github.com/pig-dot-dev/muscle-mem/blob/main/examples/cua.py

---

Call To Action

이 시스템이 발전함에 따라 모든 피드백을 환영합니다!

다음 사항을 고려해 주세요:

1. Muscle Mem discord 에 참여하세요
2. muscle-mem repo 를 테스트하고 별점을 주세요