CodeAbra/iai-mcp

모든 주장은 이를 증명하는 테스트 하네스 (harness)와 함께 제공됩니다. 벤치마크를 직접 실행해 보세요.

Independent Autistic Intelligence — Claude (및 기타 MCP 호환 어시스턴트)를 위한 로컬 메모리 레이어 (local memory layer)..

• 정의 (What it is)
• 빠른 시작 (Quick start)
• 사용법 (Usage)
• 작동 원리 (How it works)
• 벤치마크 (Benchmarks)
• 설정 (Configuration)
• Doctor
• AI 어시스턴트를 위한 참고 사항 (Notes for AI assistants)
• 상태 및 제한 사항 (Status and limitations)
• 호환성 (Compatibility)
• 이름에 대하여 (About the name)
• 저자 (Authors)
• 라이선스 (License)
• 기여하기 (Contributing)

MCP 프로토콜을 사용하여 Claude 및 기타 모든 MCP 호환 어시스턴트에게 장기 기억 (long-term memory)을 부여하는 로컬 서버입니다. 모든 세션의 모든 턴을 있는 그대로 캡처하고, 이러한 캡처 내용을 시간에 따라 당신이 누구인지에 대한 개인적인 지도 (personal map)로 구성하며, 새로운 대화가 시작될 때마다 관련 있는 작은 메모리 조각을 다시 제공합니다. 당신은 더 이상 "이것을 기억해 줘" 또는 "지난번에 우리가 뭐라고 했지?"라고 말할 필요가 없습니다.

저는 이것을 저 자신을 위해 만들었습니다. 잘 작동했습니다. 저는 몇 달 동안 매일 이것을 실행해 왔으며, 이제 이를 공유합니다. 벤치마크는 대부분 저 자신의 호기심을 위한 것이었습니다. 이것이 실제로 작동하는 것인지, 아니면 제가 그냥 익숙해진 것인지 알고 싶었습니다.

• macOS (Apple Silicon 테스트 완료)
• Python 3.11 또는 3.12
• Node.js 18+
• MCP 호스트로서의 Claude Code 또는 Codex CLI
• 약 500 MB의 여유 디스크 공간

Windows 및 Linux는 아직 지원되지 않지만 작업 중입니다.

git clone https://github.com/CodeAbra/iai-mcp.git
cd iai-mcp
bash scripts/install.sh

설치 프로그램은 Python 가상 환경 (venv)을 생성하고, 종속성 (LanceDB, sentence-transformers, torch-hd, NetworkX, igraph)을 설치하며, TypeScript MCP 래퍼 (wrapper)를 빌드하고, 기본 임베딩 모델 (embedding model, 약 130 MB)을 미리 다운로드하며, CLI를 ~/.local/bin/iai-mcp에 심볼릭 링크 (symlink)로 연결하고, macOS에서는 launchd에 데몬 (daemon)을 등록합니다.

~/.local/bin이 당신의 PATH에 포함되어 있는지 확인하세요:

export PATH="$HOME/.local/bin:$PATH" # ~/.zshrc 또는 ~/.bashrc에 추가
iai-mcp --version

이것이 메모리를 주변 환경에 녹아들게 (ambient) 만드는 요소입니다. 이러한 훅 (hooks)이 없다면 iai-mcp는 메모리를 읽기만 할 뿐, 대화 내용을 절대 쓰지 않으며 세션 시작 시 회상 (recall)을 주입하지 않습니다. 한 번의 명령으로 이 세 가지를 모두 연결할 수 있습니다:

iai-mcp capture-hooks install # 세 가지 훅(hook)을 모두 복사하고 ~/.claude/settings.json을 패치합니다.
iai-mcp capture-hooks status # 확인: "status: ACTIVE"가 출력되어야 합니다.
iai-mcp capture-hooks uninstall # 필요할 경우 깔끔하게 제거합니다.

Codex의 경우:

iai-mcp capture-hooks install --target codex

둘 다 설치하려면:

iai-mcp capture-hooks install --target all

설치 시 수행되는 작업:

• deploy/hooks/에 있는 세 개의 훅 스크립트를 ~/.claude/hooks/로 복사합니다 (chmod +x 적용):

iai-mcp-turn-capture.sh (UserPromptSubmit, 타임아웃 5초) — 각 프롬프트와 그 직전의 어시스턴트(assistant) 턴들을 순수 파일 I/O 방식으로 세션별 버퍼에 추가합니다. 세션 중에는 데몬(daemon) RPC가 전혀 발생하지 않습니다.

iai-mcp-session-capture.sh (Stop, 타임아웃 35초) — 세션 종료 시, 데몬이 비울 수 있도록 버퍼를 넘기고(roll over), 안전장치로서 iai-mcp capture-transcript --no-spawn을 실행합니다.

iai-mcp-session-recall.sh (SessionStart, 타임아웃 30초) — iai-mcp session-start를 호출하고 조립된 메모리 접두사(memory prefix)를 표준 출력(stdout)으로 파이프(pipe)합니다. Claude Code는 이를 첫 번째 프롬프트 이전에 additionalContext로 주입합니다. 안전장치: 저장소가 비어 있거나 데몬에 접근할 수 없는 경우 빈 표준 출력을 반환하며, 세션 시작이 차단되는 일은 없습니다.

• Claude Desktop에 설치된 경우 Claude Desktop의 설정에 iai-mcp를 등록합니다.
• 멱등성(Idempotent) 보장 — 다시 실행하면 기존 항목을 감지하고 변경을 수행하지 않습니다.
• 비밀 정보(secrets), 토큰, 네트워크 호출을 사용하지 않습니다.

런타임(runtime) 시 발생하는 일:

모든 프롬프트(턴당 훅): 새로운 트랜스크립트(transcript) 턴을 세션 버퍼에 추가합니다. 턴당 약 5ms가 소요되며, 임베딩(embedding)이나 데몬 소켓을 사용하지 않습니다.
모든 세션 종료(Stop 훅): 버퍼를 넘기고 남은 턴들을 캡처합니다. 안전하게 종료 코드 0을 반환합니다.
모든 세션 시작(recall 훅): 캐시된 메모리 접두사를 조립하여 Claude로 파이프합니다. 저장소가 비어 있거나 데몬에 접근할 수 없는 경우 → 빈 표준 출력을 반환합니다.
유휴(idle) 상태 시(데몬): WAKE → DROWSY 경계(5분 유휴) 및 모든 REM 사이클 이후에 쉴드(shield) → 임베딩(embed) → 중복 제거(dedup) → 암호화 삽입 파이프라인을 통해 버퍼를 비웁니다.

Claude Code:

claude mcp add iai-mcp -- node "$(pwd)/mcp-wrapper/dist/index.js"

또는 ~/.claude.json 파일을 직접 수정합니다:

{
"mcpServers": {
"iai-mcp": {
...

절대 경로를 사용해야 합니다. ~와 $HOME은 여기서 확장되지 않습니다.

Claude Desktop(테스트되지 않음)의 경우, ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 수정합니다.

Codex CLI:

[mcp_servers.iai-mcp]
command = "node"
args = ["/absolute/path/to/iai-mcp/mcp-wrapper/dist/index.js"]
...

Codex hooks는 현재 Codex CLI 빌드에서 안정적입니다. 만약 로컬 정책이나 이전 설치로 인해 hooks가 비활성화된 경우, ~/.codex/config.toml 파일에 [features].hooks = true를 활성화합니다.

iai-mcp doctor
iai-mcp daemon status

Claude Code를 재시작합니다. 세션을 시작하고 작업을 수행한 후 종료합니다. 그런 다음:

tail ~/.iai-mcp/logs/capture-$(date -u +%Y-%m-%d).log

rc=0 라인이 표시되어야 합니다. 이것이 당신의 첫 번째 기억입니다.

세션 중에는 iai-mcp를 직접 호출하지 않습니다. 연결되면:

캡처는 자동입니다. 사용자와 어시스턴트의 모든 턴(turn)은 타임스탬프와 세션 메타데이터와 함께 그대로 기록됩니다. *

Procedural(절차적 정보)는 시간이 지나면서 학습된 당신에 대한 안정적인 매개변수 세트입니다: 선호도, 스타일 단서, 반복되는 패턴 등입니다. 작동 방식에 따라 변화하는 11개의 밀봉된 노브(knobs)와 같습니다.

백그라운드 패스(background pass)가 주기적으로(수면 주기 동안) 실행됩니다: 에피소드를 클러스터링(clustering)하고, 의미론적 요약(semantic summaries)을 구축하며, 강화되지 않은 오래된 연결은 감쇠(decay)시키고, 빈번하게 함께 검색되는 경로를 강화합니다. 다시 방문하지 않은 것들은 자연스럽게 흐릿해집니다. Anthropic API를 한 번 호출하는 선택 사항인 "오늘의 통찰(insight of the day)" 단계가 있지만, 기본적으로는 꺼져 있습니다.

회상(Recall)은 세 가지 신호, 즉 의미론적 유사성(semantic similarity), 그래프 링크 강도(graph-link strength), 그리고 최신성(recency)을 결합합니다. 이 모든 것이 함께 순위가 매겨집니다.

모든 기록은 AES-256-GCM으로 저장 시 암호화(encrypted at rest)됩니다. 키는 ~/.iai-mcp/.key (mode 0600)에 저장됩니다. 백업해 두십시오. 키를 잃어버리면 기억도 잃게 됩니다.

모든 것은 ~/.iai-mcp/에 저장됩니다. 임베딩(Embeddings)은 bge-small-en-v1.5를 사용하여 로컬에서 계산됩니다. 머신을 떠나는 유일한 데이터는 클라이언트가 사용하는 LLM API와의 일반적인 대화뿐입니다.

Claude Code <--MCP-stdio--> TypeScript wrapper <--UNIX socket--> Python daemon <--> LanceDB

저는 정직한 수치를 원했기 때문에 이것들을 만들었습니다. 모든 하네스(harness)는 bench/에 포함되어 있습니다. 당신의 머신에서 직접 실행하여 결과값을 확인해 보십시오.

지표 (Metric)	목표 (Target)	측정값 (Measured)
Verbatim recall (바이트 단위 일치 회상)	>=99%	N=10k에서 >=99%
...

python -m bench.verbatim # verbatim fidelity (축자적 충실도)
python -m bench.neural_map # recall latency (회상 지연 시간)
python -m bench.memory_footprint # RAM usage (RAM 사용량)
...

LongMemEval-S 실행은 의도적으로 블라인드(blind) 테스트로 진행되었습니다. 데이터셋 특화 튜닝이나 하이퍼파라미터 스윕(hyperparameter sweep)은 없습니다. 수치는 있는 그대로입니다.

변수 (Variable)	기본값 (Default)	역할 (What it does)
IAI_MCP_STORE	~/.iai-mcp/	데이터 디렉토리
IAI_MCP_EMBED_MODEL	bge-small-en-v1.5	임베딩 모델. 다국어를 위한 bge-m3는 크기가 약 3배입니다.

임베더(embedder)를 전환하려면 저장소를 다시 임베딩해야 합니다: iai-mcp migrate reembed.

iai-mcp doctor

데몬 (daemon), 저장소 (store), 그리고 런타임 상태 (runtime state)에 대해 14가지 체크를 수행합니다. 출력은 각 체크 항목당 한 줄로 표시됩니다: PASS, WARN, 또는 FAIL.

iai-mcp doctor

체크 항목:

#	체크 항목	의미
a	데몬 활성화 여부 (Daemon alive)	데몬 프로세스가 실행 중인가?
...

14/14 PASS는 정상 상태입니다. 수면 주기 (sleep cycle) 동안 체크 (b)가 실패하는 13/14 상태 또한 정상입니다 (통합 (consolidation) 과정 중에는 소켓이 사용 중입니다). 여러 개의 FAIL이 발생하거나 (a) 또는 (f)에서 FAIL이 발생하는 것은 실제로 문제가 있음을 의미합니다.

증상	원인	해결 방법
import lancedb 실행 시 Illegal instruction (SIGILL) 오류로 충돌 발생	CPU에 AVX2가 없음 (Intel Celeron N4020, Atom, 구형 Core2, 일부 임베디드 ARM). LanceDB는 SSE 전용 폴백 (fallback)을 지원하지 않음.	AVX2를 지원하는 호스트에 배포하고 SSH stdio를 통해 연결하십시오 — Headless / VPS 배포 섹션을 참조하십시오.
첫 실행 시 keyring.errors.NoKeyringError 발생	저장소가 ~/.iai-mcp/.crypto.key에 파일 기반으로 저장됨. 이전 설정은 Keychain 전용 경로를 참조했음.	iai-mcp crypto init 실행 (멱등성 유지). iai-mcp daemon install은 신규 설치 시 이를 자동으로 호출함.
첫 시작 시 데몬이 CryptoKeyError와 함께 충돌 발생	신규 설치 시 daemon install을 건너뜀 (예: systemd 유닛을 수동으로 복사함) — .crypto.key가 아직 존재하지 않음.	iai-mcp crypto init을 실행한 후 데몬을 재시작하십시오.
iai-mcp daemon install 실행 시 "launchd bootstrap failed" 메시지 출력	이전 설치로 인한 기존 plist 파일이 존재함	먼저 iai-mcp daemon uninstall을 실행한 후, 다시 install을 수행하십시오.
데몬은 "active" 상태이나 틱 이벤트 (tick events)가 없음	첫 주 부트스트랩 단계 (아직 조용한 시간대 (quiet-window) 데이터가 없음)	MCP가 유휴 상태(idle)인 상태로 2시간을 기다리거나, 강제로 실행하십시오: iai-mcp daemon force-rem
claude mcp add 이후 Claude Code에 iai-mcp 도구가 나타나지 않음	완전히 종료하지 않음 — "창 재로드 (reload window)"만으로는 부족함	killall Claude를 실행한 후 다시 실행하십시오. MCP stderr를 확인하려면 ~/Library/Logs/Claude/*.log를 확인하십시오.

로컬 CPU에 AVX2가 없는 경우 (Intel Celeron N4020 Gemini Lake, 구형 Atom, 일부 임베디드 ARM) import lancedb는 SIGILL과 함께 충돌이 발생할 것입니다.

그리고 데몬 (daemon)을 로컬에서 실행할 수 없습니다. 탈출구(escape hatch)는 데몬을 원격 호스트(AVX2를 지원하는 저렴한 VPS라면 무엇이든 가능)에서 실행하고, Claude Code가 SSH stdio를 통해 MCP 래퍼 (wrapper)를 생성하도록 하는 것입니다.

원격 호스트 (remote host) (Linux 예시):

git clone https://github.com/CodeAbra/iai-mcp.git /opt/iai-mcp
cd /opt/iai-mcp && bash scripts/install.sh
loginctl enable-linger "$USER"
...

로컬 호스트 (local host):

claude mcp add iai-mcp -- \
ssh -o ConnectTimeout=5 -o ServerAliveInterval=30 \
user@vps.example.com \
...

동일 대륙 내에서의 왕복 지연 시간 (Round-trip latency)은 일반적으로 호출당 10-50 ms입니다.

헤드리스 호스트 (headless hosts)에 대한 Doctor 주의사항. iai-mcp doctor

(n) "HID idle source" 체크가 디스플레이 하드웨어가 없기 때문에 WARN(경고)을 반환합니다. 데몬의 깨어남/잠듦 (wake/sleep) 사이클은 heartbeat-idle로 대체되며, 이는 정상적으로 작동합니다. (b) "socket" 체크는 DREAMING 상태 동안 일시적으로 FAIL(실패)할 수 있습니다. 두 가지 모두 예상된 동작입니다.

만약 당신이 사용자의 iai-mcp 설치 또는 디버깅을 돕는 AI 모델이라면, 무엇인가를 진단하기 전에 이 내용을 읽으십시오.

데몬은 네 가지 FSM (유한 상태 머신, Finite State Machine) 상태를 가집니다: WAKE, TRANSITIONING, SLEEP, DREAMING. 이와 별개로, 래퍼 계층 (wrapper-layer)의 라이프사이클 (lifecycle)은 네 가지 상태를 가집니다: WAKE, DROWSY, SLEEP, HIBERNATION. 이것들은 서로 다른 파일에 있는 두 개의 서로 다른 상태 머신입니다. 혼동하지 마십시오.

고장 난 것처럼 보이지만 실제로는 그렇지 않은 것들:

last_tick_at이 몇 시간 동안 변경되지 않음. 이것은 프로세스 하트비트 (heartbeat)가 아니라 수면 사이클 틱 (sleep-cycle tick) 타임스탬프입니다. 데몬은 last_tick_at이 오래되었더라도 살아있고 건강할 수 있습니다. 대신 iai-mcp daemon status를 확인하십시오.

몇 시간 동안 fsm_state: DREAMING 상태임. 정상입니다. 데몬은 수면 사이클을 실행 중입니다. 깨어남 전환 (Wake transitions)은 시간 기반이 아니라 이벤트 기반 (새 세션이 도착하면 깨어남)입니다.

캡처 로그에 status: deferred가 나타남. 이것은 Stop 훅 (hook)이 취하는 유일한 경로입니다. 이는 캡처 내용을 ~/.iai-mcp/.deferred-captures/에 기록하며, 데몬은 다음 틱 (tick)에서 이를 가져옵니다. 이는 실패가 아니라 설계된 방식입니다.

iai-mcp doctor

iai-mcp doctor 명령을 실행했을 때, (b) "socket unreachable" 체크 항목을 포함하여 13/14 PASS가 표시된다면 이는 정상입니다. 이는 데몬의 FSM (Finite State Machine, 유한 상태 기계)이 SLEEP 또는 DREAMING 상태일 때 예상되는 결과입니다. 데이터 통합 패스 (consolidation passes) 동안 소켓은 의도적으로 응답하지 않으며, 이는 정상적인 상태입니다.

콜드 스타트 (Cold start)에는 몇 초가 소요됩니다. 데몬은 LanceDB 저장소를 초기화하고 임베딩 모델 (embedding model)을 메모리에 로드해야 합니다. 5초 동안 응답이 없다고 해서 프로세스를 종료하지 마세요.

실제 문제는 다음과 같은 경우입니다: iai-mcp daemon status 명령이 ok: False를 반환하거나, iai-mcp doctor가 여러 개의 FAIL 결과를 보여주거나, 데몬 프로세스가 아예 존재하지 않는 경우 (pgrep -f iai_mcp.daemon 명령이 아무것도 반환하지 않음)입니다.

의심스러운 상황이 발생하면 iai-mcp doctor를 실행하고 출력 내용을 읽어보세요. 출력 결과는 그 자체로 설명이 충분합니다.