# Understanding the Architectural Relationship Between Wings, Rooms, and Drawers in MemPalace

> Explore the MemPalace architecture: discover how Wings, Rooms, and Drawers form a hierarchical tree for organizing your memory palace data efficiently.

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

---

**MemPalace implements a three-level hierarchical tree where Wings categorize broad domains, Rooms segment time-based sessions, and Drawers store immutable verbatim text chunks as metadata-tagged leaf nodes.**

MemPalace organizes user memory through a hierarchical architecture that mirrors the classical "**method of loci**" technique. This open-source system structures information through an architectural relationship between three distinct entities: **Wings**, **Rooms**, and **Drawers**. The hierarchy is implemented across the `MemPalace/mempalace` repository and stored within the vector database backend as metadata relationships rather than separate objects.

## The Three-Level Memory Hierarchy

The architectural design defines a directed tree structure that flows from broad categories down to atomic content units. This organization is documented in [`AGENTS.md`](https://github.com/MemPalace/mempalace/blob/main/AGENTS.md) and enforced throughout the codebase.

### Wings as Top-Level Categories

**Wings** represent the highest level of categorization within the MemPalace architecture. These broad containers typically separate distinct life domains such as people, projects, or general topics. According to the project design documentation, wings function as the primary taxonomic dividers that partition the memory palace into manageable sections.

### Rooms as Temporal Subdivisions

**Rooms** exist as subdivisions inside a wing, typically representing specific days, sessions, or sub-topics. This layer organizes chronologically or thematically related information within a single wing. The architectural design specifies that rooms group time-based or contextually similar memories before they reach the leaf storage level.

### Drawers as Verbatim Leaf Nodes

**Drawers** serve as the leaf nodes containing the actual immutable verbatim text chunks—the exact words supplied by the user. Unlike wings and rooms, which are purely organizational constructs, drawers represent the concrete data entities. Each drawer stores the full verbatim content supplied during capture, along with metadata tags identifying its parent wing and room.

## Metadata-Based Storage Implementation

The hierarchy exists only as metadata within the underlying vector store. By default, MemPalace uses **ChromaDB** as the storage backend, where each drawer document carries `wing` and `room` metadata fields. Higher-level nodes are never instantiated as separate database objects or tables; instead, the system aggregates drawers by scanning these metadata tags.

When a drawer is created, the `wing` and `room` parameters are attached as metadata fields, enabling fast aggregation queries without joins or foreign key lookups. The `tool_status` function in [`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py) builds hierarchical statistics by scanning the metadata of all drawers and counting occurrences per wing and room.

## Querying the Hierarchy Programmatically

The MCP server exposes read-only tools that traverse this relationship without requiring direct database access. These functions demonstrate how the architectural layers operate at runtime.

List all wings with their drawer counts using `tool_list_wings`:

```python
from mempalace.mcp_server import tool_list_wings

print(tool_list_wings())

# → {"wings": {"project": 123, "personal": 87, "unknown": 5}}

```

Filter rooms by a specific wing using `tool_list_rooms`:

```python
from mempalace.mcp_server import tool_list_rooms

print(tool_list_rooms(wing="project"))

# → {"wing": "project", "rooms": {"2023-07-01": 30, "2023-07-02": 28}}

```

Create new leaf nodes with `tool_add_drawer`, supplying the hierarchical tags as strings:

```python
from mempalace.mcp_server import tool_add_drawer

result = tool_add_drawer(
    content="Met with Alice about the new API design.",
    wing="project",
    room="2023-07-03",
)
print(result)  # contains the generated drawer ID and metadata

```

These examples illustrate that wings and rooms function as simple string taxonomies, while the system automatically organizes drawers beneath them through metadata indexing.

## Core Implementation Files

The architectural relationship is defined across several key files in the repository:

- [`AGENTS.md`](https://github.com/MemPalace/mempalace/blob/main/AGENTS.md) – Contains the high-level design overview defining wings as broad categories, rooms as time-based groupings, and drawers as verbatim content containers.
- [`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py) – Implements the MCP read-only tools including `tool_list_wings`, `tool_list_rooms`, and `tool_status` that expose the hierarchy to callers.
- [`mempalace/palace.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace.py) – Provides shared operations for accessing the storage backend where drawer metadata persistence occurs.
- [`mempalace/palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace_graph.py) – Contains graph utilities for traversing the wing → room → drawer relationships used by advanced queries and tunnel handling.

## Summary

- **Wings → Rooms → Drawers** forms a directed tree structure with drawers as leaf nodes and organizational layers existing only as metadata.
- **Wings** categorize broad domains (projects, people, topics), while **Rooms** segment by time or session, and **Drawers** contain immutable verbatim text.
- The hierarchy is implemented through metadata fields (`wing`, `room`) on vector store documents rather than separate database objects.
- Query tools in [`mempalace/mcp_server.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/mcp_server.py) aggregate drawers by scanning metadata to build per-wing and per-room statistics.
- All three levels are defined in [`AGENTS.md`](https://github.com/MemPalace/mempalace/blob/main/AGENTS.md) and enforced through the [`palace.py`](https://github.com/MemPalace/mempalace/blob/main/palace.py) and [`palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/palace_graph.py) modules.

## Frequently Asked Questions

### Are Wings and Rooms stored as separate database tables in MemPalace?

No. Wings and rooms exist purely as metadata tags attached to drawer documents in the vector store. When you create a drawer using `tool_add_drawer`, the system stores the `wing` and `room` strings as metadata fields on that document. Tools like `tool_list_wings` dynamically count drawers by aggregating these metadata tags, meaning the hierarchical parents are organizational constructs rather than independent data entities.

### How does the three-level architecture relate to the method of loci?

The architectural relationship directly implements the classical memory palace technique. **Wings** correspond to distinct wings of a physical palace, **Rooms** represent specific locations within those wings, and **Drawers** contain the detailed memories (verbatim text). This spatial metaphor helps users mentally navigate their stored information by mapping digital organization to physical spaces.

### Can a Drawer exist without being assigned to a Wing and Room?

The architecture requires drawers to specify both `wing` and `room` metadata during creation. When calling `tool_add_drawer`, both parameters are typically provided as strings, and the system stores the drawer with these metadata tags. While the underlying storage might technically allow orphaned records, the MemPalace tools and [`palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/palace_graph.py) utilities expect and enforce this three-level hierarchy for proper organization and retrieval.

### What backend technology stores the Wing-Room-Drawer relationships?

By default, MemPalace uses **ChromaDB** as the vector store backend, where drawer documents are indexed with `wing` and `room` metadata fields. The relationships are realized through metadata filtering and aggregation queries rather than foreign key relationships or graph edges. However, [`mempalace/palace_graph.py`](https://github.com/MemPalace/mempalace/blob/main/mempalace/palace_graph.py) provides graph utilities for traversing these relationships when more complex queries or tunnel handling is required.