여러 코딩 에이전트가 이어 쓰는 장기 메모리 — ai-memory

AI 요약

ai-memory는 Claude Code에서 중단한 작업을 OpenAI Codex, Cursor, Gemini CLI 같은 다른 에이전트에서 이어 가도록 설계한 장기 메모리 시스템입니다. 각 에이전트가 따로 저장하는 메모리는 한 컴퓨터와 한 도구에 묶이지만, ai-memory는 서버 하나를 여러 에이전트와 컴퓨터, 팀원이 함께 사용하도록 구성합니다. 프로젝트 지식은 공유하고 개인별 handoff는 분리하며, 여러 사용자의 인증과 작성자 표시, 변경 audit log를 기본 기능으로 제공합니다.

■ 기록부터 재개까지의 흐름

작업 중 에이전트가 발생시키는 prompt, tool call, session boundary를 lifecycle hook이 관찰합니다. 관찰 내용은 typed privacy boundary에서 정제한 뒤 서버에 저장합니다. 세션이 끝나면 관찰 데이터가 프로젝트의 Markdown wiki 페이지로 정리됩니다. 이 과정에 LLM을 선택적으로 붙여 세션 요약을 만들 수 있지만, 기본 경로는 LLM 호출 없이 동작합니다. 다음 세션은 제한된 분량의 brief를 받고, 필요하면 전체 메모리를 검색합니다.

흐름은 capture → consolidate → recall → handoff입니다. capture는 hook이 작업을 조용히 수집하는 단계이고, consolidate는 세션 종료 시 읽을 수 있는 wiki 페이지를 만드는 단계입니다. recall은 검색과 brief 주입으로 필요한 맥락을 가져옵니다. handoff는 다음 에이전트가 이어받을 작업 위치, 실패한 접근, 남은 질문을 명시적으로 전달합니다. handoff는 단순한 관례가 아니라 타입, 소유자, 한 번만 claim하는 규칙을 가진 protocol로 구현합니다.

■ Markdown 원본과 검색 인덱스

기억의 원본은 Git으로 관리하는 일반 .md 파일입니다. grep으로 찾거나 Obsidian에서 열고, 직접 수정하거나 rsync로 옮길 수 있습니다. SQLite 데이터베이스는 Markdown에서 다시 만들 수 있는 파생 인덱스입니다. 따라서 기억을 바이너리 저장소나 특정 vector store에 가두지 않습니다.

Rust로 만든 단일 바이너리가 MCP/HTTP 서버와 하나의 data directory를 관리합니다. 디렉터리는 wiki/에 Markdown 원본, raw/에 정제된 managed-workstream transcript 조각, db/에 SQLite 인덱스, models/에 로컬 embedding 모델 영역, logs/에 tracing 로그를 둡니다. 서버는 쓰기를 하나의 SQLite writer로 직렬화하고, FTS5 전문 검색, entity 검색, graph neighbor 검색, 선택적인 vector 검색 결과를 RRF 방식으로 합칩니다. 전역 검색이 아닌 경우에는 원본 관찰 데이터도 제한적으로 보조 검색 결과에 포함합니다.

■ 에이전트와 환경 지원

README는 Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro 등 20개가 넘는 harness를 first-party integration으로 열거합니다. 통합 방식은 MCP 등록, lifecycle hook, 또는 두 방식을 함께 사용합니다. Linux와 macOS, WSL2 기반 Windows를 지원하고 native Windows는 Experimental로 표시합니다. Claude Desktop, VS Code Copilot, Zed처럼 MCP-only인 클라이언트도 별도 상태로 구분합니다.

서버는 노트북에서만 실행해도 되고, homelab이나 LAN의 다른 컴퓨터에 배치해 여러 머신과 팀원이 연결해도 됩니다. Docker 이미지는 linux/amd64와 linux/arm64를 포함하므로 Apple Silicon Mac과 ARM64 Linux에서 별도 에뮬레이션 없이 사용할 수 있습니다. Docker가 없으면 Podman을 자동으로 사용합니다. 기본 설치는 127.0.0.1:49374에 loopback으로 바인딩해 외부 접근을 막습니다.

■ 설치와 자동 연결

Docker 또는 Podman으로 서버를 실행한 뒤 다음 두 명령으로 에이전트를 연결합니다.

ai-memory install-mcp --client claude-code --apply

ai-memory install-hooks --agent claude-code --apply

Codex, Command Code, Devin, OpenCode, Gemini CLI 등은 각각의 이름으로 같은 절차를 적용합니다. ai-memory run claude를 사용하면 처음 실행하는 harness에 필요한 hook과 MCP를 자동으로 설치하고, 프로젝트 범위와 cross-harness session continuity도 함께 설정합니다. ai-memory run codex --yolo로 같은 workstream을 다른 harness에서 재개하거나, ai-memory continue로 최신 managed checkout을 이어갈 수 있습니다. 설치 명령은 멱등적으로 동작하며, 수정하는 파일 옆에 timestamp가 붙은 백업을 남깁니다.

■ 보안과 운영 모델

초기 quick-start에는 인증이 없지만 서버가 loopback에만 바인딩하므로 단일 사용자 노트북에서는 외부에 노출되지 않습니다. LAN에 공개할 때는 bearer token, 사용자 계정, API credential, OIDC device authentication, reverse proxy 기반 TLS를 단계적으로 적용합니다. 저장 전에 capture 내용을 정제하고, 저장소별 [capture] 규칙으로 특정 경로를 제외하거나 allowlist 방식으로 제한합니다. 삭제 명령은 어떤 데이터가 삭제되는지 명확히 구분하며, 모든 변경을 audit log에 기록합니다.

운영 문서는 data directory 하나에 서버 하나만 연결하라고 안내합니다. purge, rename, backup, restore, reset, reindex, page 복구 절차도 별도 safety matrix로 정리합니다. 시스템의 측정된 write ceiling은 약 700회/초로 제시하며, 추정치가 아니라 측정값으로 공개합니다.

■ 기존 메모리 도구와의 차이

Mem0나 LangMem 같은 fact extractor가 턴 단위의 원자 사실을 추출하는 데 집중한다면, ai-memory는 사람이 읽고 수정할 수 있는 페이지를 만듭니다. Zep이나 Graphiti처럼 시간 관계와 typed relation을 다루면서도 별도 graph database 없이 bi-temporal-lite 검색과 typed edge를 제공합니다. basic-memory와는 Markdown을 원본으로 삼는 점이 비슷하지만, lifecycle 자동 수집과 FTS/entity/graph 인덱스, cross-agent handoff, multi-user 공유를 추가합니다.

Claude Code 내장 memory와 비교하면 특정 노트북의 MEMORY.md에 머무르지 않고 여러 에이전트와 머신에서 동기화하며, tool lifecycle까지 자동 기록합니다. LLM consolidation과 vector search는 선택 사항이고, capture, 검색, handoff는 API key 없이 사용할 수 있습니다. 저장소를 Git 기반 Markdown으로 유지하면서도 다양한 coding CLI 사이에 작업 상태를 전달하는 데 초점을 둔 프로젝트입니다.

원문: GitHub / 번역·요약: Trawling