rohitg00/agentmemory

**
당신의 코딩 에이전트(coding agent)는 모든 것을 기억합니다. 더 이상 다시 설명할 필요가 없습니다.
iii engine을 기반으로 구축되었습니다.
**

Claude Code, Cursor, Gemini CLI, Codex CLI, Hermes, OpenClaw, pi, OpenCode, 그리고 모든 MCP 클라이언트를 위한 지속성 메모리 (Persistent memory).

이 프로젝트의 핵심은 Karpathy의 LLM Wiki 패턴에 신뢰도 점수 (confidence scoring), 라이프사이클 (lifecycle), 지식 그래프 (knowledge graphs), 그리고 하이브리드 검색 (hybrid search)을 확장한 것이며, agentmemory는 그 구현체입니다.

빠른 시작 (Quick Start) • 벤치마크 (Benchmarks) • 경쟁사 비교 (vs Competitors) • 에이전트 (Agents) • 작동 원리 (How It Works) • MCP • 뷰어 (Viewer) • iii Console • iii 기반 (Powered by iii) • 설정 (Config) • API

agentmemory는 훅 (hooks), MCP, 또는 REST API를 지원하는 모든 에이전트와 함께 작동합니다. 모든 에이전트는 동일한 메모리 서버를 공유합니다.

Claude Code (12 hooks + MCP + skills)
|
OpenClaw (MCP + plugin)
|
Hermes (MCP + plugin)
|
Cursor (MCP server)
|
Gemini CLI (MCP server)
|
OpenCode (MCP server)
|
Codex CLI (6 hooks + MCP + skills)
|
Cline (MCP server)
|
Goose (MCP server)
|
Kilo Code (MCP server)
|
Aider (REST API)
|
Claude Desktop (MCP server)
|
Windsurf (MCP server)
|
Roo Code (MCP server)
|
Claude SDK (AgentSDKProvider)
|
모든 에이전트 (REST API)
|

MCP 또는 HTTP를 사용하는 모든 에이전트와 작동합니다. 하나의 서버로, 모든 에이전트 간에 메모리가 공유됩니다.

당신은 매 세션마다 동일한 아키텍처를 설명합니다. 동일한 버그를 다시 발견합니다. 동일한 선호도를 다시 가르칩니다. 내장된 메모리 (CLAUDE.md, .cursorrules)는 200줄에서 한계에 도달하며 오래된 정보가 됩니다. agentmemory는 이를 해결합니다. 에이전트가 수행하는 작업을 조용히 캡처하여 검색 가능한 메모리로 압축하고, 다음 세션이 시작될 때 적절한 컨텍스트 (context)를 주입합니다. 단 하나의 명령으로, 에이전트 간에 작동합니다.

무엇이 변하는가: 세션 1에서 JWT 인증을 설정합니다. 세션 2에서 속도 제한 (rate limiting)을 요청합니다. 에이전트는 이미 당신의 인증이 src/middleware/auth.ts에서 jose 미들웨어를 사용한다는 것, 당신의 테스트가 토큰 검증을 포함한다는 것, 그리고 Edge 호환성을 위해 jsonwebtoken 대신 jose를 선택했다는 것을 알고 있습니다. 다시 설명할 필요도, 복사해서 붙여넣을 필요도 없습니다. 에이전트는 그냥 알고 있습니다.

npx @agentmemory/agentmemory

v0.9.0 신규 사항— 랜딩 페이지 agent-memory.dev, 파일 시스템 커넥터 (@agentmemory/fs-watcher)

standalone MCP가 이제 실행 중인 서버로 프록시(proxy)되어 훅(hook)과 뷰어(viewer)가 일치하도록 개선되었습니다. 모든 삭제 경로에 걸쳐 감사 정책(audit policy)이 코드화되었으며, 아주 작은 Node 프로세스에서 memory_critical 플래그가 발생하는 건강 상태(health) 문제가 해결되었습니다. 자세한 내용은 CHANGELOG.md를 참조하세요.

|
|
|

임베딩 모델 (Embedding model):

all-MiniLM-L6-v2

(로컬, 무료, API 키 불필요). 전체 보고서: benchmark/LONGMEMEVAL.md, benchmark/QUALITY.md, benchmark/SCALE.md. 경쟁사 비교: benchmark/COMPARISON.md — agentmemory 대 mem0, Letta, Khoj, claude-mem, Hippo.

feature	agentmemory	mem0 (53K ⭐)	Letta / MemGPT (22K ⭐)	Built-in (CLAUDE.md)
유형 (Type)	Memory engine + MCP server	Memory layer API	Full agent runtime	Static file
검색 성능 R@5 (Retrieval R@5)	95.2%	68.5% (LoCoMo)	83.2% (LoCoMo)	N/A (grep)
자동 캡처 (Auto-capture)	12 hooks (수동 작업 없음)	수동 add() 호출	에이전트 자체 편집	수동 편집
검색 (Search)	BM25 + Vector + Graph (RRF fusion)	Vector + Graph	Vector (archival)	컨텍스트에 모든 내용 로드
멀티 에이전트 (Multi-agent)	MCP + REST + leases + signals	API (조정 없음)	Letta 런타임 내에서만 가능	에이전트별 파일
프레임워크 종속성 (Framework lock-in)	없음 (모든 MCP 클라이언트)	없음	높음 (Letta 사용 필수)	에이전트별 형식
외부 의존성 (External deps)	없음 (SQLite + iii-engine)	Qdrant / pgvector	Postgres + vector DB	없음
메모리 생명주기 (Memory lifecycle)	4단계 통합 + 감쇠 + 자동 망각	수동 추출	에이전트 관리	수동 가지치기
토큰 효율성 (Token efficiency)	세션당 ~1,900 토큰 ($10/yr)	통합 방식에 따라 다름	핵심 메모리가 컨텍스트에 포함	240개 관측치 기준 22K+ 토큰
실시간 뷰어 (Real-time viewer)	있음 (port 3113)	클라우드 대시보드	클라우드 대시보드	없음
셀프 호스팅 (Self-hosted)	있음 (기본값)	선택 사항	선택 사항	있음

호환성: 이번 릴리스는 안정적인 iii-sdk ^0.11.0 및 iii-engine v0.11.x를 대상으로 합니다.

# 터미널 1: 서버 시작
npx @agentmemory/agentmemory
# 터미널 2: 샘플 데이터 시딩 및 회상(recall) 작동 확인
...

demo

3개의 현실적인 세션(JWT 인증, N+1 쿼리 수정, 속도 제한 (rate limiting))을 시딩 (seeds)하고 이에 대해 의미론적 검색 (semantic searches)을 실행합니다. "database performance optimization"을 검색했을 때 "N+1 query fix"를 찾아내는 것을 볼 수 있습니다. 키워드 매칭 (keyword matching)으로는 이를 수행할 수 없습니다.

http://localhost:3113을 열어

메모리가 실시간으로 구축되는 과정을 확인하세요.

agentmemory가 기록하는 모든 세션은 재생 (replayable)이 가능합니다. 뷰어를 열고 Replay 탭을 선택한 뒤 타임라인을 탐색해 보세요. 프롬프트 (prompts), 도구 호출 (tool calls), 도구 결과 (tool results), 그리고 응답 (responses)이 재생/일시정지, 속도 조절 (0.5×–4×), 그리고 키보드 단축키 (스페이스바: 토글, 화살표: 단계별 이동) 기능이 포함된 개별 이벤트로 렌더링됩니다.

가져오고 싶은 이전의 Claude Code JSONL 트랜스크립트 (transcripts)가 이미 있나요?

# 기본 ~/.claude/projects 하위의 모든 항목을 가져오기
npx @agentmemory/agentmemory import-jsonl
# 또는 단일 파일 가져오기
...

가져온 세션은 네이티브 세션과 함께 Replay 선택기에 나타납니다. 내부적으로 각 항목은 사이드 채널 서버 없이 mem::replay::load, mem::replay::sessions, 그리고 mem::replay::import-jsonl 함수를 통해 라우팅됩니다.

로컬 런타임 (runtime)을 의도적으로 업데이트하려는 경우 유지 관리 명령어를 사용하세요:

npx @agentmemory/agentmemory upgrade

경고: 이 명령어는 현재 워크스페이스/런타임을 변경합니다. JavaScript 의존성 (dependencies)을 업데이트할 수 있으며, cargo install iii-engine --force를 실행할 수 있고, Docker 이미지를 가져올 수 있습니다.

구현 세부 사항은 src/cli.ts에 있습니다 (src/cli.ts:544-595 영역 근처의 runUpgrade를 참조하세요).

agentmemory 설치: 별도의 터미널에서 npx @agentmemory/agentmemory를 실행하여 메모리 서버 (memory server)를 시작하세요. 그 다음 /plugin marketplace add rohitg00/agentmemory와 /plugin install agentmemory를 실행합니다. 이 플러그인은 12개의 모든 훅 (hooks), 4개의 스킬 (skills)을 등록하며, .mcp.json을 통해 @agentmemory/mcp stdio 서버를 자동으로 연결 (auto-wires)하므로, 추가적인 설정 단계 없이도 51개의 MCP 도구 (memory_smart_search, memory_save, memory_sessions, memory_governance_delete 등)를 사용할 수 있습니다. curl http://localhost:3111/agentmemory/health로 확인하세요. 실시간 뷰어 (real-time viewer)는 http://localhost:3113에서 확인할 수 있습니다.

# 1. 별도의 터미널에서 메모리 서버 시작
npx @agentmemory/agentmemory
# 2. agentmemory 마켓플레이스 등록 및 플러그인 설치
...

Codex 플러그인은 Claude Code 플러그인과 동일한 plugin/ 디렉토리에서 제공됩니다. 이 플러그인은 다음을 등록합니다:

• @agentmemory/mcp를 MCP 서버로 등록 (AGENTMEMORY_TOOLS=all 설정 시 51개 도구 전체 사용 가능)
• 6개의 라이프사이클 훅 (lifecycle hooks): SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop
• 4개의 스킬 (skills): /recall, /remember, /session-history, /forget

Codex의 훅 엔진 (hook engine)은 훅 서브프로세스 (hook subprocesses)에 CLAUDE_PLUGIN_ROOT를 주입하므로 (codex-rs/hooks/src/engine/discovery.rs에 따라), 동일한 훅 스크립트가 중복 없이 두 호스트 모두에서 작동합니다. Subagent / SessionEnd / Notification / TaskCompleted / PostToolUseFailure 이벤트는 Claude-Code 전용이며 Codex에는 등록되지 않습니다.

OpenClaw (이 프롬프트를 붙여넣으세요)

OpenClaw를 위한 agentmemory를 설치하세요. 별도의 터미널에서 `npx @agentmemory/agentmemory`를 실행하여 localhost:3111에서 메모리 서버를 시작하세요. 그 다음, 51개의 모든 메모리 도구와 함께 agentmemory를 사용할 수 있도록 이 내용을 내 OpenClaw MCP 설정에 추가하세요:
{
"mcpServers": {
...

전체 가이드: integrations/openclaw/

Hermes Agent (이 프롬프트를 붙여넣으세요)

Hermes용 agentmemory를 설치합니다. 별도의 터미널에서 npx @agentmemory/agentmemory를 실행하여 localhost:3111에서 메모리 서버 (memory server)를 시작하세요. 그런 다음, Hermes가 51개의 모든 메모리 도구 (memory tools)를 갖춘 MCP 서버 (MCP server)로서 agentmemory를 사용할 수 있도록 다음 내용을 ~/.hermes/config.yaml에 추가하세요:

mcp_servers:
agentmemory:
...

전체 가이드: integrations/hermes/

메모리 서버 (memory server) 시작: npx @agentmemory/agentmemory

agentmemory 항목은 mcpServers 형태를 사용하는 모든 호스트 (Cursor, Claude Desktop, Cline, Roo Code, Windsurf, Gemini CLI, OpenClaw)에서 **동일한 MCP 서버 블록 (MCP server block)**입니다:

"agentmemory": {
  "command": "npx",
  "args": ["-y", "@agentmemory/mcp"],
  ...
}

이 항목을 호스트의 설정 파일 (config file) 내 기존 mcpServers 객체 (object)에 병합 (Merge) 하세요 — 파일을 교체하지 마세요. 파일에 이미 다른 서버들이 있다면, mcpServers 내부의 또 다른 키 (key)로서 agentmemory를 옆에 추가하세요. 만약 mcpServers가 아예 없다면, { "mcpServers": { ... } } 내부에 해당 블록을 붙여넣으세요.

에이전트 (Agent)	설정 파일 (Config file)	참고 사항 (Notes)
Cursor	~/.cursor/mcp.json	mcpServers에 병합. 웹사이트에서 원클릭 딥링크 (deeplink) 사용 가능.
Claude Desktop	claude_desktop_config.json (Application Support)	mcpServers에 병합. 편집 후 Claude Desktop을 재시작하세요.
Cline / Roo Code / Kilo Code	Cline MCP 설정 (Settings UI → MCP Servers → Edit)	동일한 mcpServers 블록 사용.
Windsurf	~/.codeium/windsurf/mcp_config.json	동일한 mcpServers 블록 사용.
Gemini CLI	~/.gemini/settings.json	gemini mcp add agentmemory npx -y @agentmemory/mcp --scope user (자동 병합).
OpenClaw	OpenClaw MCP 설정	동일한 mcpServers 블록을 사용하거나, 더 심층적인 메모리 플러그인 (memory plugin)을 사용하세요.
Codex CLI (MCP 전용)	.codex/config.toml	TOML 형태: codex mcp add agentmemory -- npx -y @agentmemory/mcp 또는 [mcp_servers.agentmemory]를 수동으로 추가.
Codex CLI (전체 플러그인)	Codex 플러그인 마켓플레이스 (plugin marketplace)	codex plugin marketplace add rohitg00/agentmemory 실행 후 codex plugin install agentmemory 실행.

MCP에 6개의 라이프사이클 후크(SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, Stop)와 4가지 스킬을 등록합니다. | OpenCode | opencode.json | 다른 형태 — 최상위 mcp 키 아래에 명령이 배열 형태로 지정됩니다: {"mcp": {"agentmemory": {"type": "local", "command": ["npx", "-y", "@agentmemory/mcp"], "enabled": true}}} . | pi | ~/.pi/agent/extensions/agentmemory | integrations/pi를 복사하고 pi를 재시작합니다. | Hermes Agent | ~/.hermes/config.yaml | memory.provider: agentmemory를 사용하여 더 깊은 메모리 제공자 플러그인을 사용합니다. | Goose | Goose MCP 설정 UI | 동일한 mcpServers 블록을 사용합니다. | Aider | n/a | REST API에 직접 연결하여 사용합니다: curl -X POST http://localhost:3111/agentmemory/smart-search -d '{"query": "auth"}' . | 모든 에이전트 (32+) | n/a | npx skillkit install agentmemory가 호스트를 자동 감지하고 병합합니다.

샌드박스 MCP 클라이언트 (Flatpak / Snap / 제한적인 컨테이너)의 경우, 호스트의 localhost에 접근할 수 없습니다.
: 환경 변수(env) 블록에 `

macOS x64: aarch64-apple-darwin 대신 x86_64-apple-darwin 사용

Linux x64: x86_64-unknown-linux-gnu 대신 swap

Linux arm64: aarch64-unknown-linux-gnu 대신 swap

Windows: iii-hq/iii releases v0.11.2에서 iii-x86_64-pc-windows-msvc.zip을 다운로드하여 iii.exe를 압축 해제한 후, PATH에 추가하세요.

또는 Docker를 사용하세요 (번들로 포함된 docker-compose.yml이 iiidev/iii:0.11.2를 pull 합니다). 전체 문서: iii.dev/docs.

agentmemory는 Windows 10/11에서 실행되지만, Node.js 패키지만으로는 충분하지 않습니다. 백그라운드 프로세스로 별도의 네이티브 바이너리인 iii-engine 런타임(runtime)이 필요합니다. 공식 업스트림(upstream) 설치 프로그램은 sh 스크립트이며, 현재 PowerShell 설치 프로그램이나 scoop/winget 패키지는 제공되지 않으므로 Windows 사용자는 두 가지 경로가 있습니다:

옵션 A — 사전 빌드된 Windows 바이너리 (권장):

# 1. 브라우저에서 https://github.com/iii-hq/iii/releases/tag/iii%2Fv0.11.2 를 엽니다.
# (agentmemory가 engine v0.11.6+에서 요구하는 새로운 샌드박스(sandbox) 모델에 맞춰
# 리팩토링될 때까지 v0.11.2로 고정합니다)
...

옵션 B — Docker Desktop:

# 1. Windows용 Docker Desktop을 설치합니다.
# 2. Docker Desktop을 시작하고 엔진이 실행 중인지 확인합니다.
# 3. agentmemory를 실행합니다 — 번들된 compose 파일이 자동으로 시작됩니다:
...

옵션 C — 독립형 MCP 전용 (엔진 미포함): 에이전트(agent)를 위한 MCP 도구만 필요하고 REST API, 뷰어(viewer) 또는 크론 작업(cron jobs)이 필요하지 않다면, 엔진을 완전히 건너뛰세요:

npx -y @agentmemory/agentmemory mcp
# 또는 shim 패키지를 통해:
npx -y @agentmemory/mcp