Skip to Content
Mind Palace 0.4.2-alpha is out. Check it out →
ArchitectureArchitecture Overview

Architecture Overview

This document describes the high-level architecture of Mind Palace.

System Overview

┌─────────────────────────────────────────────────────────────────┐
│                        Mind Palace                               │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐        │
│  │   palace     │   │   VS Code    │   │  AI Agents   │        │
│  │    CLI       │   │  Extension   │   │  (via MCP)   │        │
│  └──────┬───────┘   └──────┬───────┘   └──────┬───────┘        │
│         │                  │                  │                 │
│         └──────────────────┼──────────────────┘                 │
│                            │                                    │
│                     ┌──────┴──────┐                            │
│                     │   Butler    │                            │
│                     │  (MCP API)  │                            │
│                     └──────┬──────┘                            │
│                            │                                    │
│     ┌──────────────────────┼──────────────────────┐            │
│     │                      │                      │            │
│  ┌──┴───┐            ┌─────┴────┐          ┌─────┴────┐       │
│  │Index │            │  Memory  │          │ Corridor │       │
│  │Oracle│            │(Sessions)│          │ (Global) │       │
│  └──────┘            └──────────┘          └──────────┘       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Components

1. CLI (apps/cli)

The command-line interface for all Mind Palace operations.

Responsibilities:

  • Initialize workspaces
  • Scan and index codebases
  • Query symbols and files
  • Manage sessions and learnings
  • Serve MCP and LSP servers

Key Files:

  • apps/cli/main.go - Entry point
  • apps/cli/internal/cli/cli.go - Command implementations

2. Butler (apps/cli/internal/butler)

The central coordinator and MCP server.

Responsibilities:

  • Handle MCP tool calls from agents
  • Coordinate between index, memory, and corridors
  • Assemble context for agent queries
  • Serve as the API layer

Key Files:

  • apps/cli/internal/butler/butler.go - Main coordinator
  • apps/cli/internal/butler/mcp.go - MCP protocol handling

3. Index/Oracle (apps/cli/internal/index)

The code intelligence engine.

Responsibilities:

  • Parse source files
  • Build symbol tables
  • Index function calls and references
  • Provide fast symbol lookup

Key Files:

  • apps/cli/internal/index/index.go - Core indexing
  • apps/cli/internal/index/oracle.go - Query and context assembly

4. Memory (apps/cli/internal/memory)

Session memory and learning storage.

Responsibilities:

  • Track agent sessions
  • Log activities
  • Store and retrieve learnings
  • Maintain file intelligence

Key Files:

  • apps/cli/internal/memory/memory.go - Main interface
  • apps/cli/internal/memory/schema.go - Database schema

5. Corridor (apps/cli/internal/corridor)

Cross-workspace knowledge sharing.

Responsibilities:

  • Manage personal corridor
  • Link workspaces
  • Promote learnings
  • Search across corridors

Key Files:

  • apps/cli/internal/corridor/global.go - Global corridor manager
  • apps/cli/internal/corridor/schema.go - Database schema

6. LSP Server (apps/cli/internal/lsp)

Language Server Protocol implementation for editor integration.

Responsibilities:

  • Pattern violation diagnostics
  • Contract mismatch detection
  • Hover information
  • Code actions for approvals

Key Files:

  • apps/cli/internal/lsp/server.go - LSP server
  • apps/cli/internal/lsp/diagnostics.go - Diagnostic generation

7. Analysis (apps/cli/internal/analysis)

Language-specific parsers.

Responsibilities:

  • Parse source files
  • Extract symbols (functions, types, etc.)
  • Identify call relationships
  • Handle language-specific constructs

Supported Languages:

  • Go (primary)
  • TypeScript/JavaScript
  • Python
  • Java
  • Rust
  • C/C++

Data Flow

Scanning

Source Files
    │
    ▼
┌───────────┐
│ Analyzers │ ──> Parse & extract symbols
└─────┬─────┘
      │
      ▼
┌───────────┐
│   Index   │ ──> Store in SQLite (palace.db)
└───────────┘

Query

Query ("findUser")
    │
    ▼
┌───────────┐
│  Oracle   │ ──> Search symbols, build context
└─────┬─────┘
      │
      ▼
┌───────────┐
│  Memory   │ ──> Add relevant learnings
└─────┬─────┘
      │
      ▼
┌───────────┐
│ Corridors │ ──> Add cross-project learnings
└─────┬─────┘
      │
      ▼
Context Response (files, symbols, learnings)

Session Workflow

Agent Starts
    │
    ├─> start_session ──> Memory records session
    │
    ├─> log_activity ──> Memory tracks file access
    │
    ├─> get_context ──> Oracle + Memory + Corridors
    │
    ├─> add_learning ──> Memory stores learning
    │
    └─> end_session ──> Memory finalizes session

Database Schema

Code Index (palace.db)

┌────────────┐    ┌──────────────┐
│   rooms    │    │    files     │
├────────────┤    ├──────────────┤
│ name       │◄───┤ room_name    │
│ path       │    │ path         │
│ description│    │ language     │
└────────────┘    │ hash         │
                  └──────┬───────┘
                         │
                         ▼
                  ┌──────────────┐    ┌────────────────┐
                  │   symbols    │    │     calls      │
                  ├──────────────┤    ├────────────────┤
                  │ name         │◄───┤ caller_symbol  │
                  │ kind         │    │ callee_symbol  │
                  │ file_path    │    │ file_path      │
                  │ line         │    │ line           │
                  │ signature    │    └────────────────┘
                  └──────────────┘

Memory (memory.db)

┌────────────────┐    ┌────────────────┐
│    sessions    │    │   activities   │
├────────────────┤    ├────────────────┤
│ id             │◄───┤ session_id     │
│ agent_type     │    │ kind           │
│ goal           │    │ target         │
│ state          │    │ outcome        │
└────────────────┘    └────────────────┘

┌────────────────┐    ┌────────────────┐
│   learnings    │    │   file_intel   │
├────────────────┤    ├────────────────┤
│ id             │    │ path           │
│ scope          │    │ edit_count     │
│ scope_path     │    │ failure_count  │
│ content        │    │ last_editor    │
│ confidence     │    └────────────────┘
└────────────────┘

Directory Structure

mind-palace/
├── apps/                    # All ecosystem applications
│   ├── cli/                 # Palace CLI (Go)
│   │   ├── main.go          # Entry point
│   │   ├── internal/        # Core engine packages
│   │   ├── pkg/             # Public Go API
│   │   ├── schemas/         # JSON schemas
│   │   ├── starter/         # Init templates
│   │   └── tests/           # Integration tests
│   ├── docs/                # Next.js documentation
│   └── vscode/              # VS Code extension
├── assets/                  # Shared branding assets
├── packaging/               # Installer scripts
├── scripts/                 # Build & CI scripts
└── Makefile

Technology Stack

ComponentTechnology
CLI & BackendGo
DatabaseSQLite (modernc.org/sqlite)
MCP ProtocolJSON-RPC over stdio
LSP ServerGo (Language Server Protocol)
Parser (Go)go/parser, go/ast
Parser (TS/JS)tree-sitter
VS Code ExtensionTypeScript

Performance Considerations

  • Index: Uses SQLite FTS5 for fast text search
  • Memory: Indexed queries on session and file path
  • Scanning: Incremental updates based on file hash

Security

  • MCP server uses stdio (no network exposure by default)
  • No authentication required (local development tool)
  • No data transmitted externally
  • All data stored locally in .palace directory
Last updated on
EcosystemAutonomous Agent Guide