Memories¶

// Top-K fused memories for a chat — the same shape the host uses internally
// during prompt assembly.
const result = await spindle.memories.cortex.query({
  chatId: 'chat-id',
  queryText: 'recent conflict with Selene',
  topK: 8,
  emotionalContext: ['betrayal', 'fury'],
  includeConsolidations: true,
  includeRelationships: true,
})

for (const memory of result.memories) {
  spindle.log.info(`${memory.finalScore.toFixed(2)}  ${memory.content}`)
}
spindle.log.info(`Entities in context: ${result.entityContext.map(e => e.name).join(', ')}`)
spindle.log.info(`Active arc: ${result.arcContext ?? 'none'}`)

// Read whatever the most recent generation saw — zero roundtrip.
const cached = await spindle.memories.cortex.getCached('chat-id')

// Linked cortex: every vault attached to the chat + every bidirectional
// interlink target, all queried in parallel.
const linked = await spindle.memories.cortex.queryLinked('chat-id', {
  queryText: 'who else knows about the dagger?',
})

const entities = await spindle.memories.entities.list('chat-id')        // active only
const all     = await spindle.memories.entities.list('chat-id', { activeOnly: false })
const selene  = await spindle.memories.entities.findByName('chat-id', 'Selene')

// Upsert is a smart merge — matches against canonical name + known aliases.
const upserted = await spindle.memories.entities.upsert('chat-id', {
  name: 'Selene',
  type: 'character',
  aliases: ['the Lady of Ashes'],
  confidence: 0.95,
})

await spindle.memories.entities.addFacts(upserted.id, [
  "Carries a dagger inscribed with her mother's name",
  'Allergic to silver',
])
await spindle.memories.entities.updateStatus(upserted.id, { status: 'deceased' })
await spindle.memories.entities.updateEmotionalValence(upserted.id, {
  betrayal: 0.6,
  grief: 0.4,
})

// Use entity names (not IDs); the host resolves canonical IDs server-side.
await spindle.memories.relations.upsert('chat-id', {
  source: 'Selene',
  target: 'Marcus',
  type: 'rival',
  label: 'duel pending',
  sentiment: -0.4,
})

const activeEdges = await spindle.memories.relations.list('chat-id')
const everyEdge   = await spindle.memories.relations.listAll('chat-id') // includes superseded
const seleneEdges = await spindle.memories.relations.forEntity('chat-id', selene!.id)

const arcs    = await spindle.memories.consolidations.list('chat-id')
const tier2   = await spindle.memories.consolidations.list('chat-id', { tier: 2 })
const current = await spindle.memories.consolidations.latestArc('chat-id')

// Fire-and-forget; new arcs become visible via list() once the background
// pass completes. Runs in extractive / heuristic mode only.
await spindle.memories.consolidations.run('chat-id')

const salience = await spindle.memories.salience.list('chat-id', { limit: 50 })

// Snapshot a chat's cortex state for later reuse. Copies entities + relations
// synchronously and starts a background LanceDB chunk copy.
const vault = await spindle.memories.vaults.create({
  chatId: 'chat-id',
  name: 'Campaign — Act 1',
  description: 'Frozen state at the end of the first arc',
})

const { vault: meta, entities: vaultEntities, relations: vaultRelations } =
  (await spindle.memories.vaults.get(vault.id))!

// Attach the vault as read-only knowledge to another chat.
await spindle.memories.links.attach({
  chatId: 'another-chat-id',
  linkType: 'vault',
  vaultId: vault.id,
})

// Interlink two chats so each sees the other's live entities/relations.
await spindle.memories.links.attach({
  chatId: 'chat-a',
  linkType: 'interlink',
  targetChatId: 'chat-b',
  bidirectional: true,
})

// Re-run the LanceDB chunk copy after an embedding model swap.
await spindle.memories.vaults.reindex(vault.id)

// Inspect the raw chunk index used by the {{memories}} macro.
const chunks = await spindle.memories.chatMemory.listChunks('chat-id')

// Top-K hybrid (vector + BM25) retrieval — same call as
// `spindle.chats.getMemories()` but under the memories permission.
const memoryPayload = await spindle.memories.chatMemory.get('chat-id', { topK: 6 })

// Rebuild chunks if stale and queue any pending vectorizations.
const warm = await spindle.memories.chatMemory.warm('chat-id', { force: false })
spindle.log.info(`Warmup: ${warm.status} (${warm.reason ?? 'n/a'})`)

await spindle.memories.chatMemory.invalidate('chat-id')

const stats     = await spindle.memories.stats.usage('chat-id')
const phase     = await spindle.memories.stats.ingestionStatus('chat-id')
const timings   = await spindle.memories.stats.ingestionTelemetry('chat-id')

spindle.log.info(`${stats.entityCount} entities, ${stats.relationCount} relations`)
if (phase?.status === 'processing') {
  spindle.log.info(`Phase: ${phase.phase} (${phase.pendingJobs} job(s) queued)`)
}
spindle.log.info(`Avg ingestion: ${timings.averages.totalMs.toFixed(1)}ms over ${timings.samples} samples`)

try {
  await spindle.memories.entities.list('chat-id')
} catch (err) {
  if (err.message.startsWith('PERMISSION_DENIED:')) {
    spindle.toast.warning('Enable the "Memories" permission to use this feature.')
  } else {
    throw err
  }
}