AI 코딩 에이전트를 위한 장기 메모리 시스템 ai-memory

AI 코딩 에이전트를 위한 장기 메모리(Long-term memory).
Claude Code 작업을 하다가 중단하고, 같은 디렉토리에서 OpenAI Codex를 시작해도 아키텍처, 실패한 접근 방식 또는 해결되지 않은 질문들을 다시 설명할 필요 없이 계속할 수 있습니다.

웹사이트: aimemory.sh

Release

Rust

License

ai-memory가 필요한 이유 (Why ai-memory)

사용하는 코딩 에이전트들은 이미 메모리 기능을 가지고 있을 것입니다. Claude Code는 자체 노트를 작성하고, Cursor는 일부 내용을 기억하며, 모든 플랫폼들이 이 기능을 추가하고 있습니다. 하지만 이들 모두 공통적인 한계점을 안고 있습니다: 노트가 하나의 장치에 존재하고, 하나의 에이전트에 속하며, 도구를 전환하거나 동료에게 작업을 넘길 때 시야에서 사라진다는 것입니다.

ai-memory는 이러한 한계를 제거합니다.

• 에이전트 간에 추적됩니다. 20개가 넘는 다양한 하네스(Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro 등)가 하나의 공유 메모리를 공급합니다. Claude Code 작업을 중단하고 같은 디렉토리에서 Codex를 실행하면, 다음 에이전트가 사용자가 어디까지 했는지, 무엇이 실패했는지, 그리고 아직 해결되지 않은 것이 무엇인지를 담은 인계(handoff)를 이어받습니다. 이 인계는 타입화된 프로토콜입니다: 각각의 인계에는 소유자가 있으며 정확히 한 번만 주장됩니다.

• 요약본이 아닌 세션 전체를 유지할 수 있습니다. ai-memory run으로 에이전트를 시작합니다: Claude Code를 중단하고, ai-memory run codex를 실행하면 Codex는 공유 작업 흐름과 더불어, 경계가 있는(bounded) 시작 패킷이 생략한 정확한 세부 정보를 위해 Claude의 보이는 네이티브 히스토리의 사적이고 임시적인 로컬 투영본을 얻게 됩니다. 원격 서버는 하네스와 세션 ID만 수신하며, 로컬 트랜스크립트 경로나 본문은 절대 받지 않습니다. 직접적인 하네스 실행은 이전과 완전히 동일하게 작동합니다.

• 프로젝트 전반에 걸쳐 당신을 따라다닙니다. 사용자가 평소 작업하는 방식(패키지 매니저, 테스트 레이아웃, 아키텍처 습관 등)이 세션 시작 시 모든 새 저장소에 도달하여, 스스로를 반복해서 설명할 필요가 없습니다. 이 기능은 각 저장소의 규칙 파일 아래 기본값으로 위치합니다. 단일 사용자에게는 기본적으로 활성화되어 있으며, 공유 서버에서는 선택적이고 개인별로 적용됩니다. docs/cross-project-profile.md를 참조하세요.

• 기기 전반에 걸쳐 당신을 따라다닙니다. 메모리는 사용자가 운영하는 서버(같은 노트북, 홈랩 박스 또는 다른 곳 어디든 상관없음)에 존재하므로, 데스크톱에서 작업하던 프로젝트를 같은 지식과 동일한 미해결 질문을 가지고 노트북에서도 재개할 수 있습니다.

• 팀 단위로 작동합니다. 모두가 하나의 서버를 가리키게 하면, 한 사람의 세션이 학습한 내용을 모든 사람의 에이전트가 검색할 수 있습니다. 지식은 프로젝트별로 공유되며, 개인 간 인계는 여전히 개인적으로 유지됩니다. 다중 사용자 인증(Multi-user auth), 개인별 기여도 표시(per-person attribution), 감사 로그(audit log) 기능이 기본으로 내장되어 있으며 유료 등급에 포함되지 않습니다.

• 당신의 메모리는 일반 마크다운입니다. 진실의 원천은 일반 .md 파일로 구성된 git 기반 위키이며, 이를 grep하거나 Obsidian에서 열거나 수동으로 편집하고 rsync할 수 있습니다. 데이터베이스는 파일을 통해 항상 재구축될 수 있는 파생 인덱스입니다. 유지해야 할 벡터 스토어(vector store)가 없고 바이너리 블롭에 콘텐츠가 잠기지도 않습니다.

• 작업 자체를 조용히 포착합니다. 라이프사이클 훅(Lifecycle hooks)이 무슨 일이 일어났는지(프롬프트, 도구 호출, 세션 경계 등) 기록하고, 무언가를 저장하기 전에 타입 지정된 개인 정보 보호 경계에서 이를 정리하며, 서버가 이를 읽기 쉬운 페이지로 통합합니다. 기억하도록 요청할 필요가 없습니다. 기본 경로는 LLM 호출을 전혀 사용하지 않습니다: 포착, 검색 및 인계 작업을 모두 API 키 없이 처리합니다.

• LLM 없이 메모리를 관리합니다. 각 계층(tier)별로 조정 가능한 일정에 따라 메모리가 감쇠하며, 사용한 메모리는 더 느리게 감쇠합니다. 페이지를 열거나, 검색하거나, 링크를 통해 접근하는 것이 '사용'으로 간주됩니다. 에피소드 노트가 식으면 삭제되는 대신 영구적인 사실(파일 경로, 오류 코드, 결정 사항)로 압축될 수 있습니다. 거의 중복된 내용은 하나로 통합되고, 잠재적 모순점은 플래그 지정되며, 이 모든 과정이 API 호출 0회로 이루어집니다. 아무것도 강제로 삭제되지 않습니다. 원본은 git에 남아있고 버전 체인(restore-page)을 통해 복원할 수 있습니다. 접근 가중치 기반의 보존(Access-weighted retention) 기능은 항상 활성화되어 있어 메모리를 더 오래 유지할 수 있게 합니다. 콘텐츠를 재작성하거나 삭제하는 부분(압축, 중복 제거, 계층별 곡선)은 기본적으로 꺼져 있으며 사용자가 켜야 작동합니다.

• 원한다면 '꿈'을 꾸게 할 수도 있습니다. LLM이 구성된 경우, 선택적 백그라운드 패스가 사용자가 자리를 비운 동안 차가운 노트 클러스터 전체를 단일하고 일관성 있는 페이지로 재작성하며, 작업으로 돌아오는 즉시 중단됩니다. 소스를 절대 삭제하지 않습니다(병합 전 버전은 계속 접근 가능합니다). 기본적으로 꺼져 있으며, 기본 동작이 되기 위해서는 리콜 평가(recall eval)를 통과해야 합니다. 더 많은 것을 요청하지 않는 한, 위의 LLM 없는 경로가 실행됩니다.

• 자신에 대해 정직합니다. 하나의 독립적인 바이너리로 배포됩니다. Purge 명령어는 '삭제'가 정확히 무엇을 의미하는지 알려줍니다. 쓰기 상한선(~700/s)은 추측이 아닌 측정됩니다. 감사 로그(audit log)는 모든 변경 사항을 기록합니다.

작동 방식

capture ──▶ consolidate ──▶ recall ──▶ handoff
hooks        session-end      search     next agent,
observe      summaries as     + brief    any harness
...

에이전트는 작업하는 동안 라이프사이클 훅(lifecycle hooks)을 통해 정제된 관찰 기록(observations)을 방출합니다. 세션이 종료되면, 이 관찰 기록들은 프로젝트의 위키(wiki)에 일관성 있는 마크다운 페이지로 저장됩니다 (선택적으로 LLM이 작성할 수 있으며, 이것이 없어도 유용합니다). 다음 세션에서는 어떤 기기에서든 어떤 에이전트가든 제한된 요약 정보(bounded brief)를 받게 되며 모든 것을 검색할 수 있습니다: 전체 텍스트, 개체명(entities), 링크, 그리고 (선택적으로) 벡터를 하나의 순위로 통합하여 검색합니다. 에이전트 간 핸드오프는 바통을 명시적으로 전달합니다.

다중 사용자 및 다중 세션 사용을 안전하게 유지하는 불변 조건(invariants)을 포함한 전체 설계는 docs/ARCHITECTURE.md에 있습니다.

선택적인 서버 렌더링 관리 콘솔은 사용자 관리, 세션 검사 및 삭제, 개인 MCP API 키를 제공합니다. --features management-ui로 빌드하고 serve --transport http --enable-management-ui를 실행하면 됩니다. 컴파일 시간(compile-time)과 런타임(runtime) 모두 옵트인(opt-in)이 필요합니다.

지원 매트릭스 (Support matrix)

아래의 모든 행은 CI에서 확인한 퍼스트 파티 통합(first-party integration)입니다 (MCP 등록, 라이프사이클 훅 또는 둘 다). 에이전트별 참고 사항 및 주의사항이 포함된 전체 매트릭스는 docs/support-matrix.md에 있습니다.

다른 도구에서 오는 경우?

대부분의 에이전트 메모리 도구는 한 가지 것에 최적화되어 있습니다: 턴(turn)별 원자적인 사실 추출, 시간적 지식 그래프(temporal knowledge graph), 에이전트가 편집 가능한 메모리 OS, 또는 호스팅되는 컨텍스트 API입니다. ai-memory는 진실의 근원(source of truth)으로서 git 기반 마크다운 위키를 중심으로 구축되었으며, 검색을 위한 파생 인덱스(derived index)를 가집니다. 이는 라이프사이클 훅에서 자동으로 포착되며, 에이전트, 기기, 사람 간에 공유되고, 기본적으로 LLM 호출 없이 작동합니다. 이 표는 각 도구로부터 무엇이 가져와지고 여러분이 무엇을 얻게 되는지 보여줍니다:

다음의 어깨 위에 구축됨: Karpathy LLM Wiki (컴파일-검색 아님), agentmemory (코딩 에이전트를 위한 후크 포착), basic-memory (디스크 기반 markdown 진실), cognee (파이프라인 구성 및 트리플렛 임베딩), Hermes Agent (자가 개선 루프), 그리고 A-MEM (Zettelkasten 스타일의 원자적 노트).

각 접근 방식이 어느 부분에서 강점을 가지는지, ai-memory가 어떻게 다른지, 그리고 발표된 벤치마크를 다루는 전체 비교 내용은 How ai-memory compares에 있습니다.

빠른 시작(Quick start)

Linux 및 macOS (두 명령어, root 권한 불필요)

curl -fsSL https://github.com/akitaonrails/ai-memory/releases/latest/download/install.sh | sh
ai-memory setup

install.sh는 사용자의 OS와 CPU에 맞는 릴리스를 다운로드하고, 해당 릴리스의 공개된 SHA-256 체크섬과 비교합니다 (일치하지 않으면 설치를 거부함). 그리고 ~/.local/bin/ai-memory를 링크합니다. 이후 ai-memory setup은 데이터 디렉토리를 생성하고 소유자 전용 파일에 베어러 토큰을 저장하며, 사용자별 서비스(systemd --user 또는 launchd LaunchAgent)를 시작하고, 발견된 모든 에이전트 또는 --agent로 지정한 에이전트에 대해 MCP, 훅(hooks), 그리고 에이전트 스킬(Agent Skills)을 연결합니다. 이 과정에서 어떤 에이전트를 어디서 찾았는지 계획(plan)을 보여주고 먼저 질문합니다: y를 입력하거나 연결할 에이전트의 번호를 입력하라고 합니다. --plan은 계획만 출력하고 아무것도 변경하지 않으며, --web은 브라우저 페이지로 계획을 보여주고 사용자가 체크한 에이전트를 적용하며, --yes는 질문 단계를 건너뛰고, 다시 실행해도 아무것도 변경하지 않습니다. 그 후에 에이전트를 재시작하고 그중 하나에게

install.ps1은 릴리스 zip 파일을 게시된 SHA-256 체크섬과 비교하고, 이를 %LOCALAPPDATA%\Programs\ai-memory 아래에 압축 해제한 후 해당 디렉토리를 사용자 PATH에 추가합니다. 이후 ai-memory setup은 Linux 및 macOS에서 수행하는 작업을 서비스 로그온 항목으로 대체하여 실행합니다: 서버는 사용자가 로그인할 때 콘솔 창 없이 시작하며, 실패하면 재시작됩니다. 자세한 내용과 다른 Windows 설정(WSL2, Docker Desktop, 실제 Windows 서비스)은 docs/windows.md에 있습니다.

Arch Linux (AUR)

네이티브 Arch 설치의 경우 AUR 패키지를 사용하십시오. 이 패키지는 /usr/bin/ai-memory, 패키징된 훅 소스, 그리고 시스템 레벨 및 사용자 레벨 systemd 유닛을 설치합니다.

yay -S ai-memory-bin    # 미리 빌드된 Linux x86_64/aarch64 바이너리
yay -S ai-memory        # 소스에서 빌드
ai-memory setup         # 데이터 디렉토리, 사용자 서비스, 에이전트, 자체 검사

Fedora (RPM)

최신 릴리스에서 x86_64 또는 aarch64 RPM을 다운로드한 다음 설치합니다:

sudo dnf install ./ai-memory-*.rpm

단일 사용자 워크스테이션의 경우, 위 두 명령어 경로와 마찬가지로 ai-memory setup이 나머지 작업을 수행합니다: 데이터 디렉토리 및 토큰, 사용자 서비스, 발견된 에이전트, 그리고 자체 검사.

ai-memory setup

시스템 서비스 설치는 패키징된 유닛을 통해 /var/lib/ai-memory와 /etc/ai-memory/를 사용합니다. 전체 사용자 서비스, 시스템 서비스, 인증(auth), 및 제공자 설정은 docs/install.md#arch-linux-native-packages-aur에 있습니다.

macOS (메뉴 막대 앱)