🧠 Prism MCP — AI 에이전트를 위한 마인드 팰리스(Mind Palace)

AI 에이전트는 세션이 바뀔 때마다 모든 것을 잊어버립니다. Prism은 이를 해결하고, 에이전트에게 생각하는 법을 가르칩니다.

Prism v7.8은 인간의 뇌 메커니즘에서 영감을 받은 진정한 **인지 아키텍처(Cognitive Architecture)**입니다. 단순한 벡터 검색을 넘어, 에이전트는 이제 경험을 통해 원칙을 형성하고, 인과 관계를 따라 사고하며, 정보가 부족할 때 이를 스스로 인지합니다. 에이전트는 단순히 기억하는 것이 아니라, 학습합니다.

npx -y prism-mcp-server

Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gemini · Antigravity 등 모든 MCP 클라이언트와 호환됩니다.

https://github.com/dcostenco/prism-mcp/raw/main/docs/prism_mcp_demo.mp4

📖 목차

• Prism을 선택해야 하는 이유

• 빠른 시작

• 마법 같은 순간

• 설정 가이드

• 범용 가져오기: 기록 불러오기

• Prism의 차별점

• 인지 아키텍처 (v7.8)

• 데이터 개인정보 보호 및 전송

• 사용 사례

• 새로운 기능

• Prism 비교

• CLI 참조

• 도구 참조

• 환경 변수

• 아키텍처

• 과학적 기반

• 마일스톤 및 로드맵

• 문제 해결 FAQ

Prism을 선택해야 하는 이유

AI 코딩 어시스턴트와 대화를 시작할 때마다, 에이전트는 항상 처음부터 다시 시작합니다. 아키텍처를 다시 설명하고, 결정 사항을 다시 말하고, TODO 목록을 다시 나열해야 합니다. 수 시간의 컨텍스트가 사라지는 것입니다.

Prism은 에이전트에게 지속되는 뇌를 제공하고, 추론하는 법을 가르칩니다. 세션이 끝날 때 중요한 내용을 저장하고, 다음 세션에서 즉시 불러오세요. Prism은 단순한 저장을 넘어, 원시 경험을 지속적인 원칙으로 통합하고, 인과 관계를 추적하여 근본 원인을 파악하며, *"모른다"*고 말할 때를 아는 능력을 갖추게 합니다.

📌 용어: 이 문서에서 **"Prism"**은 MCP 서버 및 인지 메모리 엔진을 의미합니다. **"마인드 팰리스(Mind Palace)"**는 localhost:3000에서 실행되는 시각적 대시보드 UI를 의미하며, 에이전트의 뇌를 들여다보는 창입니다. 둘은 함께 작동하며, 대시보드는 선택 사항입니다.

Prism의 세 가지 핵심 요소:

1. 🧠 인지 메모리(Cognitive Memory) — 기억은 인간의 뇌처럼 순위가 매겨집니다. 최근에 자주 접근한 컨텍스트가 먼저 나타나며, 오래된 컨텍스트는 ACT-R 활성화 감쇠를 통해 자연스럽게 사라집니다. 원시 경험은 헤브 학습(Hebbian learning)을 통해 의미론적 원칙으로 통합됩니다. 그 결과, 일반적인 벡터 검색과는 비교할 수 없는 검색 품질을 제공합니다. (참조: 인지 아키텍처 및 과학적 기반.)

2. 🔗 다중 홉 추론(Multi-Hop Reasoning) — 에이전트가 "오류 X"를 검색할 때, Prism은 단순히 "오류 X"가 언급된 로그만 찾지 않습니다. 활성화 확산(Spreading activation)이 인과 관계 그래프를 따라 이동하여 "오류 X"와 연결된 "아키텍처 결정 Z"와 관련된 "해결책 Y"를 찾아냅니다. 이는 문자 그대로의 사고 흐름입니다. (참조: 인지 아키텍처.)

3. 🏭 자율 실행 (Dark Factory) — 준비가 되면, Prism은 적대적 평가자가 생성자가 놓친 버그를 잡아내는 fail-closed 파이프라인을 통해 코딩 작업을 처음부터 끝까지 수행할 수 있습니다. (참조: Dark Factory.)

🚀 빠른 시작

사전 요구 사항

• Node.js v18+ (v20 LTS 권장; v23.x는 알려진 npx 문제가 있음)

• MCP 호환 클라이언트 (Claude Desktop, Cursor, Windsurf, Cline 등)

• 핵심 기능 사용 시 API 키 불필요 (참조: 기능 매트릭스)

설치

MCP 클라이언트 설정(claude_desktop_config.json, .cursor/mcp.json 등)에 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

⚠️ Windows / 제한된 셸: MCP 클라이언트에서 npx를 찾을 수 없다는 오류가 발생하면, 노드 바이너리의 절대 경로를 사용하세요 (예: C:\Program Files\nodejs\npx.cmd).

설치 완료입니다. 클라이언트를 재시작하면 모든 도구를 사용할 수 있습니다. 마인드 팰리스 대시보드(에이전트의 뇌를 위한 시각적 UI)는 http://localhost:3000에서 자동으로 시작됩니다. 탭을 계속 열어둘 필요는 없습니다. 대시보드는 백그라운드에서 실행되며 MCP 도구는 대시보드 유무와 관계없이 작동합니다.

🔮 팁: 설치 후 브라우저에서 **http://localhost:3000**을 열어 마인드 팰리스 대시보드를 확인하세요. 에이전트의 뇌를 실시간으로 시각화한 아름다운 UI입니다. 지식 그래프, 의도 상태 게이지, 세션 원장을 탐색해 보세요.

🔄 Prism 업데이트: npx -y는 패키지를 로컬에 캐시합니다. 최신 버전으로 강제 업데이트하려면 MCP 클라이언트를 재시작하세요. npx -y가 자동으로 최신 릴리스를 가져옵니다. 이전 버전에 머물러 있다면 재시작 전에 npx clear-npx-cache (또는 npm cache clean --force)를 실행하세요.

MCP 설정의 env 블록에 PRISM_DASHBOARD_PORT를 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": { "PRISM_DASHBOARD_PORT": "3001" }
    }
  }
}

그런 다음 http://localhost:3001을 대신 여세요.

기능 매트릭스

🔑 핵심 마인드 팰리스는 API 키 없이 100% 오프라인으로 작동합니다. 클라우드 키는 지능형 기능을 잠금 해제합니다. 환경 변수를 참조하세요.

💰 API 비용 참고: GOOGLE_API_KEY (Gemini)는 대부분의 개인 사용량을 커버하는 넉넉한 무료 티어를 제공합니다. BRAVE_API_KEY는 월 2,000회 무료 검색을 제공합니다. FIRECRAWL_API_KEY는 500 크레딧의 무료 플랜이 있습니다. 일반적인 개인 개발 환경에서는 무료 티어 내에서 월 $0으로 충분합니다. 대규모 팀이나 헤비한 자율 파이프라인 사용 시에만 비용이 발생합니다.

✨ 마법 같은 순간

세션 1 (월요일 저녁):

You: "Analyze this auth architecture and plan the OAuth migration."
Agent: *deep analysis, decisions, TODO list*
Agent: session_save_ledger → session_save_handoff ✅

세션 2 (화요일 아침 — 새로운 대화, 새로운 컨텍스트 창):

Agent: session_load_context → "Welcome back! Yesterday we decided to use PKCE
       flow with refresh tokens. 3 TODOs remain: migrate the user table,
       update the middleware, and write integration tests."
You: "Pick up where we left off."

에이전트가 모든 것을 기억합니다. 파일을 다시 업로드할 필요도, 결정을 다시 설명할 필요도 없습니다.

📖 설정 가이드

claude_desktop_config.json에 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

.cursor/mcp.json (프로젝트) 또는 ~/.cursor/mcp.json (전역)에 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

~/.codeium/windsurf/mcp_config.json에 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"]
    }
  }
}

Continue config.json 또는 Cline MCP 설정에 추가하세요:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": {
        "PRISM_STORAGE": "local",
        "BRAVE_API_KEY": "your-brave-api-key"
      }
    }
  }
}

Claude Code는 .clauderules에 추가하여 MCP 도구를 자연스럽게 불러옵니다. 단순히 다음을 추가하세요:

Always start the conversation by calling `mcp__prism-mcp__session_load_context(project='my-project', level='deep')`.
When wrapping up, always call `mcp__prism-mcp__session_save_ledger` and `mcp__prism-mcp__session_save_handoff`.

형식 참고: Claude는 MCP 도구를 이중 밑줄(mcp__prism-mcp__...)로 자동으로 감싸며, 대부분의 다른 클라이언트는 단일 밑줄(mcp_prism-mcp_...)을 사용합니다. Prism 백엔드는 두 형식 모두 원활하게 처리합니다.

CLI 대안: MCP 도구를 사용할 수 없거나 Claude Code 주변에서 스크립트를 작성하는 경우:

# Load context before a session
prism load my-project --level deep

# Machine-readable JSON for parsing in scripts
prism load my-project --level deep --json

안정적인 세션 자동 로드를 보장하는 검증된 3계층 프롬프트 아키텍처는 Gemini 설정 가이드를 참조하세요.

Antigravity는 모델에 MCP 도구를 노출하지 않습니다. 대체 수단으로 prism load CLI를 사용하세요:

# From a shell or run_command tool
prism load my-project --level standard --json

# Or via the wrapper script
bash ~/.gemini/antigravity/scratch/prism_session_loader.sh my-project

CLI는 MCP 도구와 동일한 저장소 계층(SQLite 또는 Supabase)을 사용합니다.

⚠️ 중요 (v9.2.2): 스플릿 브레인 방지 MCP 서버가 PRISM_STORAGE=local로 설정되어 있는데 Supabase 자격 증명도 설정된 경우, CLI는 잘못된 백엔드(Supabase)에서 읽고 서버는 SQLite에 쓸 수 있습니다. 이로 인해 TODO가 꼬이고 상태가 달라집니다. 로컬 모드 환경에서 CLI를 사용할 때는 --storage local을 명시적으로 전달하세요:

prism load my-project --storage local --json

prism_session_loader.sh 래퍼는 v9.2.2부터 이를 자동으로 처리합니다.

prism load CLI를 사용하여 모든 셸 환경에서 세션 컨텍스트에 액세스하세요:

# Quick check — human-readable
prism load my-project

# Parse JSON in scripts
CONTEXT=$(prism load my-project --level quick --json)
SUMMARY=$(echo "$CONTEXT" | jq -r '.handoff[0].last_summary')
VERSION=$(echo "$CONTEXT" | jq -r '.handoff[0].version')
echo "Project at v$VERSION: $SUMMARY"

# Explicit storage backend (v9.2.2 — prevents split-brain)
prism load my-project --storage local --json
prism load my-project --storage supabase --json

# Role-scoped loading
prism load my-project --role qa --json

# Use in CI/CD to verify context exists before deploying
if ! prism load my-project --level quick --json | jq -e '.handoff[0].version' > /dev/null 2>&1; then
  echo "No Prism context found — skipping context-aware deploy"
fi

📦 설치: npm install -g prism-mcp-server를 실행하면 prism CLI를 전역에서 사용할 수 있습니다. 로컬 빌드의 경우: node /path/to/prism/dist/cli.js load.

여러 기기나 팀 간에 메모리를 동기화하려면:

{
  "mcpServers": {
    "prism-mcp": {
      "command": "npx",
      "args": ["-y", "prism-mcp-server"],
      "env": {
        "PRISM_STORAGE": "supabase",
        "SUPABASE_URL": "https://your-project.supabase.co",
        "SUPABASE_KEY": "your-supabase-anon-or-service-key"
      }
    }
  }
}

스키마 마이그레이션

Prism은 첫 연결 시 스키마를 자동으로 적용하므로 수동 단계가 필요 없습니다. 마이그레이션을 수동으로 적용하거나 다시 적용해야 하는 경우(예: 새 프로젝트 또는 버전 업데이트 후), Supabase SQL Editor 또는 CLI를 통해 supabase/migrations/의 SQL 파일을 순서대로 실행하세요:

# Via CLI (requires supabase CLI + project linked)
supabase db push

# Or apply a single migration via the Supabase dashboard SQL Editor
# Paste the contents of supabase/migrations/0NN_*.sql and click Run

주요 마이그레이션:

• 020_* — 핵심 스키마 (원장, 핸드오프, FTS, TTL, CRDT)

• 033_memory_links.sql — 연관 메모리 그래프 (MemoryLinks) — session_backfill_links에 필요

Anon 키 vs. 서비스 역할 키: Anon 키는 개인용으로 작동합니다 (Supabase RLS 정책 적용). 여러 사용자가 동일한 Supabase 프로젝트를 공유하는 팀 배포에는 서비스 역할 키를 사용하세요. RLS를 우회하여 인증 컨텍스트와 관계없이 모든 행을 관리할 수 있습니다. 서비스 역할 키를 클라이언트