Understanding the Wing/Room/Drawer Palace Structure in MemPalace

MemPalace organizes every memory chunk into a three-level hierarchy—Wings (categories), Rooms (groupings), and Drawers (verbatim text)—enabling fast semantic search and cross-topic navigation through the method of loci.

The open-source MemPalace project implements a digital method of loci through a strict Wing/Room/Drawer palace structure that governs how all user data is stored, indexed, and retrieved. This architecture ensures verbatim preservation of source material while providing lightweight graph-based navigation across conceptual boundaries. Every component—from the initialization wizard to the graph traversal engine—operates within this three-tier framework defined in the MemPalace/mempalace repository.

The Three Levels of the Memory Palace Hierarchy

MemPalace stores every piece of user data verbatim inside a three-level hierarchy that mirrors the ancient memory palace technique.

Wings – Top-Level Categories

Wings represent the highest level of organization—broad categories such as project names, people, or topics. During the init command, the interactive wizard defined in mempalace/onboarding.py prompts users for a comma-separated list of Wings, normalizing them (converting hyphens to underscores) before writing them to ~/.mempalace/config.json. These serve as the primary namespaces that partition your knowledge base into distinct cognitive realms.

Rooms – Temporal or Topical Groupings

Rooms function as time-based or topical containers within a Wing, analogous to "day/session" or "topic block" divisions. The metadata attached to each drawer contains a mandatory room field derived from file timestamps or front-matter dates during the mining process. According to the source in mempalace/palace_graph.py (lines 35-42), the graph builder reads these room identifiers from ChromaDB metadata to construct the navigable structure.

Drawers – Immutable Verbatim Chunks

Drawers are the leaf nodes containing the actual verbatim text—transcript lines, code snippets, or notes. Stored as documents in the main Chroma collection via mempalace/palace.py (lines 72-84), each drawer's metadata records its parent wing, room, and optional hall (cross-wing tunnel). Drawers are never altered after creation, serving as the immutable foundation that preserves exact user text.

How the Hierarchy is Built in Code

The construction of the Wing/Room/Drawer palace structure follows a deterministic pipeline from initialization to graph generation.

1. init prompts the user for Wings and persists them to the palace configuration.

2. Mining (mempalace mine …) parses source files, determines the target wing (falling back to directory name) and room (from timestamps or front-matter), then creates drawer metadata:

   {
     "wing": "<wing_slug>",
     "room": "<room_name>",
     "hall": "<optional_cross_wing_tunnel>",
     "source_file": "...",
     "normalize_version": 2
   }

3. palace_graph.build_graph() walks the Chroma collection after mining, aggregating drawer metadata to produce a graph where:

   • Nodes = rooms, annotated with the set of wings containing that room, connecting halls, and drawer counts.
   • Edges = "tunnels" (cross-wing connections) derived from rooms appearing in multiple wings (lines 50-66 in mempalace/palace_graph.py).

Querying the Wing/Room/Drawer Structure

Understanding the storage contract allows direct interaction with the palace layers through the Python API.

Listing Rooms by Wing

To retrieve all rooms belonging to a specific wing, use the cached graph structure:

from mempalace.palace_graph import build_graph

# Obtain the cached graph (or rebuild if stale)

nodes, _ = build_graph()

# Filter rooms that belong to the desired wing

def rooms_for_wing(wing: str) -> list[str]:
    return [room for room, info in nodes.items() if wing in info["wings"]]

print(rooms_for_wing("my_project"))

The build_graph function (lines 18-24 in mempalace/palace_graph.py) reads drawer metadata and returns a dictionary where each room entry contains a wings set for O(1) membership testing.

Retrieving Drawers from a Specific Room

Access verbatim content through the collection interface:

from mempalace.palace import get_collection
from mempalace.config import MempalaceConfig

cfg = MempalaceConfig()
col = get_collection(cfg.palace_path, collection_name=cfg.collection_name)

room_name = "2024-06-07"
results = col.get(where={"room": room_name}, include=["documents", "metadatas"])
drawers = results["documents"]    # verbatim text blobs

metadata = results["metadatas"]   # wing, date, etc.

for doc, meta in zip(drawers, metadata):
    print(f"[{meta['wing']}] {doc[:120]}…")

The get_collection wrapper (lines 73-82 in mempalace/palace.py) resolves the backend (default Chroma) and returns a collection object respecting the palace metadata contract.

Navigating Cross-Wing Connections with Halls

Halls (or tunnels) enable cross-wing reasoning by linking rooms that appear in multiple wings. Traverse these connections using:

from mempalace.palace_graph import traverse

paths = traverse(start_room="my_note_2024-06-07", max_hops=3)
for p in paths:
    print(f"{p['room']} (via {p['hall']}) → hop {p['hop_distance']}")

The traverse function (lines 89-95 in mempalace/palace_graph.py) performs a breadth-first walk limited by max_hops, utilizing the cached graph to answer "what topics bridge Wing A and Wing B?" without scanning individual drawers (lines 150-167).

Why This Architecture Matters

The three-tier design delivers specific performance and semantic guarantees:

• Verbatim guarantee – Drawers remain immutable leaf nodes, preserving exact user text without normalization or alteration.
• Fast lookup – Rooms serve as the primary index for semantic search; the graph caches relationships for O(1) cross-wing lookups.
• Cross-wing reasoning – Halls (tunnels) let the system identify conceptual bridges between wings without expensive full-text scans.

Summary

• The Wing/Room/Drawer palace structure in MemPalace categorizes data into Wings (projects/topics), Rooms (sessions/dates), and Drawers (immutable text chunks).
• Source files mempalace/onboarding.py, mempalace/palace.py, and mempalace/palace_graph.py handle initialization, storage, and graph navigation respectively.
• Metadata fields wing, room, and hall attached to each drawer enable hierarchical filtering and cross-wing traversal.
• Graph caching via build_graph() converts the flat Chroma collection into a navigable room-to-room structure with tunnel edges.

Frequently Asked Questions

What is the difference between a Wing and a Room in MemPalace?

Wings are top-level categorical namespaces (like "Project-A" or "Research") defined during init and stored in ~/.mempalace/config.json. Rooms are sub-groupings within a Wing—typically temporal (dates) or topical—assigned during the mining process. While a Wing represents "where" knowledge belongs conceptually, a Room represents "when" or "in what context" it was captured.

How does MemPalace ensure text remains immutable at the Drawer level?

Drawers are stored as raw document strings in the ChromaDB collection with a strict write-once policy enforced by the mining pipeline in mempalace/miner.py. The normalize_version field in metadata tracks processing stages, but the documents array returned by col.get() always contains the verbatim original text as ingested, ensuring no subsequent transformation alters the source material.

What is a "Hall" and how does it enable cross-wing navigation?

A Hall (also called a tunnel) is a metadata tag indicating that a specific drawer serves as a bridge between multiple Wings. When palace_graph.build_graph() detects the same Room name appearing in different Wings, it creates a tunnel edge. The traverse() function uses these edges to perform breadth-first searches across the palace, allowing queries to hop from one Wing to another via shared conceptual Rooms without scanning every drawer.

Which source files should I examine to understand the palace hierarchy implementation?

Key files include: mempalace/onboarding.py for Wing creation logic; mempalace/palace.py for low-level collection helpers and drawer storage; mempalace/miner.py for the Wing/Room assignment algorithm during ingestion; and mempalace/palace_graph.py for the Room graph and Hall/tunnel construction. For export functionality showing the full hierarchy, see mempalace/exporter.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}