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, downloaded automatically)
embedding_model: local/all-MiniLM-L6-v2           # 384 dimensions
embedding_model: local/all-mpnet-base-v2           # 768 dimensions

The embedding dimension is detected automatically. MUXI creates dimension-specific storage tables (memories_384, memories_1536, etc.), so different formations can share the same database even with different embedding models.

Local models are great for development and air-gapped environments. No API key needed -- the model downloads on first use via sentence-transformers.

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