🧠 Prism MCP — AI 智能体的“记忆宫殿”

你的 AI 智能体在每次会话间都会“失忆”。Prism 解决了这个问题，并教会它如何思考。

Prism v7.8 是一种受人类大脑机制启发的真正认知架构。超越了简单的向量搜索，你的智能体现在可以从经验中形成原则，遵循因果思维链，并具备自我意识，知道何时缺乏信息。你的智能体不仅能记住，还能学习。

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. 🧠 认知记忆 — 记忆像人类大脑一样进行排名：最近和频繁访问的上下文首先浮现，而陈旧的上下文通过 ACT-R 激活衰减自然淡出。原始经验通过赫布学习 (Hebbian learning) 整合为语义原则。其结果是任何简单的向量搜索都无法比拟的检索质量。(参见 认知架构 和 科学基础。)

2. 🔗 多跳推理 — 当你的智能体搜索“错误 X”时，Prism 不仅仅会找到提到“错误 X”的日志。激活扩散会遍历因果图，并带回与“架构决策 Z”相连的“变通方案 Y”——这是一种真正的思维链。(参见 认知架构。)

3. 🏭 自主执行 (暗工厂) — 当你准备好时，Prism 可以端到端地运行编码任务，通过一个故障关闭管道，其中对抗性评估器会在你看到 PR 之前捕获生成器遗漏的错误。(参见 暗工厂。)

🚀 快速入门

前置条件

• 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 / 受限 Shell： 如果你的 MCP 客户端提示找不到 npx，请使用 node 二进制文件的绝对路径 (例如 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)。

将 PRISM_DASHBOARD_PORT 添加到你的 MCP 配置 env 块中：

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

然后改为打开 http://localhost:3001。

能力矩阵

🔑 核心记忆宫殿在 100% 离线状态下无需任何 API 密钥即可工作。云端密钥可解锁智能功能。参见 环境变量。

💰 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 通过将 MCP 工具添加到工作区 .clauderules 中来自然地获取它们。只需添加：

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

参见 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 从任何 shell 环境访问会话上下文：

# 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 编辑器 或 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 所需

匿名密钥 vs 服务角色密钥： 匿名密钥适用于个人使用 (应用 Supabase RLS 策略)。对于多个用户共享同一个 Supabase 项目的团队部署，请使用服务角色密钥——它绕过 RLS 并允许 Prism 管理所有行，无论身份验证上下文如何。切勿在客户端暴露服务角色密钥。

git clone https://github.com/dcostenco/prism-mcp.git
cd prism-mcp && npm install && npm run build

然后添加到你的 MCP 配置：

{
  "mcpServers": {
    "prism-mcp": {
      "command": "node",
      "args": ["/path/to/prism-mcp/dist/server.js"],
      "env": {
        "BRAVE_API_KEY": "your-key",
        "GOOGLE_API_KEY": "your-gemini-key"
      }
    }
  }
}

Prism 可以原生部署到 Render 等云平台，这样你的智能体记忆始终在线，并可在不同机器或团队之间访问。

1. Fork 此仓库。

2. 在 Render 仪表板中，创建一个指向你仓库的新 Web Service。

3. 在设置向导中，选择 Docker 作为运行时。

4. 将 Dockerfile 路径设置为 Dockerfile.smithery。

5. 使用 sse 传输将你的本地 MCP 客户端连接到新的云端点：

{
  "mcpServers": {
    "prism-mcp-cloud": {
      "command": "npx",
      "args": ["-y", "supergateway", "--url", "https://your-prism-app.onrender.com/sse"]
    }
  }
}

注意： Dockerfile.smithery 使用优化的多阶段构建，在开发环境中安全编译 Typescript，然后在精简的生产镜像中启动服务器。无需发布 NPM！

常见安装陷阱

❌ 不要使用 npm install -g： 硬编码二进制路径 (例如 /opt/homebrew/Cellar/node/23.x/bin/prism-mcp-server) 绑定到特定的 Node.js 版本——当 Node 更新时，路径会静默失效。

✅ 始终使用 npx：

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

npx 会自动解析正确的二进制文件，始终获取最新版本，并且在 macOS、Linux 和 Windows 上运行一致。已经全局安装了？请先运行 npm uninstall -g prism-mcp-server。

❓ 启动时看到缺少 API 密钥的警告？ 这是预期的，不是错误。BRAVE_API_KEY / GOOGLE_API_KEY 警告仅供参考——核心会话记忆无需任何密钥即可工作。参见 环境变量 了解每个密钥解锁的功能。

💡 智能体会自动加载 Prism 吗？ 使用 Cursor、Windsurf 或其他 MCP 客户端的智能体会自动看到 session_load_context