tigerless-labs/agent-memory

agent-memory는 AI 에이전트에게 세션 간에 지속되는 영구 메모리를 제공합니다. 세션이 끝날 때 에이전트가 배운 모든 것을 잊어버리는 대신, 이 시스템은 메모리를 일반 Markdown 파일로 저장하고 빠른 검색을 위해 인덱싱하며, 에이전트가 필요한 세부 수준에서 정확히 필요한 것을 검색할 수 있게 합니다.

핵심 아이디어

대부분의 AI 어시스턴트(예: Claude Code, Codex, Muse)는 세션이 닫히면 모든 것을 잊어버립니다. Agent-memory는 디스크에 메모리 저장소를 유지하여 이를 해결합니다. Markdown 파일이 단일 진실 소스입니다. 에이전트는 ls 및 grep과 같은 도구로 직접 읽을 수 있습니다. 인덱스(SQLite)는 순전히 캐시로 파일 옆에 있으므로 실제 메모리를 잃지 않고 인덱스를 삭제하고 다시 빌드할 수 있습니다.

검색 작동 방식

에이전트의 컨텍스트에 큰 텍스트 덩어리를 붙여넣는 대신, agent-memory는 관련 Markdown 파일의 경로 목록을 반환합니다. 각 히트에는 한 줄 요약과 점수가 포함됩니다. 그런 다음 에이전트는 원하는 깊이로 파일을 엽니다: 요약만, 제목만, 전체 본문, 또는 해당 메모리로 이어진 원시 소스 메시지까지. 이렇게 하면 에이전트는 실제로 필요한 것에 대해서만 비용을 지불합니다.

주요 기능

• 메모리를 찾는 세 가지 방법 – 세션 시작 시 주입되는 결정적 MEMORY.md, 순위가 매겨진 BM25 검색(선택적 벡터 검색 포함), 그리고 일반 파일 시스템 자체. 한 방법이 놓치면 다른 방법이 잡아냅니다.
• 쓰기 범위는 자동 – 시스템은 자연스러운 경계(예: 세션 종료 시)에서 메모리를 저장하므로 에이전트가 기억할 필요가 없습니다. 세션의 전체 사본이 먼저 보관되므로 증류기가 무언가를 놓쳐도 아무것도 잃지 않습니다.
• 파일이 진실이고 인덱스는 단지 캐시 – 지식을 잃지 않고 .index/를 지우고 다시 빌드(mem rebuild)할 수 있습니다. 이는 약속이 아니라 테스트로 강제됩니다.
• 독립적인 "관리" 계층 – 유휴 시간(예: 밤새)에 시스템은 통합, 업데이트, 삭제 제안을 수행하지만 삭제는 확인한 경우에만 발생합니다. 또한 시간 여행 회상(지난 화요일 기준으로 무엇을 알았나?)을 지원합니다.
• 라이브러리 내 API 키, LLM 호출 없음 – 판단은 호스트 에이전트 자체 CLI에서 오므로 모든 쓰기가 트랜스크립트에 표시되고 청구 표면이 없습니다.

저장소 레이아웃

모든 것이 하나의 디렉토리(기본 ~/agent-memory-store)에 있습니다. 포함 내용:

• MEMORY.md – 메모리당 한 줄의 루트 인덱스
• config.toml – 모든 조정 가능한 매개변수
• decision/ – 실제 메모리 파일, 메모리당 하나, 유형 및 그룹별로 구성
• archive/ – 원시 세션 및 출처 증거의 추가 전용 복사본
• .index/ – 재구성 가능한 검색 인덱스 및 액세스 로그
• .state/ – 런타임 부기(쓰기 잠금 및 증류 워터마크 등)

시작하기

Python 3.12+ 및 uv가 필요합니다. 체크아웃에서 설치:

git clone https://github.com/tigerless-labs/agent-memory.git
cd agent-memory
uv sync --all-packages

그런 다음 저장소를 초기화하고 첫 번째 메모리를 작성합니다:

mem init
mem record --type decision --field project=agent-memory \
  --abstract "Markdown files are the single source of truth" \
  --body "Indexes are rebuildable caches."
mem recall "source of truth"

또한 한 줄로 Claude Code, Codex 또는 Muse에 연결할 수 있습니다:

mem setup --host claude-code

작동하나요?

README에는 LongMemEval‑S(표준 메모리 평가)에 대한 벤치마크가 포함되어 있습니다. 제한된 건초 더미에서 agent-memory는 52.9%의 통합 정확도를 얻었고 MemCore는 35.8%, 메모리 없음은 5.8%였습니다. 또한 교차 호스트 테스트를 통과합니다: 한 호스트(예: Claude Code)가 작성한 메모리는 다른 호스트(예: Codex)가 특정 세부 사항을 그대로 찾을 수 있습니다.

정직성에 대한 참고

벤치마크 수치는 테스트 설정이 더 작은 건초 더미를 사용하므로 게시된 LongMemEval 점수와 직접 비교할 수 없습니다. 이는 쓰기 전략 연구이지 규모 연구가 아닙니다. 프로젝트는 또한 전체 실험 프로토콜과 원시 데이터를 저장소에 포함하므로 결과를 직접 확인할 수 있습니다.

요약: agent-memory는 클라우드 서비스나 API 키 없이 소유한 일반 파일을 사용하여 AI 에이전트가 세션 간에 사물을 기억할 수 있게 합니다.