MemPalace Setup Guide: Install & Configure in 5 Minutes

To install MemPalace, open your terminal and run the following command. This single line pulls in everything you need:

pip install mempalace

The command installs MemPalace along with its core dependencies:

• •ChromaDB— the vector database that powers semantic search across your memories. Stores embeddings locally, no cloud needed.
• •SQLite— lightweight relational storage for metadata, relationships, and the structural hierarchy of your palace.
• •Sentence Transformers (all-MiniLM-L6-v2)— a compact 384-dimensional embedding model that runs on CPU. Converts text into vectors for similarity search.

To initialize your palace, run the command below to create the directory structure that MemPalace uses to organise your memories:

mempalace init

This creates a .mempalace/ directory in your home folder with the following layout:

.mempalace/
├── palace.db          # SQLite metadata
├── chroma/            # Vector embeddings
└── wings/
    └── default/
        ├── hall_facts/
        ├── hall_events/
        ├── hall_discoveries/
        ├── hall_preferences/
        └── hall_advice/

Think of it like a real memory palace: Wings are top-level containers (one per person or project), Rooms are specific topics within a wing, and Halls are corridors that categorise memories by type. We cover the full architecture in the Core Concepts section below.

To connect MemPalace to Claude Code, add the MCP server configuration below to your Claude Code settings file (~/.claude.jsonor your project's .mcp.json):

{
  "mcpServers": {
    "mempalace": {
      "command": "mempalace",
      "args": ["mcp"]
    }
  }
}

That's it. Restart Claude Code and MemPalace will appear as an available MCP tool. Claude can now read, write, and search your memories automatically during conversations.

To connect MemPalace to other AI clients, follow the quick setup instructions below. MemPalace works with any MCP-compatible client:

To store your first memory, choose one of two methods: bulk import from conversation exports, or real-time storage through the MCP interface.

Option A: Import conversation history

Export your conversation history from Claude, ChatGPT, or any supported client, then run:

mempalace mine conversations ./path/to/export.json

MemPalace will parse the conversations, extract facts, events, preferences, and discoveries, then file each memory into the appropriate hall.

Option B: Through the MCP interface

Once connected, simply chat with your AI assistant. MemPalace automatically captures important information during your conversations. You can also explicitly ask your assistant to “remember” something:

You: "Remember that our production database is on us-east-1
      and the staging DB is on eu-west-2."

Claude: "Stored in hall_facts under the 'infrastructure' room."

To search your memories, query your palace from the command line or let your AI assistant search automatically.

CLI search

mempalace search "database configuration"

Returns semantically relevant memories ranked by similarity. You can filter by wing, room, or hall:

mempalace search "database config" --wing=work --hall=hall_facts

AI-assisted search

When connected via MCP, your AI assistant searches automatically whenever context is needed. You can also ask directly:

You: "What did we decide about the caching strategy last week?"

Claude: [searches palace] "On March 30 you decided to use Redis for
session cache and CloudFront for static assets. The TTL for sessions
is 4 hours. (Source: hall_events/infrastructure)"

Core Concepts

MemPalace borrows from the ancient method of loci— a mnemonic technique where you associate memories with physical locations in an imagined building. Here's how the metaphor maps to the system:

4-Layer Memory Stack

MemPalace uses a tiered retrieval system that balances context window efficiency with recall depth. Only the layers that are needed get loaded, keeping token usage minimal.

L0 and L1 are injected into every conversation automatically (<200 tokens total). L2 activates when the conversation topic matches a known room. L3 fires only when the user or AI explicitly requests a deep search. This design means MemPalace adds virtually zero overhead to normal conversations while providing perfect recall when needed.

Troubleshooting

Running into issues? Here are solutions to the most common problems:

# Windows PowerShell
$env:PYTHONIOENCODING = "utf-8"
mempalace init

python3 --version   # Should be 3.9+
pip3 install mempalace

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3-dev

# Then retry
pip install mempalace

which mempalace   # Should print a path
mempalace mcp     # Should start the MCP server

Frequently Asked Questions