Skip to content

Memory

Jump to bottom
Jdaie edited this page Jun 27, 2026 · 1 revision

Memory

Whisplay AI Chatbot supports memory so the assistant can remember user preferences, durable facts, and useful context from earlier conversations.

There are two memory options:

Module Best for Storage
Local Memory Simple built-in memory with no extra service JSON file under data/memory
MemPalace Larger external long-term memory with semantic search MemPalace + ChromaDB

For most users, start with Local Memory. It is lightweight, built into Whisplay, and only needs .env configuration.

Local Memory

Local Memory stores conversation sessions and concise user memories in a local JSON file. When enabled, it can:

  • Save completed user/assistant exchanges in the background.
  • Summarize each conversation session for future recall.
  • Keep short user preference, context, and fact memories.
  • Inject a small amount of remembered context at the start of a new conversation.
  • Search previous sessions when the user says things like "last time", "before", "remember", "上次", "之前", "记得", or "聊过".

Local Memory is disabled by default.

Configuration

Add this to .env:

# Enable built-in lightweight local memory.
MEMORY_ENABLED=true

# Auto-save completed user/assistant exchanges.
# Default: true when MEMORY_ENABLED=true.
MEMORY_AUTO_SAVE=true

# Storage directory.
# Default: ./data/memory
MEMORY_DIR=./data/memory

# Optional fixed user profile/preferences injected with local memories.
MEMORY_PROFILE_TEXT=

# Start a new memory session after this many idle seconds.
# Default: CHAT_HISTORY_RESET_TIME or 300.
MEMORY_SESSION_IDLE_SECONDS=300

# Retention and recall limits.
MEMORY_MAX_SESSIONS=200
MEMORY_MAX_SESSION_EXCHANGES=20
MEMORY_MAX_SEARCH_RESULTS=4
MEMORY_WAKEUP_MAX_ITEMS=5

You can also customize the prompt used to summarize saved conversations:

MEMORY_SUMMARY_PROMPT_PREFIX=Summarize the following user-assistant conversation into a concise memory for future recall. Preserve user preferences, facts, decisions, open tasks, and important context. Do not quote the transcript verbatim. Keep it under 80 words:

Storage Format

By default, Local Memory writes to:

./data/memory/memory.json

The file contains:

Field Description
sessions Recent conversation sessions, each with title, summary, timestamps, keywords, and retained exchanges.
userMemories Durable preference/context/fact memories saved explicitly or inferred from user text.

The maximum number of sessions is controlled by MEMORY_MAX_SESSIONS. Each session keeps only the latest MEMORY_MAX_SESSION_EXCHANGES exchanges.

Automatic Recall

At the beginning of a conversation turn, Local Memory may add a hidden memory context block to the LLM prompt. It can include:

  • MEMORY_PROFILE_TEXT, if configured.
  • A few recent durable user memories, controlled by MEMORY_WAKEUP_MAX_ITEMS.
  • Matching historical session summaries when the user asks about prior conversations.

The assistant is instructed to use this context naturally and avoid inventing details when the memory is uncertain.

LLM Tools

When Local Memory is enabled, Whisplay registers two LLM tools:

Tool Purpose
searchLocalMemory Search local lightweight memory for preferences, situations, and previous conversations.
storeLocalMemory Store a concise user preference, situation, or durable fact.

The model may call these tools automatically when the user refers to previous conversations or asks the assistant to remember something.

Example prompts:

  • "Remember that I prefer short answers."
  • "以后默认用中文回答我。"
  • "What did we talk about last time?"
  • "上次我们说到哪个配置了？"
  • "Remember this device is installed in the kitchen."

Auto-Save Behavior

When MEMORY_AUTO_SAVE=true, Whisplay saves an exchange after the user speaks, the LLM responds, and the response finishes. Saving happens in the background and does not block the chat flow.

If the user's text looks like a preference or instruction to remember something, Local Memory also stores it as a durable user memory. Examples include text containing "记住", "以后", "偏好", "我喜欢", "我不喜欢", "我希望", "不要", "别再", or "下次".

Set MEMORY_AUTO_SAVE=false if you only want manual memory through storeLocalMemory.

MemPalace

MemPalace is the optional external long-term memory integration. It is better when you want a larger memory palace, semantic search, imported conversation history, and ChromaDB-backed retrieval.

Use MemPalace when:

  • You want to mine existing ChatGPT, Claude, Slack, notes, or project exports.
  • You need semantic search across a larger memory corpus.
  • You want memory organized by wings, rooms, halls, and projects.

Basic .env:

MEMPALACE_ENABLED=true
MEMPALACE_PALACE_PATH=/home/pi/.mempalace/palace
MEMPALACE_PYTHON_PATH=python3
MEMPALACE_MAX_RESULTS=5
MEMPALACE_AUTO_SAVE=true

See MemPalace for full setup, mining commands, tools, and troubleshooting.

Choosing a Memory Module

Use Local Memory if you want the simplest built-in option. It has no external dependency and is suitable for everyday preferences, short-term project context, and remembering recent conversations.

Use MemPalace if you need a larger external memory system and are comfortable installing Python dependencies and maintaining the palace database.

You can enable both, but doing so may increase prompt size and tool activity. Start with one memory module unless you have a clear reason to combine them.

Warning: Memory can increase token usage because recalled summaries, durable memories, search results, and tool outputs are added to the LLM context. Keep MEMORY_WAKEUP_MAX_ITEMS, MEMORY_MAX_SEARCH_RESULTS, and MemPalace result limits conservative on small models or cost-sensitive cloud models.

Troubleshooting

  • No memories are recalled — Confirm MEMORY_ENABLED=true, ask a question that clearly refers to previous context, and check that data/memory/memory.json exists.
  • Too much old context appears — Lower MEMORY_WAKEUP_MAX_ITEMS and MEMORY_MAX_SEARCH_RESULTS.
  • Wrong or stale memory appears — Edit or remove the relevant entry from data/memory/memory.json, then restart the chatbot.
  • Memory file is not written — Ensure the chatbot user can write to MEMORY_DIR.
  • Provider rejects tool calls — Confirm the selected LLM model supports function/tool calling, or disable provider-specific tool calling.

Clone this wiki locally