Skip to Content
Loremind Platform APILong-Term Memory

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, important moments are automatically extracted:

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

Memory Retrieval

When an NPC responds, relevant past memories are automatically recalled and used to personalize the response.

Example:

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

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

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

Enabling Memory

In Game Engine SDKs

Example (C#):

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

Requirements:

  • Production backend setup (see Server Integration)
  • 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)

Example Implementation (C#)

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)

PII Filtering

Personally identifiable information is automatically filtered to protect player privacy. Sensitive data like contact information is never stored in memories.

Memory Checkpoints

When conversations exceed maxSessionLength (default: 20 turns):

  1. Platform extracts memories from conversation
  2. Stores them in long-term memory
  3. 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 for retrieval and storage. Costs are typically a small percentage of total interaction cost.

See Billing for cost monitoring.

Testing Memory

In Dashboard Playground

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

In Code (C# Example)

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

The system found different memories more relevant. Check memory content in the dashboard or adjust retrieval settings.

Next Steps

Last updated on
API ReferenceRuntime Context