Events and memory

Events support dialogue, choice, quest, relationship, inventory, achievement,

world and custom. importance is between 0 and 1 (default 0.5); source defaults to

sdk. Optional fields include sessionId, worldId, UTC timestamp, metadata and

idempotencyKey. An event with a session must belong to that session's character while active.

const batch = await fourBtd.events.captureBatch([
  {
    characterId: mira.id,
    type: 'dialogue',
    content: 'Welcome home.',
  },
  {
    characterId: mira.id,
    type: 'choice',
    content: 'Helped the traveler.',
  },
]);

for (const result of batch) {
  if (result.success) {
    console.log(result.data.id);
  } else {
    console.log(result.error.code);
  }
}

const memory = await fourBtd.memory.commit({
  characterId: mira.id,
  type: 'semantic',
  content: 'The river crossing is safe.',
  tags: ['travel'],
});

await fourBtd.memory.evolve(
  {
    memoryId: memory.id,
    content: 'The bridge is now damaged.',
    salience: 0.95,
  },
  {
    expectedVersion: memory.version,
  },
);

const context = await fourBtd.memory.hydrate({
  characterId: mira.id,
  query: 'bridge',
  tags: ['travel'],
  types: ['semantic'],
  minSalience: 0.5,
  from: '2020-01-01T00:00:00Z',
  to: '2100-01-01T00:00:00Z',
  limit: 10,
});

await fourBtd.memory.forget(memory.id, 'Player requested removal from recall');

Memory supports episodic, semantic, relationship, and world.

evolve applies an explicit content, salience, tags, or provenance patch. It increments the memory version while preserving its ID. It does not call a language model.

Event provenance must reference events belonging to the same character.

hydrate uses the same filters and ranking as recall:

• All requested tags must match.

• types uses OR filtering.

• UTC creation times are filtered inclusively.

• Query terms match case-insensitive substrings, with at least one term required to match.

• Relevance is 70% matching-term fraction + 30% salience.

• Without query terms, relevance is based entirely on salience.

• Ties are resolved using the memory ID.

These are deterministic local heuristics, not embedding-based search.

Forgotten memories are excluded from recall and list, but retained for audit. Forgetting a memory does not physically erase it.