How agentskills-manager/mempalace works
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: miner.py Miner · searcher.py Searcher · cli.py CLI · entity_registry.py Registry
Components 19
Interfaces
User and agent entry points into the package
- Main entry · Module entry for direct execution
mempalace/__main__.py - CLI · Local user-facing command interface
mempalace/cli.py - MCP server · Programmatic tool access for agents
mempalace/mcp_server.py
Setup
Configuration and first-run environment preparation
- Config · Central runtime configuration
mempalace/config.py - Onboarding · First-run setup and environment prep
mempalace/onboarding.py
Ingestion
Text intake, splitting, and cleanup
- Miner · Generic text ingestion pipeline
mempalace/miner.py - Convo miner · Specialized ingestion for dialogue-like text
mempalace/convo_miner.py - Room detector · Locates local conversation or context partitions
mempalace/room_detector_local.py - File splitter · Breaks very large files into manageable pieces
mempalace/split_mega_files.py - Normalize · Standardizes raw text before extraction
mempalace/normalize.py - Spellcheck · Repairs or smooths noisy text
mempalace/spellcheck.py - Dialect · Adjusts parsing rules for source style or format
mempalace/dialect.py - Layers · Structured representation between text and extraction
mempalace/layers.py
Entities
Detection and canonicalization of memory-worthy concepts
- Entity detector · Identifies names, concepts, and memory targets
mempalace/entity_detector.py - Registry · Deduplicates and tracks canonical entities
mempalace/entity_registry.py
Knowledge
Structured graph storage and retrieval
- Extractor · Derives structured facts and relations from text
mempalace/general_extractor.py - Knowledge graph · Core structured memory and relationship store
mempalace/knowledge_graph.py - Palace graph · Domain-specific graph wrapper over memory model
mempalace/palace_graph.py - Searcher · Queries memory and returns relevant context
mempalace/searcher.py
Connections 20
- 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