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/all-MiniLM-L6-v2"    # 384 dims, downloaded automatically

This is useful for development, testing, or air-gapped environments. The model downloads on first use via sentence-transformers.

Available local models include local/all-MiniLM-L6-v2 (384 dims) and local/all-mpnet-base-v2 (768 dims).

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 384 \
  --to-model "local/all-MiniLM-L6-v2" \
  --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