Skip to content

MemPalace

Jump to bottom
Jdaie edited this page Apr 17, 2026 · 1 revision

MemPalace is an open-source, local-first AI memory system. It stores your conversations in a structured "palace" (wings, rooms, halls) backed by ChromaDB, and provides semantic search with 96.6% recall — all on-device with zero cloud calls.

When integrated with Whisplay AI Chatbot, the LLM gains four tools:

Tool Description
mempalaceSearch Semantic search across all stored memories
mempalaceStore Save a decision, preference, or fact for future recall
mempalaceWakeUp Load identity + critical facts (~170 tokens)
mempalaceStatus Palace overview — wings, rooms, memory counts

Additionally, every conversation is automatically saved to the memory palace after each exchange completes. This means the chatbot builds long-term memory passively — no manual action required.

The LLM also calls tools automatically when context from past sessions would be useful — e.g. "why did we choose GraphQL?" triggers mempalaceSearch behind the scenes.

Prerequisites

Install MemPalace on the device:

pip install mempalace

On Raspberry Pi, this also pulls in ChromaDB. Allow a few minutes for the first install.

Initialize a palace and mine your data (one-time setup):

mempalace init ~/projects/myapp
mempalace mine ~/chats/ --mode convos

Configuration

Add the following to your .env file:

# Enable MemPalace long-term memory tools
MEMPALACE_ENABLED=true

# Path to the palace data directory (default: ~/.mempalace/palace)
# MEMPALACE_PALACE_PATH=~/.mempalace/palace

# Python binary that has mempalace installed (default: python3)
# MEMPALACE_PYTHON_PATH=python3

# Maximum search results returned per query (default: 5)
# MEMPALACE_MAX_RESULTS=5

# Default wing for search/store when none is specified
# MEMPALACE_DEFAULT_WING=

# Auto-save every conversation exchange to long-term memory (default: true when enabled)
# Set to false to only use manual mempalaceStore tool calls
# MEMPALACE_AUTO_SAVE=true

If you installed mempalace in a virtual environment, point MEMPALACE_PYTHON_PATH to that venv's python:

MEMPALACE_PYTHON_PATH=/home/pi/.venv/bin/python

How It Works

Automatic Memory (Auto-Save)

Every time a conversation exchange completes (user speaks → ASR → LLM responds → TTS finishes), the full exchange is automatically saved to the memory palace as a verbatim record in the conversations room under hall_events. This happens in the background and never blocks the chat flow.

The auto-save stores:

[2026-04-12 15:30:00]
User: Why did we switch to GraphQL?
Assistant: We switched to GraphQL because REST endpoints were proliferating...

To disable auto-save and only use explicit tool calls, set MEMPALACE_AUTO_SAVE=false.

LLM Tools (On-Demand)

Once enabled, the LLM receives four function-calling tools. It decides when to invoke them based on the conversation:

  1. Search — User asks "What did we decide about auth?" → LLM calls mempalaceSearch("auth decision") → verbatim results returned → LLM answers with context.

  2. Store — User says "Let's go with Postgres for the new service" → LLM calls mempalaceStore(content="Decided to use Postgres for the new service because...", wing="wing_myapp", room="database", hall="hall_facts") → stored locally.

  3. Wake-up — User says "Remind me what I'm working on" → LLM calls mempalaceWakeUp() → receives ~170 tokens of critical context (identity, team, projects, preferences).

  4. Status — User asks "How much have I stored?" → LLM calls mempalaceStatus() → palace overview returned.

The Palace Structure

MemPalace organizes memories into a navigable hierarchy:

Wing (person or project)
  └── Hall (memory type: facts, events, discoveries, preferences, advice)
       └── Room (specific topic: auth-migration, database, ci-pipeline)
            └── Closet (summary)
                 └── Drawer (verbatim original content)
  • Wings — one per person or project
  • Halls — memory types: hall_facts, hall_events, hall_discoveries, hall_preferences, hall_advice
  • Rooms — named topics within a wing
  • Tunnels — cross-wing connections when the same room appears in different wings

Example .env (Online LLM Stack)

Combine MemPalace with local ASR/LLM/TTS for a fully offline chatbot with long-term memory:

ASR_SERVER=faster-whisper
LLM_SERVER=gemini
TTS_SERVER=piper-http

MEMPALACE_ENABLED=true
MEMPALACE_PALACE_PATH=/home/pi/.mempalace/palace

# OTHER ENV VARS for ASR/LLM/TTS...

Note: Full offline stack with MemPalace on Raspberry Pi 5 is possible but it will be slow due to large context. For a more responsive experience, use MemPalace with an online LLM backend (OpenAI, Gemini, etc.) while keeping ASR and TTS local.

Mining Conversation History

MemPalace can import conversations from Claude, ChatGPT, Slack exports, and more:

# Mine project files (code, docs, notes)
mempalace mine ~/projects/myapp

# Mine conversation exports
mempalace mine ~/chats/ --mode convos

# Mine with auto-classification (decisions, milestones, problems)
mempalace mine ~/chats/ --mode convos --extract general

# Tag with a specific wing
mempalace mine ~/chats/ --mode convos --wing myapp

Troubleshooting

  • "mempalace: command not found" — Ensure pip install mempalace succeeded and the Python binary is in PATH, or set MEMPALACE_PYTHON_PATH explicitly.
  • Slow first search — ChromaDB builds its index on first query. Subsequent searches are fast.
  • Empty search results — Run mempalace status to verify data has been mined. Run mempalace mine on your data directories first.
  • Permission errors — Ensure the palace directory is readable/writable by the user running the chatbot service.

Clone this wiki locally