Guides / Use cases

Game NPCs

Characters that remember the player across play sessions, each from their own point of view: the blacksmith remembers the hammer you lost, the innkeeper only knows what reached his ears. Recall stores the scenes, learns what each NPC saw, and hands your dialogue model the right memory in a few hundred milliseconds.

What memory adds

Without memory, every conversation with an NPC starts from the script. With it, what the player did and said becomes part of the world:

Recall does not write the lines. Your game's own model does, as it does now; Recall gives it what this NPC knows about this player, and learns from what was said.

How to model it

Multiplayer works the same way: one peer per player, and each NPC keeps a separate view of each player it met. For a shared world, use one workspace per server or shard instead of per save.

Build it

Install the SDK (npm install @recall-memory/sdk or pip install recall-mem) and set RECALL_API_KEY. Create the save's peers and a session per scene; nothing is sent until the first call.

import { Recall } from "@recall-memory/sdk";

const recall = new Recall({ workspaceId: "save-7f3a" });

const player = recall.peer("player");
// Your game writes the NPCs' lines, so Recall need not learn about them (cheaper, see below).
const npc = { configuration: { observeMe: false } };
const mira = recall.peer("npc-mira", { ...npc, metadata: { role: "blacksmith" } });
const tomas = recall.peer("npc-tomas", { ...npc, metadata: { role: "innkeeper" } });

// One session per scene. Mira takes part and keeps her own view of the player.
const forge = recall.session("forge-day-3", {
  peers: [player, [mira, { observeOthers: true }]],
});

from recall_memory import PeerConfig, Recall, SessionPeerConfig

recall = Recall(workspace_id="save-7f3a")

player = recall.peer("player")
# Your game writes the NPCs' lines, so Recall need not learn about them (cheaper, see below).
npc = PeerConfig(observe_me=False)
mira = recall.peer("npc-mira", configuration=npc, metadata={"role": "blacksmith"})
tomas = recall.peer("npc-tomas", configuration=npc, metadata={"role": "innkeeper"})

# One session per scene. Mira takes part and keeps her own view of the player.
forge = recall.session(
    "forge-day-3",
    peers=[player, (mira, SessionPeerConfig(observe_others=True))],
)

Every line of dialogue: one request. turn stores the player's line and returns the context for the reply in the same round trip: the scene so far, a summary of older turns, and what Mira has learned about the player. peerPerspective is what keeps her view her own. It uses no model, so it is fast and included in the price.

// One request per line of dialogue: store the player's line, get back what Mira knows.
const { context } = await forge.turn(
  [
    player.message(
      "I lost your hammer in the river. I'll pay you 30 gold by the harvest festival.",
    ),
  ],
  { peerTarget: player, peerPerspective: mira, tokens: 2000 },
);
const prompt = context.toOpenAI(mira); // Mira's memory as system messages, then the scene
// Your game's own model writes Mira's line from `prompt`; store it so she remembers saying it.
const line = "Thirty gold by the festival, then. I'll hold you to that.";
await forge.addMessages([mira.message(line)]);

# One request per line of dialogue: store the player's line, get back what Mira knows.
result = forge.turn(
    [
        player.message(
            "I lost your hammer in the river. I'll pay you 30 gold by the harvest festival."
        )
    ],
    peer_target=player,
    peer_perspective=mira,
    tokens=2000,
)
prompt = result.context.to_openai(assistant=mira)  # Mira's memory, then the scene
# Your game's own model writes Mira's line from `prompt`; store it so she remembers saying it.
line = "Thirty gold by the festival, then. I'll hold you to that."
forge.add_messages([mira.message(line)])

Game logic: ask. For decisions (does Mira refuse to sell? does the debt quest unlock?), ask the NPC's memory in plain language. That is one model call of a few seconds, so call it when a quest step or a scene starts, not every frame. Ask for JSON with responseFormat when your code needs a field rather than a sentence.

// Quest logic, not dialogue: what does Mira believe? One model call, so keep it off the
// frame loop. (waitForIdle is for this demo; a game asks later, when learning is done.)
await recall.waitForIdle();
const debt = await mira.chat("Does the player owe me anything? How much, and by when?", {
  target: player,
  reasoningLevel: "minimal",
});

# Quest logic, not dialogue: what does Mira believe? One model call, so keep it off the
# frame loop. (wait_for_idle is for this demo; a game asks later, when learning is done.)
recall.wait_for_idle()
debt = mira.chat(
    "Does the player owe me anything? How much, and by when?",
    target=player,
    reasoning_level="minimal",
)

Rumours spread when your story says so. NPCs who were not there know nothing. To pass news on, write a fact into the listener's view yourself. That keeps gossip under your control instead of leaking between characters.

// Tomas was not at the forge, so he knows nothing yet. When your story says the news has
// travelled, write it into his view of the player yourself.
await tomas
  .conclusionsOf(player)
  .create("Heard from Mira: the player lost her hammer and owes her 30 gold.");
const rumour = await tomas.chat("What have I heard about the player?", {
  target: player,
  reasoningLevel: "minimal",
});

# Tomas was not at the forge, so he knows nothing yet. When your story says the news has
# travelled, write it into his view of the player yourself.
tomas.conclusions_of(player).create(
    [{"content": "Heard from Mira: the player lost her hammer and owes her 30 gold."}]
)
rumour = tomas.chat(
    "What have I heard about the player?", target=player, reasoning_level="minimal"
)

New game, or a player who leaves.

// A new game drops the whole save: its scenes first, then the workspace.
const scenes = [];
for await (const scene of await recall.sessions()) scenes.push(scene);
for (const scene of scenes) await scene.delete();
await recall.deleteWorkspace();
// To forget one player and keep the world: await player.delete()

# A new game drops the whole save: its scenes first, then the workspace.
for scene in list(recall.sessions()):
    scene.delete()
recall.delete_workspace(recall.workspace_id)
# To forget one player and keep the world: player.delete()

Unity, Unreal and Godot

There is no engine SDK; the REST API is two calls. Do not put your API key in the game build, where players can extract it: call Recall from your game server, or mint each player a key scoped to their own save with POST /v3/keys, so a leaked key reaches no one else's memory (set a monthly cap under Billing too). The turn call from C#:

// POST /v3/workspaces/{save}/sessions/{scene}/turn
var body = @"{
  ""messages"": [{ ""peer_id"": ""player"", ""content"": ""I lost your hammer in the river."" }],
  ""context"": { ""tokens"": 2000, ""peer_target"": ""player"", ""peer_perspective"": ""npc-mira"" }
}";
using var req = new HttpRequestMessage(HttpMethod.Post,
    $"https://api.recallmem.dev/v3/workspaces/{save}/sessions/{scene}/turn");
req.Headers.Authorization = new AuthenticationHeaderValue("Bearer", apiKey);
req.Content = new StringContent(body, Encoding.UTF8, "application/json");
var res = await http.SendAsync(req);   // { "messages": [...], "context": { ... } }

Set up each scene once, before its first turn: POST /v3/workspaces/{save}/sessions with {"id": "forge-day-3", "peers": {"player": {}, "npc-mira": {"observe_others": true}}}. It is get-or-create, so sending it again is harmless. See the REST API.

Settings that matter

Cost and speed

Measured from Europe against the hosted API (Frankfurt), October 2026: a turn or context call took 0.3 to 0.7 seconds, a question at minimal or low 2 to 4.5 seconds. Learning happens in the background and does not hold up the call.

Context, search and storage are included. You pay for learning, $1.75 per million message tokens with every message counting as at least 50, and for questions. A player who plays two hours a week, with 200 lines of their own and 200 NPC lines of about 30 tokens, and 20 game-logic questions:

More in Cost and speed.

Privacy and forgetting

Players type freely into chat-driven games, including things that are not about the game. Say in your privacy notice that conversations with characters are stored to give them memory, and let players reset it. Deleting the save's workspace removes everything in it; player.delete() forgets one player in a shared world, including every NPC's view of them. Games for children need more care: see Privacy, consent and forgetting.

Pitfalls

• One workspace for all saves. Memories from a deleted save then haunt the new one. Use a workspace per save or per world.
• Asking in the frame loop. Questions take seconds. Read context for dialogue; ask only for game logic, ahead of time.
• Reading without peerPerspective. Every NPC then knows everything the player ever said to anyone.
• NPC ids that change between builds. Memory belongs to the id: keep npc-mira stable even if her display name changes.
• Expecting the NPC's lines to be written for you. Recall is memory, not the dialogue model; bring your own model and persona prompt.

Next: Cost and speed · Designing workspaces, peers and sessions