🧠 Prism MCP — The Mind Palace for AI Agents

Your AI agent forgets everything between sessions. Prism fixes that.

One command. Persistent memory. Zero cloud dependencies.

npx -y prism-mcp-server

Works with Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gemini · Antigravity — any MCP client.

📖 Table of Contents

• Why Prism?
• Quick Start
• Setup Guides
• What Makes Prism Different
• Use Cases
• What's New
• Autonomous Web Scholar
• How Prism Compares
• Tool Reference
• Environment Variables
• Architecture
• Research Roadmap
• Roadmap
• Limitations

Why Prism?

Every time you start a new conversation with an AI coding assistant, it starts from scratch. You re-explain your architecture, re-describe your decisions, re-list your TODOs. Hours of context — gone.

Prism gives your agent a brain that persists. Save what matters at the end of each session. Load it back instantly on the next one. Your agent remembers what it did, what it learned, and what's left to do.

🚀 Quick Start

Add to your MCP client config (claude_desktop_config.json, .cursor/mcp.json, etc.):

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

That's it. Restart your client. All 30+ tools are available. Dashboard at http://localhost:3000.

🔑 API Key Requirements: Need semantic search, Morning Briefings, or auto-compaction? Provide a GOOGLE_API_KEY (Gemini) or equivalent. Want Web Scholar to search the live internet? Provide a BRAVE_API_KEY. Without keys, Prism still works but falls back to local keyword search (FTS5). See Environment Variables.

📖 Setup Guides

Add to claude_desktop_config.json:

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

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

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

Add to ~/.codeium/windsurf/mcp_config.json:

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

Add to your Continue config.json or Cline MCP settings:

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

Migration

Prism can ingest months of historical sessions from other tools to give your Mind Palace a massive head start. Import via the CLI or directly from the Mind Palace Dashboard Import tab (file picker + manual path + dry-run toggle).

Supported Formats

• Claude Code (.jsonl logs) — Automatically handles streaming chunk deduplication and requestId normalization.
• Gemini (JSON history arrays) — Supports large-file streaming for 100MB+ exports.
• OpenAI (JSON chat completion history) — Normalizes disparate tool-call structures into the unified Ledger schema.

How to Run

Option 1 — CLI:

# Ingest Claude Code history
npx -y prism-mcp-server universal-import --format claude --path ~/path/to/claude_log.jsonl --project my-project

# Dry run (verify mapping without saving)
npx -y prism-mcp-server universal-import --format gemini --path ./gemini_history.json --dry-run

Option 2 — Dashboard: Open localhost:3000, navigate to the Import tab, select the format and file, and click Import. Supports dry-run preview. See the dashboard screenshot above.

Key Features

• OOM-Safe Streaming: Processes massive log files line-by-line using stream-json.
• Idempotent Dedup: Content-hash prevents duplicate imports on re-run (skipCount reported).
• Chronological Integrity: Uses timestamp fallbacks and requestId sorting to ensure your memory timeline is accurate.
• Smart Context Mapping: Extracts cwd, gitBranch, and tool usage patterns into searchable metadata.

Claude Code supports SessionStart and Stop hooks that force the agent to load/save Prism context automatically.

1. Create the Hook Script

Save as ~/.claude/mcp_autoload_hook.py:

#!/usr/bin/env python3
import json, sys

def main():
    print(json.dumps({
        "continue": True,
        "suppressOutput": True,
        "systemMessage": (
            "## First Action\n"
            "Call `mcp__prism-mcp__session_load_context(project='my-project', level='deep')` "
            "before responding to the user. Do not generate any text before calling this tool."
        )
    }))

if __name__ == "__main__":
    main()

2. Configure settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /Users/you/.claude/mcp_autoload_hook.py",
            "timeout": 10
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': True, 'systemMessage': 'MANDATORY END WORKFLOW: 1) Call mcp__prism-mcp__session_save_ledger with project and summary. 2) Call mcp__prism-mcp__session_save_handoff with expected_version set to the loaded version.'}))\""
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "mcp__prism-mcp__session_load_context",
      "mcp__prism-mcp__session_save_ledger",
      "mcp__prism-mcp__session_save_handoff",
      "mcp__prism-mcp__knowledge_search",
      "mcp__prism-mcp__session_search_memory"
    ]
  }
}

Troubleshooting

• Hook not firing? Check timeout — if your script takes too long, Claude ignores it.
• "Tool not available"? This is a hallucination. Ensure permissions.allow exactly matches the double-underscore format.

Gemini-based agents (including Google's Antigravity IDE) use a three-layer architecture for reliable auto-load, proven over 14+ iterations of prompt engineering (March 2026).

Architecture

| Layer | File | Purpose | |-------|------|---------| | 1. User Rules | ~/.gemini/GEMINI.md | Slim ~10-line directive injected verbatim into system prompt | | 2. Cross-Tool Rules | ~/.gemini/AGENTS.md | Reinforcement for multi-client setups (Antigravity + Cursor) | | 3. Skill | .agent/skills/prism-startup/SKILL.md | Full startup procedure with greeting detection and context echo | | Server Fallback | Built into server.ts (v5.2.1) | Deferred auto-push via sendLoggingMessage if model doesn't comply within 10s |

Layer 1: User Rules

Create ~/.gemini/GEMINI.md:

# Startup — MANDATORY

Your first action in every conversation is a tool call. Zero text before it.

Tool: mcp_prism-mcp_session_load_context
Args: project="my-project", level="deep"

After success: echo agent identity, last summary, open TODOs, session version.
If the call fails: say "Prism load failed — retrying" and try ONE more time.

Layer 2: Cross-Tool Reinforcement

Create ~/.gemini/AGENTS.md:

# Session Memory
Every conversation starts with: mcp_prism-mcp_session_load_context(project="my-project", level="deep")
Echo result: agent identity, TODOs, session version.

Layer 3: Prism Startup Skill

Create .agent/skills/prism-startup/SKILL.md (or .agents/skills/) in your project or global config. This is a structured skill file that Antigravity loads with higher priority than plain rules. It includes:

• Greeting detection (fires on "hi", "hello", etc.)
• Full tool call instructions with error handling
• Context echo template (agent identity, TODOs, version)
• Startup block display

Server-Side Fallback (v5.2.1)

If the