Concepts

Mind Palace has two types of artifacts: curated (you write, commit to git) and generated (CLI creates, gitignored).


.palace/
├── palace.jsonc          # Curated: project config
├── rooms/*.jsonc         # Curated: room definitions
├── playbooks/*.jsonc     # Curated: workflow templates
├── brain/                # Generated: knowledge storage
│   ├── decisions/*.json  # Decisions with outcomes
│   ├── ideas/*.json      # Ideas and hypotheses
│   └── learnings/*.json  # Verified learnings
├── sessions/             # Generated: agent sessions
│   └── *.json            # Session transcripts
├── index/
│   ├── palace.db         # Generated: SQLite + FTS5 index
│   └── scan.json         # Generated: scan metadata
└── outputs/
    └── context-pack.json # Generated: assembled context

Curated Artifacts

Palace Config

.palace/palace.jsonc - The root manifest.


{
  "schemaVersion": "1.0.0",
  "kind": "palace/config",
  "project": { "name": "my-app" },
  "defaultRoom": "core",
  "guardrails": {
    "doNotTouchGlobs": ["*.secret", "vendor/**"]
  },
  "neighbors": {
    /* corridors to other repos */
  },
  "vscode": {
    /* extension settings */
  }
}

Rooms

.palace/rooms/*.jsonc - Logical groupings answering “where should I look?”


// rooms/auth.jsonc
{
  "schemaVersion": "1.0.0",
  "kind": "palace/room",
  "name": "auth",
  "purpose": "Authentication and session management",
  "entryPoints": ["src/auth/login.ts", "src/middleware/auth.ts"],
  "includeGlobs": ["src/auth/**", "src/middleware/auth*"]
}

Generated Artifacts

Index (Tier-0)

palace.db - SQLite database with:

WAL mode - Concurrent reads during writes
FTS5 - Full-text search with BM25 ranking
File hashes - SHA-256 for staleness detection

Created by palace scan. This is the source of truth for the codebase structure.

Context Pack

context-pack.json - Portable context for agents.

Created by palace explore "goal" --full or palace check --collect. Contains file snippets, related learnings, and project metadata.

Change Signal

change-signal.json - Diff metadata for scoped workflows.

Created by palace check --signal --diff HEAD~1..HEAD. Tells the palace exactly what has changed between two points.

Runtime Components

Butler

The search engine. Uses FTS5 with BM25 ranking + entry-point boosting. Exposed via palace explore.


palace explore "where is authentication"
palace explore --room api "rate limiting"

MCP Server

JSON-RPC 2.0 server for AI agents.


palace serve

Exposes tools like search_mind_palace, get_context, and get_graph.

Observer

The VS Code extension HUD. Automates command execution and provides a “Traffic Light” for codebase health.

Verification Model

Mind Palace uses a tiered verification system to ensure AI agents aren’t working on stale information.


palace check [--strict] [--diff <range>]

Fast Mode (Default): Checks modification times and file sizes. Hashes only files that look different.
Strict Mode: Re-hashes every file in the workspace to guarantee 100% correctness.
Scoped Mode: Verifies only the files within a specific Git diff range.

Corridors

Import context from other Mind Palace repositories.


{
  "neighbors": {
    "backend": {
      "url": "https://storage.example.com/backend/context-pack.json",
      "ttl": "24h"
    },
    "shared-lib": {
      "localPath": "../shared-lib" // monorepo
    }
  }
}

Remote files are namespaced: corridor://backend/src/api.ts. This allows the Palace to search across repository boundaries.