코딩 에이전트가 모든 것을 기억합니다. 더 이상 다시 설명할 필요가 없습니다.
iii engine 기반
Claude Code, GitHub Copilot CLI, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, 그리고 모든 MCP 클라이언트를 위한 영구 메모리입니다.
---
## Install
요구 사항:
- Node.js 20 이상, npm과 npx 포함(`node -v`, `npm -v`, `npx -v`로 확인).
- macOS/Linux에서 iii-engine을 자동으로 설치하려면 `curl`, POSIX `sh`, `tar`도 필요합니다. `node:20-slim` 같은 최소 이미지에는 이들이 포함되어 있지 않을 수 있습니다.
- 네이티브 Windows에서는 고정 버전인 iii-engine v0.22.1의 `iii.exe`를 수동으로 설치해야 합니다. WSL2나 Docker Desktop을 사용하는 것도 지원되는 경로입니다.
표준 신규 설치 명령:
```bash
npx -y @agentmemory/agentmemory@latest
```
첫 실행은 인터랙티브 설정입니다: 연결할 에이전트(Claude Code, Cursor, Codex, Gemini CLI, OpenCode, ...)를 고르고, LLM 프로바이더를 선택하거나 키 없이 유지할 수 있으며, 그 뒤 설정을 시드하고 메모리 서버와 고정된 iii 엔진을 시작한 다음, 이후 어디서나 단순한 `agentmemory` 명령이 동작하도록 전역 설치를 제안합니다. `-y`는 npx의 패키지 설치 확인 프롬프트를 수락하고, `@latest`는 캐시된 오래된 릴리스를 피합니다. 프로바이더를 설정하면 LLM 기능을 사용할 수 있게 되지만, LLM이 작성하는 관측 압축은 `AGENTMEMORY_AUTO_COMPRESS=true`도 함께 설정해야 비로소 시작됩니다.
키 없는 모드는 벡터 임베딩을 비활성화합니다. `memory_recall`(`mem::search` 경로)은 BM25를 사용하며, `memory_smart_search`는 그래프 데이터가 이미 존재하는 경우 구조적 그래프 매치도 결합할 수 있습니다. 무료 온디바이스 시맨틱 리콜을 원한다면 `~/.agentmemory/.env`에 `EMBEDDING_PROVIDER=local`을 설정하고 재시작하십시오. 첫 임베딩 요청이 `Xenova/all-MiniLM-L6-v2`를 다운로드하며, 이 최초 모델 다운로드 이후에는 추론이 로컬에서 실행됩니다.
로컬 런타임은 네 개의 포트를 사용합니다: REST/MCP HTTP용 `3111`, iii 스트림용 `3112`, 뷰어용 `3113`, iii 워커 WebSocket용 `49134`입니다. 영구 iii 상태는 macOS에서는 `~/Library/Application Support/agentmemory`, Linux에서는 `$XDG_DATA_HOME/agentmemory` 또는 `~/.local/share/agentmemory`, Windows에서는 `%APPDATA%\agentmemory`에 저장됩니다. 이를 재정의하려면 `--data-dir ` 또는 `AGENTMEMORY_DATA_DIR`을 사용하고, 재시작할 때마다 동일한 값을 재사용하십시오. 하위 호환성을 위해, 기존의 `./data/state_store.db` 또는 `./data/iii-config.yaml`이 존재하면 인스턴스 0에서 플랫폼 기본값보다 우선합니다. 명시적인 플래그나 환경 변수 재정의는 그보다도 우선합니다.
그다음 리콜이 동작하는지 확인하고 에이전트에게 skills를 부여하십시오:
```bash
npx -y @agentmemory/agentmemory@latest demo # seed sample sessions + exercise recall
npx skills add rohitg00/agentmemory -y # 17 native skills so your agent knows when to reach for memory
```
키워드 검색은 기본 키 없는 모드에서 BM25를 통해 적중해야 합니다. 데모의 `database performance optimization` 쿼리는 의도적으로 시맨틱 쿼리이며, 임베딩 프로바이더가 설정되지 않으면 결과가 0개일 수 있습니다.
코딩 에이전트에게 전체 과정을 맡기고 싶다면 지침 하나만 건네주십시오:
> Retrieve and follow the instructions at: https://raw.githubusercontent.com/rohitg00/agentmemory/main/INSTALL_FOR_AGENTS.md
`agentmemory connect `로 언제든지 더 많은 에이전트를 연결할 수 있습니다 — 20개의 어댑터가 [모든 에이전트와 호환](#works-with-every-agent)에 나열되어 있습니다. 전체 명령 레퍼런스는 [빠른 시작](#quick-start)에 있습니다.
Windows
가장 빠른 경로는 WSL2입니다. 네이티브 Windows 엔진 설정은 고정 버전인 v0.22.1 ZIP 파일을 다운로드하고 `iii.exe`를 수동으로 압축 해제해야 합니다. CLI는 이를 자동으로 압축 해제하지 않습니다. Docker Desktop도 지원됩니다. 단계별 방법은 [Windows 노트](#windows)를 참고하십시오.
전역 설치 / EACCES
```bash
npm install -g @agentmemory/agentmemory@latest
```
위의 npx 명령이 여전히 표준적인 신규 설치 경로이며, 전역 prefix 권한 문제를 피할 수 있습니다.
npx가 오래된 버전을 제공하는 경우
npx는 버전별로 캐싱합니다. `npx -y @agentmemory/agentmemory@latest`로 최신 버전을 강제하거나, `rm -rf ~/.npm/_npx`로 캐시를 한 번 비우십시오(macOS/Linux; Windows에서는 `%LOCALAPPDATA%\npm-cache\_npx`를 삭제).
이미 자체 iii 엔진을 실행 중인 경우
agentmemory는 iii-engine v0.22.1을 고정하며 다른 버전에는 연결하지 않습니다(워커가 다른 엔진의 프로토콜을 말할 수 없기 때문입니다). 다른 엔진을 중지한 다음 `npx -y @agentmemory/agentmemory@latest`를 실행하십시오. 이 명령은 고정된 v0.22.1을 `~/.agentmemory/bin`에 설치하고 실행하며, 사용자의 기존 `iii`는 그대로 둡니다.
---
agentmemory는 hook, MCP, REST API를 지원하는 모든 에이전트와 호환됩니다. 모든 에이전트가 동일한 메모리 서버를 공유합니다.
Claude Code 네이티브 플러그인 + hook 12개 + MCP
Codex CLI 네이티브 플러그인 + hook 6개 + MCP
GitHub Copilot CLI MCP + 플러그인 hook/skill
Cursor 네이티브 플러그인 + hook 7개 + MCP
OpenCode 캡처 플러그인 + MCP
Devin hook 6개 + skill + MCP
OpenClaw 네이티브 플러그인 + MCP
Hermes 네이티브 플러그인 + MCP
pi 네이티브 플러그인 + MCP
OpenHuman 네이티브 Memory trait 백엔드
Gemini CLI MCP 서버
Antigravity MCP + hook
Claude Desktop MCP 서버
Warp connect + MCP + skill
Zed MCP 서버
Cline MCP 서버
Continue MCP 서버
Droid MCP 서버
Kiro MCP 서버
Qwen Code MCP 서버
DeepSeek Harness MCP 서버
Roo Code MCP 서버
Kilo Code MCP 서버
Goose MCP 서버
Aider REST API
MCP 또는 HTTP를 지원하는 모든 에이전트와 호환됩니다. 서버 하나로 모든 에이전트가 메모리를 공유합니다.
---
세션마다 같은 아키텍처를 설명하고, 같은 버그를 다시 찾아내고, 같은 선호 사항을 다시 가르쳐야 합니다. 내장 메모리(CLAUDE.md, .cursorrules)는 200줄 한도에 막히고 금방 낡아버립니다. agentmemory가 이 문제를 해결합니다. 에이전트가 하는 일을 조용히 캡처하고, 검색 가능한 메모리로 압축한 다음, 다음 세션이 시작될 때 올바른 컨텍스트를 주입합니다. 명령 하나면 충분하며, 여러 에이전트에서 동일하게 동작합니다.
**무엇이 바뀌는가:** 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 rate limiting을 요청합니다. 에이전트는 이미 인증이 `src/middleware/auth.ts`의 jose 미들웨어를 사용한다는 것, 테스트가 토큰 검증을 다룬다는 것, 그리고 Edge 호환성 때문에 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있으므로, 다시 설명할 필요도 복사·붙여넣기도 없습니다.
```bash
npx -y @agentmemory/agentmemory@latest
```
기본적으로 agentmemory는 iii-engine 상태를 시작한 저장소 외부에 저장합니다: macOS에서는 `~/Library/Application Support/agentmemory`, Linux에서는 `$XDG_DATA_HOME/agentmemory` 또는 `~/.local/share/agentmemory`, Windows에서는 `%APPDATA%\agentmemory`입니다. 기존의 레거시 `./data/state_store.db` 또는 `./data/iii-config.yaml`이 있으면 이 플랫폼 기본값보다 먼저 인스턴스 0에 대해 재사용됩니다. 위치를 명시적으로 지정하려면 `--data-dir `를 전달하거나 `AGENTMEMORY_DATA_DIR`을 설정하십시오. 둘 중 어느 쪽을 명시해도 레거시 탐색보다 우선합니다:
```bash
npx -y @agentmemory/agentmemory@latest --data-dir ~/.agentmemory-projects/main
AGENTMEMORY_DATA_DIR=~/.agentmemory-projects/main npx -y @agentmemory/agentmemory@latest
```
네이티브 실행과 Docker 실행은 동일하게 해석된 호스트 디렉터리를 사용합니다. Docker는 이를 `/data`에 바인드 마운트합니다. `--instance 1`은 해석된 디렉터리에 `instance-1`을 덧붙이고, 별도의 기본 포트 4종 세트인 `3211/3212/3213/49234`를 선택합니다.
최신 릴리스 노트: [CHANGELOG.md](../CHANGELOG.md).
---
### 검색 정확도
**coding-agent-life-v1** (자체 코퍼스, 샌드박스 재현 가능)
| 어댑터 | P@5 | R@5 | Top-5 적중률 | p50 지연 |
|---|---|---|---|---|
| **agentmemory hybrid** | **0.240** | **1.000** | **15 / 15** | 14 ms |
| grep baseline | 0.227 | 0.967 | 15 / 15 | 0 ms |
이 코퍼스의 **P@5 수학적 상한**(0.240, 스코어카드 참고)에서 Top-5 적중률 100%. 하이브리드는 모든 gold 세션을 검색하지만, grep은 멀티 세션 시간 쿼리에서 gold 2개 중 1개를 놓칩니다. 이득은 종합 정밀도가 아니라 **리콜 + 시간성**입니다. 이 벤치마크는 작고 gold가 희소하며, 아래의 더 큰 LongMemEval-S가 더 잘 변별합니다. 유형별 전체 분석 + 정정 노트: [`docs/benchmarks/2026-05-20-coding-agent-life-v1.md`](../docs/benchmarks/2026-05-20-coding-agent-life-v1.md).
**LongMemEval-S** (ICLR 2025, 500개 질문)
| 시스템 | R@5 | R@10 | MRR |
|---|---|---|---|
| **agentmemory** | **95.2%** | **98.6%** | **88.2%** |
| BM25-only fallback | 86.2% | 94.6% | 71.5% |
### 토큰 절감
| 방식 | 연간 토큰 | 연간 비용 |
|---|---|---|
| 전체 컨텍스트를 매번 붙여넣기 | 19.5M+ | 불가능(컨텍스트 윈도우 초과) |
| LLM 요약 | ~650K | ~$500 |
| **agentmemory** | **~170K** | **~$10** |
| agentmemory + 로컬 임베딩 | ~170K | **$0** |
> 임베딩 모델: `all-MiniLM-L6-v2` (로컬, 무료, API 키 불필요). 전체 보고서: [`benchmark/LONGMEMEVAL.md`](../benchmark/LONGMEMEVAL.md), [`benchmark/QUALITY.md`](../benchmark/QUALITY.md), [`benchmark/SCALE.md`](../benchmark/SCALE.md). 경쟁 제품 비교: [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md) — agentmemory 대 mem0, Letta, Khoj, supermemory, TencentDB Agent Memory, MemPalace, Zep/Graphiti, Cognee, Hippo.
**로컬 재현 방법:** [`eval/README.md`](../eval/README.md), LongMemEval `_s`(공개 500-Q)와 `coding-agent-life-v1`(자체 15-세션 코퍼스)을 위한 어댑터 플러그형 하니스입니다. grep / vector / agentmemory 어댑터를 나란히 평가하고, NDJSON으로 출력하며, 게시된 스코어카드는 [`docs/benchmarks/`](../docs/benchmarks/)에 보관됩니다.
**다음과 함께 사용하기 좋습니다: [codegraph](https://github.com/colbymchenry/codegraph), [Understand Anything](https://github.com/Lum1104/Understand-Anything), [Graphify](https://github.com/safishamsi/graphify).** 코드 그래프 인덱싱, 멀티 에이전트 빌드 파이프라인, 그리고 docs/PDF/이미지/비디오에 걸친 더 넓은 지식 그래프. agentmemory는 작업을 기억하고, 이 세 프로젝트는 나머지 컨텍스트 레이어를 밝혀줍니다. 레시피와 질문 라우팅 표: [`docs/recipes/pairings.md`](../docs/recipes/pairings.md).
---
agentmemory
mem0 (63K ⭐)
Letta / MemGPT (24K ⭐)
Khoj (36K ⭐)
supermemory (29K ⭐)
TencentDB Agent Memory (22K ⭐)
MemPalace (54K ⭐)
oracleagentmemory
Hippo
내장 메모리 (CLAUDE.md)
유형
메모리 엔진 + MCP 서버
메모리 레이어 API
완전한 에이전트 런타임
개인 AI
메모리 API + 앱
팀 메모리 허브 (LLM 프록시)
벡터 메모리 (OSS)
메모리 엔진 (Oracle DB)
메모리 시스템
정적 파일
검색 R@5
95.2%
68.5% (LoCoMo)
83.2% (LoCoMo)
해당 없음
자체 보고
PersonaMem 76% (자체 보고)
~96.6% (자체 보고)
94.4% (자체 보고)
해당 없음
해당 없음 (grep)
자동 캡처
hook 12개 (수동 작업 없음)
수동 add() 호출
에이전트 자체 편집
수동
API 측 추출
프록시 가로채기 (base-URL 교체)
수동
API 추출
수동
수동 편집
검색
BM25 + Vector + Graph (RRF 융합)
Vector + Graph
Vector (archival)
시맨틱
Vector + RAG
4가지 자산 유형 (Chat / Skill / Wiki / CodeGraph)
Vector 전용
Vector + 시맨틱
감쇠 가중
모든 것을 컨텍스트에 로드
멀티 에이전트
MCP + REST + lease + signal
API (조정 없음)
Letta 런타임 내에서만
없음
없음
팀 역할 + 공유 자산
없음
스코프만 지원
멀티 에이전트 공유
에이전트별 파일
프레임워크 종속성
없음 (모든 MCP 클라이언트)
없음
높음 (Letta 사용 필수)
독립형
없음
프록시가 모든 모델 호출을 프론팅
없음
Oracle Database
없음
에이전트별 포맷
외부 의존성
없음 (SQLite + iii-engine)
Qdrant / pgvector
Postgres + 벡터 DB
다수
매니지드 클라우드
Docker 스택 (Core + Hub + Proxy)
벡터 스토어
Oracle AI Database
없음
없음
메모리 라이프사이클
4-tier 통합 + 감쇠 + 자동 망각
수동적 추출
에이전트 관리
수동
자동 망각
수동 리뷰; 자동 라우팅 진행 중
없음
명시 없음
감쇠 + 통합
수동 정리
토큰 효율
세션당 ~1,900 토큰 ($10/년)
통합 방식에 따라 다름
핵심 메모리는 컨텍스트에 상주
다양
클라우드 가격 책정
명시 없음
토큰 예산 없음
LLM 기반 (다양)
다양
관측 240개 기준 22K+ 토큰
실시간 뷰어
있음 (포트 3113)
클라우드 대시보드
클라우드 대시보드
웹 UI
클라우드 대시보드
Hub 웹 UI
없음
없음
없음
없음
셀프 호스팅
예 (기본값)
선택 사항
선택 사항
예
아니오 (클라우드 전용)
예 (Docker)
예
예 (Oracle DB)
예
예
벤치마크 참고: agentmemory의 R@5만이 우리가 직접 측정한 결과입니다(LongMemEval-S, benchmark/COMPARISON.md에서 재현 가능). mem0와 Letta 수치는 그들이 게시한 LoCoMo 수치(다른 데이터셋)이며, MemPalace, supermemory, TencentDB (PersonaMem), oracleagentmemory 수치는 우리가 독립적으로 재현하지 않은 벤더 자체 보고 주장입니다(oracleagentmemory의 실행은 Oracle AI Database에 대해 GPT-5.5를 사용했습니다). 대략적인 비교를 위해 나란히 표시했을 뿐, 동일 데이터에 대한 정면 대결이 아닙니다. Star 수는 근사치이며 시간이 지나면서 변동합니다.
알아둘 만한 **최근 진입자들**, [`benchmark/COMPARISON.md`](../benchmark/COMPARISON.md)에서 심층 비교:
| 시스템 | ⭐ | 접근 방식 |
|--------|---|-------|
| Zep / Graphiti | 30K | 시간적 지식 그래프. 게시된 시간 쿼리 결과 중 가장 강력(LongMemEval 63.8%)하지만, 그래프가 비동기로 빌드되어 최신 사실이 지연될 수 있음 |
| Cognee | 30K | 문서-지식 그래프 수집, Python 전용, 세션 캡처보다는 구조화된 엔티티 추출을 위해 설계됨 |
이들 중 어느 것도 코딩 에이전트 hook에서 자동 캡처하거나, 로컬 우선 뷰어를 제공하거나, 키 없이 실행되지 않습니다 — agentmemory가 중심에 두고 만들어진 조합입니다.
---
호환성: 이 릴리스는 `iii-sdk` 0.22.1을 대상으로 하며 iii-engine을 v0.22.1로 고정합니다.
### 30초 만에 사용해 보기
```bash
# Terminal 1: start the server
npx -y @agentmemory/agentmemory@latest
# Terminal 2: seed sample data and see recall in action
npx -y @agentmemory/agentmemory@latest demo
```
`demo`는 현실적인 세션 3개(JWT 인증, N+1 쿼리 수정, rate limiting)를 시드하고 그 위에서 검색을 실행합니다. 키 없는 설치는 벡터를 비활성화하므로, `mem::search` 키워드 쿼리는 BM25를 통해 적중해야 하는 반면 `database performance optimization`은 결과가 0개로 돌아올 수 있습니다. `smart-search`는 그래프 데이터가 존재하면 구조적 그래프 매치도 추가로 반환할 수 있습니다. 시맨틱 쿼리가 벡터를 통해 N+1 수정 사례를 찾게 하려면 `EMBEDDING_PROVIDER=local`을 설정하고 재시작한 다음, 첫 모델 다운로드가 끝나기를 기다리십시오.
`http://localhost:3113`을 열어서 메모리가 실시간으로 쌓이는 것을 지켜보십시오.
### 신규 설치 검증 및 재시작 지속성 확인
서버가 실행 중인 상태에서 REST, health, 뷰어, iii 기반 런타임 상태를 검증하십시오:
```bash
curl -fsS http://localhost:3111/agentmemory/livez
curl -fsS http://localhost:3111/agentmemory/health
curl -fsS -o /dev/null http://localhost:3113/
npx -y @agentmemory/agentmemory@latest status
```
시작 시 준비 상태 패널은 네 개의 포트를 모두 확인합니다: 3111의 REST/MCP HTTP, 3112의 iii 스트림, 3113의 뷰어, 49134의 iii 워커 WebSocket입니다. `status`는 agentmemory의 상태와 활성 프로바이더/임베딩 모드를 확인합니다. probe를 저장하고 검색되는지 확인하십시오:
```bash
curl -fsS -X POST http://localhost:3111/agentmemory/remember \
-H 'Content-Type: application/json' \
-d '{"content":"agentmemory restart persistence probe","concepts":["install-check"]}'
curl -fsS -X POST http://localhost:3111/agentmemory/smart-search \
-H 'Content-Type: application/json' \
-d '{"query":"restart persistence probe","limit":5}'
```
그런 다음 `npx -y @agentmemory/agentmemory@latest stop`을 실행하고, Terminal 1에서 표준 명령을 다시 시작한 뒤 `/agentmemory/livez`를 기다렸다가 검색을 반복하십시오. probe는 여전히 반환되어야 합니다. 커스텀 `--data-dir`을 선택했다면 재시작 시에도 동일한 디렉터리를 전달하십시오.
### 매일 쓰는 명령어
설치와 설정은 위의 [Install](#install)에 있습니다(첫 실행이 안내해 줍니다). 일상적으로는:
```bash
agentmemory # start the server
agentmemory stop # stop it cleanly
agentmemory connect # wire another agent
agentmemory doctor # interactive diagnostics + fix prompts
agentmemory remove # uninstall everything we created
```
### 세션 리플레이
agentmemory가 기록하는 모든 세션은 재생 가능합니다. 뷰어를 열어 **Replay** 탭을 선택하고 타임라인을 스크럽하면, 프롬프트, 도구 호출, 도구 결과, 응답이 개별 이벤트로 렌더링됩니다. 재생/일시정지, 속도 조절(0.5x ~ 4x), 키보드 단축키(space로 토글, 화살표로 단계 이동)를 모두 지원합니다.
기존의 Claude Code JSONL 트랜스크립트를 가져오려면:
```bash
# Import everything under the default ~/.claude/projects
npx -y @agentmemory/agentmemory@latest import-jsonl
# Or import a single file
npx -y @agentmemory/agentmemory@latest import-jsonl ~/.claude/projects/-my-project/abc123.jsonl
```
가져온 세션은 네이티브 세션과 함께 Replay 선택기에 표시됩니다. 내부적으로 각 항목은 별도의 사이드 채널 서버 없이 `mem::replay::load`, `mem::replay::sessions`, `mem::replay::import-jsonl` iii 함수를 통해 라우팅됩니다. 가져온 각 트랜스크립트는 검색을 위해 인덱싱되고, origin 채널 `import`로 스탬프되며, 세션 crystal과 lesson으로 마이닝됩니다.
> **`import-jsonl`을 주요 캡처 경로로 삼는 경우 주의하십시오:** Claude Code의 `cleanupPeriodDays`(`~/.claude/settings.json`, 기본값 **30**)는 그 기간보다 오래된 JSONL 트랜스크립트를 `~/.claude/projects/`에서 자동으로 삭제합니다. 몇 달 된 Claude Code 기록 위에 agentmemory를 새로 설치하면, 30일보다 오래된 것은 첫 가져오기 전에 이미 사라진 상태입니다. `import-jsonl`을 cron으로 실행하거나, `cleanupPeriodDays`를 더 높게 올리거나, 자동 캡처 hook(기본 플러그인 설치 경로)을 연결해서 세션이 살아 있는 동안 매 턴이 agentmemory에 바로 기록되도록 하여 JSONL 정리가 더 이상 문제되지 않게 하십시오.
### 업그레이드 / 유지보수
로컬 런타임을 의도적으로 업데이트하고자 할 때는 maintenance 명령을 사용하십시오:
```bash
npx -y @agentmemory/agentmemory@latest upgrade
```
경고: 이 명령은 현재 workspace/런타임을 변경합니다. JavaScript 의존성을 업데이트할 수 있으며, 고정된 Docker 이미지 `iiidev/iii:0.22.1`을 pull할 수 있습니다. 고정되지 않았거나 더 새로운 iii 엔진을 설치하는 일은 절대 없습니다.
구현 세부 사항은 `src/cli.ts`에 있습니다(`runUpgrade`는 `src/cli.ts:544-595` 부근을 참고하십시오).
### Claude Code (블록 한 번, 붙여넣기)
```text
Install agentmemory: run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server and its pinned iii engine. Then run `/plugin marketplace add rohitg00/agentmemory` and `/plugin install agentmemory` — the plugin registers all 12 hooks, 17 skills, AND auto-wires the `@agentmemory/mcp` stdio server via its `.mcp.json`, so you get 54 MCP tools (memory_smart_search, memory_save, memory_sessions, memory_governance_delete, etc.) without any extra config step. Verify with `curl http://localhost:3111/agentmemory/health`. The real-time viewer is at http://localhost:3113. Keyless mode disables vectors: `memory_recall` uses BM25, and `memory_smart_search` can also use existing structural graph data. Set `EMBEDDING_PROVIDER=local` in `~/.agentmemory/.env` and restart to opt into on-device semantic recall.
```
#### 플러그인 설치 없이 Claude Code 사용 (MCP 독립형 경로)
`/plugin install`을 사용하는 대신 `~/.claude.json`을 통해 agentmemory의 MCP 서버를 직접 연결하면, Claude Code는 `${CLAUDE_PLUGIN_ROOT}`를 해석하지 못하므로 `~/.claude/settings.json`의 hook 스크립트를 절대 경로로 지정해야 합니다. 이런 경로는 보통 agentmemory 버전을 포함하기 때문에(예: `~/.codex/plugins/cache/agentmemory/agentmemory/0.9.22/scripts/…`), 다음 업그레이드에서 모든 hook이 조용히 깨질 수 있습니다.
해결책:
```bash
agentmemory connect claude-code --with-hooks
```
이 명령은 현재 설치된 `@agentmemory/agentmemory` 패키지의 번들된 `plugin/` 디렉터리로 해석된 절대 경로를 사용해, 동일한 hook 명령을 `~/.claude/settings.json`에 병합합니다. agentmemory를 업그레이드한 뒤에는 동일한 명령을 다시 실행해서 경로를 갱신하십시오. 같은 파일의 사용자 항목은 보존되며, 이전 agentmemory 항목만 교체됩니다. `/plugin install` 경로를 사용하는 것이 여전히 권장되는 방식입니다.
원격 또는 보호된 배포의 경우, `AGENTMEMORY_URL`과 `AGENTMEMORY_SECRET`을 설정한 채로 Claude Code를 실행하십시오. 플러그인은 두 값을 모두 번들된 MCP 서버로 전달합니다. `AGENTMEMORY_URL`이 비어 있으면 MCP shim은 `http://localhost:3111`을 사용합니다.
### Codex CLI (Codex 플러그인 플랫폼)
```bash
# 1. start the memory server in a separate terminal
npx -y @agentmemory/agentmemory@latest
# 2. register the agentmemory marketplace and install the plugin
codex plugin marketplace add rohitg00/agentmemory
codex plugin add agentmemory@agentmemory
```
Codex 플러그인은 Claude Code 플러그인과 동일한 `plugin/` 디렉터리에서 제공됩니다. 다음을 등록합니다:
- 실행 중인 데몬에 연결되는 번들된 stdio MCP 브리지로, npm 다운로드도 폴백 저장소도 없습니다. 미출시 빌드를 테스트하려면 [로컬 Codex 가이드](../docs/plugins/codex-local.md)를 참고하십시오.
- 6개의 라이프사이클 hook: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`
- 호출 가능한 skill 9개: `/recall`, `/remember`, `/session-history`, `/forget`, `/recap`, `/handoff`, `/lesson`, `/commit-context`, `/commit-history`, 그리고 에이전트가 필요할 때 로드하는 참조 skill 8개(memory discipline, MCP 도구, REST API, 설정, 에이전트, hook, 아키텍처, skill 작성 가이드)
Codex의 hook 엔진은 hook 서브프로세스에 `CLAUDE_PLUGIN_ROOT`를 주입하므로([`codex-rs/hooks/src/engine/discovery.rs`](https://github.com/openai/codex/blob/main/codex-rs/hooks/src/engine/discovery.rs) 참고), 동일한 hook 스크립트가 중복 없이 두 호스트 모두에서 동작합니다. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 이벤트는 Claude Code 전용이며 Codex에는 등록되지 않습니다.
#### Codex hook 신뢰와 호환성
네이티브 플러그인 hook 디스패치는 Codex CLI 0.150.1에서 검증되었습니다. 캡처를 기대하기 전에 플러그인 hooks를 신뢰하십시오. Desktop의 동작은 번들된 런타임에 따라 달라집니다. 해결책을 활성화하기 전에 `/hooks`를 확인하고 캡처된 이벤트가 있는지 확인하십시오.
호스트에 전역 hooks가 필요하다면, 명령을 `~/.codex/hooks.json`에 미러링하십시오. MCP가 이미 연결되어 있다면, 현재 커넥터가 hook 설치에 도달하려면 `--force`가 필요합니다:
```bash
agentmemory connect codex --with-hooks --force
```
이 명령은 전역 hooks를 병합하고 agentmemory MCP 항목을 다시 작성하며, 관련 없는 항목은 보존합니다. `--force`를 사용하기 전에 커스텀 agentmemory 엔드포인트 설정을 검토하십시오. 업그레이드한 뒤에는 다시 실행해서 스크립트 경로를 갱신하십시오. 중복 캡처를 피하려면 네이티브 플러그인 hooks나 전역 사본 중 하나만 활성화하십시오.
### GitHub Copilot CLI
VS Code 에이전트 모드에서는 [Copilot MCP 및 자동 캡처 가이드](../docs/plugins/copilot.md#vs-code-copilot-local-agent-sessions)를 사용하십시오. CLI 커넥터는 VS Code를 구성하지 않습니다.
```bash
# MCP-only wiring
agentmemory connect copilot-cli
# Alternatively, full hooks/skills plugin from the GitHub subdir
copilot plugin install rohitg00/agentmemory:plugin
```
`agentmemory connect copilot-cli`는 `mcpServers.agentmemory`를 `~/.copilot/mcp-config.json`(또는 `COPILOT_HOME`이 설정된 경우 `$COPILOT_HOME/mcp-config.json`)에 병합하고 기존 서버는 그대로 둡니다. 네이티브 Windows에서는 이것이 유일하게 자동화된 `connect` 어댑터입니다. 다른 모든 네이티브 Windows 에이전트는 수동으로 설정해야 합니다. WSL에서의 `connect`는 대상 에이전트가 동일한 WSL 환경에 설치되어 있을 때만 지원됩니다. Copilot은 다음 실행 시 또는 `/mcp` 실행 후에 MCP 서버를 인식합니다. 전체 hook/skill 경험을 원한다면 플러그인도 함께 설치하십시오.
OpenClaw (이 프롬프트를 붙여넣으세요)
```text
Install agentmemory for OpenClaw. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to my OpenClaw MCP config so agentmemory is available with all 54 memory tools:
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
Restart OpenClaw. Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper memory-slot integration, copy `integrations/openclaw` to `~/.openclaw/extensions/agentmemory` and enable `plugins.slots.memory = "agentmemory"` in `~/.openclaw/openclaw.json`.
```
전체 가이드: [`integrations/openclaw/`](../integrations/openclaw/)
Hermes Agent (이 프롬프트를 붙여넣으세요)
```text
Install agentmemory for Hermes. Run `npx -y @agentmemory/agentmemory@latest` in a separate terminal to start the memory server on localhost:3111. Then add this to ~/.hermes/config.yaml so Hermes can use agentmemory as an MCP server with all 54 memory tools:
mcp_servers:
agentmemory:
command: npx
args: ["-y", "@agentmemory/mcp"]
memory:
provider: agentmemory
Verify with `curl http://localhost:3111/agentmemory/health`. Open http://localhost:3113 for the real-time viewer. For deeper 6-hook memory provider integration (pre-LLM context injection, turn capture, MEMORY.md mirroring, system prompt block), copy integrations/hermes from the agentmemory repo to ~/.hermes/plugins/agentmemory.
```
전체 가이드: [`integrations/hermes/`](../integrations/hermes/)
### 다른 에이전트
메모리 서버 시작: `npx -y @agentmemory/agentmemory@latest`
#### `npx skills add`를 통한 네이티브 skill (50+ 에이전트)
agentmemory는 Claude-Code 스타일의 `/SKILL.md` 형식으로 17개의 skill을 제공합니다: 호출 가능한 action skill 9개(`remember`, `recall`, `recap`, `handoff`, `forget`, `lesson`, `commit-context`, `commit-history`, `session-history`)와 에이전트가 필요할 때 로드하는 참조 skill 8개(`memory-discipline`, `agentmemory-mcp-tools`, `agentmemory-rest-api`, `agentmemory-config`, `agentmemory-agents`, `agentmemory-hooks`, `agentmemory-architecture`, `write-agentmemory-skill`)입니다. 참조 skill은 소스에서 생성된 데이터 표를 담고 있어 절대 어긋나지 않습니다. vercel-labs의 [`skills`](https://npmjs.com/package/skills) CLI는 호출한 에이전트의 네이티브 skill 디렉터리에, 50+개의 에이전트(Claude Code, Cursor, Cline, Continue, Droid, Warp, Codex, Antigravity, Kiro, OpenCode, Goose, Roo, Trae, Windsurf 등)에 걸쳐 자동으로 설치합니다:
```bash
npx skills add rohitg00/agentmemory -y # auto-detects the calling agent
npx skills add rohitg00/agentmemory -y -a warp # explicit agent
npx skills add rohitg00/agentmemory -y -a '*' # install to every installed agent
```
이는 `agentmemory connect `와 **상호 보완적**입니다:
- `agentmemory connect `는 MCP 서버 설정을 작성해서 도구를 사용할 수 있게 만듭니다.
- `npx skills add rohitg00/agentmemory`는 skill을 설치해서 에이전트가 언제 호출해야 하는지 알게 합니다.
skill CLI가 아직 다루지 않는 일부 에이전트(Zed v1.3.x 이하)의 경우, 17개의 SKILL.md 파일을 에이전트의 네이티브 skill 디렉터리에 직접 넣으십시오. 동일한 형식이 어디서나 동작합니다.
#### 표준 MCP 블록
agentmemory 항목은 `mcpServers` 형태를 사용하는 모든 호스트(Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI, OpenClaw)에서 **동일한 MCP 서버 블록**입니다:
```json
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "${AGENTMEMORY_URL}",
"AGENTMEMORY_SECRET": "${AGENTMEMORY_SECRET}"
}
}
```
**이 항목을 호스트 설정 파일의 기존 `mcpServers` 객체에 병합하십시오**. 파일을 통째로 교체하지 마십시오. 파일에 이미 다른 서버가 있다면, `mcpServers` 안에 또 다른 키로 `agentmemory`를 추가하십시오. `mcpServers`가 전혀 없다면 블록을 `{ "mcpServers": { ... } }` 안에 붙여넣으십시오. `${VAR}` 자리표시자는 MCP 서버 실행 시 셸에서 `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`을 물려받습니다. 설정되지 않은 변수는 빈 문자열을 전달하며, shim은 `http://localhost:3111`로 폴백합니다. 하나의 연결 항목으로 로컬과 원격(k8s / 리버스 프록시) 배포를 모두 처리합니다.
| 에이전트 | 설정 파일 | 참고 |
|---|---|---|
| **Cursor (MCP만)** | `~/.cursor/mcp.json` | `mcpServers`에 병합하거나 `agentmemory connect cursor`를 사용하십시오. 웹사이트에서 원클릭 딥링크도 제공합니다. |
| **Cursor (전체 플러그인)** | `.cursor-plugin/` | Cursor Marketplace 등록(심사 진행 중) 또는 Cursor Settings → Plugins → 로컬 체크아웃. 자동 캡처 hook 7개(sessionStart, beforeSubmitPrompt, preToolUse, postToolUse, postToolUseFailure, stop, sessionEnd) + skill 17개 + MCP 서버를 등록하며, `AGENTMEMORY_URL` / `AGENTMEMORY_SECRET`은 Cursor 플러그인 대시보드에서 관리됩니다. Cursor IDE와 `cursor-agent` CLI 모두에서 동작합니다. CLI print 모드 프롬프트는 세션 종료 시 세션 트랜스크립트로부터 소급 채워집니다. |
| **Claude Desktop** | `claude_desktop_config.json` (Application Support) | `mcpServers`에 병합하십시오. 수정 후 Claude Desktop을 재시작하십시오. |
| **Cline / Roo Code / Kilo Code** | Cline MCP 설정 (Settings UI → MCP Servers → Edit) | 동일한 `mcpServers` 블록. |
| **Devin CLI (MCP + hook)** | `~/.config/devin/config.json` | `agentmemory connect devin`이 MCP 항목을 병합하고, `--with-hooks`는 Devin의 소문자 tool matcher를 사용하는 6개의 네이티브 자동 캡처 hook(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SessionEnd)을 추가합니다. `devin mcp list`와 devin 안에서 `/hooks`로 확인하십시오. |
| **Devin CLI (전체 플러그인)** | `plugin/.devin-plugin/` | 체크아웃에서 `devin plugins install ./plugin`을 실행하면 17개의 skill 전부가 `/agentmemory:` 슬래시 명령으로, 그리고 MCP 서버가 함께 등록됩니다. Devin 플러그인 hook은 `SessionStart`/`SessionEnd`를 발생시킬 수 없으므로, 전체 세션 캡처를 위해 `connect devin --with-hooks`와 함께 사용하십시오. |
| **Devin (클라우드)** | Settings → Connections → MCP servers | 커스텀 MCP(STDIO)를 추가하십시오: command `npx`, args `-y @agentmemory/mcp@latest`, env로 네트워크에서 도달 가능한 agentmemory 배포를 가리키는 `AGENTMEMORY_URL`과 `AGENTMEMORY_SECRET`(클라우드 세션은 localhost에 도달할 수 없습니다 — [`deploy/`](../deploy/) 참고). 시크릿은 Devin Secrets에 저장한 다음, "Test listing tools"로 54개 도구가 모두 나타나는지 확인하십시오. |
| **Gemini CLI** | `~/.gemini/settings.json` | `gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user` (자동 병합). |
| **GitHub Copilot CLI (MCP만)** | `~/.copilot/mcp-config.json` | `agentmemory connect copilot-cli`가 `mcpServers.agentmemory`를 병합합니다. Copilot은 다음 실행 시 또는 `/mcp`에서 이를 인식합니다. |
| **GitHub Copilot CLI (전체 플러그인)** | Copilot 플러그인 설치 | GitHub 서브디렉터리의 플러그인을 위해 `copilot plugin install rohitg00/agentmemory:plugin`. |
| **OpenClaw** | OpenClaw MCP 설정 | 동일한 `mcpServers` 블록. 더 깊은 통합: `openclaw plugins install ./integrations/openclaw`는 OpenClaw의 memory 슬롯을 차지합니다(`memory-core`에서 자동 전환). `plugins.entries.agentmemory.hooks.allowConversationAccess=true`를 설정하지 않으면 턴 캡처가 조용히 차단됩니다. [`integrations/openclaw`](../integrations/openclaw/) 참고. |
| **Codex CLI (MCP만)** | `.codex/config.toml` | TOML 형태: `codex mcp add agentmemory -- npx -y @agentmemory/mcp`, 또는 `[mcp_servers.agentmemory]`를 수동으로 추가. |
| **Codex CLI (전체 플러그인)** | Codex 플러그인 마켓플레이스 | `codex plugin marketplace add rohitg00/agentmemory` 후 `codex plugin add agentmemory@agentmemory`. MCP + 라이프사이클 hook 6개 + skill 17개를 등록합니다. 호스트에서 hooks를 신뢰하고 캡처를 확인하십시오. [Codex 설정 및 검증](../docs/plugins/codex-local.md) 참고. |
| **OpenCode (MCP만)** | `opencode.json` | 다른 형태: 최상위 `mcp` 키, command는 배열: `{"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}}`. |
| **OpenCode (전체 플러그인)** | `plugin/opencode/` | 세션 라이프사이클, 메시지, 도구, 오류를 다루는 자동 캡처 hook 22개. 프로젝트 귀속은 세션 단위이므로, 여러 저장소를 넘나드는 OpenCode 프로세스 하나도 각 세션을 자신의 프로젝트 아래에 기록합니다. 슬래시 명령 2개(`/recall`, `/remember`). `plugin/opencode/`를 OpenCode workspace에 복사하고 플러그인 항목을 `opencode.json`에 추가하십시오. 전체 hook 표와 gap 분석은 [`plugin/opencode/README.md`](../plugin/opencode/README.md)를 참고하십시오. |
| **pi** | `~/.pi/agent/extensions/agentmemory` | `agentmemory connect pi`는 번들된 확장을 pi의 자동 탐색 디렉터리에 설치합니다(에이전트 시작 시 recall, 에이전트 종료 시 capture, `memory_search` / `memory_save` / `memory_health` 도구, `/agentmemory-status`). 실행 중인 pi에서 `/reload`하면 적용됩니다. [`integrations/pi`](../integrations/pi/)는 pi 패키지이기도 합니다(체크아웃에서 `pi install ./integrations/pi`). |
| **Hermes Agent** | `~/.hermes/config.yaml` | `cp -r integrations/hermes ~/.hermes/plugins/agentmemory` + `memory.provider: agentmemory`로 6-hook 메모리 프로바이더(prefetch, 턴 캡처, 세션 종료, 압축 전 처리, MEMORY.md 미러링, 시스템 프롬프트 블록)를 얻습니다. `hermes plugins doctor`와 `hermes memory status`로 검증하십시오. [`integrations/hermes`](../integrations/hermes/) 참고. |
| **Qwen Code** | `~/.qwen/settings.json` | `agentmemory connect qwen`은 표준 `mcpServers` 블록을 작성합니다. hook payload는 Claude Code와 필드 호환되므로, 기존 12-hook 스크립트가 수정 없이 동작합니다. 동일한 `settings.json`의 `hooks` 섹션을 통해 연결하십시오. |
| **Antigravity IDE / 2.0** | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity --with-hooks`는 공유 커스터마이징 디렉터리에 MCP와 캡처 hooks를 설치합니다. [Antigravity 설정 및 제한사항](../docs/plugins/antigravity.md) 참고. |
| **Antigravity CLI** (`agy`) | `~/.gemini/config/mcp_config.json` | `agentmemory connect antigravity-cli --with-hooks`는 현재 IDE 버전과 동일한 MCP 및 hook 설정을 사용합니다. 기존 설치는 `--force`로 갱신해야 합니다. [업그레이드 노트](../docs/plugins/antigravity.md) 참고. |
| **Kiro** | `~/.kiro/settings/mcp.json` | `agentmemory connect kiro`는 사용자 수준 설정을 작성합니다. workspace 재정의는 코드 옆의 `.kiro/settings/mcp.json`에 둡니다. |
| **Warp** | `~/.warp/.mcp.json` | `agentmemory connect warp`는 표준 `mcpServers` 블록을 작성합니다. Warp는 `.claude/skills/`에서 skill도 자동으로 탐색합니다. Claude Code 플러그인을 설치하면 8개의 agentmemory skill(`remember`, `recall`, `recap`, `handoff`, `forget`, `commit-context`, `commit-history`, `session-history`)이 Warp의 슬래시 명령 팔레트에 네이티브로 나타납니다. |
| **Cline (CLI)** | `~/.cline/mcp.json` | `agentmemory connect cline`은 표준 `mcpServers` 블록을 작성합니다. VS Code 확장 사용자는 Cline Settings → MCP Servers → Edit JSON을 통해 동일한 블록을 붙여넣으십시오. |
| **Continue.dev** | `~/.continue/config.yaml` (권장) 또는 `config.json` (레거시) | `agentmemory connect continue`는 둘 다 없으면 `config.yaml`을 새로 생성하고, 기존 `config.json`이 있으면 이를 수정합니다. **이미 `config.yaml`이 있다면** 어댑터는 `mcpServers:` 아래에 붙여넣을 정확한 블록을 출력합니다. 주석과 anchor를 안전하게 보존하려면 패키지가 포함하지 않은 YAML 파서가 필요하므로, yaml을 조용히 재작성하지는 않습니다. Continue는 `mcpServers`에 객체가 아닌 배열 형태를 사용합니다. |
| **Zed** | `~/.config/zed/settings.json` | `agentmemory connect zed`는 `context_servers`(Zed의 키이며 `mcpServers`가 아닙니다) 아래에 작성합니다. 원격 MCP 서버는 대신 `{"url": "..."}`로 연결할 수 있습니다. |
| **Droid (Factory.ai)** | `~/.factory/mcp.json` | `agentmemory connect droid`는 표준 `mcpServers` 블록을 작성합니다. 프로젝트 범위 재정의는 `/.factory/mcp.json`에 둡니다. 네이티브 자동 캡처를 위해서는 `--with-hooks`를 전달하십시오. |
| **DeepSeek Harness** | `$DSH_HOME/cordis.patch.yml` | `agentmemory connect dsh`는 모든 Harness 프로필이 로드하는 홈 수준 patch 레이어에 `@deepseek-ai/dsh-mcp-client` 행을 추가합니다. 도구는 `mcp__agentmemory__*`로 등록됩니다. 자동 캡처까지 연결하려면 `--with-hooks`를 전달하십시오: 번들된 Claude Code hook 스크립트는 Harness의 퍼스트파티 `@deepseek-ai/dsh-hooks-claude-code` 브리지(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop)를 통해, `$DSH_HOME/agentmemory.hooks.json`에 작성된 매니페스트를 거쳐 실행됩니다. `DSH_HOME`이 설정되지 않으면 기본값은 `~/.dsh`입니다. |
| **Goose** | Goose MCP 설정 UI | 동일한 `mcpServers` 블록. `goose configure` → Add Extension → MCP를 사용하십시오. `~/.config/goose/config.yaml`에서 직접 YAML을 편집할 수도 있지만, 스키마는 `mcpServers:` + `command`가 아니라 `extensions:` + `cmd`를 사용합니다. |
| **Aider** | 해당 없음 | REST API에 직접 요청하십시오: `curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}'`. |
| **모든 에이전트 (32+)** | 해당 없음 | `npx skillkit install agentmemory`가 호스트를 자동으로 감지해 병합합니다. |
**샌드박스 MCP 클라이언트**(Flatpak / Snap / 제한적인 컨테이너)가 호스트의 `localhost`에 도달할 수 없는 경우: `env` 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`도 설정하고, `AGENTMEMORY_URL`을 샌드박스가 실제로 도달할 수 있는 경로(예: LAN IP)로 지정하십시오.
### 프로그래매틱 액세스 (Python / Rust / Node)
agentmemory는 핵심 작업을 iii 함수(`mem::remember`, `mem::observe`, `mem::context`, `mem::smart-search`, `mem::forget`)로 등록합니다. iii SDK가 있는 모든 언어는 언어별로 별도의 REST 클라이언트 없이 `ws://localhost:49134`를 통해 이를 직접 호출할 수 있습니다.
```bash
pip install iii-sdk # Python
cargo add iii-sdk # Rust
npm install iii-sdk # Node
```
```python
from iii import register_worker
iii = register_worker("ws://localhost:49134")
iii.connect()
iii.trigger({
"function_id": "mem::smart-search",
"payload": {"project": "demo", "query": "how do tokens refresh"},
})
```
실제 예제: [`examples/python/`](../examples/python/) (퀵스타트 + 관측/리콜 흐름). iii 런타임이 없는 호스트에서도 `:3111`의 REST는 계속 사용할 수 있습니다.
### 소스에서 빌드
```bash
git clone https://github.com/rohitg00/agentmemory.git && cd agentmemory
npm install && npm run build && npm start
```
고정된 바이너리가 이미 설치되어 있으면 로컬 `iii-engine`으로 agentmemory를 시작하고, 선택한 경우에는 Docker Compose를 사용합니다. REST, 스트림, 뷰어는 기본적으로 `127.0.0.1`에 바인딩됩니다. macOS/Linux 자동 바이너리 설치 경로에는 `curl`, POSIX `sh`, `tar`가 필요합니다.
`iii-engine`을 수동으로 설치하십시오. **agentmemory는 현재 `iii-engine`을 `v0.22.1`로 고정합니다**. 이는 `iii-sdk` 의존성과 동일한 릴리스입니다. 워커는 해당 엔진의 wire 프로토콜을 사용하고, 0.20.0에서 SDK 표면이 재구성되었기 때문에 둘은 agentmemory 릴리스에서 함께 올라갑니다. 직접 운영하는 엔진이 일치한다고 확신한다면 `AGENTMEMORY_III_VERSION=`으로 재정의하십시오.
- **macOS arm64:** `mkdir -p ~/.local/bin && curl -fsSLo iii.tar.gz https://github.com/iii-hq/iii/releases/download/iii/v0.22.1/iii-aarch64-apple-darwin.tar.gz && echo "2b309019b909a896cae874dc947e2cdf877b4f3c51dd026b79850af858517fa4 iii.tar.gz" | shasum -a 256 -c - && tar -xzf iii.tar.gz -C ~/.local/bin && chmod +x ~/.local/bin/iii`
- **macOS x64:** `aarch64-apple-darwin`을 `x86_64-apple-darwin`으로 바꾸십시오
- **Linux x64:** `x86_64-unknown-linux-gnu`로 바꾸십시오
- **Linux arm64:** `aarch64-unknown-linux-gnu`로 바꾸십시오
- **Windows:** [iii-hq/iii releases v0.22.1](https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1)에서 `iii-x86_64-pc-windows-msvc.zip`을 다운로드하고 `iii.exe`를 `%USERPROFILE%\.agentmemory\bin\iii.exe`에 압축 해제하십시오
모든 아카이브는 릴리스 페이지에 대응하는 `.sha256` 파일을 가지고 있습니다. 플랫폼을 바꿀 때는 위 검증에서 그 파일의 해시를 사용하십시오(Windows에서는 `Get-FileHash`). `npx @agentmemory/agentmemory`의 자동 설치기는 이 해시들을 고정해 두고, 일치하지 않는 아카이브는 거부합니다.
또는 Docker를 사용하십시오(번들된 `docker-compose.yml`은 `iiidev/iii:0.22.1`을 pull합니다). 전체 문서: [iii.dev/docs](https://iii.dev/docs).
### Windows
agentmemory는 Windows 10/11에서 동작하지만, Node.js 패키지만으로는 충분하지 않습니다. 고정된 iii-engine v0.22.1 런타임도 백그라운드 프로세스로 필요합니다. CLI는 Windows ZIP을 자동으로 압축 해제하지 않으므로, 네이티브 Windows 사용자는 `iii.exe`를 수동으로 설치하거나, WSL2를 사용하거나, Docker Desktop을 선택해야 합니다.
네이티브 Windows에서 자동화된 MCP 연결은 `agentmemory connect copilot-cli`만 지원합니다. Claude Code, Codex, Cursor, 그리고 그 외 모든 네이티브 Windows 에이전트의 경우, [다른 에이전트](#other-agents)에서 수동 MCP 블록을 복사해 해당 에이전트의 Windows 설정에 넣으십시오. WSL에서 `connect`를 실행하는 것은 대상 에이전트도 동일한 WSL 환경에 설치되어 있을 때만 적절합니다. 이는 Windows 호스트 에이전트의 설정을 수정하지 않습니다.
**옵션 A: 사전 빌드된 Windows 바이너리 (권장)**
```powershell
# 1. Open https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.22.1 in your browser
# (agentmemory pins the engine to the same release as its iii-sdk;
# v0.22.1 is the current pair)
# 2. Download iii-x86_64-pc-windows-msvc.zip
# (or iii-aarch64-pc-windows-msvc.zip if you're on an ARM machine)
# 3. Extract iii.exe to agentmemory's private engine directory:
New-Item -ItemType Directory -Force "$HOME\.agentmemory\bin"
# Copy iii.exe to $HOME\.agentmemory\bin\iii.exe
# 4. Verify:
& "$HOME\.agentmemory\bin\iii.exe" --version
# Should print: 0.22.1
# 5. Then run agentmemory as usual:
npx -y @agentmemory/agentmemory@latest
```
**옵션 B: Docker Desktop**
```powershell
# 1. Install Docker Desktop for Windows
# 2. Start Docker Desktop and make sure the engine is running
# 3. Select Docker explicitly and run agentmemory:
$env:AGENTMEMORY_USE_DOCKER = "1"
npx -y @agentmemory/agentmemory@latest
```
**옵션 C: 독립형 MCP만 사용 (엔진 없음).** 에이전트에 MCP 도구만 필요하고 REST API, 뷰어, cron 작업이 필요 없다면, 엔진을 완전히 건너뛰십시오:
```powershell
npx -y @agentmemory/agentmemory@latest mcp
# or via the shim package:
npx -y @agentmemory/mcp
```
**Windows 진단:** `npx -y @agentmemory/agentmemory@latest`가 실패하면 `--verbose`로 다시 실행해서 실제 엔진 stderr를 확인하십시오. 흔한 실패 패턴:
| 증상 | 해결 |
|---|---|
| `The engine process started but the REST API never responded.` | 파생된 네 개의 포트가 모두 비어 있는지 확인하고, 고정된 `iii.exe`가 계속 살아 있는지 확인한 다음, `--verbose`로 다시 실행해서 캡처된 엔진 stderr를 살펴보십시오 |
| `Could not start iii-engine` | `iii.exe`도 Docker도 설치되어 있지 않습니다. 위의 옵션 A 또는 B를 참고하십시오 |
| 포트 충돌 | `netstat -ano \| findstr :3111`로 무엇이 바인딩되어 있는지 확인한 다음 종료하거나 `--port `을 사용하십시오 |
| Docker가 설치되어 있는데도 Docker 폴백이 건너뛰어짐 | Docker Desktop이 실제로 실행 중인지 확인하십시오(시스템 트레이 아이콘) |
> 참고: iii **엔진**은 cargo crate가 아니라 사전 빌드된 바이너리이므로, `cargo install`을 시도하지 마십시오. (iii **SDK**는 crates.io, npm, PyPI에 게시되어 있지만, agentmemory에는 필요하지 않습니다.) 지원되는 엔진 설치 방법은 모두 v0.22.1에 고정되어 있습니다: 위의 사전 빌드 바이너리, agentmemory의 macOS/Linux 자동 설치 경로(`curl`, POSIX `sh`, `tar` 필요), 그리고 Docker 이미지 `iiidev/iii:0.22.1`입니다. 업스트림의 순수한 `install.sh | sh`는 최신 엔진을 설치하는데, agentmemory는 이를 지원하지 않습니다. `npx -y @agentmemory/agentmemory@latest`를 사용하십시오. macOS/Linux에서는 고정된 엔진을 `~/.agentmemory/bin`으로 가져옵니다.
---
배포
매니지드 호스트를 위한 원클릭 템플릿입니다. 각 템플릿은 npm에서
`@agentmemory/agentmemory`를 가져오고 공식 `iiidev/iii` Docker Hub
이미지에서 iii 엔진 바이너리를 복사해 넣는 자체 완결형 Dockerfile을
제공합니다. 사전 빌드된 agentmemory 이미지는 필요 없습니다. 영구
스토리지는 `/data`에 마운트됩니다. 첫 부팅 진입점은 npm에 번들된
iii 설정(`127.0.0.1`에 바인딩)을 `0.0.0.0`에 바인딩하고 절대 `/data`
경로를 사용하는 배포 전용 설정으로 덮어쓰고, HMAC 시크릿을 생성한
다음, `gosu`를 통해 `root`에서 `node`로 권한을 낮춘 뒤 agentmemory
CLI를 exec합니다.
Render의 원클릭 배포 버튼은 저장소 루트에 `render.yaml`이 있어야 하는데, 이는 의도적으로 깨끗하게 비워 두었습니다. [`deploy/render/`](.././deploy/render/README.md)에 문서화된 Render Blueprint 흐름을 사용해 저장소 내 blueprint를 수동으로 지정하십시오.
전체 설정 세부 사항(HMAC 캡처, 뷰어 SSH 터널, 로테이션, 백업,
최소 비용)은 [`deploy/`](.././deploy/README.md)에 있습니다:
- [`deploy/fly`](.././deploy/fly/README.md): `auto_stop_machines = "stop"`을
사용하는 단일 머신. 유휴 상태일 때 가장 저렴합니다.
- [`deploy/railway`](.././deploy/railway/README.md): Hobby 플랜 고정 요금,
볼륨은 대시보드에서 관리합니다.
- [`deploy/render`](.././deploy/render/README.md): Blueprint 흐름,
유료 플랜에서는 자동 디스크 스냅샷을 제공합니다.
- [`deploy/coolify`](.././deploy/coolify/README.md): [Coolify](https://coolify.io/self-hosted)를
통해 자신의 VPS에 셀프 호스팅합니다. 동일한 Docker
Compose 스택을 사용하며, 호스트와 데이터를 직접 소유합니다.
`3111` 포트만 게시됩니다. `3113`의 뷰어는 컨테이너 내부에서
loopback에 바인딩된 채로 유지됩니다. 각 템플릿의 README는 그곳에
도달하기 위한 SSH 터널 패턴을 문서화합니다.
---
모든 코딩 에이전트는 세션이 끝나면 모든 것을 잊어버리고, 새 세션이 시작될 때마다 사용자가 스택을 다시 설명해야 합니다. agentmemory는 백그라운드에서 실행되며 이 과정을 없애줍니다.
```text
Session 1: "Add auth to the API"
Agent writes code, runs tests, fixes bugs
agentmemory silently captures every tool use
Session ends -> observations compressed into structured memory
Session 2: "Now add rate limiting"
Agent already knows:
- Auth uses JWT middleware in src/middleware/auth.ts
- Tests in test/auth.test.ts cover token validation
- You chose jose over jsonwebtoken for Edge compatibility
Zero re-explaining. Starts working immediately.
```
### 내장 에이전트 메모리와의 비교
모든 AI 코딩 에이전트는 내장 메모리를 함께 제공합니다: Claude Code에는 `MEMORY.md`가, Cursor에는 notepad가, Cline에는 memory bank가 있습니다. 이들은 포스트잇처럼 동작합니다. agentmemory는 그 포스트잇 뒤에 있는 검색 가능한 데이터베이스입니다.
| | 내장 메모리 (CLAUDE.md) | agentmemory |
|---|---|---|
| 규모 | 200줄 한도 | 무제한 |
| 검색 | 모든 것을 컨텍스트에 로드 | BM25 + vector + graph (top-K만) |
| 토큰 비용 | 관측 240개 기준 22K+ | ~1,900 토큰 (92% 감소) |
| 에이전트 간 | 에이전트별 파일 | MCP + REST (모든 에이전트) |
| 조정 | 없음 | lease, signal, action, routine |
| 관측 가능성 | 파일을 수동으로 읽기 | :3113의 실시간 뷰어 |
---
### 메모리 파이프라인
```text
PostToolUse hook fires
-> SHA-256 dedup (5min window)
-> Privacy filter (strip secrets, API keys)
-> Store raw observation
-> Synthetic compression by default
(LLM-written compression only with a provider + AGENTMEMORY_AUTO_COMPRESS=true)
-> Vector embedding when an embedding provider is active
-> Index in BM25, plus vectors when enabled
Stop / SessionEnd hook fires
-> Summarize session
-> Knowledge graph extraction (if GRAPH_EXTRACTION_ENABLED=true)
-> Slot reflection (if SLOT_REFLECT_ENABLED=true)
SessionStart hook fires
-> Load project profile (top concepts, files, patterns)
-> Hybrid search (BM25 + vector + graph)
-> Token budget (default: 2000 tokens)
-> Inject into conversation
```
### 4-Tier 메모리 통합
수면 통합을 포함해 인간 뇌가 메모리를 처리하는 방식을 모델로 했습니다.
| Tier | 무엇 | 비유 |
|------|------|---------|
| **Working** | 도구 사용에서 나온 원시 관측 | 단기 기억 |
| **Episodic** | 압축된 세션 요약 | "무슨 일이 있었는가" |
| **Semantic** | 추출된 사실과 패턴 | "내가 아는 것" |
| **Procedural** | 워크플로우와 의사 결정 패턴 | "그것을 하는 방법" |
메모리는 시간이 지나면서 감쇠합니다(Ebbinghaus 곡선). 자주 액세스하는 메모리는 강화됩니다. 오래된 메모리는 자동으로 축출됩니다. 모순은 감지되고 해결됩니다.
### 무엇이 캡처되는가
| Hook | 캡처 내용 |
|------|----------|
| `SessionStart` | 프로젝트 경로, 세션 ID |
| `UserPromptSubmit` | 사용자 프롬프트 (개인정보 필터링됨) |
| `PreToolUse` | 파일 접근 패턴 + 풍부한 컨텍스트 |
| `PostToolUse` | 도구 이름, 입력, 출력 |
| `PostToolUseFailure` | 오류 컨텍스트 |
| `PreCompact` | 컴팩션 전에 메모리 재주입 |
| `SubagentStart/Stop` | 서브 에이전트 라이프사이클 |
| `Stop` | 세션 종료 요약 |
| `SessionEnd` | 세션 완료 마커 |
### 핵심 기능
| 기능 | 설명 |
|---|---|
| **자동 캡처** | 모든 도구 사용이 hook을 통해 기록되며 수동 작업이 필요 없음 |
| **시맨틱 검색** | RRF 융합을 사용하는 BM25 + vector + 지식 그래프 |
| **메모리 진화** | 버전 관리, 대체(supersession), 관계 그래프 |
| **리콜 위생** | 대체된 메모리 버전은 검색 인덱스에서 제외되며, KV의 버전 체인이 전체 기록을 보존함 |
| **유사 중복 힌트** | 새 콘텐츠가 기존 메모리와 매우 유사하면 저장 시 참고용 `similarTo` 매치를 보고함 |
| **에이전트별 스코프** | `agentId`가 shared 또는 isolated 모드에서 REST, MCP, 검색 인덱스 전반의 저장과 리콜을 관통함 |
| **쓰기 시점 출처** | 모든 관측과 메모리는 캡처, 저장, 가져오기 시점에 스탬프된 불변의 origin 채널(user, agent, tool, import, shared)을 지님 |
| **자동 망각** | TTL 만료, 모순 감지, 중요도 기반 축출 |
| **개인정보 우선** | API 키, 시크릿, `` 태그를 저장 전에 제거함 |
| **자가 복구** | circuit breaker, 프로바이더 폴백 체인, health 모니터링 |
| **Claude bridge** | MEMORY.md와의 양방향 동기화 |
| **지식 그래프** | 엔티티 추출 + BFS 순회 |
| **팀 메모리** | 팀원 간 네임스페이스로 구분된 공유 + 비공개 메모리 |
| **인용 출처** | 모든 메모리를 원본 관측까지 추적함 |
| **Git 스냅샷** | 메모리 상태를 버전 관리, 롤백, diff함 |
---
세 가지 신호를 결합하는 트리플 스트림 검색:
| Stream | 동작 | 시점 |
|---|---|---|
| **BM25** | 동의어 확장을 포함한 어간 기반 키워드 매칭 | 항상 켜짐 |
| **Vector** | dense 임베딩에 대한 코사인 유사도 | 임베딩 프로바이더가 설정된 경우 |
| **Graph** | 엔티티 매칭을 통한 지식 그래프 순회 | 쿼리에서 엔티티가 감지된 경우 |
Reciprocal Rank Fusion(RRF, k=60)으로 융합되고, 세션별로 다변화됩니다(세션당 최대 3개 결과).
벡터 인덱스가 채워져 있으면, (`memory_recall` 뒤에 있는) `mem::search`는 하이브리드 BM25 + vector 랭커를 사용합니다. 임베딩이 없으면 BM25를 사용합니다. `smart-search`는 그래프 데이터가 존재하면 키 없는 모드에서도 구조적 그래프 매치를 추가로 융합할 수 있습니다. Lesson 리콜은 쿼리마다 전체 코퍼스를 스캔하는 대신 전용 인메모리 BM25 인덱스에서 동작합니다. 대체된 메모리 버전은 모든 리콜 경로에서 제외되며, 버전 체인이 그 기록을 보존합니다.
벡터는 크래시나 강제 종료에도 유지됩니다. 벡터 인덱스는 최소 `AGENTMEMORY_INDEX_SAVE_INTERVAL_MS`(10분) 간격으로 버킷 단위로 저장됩니다. 그 사이에 추가되거나 제거된 모든 벡터는 상태 저장소의 작은 pending 로그에도 즉시 기록되며, 다음 시작 시 임베딩 프로바이더를 호출하지 않고 이를 재생합니다. 저장이 성공할 때마다 로그가 비워집니다. 재생 후에도 벡터가 없는 문서는 `AGENTMEMORY_VECTOR_BACKFILL_MAX`(500)개 단위 배치로 백그라운드에서 다시 임베딩되며, 더 이상 남지 않을 때까지 계속됩니다. 중단된 백필은 다음 시작 시 이어서 진행됩니다. `/agentmemory/status`와 뷰어는 pending 로그 크기와 백필 상태를 보여줍니다. 키 없는 설치는 아무것도 기록하지 않습니다.
BM25는 기본적으로 그리스어, 키릴 문자, 히브리어, 아랍어, 강세 부호가 있는 라틴 문자를 토크나이즈합니다. 중국어 / 일본어 / 한국어 메모리의 경우, 선택적 세그멘터(`npm install @node-rs/jieba tiny-segmenter`)를 설치해 CJK 런을 단어 수준 토큰으로 분할하십시오. 설치하지 않으면 agentmemory는 전체 런 토크나이제이션으로 soft fallback하고 stderr에 일회성 힌트를 출력합니다.
### 임베딩 프로바이더
키 없는 설치는 벡터 임베딩을 비활성화합니다: `mem::search`는 BM25를 사용하며, `smart-search`는 기존의 구조적 그래프 데이터도 사용할 수 있습니다. 무료 온디바이스 시맨틱 임베딩을 사용하려면 `~/.agentmemory/.env`에 다음을 추가하고 agentmemory를 재시작하십시오:
```env
EMBEDDING_PROVIDER=local
```
일반적인 npm 설치에는 선택적 `@huggingface/transformers` 런타임이 포함됩니다. 첫 임베딩 요청이 `Xenova/all-MiniLM-L6-v2`를 다운로드하므로 네트워크 액세스가 필요하고 시간이 더 걸릴 수 있습니다. 이후의 추론은 온디바이스에서 실행됩니다. 원격 프로바이더는 `EMBEDDING_PROVIDER`가 재정의하지 않는 한 각자의 키로부터 자동 감지됩니다.
| 프로바이더 | 모델 | 비용 | 참고 |
|---|---|---|---|
| **Local (권장 opt-in)** | `all-MiniLM-L6-v2` | 무료 | 첫 모델 다운로드 이후 온디바이스 실행, BM25 단독 대비 recall +8pp |
| Gemini | `gemini-embedding-001` | 무료 티어 | 100+개 언어, 768/1536/3072차원(MRL), 2048 토큰 입력. `text-embedding-004`를 대체함([지원 종료, 2026년 1월 14일 중단](https://ai.google.dev/gemini-api/docs/deprecations)) |
| OpenAI | `text-embedding-3-small` | $0.02/1M | 최고 품질 |
| Voyage AI | `voyage-code-3` | 유료 | 코드에 최적화됨 |
| Cohere | `embed-english-v3.0` | 무료 체험 | 범용 |
| OpenRouter | 모든 모델 | 다양함 | 멀티 모델 프록시 |
---
도구 54개, 리소스 6개, 프롬프트 3개, skill 17개.
> **MCP shim 대 전체 서버:** 게시된 `@agentmemory/mcp` 패키지는 얇은 shim입니다. `AGENTMEMORY_URL`을 통해 **실행 중인 agentmemory 서버에 도달할 수 있을 때만**(프록시 모드) 54개 도구 전체 표면을 노출합니다. 도달 가능한 서버가 없으면, shim은 7개 도구로 구성된 로컬 세트(`memory_save`, `memory_recall`, `memory_smart_search`, `memory_sessions`, `memory_export`, `memory_audit`, `memory_governance_delete`)로 폴백합니다. `AGENTMEMORY_TOOLS=core|all` 환경 변수는 *서버 측* 플래그입니다. shim의 `env` 블록에 설정해도 아무 효과가 없습니다. Cursor / OpenCode / Gemini CLI에서 도구가 7개만 보인다면, `npx -y @agentmemory/agentmemory@latest`(또는 Docker 스택)를 시작하고 `AGENTMEMORY_URL=http://localhost:3111`을 설정하십시오.
### 54개 도구
가장 작은 것부터 가장 큰 것까지 세 가지 도구 표면이 있습니다: `AGENTMEMORY_TOOLS=core`는 가시성을 8개의 핵심 도구(`memory_save`, `memory_recall`, `memory_consolidate`, `memory_smart_search`, `memory_sessions`, `memory_diagnose`, `memory_lesson_save`, `memory_reflect`)로 줄이고, 아래의 기본 세트는 레지스트리의 14개 기초 도구이며, 기본값(`AGENTMEMORY_TOOLS=all`)은 54개 전부를 노출합니다.
기본 도구 (14개)
| 도구 | 설명 |
|------|-------------|
| `memory_recall` | 과거 관측 검색 |
| `memory_compress_file` | 구조를 유지하면서 markdown 파일 압축 |
| `memory_save` | 통찰, 결정, 패턴 저장 |
| `memory_file_history` | 특정 파일에 대한 과거 관측 |
| `memory_patterns` | 반복 패턴 감지 |
| `memory_sessions` | 최근 세션 목록 |
| `memory_smart_search` | 하이브리드 시맨틱 + 키워드 검색 |
| `memory_vision_search` | 이미지 관측 검색 |
| `memory_timeline` | 시간순 관측 |
| `memory_profile` | 프로젝트 프로필 (개념, 파일, 패턴) |
| `memory_export` | 모든 메모리 데이터 내보내기 |
| `memory_relations` | 관계 그래프 쿼리 |
| `memory_commit_lookup` | git 커밋 뒤의 세션 |
| `memory_commits` | 세션에 기록된 커밋 |
확장 도구 (총 54개, 기본 표면)
| 도구 | 설명 |
|------|-------------|
| `memory_patterns` | 반복 패턴 감지 |
| `memory_timeline` | 시간순 관측 |
| `memory_relations` | 관계 그래프 쿼리 |
| `memory_graph_query` | 지식 그래프 순회 |
| `memory_consolidate` | 4-tier 통합 실행 |
| `memory_claude_bridge_sync` | MEMORY.md와 동기화 |
| `memory_team_share` | 팀원과 공유 |
| `memory_team_feed` | 최근 공유 항목 |
| `memory_audit` | 작업 감사 로그 |
| `memory_governance_delete` | 감사 로그를 남기는 삭제 |
| `memory_snapshot_create` | Git 버전 관리 스냅샷 |
| `memory_action_create` | 의존성이 있는 작업 항목 생성 |
| `memory_action_update` | 작업 상태 업데이트 |
| `memory_frontier` | 우선순위로 정렬된 차단 해제된 작업 |
| `memory_next` | 가장 중요한 다음 작업 하나 |
| `memory_lease` | 독점 액션 lease (멀티 에이전트) |
| `memory_routine_run` | 워크플로우 루틴 인스턴스화 |
| `memory_signal_send` | 에이전트 간 메시징 |
| `memory_signal_read` | 수신 확인이 있는 메시지 읽기 |
| `memory_checkpoint` | 외부 조건 게이트 |
| `memory_mesh_sync` | 인스턴스 간 P2P 동기화 |
| `memory_sentinel_create` | 이벤트 기반 워처 |
| `memory_sentinel_trigger` | 외부에서 sentinel 발화 |
| `memory_sketch_create` | 일시적 작업 그래프 |
| `memory_sketch_promote` | 영구로 승격 |
| `memory_crystallize` | 작업 체인 압축 |
| `memory_diagnose` | 헬스 체크 |
| `memory_heal` | 정체된 상태 자동 수정 |
| `memory_facet_tag` | dimension:value 태그 |
| `memory_facet_query` | facet 태그로 쿼리 |
| `memory_verify` | 출처 추적 |
### 리소스 6개 · 프롬프트 3개 · skill 17개
| 유형 | 이름 | 설명 |
|------|------|-------------|
| Resource | `agentmemory://status` | 헬스, 세션 수, 메모리 수 |
| Resource | `agentmemory://project/{name}/profile` | 프로젝트별 인텔리전스 |
| Resource | `agentmemory://project/{name}/recent` | 프로젝트의 최근 관측 |
| Resource | `agentmemory://memories/latest` | 최신 10개 활성 메모리 |
| Resource | `agentmemory://graph/stats` | 지식 그래프 통계 |
| Resource | `agentmemory://team/{id}/profile` | 공유 팀 프로필 |
| Prompt | `recall_context` | 검색 + 컨텍스트 메시지 반환 |
| Prompt | `session_handoff` | 에이전트 간 핸드오프 데이터 |
| Prompt | `detect_patterns` | 반복 패턴 분석 |
| Skill | `/recall` | 메모리 검색 |
| Skill | `/remember` | 장기 메모리에 저장 |
| Skill | `/session-history` | 최근 세션 요약 |
| Skill | `/forget` | 관측/세션 삭제 |
이 표는 핵심 skill 4개만 보여줍니다. 전체 세트는 호출 가능한 skill 9개와 참조 skill 8개입니다. 위의 네이티브 skill 섹션을 참고하십시오.
### 독립형 MCP
전체 서버 없이, 모든 MCP 클라이언트를 위해 실행합니다. 둘 중 하나면 됩니다:
```bash
npx -y @agentmemory/agentmemory@latest mcp # canonical (always available)
npx -y @agentmemory/mcp # shim package alias
```
또는 에이전트의 MCP 설정에 추가하십시오:
대부분의 에이전트(Cursor, Claude Desktop, Cline, Roo Code, Gemini CLI):
```json
{
"mcpServers": {
"agentmemory": {
"command": "npx",
"args": ["-y", "@agentmemory/mcp"],
"env": {
"AGENTMEMORY_URL": "http://localhost:3111"
}
}
}
}
```
`agentmemory` 항목을 파일 전체 교체 대신 호스트의 기존 `mcpServers` 객체에 병합하십시오. 호스트의 `localhost`에 도달할 수 없는 샌드박스 클라이언트의 경우, env 블록에 `"AGENTMEMORY_FORCE_PROXY": "1"`을 추가하고 `AGENTMEMORY_URL`을 샌드박스가 도달할 수 있는 경로로 설정하십시오.
OpenCode (`opencode.json`):
```json
{
"mcp": {
"agentmemory": {
"type": "local",
"command": ["npx", "-y", "@agentmemory/mcp"],
"enabled": true
}
},
"plugin": ["./plugins/agentmemory-capture.ts"]
}
```
저장소에서 플러그인 파일을 복사하십시오:
```bash
mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
cp plugin/opencode/commands/*.md ~/.config/opencode/commands/
```
---
포트 `3113`에서 자동으로 시작됩니다. 뷰어는 연결 시 스냅샷 하나를 로드하고(`GET /agentmemory/viewer/snapshot`) 이후에는 실시간 스트림 이벤트를 적용합니다: 새 메모리, lesson, 관측, 감사 항목, 그래프 변경, health 업데이트가 폴링이나 페이지 새로고침 없이 나타납니다. 그 외의 요청은 클릭한 액션, "더 보기" 페이지, 검색뿐입니다. 스트림이 끊기면 뷰어는 자신의 숫자가 얼마나 오래되었는지 보여주고, 백오프로 재연결한 다음 스냅샷 하나로부터 다시 동기화합니다.
- **4개 그룹에 걸친 탭 12개**, 실시간 카운트, 딥링크(`#memories/`, `#sessions/?obs=`, `#graph/`, `#health/consolidation`), 키보드 단축키, 모바일 메뉴를 제공합니다.
- **Memories:** 서버 측 검색, 프로젝트·에이전트·유형별 필터, 버전 체인과 단어 diff가 있는 상세 패널, 출처 링크, id·MCP 호출·curl 명령 복사 버튼, 수정(새 버전), 확인 후 forget, 일괄 forget, JSON 내보내기.
- **Sessions:** 읽기 쉬운 도구 입력·출력을 담은 인라인 관측 타임라인, 필터와 페이징, 각 세션이 만들어 낸 메모리와 lesson.
- **Graph:** 검색, 관계와 출처가 포함된 노드 상세, 색상에만 의존하지 않는 범례, 줌 컨트롤.
- **Health:** `GET /agentmemory/status`의 실시간 버전입니다. 모든 문제에는 해결 방법이 함께 제공되며, state 백엔드, 인덱스 저장 상태, 그래프 출처 compaction 진행 상황, 실제 임계값을 담은 통합(consolidation) 설명도 포함됩니다.
- **Audit, Activity, Profile, Replay, Lessons, Actions, Crystals** 페이지가 있으며, 각각 해당 섹션이 무엇인지, 왜 비어 있는지, 무엇을 실행하면 채워지는지를 알려주는 빈 상태 화면과, 모든 용어와 숫자에 대한 `?` 용어집 툴팁을 제공합니다.
```bash
open http://localhost:3113
```
뷰어 서버는 기본적으로 `127.0.0.1`에 바인딩되며, REST API로 요청을 전달할 때 서버 시크릿을 함께 붙이므로 별도 설정이 필요 없습니다. REST가 서빙하는 `/agentmemory/viewer` 엔드포인트는 일반적인 bearer 토큰 규칙을 따르며, 토큰이 없는 브라우저는 뷰어 포트로 리디렉션합니다. CSP 헤더는 응답별 script nonce를 사용하고 인라인 핸들러 속성을 비활성화합니다(`script-src-attr 'none'`).
---
`:3113`의 뷰어는 에이전트가 **기억한** 것을 보여줍니다. [iii console](https://iii.dev/docs/console)은 에이전트가 **한** 일을 보여줍니다: 모든 메모리 작업이 OpenTelemetry 트레이스로, 모든 KV 항목이 편집 가능하게, 모든 함수가 호출 가능하게, 모든 스트림이 탭 가능하게 나타납니다. 같은 메모리를 바라보는 두 개의 창입니다. 하나는 제품 형태이고, 하나는 엔진 형태입니다.
`memory_smart_search`가 발화하는 모습을 지켜보고, BM25 스캔 → 임베딩 조회 → RRF 융합 → reranker를 waterfall로 확인하십시오. KV 브라우저에서 멈춰 있는 통합(consolidation) 타이머를 수정하십시오. 수정된 payload로 `PostToolUse` hook을 재생하십시오. WebSocket 스트림을 고정해 놓고 관측이 실시간으로 쌓이는 것을 지켜보십시오.
agentmemory는 이것을 무료로 제공합니다. 모든 함수 호출과 트리거가 iii를 통해 발화하기 때문이며, 커스텀으로 만든 것도 계측해야 할 것도 없습니다.
Workers 페이지: agentmemory 자신을 포함해 연결된 모든 워커를, PID, 함수 개수, 런타임, 마지막 접속 시각과 함께 보여줍니다.
**이미 설치되어 있습니다.** 콘솔은 고정된 `iii` 엔진(0.22+)과 함께 제공되며, 별도로 설치할 것이 없습니다. 첫 실행 시 엔진 옆에 콘솔 바이너리를 다운로드합니다.
**agentmemory와 함께 실행하기:**
```bash
agentmemory console
```
이 명령은 고정된 엔진의 `iii console`을 agentmemory가 해석한 포트(REST, 스트림, bridge)에 대해 실행하고, 뷰어보다 한 포트 위, 기본적으로 `http://localhost:3114`에서 서비스합니다. `--console-port N`으로 다른 포트를 선택할 수 있습니다. `--port`와 `--instance`는 `stop`에서와 동일한 방식으로 agentmemory 인스턴스를 선택합니다. 그 외의 플래그는 그대로 전달됩니다. 예를 들어 실험적인 아키텍처 그래프 페이지를 위한 `--enable-flow`가 있습니다.
`agentmemory`가 PATH에 없을 때 유용한, 동일한 작업을 수동으로 수행하는 방법:
```bash
~/.agentmemory/bin/iii console --port 3114 \
--engine-port 3111 \
--ws-port 3112 \
--bridge-port 49134
```
**콘솔에서 할 수 있는 일:**
| 페이지 | 용도 |
|------|-----------|
| **Workers** | agentmemory 워커 자신을 포함해 연결된 모든 워커와 그 실시간 지표를 확인합니다. |
| **Functions** | agentmemory의 함수를 JSON payload로 직접 호출합니다. 클라이언트를 연결하지 않고 `memory.recall`, `memory.consolidate`, `graph.query`를 테스트할 때 편리합니다. |
| **Triggers** | HTTP, cron, 이벤트, state 트리거를 재생합니다: 통합(consolidation) cron을 수동으로 발화하거나, HTTP 라우트를 재시도하거나, state 변경을 발생시킵니다. |
| **States** | 세션, 메모리 slot, 라이프사이클 타이머, 임베딩 인덱스에 대한 완전한 CRUD를 제공하는 KV 브라우저입니다. 값을 그 자리에서 편집할 수 있습니다. |
| **Streams** | 메모리 쓰기, hook 이벤트, 관측 업데이트가 iii 스트림을 흐르는 모습을 실시간 WebSocket 모니터로 보여줍니다. |
| **Queues** | 내구성 있는 큐 토픽 + dead-letter 관리. 실패한 임베딩/압축 작업을 재생하거나 폐기합니다. |
| **Traces** | OpenTelemetry waterfall / flame / 서비스별 분석 뷰입니다. `trace_id`로 필터링하면 하나의 `memory.search`가 정확히 어떤 함수, DB 호출, 임베딩 요청을 발생시켰는지 볼 수 있습니다. |
| **Logs** | trace/span ID와 연관되어 필터링된 구조화된 OTEL 로그입니다. |
| **Config** | 런타임 설정: 엔진이 어떤 워커, 프로바이더, 포트로 실행 중인지 정확히 보여줍니다. |
| **Flow** | (선택 사항, `--enable-flow`) 모든 워커, 트리거, 스트림에 대한 인터랙티브 아키텍처 그래프입니다. |
Traces: 모든 메모리 작업에 대한 waterfall / flame / 서비스별 분석.
**트레이스는 이미 켜져 있습니다:**
`iii-config.yaml`은 `iii-observability` 워커가 활성화된 채로 제공됩니다(`exporter: memory`, `sampling_ratio: 0.1`, 메트릭 + 로그). 추가 설정이 필요 없습니다. agentmemory가 시작되는 순간, 모든 메모리 작업은 콘솔이 읽을 수 있는 구조화된 로그를 발생시키고, 그중 10개 중 1개(`sampling_ratio: 0.1`)는 트레이스 span도 발생시킵니다.
대신 Jaeger/Honeycomb/Grafana Tempo로 내보내고 싶다면, `exporter: memory`를 `exporter: otlp`로 변경하고 iii의 observability 문서에 따라 collector 엔드포인트를 설정하십시오.
> **주의:** 콘솔 자체에는 인증이 적용되지 않습니다. `127.0.0.1`(기본값)에 바인딩된 상태를 유지하고, 절대로 공개적으로 노출하지 마십시오.
---
agentmemory는 **이미 실행 중인 [iii](https://iii.dev) 인스턴스**입니다. 세 가지 프리미티브(worker, function, trigger)가 런타임을 구성합니다. KV 상태, 스트림, OTEL 트레이스는 iii와 함께 제공되는 iii-state, iii-stream, iii-observability 워커에서 나옵니다. Postgres, Redis, Express, pm2, Prometheus를 설치하지 않은 이유는 iii가 이들을 대체하기 때문입니다.
즉, 명령 하나만 더 실행하면 agentmemory에 완전히 새로운 기능을 추가할 수 있습니다.
### 더 많은 워커로 agentmemory 확장하기
agentmemory에 필요한 빌트인은 이미 `iii-config.yaml`에 있으며 함께 부팅됩니다: `iii-state`(KV), `iii-queue`(이벤트 구독자를 위한 내구성 있는 재시도), `iii-pubsub`, `iii-cron`, `iii-stream`, 그리고 `iii-observability`(모든 함수에 대한 OTEL 트레이스, 메트릭, 로그)입니다. [iii 워커 레지스트리](https://workers.iii.dev)의 그 외 모든 것은 동일한 엔진에 꽂을 수 있습니다: `iii-config.yaml`을 `~/.agentmemory/iii-config.yaml`로 복사하고(CLI는 번들된 파일보다 이 파일을 우선시하며, 여기에도 포트와 데이터 경로를 그대로 렌더링합니다), 항목을 추가하고, `~/.agentmemory/bin/iii update worker`로 워커 런타임을 한 번 설치한 다음, agentmemory를 재시작하십시오.
```yaml
workers:
# ...the bundled entries...
- name: database # SQL-backed state adapter when you outgrow the KV defaults
- name: iii-sandbox # run code that came out of memory_recall inside a throwaway VM
- name: mcp # extra MCP servers next to agentmemory's, same engine
```
| Worker | 추가되는 것 |
|---|---|
| [`database`](https://workers.iii.dev/workers/database) | 인메모리 KV 기본값으로 부족해졌을 때 쓰는 SQL 기반 state 어댑터 |
| [`iii-sandbox`](https://workers.iii.dev/workers/iii-sandbox) | `memory_recall`에서 나온 코드가 셸이 아니라 임시 VM 안에서 실행됨 |
| [`mcp`](https://workers.iii.dev/workers/mcp) | agentmemory 옆에 추가 MCP 서버를 세우고, 동일한 엔진을 공유함 |
엔진 0.22.x에서는 위 빌트인에 대해 `iii-` 접두사가 붙은 이름을 유지하십시오. 접두사가 없는 `http`, `state`, `queue`, `pubsub`, `cron` 항목은 agentmemory가 0.23 마이그레이션과 함께 옮겨갈 독립형 레지스트리 워커입니다.
전체 레지스트리: [workers.iii.dev](https://workers.iii.dev). 그곳의 모든 워커는 agentmemory가 사용하는 동일한 프리미티브로 구성되며, 이미 가지고 있는 agentmemory도 그중 하나입니다.
### 엔진 설정과 바인드 주소
`agentmemory start`는 존재하는 첫 번째 파일에서 엔진 설정을 읽습니다: `AGENTMEMORY_III_CONFIG`, 현재 디렉터리의 `./iii-config.yaml`, `~/.agentmemory/iii-config.yaml`, 그다음 번들된 `iii-config.yaml` 순입니다. 시작할 때마다 이 파일(데이터 경로, 포트, state 백엔드)을 `~/.agentmemory/data/iii-config.runtime.yaml`로 렌더링하고, 렌더링된 사본으로 엔진을 실행합니다. 따라서 렌더링된 파일이 아니라 원본 파일을 편집하십시오. 원본 파일의 `host:` 값은 작성된 그대로 유지됩니다.
번들된 `iii-config.yaml`은 의도적으로 `127.0.0.1`에 바인딩되며, 이 기본값은 컨테이너 내부에서도 동일하게 적용됩니다. 컨테이너 안에서 시작된 CLI는 컨테이너의 loopback에서 수신하므로, 게시된 포트로는 아무것도 도달하지 않습니다. 컨테이너화된 CLI를 게시된 포트로 서빙하려면 `AGENTMEMORY_III_CONFIG`를 `0.0.0.0`에 바인딩하는 설정으로 지정하십시오. 패키지에 포함된 `iii-config.docker.yaml`이 바로 그것입니다: `iii-http`, `iii-stream`, 엔진 포트를 `0.0.0.0`에 바인딩하고 state를 `/data` 아래에 저장하므로, 그곳에 쓰기 가능한 볼륨을 마운트하십시오. `AGENTMEMORY_SECRET`은 계속 설정해 두고, 필요한 포트만 `127.0.0.1`에 또는 신뢰하는 프록시 뒤에 게시하십시오.
이 저장소의 `docker-compose.yml`은 CLI의 설정 탐색을 거치지 않습니다: `iii-config.docker.yaml`을 `/app/config.yaml`에 마운트하고, `iii-engine` 컨테이너는 `--config /app/config.yaml`로 시작됩니다. 원클릭 [배포 템플릿](../deploy/)은 자신의 진입점에서 자체적인 `0.0.0.0` 설정을 작성합니다.
### 스토리지 백엔드: file (기본값) 대 redis
`iii-state`와 `iii-stream`은 기본적으로 iii-engine에 번들된 파일 기반 KV 스토어를 사용합니다: 스코프마다 하나의 JSON 파일이 있고, 이는 엔진 프로세스의 메모리에 유지되며 타이머에 따라 디스크로 재작성됩니다. 단일 사용자의 로컬 설치에는 이것이 올바른 기본값입니다. 여러 동시 writer가 있는 공유 데몬은 대신 Redis로부터 진짜 키 단위 쓰기를 얻지만, 작업마다 네트워크 왕복이라는 비용이 따릅니다(모든 `state::*` 호출은 여전히 하나의 Redis 연결에서 직렬화되므로, 이는 병렬성이 아니라 파일 스토어의 lock을 소켓으로 바꾸는 것일 뿐입니다).
`AGENTMEMORY_STATE_BACKEND=redis`(와 `AGENTMEMORY_REDIS_URL`)를 설정하면 두 워커 모두 iii-engine의 내장 `redis` 어댑터로 전환됩니다. 이 어댑터는 매 쓰기마다 스코프 전체를 재작성하는 대신 각 키를 Redis 해시 필드(`HSET`)로 저장합니다:
```env
# ~/.agentmemory/.env
AGENTMEMORY_STATE_BACKEND=redis
AGENTMEMORY_REDIS_URL=redis://localhost:6379
```
`AGENTMEMORY_STATE_BACKEND`의 기본값은 `file`입니다. 설정하지 않고 두면 지금의 동작이 그대로 유지되며, 인식되지 않는 값(`file`이나 `redis`가 아닌 모든 값)은 조용히 폴백하지 않고 시작 오류가 됩니다. `/agentmemory/status`와 뷰어의 Health 페이지(State store 행)는 어떤 백엔드가 활성화되어 있는지, 응답하는지를 보고하지만 URL은 절대 보여주지 않습니다.
**순수 `redis://`만 지원합니다.** 고정된 엔진(0.22.1)은 TLS 지원 없이 Redis 클라이언트를 빌드하므로, `rediss://` URL(Upstash, Redis Cloud, 전송 중 암호화를 사용하는 ElastiCache 등 대부분의 매니지드 Redis 서비스가 기본적으로 TLS 전용으로 제공)은 연결에 실패합니다. 연결이 암호화되지 않으므로 Redis 비밀번호와 저장된 모든 메모리가 평문으로 네트워크를 통과합니다: 로컬 Redis나 신뢰하는 사설망 안의 Redis를 가리키십시오. 그 외의 Redis를 사용한다면 agentmemory 호스트에서 암호화된 터널(stunnel, SSH, VPN)을 실행해서, 순수 `redis://` 구간은 그 호스트 안에만 머물게 하고 터널의 업스트림 연결은 암호화·인증되도록 하십시오. Redis 비밀번호에 단일 인용부호가 포함되어 있다면 percent-encode하십시오(`%27`). 엔진은 URL을 파싱하기 전에 YAML 설정 안에서 이를 확장합니다.
**`--instance`당 하나의 Redis 서버.** 엔진의 Redis 키 접두사(`state:`, `stream::`)는 고정되어 있으므로, 동일한 데이터베이스를 가리키는 두 개의 agentmemory 인스턴스(`--instance 1`, `--instance 2`, ...)는 서로의 데이터를 덮어씁니다. 별도의 데이터베이스 인덱스(`redis://localhost:6379/1`)를 사용하면 저장된 데이터는 분리되지만, 엔진은 실시간 뷰어 이벤트를 하나의 Redis pub/sub 채널(`stream::events`)로 중계하고 Redis pub/sub는 데이터베이스 인덱스를 무시하므로, 각 인스턴스의 뷰어는 여전히 다른 인스턴스의 실시간 이벤트를 보게 됩니다. 두 개 이상을 실행할 때는 각 인스턴스에 자체 Redis 서버(또는 포트)를 부여하십시오.
**같은 점과 다른 점.** agentmemory의 모든 기능은 Redis에서도 동작합니다: 세션, 관측, 메모리(remember, supersede, evolve, forget), 검색과 인덱스 버킷, lesson, 그래프, 감사 로그와 그 월별 스코프, 내보내기와 가져오기, 거버넌스 삭제, 통합(consolidation) 상태, 뷰어 스냅샷과 그 실시간 스트림, health 모니터까지 모두 동작합니다. 엔진은 각 스코프를 하나의 Redis 해시(`HSET`/`HGET`/`HGETALL`)로 저장하고, 파일 스토어와 동일한 state 트리거를 발화합니다. 엔진의 세 가지 차이점은 agentmemory 내부에서 처리됩니다:
- Redis는 스코프의 레코드를 고정된 순서 없이 반환합니다. agentmemory는 이를 (레코드 id의 생성 시각, 그다음 타임스탬프 기준으로) 오래된 순으로 정렬하므로, 목록, 페이징, 내보내기 청크가 파일 스토어와 동일한 순서로 반환됩니다.
- 엔진은 Redis에서 부분 업데이트를 Lua 스크립트로 적용하는데, 이 스크립트는 빈 배열을 빈 객체로 바꿔버립니다. agentmemory는 Redis에서 이러한 업데이트를 직접 적용합니다(키 단위 lock 아래에서 읽기, 변경, 쓰기). 그 결과 `tags: []` 같은 필드는 배열로 유지됩니다.
- 레거시 감사 로그 확인은 디스크의 파일 스토어 파일을 찾는 대신 Redis에서 예전 스코프를 읽습니다.
사용자가 직접 챙겨야 할 차이 하나가 있습니다: **Redis가 재시작되면, agentmemory가 재시작되기 전까지 엔진은 뷰어로의 실시간 이벤트 중계를 멈춥니다.** 데이터는 여전히 정상적으로 저장되고 읽힙니다. health 모니터는 30초마다 Redis를 통해 테스트 이벤트를 보냅니다. 돌아오지 않으면 `/agentmemory/status`와 뷰어의 Health 페이지는 "실시간 업데이트가 뷰어에 도달하지 못하고 있습니다"를 해결 방법(agentmemory 재시작)과 함께 보여줍니다. Redis가 다운되었다면 상태 보고서는 "state 저장소가 응답하지 않습니다"와 확인 방법(`redis-cli -u "$AGENTMEMORY_REDIS_URL" ping`)을 보여줍니다. 매우 큰 스코프를 나열하면 하나의 `HGETALL`로 전체 해시를 읽는데, 이는 파일 스토어가 이를 메모리에 유지하는 것과 동일한 비용입니다.
**권장 Redis 설정.** 기본 `save 3600 1 300 100 60 10000` 스냅샷 정책은 크래시 시 몇 분 치의 쓰기를 잃을 수 있는데, 이는 파일 스토어의 5초 flush 윈도우보다 더 나쁩니다. 잃어버리면 곤란한 것이 있다면 `appendonly yes`를 설정하십시오. `maxmemory-policy noeviction`을 설정하십시오. `allkeys-lru` 등은 Redis가 메모리 한도에 도달하면 조용히 메모리를 버립니다.
네이티브(비 Docker) 시작과, 모든 원클릭 [배포 템플릿](../deploy/)(번들된 `iii-config.yaml`을 덮어쓰고 네이티브로 시작하는 것들)은 `AGENTMEMORY_STATE_BACKEND`/`AGENTMEMORY_REDIS_URL`을 읽어 실행되는 `iii-config`에 렌더링합니다. URL 자체는 그 렌더링된 파일에 결코 기록되지 않으며, 엔진 프로세스가 부팅 시 자신의 환경에서 확장하는 `${AGENTMEMORY_REDIS_URL}` 참조만 기록됩니다. 이 저장소 자체의 Docker Compose 경로(`AGENTMEMORY_USE_DOCKER=1`, 또는 그렇게 시작된 엔진을 다시 사용하는 경우)만 `iii-config.docker.yaml`을 읽기 전용으로 마운트하고 절대 렌더링하지 않습니다. `agentmemory start`는 이 조합을 감지하면 경고합니다. 그 파일은 [iii-state](https://workers.iii.dev/workers/iii-state)와 [iii-stream](https://workers.iii.dev/workers/iii-stream) 워커 문서에 나온 동일한 `name: redis` / `config: redis_url: ...` 형태를 따라 직접 바꾸고, `redis_url`을 컨테이너에서 도달 가능한 Redis로 지정하십시오. `docker-compose.yml`은 `AGENTMEMORY_REDIS_URL`을 엔진 컨테이너로 전달하므로, 그곳에서는 `redis_url: '${AGENTMEMORY_REDIS_URL}'`이 동작하며 URL을 마운트된 파일 밖에 유지합니다.
렌더링된 설정은 URL을 `~/.agentmemory/data/iii-config.runtime.yaml` 밖에 유지하지만, 엔진 자체의 설정 워커는 부팅하면 *확장된* 값을 `~/.agentmemory/config/iii-state.yaml`과 `iii-stream.yaml`에 그대로 영속화합니다(iii-engine의 `${VAR}` 확장은 그 워커가 시드를 저장하기 전에 일어나며, 참조가 아니라 해석된 값을 저장합니다). 이 디렉터리는 자격 증명을 담고 있는 것으로 취급하십시오: 공유 호스트에서는 `chmod 700 ~/.agentmemory`를 적용하고, 데이터베이스의 관리자 자격 증명보다는 agentmemory에 필요한 범위로 한정된 Redis ACL 사용자를 사용하십시오.
**마이그레이션은 자동이 아닙니다.** `AGENTMEMORY_STATE_BACKEND`를 전환하면 양쪽 모두 빈 스토어에서 시작합니다. 기존 데이터를 file에서 Redis로, 혹은 그 반대로 복사해 주는 것은 없습니다. 떠나는 백엔드에서 내보내고, 옮겨갈 백엔드로 가져오십시오. 아래 스크립트는 bash와 zsh에서(`bash -u` 포함) 동일하게 동작합니다. 반면 `AUTH=(${AGENTMEMORY_SECRET:+-H "Authorization: Bearer $AGENTMEMORY_SECRET"})` 같은 배열은 그렇지 않습니다: zsh는 이 헤더를 하나의 손상된 단어로 유지하는 반면 bash는 이를 둘로 분리하므로, `AGENTMEMORY_SECRET`이 설정되어 있으면 두 요청 모두 401이 됩니다:
```bash
# 0. Use the generated secret when none is exported:
AGENTMEMORY_SECRET="${AGENTMEMORY_SECRET:-$(cat ~/.agentmemory/secret 2>/dev/null)}"
# 1. On the old backend, while agentmemory is still running on it:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" http://localhost:3111/agentmemory/export > backup.json
else
curl -fsS http://localhost:3111/agentmemory/export > backup.json
fi
# 2. Confirm backup.json is a usable export before switching backends:
jq -e '.version and .exportedAt' backup.json > /dev/null || {
echo "backup.json is not a valid export; do not switch backends" >&2
exit 1
}
# 3. Switch AGENTMEMORY_STATE_BACKEND (and AGENTMEMORY_REDIS_URL if needed),
# restart agentmemory against the new backend, then:
if [ -n "${AGENTMEMORY_SECRET:-}" ]; then
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -H "Authorization: Bearer $AGENTMEMORY_SECRET" -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
else
jq -n --slurpfile d backup.json '{exportData: $d[0], strategy: "merge"}' | \
curl -fsS -X POST http://localhost:3111/agentmemory/import \
-H 'Content-Type: application/json' -d @-
fi
```
`/agentmemory/export`는 큰 코퍼스를 여러 호출로 나누어 처리할 수 있도록 `?maxSessions=`와 `?offset=`도 지원합니다. import의 `strategy`는 `merge`(기본값, 안전함), `replace`, `skip` 중 하나입니다.
### iii가 대체하는 것
| 전통적인 스택 | agentmemory가 사용하는 것 |
|---|---|
| Express.js / Fastify | iii HTTP Trigger |
| SQLite / Postgres + pgvector | iii KV State + 인메모리 벡터 인덱스 |
| SSE / Socket.io | iii Stream (WebSocket) |
| pm2 / systemd | iii 엔진의 워커 감독 |
| Prometheus / Grafana | iii OTEL + health 모니터 |
| 커스텀 플러그인 시스템 | `iii worker add ` |
**소스 파일 219개 · LOC ~52,000줄 · 테스트 2,500+개 · 함수 311개 · KV 스코프 60개**, 모두 세 가지 프리미티브 위에서 동작합니다. `agentmemory plugin install` 같은 것은 없습니다. 플러그인 시스템은 곧 iii 자체입니다.
---
### LLM 프로바이더
agentmemory는 환경에서 프로바이더를 자동으로 감지합니다. 프로바이더를 설정하면 LLM 기반 작업을 사용할 수 있게 되지만, 프로바이더 설정만으로는 LLM이 작성하는 관측 압축이 활성화되지 않습니다. 그 경로에는 프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 모두 필요합니다.
| 프로바이더 | 설정 | 참고 |
|----------|--------|-------|
| **No-op (기본값)** | 설정 필요 없음 | LLM 기반 압축/요약은 비활성화됩니다. synthetic 압축과 BM25 리콜은 계속 동작합니다. 이전에 Claude 구독 폴백에 의존했다면 아래의 `AGENTMEMORY_ALLOW_AGENT_SDK`를 참고하십시오. |
| Anthropic API | `ANTHROPIC_API_KEY` | 토큰 단위 과금 |
| MiniMax | `MINIMAX_API_KEY` | Anthropic 호환 |
| Gemini | `GEMINI_API_KEY` | 임베딩도 함께 활성화 |
| OpenRouter | `OPENROUTER_API_KEY` | 모든 모델 |
| OpenAI API | `OPENAI_API_KEY` | 기본값 `gpt-5.6-luna`, `OPENAI_MODEL`로 재정의 |
| **Local (Ollama / LM Studio / vLLM / llama.cpp)** | `OPENAI_API_KEY=local` + `OPENAI_BASE_URL=http://localhost:11434/v1` (Ollama) 또는 `http://localhost:1234/v1` (LM Studio) + `OPENAI_MODEL=` | OpenAI API와 호환되는 모든 것. 비용 없이 자신의 하드웨어에서 실행됩니다. 아래의 [로컬 모델](#local-models-ollama--lm-studio--vllm)을 참고하십시오. |
| Claude 구독 폴백 | `AGENTMEMORY_ALLOW_AGENT_SDK=true` | Opt-in 전용입니다. `@anthropic-ai/claude-agent-sdk` 세션을 생성하는데, 과거 무한한 Stop-hook 재귀를 일으킨 적이 있어 더 이상 기본값이 아닙니다. |
### 로컬 모델 (Ollama / LM Studio / vLLM)
agentmemory는 OpenAI API와 호환되는 모든 서버와 통신하므로, `/v1/chat/completions`를 노출하는 것이라면 코드 변경 없이 동작합니다. 유료 키도, 클라우드도, rate limit도 없습니다. 모든 것이 사용자의 하드웨어에서 실행됩니다.
**Ollama** (기본 포트 `11434`):
```bash
ollama pull qwen3:8b # or qwen3:4b, gpt-oss:20b, qwen3-coder:30b, etc.
ollama serve
```
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=ollama # any non-empty string; Ollama ignores it
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=qwen3:8b
```
**LM Studio** (기본 포트 `1234`):
LM Studio를 열고 → Local Server 탭 → Start Server를 누르십시오. 선택기에서 원하는 채팅 모델(Qwen 3, gpt-oss, DeepSeek R1 등)을 고르십시오.
```env
# ~/.agentmemory/.env
OPENAI_API_KEY=lmstudio # any non-empty string; LM Studio ignores it
OPENAI_BASE_URL=http://localhost:1234/v1
OPENAI_MODEL=qwen3-8b # match the model name from LM Studio
```
**vLLM / llama.cpp / Text Generation Inference**: 동일한 형태입니다. `OPENAI_BASE_URL`을 서버가 노출하는 URL로 지정하고, `OPENAI_MODEL`을 서버가 받아들이는 이름으로 설정하십시오.
**메모리 작업을 위한 모델 선택**: 압축과 요약은 짧은 작업(입력 2K 토큰 미만, 출력 500 토큰 미만)이므로 7B instruct 모델로도 충분합니다. 추천:
| 모델 | 크기 | 이유 |
|-------|------|-----|
| `qwen3:8b` | ~5.2 GB | 16GB 머신에서 균형 잡힌 기본값. 추출과 도구 형태의 텍스트에 강함 |
| `qwen3:4b` | ~2.6 GB | 가장 작은 합리적 옵션. 압축에는 괜찮지만 그래프 추출에는 약함 |
| `qwen3-coder:30b` | ~19 GB | 24-32GB 하드웨어에서 코드 형태 세션을 위한 최고의 로컬 선택(30B MoE, 활성 3.3B) |
| `gpt-oss:20b` | ~14 GB | 16GB RAM에 맞는 강력한 범용 모델 |
| `deepseek-r1:8b` | ~5.2 GB | reasoning distill. 더 느리지만 더 깔끔한 추출 |
Qwen 3 모델은 기본적으로 thinking을 수행하므로, 출력이 나오기 전에 reasoning에 토큰 예산을 전부 써버릴 수 있습니다. `AGENTMEMORY_LLM_NOTHINK=1`을 설정하면 그래프 추출 프롬프트에 `/no_think`가 덧붙으며, 추출 결과가 비어 있다면 `MAX_TOKENS`를 올리십시오(16384면 충분합니다).
reasoning 계열 모델(`` 블록을 사용하는 `o1` 스타일)은 `content`를 빈 값으로 반환하면서, 로컬 서버가 노출하지 않을 수 있는 `reasoning` 필드만 채울 수 있습니다. 추출 결과가 비어 있다면 먼저 non-reasoning 모델로 바꿔 보십시오. `OPENAI_REASONING_EFFORT=none` 환경 변수는 OpenAI의 reasoning 스키마를 그대로 따르는 Ollama Cloud thinking 모델의 thinking도 비활성화할 수 있습니다.
로컬 임베딩은 선택적 의존성으로 제공되지만 기본적으로 활성화되어 있지 않습니다. `EMBEDDING_PROVIDER=local`을 설정하면 `Xenova/all-MiniLM-L6-v2`(384차원)를 사용하게 됩니다. 첫 임베딩 요청이 모델을 다운로드하고, 이후의 추론은 온디바이스에서 이루어집니다. 이 설정이나 원격 임베딩 키가 없으면 벡터는 비활성화된 채로 남고, `mem::search`는 BM25를 사용하며, `smart-search`는 여전히 기존 그래프 매치를 추가할 수 있습니다.
### 비용을 고려한 모델 선택
프로바이더와 `AGENTMEMORY_AUTO_COMPRESS=true`가 모두 설정되어 LLM이 작성하는 백그라운드 압축이 활성화되면, 이는 모든 관측에 대해 실행되므로 모델 선택이 월간 비용을 상당히 바꿉니다. 캡처된 워크로드 데이터: 요청 635개 / 토큰 888K / 활성 사용 35시간을 2026-05-23 가격 기준 세 가지 OpenRouter 모델에 대해 실행한 결과입니다.
| Tier | 모델 | 입력 / 1M | 출력 / 1M | 캡처된 35시간 기준 비용 | 참고 |
|------|-------|------------|-------------|---------------------------|-------|
| 추천 | `deepseek/deepseek-v4-flash-0731` | $0.07 | $0.14 | ~$0.07 (추정) | 최신 DeepSeek. 압축 워크로드에 가장 저렴하게 추천되는 선택. |
| 추천 | `deepseek/deepseek-v4-pro` | $0.435 | $0.87 | ~$0.46 | Sonnet보다 약 10배 낮은 비용으로 견실한 압축 + 요약 품질. |
| 추천 | `qwen/qwen3-coder` | $0.45 | $1.80 | ~$0.55 | 세션이 코드 중심이라면 강력한 코드 reasoning. |
| 프리미엄 | `anthropic/claude-sonnet-5` | $3.00 | $15.00 | ~$5.02 (추정) | 측정된 Sonnet 4.6 실행과 동일한 정가. 2026-08-31까지는 $2/$10 도입 가격. |
| 프리미엄 | `openai/gpt-5.6-sol` | $5.00 | $30.00 | ~$9 (추정) | 플래그십 등급. 항상 켜져 있는 백그라운드 작업에는 비쌈. |
| 비추천 | `anthropic/claude-opus-5` | $5.00 | $25.00 | ~$8.40 (추정) | 플래그십급 모델. 압축 작업에는 과도한 지출. |
측정된 행은 캡처된 실행에서 나온 것이며, (추정) 행은 동일한 토큰 조합을 각 모델의 정가에 맞춰 환산한 것입니다.
`OPENROUTER_MODEL`이 premium 등급 패턴과 일치하면 agentmemory는 런타임 경고를 출력합니다. 충분히 알고 선택했다면 `AGENTMEMORY_SUPPRESS_COST_WARNING=1`을 설정해 끌 수 있습니다.
메모리 작업에서의 품질 대 비용 트레이드오프: 압축은 품질 기준이 비교적 느슨한 요약 작업입니다(사용자가 아니라 에이전트가 요약을 다시 읽습니다). DeepSeek V4 Flash / V4 Pro / Qwen3-Coder는 이 작업에서 Sonnet과 오차 범위 안에 있으면서 비용은 10~70배 적게 듭니다. premium 등급 모델은 직접 읽는 쿼리를 위해 아껴 두십시오.
출처: [OpenRouter pricing for Claude Sonnet 5](https://openrouter.ai/anthropic/claude-sonnet-5), [DeepSeek V4 Flash](https://openrouter.ai/deepseek/deepseek-v4-flash-0731), [DeepSeek pricing notes](https://api-docs.deepseek.com/quick_start/pricing/).
### 멀티 에이전트 메모리 (`AGENT_ID` + `AGENTMEMORY_AGENT_SCOPE`)
여러 역할(architect / developer / reviewer / researcher / support-agent)이 하나의 agentmemory 서버를 공유하는 멀티 에이전트 구성에서, `AGENT_ID`는 모든 쓰기에 그것을 수행한 역할을 태그합니다. `AGENTMEMORY_AGENT_SCOPE`는 리콜이 그 태그로 필터링되는지를 제어합니다.
```env
TEAM_ID=company
USER_ID=engineering-team
AGENT_ID=architect
AGENTMEMORY_AGENT_SCOPE=isolated # optional; default "shared"
```
두 가지 모드:
| 모드 | 쓰기 태깅 | 리콜 필터링 | 사용 시점 |
|------|------------|---------------|-------------|
| `shared` (기본값) | yes | no | 감사 기록이 남는 에이전트 간 컨텍스트. architect는 developer가 남긴 내용을 볼 수 있지만, 모든 행에는 누가 남겼는지가 기록됩니다. |
| `isolated` | yes | yes | 엄격한 분리. architect는 developer의 관측/메모리/세션을 절대 볼 수 없습니다. |
`AGENT_ID`가 설정되었을 때 태깅되는 것: `Session.agentId`, `RawObservation.agentId`, `CompressedObservation.agentId`, `Memory.agentId`. 역할은 `api::session::start` → `mem::observe` → `mem::compress` → KV로 흐릅니다.
isolated 모드에서 필터링되는 것: `mem::smart-search`, `/agentmemory/memories`, `/agentmemory/observations`, `/agentmemory/sessions`. 각 엔드포인트는 요청별로 재정의하기 위한 `?agentId=`과, env 스코프를 완전히 벗어나기 위한 `?agentId=*`를 받습니다. `/memories`는 또한 `agentId`가 정의되지 않은 pre-AGENT_ID 메모리를 드러내기 위해 `?includeOrphans=true`도 받습니다.
SDK / REST 계층에서의 호출별 재정의: 모든 변형 엔드포인트(`/session/start`, `/remember`)는 요청 본문에 env보다 우선하는 `agentId` 필드를 받습니다. 하나의 서버 프로세스로 여러 역할을 라우팅하는 런타임에 유용합니다. MCP `memory_save` 도구도 동일한 `agentId` 필드를 노출하며, 독립형 stdio 서버는 `agentId`와 `project`를 모두 전달하고, 저장된 메모리는 `agentId`를 검색 인덱스까지 가지고 가므로, 에이전트 범위 검색은 관측뿐 아니라 메모리도 포함합니다.
`AGENT_ID`가 설정되지 않으면 메모리는 스코프 없이 유지됩니다(레거시 동작, 태그 없음, 필터 없음).
### 포트
agentmemory + iii-engine은 기본적으로 네 개의 포트에 바인딩됩니다. 재시작이 `port in use`로 실패하면, 이 표가 어떤 프로세스를 찾아야 하는지 알려줍니다.
| 포트 | 프로세스 | 용도 | 환경 변수 재정의 |
|------|---------|---------|--------------|
| `3111` | agentmemory | REST API + MCP HTTP + `/agentmemory/health` + `/agentmemory/livez` | `III_REST_PORT` |
| `3112` | iii-engine | 내부 스트림 워커 (agentmemory + 뷰어가 사용) | `III_STREAM_PORT` (권장) 또는 레거시 `III_STREAMS_PORT` |
| `3113` | agentmemory | 실시간 뷰어 (`http://localhost:3113`) | `III_VIEWER_PORT`, 또는 보고되는 URL을 위한 `AGENTMEMORY_VIEWER_URL` |
| `49134` | iii-engine | WebSocket. 워커가 이곳에 등록되고 OTel 텔레메트리가 이를 통해 흐름 | `III_ENGINE_PORT` 또는 `III_ENGINE_URL` |
`--port `은 REST 앵커를 변경하고, 위의 대응하는 명시적 포트나 URL이 설정되지 않은 경우에만 스트림을 `N+1`, 뷰어를 `N+2`, 엔진 WebSocket을 `N+46023`으로 파생시킵니다. 이는 독립된 라이프사이클 네임스페이스를 만들지 않습니다. 두 번째 데몬에는 `--instance 1`을 사용하십시오. 앵커 3211을 사용하며 기본값은 `3211/3212/3213/49234`이고, 별도의 `instance-1` 데이터 및 라이프사이클 디렉터리를 받습니다. 인스턴스 1부터 50까지 동일한 패턴을 따릅니다.
고정된 엔진은 `--no-update-check`로 시작됩니다(부팅 시 GitHub에 대한 업데이트나 보안 권고 조회 없음) 그리고 iii의 익명 사용 텔레메트리가 꺼진 상태로 시작됩니다: agentmemory는 변수를 직접 export하지 않는 한 자신이 생성하는 엔진에 대해 `III_TELEMETRY_ENABLED=false`를 설정하며, 번들된 compose 파일도 동일하게 동작합니다.
크래시 이후에도 포트가 바인딩된 채로 남아 있을 때 오래된 프로세스를 정리하는 방법:
```bash
# macOS / Linux — find whatever is on each port and kill it
lsof -i :3111,3112,3113,49134
pkill -f agentmemory || true
pkill -f 'iii ' || true
# Windows
netstat -ano | findstr ":3111 :3112 :3113 :49134"
taskkill /F /PID
```
`agentmemory stop`은 정상적인 네이티브 종료 시 워커와 엔진 pidfile을 모두 깔끔하게 회수합니다. Docker 모드에서는 네이티브 워커를 flush하고, 정확히 검증된 엔진 컨테이너를 중지하며, 무손실 재시작을 위해 컨테이너와 그 `/data` 마운트를 모두 보존합니다. 다음 시작은 동일한 컨테이너를 검증하고 재사용합니다. Docker 기반 제거에는 `agentmemory remove --keep-data`가 필요합니다: 검증된 컨테이너, 그 데이터 마운트, 이를 복구하는 데 필요한 라이프사이클 기록은 보존하면서 agentmemory가 공유로 관리하는 파일만 제거합니다. 파괴적인 Docker 데이터 삭제는 백업 이후 운영자에게 의도적으로 맡겨져 있습니다. CLI는 또한 `--force`가 전달되지 않는 한 Docker나 VM 포트 점유자(Docker backend, vpnkit, colima)를 네이티브 엔진으로 채택하거나 시그널을 보내는 것을 거부합니다. 위의 수동 정리는 어떤 pidfile도 남지 않은 크래시 후 케이스에만 해당됩니다.
### 설정 파일
agentmemory 런타임 설정은 매 셸에서 변수를 export하는 대신 `~/.agentmemory/.env`에 두십시오. 뷰어가 `export ANTHROPIC_API_KEY=...`와 같은 설정 힌트를 보여주면, `export` 접두사 없이 `ANTHROPIC_API_KEY=...`로 이 파일에 복사한 다음 agentmemory를 재시작하십시오.
프로세스 환경 변수는 여전히 동작하며 파일 안의 값보다 우선합니다.
Windows에서는 동일한 파일이 `%USERPROFILE%\.agentmemory\.env`에 있습니다:
```powershell
New-Item -ItemType Directory -Force $HOME\.agentmemory
notepad $HOME\.agentmemory\.env
```
API 키 대신 Claude Code Pro/Max 구독으로 테스트하려면, 명시적으로 opt-in하십시오:
```env
AGENTMEMORY_ALLOW_AGENT_SDK=true
AGENTMEMORY_AUTO_COMPRESS=true
```
LLM이 작성하는 관측 압축에는 두 줄이 모두 필요합니다: LLM 프로바이더에 대한 접근(이 명시적 구독 폴백 포함)과 `AGENTMEMORY_AUTO_COMPRESS=true`입니다. 프로바이더만 있으면 기본 synthetic 압축 경로가 그대로 유지됩니다.
통합(consolidation, 그래프 노드, lesson, crystal)은 LLM 프로바이더가 설정되어 있으면 기본적으로 켜집니다. LLM 없이 동작하고 싶다면 `CONSOLIDATION_ENABLED=false`로 명시적으로 opt-out하십시오. 그래프 추출은 별도의 플래그입니다:
```env
GRAPH_EXTRACTION_ENABLED=true
# CONSOLIDATION_ENABLED=false # opt out of auto-consolidation
```
### 환경 변수
`~/.agentmemory/.env`를 생성하십시오:
```env
# LLM provider (pick one — default is the no-op provider: no LLM calls)
# ANTHROPIC_API_KEY=sk-ant-...
# ANTHROPIC_BASE_URL=... # Optional: Anthropic-compatible proxy / Azure
# GEMINI_API_KEY=...
# OPENROUTER_API_KEY=...
# MINIMAX_API_KEY=...
# OPENAI_API_KEY=*** # NOTE: this same key auto-activates BOTH the
# # OpenAI LLM provider (here) AND the OpenAI
# # embedding provider (further below). Set
# # OPENAI_API_KEY_FOR_LLM=false to scope it
# # to embeddings only.
# OPENAI_BASE_URL=https://api.openai.com # Optional: override for Azure / vLLM / LM Studio / proxies
# # Azure: https://.openai.azure.com/openai/deployments/
# # Auto-detected from `.openai.azure.com` hostname; uses
# # api-key header + api-version query param.
# OPENAI_API_VERSION=2024-08-01-preview # Optional: Azure api-version query param
# OPENAI_MODEL=gpt-5.6-luna # Optional: default model
# OPENAI_TIMEOUT_MS=60000 # Optional: OpenAI-scoped alias for the outbound fetch
# # timeout. Takes precedence over AGENTMEMORY_LLM_TIMEOUT_MS
# # for back-compat with v0.9.17. New configs should
# # prefer the global AGENTMEMORY_LLM_TIMEOUT_MS below.
# OPENAI_REASONING_EFFORT=none # Optional: "low" | "medium" | "high" | "none"
# # Honored only by OpenAI's reasoning models (o1, o3,
# # gpt-*-reasoning) and providers that mirror that
# # schema (Ollama Cloud thinking models). Standard
# # chat models reject this field with 400. Set to
# # "none" for thinking models that return reasoning
# # but no content.
# OPENAI_API_KEY_FOR_LLM=false # Optional: set to false to skip OpenAI auto-detection
# # for LLM (useful if you only want OpenAI for embeddings)
# Opt-in Claude-subscription fallback (spawns @anthropic-ai/claude-agent-sdk);
# leave OFF unless you understand the Stop-hook recursion risk:
# AGENTMEMORY_ALLOW_AGENT_SDK=true
# Embedding provider (BM25-only when unset; local is an explicit opt-in)
# EMBEDDING_PROVIDER=local
# VOYAGE_API_KEY=...
# OPENAI_API_KEY=sk-...
# OPENAI_BASE_URL=https://api.openai.com # Override for Azure / vLLM / LM Studio / proxies
# OPENAI_EMBEDDING_MODEL=text-embedding-3-small
# OPENAI_EMBEDDING_DIMENSIONS=1536 # Required when the model is not in the known-models table
# OPENAI_EMBEDDING_BASE_URL=https://... # Embeddings only; falls back to OPENAI_BASE_URL
# OPENAI_EMBEDDING_API_KEY=sk-... # Embeddings only; wins over OPENAI_API_KEY when set
# Outbound LLM / embedding timeout
# AGENTMEMORY_LLM_TIMEOUT_MS=60000 # Default: 60 000 ms (60 s). Applies to every
# raw-fetch provider (Gemini, OpenRouter, MiniMax,
# OpenAI LLM, OpenAI/Cohere/Voyage/OpenRouter
# embedding). For the OpenAI LLM path, the
# OpenAI-scoped OPENAI_TIMEOUT_MS alias (above)
# takes precedence when set, for back-compat
# with v0.9.17.
# Increase for slow networks or large batch calls;
# decrease to fail-fast on rate-limit holds.
# Search tuning
# BM25_WEIGHT=0.4
# VECTOR_WEIGHT=0.6
# TOKEN_BUDGET=2000
# Auth (generated into ~/.agentmemory/secret on first start when unset)
# AGENTMEMORY_SECRET=your-secret
# VIEWER_ALLOWED_ORIGINS=https://memory.example.com
# AGENTMEMORY_IMPORT_ROOT=~/projects
# Ports (defaults: 3111 API, 3113 viewer)
# III_REST_PORT=3111
# Engine usage telemetry (iii). Off unless you set it; true opts in.
# III_TELEMETRY_ENABLED=false
# Features
# AGENTMEMORY_AUTO_COMPRESS=false # OFF by default. Requires an LLM
# provider as well. When both are on,
# every PostToolUse hook calls your
# LLM provider to compress the
# observation — expect significant
# token spend on active sessions.
# AGENTMEMORY_SLOTS=false # OFF by default. Editable pinned
# memory slots — persona,
# user_preferences, tool_guidelines,
# project_context, guidance,
# pending_items, session_patterns,
# self_notes. Size-limited; agent
# edits via memory_slot_* tools.
# Pinned slots addressable for
# SessionStart injection.
# AGENTMEMORY_REFLECT=false # OFF by default. Requires SLOTS=on.
# Stop hook fires mem::slot-reflect:
# scans recent observations, auto-
# appends TODOs to pending_items,
# counts patterns in
# session_patterns, records touched
# files in project_context. Fire-
# and-forget; does not block.
# AGENTMEMORY_INJECT_CONTEXT=false # OFF by default. When on:
# - SessionStart may inject ~1-2K
# chars of project context into
# the first turn of each session
# (this is what actually reaches
# the model — Claude Code treats
# SessionStart stdout as context)
# - PreToolUse fires /agentmemory/enrich
# on every file-touching tool call
# (resource cleanup, not a token
# fix — PreToolUse stdout is debug
# log only per Claude Code docs)
# Observations are still captured via
# PostToolUse regardless of this flag.
# GRAPH_EXTRACTION_ENABLED=false
# AGENTMEMORY_LLM_NOTHINK=1 # Local reasoning models only: ask the
# model to skip its hidden thinking pass
# during graph extraction. Faster runs;
# relation quality can drop slightly.
# CONSOLIDATION_ENABLED=false # on by default when an LLM provider is configured
# LESSON_DECAY_ENABLED=true
# OBSIDIAN_AUTO_EXPORT=false
# AGENTMEMORY_EXPORT_ROOT=~/.agentmemory
# CLAUDE_MEMORY_BRIDGE=false
# SNAPSHOT_ENABLED=false
# Storage and durability
# AGENTMEMORY_STATE_BACKEND=file # file (default) or redis; see "Storage backend" below
# AGENTMEMORY_REDIS_URL=redis://localhost:6379 # Required with redis, plain redis:// only
# AGENTMEMORY_STATE_SAVE_INTERVAL_MS=2000 # How often the engine writes file state to disk.
# A hard kill loses at most this window.
# AGENTMEMORY_INDEX_SAVE_INTERVAL_MS=600000 # Minimum time between search index saves;
# shutdown and deletes still save at once.
# AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=true # One-time background trim of oversized graph
# provenance; false skips it
# Sessions
# AGENTMEMORY_SESSION_SWEEP_ENABLED=true # Hourly sweep marks sessions left active past
# the threshold as abandoned. Deletes nothing;
# new activity makes the session active again.
# AGENTMEMORY_SESSION_SWEEP_STALE_HOURS=24
# Capture filters (hooks)
# AGENTMEMORY_CAPTURE_ALLOW= # Comma or space list of tool names or globs;
# when set, only these tools are captured
# AGENTMEMORY_CAPTURE_DENY= # Extra names or globs to skip, added to the
# defaults: memory_*, toolsearch,
# listmcpresources, fetchmcpresource
# AGENTMEMORY_CAPTURE_OUTPUT_MAX=8000 # Max characters of tool output per observation
# AGENTMEMORY_PRE_COMPACT_BUDGET=1500 # Token budget for PreCompact context; 0 disables
# Audit log
# AGENTMEMORY_AUDIT_RETENTION_MONTHS=0 # Drop month scopes older than N months; 0 keeps all
# AGENTMEMORY_AUDIT_INDEX_PERSIST=false # 1 or true records index migration and cleanup
# rows (debugging only)
# Team
# TEAM_ID=
# USER_ID=
# TEAM_MODE=private
# Tool visibility: "all" (54 tools, default) or "core" (8 tools, lean)
# AGENTMEMORY_TOOLS=core
```
---
포트 `3111`의 엔드포인트 138개. REST API는 기본적으로 `127.0.0.1`에 바인딩됩니다. 보호된 엔드포인트는 `Authorization: Bearer `을 요구하며, mesh sync 엔드포인트는 양쪽 피어 모두에 `AGENTMEMORY_SECRET`이 명시적으로 설정되어 있어야 합니다.
**인증은 기본적으로 켜져 있습니다.** `AGENTMEMORY_SECRET`이(셸이나 `~/.agentmemory/.env`에) 설정되어 있지 않으면, 서버는 첫 시작 시 무작위 시크릿을 생성해 `~/.agentmemory/secret`에 `0600` 권한으로 저장합니다. 번들된 모든 클라이언트는 로컬 서버와 통신할 때 그곳에서 이를 읽습니다: CLI, 뷰어, `plugin/scripts` 아래의 hook, MCP 서버와 `@agentmemory/mcp` shim, `agentmemory connect`가 작성하는 설정, 그리고 번들된 OpenCode, Pi, OpenClaw, Hermes, filesystem-watcher 통합까지입니다. 저장된 시크릿은 loopback URL(`localhost`, `127.0.0.0/8`, `::1`)에만 전송됩니다. 명시적인 `AGENTMEMORY_SECRET`은 항상 우선하며, 원격 클라이언트는 여전히 이를 설정해야 합니다. Docker와 `deploy/` 진입점은 이미 자체 시크릿을 생성하고 export합니다. API를 직접 호출하려면:
```bash
curl -H "Authorization: Bearer $(cat ~/.agentmemory/secret)" http://localhost:3111/agentmemory/health
```
**쓰기 요청 규칙.** REST API와 뷰어에 대한 `POST`, `PUT`, `PATCH`, `DELETE` 요청은 본문이 있을 때마다 `Content-Type: application/json`을 보내야 하며(`charset` 파라미터는 괜찮습니다), `Origin` 헤더가 있다면 설정된 REST 또는 뷰어 포트의 loopback origin이거나 `VIEWER_ALLOWED_ORIGINS`(쉼표로 구분, 예: `https://memory.example.com`)에 나열되어 있어야 합니다. `Origin` 헤더를 보내지 않는 클라이언트(CLI, hook, MCP, curl, 서버 간 호출)는 영향을 받지 않습니다. 뷰어는 자신의 origin도 허용합니다.
**파일 경로.** 파일을 읽거나 쓰는 엔드포인트(`/compress-file`, `/replay/import-jsonl`, `/graph/import-graphify`)는 `~/.agentmemory`, 인스턴스 데이터 디렉터리, 또는 `AGENTMEMORY_IMPORT_ROOT`에 나열된 디렉터리(여러 개는 `:`로, Windows에서는 `;`로 구분) 아래의 경로만 받습니다. `/replay/import-jsonl`은 기본값인 `~/.claude/projects`도 받습니다. `/obsidian/export`는 `AGENTMEMORY_EXPORT_ROOT` 안에, `/migrate`는 `~/.agentmemory` 안에 머뭅니다. 심볼릭 링크는 매 검사 전에 해석됩니다.
**시크릿 제거.** API 키, bearer 토큰, PEM 개인 키 블록, URL에 내포된 자격 증명(`scheme://user:password@host`)은 텍스트가 저장되기 전에 모든 쓰기 경로에서 삭제됩니다: 관측, remember, evolve, slot, lesson, action, sketch, signal, checkpoint, import, jsonl replay, mesh sync, team share, 압축과 요약 출력, crystal, 그래프 노드까지입니다.
주요 엔드포인트
| 메서드 | Path | 설명 |
|--------|------|-------------|
| `GET` | `/agentmemory/health` | Health 체크 (항상 공개) |
| `GET` | `/agentmemory/status` | 무엇이 문제인지와 해결 방법 (브라우저에는 HTML, 그 외에는 JSON) |
| `GET` | `/agentmemory/viewer/snapshot` | 뷰어가 보여주는 모든 것을 하나의 응답으로 |
| `POST` | `/agentmemory/session/start` | 세션 시작 + 컨텍스트 받기 |
| `POST` | `/agentmemory/session/end` | 세션 종료 |
| `POST` | `/agentmemory/observe` | 관측 캡처 (아래의 캡처 전달 참고) |
| `GET` | `/agentmemory/capture` | 캡처 인박스, dead letter, 오프라인 spool |
| `POST` | `/agentmemory/capture/retry` | dead-letter 캡처 재시도 |
| `POST` | `/agentmemory/capture/drain` | 로컬 오프라인 spool을 지금 전송 |
| `POST` | `/agentmemory/smart-search` | 하이브리드 검색 |
| `POST` | `/agentmemory/context` | 컨텍스트 생성 |
| `POST` | `/agentmemory/remember` | 장기 메모리에 저장 |
| `POST` | `/agentmemory/forget` | 관측 삭제 |
| `POST` | `/agentmemory/enrich` | 파일 컨텍스트 + 메모리 + 버그 |
| `GET` | `/agentmemory/profile` | 프로젝트 프로필 |
| `GET` | `/agentmemory/export` | 모든 데이터 내보내기 |
| `POST` | `/agentmemory/import` | JSON에서 가져오기 |
| `POST` | `/agentmemory/graph/query` | 지식 그래프 쿼리 |
| `POST` | `/agentmemory/graph/compact` | 과도하게 커진 그래프 출처 정리 |
| `POST` | `/agentmemory/team/share` | 팀과 공유 |
| `GET` | `/agentmemory/audit` | 감사 기록 |
전체 엔드포인트 목록: [`src/triggers/api.ts`](../src/triggers/api.ts)
**캡처 전달.** hook은 각 관측을 `eventId`와 함께 `POST /agentmemory/observe`로 한 번 전송합니다. payload에 자체 id가 있으면(예: Claude Code의 `tool_use_id`) 그 호출의 호스트 고유 id를 사용하고, 없으면 세션, hook 유형, 도구 이름, 입력, 출력, 호스트 타임스탬프의 해시를 사용합니다. 서버는 이벤트를 state 저장소의 캡처 인박스에 기록하고, 관측을 저장한 다음, 인박스 항목을 제거합니다. 상태 코드는 무슨 일이 있었는지를 알려줍니다:
| 상태 코드 | `status` 필드 | 의미 |
|---|---|---|
| `201` | `accepted` | 저장됨. `observationId`는 새로운 관측입니다. |
| `202` | `accepted` (`state: "retrying"`) | 수락되었지만 저장에 실패했습니다. 서버는 재시작 후에도 이를 재시도합니다. |
| `200` | `duplicate` | 이 `eventId`는 이미 수락되었습니다. `observationId`는 기존 관측이며, 새로 저장되는 것은 없습니다. |
| `400` / `422` | `rejected` | payload가 잘못되었거나 저장이 영구적으로 실패했습니다 (이벤트는 dead letter로 보관됩니다). |
| `503` | `rejected` (`retryable: true`) | 인박스가 가득 찼습니다(`AGENTMEMORY_CAPTURE_INBOX_MAX`). hook은 이벤트를 spool에 저장해 두고 나중에 전송합니다. |
실패한 이벤트는 `AGENTMEMORY_CAPTURE_RETRY_INTERVAL_MS`(10초)마다 백오프를 두 배씩 늘려가며 `AGENTMEMORY_CAPTURE_MAX_ATTEMPTS`(5회)까지 재시도됩니다. 여전히 실패하는 이벤트는 dead letter로 인박스에 남아 `/agentmemory/status`와 뷰어의 Health 페이지에 나열되며, `POST /agentmemory/capture/retry`(`{"eventId": "..."}` 또는 `{"all": true}`)로 재시도할 수 있습니다. 수락된 이벤트 id는 `AGENTMEMORY_CAPTURE_DEDUP_HOURS`(168시간, 최대 `AGENTMEMORY_CAPTURE_EVENTS_MAX`개) 동안 기억되므로, 타임아웃이나 재시작 후 재생된 hook은 한 번만 저장되지만, 각자 호스트 id를 가진 두 개의 별도 도구 호출은 내용이 동일해도 두 번 저장됩니다. 관측이 삭제되면(forget, 세션 삭제, eviction, 자동 망각, 또는 스토어를 교체하는 import) 그 이벤트는 관측이 제거되기 전에 삭제됨으로 표시되므로, 같은 시간 범위 안에서 그 이벤트를 재생하면 duplicate로 응답되고 아무것도 저장하지 않습니다. state 저장소는 2초마다 디스크에 기록하므로, 응답된 이벤트가 잠깐 동안은 메모리에만 있을 수 있습니다. 이를 보완하기 위해 모든 `2xx` 응답은 서버의 `bootId`(매 시작마다 새로 생성), `acceptedAt`, `durableAfterMs`(파일 스토어에서는 저장 간격 + 1.5초, redis에서는 1.5초이며, 영속성은 운영자의 설정에 따름)도 함께 전달합니다. hook은 그 시간 범위가 지날 때까지 이벤트를 로컬 spool에 보관하고, 추가 요청 없이 이후 호출에서 이를 삭제합니다. 그 사이에 `bootId`가 바뀌었다면 서버가 재시작된 것이므로, hook은 동일한 `eventId`로 이벤트를 다시 보냅니다. 디스크에 실제로 도달한 이벤트는 두 번 저장되지 않습니다. 서버 또한 시작 시와 매 재시도 간격마다 그런 이벤트를 스스로 전송하므로, 이후 어떤 hook도 실행되지 않더라도 재시작으로 데이터가 손실되지 않습니다. 오래된 hook은 추가 필드를 무시하고, 더 오래된 서버를 상대하는 새 hook은 예전처럼 `2xx`에서 이벤트를 버립니다.
서버가 다운되었거나, 제때 응답하지 않거나, 5xx를 반환하면, hook은 관측을 로컬 spool 파일 `/capture-spool/-.jsonl`에 추가합니다(폴더는 `AGENTMEMORY_CAPTURE_SPOOL_DIR`로 재정의할 수 있습니다). 이 파일은 사용자 전용(모드 600)이며, 시크릿은 서버가 제거하는 방식과 동일하게 제거되고, 최대 `AGENTMEMORY_CAPTURE_SPOOL_MAX_BYTES`(5MiB)까지 보관하며 `AGENTMEMORY_CAPTURE_SPOOL_MAX_AGE_HOURS`(168)보다 오래된 항목은 버립니다. 가득 차면 새 항목은 버려지고 집계되며, `/agentmemory/status`가 이를 보고합니다. 서버가 정상일 때는 hook이 여전히 시간 제한 안에 0으로 종료하고 추가 요청을 보내지 않습니다. spool은 다음 시작 시점과, 서버에 다시 도달하는 첫 hook에 의해 백그라운드 프로세스로 전송되므로 에이전트가 기다리지 않습니다. 이벤트 id가 이를 안전하게 만듭니다: 타임아웃 전에 실제로 도착한 관측은 두 번 저장되지 않습니다. `npx @agentmemory/agentmemory capture`는 spool과 서버 인박스를 보여주고, `--drain`은 지금 spool을 전송하며, `GET /agentmemory/capture`는 동일한 내용을 JSON으로 반환합니다. spool을 끄려면 `AGENTMEMORY_CAPTURE_SPOOL=false`를 설정하십시오.
**그래프 출처 압축.** 각 지식 그래프 노드와 엣지는 자신이 비롯된 가장 최근 관측 32개의 id를 보관합니다. 이 한도가 적용되기 전에 작성된 스토어는 활발한 노드마다 수천 개의 id를 가지고 있을 수 있는데, 이는 그래프 검색과 뷰어를 느리게 만들거나 워커를 다운시킵니다. agentmemory는 스스로 이를 고칩니다: 업그레이드 후 첫 시작 시, 모든 노드, 엣지, 대체된 엣지(시간적 그래프 기록), 캐시된 스냅샷을 백그라운드에서 그 한도까지 작은 조각 단위로, 사이에 일시 정지를 두고 정리하므로 검색, 캡처, 뷰어는 계속 동작합니다. 진행 상황을 저장하고, 재시작 후 이어서 진행하며, 완료되면 다시는 실행되지 않습니다. `/agentmemory/status`와 뷰어의 Health 페이지는 이를 pending, running(현재 스코프와 위치와 함께), done, failed로 보여줍니다. 끄려면 `AGENTMEMORY_GRAPH_COMPACT_ON_BOOT=false`를 설정하십시오.
수동으로 실행하려면 `POST /agentmemory/graph/compact`를 호출하십시오. 모든 노드와 엣지를 나열하는 대신 name과 edge-key 인덱스를 순회하며, 다시 실행해도 안전합니다. id를 정리할 때는 `graph_compact` 감사 항목을 기록합니다.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{}'
```
큰 스토어에서, 또는 호출이 504를 반환할 때는 조각 단위로 실행하십시오. `scope`(`nodes`, `edges`, `history`), `offset`, `limit`을 보낸 다음, 반환된 `nextOffset`이 `null`이 될 때까지 다시 호출하십시오. `nodes`, `edges`, `history` 각각에 대해 이를 수행하고, 조각 단위 실행은 캐시된 스냅샷을 건드리지 않으므로 마지막에 `{"scope":"snapshot"}` 호출 하나로 마무리하십시오.
```bash
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"nodes","offset":0,"limit":200}'
curl -X POST http://localhost:3111/agentmemory/graph/compact -H "Content-Type: application/json" -d '{"scope":"snapshot"}'
```
---
```bash
npm run dev # Hot reload
npm run build # Production build
npm test # 2,500+ tests
npm run test:integration # API tests (requires running services)
```
**사전 요구 사항:** npm/npx가 포함된 Node.js >= 20; [iii-engine](https://iii.dev/docs) v0.22.1 또는 Docker. macOS/Linux 자동 엔진 설치에는 `curl`, POSIX `sh`, `tar`도 필요합니다. 네이티브 Windows는 수동으로 고정한 `iii.exe`, WSL2, 또는 Docker Desktop을 사용합니다.
