Igor Lins e Silva
dfb22f5345
- 22 content pages across Guide, Concepts, and Reference sections - Custom indigo/cyan theme with Lucide icons and Mermaid diagrams - GitHub Actions workflow for GitHub Pages deployment - Live preview: https://mempalace-docs.netlify.app/
130 lines
5.5 KiB
Markdown
130 lines
5.5 KiB
Markdown
# Module Map
|
|
|
|
Complete source file reference for the MemPalace codebase.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
mempalace/
|
|
├── README.md ← project documentation
|
|
├── mempalace/ ← core package
|
|
│ ├── cli.py ← CLI entry point
|
|
│ ├── mcp_server.py ← MCP server (19 tools)
|
|
│ ├── knowledge_graph.py ← temporal entity graph
|
|
│ ├── palace_graph.py ← room navigation graph
|
|
│ ├── dialect.py ← AAAK compression
|
|
│ ├── miner.py ← project file ingest
|
|
│ ├── convo_miner.py ← conversation ingest
|
|
│ ├── searcher.py ← semantic search
|
|
│ ├── layers.py ← 4-layer memory stack
|
|
│ ├── onboarding.py ← guided setup
|
|
│ ├── config.py ← configuration loading
|
|
│ ├── normalize.py ← chat format converter
|
|
│ ├── entity_detector.py ← auto-detect people/projects
|
|
│ ├── entity_registry.py ← entity code registry
|
|
│ ├── room_detector_local.py ← room detection from directories
|
|
│ ├── general_extractor.py ← 5-type memory extraction
|
|
│ ├── split_mega_files.py ← transcript splitting
|
|
│ ├── spellcheck.py ← optional spell checking
|
|
│ ├── hooks_cli.py ← hook logic
|
|
│ ├── instructions_cli.py ← skill instructions
|
|
│ └── version.py ← version string
|
|
├── benchmarks/ ← reproducible benchmark runners
|
|
│ ├── BENCHMARKS.md ← full results + methodology
|
|
│ ├── longmemeval_bench.py ← LongMemEval runner
|
|
│ ├── locomo_bench.py ← LoCoMo runner
|
|
│ ├── membench_bench.py ← MemBench runner
|
|
│ └── convomem_bench.py ← ConvoMem runner
|
|
├── hooks/ ← Claude Code auto-save hooks
|
|
│ ├── mempal_save_hook.sh ← save every N messages
|
|
│ └── mempal_precompact_hook.sh ← emergency save
|
|
├── examples/ ← usage examples
|
|
│ ├── basic_mining.py
|
|
│ ├── convo_import.py
|
|
│ ├── mcp_setup.md
|
|
│ └── gemini_cli_setup.md
|
|
├── tests/ ← test suite
|
|
├── assets/ ← logo + brand
|
|
└── pyproject.toml ← package config
|
|
```
|
|
|
|
## Core Modules
|
|
|
|
### `cli.py` — CLI Entry Point
|
|
|
|
Argparse-based CLI with subcommands: `init`, `mine`, `split`, `search`, `compress`, `wake-up`, `repair`, `status`, `hook`, `instructions`. Dispatches to the corresponding module.
|
|
|
|
### `mcp_server.py` — MCP Server
|
|
|
|
JSON-RPC over stdin/stdout. Implements the MCP protocol with 19 tools covering palace read/write, knowledge graph, navigation, and agent diary operations. Includes the Memory Protocol and AAAK Spec in status responses.
|
|
|
|
### `searcher.py` — Semantic Search
|
|
|
|
Two functions: `search()` for CLI output and `search_memories()` for programmatic use. Both query ChromaDB with optional wing/room filters and return verbatim drawer content with similarity scores.
|
|
|
|
### `layers.py` — Memory Stack
|
|
|
|
Four classes (`Layer0` through `Layer3`) and the unified `MemoryStack`. Layer 0 reads identity, Layer 1 auto-generates from top drawers, Layer 2 does filtered retrieval, Layer 3 does semantic search.
|
|
|
|
### `knowledge_graph.py` — Temporal KG
|
|
|
|
SQLite-backed entity-relationship graph with temporal validity windows. Supports add, invalidate, query, timeline, and stats. Auto-creates entities on triple insertion.
|
|
|
|
### `palace_graph.py` — Navigation Graph
|
|
|
|
Builds a graph from ChromaDB metadata where nodes = rooms and edges = tunnels (rooms spanning multiple wings). Supports BFS traversal and tunnel finding.
|
|
|
|
### `dialect.py` — AAAK Compression
|
|
|
|
Lossy abbreviation system with entity encoding, emotion detection, topic extraction, and flag identification. Works on both plain text and structured zettel data.
|
|
|
|
## Ingest Modules
|
|
|
|
### `miner.py` — Project Ingest
|
|
|
|
Scans project directories for code and doc files. Respects `.gitignore`. Files content as drawers tagged with wing/room metadata.
|
|
|
|
### `convo_miner.py` — Conversation Ingest
|
|
|
|
Imports conversation exports (Claude, ChatGPT, Slack, Markdown, plaintext). Chunks by exchange pair. Supports `exchange` and `general` extraction modes.
|
|
|
|
### `normalize.py` — Format Converter
|
|
|
|
Converts 5 chat formats to a standard transcript format before mining.
|
|
|
|
### `general_extractor.py` — Memory Type Extraction
|
|
|
|
Classifies conversation content into decisions, preferences, milestones, problems, and emotional context.
|
|
|
|
## Detection Modules
|
|
|
|
### `entity_detector.py` — Entity Detection
|
|
|
|
Scans file content to auto-detect people and projects using regex patterns and heuristics.
|
|
|
|
### `entity_registry.py` — Entity Registry
|
|
|
|
Manages entity name → code mappings for AAAK dialect.
|
|
|
|
### `room_detector_local.py` — Room Detection
|
|
|
|
Detects rooms from folder structure during `mempalace init`.
|
|
|
|
## Utility Modules
|
|
|
|
### `config.py` — Configuration
|
|
|
|
Loads settings from `~/.mempalace/config.json` and environment variables.
|
|
|
|
### `split_mega_files.py` — Transcript Splitting
|
|
|
|
Splits concatenated transcripts into per-session files based on session boundary detection.
|
|
|
|
### `onboarding.py` — Guided Setup
|
|
|
|
Interactive setup wizard for `mempalace init`. Generates AAAK bootstrap and wing config.
|
|
|
|
### `spellcheck.py` — Spell Checking
|
|
|
|
Optional spell checking utility (requires `autocorrect` package).
|