mempalace

Organizes persistent AI memory using a five-level spatial hierarchy (Wing → Room → Hall → Tunnel → Drawer) derived from the Method of Loci, enabling structured navigation and metadata filtering beyond flat vector search. Wings represent high-level entities (projects/people), Rooms are topic domains, Halls connect rooms within wings, Tunnels cross-reference related rooms across wings, and Drawers store verbatim text chunks. This metaphorical structure maps directly to ChromaDB vector storage and SQLite knowledge graph, allowing both semantic retrieval and relational fact tracking.

Stores raw, uncompressed conversation and code text chunks (Drawers) in ChromaDB vector store while preserving original formatting and reasoning context. Unlike summarization-based systems that lose critical decision rationale, MemPalace indexes full text with embeddings for semantic retrieval while maintaining the complete original source. Each Drawer is a verbatim chunk with metadata tags (Wing, Room, timestamp, source) enabling both vector similarity search and metadata filtering.

Provides command-line interface (mempalace/cli.py) for all palace operations: initialization, mining, search, memory management, and configuration. CLI supports interactive onboarding flow for first-time setup, guided room/wing assignment during mining, and batch operations for large-scale ingestion. Configuration is stored in YAML/JSON files enabling reproducible palace setups and version control of memory schemas.

Includes built-in benchmarking suite (tests/test_*.py, benchmarks/) that evaluates memory recall performance using LongMemEval metrics (R@5, R@10, etc.). Benchmarks measure retrieval accuracy on standardized test sets, enabling performance comparison across embedding models, compression levels, and hierarchy configurations. MemPalace achieves 96.6% R@5 on LongMemEval, operating entirely on-device without external APIs.

Operates entirely on-device using local ChromaDB and SQLite backends, with no external API calls for embeddings, storage, or inference. Embedding models can be local (e.g., sentence-transformers) or cloud-based (OpenAI, Anthropic), but the system functions without them. This architecture enables offline operation, data privacy (no data leaves the device), and cost efficiency (no per-query API charges).

Normalizes conversation exports from multiple platforms (Claude, ChatGPT, Slack) into unified internal format via convo_miner.py and normalize.py. Handles variations in speaker identification, timestamp formats, message structure, and metadata across platforms. Normalized conversations are then chunked, embedded, and stored as Drawers with consistent metadata (author, timestamp, source platform).

Enables context retrieval scoped to specific hierarchy levels (Wing, Room, Hall) with optional cross-wing tunnel traversal for related content. Queries can be constrained to a single Wing (project) for focused context, or expanded across Wings via Tunnels (cross-project connections) for broader reasoning. This enables both narrow, focused context retrieval and broad, multi-project reasoning without requiring separate queries.

Manages palace configuration (storage paths, embedding models, entity definitions, room routing rules) via YAML/JSON files with schema validation. Configuration is versioned and can be stored in version control, enabling reproducible palace setups and team collaboration. Supports environment variable substitution for sensitive values (API keys, database paths).

Defines plugin manifests that enable AI clients (Claude, custom agents) to discover and integrate MemPalace tools without manual configuration. Manifests specify tool names, parameters, descriptions, and integration points, following MCP standards. This enables one-click integration with compatible AI clients.

Implements a dual-storage architecture combining ChromaDB (vector store for semantic text retrieval) and SQLite knowledge graph (for temporal entity-relationship triples). The vector backend indexes Drawer text chunks for similarity search, while the knowledge graph stores Subject-Predicate-Object triples with timestamps to track facts and relationships over time. This separation allows semantic queries ('find discussions about authentication') to coexist with relational queries ('what decisions were made about authentication in Q3?') without forcing either into the other's paradigm.

Automatically ingests data from two sources: local project directories (code, docs, notes via miner.py) and chat exports (Claude, ChatGPT, Slack via convo_miner.py). The system normalizes diverse transcript formats into a unified internal representation using normalize.py, handling variations in speaker identification, timestamps, and message structure. Mined data is then chunked, embedded, and stored in the palace hierarchy with automatic or guided room/wing assignment.

Exposes MemPalace functionality as a Model Context Protocol (MCP) server with 19 specialized tools for search, retrieval, storage, and maintenance operations. Tools are organized by function (search_palace, retrieve_drawer, add_memory, etc.) and accept structured parameters with validation. The MCP server enables any MCP-compatible AI client (Claude, custom agents) to interact with the memory system without direct Python imports, supporting both synchronous and asynchronous tool invocation.

Performs vector similarity search on Drawer text chunks using ChromaDB embeddings, with optional metadata filtering (Wing, Room, timestamp, source) and hierarchy scoping. Search can be constrained to a specific Wing (project) or Room (topic) before vector search, reducing irrelevant results. Results are ranked by cosine similarity and returned with full metadata, enabling LLMs to understand context (project, topic, time period) alongside semantic relevance.

Stores and queries Subject-Predicate-Object triples with timestamps in SQLite knowledge graph, enabling temporal reasoning about facts and relationships. Triples are extracted from ingested text (via heuristic or manual definition) and stored with creation/modification timestamps. Supports temporal queries ('what was the state of X on date Y?') and relationship traversal ('what entities are connected to X?'). The knowledge graph operates independently from vector search, allowing relational reasoning without semantic similarity.

Implements AAAK (Adaptive Archival Annotation Kompression) dialect for compressing memory records with configurable compression levels and auto-save hooks that trigger on file changes. The dialect supports lossless compression of verbatim text while preserving metadata, reducing storage overhead. Auto-save hooks (shell scripts or Python CLI) monitor project directories and automatically ingest changes into the palace, enabling continuous memory updates without manual mining.

Provides maintenance tools for identifying and removing duplicate memory records (exact text matches, near-duplicates via embedding similarity), repairing corrupted records, and migrating data between storage backends. Deduplication operates on both vector store (ChromaDB) and knowledge graph (SQLite), identifying duplicates via text hashing and embedding similarity. Repair operations validate record integrity, fix malformed metadata, and rebuild indexes.

Automatically detects entities (people, projects, concepts) in ingested text and maintains a registry mapping entities to palace locations (Wings/Rooms). Room detection and routing heuristics assign new entities to appropriate Wings/Rooms based on context and existing entity mappings. The entity registry enables cross-reference resolution ('when we talk about X, which project/room does it belong to?') and automatic room assignment during ingestion.