ai-memory — AI 코딩 에이전트에 장기 기억을 심는 오픈소스 도구

ai-memory란 무엇이고, 왜 필요한가?

ai-memory는 AI 코딩 에이전트의 세션 간 기억을 유지하는 MCP 서버다. 에이전트가 작업 중 관찰한 내용(프롬프트, 도구 호출, 결정)을 자동으로 캡처하고, 마크다운 위키 페이지로 정리한 뒤, 다음 세션이 시작될 때 컨텍스트로 주입한다. 벡터 DB 없이 SQLite FTS5로 동작하며, 모든 기억은 grep 가능한 마크다운 파일로 저장된다.

Claude Code의 내장 메모리(CLAUDE.md)도 비슷한 역할을 하지만, 단일 에이전트·단일 프로젝트에 한정된다. ai-memory는 한 단계 더 나아간다. Claude Code에서 작업하다 Cursor로 전환해도, Codex로 넘어가도 기억이 이어진다. 프로젝트의 철학을 만든이의 말로 정리하면 이렇다:

"에이전트 메모리는 텍스트다. 텍스트는 디스크에 산다. SQLite로 인덱싱하고, 가치 있을 때만 LLM으로 정리한다. 아무도 찾지 않는 기억은 잊어버린다."

어떻게 작동하는가 — 설치부터 실사용까지

Docker 컨테이너를 띄우고, CLI 한 줄로 에이전트에 연결하면 끝이다. 관찰 기록 → 위키 컴파일 → 핸드오프 주입의 세 단계로 동작하며, 설치 명령은 멱등성을 보장해 반복 실행해도 안전하다.

설치 (3단계)

# 1. Docker 서버 실행 (로컬 전용, 127.0.0.1 바인딩)
docker run -d --name ai-memory \
  -p 127.0.0.1:49374:49374 \
  -v $HOME/.ai-memory:/data \
  akitaonrails/ai-memory:latest

# 2. MCP 서버 등록 (Claude Code 예시)
ai-memory install-mcp --client claude-code --apply

# 3. 후킹 설정 (자동 캡처 활성화)
ai-memory install-hooks --agent claude-code --apply

이후 Claude Code를 평소대로 열면 된다. 모든 관찰이 자동으로 ai-memory에 흘러간다.

핵심 MCP 도구 8개

• recall — 위키에서 관련 기억 검색
• save — 현재 관찰을 위키에 저장
• sessions — 이전 세션 목록 조회
• smart_search — FTS5 + 그래프 기반 하이브리드 검색
• handoff — 세션 핸드오프 컨텍스트 생성 (열린 질문, 다음 단계, 수정 파일 목록)
• consolidate — 관찰들을 일관된 위키 페이지로 압축
• forget — 더 이상 유효하지 않은 기억 삭제
• governance_delete — 감사 추적 포함 영구 삭제

동작 흐름

1단계 — 관찰 캡처: 에이전트가 작업하는 동안 프롬프트, 도구 호출, 결정 사항이 자동으로 기록된다. 별도의 "메모 작성" 동작이 필요 없다.

2단계 — 위키 컴파일: 축적된 관찰을 LLM이 일관된 마크다운 페이지로 정리한다. 배경 스케줄러가 자동으로 실행하며, 오래되어 아무도 조회하지 않는 기억은 자연스럽게 감쇠(decay)된다.

3단계 — 세션 핸드오프: 새 세션이 시작될 때, 이전 세션의 맥락(열린 질문, 다음 단계, 수정한 파일 목록)이 자동 주입된다. Claude Code에서 Cursor로 전환해도 컨텍스트가 이어진다.

Claude Code 내장 메모리와 뭐가 다른가?

Claude Code의 CLAUDE.md는 키-밸류 스타일의 단순 메모리이고 Claude Code 전용이다. ai-memory는 서버 기반 위키로, 10개 이상의 에이전트 간 메모리 공유와 세션 핸드오프를 지원한다. 복잡한 만큼 설정 비용도 높다 — 단일 에이전트로 충분하면 CLAUDE.md가 더 실용적이다.

실사용 리뷰 — 장점과 한계는 무엇인가?

GitHub 이슈 406건과 178개 포크가 보여주는 것은 실사용자가 있다는 것과, 동시에 거친 부분도 있다는 것이다. 개발자 Fabio Akita 본인이 블로그에서 agentmemory의 데이터 유실 버그를 경험한 후 직접 만들었다고 밝힌 만큼, 안정성에 대한 집착이 프로젝트 전반에 깔려 있다.

강점

• 벡터 DB 불필요 — SQLite FTS5면 충분하다는 철학. 인프라 복잡도가 극적으로 낮다
• 마크다운 위키 — 기억이 grep 가능하고, Obsidian에서 열리고, rsync로 백업된다. 블랙박스가 아니라 텍스트
• 에이전트 간 핸드오프 — Claude Code에서 시작한 작업을 Cursor로, Codex로 이어갈 수 있다. 유일한 차별점
• 자동 캡처 — 에이전트 사용 중 별도 동작 없이 관찰이 기록된다
• Rust + Docker — 빠르고 리소스 소모 적으며, 환경 일관성 보장
• 멱등 설치 — 재실행해도 기존 설정을 덮어쓰지 않고, 수정 전 .bak 백업 생성
• 자동 메모리 감쇠 — 조회되지 않는 기억은 자연스럽게 제거. 메모리 부풀림 방지

한계

• Docker 의존 — 가볍게 쓰려는 사용자에게 진입 장벽. Docker Desktop 없으면 시작 불가
• 아직 베타 — 프로젝트가 공식적으로 베타 상태를 명시. 3개월간 406개 이슈는 실사용 거침을 시사
• LLM 비용 — 위키 컴파일(consolidation)에 LLM API가 필요. 배경 자동 정리에 토큰이 소모된다
• 독립 리뷰 부족 — 2026년 8월 기준, 개발자 본인의 블로그 포스트 4건 외 독립 리뷰·Reddit 스레드·HN 토론이 거의 없다
• 메모리 신뢰도 문제 — AI 메모리 분야 공통 과제. 코드가 리팩토링되면 기억 속 파일명·함수명이 더 이상 유효하지 않을 수 있다. 기억이 "자신 있게 틀리는" 상황이 발생할 수 있다

ai-memory를 써야 하는 사람과 쓰지 않아도 되는 사람은?

여러 에이전트를 번갈아 쓰면서 장기 프로젝트를 진행하는 개발자에게 가장 유용하다. 단일 에이전트로 충분하거나 Docker 설치가 부담스러운 환경이라면 Claude Code 내장 메모리로 시작하는 것이 현실적이다.

추천 대상:

• Claude Code + Cursor + Codex 등 여러 에이전트를 프로젝트별로 전환하는 개발자
• 수주~수개월 단위 장기 프로젝트에서 세션 연속성이 중요한 팀
• 메모리를 마크다운으로 직접 읽고 관리하고 싶은 파워 유저
• 클라우드에 데이터를 보내지 않고 로컬에서 모든 것을 처리하고 싶은 보안 민감 환경

아직 불필요한 대상:

• Claude Code 하나로 충분한 개인 프로젝트 — CLAUDE.md 자동 메모리면 된다
• Docker 설치가 어렵거나 리소스 제약이 있는 환경
• 배경 LLM 호출에 추가 토큰 비용을 쓰고 싶지 않은 경우
• 안정된 프로덕션 도구를 원하는 경우 — 아직 베타다

빠른 시작 — 5분 안에 Claude Code에 연결하기

Docker가 설치되어 있다면 3개 명령으로 끝난다. 서버 실행, MCP 등록, 후킹 설정. 이후 Claude Code를 평소대로 쓰면 메모리가 자동 축적된다.

# Docker 서버 실행
docker run -d --name ai-memory \
  -p 127.0.0.1:49374:49374 \
  -v $HOME/.ai-memory:/data \
  akitaonrails/ai-memory:latest

# Claude Code에 MCP 서버 등록
ai-memory install-mcp --client claude-code --apply

# 자동 캡처 후킹
ai-memory install-hooks --agent claude-code --apply

# 기존 프로젝트 부트스트랩 (선택)
ai-memory bootstrap

bootstrap 명령은 git log, README, docs/, 모듈 헤더, 프로젝트 규칙을 수집해 초기 위키 페이지를 자동 생성한다. 기존 프로젝트에 처음 적용할 때 유용하다.