한 에이전트가 다른 프로젝트의 에이전트에게 일을 부탁합니다
API로 통신하는 두 저장소가 있고, 각각 자기 에이전트와 자기 기억을 갖고 있습니다. 프런트엔드 에이전트는 프로토콜을 압니다. 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 리모트가 있는 체크아웃은 그 리모트를 기준으로 분류되므로, 같은 저장소를 두 번 클론해도 기억 하나를 공유하고, 리모트가 없는 폴더는 이름을 씁니다. 나머지는 작은 파일 하나로 바꿀 수 있습니다.
클라이언트마다 워크스페이스 하나
~/work/client-a/에.ai-memory.toml을 두면 그 아래 모든 저장소가 해당 워크스페이스에 들어갑니다. 클라이언트 B 작업 중에 클라이언트 A의 내용이 나타나는 일은 없습니다.모노레포를 프로젝트 하나로
project를 지정한 마커는 모든 하위 디렉터리를 그 프로젝트에 고정하므로, 패키지들이 기억 하나를 공유합니다. project를 빼면 패키지마다 자기 기억을 갖습니다.
Git worktree
연결된 worktree는 메인 저장소로 해석되므로, 다른 곳에 체크아웃한 브랜치도 같은 기억을 씁니다.
한 프로젝트에 에이전트 둘
현재 프로젝트 포인터는 호출자별로 격리되므로, Claude Code와 Codex를 같은 디렉터리에서 나란히 실행해도 서로 섞이지 않습니다.
노트북 한 대, 회사 두 곳
ai-memory server add로 서버를 등록하고, 마커에server = "team-b"로 이름을 적으세요. 그 트리에서 나온 훅은 거기로만 가고 다른 곳으로는 가지 않으며, 이름이 해석되지 않으면 아무것도 보내지 않습니다.신원 고정하기
identity = "acme/platform"은 그 체크아웃이 어디에 있든, 리모트가 없어도, 그 키 아래로 분류합니다.
# 이 디렉터리 아래 모든 저장소는 client-a 워크스페이스에 들어갑니다
workspace = "client-a"
모든 세션에 닿는 규칙
에이전트에게 무언가를 영구적으로 기억하라고 하면 위키의 페이지가 됩니다. 규칙은 사실과 따로 정리되며, 세션 브리핑이 첫 프롬프트 전에 에이전트 앞에 놓아 줄 수 있습니다.
한 번만 말하면 됩니다
"기억해: 결제 코드를 건드리기 전에 PCI 노트를 읽을 것." 에이전트가 영속 페이지를 작성합니다. 전역 규칙으로 요청하면 모든 프로젝트에 적용됩니다.
브리핑이 실어 옵니다
프로젝트 마커 파일에
inject_on_session_start = true를 넣으면, 고정된 페이지와 규칙과 슬롯이 모든 새 세션의 컨텍스트 앞에 붙습니다.린트가 승격을 제안합니다
규칙이 충분히 영속적으로 보이면
memory_lint가CLAUDE.md나AGENTS.md로 복사할 것을 제안합니다. ai-memory가 그 파일을 직접 수정하는 일은 없습니다.결정 기록은 여러분의 것입니다
ai-memory는 저장소에 아무것도 쓰지 않습니다. ADR 디렉터리는 그대로 두고, 위키가 낡은 사본을 들고 있지 않도록
[capture] ignore_paths에 그 경로를 추가하세요.
# 고정된 페이지, 규칙, 슬롯을 모든 세션 앞에 붙입니다
[briefing]
inject_on_session_start = true
기한이 있는 메모, 순위를 바꾸는 피드백
금요일까지만 기억하기
expires_at을 지정해 쓴 페이지는 그 날짜가 지나면 검색에서 빠집니다. 만료된 페이지를 요청하는 검색에서는 여전히 볼 수 있습니다.그 페이지는 틀렸어
memory_feedback은 페이지에 도움됨, 도움 안 됨, 오래됨, 틀림을 기록합니다. 오래됨과 틀림은 이후 랭킹을 낮추고 노화를 앞당깁니다. 피드백으로 삭제되는 것은 없습니다.세션 옮기기
임시 디렉터리로
cd한 뒤 엉뚱한 프로젝트에 캡처된 세션은ai-memory move-session으로 다시 붙일 수 있습니다. 관찰 기록과 페이지도 함께 옮겨집니다.압축에서 복구하기
Claude Code나 Codex가 컨텍스트를 압축할 때 훅이 먼저 새 세션 페이지를 쓰므로, 압축으로 사라진 내용을 다시 불러올 수 있습니다.
브라우저로 읽고, 어디로든 가져가기
읽기 전용 웹 UI
--enable-web으로 서버를 시작하면 모든 프로젝트의 페이지를 concepts, decisions, gotchas, sessions로 묶어 둘러볼 수 있고,/api/v1아래에 JSON API가 열립니다.열린 포맷
각 프로젝트는 Open Knowledge Format 번들입니다.
ai-memory export-okf가 OKF를 읽는 어떤 도구용으로든 패키징해 주고, 그 밖의 용도에는 파일이 일반 markdown이라 그대로 쓰면 됩니다.에이전트를 위한 스킬
ai-memory install-mcp는 짧은 라우팅 스니펫과 관리형 Agent Skills도 함께 설치하므로, 에이전트가 "이거 전에 얘기했었나?"에 어느 도구가 답하는지, 메시지는 어느 도구로 보내는지 알게 됩니다.
런처가 알아서 처리하는 일들
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을 추가하세요.