Mind Palace

A deterministic context system for codebases, inspired by the Method of Loci .

Quick Links: Getting Started | CLI Reference | Features | Architecture

The Problem

AI agents working with codebases face three failures:

Context rot - Agents receive stale snapshots that diverge from reality
Scope drift - Without boundaries, agents wander into irrelevant code
Heuristic fragility - File-matching guesses break as codebases evolve

Current solutions (RAG, embeddings, “just dump everything”) are probabilistic. They work until they don’t.

The Solution

Mind Palace provides a deterministic, schema-validated index that both humans and AI agents can trust.


┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   You curate    │     │   CLI indexes   │     │  Agents query   │
│   Rooms +       │ ──► │   with hashes   │ ──► │  with contracts │
│   Playbooks     │     │   (SQLite+FTS5) │     │  (MCP protocol) │
└─────────────────┘     └─────────────────┘     └─────────────────┘

No embeddings. No guessing. Deterministic.

Method of Loci

The Method of Loci (memory palace technique) is a mnemonic strategy from ancient Greece. You mentally place information in specific locations within an imagined building, then “walk through” to recall it.

Mind Palace applies this to code:

Memory Palace	Mind Palace
Imagined building	Your codebase
Rooms	Logical groupings (auth, api, cli)
Objects in rooms	Entry points, key files
Walking through	Querying with Butler
Recalling	Assembling context packs

The metaphor isn’t decorative—it’s the architecture.

Key Properties

Property	How
Deterministic	SHA-256 hashes, SQLite with WAL, reproducible scans
Schema-first	JSON Schema validation on all artifacts
Verifiable	`palace check` proves freshness
Agent-ready	MCP server for direct AI integration
Diff-scoped	Constrain context to changed files only

Quick Start


# Install
curl -L https://github.com/koksalmehmet/mind-palace/releases/latest/download/palace-darwin-arm64 -o palace
chmod +x palace && sudo mv palace /usr/local/bin/
 
# Initialize
palace init && palace scan
 
# Explore
palace explore "where is authentication handled"
 
# Generate context for an AI agent
palace explore "fix the login bug" --full

Components

Component	Purpose
CLI	Core engine: `palace scan`, `explore`, `check`, `store`, `serve`
VS Code Extension	HUD, sidebar, auto-sync
MCP Server	AI agent integration via JSON-RPC
Dashboard	Web UI for visualization and monitoring

Features

Brain (Ideas & Decisions)

Track ideas, decisions, and their outcomes over time.


palace store "Let's use JWT for authentication" --as decision
palace recall "auth" --type decision

Session Memory

Track agent work sessions, activities, and learnings. See Session Memory.


palace session start --agent claude --goal "Add authentication"
palace store "Use bcrypt for password hashing" --as learning
palace recall "authentication"
palace brief src/auth.go

Call Graph

Explore function relationships in your codebase.


palace explore --map handleAuth --direction up
palace explore --map processRequest --direction down --depth 3

Governance

Proposals workflow for human-in-the-loop approval. See Governance.


palace store "Use JWT for auth" --as decision  # Creates proposal
palace proposals --status pending              # List pending proposals
palace approve prop_abc123                     # Approve proposal
palace store --direct "Trust this source" --as learning  # Direct write

Corridors

Share knowledge across projects. See Corridors.


palace corridor link api-service ~/code/api-service
palace corridor search "error handling" --all
palace corridor personal
palace corridor promote learning_123

Dashboard

Visual exploration of your codebase. See Dashboard.


palace dashboard
# Opens http://localhost:3001

Next Steps

Getting Started - Installation and quick start
Concepts - Core terminology and architecture
CLI Reference - Complete command reference