Add Memory

Enable memory so agents remember what users told them - within a conversation and across sessions. This guide adds persistent memory to your formation.

Overview

MUXI memory layers:

1. Buffer - Recent messages (in-memory)
2. Vector Search - Semantic similarity
3. Persistent - Long-term storage (database)

Step 1: Enable Buffer Memory

Add to formation.afs:

memory:
  buffer:
    size: 50        # Keep 50 recent messages

This remembers the current conversation.

Step 2: Enable Vector Search

Find related past conversations:

memory:
  buffer:
    size: 50
    vector_search: true

Using Local Embeddings

You can run embedding models locally with no API key required:

llm:
  models:
    - embedding: "local/nomic-ai/nomic-embed-text-v1.5"   # 768 dims, default

The id after local/ is the full HuggingFace repo id (/). This is useful for development, testing, or air-gapped environments. The default model (local/nomic-ai/nomic-embed-text-v1.5) is pre-downloaded by muxi-server init into a shared cache ($MUXI_CACHE_DIR or /cache) and bind-mounted into formations at /opt/hf-cache, so the first deploy doesn't stall on a multi-hundred-MB fetch.

Common picks:

• local/nomic-ai/nomic-embed-text-v1.5 (768 dims, 8k context, Apache-2.0) -- default
• local/nomic-ai/nomic-embed-text-v2-moe (768 dims, multilingual)
• local/sentence-transformers/all-mpnet-base-v2 (768 dims)
• local/sentence-transformers/all-MiniLM-L6-v2 (384 dims)

Any HuggingFace embedding repo works. To pin a specific revision, append : to the slug (e.g. local/nomic-ai/nomic-embed-text-v1.5:e04b7e4...).

Step 3: Enable Persistent Memory

Persistent memory is enabled by default with SQLite. For production, use PostgreSQL:

SQLite (Default)

No configuration needed -- works out of the box. To customize:

memory:
  persistent:
    connection_string: "sqlite:///data/memory.db"

PostgreSQL (Multi-user)

memory:
  persistent:
    connection_string: ${{ secrets.POSTGRES_URI }}

Add secret:

muxi secrets set POSTGRES_URI
# Enter: postgresql://user:pass@host:5432/muxi

Step 4: Test

muxi dev

Test memory:

You: My name is Alice
Assistant: Nice to meet you, Alice!

[Restart formation]

You: What's my name?
Assistant: Your name is Alice.

Full Configuration

memory:
  buffer:
    size: 50
    multiplier: 10
    vector_search: true

  persistent:
    connection_string: ${{ secrets.POSTGRES_URI }}

Multi-User Memory

Isolate memory per user (requires PostgreSQL):

memory:
  persistent:
    connection_string: ${{ secrets.POSTGRES_URI }}

Pass user ID in requests:

curl -H "X-Muxi-User-Id: user_123" ...

Disable Memory

For stateless interactions:

memory:
  buffer:
    size: 0
  persistent:
    enabled: false

Migrating Embedding Models

If you switch embedding models (e.g., from an API model to a local one), existing memories need re-embedding since the dimensions differ. Use the migration script:

python scripts/migrate_embeddings.py \
  --from-dim 1536 \
  --to-dim 768 \
  --to-model "local/nomic-ai/nomic-embed-text-v1.5" \
  --connection-string "postgresql://user:pass@localhost/muxi"

The source table is preserved -- the script creates a new table for the target dimension.

Troubleshooting

Memory Not Persisting

Check database connection:

psql $POSTGRES_URI -c "SELECT 1"

High Memory Usage

Reduce buffer size:

memory:
  buffer:
    size: 20

Learn More

Memory Reference - Configuration options
Memory Concept - Architecture overview
Deep Dive: Memory Systems - Technical internals
Multi-User Support - User isolation