Long-Term Memory

NPCs can remember past conversations with individual players across play sessions.

Overview

Without memory:


Day 1 - Player: "My name is Alex"
       NPC: "Nice to meet you, Alex!"

Day 7 - Player: "Do you remember me?"
       NPC: "I'm sorry, have we met?"  ❌

With memory:


Day 1 - Player: "My name is Alex"
       NPC: "Nice to meet you, Alex!"

Day 7 - Player: "Do you remember me?"
       NPC: "Of course, Alex! Good to see you again!" ✓

How It Works

Memory Storage

During conversation, the LLM extracts important moments:


Player: "I'm searching for my lost sister."
→ Memory stored: "Player is searching for their lost sister"

Each memory includes:

Memory text
Importance score (1-10)
Topics/categories
Timestamp
Associated Entity Mind ID

Memory Retrieval

Before generating a response:

Platform searches past memories using semantic similarity
Top 5 relevant memories injected into LLM context
LLM uses memories to personalize response

Example:


Current message: "Have you seen any strangers around here?"

Retrieved memories:
- "Player is searching for their lost sister" (0.85)
- "Player mentioned sister has red hair" (0.72)

Response: "No strangers lately, but I'll keep an eye out for
someone with red hair, like you mentioned."

Enabling Memory

In Unity SDK


npc.EnableMemoryRetrieval = true; // Retrieve past memories
npc.EnableMemoryStorage = true;   // Store new memories

Requirements:

Server Mediated authentication mode
playerId provided in requests
entityMindId set on NPC

In API Requests


{
  "text": "Hello!",
  "entityMindId": "clxyz_blacksmith",
  "playerId": "player_001",
  "memory": {
    "retrieve": true
  }
}

Player IDs

Player IDs uniquely identify individual players for memory storage.

Good choices:

Platform IDs: steam_76561198012345678
Game account IDs: account_12345
Persistent UUIDs: 550e8400-e29b-41d4-a716-446655440000

Avoid:

Temporary session IDs (memories won’t persist)
Email addresses or real names (PII concerns)
Device IDs (players switch devices)

Unity Implementation


public static string GetPlayerId()
{
    var playerId = PlayerPrefs.GetString("LoreMind_PlayerId");
 
    if (string.IsNullOrEmpty(playerId))
    {
        playerId = $"player_{System.Guid.NewGuid()}";
        PlayerPrefs.SetString("LoreMind_PlayerId", playerId);
        PlayerPrefs.Save();
    }
 
    return playerId;
}

For multiplayer with accounts:


return $"steam_{SteamUser.GetSteamID()}";
// or
return $"account_{GameAccount.CurrentUser.Id}";

Memory Extraction

What Gets Extracted

Personal information (names, professions, background)
Relationships (friends, family, allies)
Goals and quests (what player is doing)
Preferences (likes, dislikes)
Past events (things that happened)

What Doesn’t Get Extracted

Trivial greetings (“Hi”, “Hello”)
Generic questions (“What do you sell?”)
PII (emails, phone numbers, addresses)

Importance Scoring

Score	Meaning	Examples
1-3	Minor	”Player asked about the weather”
4-6	Moderate	”Player is interested in swords”
7-9	Important	”Player is on a quest to find artifact”
10	Critical	”Player saved the village from attack”

Higher importance = more likely to be retrieved.

PII Filtering

The platform automatically filters personally identifiable information:

Email addresses
Phone numbers
Street addresses
Credit card numbers
Social security numbers

Example:


Player: "My email is alex@example.com"
Attempted memory: "Player's email is alex@example.com"
→ BLOCKED (contains email address)

Memory Checkpoints

When conversations exceed maxSessionLength (default: 20 turns):

Platform extracts memories from conversation
Stores them in long-term memory
Returns memoryCheckpoint: true in response


var response = await npc.RespondAsync("...");
 
if (response.metadata.memoryCheckpoint)
{
    // Safe to trim conversation history
    conversationHistory.RemoveRange(0, 10);
    Debug.Log($"Stored {response.metadata.memoriesStored} memories");
}

Cost Impact

Memory operations add incremental costs:

Retrieval - Embedding + vector search
Storage - Embedding + database write

Costs are typically a small percentage of total interaction cost. Each response includes memory costs in costBreakdown.memory.

See Billing for cost monitoring.

Testing Memory

In Dashboard Playground

Navigate to Lore > Playground
Select an Entity Mind
Enter a test player ID
Enable “Use Long-Term Memory”
Have a conversation
View stored memories in Test Players tab

In Unity


async void TestMemory()
{
    var client = LoreMindClient.Instance;
    string testPlayerId = "test_player_001";
 
    // First conversation - establish memory
    var response1 = await client.NPCInteract(new NPCInteractRequest
    {
        Text = "Hi! My name is Alex and I'm a blacksmith.",
        EntityMindId = "clxyz_blacksmith",
        PlayerId = testPlayerId,
        Memory = new MemoryOptions { Retrieve = true }
    });
    Debug.Log($"Memories stored: {response1.Metadata.MemoriesStored}");
 
    // Second conversation - test recall
    var response2 = await client.NPCInteract(new NPCInteractRequest
    {
        Text = "Do you remember me?",
        EntityMindId = "clxyz_blacksmith",
        PlayerId = testPlayerId,
        Memory = new MemoryOptions { Retrieve = true }
    });
    Debug.Log($"Memories retrieved: {response2.Metadata.MemoriesRetrieved}");
}

Best Practices

When to Use Memory

Good use cases:

Main story NPCs
Recurring side characters
Merchants/shopkeepers players visit often
Quest givers with long arcs

Skip memory for:

One-off NPCs (random encounters)
Generic guards/servants
Tutorial NPCs

Memory-Aware Dialogue

Design conversations that leverage memory:


if (response.metadata.memoriesRetrieved == 0)
{
    // First meeting - introduction
}
else
{
    // Returning player - reference past
}

Troubleshooting

Memories not being stored

Check playerId is provided
Check entityMindId is provided
Check memory.retrieve is true
Verify project has memory enabled
Check response: memoriesStored should be > 0

Memories not being retrieved

Same playerId in both conversations
Same entityMindId (memories are per-NPC)
Check response: memoriesRetrieved should be > 0
Allow time between storage and retrieval (embeddings process async)

Wrong memories retrieved

Semantic search found different memories more relevant. Check memory content or increase minScore threshold.

Next Steps

Entity Minds - Configure NPC personalities
Billing - Monitor memory costs
Unity SDK - Implementation guide