# agentskills-manager/mempalace architecture

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

- Interactive diagram: https://gitdiagram.com/agentskills-manager/mempalace
- Repository: https://github.com/agentskills-manager/mempalace

## Overview

1. **What this repo is**
   - The checked-in code is a Python package named `mempalace`, which provides an AI memory / knowledge capture system: ingest text, extract entities, build a graph, and search it later.
   - The README frames it as an included “skill” inside a larger AgentSkill Manager, but the code tree itself is focused on the `mempalace` memory subsystem.

2. **Primary entry points**
   - `mempalace/__main__.py` and `mempalace/cli.py` are the user-facing runtime entry points.
   - `mempalace/mcp_server.py` exposes the same capability through an MCP-style server interface for agent/tool integrations.
   - This gives the package two access paths: direct local CLI use and programmatic agent access.

3. **Configuration and first-run setup**
   - `config.py` centralizes runtime settings.
   - `onboarding.py` likely handles initial setup, path discovery, and environment preparation.
   - These modules form the boundary between the package and the host machine / agent workspace.

4. **Ingestion layer**
   - `miner.py` is the generic ingestion pipeline.
   - `convo_miner.py` is a specialized miner for conversation-like inputs.
   - `room_detector_local.py` suggests local detection of conversation “rooms” or contextual partitions.
   - `split_mega_files.py` handles very large source files so downstream extraction can work on manageable chunks.

5. **Text cleanup and source adaptation**
   - `normalize.py` and `spellcheck.py` clean and standardize raw text before indexing.
   - `dialect.py` likely adapts parsing rules to different source formats or writing styles.
   - `layers.py` suggests an intermediate representation used to structure processed text before entity or graph extraction.

6. **Entity detection and canonicalization**
   - `entity_detector.py` identifies names, concepts, or other memory-worthy items in text.
   - `entity_registry.py` stores and deduplicates those entities so the same thing can be recognized across multiple inputs.
   - This is the main boundary between raw text processing and structured memory.

7. **Knowledge representation**
   - `knowledge_graph.py` is the core structured-memory layer where extracted facts and relationships are stored.
   - `palace_graph.py` appears to be a domain-specific graph wrapper or specialization around the same memory model.
   - Together they turn mined text into traversable relationships instead of flat documents.

8. **Retrieval and query**
   - `searcher.py` is the read path: it queries the stored memory/graph and returns relevant results.
   - In the architecture diagram, this is the consumer-facing retrieval layer that sits above the graph and registry.

9. **End-to-end data flow**
   - Input arrives through the CLI, MCP server, or mining modules.
   - Text is split/normalized, entities are detected and registered, then facts are inserted into the knowledge graph.
   - Search later reads from the same structured memory to answer queries or surface related context.

10. **Integration boundary**
   - There is no separate web app, database service, or frontend in the tree.
   - The package looks self-contained and local-first, with the main external integration point being the MCP server and the CLI.
   - `assets/` is only for documentation/branding, not core runtime behavior.

Main entry points: [`mempalace/miner.py`](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/miner.py) (Miner), [`mempalace/searcher.py`](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/searcher.py) (Searcher), [`mempalace/cli.py`](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/cli.py) (CLI), [`mempalace/entity_registry.py`](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/entity_registry.py) (Registry)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Interfaces"]
  node_mempalace__main__py(("Main entry<br/>package entry<br/>[__main__.py]"))
  node_cli["CLI<br/>command line<br/>[cli.py]"]
  node_mcp_server["MCP server<br/>agent server<br/>[mcp_server.py]"]
end

subgraph group_setup["Setup"]
  node_config["Config<br/>settings<br/>[config.py]"]
  node_onboarding["Onboarding<br/>setup<br/>[onboarding.py]"]
end

subgraph group_ingestion["Ingestion"]
  node_miner["Miner<br/>ingest pipeline<br/>[miner.py]"]
  node_convo_miner["Convo miner<br/>conversation ingest<br/>[convo_miner.py]"]
  node_room_detector_local{{"Room detector<br/>context split"}}
  node_split_mega_files["File splitter<br/>chunking"]
  node_normalize["Normalize<br/>text cleanup<br/>[normalize.py]"]
  node_spellcheck["Spellcheck<br/>text cleanup<br/>[spellcheck.py]"]
  node_dialect["Dialect<br/>source adapter<br/>[dialect.py]"]
  node_layers["Layers<br/>intermediate model<br/>[layers.py]"]
end

subgraph group_entity["Entities"]
  node_entity_detector{{"Entity detector<br/>entity extraction<br/>[entity_detector.py]"}}
  node_entity_registry[("Registry<br/>entity store<br/>[entity_registry.py]")]
end

subgraph group_knowledge["Knowledge"]
  node_general_extractor["Extractor"]
  node_knowledge_graph[("Knowledge graph<br/>graph store<br/>[knowledge_graph.py]")]
  node_palace_graph[("Palace graph<br/>domain graph<br/>[palace_graph.py]")]
  node_searcher["Searcher<br/>retrieval<br/>[searcher.py]"]
end

node_cli -->|"loads"| node_config
node_cli -->|"bootstraps"| node_onboarding
node_mempalace__main__py -->|"starts"| node_cli
node_mcp_server -->|"loads"| node_config
node_mcp_server -->|"serves"| node_searcher
node_miner -->|"chunks"| node_split_mega_files
node_miner -->|"cleans"| node_normalize
node_miner -->|"repairs"| node_spellcheck
node_miner -->|"adapts"| node_dialect
node_miner -->|"structures"| node_layers
node_convo_miner -->|"segments"| node_room_detector_local
node_convo_miner -->|"extends"| node_miner
node_layers -->|"feeds"| node_entity_detector
node_entity_detector -->|"dedupes"| node_entity_registry
node_entity_registry -->|"anchors"| node_general_extractor
node_general_extractor -->|"writes"| node_knowledge_graph
node_knowledge_graph -->|"wraps"| node_palace_graph
node_searcher -->|"queries"| node_knowledge_graph
node_searcher -->|"resolves"| node_entity_registry
node_onboarding -->|"initializes"| node_config

click node_mempalace__main__py "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/__main__.py"
click node_cli "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/cli.py"
click node_mcp_server "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/mcp_server.py"
click node_config "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/config.py"
click node_onboarding "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/onboarding.py"
click node_miner "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/miner.py"
click node_convo_miner "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/convo_miner.py"
click node_room_detector_local "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/room_detector_local.py"
click node_split_mega_files "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/split_mega_files.py"
click node_normalize "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/normalize.py"
click node_spellcheck "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/spellcheck.py"
click node_dialect "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/dialect.py"
click node_layers "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/layers.py"
click node_entity_detector "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/entity_detector.py"
click node_entity_registry "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/entity_registry.py"
click node_general_extractor "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/general_extractor.py"
click node_knowledge_graph "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/knowledge_graph.py"
click node_palace_graph "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/palace_graph.py"
click node_searcher "https://github.com/agentskills-manager/mempalace/blob/main/mempalace/searcher.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_mempalace__main__py,node_cli,node_mcp_server toneBlue
class node_config,node_onboarding toneAmber
class node_miner,node_convo_miner,node_room_detector_local,node_split_mega_files,node_normalize,node_spellcheck,node_dialect,node_layers toneMint
class node_entity_detector,node_entity_registry toneRose
class node_general_extractor,node_knowledge_graph,node_palace_graph,node_searcher toneIndigo
```

## Components

### Interfaces

User and agent entry points into the package

- [Main entry](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/__main__.py): package entry · Module entry for direct execution · `mempalace/__main__.py`
- [CLI](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/cli.py): command line · Local user-facing command interface · `mempalace/cli.py`
- [MCP server](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/mcp_server.py): agent server · Programmatic tool access for agents · `mempalace/mcp_server.py`

### Setup

Configuration and first-run environment preparation

- [Config](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/config.py): settings · Central runtime configuration · `mempalace/config.py`
- [Onboarding](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/onboarding.py): setup · First-run setup and environment prep · `mempalace/onboarding.py`

### Ingestion

Text intake, splitting, and cleanup

- [Miner](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/miner.py): ingest pipeline · Generic text ingestion pipeline · `mempalace/miner.py`
- [Convo miner](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/convo_miner.py): conversation ingest · Specialized ingestion for dialogue-like text · `mempalace/convo_miner.py`
- [Room detector](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/room_detector_local.py): context split · Locates local conversation or context partitions · `mempalace/room_detector_local.py`
- [File splitter](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/split_mega_files.py): chunking · Breaks very large files into manageable pieces · `mempalace/split_mega_files.py`
- [Normalize](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/normalize.py): text cleanup · Standardizes raw text before extraction · `mempalace/normalize.py`
- [Spellcheck](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/spellcheck.py): text cleanup · Repairs or smooths noisy text · `mempalace/spellcheck.py`
- [Dialect](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/dialect.py): source adapter · Adjusts parsing rules for source style or format · `mempalace/dialect.py`
- [Layers](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/layers.py): intermediate model · Structured representation between text and extraction · `mempalace/layers.py`

### Entities

Detection and canonicalization of memory-worthy concepts

- [Entity detector](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/entity_detector.py): entity extraction · Identifies names, concepts, and memory targets · `mempalace/entity_detector.py`
- [Registry](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/entity_registry.py): entity store · Deduplicates and tracks canonical entities · `mempalace/entity_registry.py`

### Knowledge

Structured graph storage and retrieval

- [Extractor](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/general_extractor.py): fact extractor · Derives structured facts and relations from text · `mempalace/general_extractor.py`
- [Knowledge graph](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/knowledge_graph.py): graph store · Core structured memory and relationship store · `mempalace/knowledge_graph.py`
- [Palace graph](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/palace_graph.py): domain graph · Domain-specific graph wrapper over memory model · `mempalace/palace_graph.py`
- [Searcher](https://github.com/agentskills-manager/mempalace/blob/main/mempalace/searcher.py): retrieval · Queries memory and returns relevant context · `mempalace/searcher.py`

## Connections

- CLI → Config: loads · CLI reads runtime settings
- CLI → Onboarding: bootstraps · CLI can trigger setup flow
- Main entry → CLI: starts · Module execution enters the CLI
- MCP server → Config: loads · Server uses shared configuration
- MCP server → Searcher: serves · Exposes retrieval over agent interface
- Miner → File splitter: chunks · Large inputs are split before processing
- Miner → Normalize: cleans · Text is normalized during ingestion
- Miner → Spellcheck: repairs · Noisy text is optionally corrected
- Miner → Dialect: adapts · Parsing is adjusted for source style
- Miner → Layers: structures · Creates an intermediate structured form
- Convo miner → Room detector: segments · Conversation input is partitioned by room/context
- Convo miner → Miner: extends · Conversation mining builds on the generic pipeline
- Layers → Entity detector: feeds · Structured text is prepared for entity detection
- Entity detector → Registry: dedupes · Detected entities are canonicalized in the registry
- Registry → Extractor: anchors · Canonical entities support fact extraction
- Extractor → Knowledge graph: writes · Extracted facts are stored in the graph
- Knowledge graph → Palace graph: wraps · Domain graph specializes the core graph model
- Searcher → Knowledge graph: queries · Retrieval reads from structured memory
- Searcher → Registry: resolves · Search uses entity canonicalization for lookup
- Onboarding → Config: initializes · Setup prepares configuration and paths
