Memory

Give agents memory that persists

Ask ChatGPT Ask Claude.ai Open in Cursor

MUXI's three-tier memory system lets agents remember context within conversations and across sessions.

New to memory? Read Memory Concepts → first to understand how the three-tier architecture works.

API Reference: GET /v1/memory | DELETE /v1/memory/buffer

Memory Architecture

┌─────────────────────────────────────┐
│         Buffer Memory               │  ← Recent messages (fast)
│         ~50 messages                │
└─────────────────────────────────────┘
                ↓
┌─────────────────────────────────────┐
│         Vector Search               │  ← Semantic similarity
│         Find related context        │
└─────────────────────────────────────┘
                ↓
┌─────────────────────────────────────┐
│       Persistent Memory             │  ← Long-term storage
│       SQLite / PostgreSQL           │
└─────────────────────────────────────┘

Quick Setup

Conversation Memory (Default)

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

With Semantic Search

memory:
  buffer:
    size: 50
    vector_search: true   # Find related past messages

With Persistence

Persistent memory is enabled by default (SQLite). For PostgreSQL:

memory:
  buffer:
    size: 50
    vector_search: true
  persistent:
    connection_string: ${{ secrets.POSTGRES_URI }}

Buffer Memory

Stores recent conversation messages in memory:

memory:
  buffer:
    size: 50              # Messages before summarization
    multiplier: 10        # Effective capacity: 500 messages

Field	Default	Description
`size`	50	Messages to keep in full
`multiplier`	10	Summarized message capacity
`vector_search`	false	Enable semantic search

When the buffer fills, older messages are automatically summarized to preserve context while saving space.

Vector Search

Find semantically related past conversations:

memory:
  buffer:
    vector_search: true
    embedding_model: openai/text-embedding-3-small

When enabled, MUXI:

Embeds each message as a vector
Searches for similar past interactions
Includes relevant context in prompts

This helps agents recall related information even from distant conversations.

Embedding Models

You can use API-based or local embedding models:

# API-based (requires API key)
embedding_model: openai/text-embedding-3-small    # 1536 dimensions

# Local (no API key required, pre-downloaded by muxi-server init)
embedding_model: local/nomic-ai/nomic-embed-text-v1.5            # 768 dimensions (default)
embedding_model: local/nomic-ai/nomic-embed-text-v2-moe          # 768 dimensions, multilingual
embedding_model: local/sentence-transformers/all-mpnet-base-v2   # 768 dimensions
embedding_model: local/sentence-transformers/all-MiniLM-L6-v2    # 384 dimensions

The default local model is local/nomic-ai/nomic-embed-text-v1.5 (768-dim, 8k context, Apache-2.0). The id after local/ is the full HuggingFace repo id (/); any HuggingFace embedding repo works. The embedding dimension is detected automatically. MUXI pre-creates dimension-specific storage tables (memories_384, memories_768, memories_1024, memories_1536, memories_3072), so different formations can share the same database even with different embedding models.

You can pin a specific HuggingFace revision by appending : to the slug:

embedding_model: local/nomic-ai/nomic-embed-text-v1.5:e04b7e4c5ea3e3d7e41e13d4c02fa5e29e0e3a0a

Local models are great for development and air-gapped environments. No API key needed -- the default model 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 deploys don't stall on a multi-hundred-MB fetch.

Short-name aliases like local/all-MiniLM-L6-v2 and local/all-mpnet-base-v2 were removed. Use the full HuggingFace repo id (local/sentence-transformers/all-MiniLM-L6-v2) or migrate to the new default.

Persistent Memory

Persistent memory is enabled by default with SQLite. A memory.db file is created automatically in the formation directory -- no configuration needed.

# No persistent config needed -- SQLite enabled by default
memory:
  buffer:
    size: 50

Best for: Single-user, local development. Works out of the box.

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

Best for: Custom SQLite path or explicit configuration.

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

Best for: Multi-user, production deployments.

memory:
  persistent: false

Explicitly disable persistent memory.

Multi-User Memory

Isolate memory per user:

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

Pass user ID in requests:

curl -X POST http://localhost:8001/v1/chat \
  -H "X-Muxi-User-Id: user_123" \
  -d '{"message": "Remember I prefer Python"}'

response = formation.chat(
    "Remember I prefer Python",
    user_id="user_123"
)

const response = await formation.chat('Remember I prefer Python', {
  userId: 'user_123'
});

response, _ := formation.ChatWithOptions("Remember I prefer Python", muxi.ChatOptions{
    UserID: "user_123",
})

Each user's memory is completely isolated.

Complete Configuration

memory:
  # Buffer memory
  buffer:
    size: 50
    multiplier: 10
    vector_search: true
    embedding_model: openai/text-embedding-3-small

  # Working memory (tool outputs, intermediate state)
  working:
    max_memory_mb: 10
    fifo_interval_min: 5

  # Persistent storage
  persistent:
    connection_string: ${{ secrets.POSTGRES_URI }}

Disable Memory

For stateless interactions (no context between messages):

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

How It Works

sequenceDiagram
    participant U as User
    participant M as MUXI
    participant B as Buffer
    participant V as Vector DB
    participant P as Persistent

    U->>M: New message
    M->>B: Load recent messages
    M->>V: Search similar context
    M->>P: Load user history
    M->>M: Build prompt with context
    M->>U: Response
    M->>B: Save to buffer
    M->>V: Index new message
    M->>P: Persist to database

sequenceDiagram
    participant U as User
    participant M as MUXI
    participant B as Buffer
    participant V as Vector DB
    participant P as Persistent

    U->>M: New message
    M->>B: Load recent messages
    M->>V: Search similar context
    M->>P: Load user history
    M->>M: Build prompt with context
    M->>U: Response
    M->>B: Save to buffer
    M->>V: Index new message
    M->>P: Persist to database

Next Steps

Add Memory Guide - Step-by-step tutorial
Multi-User Support - User isolation details
Knowledge - Add document-based RAG

We use cookies