MemPalace.ts

TypeScript rewrite of MemPalace (Python v3.0.14).

Local AI memory system for Claude Code, ChatGPT, and any MCP-compatible tool.

What's different from Python

| | Python (v3.0.14) | TypeScript | |---|---|---| | Vector DB | ChromaDB (subprocess, ~500ms startup) | sqlite-vec (in-process, ~15ms startup) | | Embedding context | 256 tokens max | 512 tokens max (sees more context) | | Localization | English only | EN, RU, DE, FR, ES with auto-detect | | Cross-lingual search | N/A | 50+ languages via optional multilingual model | | Metadata | Schema-less dict | Fixed columns + extra JSON (nothing lost) | | LLM rerank | Haiku only (not public) | Any OpenAI-compatible API (Ollama, OpenAI, Groq...) | | Hooks | Python shell scripts | Native Node.js (same hooks protocol) | | Dependencies | Python + chromadb + sentence-transformers | Node.js only | | Migration | — | mempalace migrate (ChromaDB → sqlite-vec) | | Tests | 92 | 402 |

LongMemEval benchmark (500 questions, M2 Ultra)

| Mode | Python | TypeScript | |------|--------|------------| | Raw (zero API) | 96.6% R@5 | 96.0% R@5 | | Hybrid (keyword re-rank) | — | 98.2% R@5 | | + LLM rerank | 100% (Haiku) | TBD (any model) |

The 0.6% raw difference is due to 512 vs 256 token embedding context — TS sees more text per session, which helps in general but slightly dilutes 3/500 edge cases. Hybrid mode compensates entirely.

Quick Start

npm install @vlaushkin/mempalace-ts

mempalace init ~/projects/myapp
mempalace mine ~/projects/myapp
mempalace search "why did we switch to GraphQL"
mempalace search "auth flow" --rerank gemma4:e4b    # optional LLM rerank

MCP Server

claude mcp add mempalace -- node dist/mcp/server.js

19 tools: mempalace_search, mempalace_add_drawer, mempalace_kg_query, mempalace_diary_write, and 15 more.

Search supports optional LLM reranking:

mempalace_search({ query: "auth flow", rerank_model: "gemma4:e4b" })

LLM Reranker

Works with any OpenAI-compatible API:

# Ollama (local, free)
mempalace search "query" --rerank gemma4:e4b

# OpenAI
MEMPALACE_RERANK_URL=https://api.openai.com/v1 \
MEMPALACE_RERANK_KEY=sk-... \
mempalace search "query" --rerank gpt-4o-mini

# Env-based config
export MEMPALACE_RERANK_URL=http://localhost:11434/v1
export MEMPALACE_RERANK_MODEL=gemma4:e4b
mempalace search "query" --rerank

Without --rerank, search works exactly as before (pure semantic).

Auto-Save Hooks

{
  "hooks": {
    "Stop": [{ "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/index.js stop" }] }],
    "PreCompact": [{ "hooks": [{ "type": "command", "command": "node /path/to/dist/hooks/index.js precompact" }] }]
  }
}

Every 15 messages → auto-save. Before context compression → emergency save.

Localization

Auto-detects language per document. Built-in: EN, RU, DE, FR, ES.

AAAK compression, memory extraction, emotion/flag detection, sentiment analysis — all locale-aware. Custom locales via registerLocale().

Multilingual Search

Enable cross-lingual search across 50+ languages:

// ~/.mempalace/config.json
{ "multilingual": true }

Uses a dual-index architecture — both all-MiniLM-L6-v2 (English, 87 MB) and paraphrase-multilingual-MiniLM-L12-v2 (50+ languages, ~470 MB) run in parallel:

• Mining writes embeddings to both indexes in one transaction
• Search auto-detects query language and picks the right index
• English queries use the original fast English model
• Non-English queries (Cyrillic, umlauts, accents, CJK, etc.) use the multilingual model

Cross-lingual similarity examples (multilingual model):

EN "machine learning"  <->  RU "машинное обучение"    → 0.95
EN "git hooks setup"   <->  DE "git hooks einrichten" → 0.91
EN "hello world"       <->  FR "bonjour le monde"     → 0.81

The multilingual model is downloaded automatically on first use (~470 MB, one-time). Without "multilingual": true, everything works exactly as before.

All Commands

mempalace init <dir>                    # detect rooms, create config
mempalace mine <dir>                    # mine project files (respects .gitignore)
mempalace mine <dir> --mode convos      # mine conversation exports
mempalace search "query"                # semantic search
mempalace search "query" --rerank       # search + LLM rerank
mempalace wake-up                       # load L0 + L1 context (~170 tokens)
mempalace compress --wing myapp         # AAAK compression
mempalace split <dir>                   # split mega-files into sessions
mempalace repair                        # rebuild vector index
mempalace status                        # palace overview
mempalace migrate export/import/verify  # ChromaDB → sqlite-vec

Development

npm install
npm run build          # tsup → dist/
npm run test           # vitest (402 tests)
npm run lint           # biome check
npm run typecheck      # tsc --noEmit

# Benchmarks
npx tsx benchmarks/longmemeval.ts data/longmemeval_s_cleaned.json
npx tsx benchmarks/longmemeval.ts data/longmemeval_s_cleaned.json --mode hybrid
npx tsx benchmarks/longmemeval.ts data/longmemeval_s_cleaned.json --rerank gemma4:e4b

License

MIT — see LICENSE.