솔루션
프로젝트 설명, 이제 그만 반복하세요
결정 사항, 실패한 접근법, 미완료 작업을 다음 에이전트 세션에 남기세요. PC와 노트북이 같은 서버에 연결할 수 있으면 메모리를 공유할 수 있습니다. 기본 메모리 기능에는 모델 제공자의 API 키가 필요하지 않습니다.
나에게 필요할까?
작업 도중에 에이전트 바꾸기
오후 4시에 Claude Code의 속도 제한에 걸렸다면, 같은 디렉터리에서 Codex를 열고 이어서 작업하면 됩니다.
Claude Code
ai-memory
인수인계
Codex
수령은 한 번만
요약
다음 단계
미해결 질문
형식이 정해져 있습니다
인수인계(핸드오프)에는 세션 요약, 다음 단계, 미해결 질문이 담깁니다. 다음 에이전트는 세션이 시작될 때, 여러분이 아무것도 입력하기 전에 이를 받습니다.
아무것도 끝나지 않았을 때도
쿼터 한도나 크래시에서는 handoff가 전혀 기록되지 않습니다. 다음 세션은 끝나지 않은 그 작업의 이름을 받고 관찰 기록을 읽을 수 있습니다.
정확히 한 번만 수령됩니다
조건을 충족하는 첫 세션이 인수인계를 수령합니다. 두 번째 요청은 같은 인수인계를 수령할 수 없습니다. 같은 인수인계가 중복 전달되는 것은 막지만, 두 에이전트가 각자 비슷한 작업을 선택하는 것까지 막지는 않습니다.
자동으로 남고, 직접 남길 수도 있습니다
세션이 끝날 때마다 인수인계가 하나씩 기록됩니다. "다음 세션을 위해 맥락을 저장해 줘"라고 말하면 직접 작성할 수 있고, 직접 작성한 쪽이 자동 기록보다 우선합니다.
Grok Build CLI와 Zero, 이 두 에이전트는 세션 시작 시 훅이 출력하는 내용을 무시합니다. 인수인계를 받으라고 요청하면 MCP로 가져옵니다. 연동 페이지에 모든 에이전트와 각각의 지원 범위가 정리되어 있습니다.
평소에 하는 말
대부분의 날에는 아무 말도 할 필요가 없습니다. 훅이 세션을 캡처하고, 세션이 끝나면 그 내용이 위키 페이지가 됩니다. 필요한 것이 있을 때는 평소 쓰는 말로 요청하면 됩니다.
- "어디까지 했었지?"
- 대기 중인 인수인계를 읽습니다. 요약, 다음 단계, 미해결 질문이 나옵니다.
- "X에 대해 논의한 적 있어?"
- 전문 검색, 엔티티, 링크, 벡터를 하나의 랭킹으로 융합해 위키를 검색합니다.
- "그동안 있었던 일 알려 줘. 한동안 자리를 비웠어."
- 자리를 비운 기간이 길수록 더 길어지는 다이제스트를 만듭니다. LLM이 설정되어 있으면 문장으로, 없으면 구조화된 데이터로 나옵니다.
- "이건 영구적으로 기억해 줘."
- git으로 버전 관리되는 영속 페이지를 작성합니다. 고정(pin)하면 절대 감쇠하지 않습니다.
- "이건 금요일까지만 기억해 줘."
- 만료일이 있는 페이지를 작성합니다. 만료일이 지나면 망각 스윕이 삭제합니다.
- "그 페이지는 오래된 내용이야."
- 보존과 lint를 위한 피드백을 기록합니다. 검색 순위를 바꾸거나 페이지를 직접 삭제하지는 않습니다.
GitHub의 사용 가이드에 전체 문구 목록과 각 문구 뒤에서 동작하는 MCP 도구가 나와 있습니다.
런처 하나, 그리고 기존 프로젝트를 위한 진입로
ai-memory run으로 에이전트 시작하기
- 처음 실행할 때 해당 에이전트의 훅과 MCP 항목이 없으면 설치합니다. 에이전트마다 한 번만 합니다.
- 에이전트를 바꾸면 같은 워크스트림이 이어지고, 요약 인수인계에 더해 화면에 보였던 히스토리까지 함께 넘어옵니다.
ai-memory continue는 어느 디렉터리에서 실행하든 가장 최근 체크아웃을 찾아 그곳에서 작업을 이어갑니다.- 현재 12개 에이전트를 지원합니다. 에이전트를 직접 실행하는 방식도 그대로 동작하며, 훅만으로도 인수인계는 전달됩니다.
cd /path/to/project
ai-memory run claude
# Claude Code를 종료하고, 같은 워크스트림을 Codex에서 이어갑니다.
ai-memory run codex --yolo
# 어느 디렉터리에서든: 하던 곳으로 돌아가기.
ai-memory continue
기존 프로젝트에 도입하기
빈 프로젝트의 첫 세션은 로컬 에이전트 히스토리를 한 번 가져옵니다. 최신 세션 25개까지만 가져옵니다. 직접 실행할 수도 있습니다.
# 무엇을 가져올지 먼저 확인한 다음 가져옵니다
ai-memory backfill --dry-run
ai-memory backfill
첫 실행 시 자동 가져오기를 끄려면 AI_MEMORY_BACKFILL_ON_START=false를 설정합니다.
# 서버에 LLM 제공자가 필요합니다
ai-memory bootstrap --dry-run
ai-memory bootstrap
부트스트랩은 git 로그, README, docs/, 규칙 파일을 읽습니다. 프로젝트가 OpenRouter를 통해 Kimi 2.6으로 측정한 1회 실행 비용은 $0.20에 한참 못 미쳤습니다. 그럴듯하게 들리지만 틀린 페이지를 쓸 수 있으니, 먼저 드라이 런 결과를 읽어 보세요.
PC와 노트북에서 같은 기억을
서버 하나를 실행하고 각 머신을 연결하세요. 기본적으로 Git 원격 저장소로 프로젝트를 식별하며, 유효한 원격 저장소가 없는 폴더는 디렉터리 이름을 사용합니다. 마커 파일로 이를 바꿀 수 있으므로 두 번째 머신을 연결할 때 실제로 선택되는 프로젝트를 확인하세요.
PC
ai-memory 서버 한 대
노트북
오프라인
로컬 스풀
ai-memory 서버 한 대
나중에 전송
- 서버는 홈랩 서버나 항상 켜져 있는 컴퓨터에 두면 됩니다. 단일 바이너리 또는 컨테이너 하나입니다.
- 노트북이 오프라인이면 훅 이벤트는 로컬 스풀에 쌓였다가 서버에 다시 연결되면 전송됩니다. 항목마다 멱등성 키가 있어서 같은 내용이 두 번 저장되지 않습니다.
ai-memory status는 대기 중인 이벤트 수와 가장 오래된 이벤트가 얼마나 됐는지 보여줍니다.- 원격 접근에는 LAN 안에서도 Bearer 토큰과 TLS가 필요합니다. 다른 기기를 연결하기 전에 둘 다 설정하세요.
# PC와 노트북 양쪽에서
export AI_MEMORY_SERVER_URL="https://memory.example.com"
export AI_MEMORY_AUTH_TOKEN='REPLACE_WITH_YOUR_SERVER_TOKEN'
ai-memory install-mcp --client claude-code --apply
ai-memory install-hooks --agent claude-code --apply
# 그다음 평소처럼 실행
ai-memory run claude
로컬 메모리와 읽을 수 있는 파일
기본 설치는 운영 비용이 들지 않고, 모든 것을 git 저장소 안의 markdown으로 저장합니다.
LLM 호출 0회
캡처, 세션 요약, 인수인계, 검색이 모두 모델 없이 동작합니다. 제공자를 추가하기 전까지 요약은 규칙 기반입니다.
임베딩은 바이너리 안에서 실행됩니다
작은 로컬 모델(all-MiniLM-L6-v2, 약 87 MB)을 백그라운드에서 한 번 내려받습니다. 벡터 검색은 다음 재시작부터 켜집니다. 키도 GPU도 필요 없습니다.
루프백 전용
기본 서버는 127.0.0.1:49374에서 수신하며 계정도 텔레메트리도 없습니다. 네트워크의 다른 어떤 것도 접근할 수 없습니다.
wiki/ 일반 markdown
grep
Obsidian
편집
rsync
git 히스토리
파일은 어디로든 가져갈 수 있습니다
Markdown 페이지는 직접 읽고 편집할 수 있습니다. Reindex로 검색 인덱스는 재구축할 수 있지만, 세션, 인계, 계정에는 데이터베이스도 필요합니다. ai-memory backup을 사용하세요. 위키의 git push만으로는 전체 백업이 되지 않습니다.
# 컨테이너에서 위키를 복사해 Obsidian으로 엽니다
docker cp ai-memory:/data/wiki ./my-ai-memory-wiki
# 또는 히스토리를 읽습니다
git -C /data/wiki log --oneline
메모리 브라우저
옵션 하나로 프로젝트, 활동, 저장된 페이지, 검색과 받은편지함을 보여 주는 브라우저 대시보드를 엽니다. 위키 페이지는 읽기 전용이지만 권한이 있는 사용자는 대기 메시지를 보내거나 수정할 수 있습니다.
ai-memory serve --transport http --bind 127.0.0.1:49374 --enable-web
# 그다음 http://127.0.0.1:49374/web 열기
자주 묻는 질문
ai-memory를 쓰려면 API 키나 LLM이 필요한가요?
아니요. 캡처, 세션 요약, 인수인계, 검색은 LLM 호출 없이 동작합니다. 벡터 검색용 임베딩은 로컬 모델로 프로세스 안에서 실행됩니다. LLM 제공자는 선택 사항이며, 추가하면 더 풍부한 통합, 부트스트랩, 리랭킹을 쓸 수 있습니다.
프로젝트 첫날부터 ai-memory를 써야 하나요?
아니요. 언제든 추가하면 됩니다. 아직 기억이 없는 프로젝트의 첫 세션은 내 컴퓨터에 이미 있는 에이전트 세션을, 지원하는 모든 에이전트에서, 최신 25개까지 가져옵니다. LLM 없이 백그라운드에서 한 번만 실행됩니다. ai-memory bootstrap으로 git 로그, README, 문서에서 페이지를 만들 수도 있는데, 이쪽은 LLM이 필요합니다.
PC와 노트북에서 같은 기억을 쓸 수 있나요?
네. 홈랩 서버나 두 컴퓨터 중 한 대에 ai-memory 서버를 하나 띄우고 양쪽 모두 그 서버에 연결하면 됩니다. 서버 간 복제는 없습니다. 노트북이 오프라인이면 훅 이벤트는 로컬 스풀에 쌓였다가 서버에 다시 연결되면 전송됩니다.
Claude Code의 내장 메모리로 충분한가요?
컴퓨터 한 대에서 Claude Code만 쓰는 개발자 한 명이라면 충분할 수 있습니다. 두 번째 에이전트, 두 번째 컴퓨터, 두 번째 사람이 생기면 부족해집니다.
제 기억은 어디에 저장되나요?
Reindex는 Markdown에서 페이지, 링크, 전문 검색을 재구축합니다. 데이터베이스에만 있는 세션, 관찰, 인계, 사용자, 키, 감사 기록은 복구하지 못합니다.
오늘 에이전트에 기억을 달아 주세요.
무료 오픈 소스입니다. 기본 메모리 기능에는 모델 제공자 키가 필요하지 않으며, 데이터는 사용자가 소유합니다.