Memories

Memories are the core unit in Memoid. They represent facts extracted from conversations.

What is a Memory?

When you send a conversation to Memoid:

{
  "messages": [
    {"role": "user", "content": "My name is Sarah and I work as a data scientist"}
  ]
}

Memoid extracts discrete facts:

• “User’s name is Sarah”
• “User works as a data scientist”

Each fact becomes a memory with:

• Unique ID
• Text content
• Vector embedding (for semantic search)
• Metadata (user_id, timestamps, etc.)

Adding Memories

From Conversations

The most common way to add memories:

result = client.add(
    messages=[
        {"role": "user", "content": "I just moved to San Francisco"},
        {"role": "assistant", "content": "Welcome to SF!"}
    ],
    user_id="user_123"
)

Memoid’s AI extracts relevant facts automatically.

Direct Addition

Add memories directly without extraction:

result = client.add(
    messages=[{"role": "user", "content": "User prefers dark mode"}],
    user_id="user_123",
    infer=False  # Skip AI extraction
)

Memory Updates

Memoid handles updates intelligently:

1. New facts are added as new memories
2. Updated facts modify existing memories
3. Contradictions update with the latest information

Example:

# First conversation
client.add(messages=[{"role": "user", "content": "I work at Startup Inc"}], user_id="u1")
# Memory: "User works at Startup Inc"

# Later conversation
client.add(messages=[{"role": "user", "content": "I just joined Google"}], user_id="u1")
# Memory updated: "User works at Google"

Retrieving Memories

List All

memories = client.list(user_id="user_123", limit=50)
for m in memories:
    print(f"{m.id}: {m.memory}")

Get by ID

memory = client.get("mem_abc123")
print(memory.memory)

Search (Semantic)

results = client.search(
    query="What does the user do for work?",
    user_id="user_123"
)

Deleting Memories

Single Memory

client.delete("mem_abc123")

By User

client.delete_all(user_id="user_123")

Memory Metadata

Each memory includes:

Field	Description
id	Unique identifier
memory	The fact text
user_id	Associated user
agent_id	Associated agent (optional)
created_at	Creation timestamp
updated_at	Last update timestamp
metadata	Custom key-value pairs

Custom Metadata

Add your own metadata:

client.add(
    messages=[...],
    user_id="user_123",
    metadata={
        "source": "chat",
        "session_id": "sess_abc",
        "confidence": 0.95
    }
)

Memory Isolation

Memories are isolated by:

• user_id — Per-user memories
• agent_id — Per-agent memories
• organization — By API key/project

Search and list operations only return memories matching the specified filters.

Best Practices

1. Always specify user_id for multi-user applications
2. Use meaningful metadata for filtering and analytics
3. Don’t store sensitive data unencrypted
4. Review extracted memories periodically for quality