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

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 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 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:

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:

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:

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 – 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 – 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 – Provides shared operations for accessing the storage backend where drawer metadata persistence occurs.
• 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 aggregate drawers by scanning metadata to build per-wing and per-room statistics.
• All three levels are defined in AGENTS.md and enforced through the palace.py and 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 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 provides graph utilities for traversing these relationships when more complex queries or tunnel handling is required.

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