# Understanding the Wing/Room/Drawer Palace Structure in MemPalace

> Learn the Wing Room Drawer palace structure in MemPalace. Master semantic search and navigation with this intuitive hierarchy for your memory palace.

- Repository: [MemPalace/mempalace](https://github.com/MemPalace/mempalace)
- Tags: internals
- Published: 2026-06-07

---

**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`](https://github.com/MemPalace/mempalace/blob/main/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`](https://github.com/MemPalace/mempalace/blob/main/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`](https://github.com/MemPalace/mempalace/blob/main/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:

   ```json
   {
     "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`](https://github.com/MemPalace/mempalace/blob/main/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:

```python
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`](https://github.com/MemPalace/mempalace/blob/main/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:

```python
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`](https://github.com/MemPalace/mempalace/blob/main/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:

```python
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`](https://github.com/MemPalace/mempalace/blob/main/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`](https://github.com/MemPalace/mempalace/blob/main/mempalace/onboarding.py), [`mempalace/palace.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace.py), and [`mempalace/palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/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`](https://github.com/MemPalace/mempalace/blob/main/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`](https://github.com/MemPalace/mempalace/blob/main/mempalace/onboarding.py) for Wing creation logic; [`mempalace/palace.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace.py) for low-level collection helpers and drawer storage; [`mempalace/miner.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/miner.py) for the Wing/Room assignment algorithm during ingestion; and [`mempalace/palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace_graph.py) for the Room graph and Hall/tunnel construction. For export functionality showing the full hierarchy, see [`mempalace/exporter.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/exporter.py).