MCP 설정
AideMemo는 에이전트가 도구로 메모리를 검색하고 쓸 수 있도록 같은 메모리
저장소를 MCP로 제공합니다. 전체 도구 목록은 기능 목록,
턴마다 알맞은 도구를 선택하는 방법은
에이전트 워크플로를 참고하세요.
Stdio MCP
로컬 에이전트에는 stdio MCP를 사용합니다.
aidememo mcp
Codex 설정 예시:
[mcp_servers.aidememo]
command = "aidememo"
args = ["--backend", "libsqlite", "--store", "/absolute/project/_meta/wiki.sqlite", "mcp"]
[mcp_servers.aidememo.env]
AIDEMEMO_SOURCE_ID = "project:my-app"
AIDEMEMO_ACTOR_ID = "codex:account-a"
Claude Code 독립 등록:
aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
--target claude \
--source-id project:my-app \
--actor-id claude:local
이 명령은 Claude Code의 현재 CLI 인자 순서를 사용하고 확인된 store를
고정합니다. 기능별 스킬과 읽기 전용 훅을 함께 제공하는 Claude 플러그인을
대신 사용할 수도 있습니다. Hermes, Cursor, OpenClaw, OpenCode에도 설치 대상이
있습니다. pi는 MCP를 받지 않으므로 의도적으로 스킬 전용입니다. 전체 표는
코딩 에이전트 설치를 참고하세요.
인증된 원격 handoff profile
Handoff 상태를 하나의 원격 SSOT project에 둘 때 격리된 Codex 계정을 각각 설치합니다.
aidememo auth login https://memory.example.com \
--profile codex-p1 --project-id aidememo --token-file /secure/p1.token
aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
--target codex --codex-home /profiles/codex-p1 \
--source-id project:aidememo --remote-profile codex-p1
aidememo auth login https://memory.example.com \
--profile codex-p2 --project-id aidememo --token-file /secure/p2.token
aidememo --store /absolute/project/_meta/wiki.sqlite mcp-install \
--target codex --codex-home /profiles/codex-p2 \
--source-id project:aidememo --remote-profile codex-p2
Installer는 서버에 인증하고 저장된 bearer binding에서 AIDEMEMO_ACTOR_ID를
파생한 뒤 해당 계정 config에 mcp --remote-profile NAME을 고정합니다. 호출자가
actor를 덮어쓰는 설정을 거부하고 하나의 원격 credential profile을 여러 Codex
home에 복사하지도 않습니다. 계정마다 한 번씩 실행한 뒤 agent를 재시작해 MCP
설정을 다시 읽게 합니다.
이 connected hybrid mode에서 aidememo_handoff는 embedded store에서 preview하고
dispatch=true일 때 원격 SSOT로 보냅니다. aidememo_handoff_inbox의 list,
outbox, show/status, accept, return은 인증 서버로 라우팅됩니다. 다른 memory tool은
고정된 local store를 계속 사용하고, 수신자 result fact는 return 시 canonical
evidence로 upload됩니다. 설치, MCP 시작, 원격 handoff 호출 시 서버가 연결돼 있어야
합니다. Offline canonical exact-read cache가 필요하면 MCP process 밖에서
aidememo replica pull --remote-profile NAME을 실행합니다. 생성되는
cache는 원자적 snapshot으로 bootstrap한 뒤 revision-pinned change를 적용합니다.
<store>.replica.sqlite는 고정된 embedded search store와 별도이며 MCP 시작 시
암묵적으로 갱신되지 않습니다. HTTP mcp-serve, retrieval-index replica,
offline write는 아직 이 profile 경로에 포함되지 않습니다.
HTTP MCP 서버
여러 에이전트가 하나의 웜 프로세스를 공유해야 할 때 HTTP를 사용합니다.
aidememo --store ~/.aidememo/team.sqlite mcp-serve --port 3000
MCP 클라이언트가 다음 주소를 사용하도록 설정합니다.
http://127.0.0.1:3000/mcp
HTTP 모드는 웜 모델 재사용과 공유 쓰기에 유용합니다. 한 번에 하나의 writer 프로세스만 데이터베이스 잠금을 가질 수 있는 redb 저장소에는 특히 권장합니다.
네트워크에 노출한 공유 저장소에서는 모든 클라이언트에 같은 범위 없는 토큰을 주기보다 bearer token마다 하나의 source와 writer identity를 고정하세요.
{
"tokens": [
{
"token": "replace-with-a-random-secret",
"source_id": "project:my-app",
"actor_id": "codex:account-a"
}
]
}
chmod 600 /etc/aidememo/token-bindings.json
aidememo --store ~/.aidememo/team.sqlite mcp-serve \
--bind 0.0.0.0 \
--auth-bindings-file /etc/aidememo/token-bindings.json
환경 변수로는 AIDEMEMO_MCP_AUTH_BINDINGS_FILE을 사용합니다. 파일은 위와 같은
{"tokens": [...]} wrapper object 또는 최상위 JSON array 형식을 사용할 수
있습니다. 각 token, source_id, actor_id는 앞뒤 공백을 제거한 뒤 비어 있지
않아야 하며 token 값은 중복될 수 없습니다. --auth-bindings-file은
--auth-token 또는 --auth-token-file과 함께 사용할 수 없고, 명시적인 CLI auth
option이 auth 환경 변수보다 우선합니다.
Bound token으로
호출하면 서버가 설정된 source_id와 actor_id를 모든 MCP tool call에 주입하고,
aidememo_fact_add_many item 내부를 포함해 호출자가 다른 값을 전달하면
거부합니다. Bound token은 범위 없는 /sync/since와 /admin/status endpoint를
사용할 수 없으며 /health에서는 health와 semantic prewarm 상태만 받습니다.
신뢰할 수 있는 범위 없는 관리자는 기존 --auth-token-file mode를 사용하세요.
Single-token 관리자는 source에 고정되지 않으므로 tool 인자에서 source_id와
actor_id를 선택하고 전역 status 및 sync endpoint를 사용할 수 있습니다.
mcp-serve 자체는 평문 HTTP를 사용합니다. Bearer binding은 identity와 scope를
강제하지만 전송 구간을 암호화하지 않습니다. Loopback이 아닌 배포에서는 반드시
TLS를 종료하는 reverse proxy 또는 암호화된 private tunnel 뒤에 서버를 두고,
backend port에 대한 직접 접근을 제한하세요.
핵심 도구
대부분의 에이전트 워크플로에는 다음 도구만 필요합니다.
| 도구 | 사용 시점 |
|---|---|
aidememo_workflow_start | 이슈, PR, 티켓, 간단한 프롬프트에서 작업을 시작할 때 |
aidememo_context | 에이전트가 턴 시작 시 프로젝트 컨텍스트를 필요로 할 때 |
aidememo_query | 특정 주제를 더 깊이 살펴볼 때 |
aidememo_search | 정확한 대상을 빠르게 검색할 때 |
aidememo_aggregate | 정확한 개수, 합계, 날짜 집합, 타임라인이 필요할 때 |
aidememo_session_canvas | 긴 추적 워크플로를 다시 시작할 때 |
aidememo_handoff | 다른 에이전트, 프로필, 계정으로 세션을 미리 보거나 dispatch할 때 |
aidememo_handoff_inbox | 수신자가 list/accept/return하고 발신자가 outbox/status로 결과를 확인할 때 |
aidememo_profile_export | 간결한 읽기 전용 프로젝트 프로필이 필요할 때 |
aidememo_fact_add | 새 팩트 하나를 배웠을 때 |
aidememo_fact_add_many | 여러 팩트를 배워 배치로 기록해야 할 때 |
권장 에이전트 패턴
티켓을 시작할 때:
{
"title": "Fix Redis timeout in worker",
"body": "Worker jobs intermittently time out against Redis.",
"source": "github:org/app#123",
"source_id": "team-a",
"bm25_only": true
}
다음 도구를 호출합니다.
aidememo_workflow_start
이후 팩트를 추가할 때 반환된 session_id를 사용합니다.
{
"content": "Lesson: the timeout was DNS resolution, not pool size.",
"fact_type": "lesson",
"entities": ["Redis", "Worker"],
"session_id": "session-..."
}
다음 도구를 호출합니다.
aidememo_fact_add
Handoff는 현재 아직 릴리스되지 않은
main기능입니다. 공개 v0.1.0 MCP 서버와 Hermes 패키지에는 이 도구가 없습니다.
사용자 중심 왕복 흐름은 추적 작업 핸드오프에서 시작하세요.
아래 호출은 저수준 MCP envelope를 설명합니다.
다른 계정이 이어받기 전에 aidememo_handoff를 호출합니다.
{
"session_id": "session-...",
"from_actor": "codex-one",
"to_actor": "codex-two",
"from": "codex/coding",
"to": "codex/reviewer",
"focus": "패치를 검토하고 집중 회귀 테스트 실행",
"done_when": "집중 테스트 통과와 리뷰 결과 기록",
"source_id": "team-a",
"dispatch": true
}
dispatch가 없으면 읽기 전용 preview입니다. dispatch한 수신자는
aidememo_handoff_inbox의 list, accept, return, outbox, status
action을 사용합니다. 설치형 worker는 고유 claim_id도 전달하며 이미 accepted된
활성 assignment는 동일 claim만 재시도할 수 있습니다. fact가 연결된 실패
assignment는 새 claim으로 재시도하며 attempt_count를 증가시킵니다. return은
결과 fact id와 outcome을 연결합니다. 실패는
accepted 상태로 남으며 AideMemo가 자동 재시도하지 않습니다.
결과 fact가 전달된 세션과 정확한 source 범위에 속하지 않거나 수신 actor가
작성하지 않았다면 return은 fail-closed로 거절됩니다.
session_id는 연속성, source_id는 검색 범위, actor_id는 사용자 지정
계정/설치 주소, agent/profile은 역할입니다. actor는 인증이 아닙니다. 할당
레코드에는 topic, offset, consumer group, retry state, 복제 content payload가 없습니다.
소스 범위 지정
공유 저장소에 여러 팀, 프로젝트, 사용자, 에이전트가 포함되면 source_id를
사용합니다.
aidememo --backend libsqlite --store ~/.aidememo/team.sqlite \
mcp-install --target codex --source-id team-a --actor-id codex-one
클라이언트가 명시적인 source_id를 전달하지 않으면 MCP 도구는 이 소스
네임스페이스를 기본값으로 사용합니다. Inbox는 설치된 AIDEMEMO_ACTOR_ID를
기본값으로 사용합니다. 설치 명령은 선택한 저장소 백엔드와 확인된
저장소 경로도 고정하므로 에이전트 프로세스가 다른 설정 기본값이나 작업 디렉터리로
이동하지 않습니다. 여러 에이전트 프로필이 같은 네임스페이스를 공유하면서 작성자
provenance가 필요하면 별도로 --actor-id를 사용합니다.
Source 범위는 fact search/list/get, pinned context, entity read, graph traversal/path/export, ID 기반 fact mutation에 일관되게 적용됩니다. Source 범위가 있는 entity 결과는 해당 source의 fact가 연결된 경우에만 반환하며, source provenance가 없는 전역 entity metadata는 제외합니다. 같은 fact content는 한 source 안에서만 중복 제거되고, 서로 다른 두 source의 같은 텍스트는 독립된 두 fact ID로 유지됩니다. Graph relation은 별도의 source provenance를 가지므로, source 범위가 있는 graph read는 relation namespace가 정확히 같은 edge만 허용합니다. 기존의 범위 없는 edge나 다른 source의 evidence, weight, relation type은 노출되지 않습니다. 클라이언트가 자기 범위를 선택하거나 덮어쓰면 안 되는 경우 위 token binding을 사용하세요.
이 경계는 하나의 신뢰된 팀 저장소에서 협력하는 에이전트에 강한 partition을
제공하지만, 상호 적대적인 tenant를 위한 완전한 database boundary는 아닙니다.
Entity name과 entity type은 source 간 공유 ontology를 의도합니다. Tenant끼리
ontology조차 공유하면 안 되거나 서로의 resource 사용으로부터 격리해야 한다면
별도 store 또는 별도 AideMemo process를 사용하세요.
이 선택의 배포 형태, trust boundary, production checklist는
공용 메모리 레이어를 참고하세요.
격리된 Codex 계정에는 같은 명시적 저장소를 가리키면서 --codex-home과
--actor-id를 반복합니다. 여러 Codex 프로필에서 메모리 공유를
참고하십시오.
문제 해결
| 증상 | 해결 방법 |
|---|---|
| 에이전트에서 도구가 보이지 않음 | MCP 설정 경로를 확인하고 에이전트를 다시 시작합니다. |
| Claude 격리 프로필에 스킬이 없음 | skill install --target claude 전에 CLAUDE_CONFIG_DIR를 설정합니다. |
| 한 Codex 프로필에서만 AideMemo가 보이지 않음 | 활성 CODEX_HOME에 설치하거나 --codex-home을 명시적으로 전달합니다. |
| Hermes 격리 프로필에서 보이지 않음 | 스킬과 MCP를 설치하기 전에 HERMES_HOME을 설정합니다. |
| pi가 MCP 단계를 제안함 | AideMemo를 업데이트하고 skill install --target pi만 사용합니다. |
command not found: aidememo | MCP 설정에 절대 경로를 사용합니다. |
| 에이전트가 잘못된 저장소를 엶 | 전역 --store로 다시 설치합니다. aidememo doctor가 Codex 저장소 불일치를 보고합니다. |
| 저장소 잠금 오류 | 공유 쓰기는 하나의 aidememo mcp-serve 프로세스를 사용합니다. |
| 다른 프로젝트 컨텍스트가 나타남 | source_id 범위를 추가하거나 확인합니다. |