akitaonrails/ai-memory

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

개요

ai‑memory는 AI 기반 코딩 어시스턴트(Claude Code, OpenAI Codex / Command-Code … 등)를 위한 Rust 기반의 자체 포함 장기 메모리 서비스입니다. 개발 세션 중 코딩 에이전트에서 발생하는 모든 것(프롬프트 및 도구 호출)을 라이프사이클 후크를 통해 자동으로 기록하고, git 백업 위키의 일반 Markdown 파일로 저장합니다.

크로스 에이전트 – 지원되는 모든 에이전트가 읽고 쓸 수 있는 하나의 공유 메모리로, 프로젝트를 다시 설명하지 않고 Claude Code에서 Codex로 전환할 수 있습니다.
크로스 프로젝트 및 크로스 머신 – 작은 사용자 프로필이 모든 저장소를 따라갑니다. 메모리 서버는 모든 머신(노트북, 홈랩, Docker 등)에서 실행할 수 있으며 여러 사용자가 액세스할 수 있습니다.
기본적으로 제로 LLM – 캡처, 검색, 핸드오프가 완전히 오프라인에서 작동합니다. 선택적 LLM 기반 '드림' 통합은 옵트인입니다.
일반 텍스트 진실 소스 – 모든 메모는 Markdown 파일로 존재하며, grep으로 검색하고, Obsidian에서 편집하고, git으로 버전 관리하고, 복원할 수 있습니다.
에이징 및 중복 제거 – 메모리는 구성 가능한 일정에 따라 감쇠하며, 사용 기반 강화, 자동 압축, 중복 병합, 모순 플래그 지정이 모두 외부 API 없이 수행됩니다.
팀 준비 – 다중 사용자 인증, 개인별 귀속, 감사 로그, 프로젝트별 공유가 내장되어 있습니다.

작동 방식

캡처 – 에이전트가 라이프사이클 후크를 통해 정제된 관찰 결과를 발행합니다.
통합 – 세션 종료 시 관찰 결과가 Markdown 페이지로 변환됩니다(선택적으로 LLM 작성).
리콜 – 이후 세션은 위키를 검색(전체 텍스트, 엔티티, 링크, 선택적 벡터 임베딩)하고 간결한 핸드오프를 받을 수 있습니다.
핸드오프 – 다음 에이전트가 핸드오프를 요청하고(타입화된 프로토콜, 한 번만 요청) 작업을 계속합니다.

서비스는 단일 바이너리(ai‑memory)로 실행되며, 작은 HTTP/MCP 서버와 빠른 검색을 위한 파생 인덱스를 호스팅합니다.

주요 기능

기능	설명
다중 에이전트 통합	자사 후크 및 MCP 등록을 통해 20개 이상의 에이전트(Claude Code, Codex, Cursor, Gemini CLI, OpenCode, Grok, Devin, Kimi, Kiro 등)를 지원합니다.
크로스 프로젝트 프로필	사용자별 프로필(패키지 관리자, 테스트 레이아웃, 아키텍처 습관)을 저장하고 새 저장소에 자동 적용합니다.
크로스 머신 서버	서버를 로컬, Docker/Podman, systemd 서비스 또는 macOS 메뉴바 앱으로 실행합니다.
Git 백업 Markdown 위키	모든 메모리는 `.md` 파일로 존재하며, 인덱스는 언제든지 저장소에서 재구축할 수 있습니다.
제로 LLM 기본 경로	캡처, 검색, 핸드오프는 전체 텍스트 검색만 사용합니다. API 키가 필요 없습니다.
선택적 LLM '드림'	콜드 클러스터를 일관된 페이지로 다시 작성하는 백그라운드 패스(LLM 공급자 필요).
에이징 및 감쇠	구성 가능한 계층별 감쇠 곡선. 사용된 페이지는 감쇠가 느립니다. 자동 압축, 중복 제거, 모순 플래그 지정.
감사 및 인증	다중 사용자 인증, 개인별 귀속, 모든 변경 사항의 불변 감사 로그.
자체 포함 바이너리	단일 실행 파일. AUR, RPM, Docker, macOS 앱 또는 네이티브 zip으로 설치.
확장 가능한 검색	전체 텍스트, 엔티티 추출, 그래프 엣지. 선택적 벡터 임베딩(OpenAI/Anthropic 등 경유).

시작하기

설치 – 플랫폼의 패키지 관리자(AUR, RPM), Docker 또는 macOS .app을 사용합니다. 바이너리에는 백그라운드 서비스용 systemd/launchd 유닛이 포함되어 있습니다.

초기화 – 데이터 디렉토리를 만들고 서비스를 시작합니다:

ai-memory --data-dir ~/.local/share/ai-memory init
systemctl --user enable --now ai-memory.service

에이전트 연결 – 사용하는 에이전트용 MCP 클라이언트와 후크를 설치합니다:
```
ai-memory install-mcp   --client claude-code --apply
ai-memory install-hooks --agent  claude-code --apply
```
다른 에이전트(codex, cursor 등)에도 반복합니다.
실행 – 래퍼를 통해 코딩 어시스턴트를 시작하여 자동 캡처를 활성화합니다:
```
ai-memory run claude      # 후크를 첨부하여 Claude Code 시작
ai-memory run codex --yolo
```
에이전트를 전환하면 다음 에이전트가 진행 상황을 요약한 핸드오프를 받습니다.

사용 사례

시나리오	이점
도구 전환	작업 중간에 Claude Code에서 Codex로 전환해도 컨텍스트를 잃지 않습니다.
팀 협업	모든 팀원이 동일한 프로젝트 수준 위키를 공유합니다. 개인 메모는 비공개로 유지됩니다.
장기 프로젝트 메모리	자동 감쇠로 자주 사용되는 지식은 유지되고, 오래된 미사용 메모는 압축됩니다.
오프라인 작업	제로 LLM 모드는 API 키 없이 작동합니다. 검색과 핸드오프는 계속 가능합니다.
감사 및 규정 준수	불변 감사 로그가 모든 변경을 기록합니다. 규제 환경에 유용합니다.

제한 사항 및 고려 사항

'드림' 통합 및 벡터 순위에는 외부 LLM/임베딩 공급자와 API 키가 필요합니다.
네이티브 Windows 지원은 아직 실험적입니다. Windows 사용자는 일반적으로 Docker 또는 zip 설치로 실행합니다.
메모리 에이징 및 압축은 구성 가능합니다. 곡선을 잘못 조정하면 유용한 메모가 너무 빨리 삭제될 수 있습니다.
이 서비스는 신뢰할 수 있는 환경을 가정합니다. Markdown 파일은 일반 텍스트이며 수동으로 편집할 수 있습니다.

라이선스 및 커뮤니티

ai‑memory는 MIT 라이선스로 배포됩니다. 개발은 Rust(1.95+ 필요)로 이루어집니다. 풀 리퀘스트를 통한 기여를 환영합니다. 프로젝트는 나열된 모든 에이전트에 대한 지원 매트릭스와 CI를 유지합니다.

위의 모든 정보는 저장소의 README에서 직접 가져온 것입니다.