자체 도구를 위한 메모리
선택 사항인 TypeScript SDK는 범위가 지정된 MCP 호출로 메모리를 저장하고 검색하며 인계합니다. 조건부 쓰기로 동시 편집을 감지합니다. npm에 게시되어 있지 않으므로 저장소에서 빌드하세요.
한 에이전트가 다른 프로젝트의 에이전트에게 일을 부탁합니다
API로 통신하는 두 저장소가 있고, 각각 자기 에이전트와 자기 기억을 갖고 있습니다. 프런트엔드 에이전트는 프로토콜을 압니다. API 저장소 전체를 읽는 대신, 완결된 요청을 작성해 그 프로젝트의 인박스에 넣습니다.
프로젝트 A
send
인박스, 1회 수령
프로젝트 B
pop
API 명세
신뢰할 수 없는 입력
맥락 공유 없음
실제 모습
프런트엔드 저장소에서
> default/api의 에이전트에게 NDJSON을 스트리밍하는 /v1/export 엔드포인트를 추가해 달라고 요청해 줘. 기존 auth 미들웨어는 유지하고, ai-memory로 보내.
에이전트가 그 자체로 완결된 본문으로 memory_message_send를 호출합니다. 읽는 쪽은 이 프로젝트를 볼 수 없으므로 요청만으로 내용이 다 설명되어야 합니다.
나중에, API 저장소에서
📬 ai-memory: 이 프로젝트의 인박스에 프로젝트 간 메시지 1건이 대기 중입니다.
> ai-memory 인박스 확인해 줘.
에이전트가 memory_message_pop을 호출해 보낸 사람 정보와 함께 요청을 받고, 그것을 바탕으로 작업합니다. 두 번째 pop은 아무것도 반환하지 않습니다.
# 현재 프로젝트에서 보내기
ai-memory message send --to-workspace default --to-project api \
--subject "export endpoint" "Add a /v1/export endpoint that streams NDJSON…"
# 다른 프로젝트에서: 소비하지 않고 목록만 보거나, 가장 오래된 것을 수령
ai-memory message list
ai-memory message pop
# 수령되기 전에 마음이 바뀌었다면
ai-memory message cancel --id <message-id>
프로젝트 또는 에이전트에게
메시지는 작업공간과 프로젝트를 대상으로 하며 등록된 에이전트 한 명을 지정할 수도 있습니다. 지정된 메일은 그 에이전트만 수거할 수 있습니다. 두 프로젝트에 접근할 수 있다면 브라우저에서 대기 중인 메시지를 보내거나 수정할 수 있습니다.
저절로 컨텍스트에 들어오는 것은 없습니다
세션 시작 알림에는 건수만 담깁니다. 메시지 본문은 명시적인 pop을 통해서만 에이전트에 도달하며, 펜스로 감싸 신뢰할 수 없는 입력으로 표시되고 보낸 사람은 펜스 밖에 표시됩니다. 프로젝트 단위로, 개수만 담은 같은 알림을 프롬프트에서도 받도록 설정할 수 있습니다.
실패 시 닫힙니다
수신 프로젝트는 반드시 존재해야 하므로, 오타가 나면 아무도 읽지 않는 인박스에 들어가는 대신 거부됩니다. 인박스마다 대기 메시지는 최대 256개입니다.
취소할 수 있고, 기록됩니다
보낸 사람은 수령되기 전까지 메시지를 취소할 수 있습니다. 보낼 때 시크릿이 제거되고, 본문 크기에는 상한이 있으며, 공유 서버에서는 모든 메시지에 보낸 사람이 기록됩니다.
클라이언트, 모노레포, 개인 작업을 따로 둡니다
기억은 워크스페이스와 프로젝트별로 정리됩니다. git 리모트가 있는 체크아웃은 그 리모트를 기준으로 분류되므로, 같은 저장소를 두 번 클론해도 기억 하나를 공유하고, 리모트가 없는 폴더는 이름을 씁니다. 나머지는 작은 파일 하나로 바꿀 수 있습니다.
client-a
client-b
personal
워크스페이스
.ai-memory.toml
모노레포
규칙
금요일 만료
피드백
클라이언트마다 워크스페이스 하나
~/work/client-a/에.ai-memory.toml을 두면 하위 저장소가 해당 워크스페이스를 사용합니다. 기억을 기본적으로 저장하고 검색하는 위치를 정하는 설정입니다. 접근 제어 규칙은 아니므로 명시적인 프로젝트 간 검색과 공유 프로필은 따로 검토해야 합니다.모노레포를 프로젝트 하나로
project를 지정한 마커는 모든 하위 디렉터리를 그 프로젝트에 고정하므로, 패키지들이 기억 하나를 공유합니다. project를 빼면 패키지마다 자기 기억을 갖습니다.
Git worktree
연결된 worktree는 메인 저장소로 해석되므로, 다른 곳에 체크아웃한 브랜치도 같은 기억을 씁니다.
한 프로젝트에 에이전트 둘
호출자별 라우팅으로 사용자를 구분합니다. 한 사람의 동시 세션에는 명시적인 workspace/project 인수나 훅 세션 ID를 전달하는 클라이언트가 필요합니다. 정적 MCP 설정으로는 항상 구분할 수 있는 것은 아닙니다.
노트북 한 대, 회사 두 곳
ai-memory server add로 서버를 등록하고, 마커에server = "team-b"로 이름을 적으세요. 그 트리에서 나온 훅은 거기로만 가고 다른 곳으로는 가지 않으며, 이름이 해석되지 않으면 아무것도 보내지 않습니다.신원 고정하기
identity = "acme/platform"은 그 체크아웃이 어디에 있든, 리모트가 없어도, 그 키 아래로 분류합니다.
# 이 디렉터리 아래 모든 저장소는 client-a 워크스페이스에 들어갑니다
workspace = "client-a"
모든 세션에 닿는 규칙
에이전트에게 무언가를 영구적으로 기억하라고 하면 위키의 페이지가 됩니다. 규칙은 사실과 따로 정리되며, 세션 브리핑이 첫 프롬프트 전에 에이전트 앞에 놓아 줄 수 있습니다.
한 번만 말하면 됩니다
"기억해: 결제 코드를 건드리기 전에 PCI 노트를 읽을 것." 에이전트가 영속 페이지를 작성합니다. 전역 규칙으로 요청하면 모든 프로젝트에 적용됩니다.
브리핑이 실어 옵니다
프로젝트 마커에서
inject_on_session_start = true를 설정하면 고정 페이지, 규칙과 슬롯으로 브리핑이 시작됩니다. 길이 제한에 들어가지 못한 페이지는memory_read_page용으로 나열됩니다. Claude Code 하위 에이전트에게도 같은 제한된 브리핑을 전달하려면inject_on_subagent_start = true를 별도로 설정하세요.린트가 승격을 제안합니다
규칙이 충분히 영속적으로 보이면
memory_lint가CLAUDE.md나AGENTS.md로 복사할 것을 제안합니다. ai-memory가 그 파일을 직접 수정하는 일은 없습니다.결정 기록은 여러분의 것입니다
서버는 저장소 파일을 읽거나 쓰지 않습니다. 에이전트와 로컬 설정 명령은 읽고 쓸 수 있습니다. ADR은 저장소에서 관리하세요.
[capture] ignore_paths는 도구를 통한 수집을 줄이지만 프롬프트를 필터링하거나 완전한 제외를 보장하지는 않습니다.
# 고정된 페이지, 규칙, 슬롯을 모든 세션 앞에 붙입니다
[briefing]
inject_on_session_start = true
만료 기한이 있는 노트와 보존 피드백
금요일까지만 기억하기
expires_at이 지정된 페이지는 해당 날짜 이후 일반 검색에서 제외됩니다. 보존 정리 작업이 삭제하기 전까지는 만료된 페이지를 포함해 검색할 수 있습니다. 고정된 페이지도 삭제 대상입니다.그 페이지는 틀렸어
memory_feedback은 유용함, 유용하지 않음, 오래됨, 잘못됨을 기록합니다. 피드백은 대상 세션 페이지의 보존에 영향을 주며, 오래됨과 잘못됨은 lint 검토 대상으로도 표시합니다. 검색 순위를 바꾸거나 페이지를 직접 삭제하지는 않습니다.세션 옮기기
임시 디렉터리로
cd한 뒤 엉뚱한 프로젝트에 캡처된 세션은ai-memory move-session으로 다시 붙일 수 있습니다. 관찰 기록과 페이지도 함께 옮겨집니다.압축에서 복구하기
컨텍스트 압축 뒤에는 Claude Code와 Codex, Factory Droid가 평소의 시작 패킷 대신 세션의 첫 프롬프트와 최신 프롬프트를 담은 짧은 앵커를 받습니다. 모든 에이전트에는 자기 프롬프트를 다시 읽고 요약보다 그것을 믿으라는 규칙도 들어갑니다.
reload context는 여전히 직접 요약을 불러옵니다.
브라우저로 읽고, 어디로든 가져가기
메모리 브라우저
내장 대시보드에는 프로젝트, 수집 상태, 에이전트 활동과 응답별 사용량이 표시됩니다. 지식 탭에는 목차, 역링크, 버전별 근거와 검색이 있으며 안내서는 /web/docs에서 볼 수 있습니다.
히스토리와 재생
모든 페이지에서 버전 목록으로 이동할 수 있고 두 버전 사이의 diff를 볼 수 있습니다. 모든 세션은 캡처된 순서대로 관찰 기록의 타임라인을 엽니다. root는 훅 카운터와 실패한 항목의 해결 방법이 담긴 상태 페이지를 볼 수 있습니다.
열린 포맷
각 프로젝트는 Open Knowledge Format 번들입니다.
ai-memory export-okf가 OKF를 읽는 어떤 도구용으로든 패키징해 주고, 그 밖의 용도에는 파일이 일반 markdown이라 그대로 쓰면 됩니다.에이전트를 위한 스킬
ai-memory install-mcp는 짧은 라우팅 스니펫과 관리형 Agent Skills도 함께 설치하므로, 에이전트가 "이거 전에 얘기했었나?"에 어느 도구가 답하는지, 메시지는 어느 도구로 보내는지 알게 됩니다.
런처가 알아서 처리하는 일들
ai-memory run은 메모리 서버를 통해 에이전트를 시작합니다. 하네스를 전환할 때 이 컴퓨터의 이전 에이전트가 남긴 보이는 대화 기록을 비공개 임시 파일로 전달할 수도 있습니다. 경로와 내용은 로컬에 남고 자식 프로세스 종료 시 삭제됩니다. 사용할 로컬 기록이 없으면 이식 가능한 원장과 핸드오프를 사용합니다.
ai-memory run
샌드박스 제안
자체 업그레이드
종료 시 닫힘
웹 로그인
명령어 하나로 업그레이드
ai-memory upgrade는 일치하는 릴리스를 내려받아 체크섬을 확인하고, 바이너리를 교체한 다음 훅을 새로 고칩니다. Docker, Homebrew, AUR, RPM으로 설치했다면 각자의 경로를 그대로 씁니다.가드레일이 풀리기 전의 경고
GitHub의 ai-jailai-memory run --yolo는 무엇을 해제하려는지 알려주고, Linux와 macOS에서 ai-jail을 쓸 수 있으면 ai-jail이 무엇을 볼 수 있는지 체크리스트로 보여주며 세션을 샌드박스 안에서 다시 실행할지 제안합니다.--jail은 합리적인 기본값으로 곧바로 들어갑니다.하네스를 위한 환경 변수
--env KEY=VALUE와--env-file은 실행되는 에이전트뿐 아니라 ai-memory 자신의 세션 조회에도 전달되므로, 계정별CLAUDE_CONFIG_DIR에 래퍼 스크립트가 필요 없습니다.종료 시 세션이 닫힙니다
세션 종료 훅이 없는 에이전트(Command Code, Kiro CLI, Antigravity CLI)는 런처가 종료될 때 요약과 인수인계를 받습니다. 그 이후에도 대화가 이어졌다면
finalize-session --reopen으로 처리합니다.웹 UI에 로그인하기
내장 위키에는 비밀번호 사용자를 위한 로그인 및 비밀번호 변경 페이지가 있고, 모든 프로젝트에 걸쳐 대기 중인 자동 개선 제안을 승인하거나 거부하는 root 전용 페이지도 있습니다.
여러분 언어의 불용어
[search.fts] stopwords에 해당 언어의 기능어를 나열해 두면, 포르투갈어 위키의 전문 검색 순위가de나que때문에 왜곡되지 않습니다.
자주 묻는 질문
한 프로젝트의 에이전트가 다른 프로젝트의 기억을 읽을 수 있나요?
네. 호출자에게 접근 권한이 있으면 명시적인 프로젝트 간 쿼리로 읽을 수 있습니다. 일반 쿼리는 현재 프로젝트를 사용합니다. 메시징은 자체적으로 이해할 수 있는 요청을 다른 프로젝트의 인박스로 전달하며, 받는 쪽에 보낸 쪽의 파일 접근 권한을 주지는 않습니다.
받은 메시지가 지시로 취급되나요?
아니요. pop으로 꺼낸 메시지는 신뢰할 수 없는 프로젝트 간 입력으로 펜스에 감싸이고, 그렇다는 안내문이 붙습니다. 에이전트는 이를 여러분과 함께 작업 요청으로 검토하며, 보낸 사람이 펜스 밖에 표시되므로 신뢰 여부를 먼저 판단할 수 있습니다.
두 세션이 같은 인박스를 확인하면 어떻게 되나요?
첫 번째 pop이 메시지를 수령하고 두 번째는 아무것도 받지 못합니다. 메시지는 정확히 한 번만 수령되며, 인수인계와 같은 규칙입니다.
워크스페이스를 꼭 설정해야 하나요?
아니요. 마커 파일이 없으면 모든 것이 default라는 워크스페이스에 들어가고, git 리모트가 프로젝트가 되며, 리모트가 없으면 디렉터리 이름이 프로젝트가 됩니다. 클라이언트를 분리하거나, 모노레포를 프로젝트 하나로 묶거나, 업무와 개인 기억을 따로 두거나, 서버를 하나 더 쓰고 싶을 때만 .ai-memory.toml을 추가하세요.
자체 도구와 팀 위키 연결
저장소에서 공유 페이지 검토
선택 사항인 ai-memory-wikisync는 선택한 공유 페이지 유형을 저장소의 Markdown과 동기화합니다. 편집 충돌을 알리고 조건부 쓰기를 사용하며, 삭제는 명시적으로 활성화해야 합니다. 서버나 비공개 세션 이력은 복제하지 않습니다.
이미 가지고 있는 문서를 기억에 넣기
선택 사항인 ai-memory-importer는 지정한 로컬 파일 하나를 읽습니다. markdown, 텍스트 레이어가 있는 PDF, DOCX, PPTX, XLSX, CSV, VTT, SRT를 지원합니다. 출처를 기록한 페이지 하나를 쓰고, 기본은 dry run이며, 파일의 digest를 남기고, 자기 것이 아닌 페이지는 절대 덮어쓰지 않습니다. OCR도 이미지도 오디오도 없습니다. 읽기 전용 스냅숏에서 claude-mem 데이터베이스도 가져옵니다. 프로젝트 매핑은 명시적으로 지정하고, 먼저 드라이런으로 실행합니다.
오늘 에이전트에 기억을 달아 주세요.
MIT 라이선스의 무료 오픈 소스입니다. 기본 기억 기능에는 모델 API 키가 필요 없지만, 코딩 에이전트는 별도 계정이 필요할 수 있습니다.