mempalace

Give your AI a memory. No API key required.

A structured, persistent memory system for AI agents — featuring a palace metaphor (wings → rooms → drawers), a temporal knowledge graph, the AAAK compression dialect, and a 4-layer memory stack.

This is a Bun/TypeScript port of the original mempalace by milla-jovovich.

OpenCode users: See opencode-mempalace for plug-and-play integration.

Requirements

• Bun ≥ 1.0
• ChromaDB server running

Install

npm install @nguyentamdat/mempalace
# or
git clone https://github.com/nguyentamdat/mempalace-js.git
cd mempalace-js
bun install

Setup

1. Start ChromaDB

# Docker (recommended)
docker run -d --name chromadb -p 127.0.0.1:8001:8000 \
  -v chromadb-data:/chroma/chroma --restart unless-stopped \
  chromadb/chroma:latest

# Or pip
pip install chromadb
chroma run --port 8001

2. Configure

The default ChromaDB URL is http://localhost:8000. Override via environment variable or config:

# Environment variable
export CHROMA_URL=http://localhost:8001

# Or in ~/.mempalace/config.json
{
  "chroma_url": "http://localhost:8001",
  "palace_path": "~/.mempalace/palace",
  "collection_name": "mempalace_drawers",
  "topic_wings": ["work", "personal", "technical", "creative"]
}

3. Initialize

bun run src/index.ts init /path/to/project

Usage

CLI

# Mine project files into the palace
bun run src/index.ts mine --mode projects --path ./my-project

# Mine conversation transcripts
bun run src/index.ts mine --mode convos --path ./transcripts

# Search memories
bun run src/index.ts search "some query"

# Compress memories with AAAK dialect (~30x reduction)
bun run src/index.ts compress

# Load memory layers (wake-up)
bun run src/index.ts wake-up

# Split mega transcript files
bun run src/index.ts split --path ./mega-file.txt

# Palace status
bun run src/index.ts status

MCP Server

Run as a JSON-RPC MCP server over stdin/stdout (19 tools):

CHROMA_URL=http://localhost:8001 bun run src/mcp-server.ts

Tools: mempalace_search, mempalace_kg_query, mempalace_kg_timeline, mempalace_kg_add, mempalace_kg_invalidate, mempalace_diary_write, mempalace_diary_read, mempalace_status, mempalace_list_wings, mempalace_list_rooms, mempalace_get_taxonomy, mempalace_add_drawer, mempalace_delete_drawer, mempalace_check_duplicate, mempalace_traverse, mempalace_find_tunnels, mempalace_graph_stats, mempalace_get_aaak_spec.

Architecture

Palace Structure

~/.mempalace/
├── palace/           (ChromaDB collection data reference)
├── config.json       (palace configuration)
├── entity_registry.json
├── identity.txt      (Layer 0 — who am I)
└── knowledge_graph.db (SQLite)

Palace (in ChromaDB)
├── Wings (top-level categories: work, personal, technical, etc.)
│   └── Rooms (specific topics within a wing)
│       └── Drawers (individual memories with metadata)
├── Diary wing (per-agent daily entries)
└── Embeddings (DefaultEmbeddingFunction)

Memory Layers

| Layer | Content | Size | |-------|---------|------| | Layer 0 | identity.txt — who am I | ~100 tokens | | Layer 1 | Auto-generated from top drawers | ~500-800 tokens | | Layer 2 | On-demand wing/room filtered | Variable | | Layer 3 | Deep semantic search | Variable |

AAAK Compression Dialect

A compact encoding format for memories that reduces token usage ~30x while preserving meaning. Uses 3-letter entity codes, emotion markers, pipe-separated fields, and importance stars (★–★★★★★).

Knowledge Graph

SQLite-based temporal entity-relationship graph with validity windows and confidence scores. Supports entities (people, projects, concepts) and triples (subject → predicate → object).

Modules

| Module | Description | |--------|-------------| | config.ts | Palace configuration (env vars, config.json, defaults) | | mcp-server.ts | JSON-RPC MCP server (19 tools) | | knowledge-graph.ts | Temporal entity-relationship graph (bun:sqlite) | | dialect.ts | AAAK compression dialect | | layers.ts | 4-layer memory stack | | searcher.ts | Semantic search via ChromaDB | | palace-graph.ts | Graph traversal and tunnel detection | | miner.ts | Project file mining | | convo-miner.ts | Conversation mining | | normalize.ts | Chat export normalization (Claude, ChatGPT, Slack) | | general-extractor.ts | Extract decisions, preferences, milestones | | entity-registry.ts | Persistent entity registry with Wikipedia lookup | | entity-detector.ts | Auto-detect people/projects from text | | onboarding.ts | Interactive setup wizard | | room-detector-local.ts | Room detection from folder structure | | spellcheck.ts | Optional spell correction | | split-mega-files.ts | Split concatenated transcripts |

Tests

bun test

Related

• opencode-mempalace — OpenCode plugin for automatic integration
• mempalace — Original Python implementation

Acknowledgements

This project is a Bun/TypeScript port of the original mempalace by milla-jovovich. All credit for the palace architecture, AAAK compression dialect, knowledge graph design, memory layer system, and MCP tool definitions goes to their work.

License

MIT