# milla-jovovich/mempalace architecture

> Architecture diagram of the GitHub repository milla-jovovich/mempalace, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/milla-jovovich/mempalace
- Repository: https://github.com/milla-jovovich/mempalace

## Overview

1. **Repository purpose**
   MemPalace is a local-first Python memory system for AI conversations and project context. The core idea is to ingest raw files, turn them into searchable “drawers,” organize them into a palace taxonomy, and expose retrieval both through a CLI and an MCP server for agent integrations.

2. **Top-level subsystems**
   The architecture splits into four main runtime paths:
   - **Ingestion and mining** for project files and conversation exports
   - **Organization and retrieval** via palace/room indexing and semantic search
   - **Structured memory** via a temporal knowledge graph
   - **Integration surface** through CLI, MCP tools, onboarding, and hooks

3. **Ingestion pipeline**
   `miner.py` handles project-file mining, while `convo_miner.py` handles chat transcripts and chunks them into exchange-level units. `normalize.py` converts multiple chat formats into a common transcript shape, and `split_mega_files.py` pre-processes oversized export files into per-session pieces before mining. The data flow is: raw source files → normalized transcript/chunks → extracted memories and metadata → stored palace/graph records.

4. **Palace model and retrieval boundary**
   `palace_graph.py` appears to manage the navigational structure described in the README: wings, rooms, halls, tunnels, and drawer locations. This is the primary architectural boundary for search and browsing. It lets the system narrow retrieval by domain before doing deeper semantic lookup, which is why wing/room filters materially improve recall.

5. **Semantic search layer**
   `searcher.py` is the search entry point exposed in both the CLI and Python API. The README indicates ChromaDB-backed local vector search, so the retrieval layer likely combines embedded drawer content with wing/room metadata to support filtered semantic search. This is the main query path for “what did we decide about X?”-style questions.

6. **Knowledge graph layer**
   `knowledge_graph.py` stores temporal entity-relationship triples with validity windows, current-state queries, historical queries, and invalidation. This is a separate structured-memory subsystem from vector search: it models facts, assignments, decisions, and timelines rather than free-text recall. The README explicitly describes SQLite as the local backing store, which makes this a durable, offline graph boundary.

7. **AAAK compression and memory layers**
   `dialect.py` implements the AAAK shorthand described in the README, and `layers.py` defines the L0–L3 memory stack used for wake-up, critical facts, and deeper retrieval. These components are the compression and presentation boundary: they turn stored memories into compact context for models while preserving the underlying verbatim source in drawers.

8. **Entity detection and registry**
   `entity_detector.py` and `entity_registry.py` support automatic identification and consistent labeling of people/projects/topics. These are the glue between unstructured text and the palace/graph model, helping route content into the correct wing, room, or entity code. `general_extractor.py` likely provides broader classification for general memories such as decisions, milestones, and preferences.

9. **User-facing interfaces**
   `cli.py` and `__main__.py` provide the command-line entry point for init, mine, search, wake-up, compress, split, and status flows. `mcp_server.py` is the agent-facing integration boundary, exposing the repository’s functionality as MCP tools so Claude/Cursor/other compatible clients can call search, graph queries, and diary operations without manual CLI use.

10. **Setup, configuration, and onboarding**
   `config.py` loads global config, palace path, and entity mappings; `onboarding.py` generates the initial palace bootstrap and wing configuration. The repository is designed so the first-run experience creates the local memory world, after which mining and retrieval are repeatable and offline.

11. **Extensions and automation**
   The `hooks/` directory contains Claude Code save/precompact hooks, which automate periodic memory capture and emergency saves before context truncation. `examples/` demonstrates project mining, convo import, and MCP setup, showing how the system is meant to be embedded into existing workflows rather than used as a standalone app.

12. **Validation and reproducibility**
   `tests/` covers configuration, normalization, mining, and conversation ingestion, which are the highest-risk transformation boundaries in the system. `benchmarks/` contains reproducible runners and methodology for LongMemEval, LoCoMo, and related evaluations, indicating that retrieval quality is a core architectural concern, not just a utility feature.

13. **Operational profile**
   This is a pure local Python package with no mandatory cloud dependency. The runtime stack is centered on Python 3.9+, local storage/indexes, and offline retrieval, with external services only appearing as optional model clients or MCP consumers on the edge of the system. The main architectural promise is that raw data stays local while the system adds structure, compression, and searchability around it.

Main entry points: [`mempalace/cli.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/cli.py) (CLI), [`mempalace/miner.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/miner.py) (Miner), [`mempalace/searcher.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/searcher.py) (Searcher), [`mempalace/knowledge_graph.py`](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/knowledge_graph.py) (Knowledge Graph)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Ingestion"]
  node_miner["Miner<br/>ingest pipeline<br/>[miner.py]"]
  node_convo_miner["Convo Miner<br/>chat ingest<br/>[convo_miner.py]"]
  node_normalize["Normalize<br/>transcript adapter<br/>[normalize.py]"]
  node_split_mega_files["Split Files<br/>export splitter"]
end

subgraph group_palace["Palace Retrieval"]
  node_palace_graph{{"Palace Graph<br/>taxonomy index<br/>[palace_graph.py]"}}
  node_searcher["Searcher<br/>semantic search<br/>[searcher.py]"]
  node_room_detector_local["Room Detector<br/>routing helper"]
end

subgraph group_graph["Knowledge Graph"]
  node_knowledge_graph[("Knowledge Graph<br/>temporal graph<br/>[knowledge_graph.py]")]
end

subgraph group_interface["Interfaces"]
  node_onboarding["Onboarding<br/>bootstrap setup<br/>[onboarding.py]"]
  node_cli["CLI<br/>command entry<br/>[cli.py]"]
  node_main(("__main__<br/>entrypoint<br/>[__main__.py]"))
  node_mcp_server["MCP Server<br/>tool server<br/>[mcp_server.py]"]
end

subgraph group_support["Support"]
  node_dialect["AAAK Dialect<br/>compression format<br/>[dialect.py]"]
  node_layers["Memory Layers<br/>context stack<br/>[layers.py]"]
  node_entity_detector["Entity Detector<br/>entity extraction<br/>[entity_detector.py]"]
  node_entity_registry["Entity Registry<br/>entity map<br/>[entity_registry.py]"]
  node_general_extractor["General Extractor<br/>memory classifier"]
  node_config["Config<br/>[config.py]"]
end

node_split_mega_files -->|"prepares"| node_normalize
node_normalize -->|"feeds"| node_convo_miner
node_convo_miner -->|"supplies"| node_miner
node_miner -->|"indexes"| node_palace_graph
node_miner -->|"writes facts"| node_knowledge_graph
node_room_detector_local -->|"routes"| node_palace_graph
node_palace_graph -->|"filters"| node_searcher
node_searcher -->|"returns context"| node_layers
node_dialect -->|"compresses"| node_layers
node_entity_detector -->|"normalizes"| node_entity_registry
node_entity_registry -->|"anchors"| node_knowledge_graph
node_general_extractor -->|"classifies"| node_miner
node_config -->|"configures"| node_onboarding
node_config -->|"loads"| node_cli
node_onboarding -->|"bootstraps"| node_cli
node_cli -->|"invokes"| node_miner
node_cli -->|"queries"| node_searcher
node_cli -->|"queries"| node_knowledge_graph
node_main -->|"dispatches"| node_cli
node_mcp_server -->|"exposes"| node_searcher
node_mcp_server -->|"exposes"| node_knowledge_graph

click node_miner "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/miner.py"
click node_convo_miner "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/convo_miner.py"
click node_normalize "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/normalize.py"
click node_split_mega_files "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/split_mega_files.py"
click node_palace_graph "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/palace_graph.py"
click node_searcher "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/searcher.py"
click node_room_detector_local "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/room_detector_local.py"
click node_knowledge_graph "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/knowledge_graph.py"
click node_dialect "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/dialect.py"
click node_layers "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/layers.py"
click node_entity_detector "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/entity_detector.py"
click node_entity_registry "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/entity_registry.py"
click node_general_extractor "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/general_extractor.py"
click node_config "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/config.py"
click node_onboarding "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/onboarding.py"
click node_cli "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/cli.py"
click node_main "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/__main__.py"
click node_mcp_server "https://github.com/milla-jovovich/mempalace/blob/main/mempalace/mcp_server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_miner,node_convo_miner,node_normalize,node_split_mega_files toneBlue
class node_palace_graph,node_searcher,node_room_detector_local toneAmber
class node_knowledge_graph toneMint
class node_onboarding,node_cli,node_main,node_mcp_server toneRose
class node_dialect,node_layers,node_entity_detector,node_entity_registry,node_general_extractor,node_config toneIndigo
```

## Components

### Ingestion

Raw files and chat exports are normalized, mined, and split into memory units.

- [Miner](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/miner.py): ingest pipeline · Extracts memories from project files and source content. · `mempalace/miner.py`
- [Convo Miner](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/convo_miner.py): chat ingest · Processes conversation exports into chunked exchange units. · `mempalace/convo_miner.py`
- [Normalize](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/normalize.py): transcript adapter · Converts multiple chat formats into a common transcript shape. · `mempalace/normalize.py`
- [Split Files](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/split_mega_files.py): export splitter · Breaks oversized conversation exports into per-session pieces. · `mempalace/split_mega_files.py`

### Palace Retrieval

Palace taxonomy and semantic search for browsing and recall.

- [Palace Graph](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/palace_graph.py): taxonomy index · Manages wings, rooms, halls, tunnels, and drawer locations. · `mempalace/palace_graph.py`
- [Searcher](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/searcher.py): semantic search · Entry point for filtered local retrieval over embedded drawers. · `mempalace/searcher.py`
- [Room Detector](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/room_detector_local.py): routing helper · Locates likely wing and room boundaries for mined content. · `mempalace/room_detector_local.py`

### Knowledge Graph

Temporal structured memory for entities, facts, and history.

- [Knowledge Graph](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/knowledge_graph.py): temporal graph · Stores entities, relations, validity windows, and historical state. · `mempalace/knowledge_graph.py`

### Interfaces

CLI, MCP, onboarding, and automation entry points.

- [Onboarding](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/onboarding.py): bootstrap setup · Creates the initial palace and wing configuration. · `mempalace/onboarding.py`
- [CLI](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/cli.py): command entry · Main command-line interface for init, mine, search, and status. · `mempalace/cli.py`
- [__main__](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/__main__.py): entrypoint · Package entrypoint that dispatches to the CLI. · `mempalace/__main__.py`
- [MCP Server](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/mcp_server.py): tool server · Exposes search and memory operations to agent clients. · `mempalace/mcp_server.py`

### Support

Configuration, compression, entity routing, and general extraction.

- [AAAK Dialect](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/dialect.py): compression format · Encodes compact memory shorthand for model context. · `mempalace/dialect.py`
- [Memory Layers](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/layers.py): context stack · Defines the L0-L3 memory stack for wake-up and deeper retrieval. · `mempalace/layers.py`
- [Entity Detector](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/entity_detector.py): entity extraction · Identifies people, projects, and topics in text. · `mempalace/entity_detector.py`
- [Entity Registry](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/entity_registry.py): entity map · Maintains consistent labels and codes for recognized entities. · `mempalace/entity_registry.py`
- [General Extractor](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/general_extractor.py): memory classifier · Classifies decisions, milestones, preferences, and other general memories. · `mempalace/general_extractor.py`
- [Config](https://github.com/milla-jovovich/mempalace/blob/main/mempalace/config.py): runtime config · Loads local paths, settings, and entity mappings. · `mempalace/config.py`

## Connections

- Split Files → Normalize: prepares · Large exports are split before transcript normalization.
- Normalize → Convo Miner: feeds · Normalized transcripts are chunked into mineable conversation units.
- Convo Miner → Miner: supplies · Conversation-derived units enter the mining pipeline.
- Miner → Palace Graph: indexes · Mined memories are placed into the palace taxonomy.
- Miner → Knowledge Graph: writes facts · Structured entities and relations are stored in the temporal graph.
- Room Detector → Palace Graph: routes · Detected rooms and wings guide retrieval placement.
- Palace Graph → Searcher: filters · Palace metadata narrows semantic search scope.
- Searcher → Memory Layers: returns context · Search results are compressed into layered memory context.
- AAAK Dialect → Memory Layers: compresses · AAAK shorthand provides compact presentation of memories.
- Entity Detector → Entity Registry: normalizes · Detected entities are mapped to stable registry labels.
- Entity Registry → Knowledge Graph: anchors · Entity identities anchor graph facts over time.
- General Extractor → Miner: classifies · General memory types are extracted during mining.
- Config → Onboarding: configures · Bootstrap uses config to create the local memory world.
- Config → CLI: loads · CLI commands operate against the configured local store.
- Onboarding → CLI: bootstraps · Initial setup is initiated through the command surface.
- CLI → Miner: invokes · The CLI runs mining workflows.
- CLI → Searcher: queries · The CLI exposes retrieval entry points.
- CLI → Knowledge Graph: queries · The CLI can inspect structured memory state.
- __main__ → CLI: dispatches · Package execution forwards to the CLI.
- MCP Server → Searcher: exposes · Agent tools wrap semantic search.
- MCP Server → Knowledge Graph: exposes · Agent tools wrap graph queries and updates.
