agent-memory

세션을 종료하는 에이전트는 그 세션에서 학습한 모든 것을 잊어버립니다. agent-memory는 이를 해결해 주는 런타임으로, 코딩 에이전트뿐만 아니라 모든 에이전트에 적용할 수 있습니다. 하나의 스토어에 있는 Markdown 파일들이 유일한 진실의 원천(single source of truth)이며, 그 옆의 SQLite 인덱스는 언제든지 삭제할 수 있는 캐시입니다. Claude Code, Codex CLI, Muse Code 등 셸 명령을 실행할 수 있는 모든 것이 이 스토어를 공유합니다.

검색은 로컬에서 순위가 매겨지며(ranked), 붙여넣기된 텍스트 대신 경로를 통해 답변합니다. 에이전트가 기록하는 것을 기억하기를 기다릴 필요 없이, 쓰기는 대화 경계에서 발생합니다. 이후 슬립 타임 패스(sleep-time pass)는 자체 클럭으로 값에 따라 통합하고 잊어버립니다. 이 모든 과정에 API 키가 필요하지 않습니다.

에이전트 메모리는 두 가지 아키텍처 라인을 따라 성장해 왔습니다. 하나는 **검색 엔진(retrieval engine)**을 구축합니다 — 임베딩, 지식 그래프(knowledge graph), 순위 지정 파이프라인(ranking pipeline) — 이 올바른 것을 찾아주지만, 에이전트에게 검사할 수 없는 불투명한 청크(opaque chunk)와 마이그레이션할 수 없는 스토어를 넘겨줍니다. 다른 하나는 에이전트에게 **파일 시스템(filesystem)**을 제공합니다 — Markdown 파일로, ls 및 grep으로 탐색 가능하며, 읽기 쉽고 실행 비용이 들지 않지만, 순위를 매기지 못하고 트리 구조가 목록의 크기를 초과하는 순간 확장성이 멈춥니다.

agent-memory는 이 두 가지를 하나의 스토어에 담았습니다. 즉, 검색 엔진이 에이전트가 직접 읽을 수 있는 파일 시스템을 인덱싱합니다. 관계(Relations)는 메모리 내 링크로 존재하며, 로컬 인덱스가 순위를 매기고, 모든 히트(hit)는 디스크의 전체 Markdown 파일로 해결됩니다. Recall은 그래프와 벡터 검색의 정밀도를 얻으면서도 에이전트가 탐색할 수 있는 평범한 디렉터리를 포기하지 않습니다 — 그리고 읽기 경로에서 모델을 호출하거나 네트워크를 가로지르는 것이 없기 때문에 빠릅니다.

Recall은 컨텍스트에 텍스트를 붙여넣지 않습니다. 이는 L0 목록(one-line abstract, file path, anchor, score)으로 답변하며, 에이전트는 작업에 필요한 깊이만큼 원하는 것을 열어봅니다:

mem recall "why files instead of a database" # L0 목록, 기본 8개 항목
mem recall "why files instead of a database" --limit 20 # 더 많은 Memory 후보군
mem read <name> --level outline # 제목만; 또는 abstract, 또는 전체
...

Index 라인 → abstract → 전체 파일 → 원본 자료: 각 계단은 이전보다 한 자릿수(order of magnitude) 이상 비용이 많이 들며, 각각은 멈출 수 있는 지점입니다. 긴 파일은 두 개의 무료 계단을 추가합니다 — 일치한 앵커와 읽기 시간에 계산된 개요입니다.

**세 가지 읽기 트랙을 갖추어 하나가 실패해도 전체가 실패하지 않습니다.**DeterministicMEMORY.md

세션 시작 시 주입되며; 원하는 경우 RRF로 벡터 플러그인이 융합된 FTS5 인덱스에 대한 BM25 검색과,
그리고 ls와 grep으로 접근 가능한 순수한 디렉터리 트리입니다.

동일 디렉터리의 memory는 무료 이웃이며, 프런트매터(frontmatter)의 links는 그래프 데이터베이스 없이도 그 아래에 그래프를 담고 있습니다.**쓰기 커버리지(Write coverage)는 시스템의 역할이지 에이전트의 판단이 아닙니다.**증류(Distillation)는 경계에서 트리거되며 작업을 지연시키지 않고 실행됩니다. 전체 트레이스(full trace)가 먼저 복사되므로, "증류기에 의해 놓쳤다"는 것이 결코 "시스템에 의해 손실되었다"는 의미가 아닙니다.파일이 진실이며, 모든 인덱스는 재구축 가능한 캐시입니다.rm -rf .index/ && mem rebuild

은 아무 지식도 잃지 않습니다 — 이는 문서에 약속된 것이 아니라 테스트를 통해 강제됩니다. 당신의 memory는 이 시스템 외부에서도 검색 가능하고, git으로 관리 가능하며, 휴대 가능합니다.**독립적인 시계로 작동하는 진정한 Manage 레이어입니다.**권한 계층을 갖춘 수면 시간 통합(Sleep-time consolidation): 방치된 패스는 추가 및 업데이트를 할 수 있으며, 삭제는 항상 당신이 확인해야 하는 제안 형태로만 도착합니다. 모든 경쟁자는 M(Memory)이 없거나 쓰기 경로에 숨겨 놓았습니다. Supersede는 체인을 온전하게 유지하고 recall --as-of

은 특정 날짜 기준으로 답변하므로, 업데이트가 결코 파괴적이지 않습니다.**라이브러리 내부에 LLM 클라이언트를 두지 않았습니다.**설치할 키도 없고 청구되는 면적(billing surface)도 없습니다: 판단은 호스트 에이전트의 자체 CLI에서 빌려오며, 이는 모든 쓰기를 당신의 기록에 보이게 유지합니다.

One memory is one file. valid_from

및 선택적 invalid_at

이 유효성 간격을 정의합니다.
교체되거나 삭제된 파일은 recall --as-of 및 트레이스에 저장됩니다. 현재 리콜, MEMORY.md, BM25, 그리고 벡터는 invalid_at가 없는 파일을 사용합니다.
프론트매터(Frontmatter)에는 안정적인 이름, 한 문장 초록, 유형 및 스키마 필드, 타임스탬프, 링크, 가중치, 출처(provenance)가 포함되며, 본문은 자유 마크다운입니다. status를 가진 기존 파일은 초기화 없이 로드됩니다.

명시적 링크는 동일한 저장소 내의 서로 다른 활성 메모리를 명명해야 합니다. correct --link는 전체 목록을 대체하고; correct --clear-links는 모든 링크를 제거합니다. MCP의 memory_correct는 동일한 작업에 대해 links: [...]와 links: []를 사용합니다. 링크를 생략하면 관련 없는 수정 과정에서도 역사적 관계가 유지됩니다. 운영 경계 설계(operation boundary design)를 참조하십시오.

에이전트는 메모리를 수정하기 위해 mem correct <name>을, 후속 메모리(successor)를 생성하기 위해 mem record --supersedes <old>를, 기존의 후속 메모리를 사용하기 위해 mem supersede <old> <new>를, 메모리를 원자적으로 결합하기 위해 mem merge <first> <second> --abstract ... --body ...를, 그리고 현재 유효성을 종료하기 위해 mem delete <name>을 사용할 수 있습니다. 분할(Splitting)은 새로운 record 호출 후 원래의 delete로 이루어집니다. 코어는 파일 범위, 관계, 출처, 동시 쓰기 등을 확인하며; Sleep은 방치된 작업을 위한 제안 및 용량 제한을 유지합니다.

LongMemEval-S에서 경계가 지정된 건초 더미(haystack)를 사용하여 120 에피소드 동안 claude -p (Haiku 4.5)를 호스트로, 보정된 Sonnet 5 심사위원 하나와 팔당(arm)당 두 번의 시험 재현을 측정했습니다.

절대적인 수치(Absolute numbers)는 발표된 LongMemEval 점수와 비교할 수 없습니다. 왜냐하면 이 테스트베드(haystack)가 에피소드당 12 세션으로 제한되어 있기 때문에, 이는 코퍼스 크기 연구라기보다는 쓰기 전략(write-strategy)에 대한 연구이기 때문입니다. 시스템 대 시스템(system-to-system) 행은 쓰기와 읽기를 함께 처리하므로 엔드투엔드 비교이며 어느 한쪽 부분에도 출처를 부여하지 않습니다.

하나의 스토어, 세 개의 호스트: Claude Code, Codex CLI, 그리고 Hermes 패스를 거치는 9쌍의 순서화된 작성기/읽기기(writer/reader) 쌍을 통해, 한 호스트의 셸이 기록한 내용을 다른 호스트가 발견하며 구체적인 내용까지 온전히 유지합니다. 메모리가 없는 상태에서의 풀링된 네트워크 기여도는 2/36에서 13/36으로 증가했으며, p값은 0.0074입니다.

어떤 측정값이 결과로 간주되는지 결정하는 프로토콜, 전체 원장(full ledger), 그리고 원시 실행 기록(raw run records)은 작업 디렉터리의 docs/experiments.md와 experiments/에 있습니다. 이 파일들은 Git 히스토리와 함께가 아니라 소스 코드와 함께 배포됩니다.

Python 3.12 이상과 uv가 필요합니다. 아직 PyPI에 릴리스된 버전이 없으므로, 체크아웃(checkout)을 통해 설치해야 합니다:

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

이렇게 하면 mem, mem-mcp, 그리고 mem-hook이 .venv/bin에 빌드됩니다. 체크아웃 내부에서 uv run mem을 실행하여 접근할 수 있으며, 이 디렉터리를 시스템의 PATH에 추가하여 셸에서도 사용할 수 있게 합니다:

export PATH="$PWD/.venv/bin:$PATH"

mem init

스토어는 기본적으로 ~/agent-memory-store를 사용하며, 만약 다른 곳에 두고 싶다면 export AGENT_MEMORY_STORE를 사용하고, 이 셸뿐만 아니라 에이전트가 실행되는 모든 곳에서 환경 변수를 설정해야 합니다.

하나의 메모리를 작성하고 다시 찾아낸 다음, 인덱스를 버려도 아무것도 손실되지 않았음을 증명해 보세요:

mem record --type decision --field project=agent-memory \
--abstract "Markdown 파일이 유일한 진실 공급원이다" \
--body "인덱스는 재구축 가능한 캐시이다."
...

mem setup --host claude-code
mem setup --host codex
mem setup --host muse-code --provider openrouter

세 가지 명령어 모두 동일한 파이프라인을 사용합니다: 호스트를 조사하고, Store를 초기화하거나 확인하며, 호스트 설정을 안전하게 병합하고, 라이프사이클 훅과 스킬을 설치하며, 제공업체별 설정을 수행한 다음, 사전 점검(preflight)을 실행합니다. 성공적인 명령어는 status: READY로 끝납니다.

; 작성된 설정만으로는 준비되었다고 간주되지 않습니다. 설정을 다시 실행하는 것은 안전하며 관리되는 훅, 스킬, 제공업체 라우팅 또는 MCP 항목을 중복하지 않습니다. 기존의 관련 없는 호스트 설정은 유지되며, 충돌하는 설정은 대체되는 대신 실패(fails closed)합니다.

일반적인 방식으로 비기본 Store를 사용하십시오. setup은 절대 경로를 모든 설치된 훅에 고정합니다:

AGENT_MEMORY_STORE=/absolute/path/to/store mem setup --host codex

나중에 동일한 검사를 실행하거나, 설정 실패 후 정확한 오류 계층을 얻으십시오:

mem doctor --host claude-code
mem doctor --host codex
mem doctor --host muse-code --provider openrouter

diagnostics는 호스트/설정/Store/훅/추론기(reasoner) 실패를 구별하며, Muse의 경우 자격 증명(credential), 프록시, 인증, 모델 카탈로그, 모델 가용성 및 실시간 요청(live-request) 실패를 구분합니다. Codex도 비활성화된 훅, 읽기 전용 기본 샌드박스, 그리고 일회성 훅 신뢰 검토에 대한 보고서를 제공합니다. Codex 사용자 훅은 여전히 Codex의 신뢰 프롬프트의 적용을 받습니다. setup과 doctor는 기본적으로 최소한의 실시간 추론기 요청을 수행하며, --no-live가 오프라인 검사를 위해 사용 가능하지만, 준비 상태가 입증되지 않았기 때문에 의도적으로 FAILED를 보고합니다.

Store가 Codex 작업 공간 밖에 있는 경우에도 SessionStart 주입 및 경계 훅은 여전히 실행되지만, 에이전트가 시작하는 CLI 호출에는 Store 접근 로그에 쓰기 액세스 권한이 필요합니다. Doctor는 Store가 sandbox_workspace_write.writable_roots에 의해 커버되거나, Codex가 --add-dir <store>로 실행될 때까지 CODEX_STORE_ACCESS_REVIEW를 보고합니다.
setup은 샌드박스 권한을 조용히 확장하지 않습니다.

호스트도 agent-memory stdio MCP 서버를 받아야 하는 경우 setup에 --mcp를 전달하십시오. MCP를 사용하는 에이전트는 mem-mcp를 통해 동일한 핵심 호출(memory_recall 등)을 받습니다.

, memory_read, memory_trace, memory_record, memory_correct, memory_supersede, memory_merge, memory_delete, memory_feedback). 셸 명령을 실행할 수 있는 것은 아무것도 필요하지 않습니다. CLI가 보편적인 폴백(fallback)이며, 더 넓은 표면적입니다 — context, sleep 그리고 제안 원장(proposal ledger)에는 아직 MCP 도구가 없습니다. Codex는 일반적인 MCP 승인 경계를 유지합니다. 설정이 서버를 구성하고 검증했더라도 첫 번째 도구 호출은 여전히 명시적인 사용자 승인을 필요로 할 수 있습니다.

SessionStart는 주입(injects)하고, Stop과 SessionEnd는 지원되는 경우 증류(distil)하며, PreCompact는 제거(evicts)합니다. 기본적으로 Write는 소스 세션이 생성된 호스트를 통해 이유(reason)를 기록하는 반면, Manage는 스토어의 레거시 [executor] 정책을 사용합니다. 이들은 아카이브되거나 인용되는 소스 세션을 변경하지 않고 독립적으로 구성될 수 있습니다:

[executor.write]
reasoner = "host"
host = "muse-code" # 또는 "source", "codex", 또는 "claude-code"
...

mem distill과 mem sleep의 경우, --reason, --reason-host, 그리고 --reason-model이 해당 작업 정책을 재정의합니다. 작업 정책은 레거시 [executor] 값을 재정의합니다. 훅(Hooks)은 생성하는 호스트를 오직 --source-host로만 전달하므로, 기본값을 제공하거나 host = "source"를 해결하지만 명시적인 Write 호스트를 절대 대체하지 않습니다. 헤드리스 리저너(headless reasoner)는 재귀적 캡처를 방지하는 실행기 마커(executor marker)를 가지고 있습니다.

두 작업 모두 reasoner = "endpoint"와 해당 작업의 테이블에 있는 일반적인 model, endpoint, project, location, 또는 timeout_seconds 값을 설정하여 자체 모델 엔드포인트를 선택할 수 있습니다. 설정되지 않은 작업 값은 레거시 [executor] 값을 상속받아 기존 스토어 구성을 유지합니다. 엔드포인트 사용은 옵트인(opt-in)이며 절대 Tigerless 프로젝트나 자격 증명(credential)을 포함하지 않습니다. 실패한 선택된 호스트, 자격 증명, 요청 또는 엔드포인트 응답은 전송 방식을 변경하지 않습니다. Write는 원래 아카이브된 백로그가 재시도 가능하도록 남겨둡니다. 분리된 경계 오류는 스토어의 .state/hooks.log에 기록됩니다.

Vertex AI를 사용하려면 사용자가 관리하는 Google Cloud 프로젝트에서 활성화하고, 호출 주체에 prediction 접근 권한을 부여하며, gcloud CLI로 인증하고, 해당 프로젝트를 명시적으로 구성해야 합니다:

[executor]
reasoner = "endpoint"
project = "your-google-cloud-project"
...

위의 레거시 형식은 작업 테이블이 이를 재정의하지 않는 한 두 작업 모두에 계속 적용됩니다. 스코프를 지정하려면 동일한 endpoint 필드를 [executor.write] 또는 [executor.manage] 아래에 배치하십시오.
mem setup과 mem doctor는 Write 및 Manage reasoner 검사로 구성 및 실시간 사전 점검 결과를 분리하여 보고합니다.

GOOGLE_CLOUD_PROJECT와 VERTEX_LOCATION은 Store 값을 재정의합니다. 또는, 환경 변수에 endpoint와 GEMINI_API_KEY를 제공하여 OpenAI와 호환되는 endpoint를 선택할 수 있습니다. Store 구성에는 비밀 정보가 포함되지 않으며, 서비스 계정 키는 리포지토리에 커밋해서는 안 됩니다.

Muse Code를 설치하고, muse가 PATH에 있는지 확인한 다음, OPENROUTER_API_KEY로 사용 가능한 OpenRouter 자격 증명을 만드십시오.