Skip to main content
Every agent conversation produces knowledge worth keeping — a user’s location, a product preference, a complaint, a goal. MemLayer gives you a clean API to store that knowledge, search it later with semantic queries, update it when facts change, and delete it when it’s no longer needed. This guide walks through the full memory lifecycle.

​
Storing a Memory

Call client.remember() to persist a piece of information tied to a specific user and agent. Each memory is embedded automatically and stored with its importance score, memory type, and optional expiry. 
from memlayer import MemLayerClient

client = MemLayerClient(api_key="ml_live_xxx")

result = client.remember(
    content="User is based in Lagos, Nigeria",
    user_id="user_123",
    agent_id="support_bot",
    memory_type="semantic",   # episodic | semantic | summary
    importance=0.8,           # 0.0 (low) to 1.0 (high)
    ttl_days=30,              # auto-expire after 30 days. None = permanent
)

print(result.id)       # UUID of the stored memory
print(result.message)  # "Memory stored successfully"

​
Parameter Reference

ParameterTypeRequiredDefaultDescription
contentstr✅—The text to store as a memory
user_idstr✅—Identifier for the end user
agent_idstr✅—Identifier for the agent
memory_typestr—"episodic"One of episodic, semantic, summary
importancefloat—0.5Priority score from 0.0 to 1.0
ttl_daysint | None—NoneDays until the memory auto-expires; None = permanent

​
Memory Types

episodic

Things that happened. Use for events, interactions, and complaints. “User reported a slow delivery on 2024-11-03.”

semantic

Facts about the user. Use for preferences, attributes, and goals. “User prefers concise bullet points.”

summary

Compressed older memories. Auto-generated by MemLayer to save space while preserving context.

​
Auto-Deduplication

MemLayer checks every incoming memory against existing ones using cosine similarity. If a near-identical memory (similarity ≥ 0.95 by default) already exists, the store is silently skipped — no duplicate is created. If you want to check before committing to a store — for example, to skip an API call entirely — use is_duplicate(): 
already_known = client.is_duplicate(
    content="User is based in Lagos",
    user_id="user_123",
    agent_id="support_bot",
    threshold=0.95,  # default; lower = stricter dedup
)

if not already_known:
    client.remember("User is based in Lagos", user_id="user_123", agent_id="support_bot")
remember() already performs deduplication internally. Use is_duplicate() only when you want to avoid the round-trip entirely, such as in high-throughput pipelines.

​
Setting a TTL

Pass ttl_days to automatically expire a memory after a set number of days. MemLayer deletes it in the background — no manual cleanup needed. 
# This memory will expire in 7 days
result = client.remember(
    content="User is trialing the Pro plan",
    user_id="user_123",
    agent_id="support_bot",
    memory_type="semantic",
    importance=0.6,
    ttl_days=7,
)
When no ttl_days is provided (the default), the memory is stored permanently until you explicitly delete it or the user resets their data.

​
Searching Memories

Use client.recall() to run a semantic search against a user’s memories. Results are ranked by a hybrid score combining semantic similarity, recency, and importance. 
memories = client.recall(
    query="what are this user's communication preferences?",
    user_id="user_123",
    agent_id="support_bot",
    top_k=5,        # return up to 5 results (1-20)
    min_score=0.70, # minimum relevance threshold (0.0-1.0)
    memory_type="semantic",  # optional: filter by type
)

for m in memories:
    print(f"[{m.score:.3f}] {m.content}")
    print(f"  type={m.memory_type}  importance={m.importance}")

​
Hybrid Scoring

MemLayer blends three signals to rank results so the most useful memories always surface first:
SignalWeightWhat it captures
Semantic similarity70%How closely the memory matches the query
Recency20%How recently the memory was created or accessed
Importance10%The importance score you assigned at store time
Adjust min_score to control recall precision. A threshold of 0.70 is a good default; lower it toward 0.50 for broader results, raise it toward 0.85 for high-precision retrieval.

​
Updating a Memory

When a fact changes — a user moves cities, updates a preference, or corrects information — use client.update() to replace the content in place. The memory keeps its original UUID, and MemLayer automatically re-embeds the new content. 
# User just moved — update the existing memory
updated = client.update(
    memory_id="775263ee-73af-4416-9804-1f274048ae08",
    user_id="user_123",
    agent_id="support_bot",
    new_content="User moved from Lagos to Abuja, Nigeria",
    importance=0.95,  # optional: revise the importance score
)

print(updated.content)  # "User moved from Lagos to Abuja, Nigeria"
print(updated.id)       # same UUID as before
Prefer update() over deleting and re-storing. It preserves the memory’s history metadata and avoids creating a new UUID that might be referenced elsewhere in your application.

​
Deleting a Memory

​
Delete a Single Memory

Use client.forget() when a specific piece of information is no longer accurate or relevant: 
result = client.forget(
    memory_id="775263ee-73af-4416-9804-1f274048ae08",
    user_id="user_123",
    agent_id="support_bot",
)

print(result.deleted)  # 1
print(result.message)  # "Memory deleted"

​
Wipe All Memories

Use client.forget_all() to permanently erase every memory for a user+agent pair. This is the right tool for GDPR deletion requests and account resets: 
result = client.forget_all(
    user_id="user_123",
    agent_id="support_bot",
)

print(f"Deleted {result.deleted} memories")
forget_all() is irreversible. All memories for the specified user_id and agent_id are permanently deleted. Use it only for explicit user requests or account termination flows.