Writing to a memory

Memory is not read-only. An agent that reaches a conclusion worth keeping should put it back, so the next session, in any client, can retrieve it.

Both write tools need the memory:write scope.

cortex_remember

Stores one durable fact. The text should be a single self-contained statement, readable years later without the surrounding conversation.

{
  "text": "Pricing moved to $19.99/seat for Solo in July 2026.",
  "kind": "decision",
  "confidence": 0.9,
  "source_universal_ids": ["gmail_messages:18f2c...", "drive_files:1kZ..."]
}

What is worth remembering

Write facts that outlive the session: decisions and their reasons, stable preferences, outcomes, corrections to something previously believed.

Skip the transient: what the user asked five minutes ago, anything already in a connected source (it is in the graph already), and anything you inferred with low confidence and did not verify. A memory full of restated context retrieves worse than a sparse one.

The same write from the SDK and the CLI

const memory = client.cortex(officeId).forAgent(officeId, 'atlas');
 
// Provenance defaults to the results of this instance's most recent ask(),
// so the conclusion is linked to the evidence that produced it.
await memory.ask('what did pricing move to?');
await memory.remember('Pricing moved to $19.99/seat for Solo in July 2026.', {
  kind: 'decision',
  confidence: 0.9,
});
 
// Override it explicitly when you need to:
await memory.remember('...', { sources: ['gmail_messages:18f2c...'] });
await memory.remember('...', { sources: [] });   // store with no provenance

await client.cortex(officeId).remember(officeId, {
  agent: 'atlas',                                  // required
  text: 'Pricing moved to $19.99/seat for Solo in July 2026.',
  kind: 'decision',
  confidence: 0.9,
  source_universal_ids: ['gmail_messages:18f2c...', 'drive_files:1kZ...'],
});

mi cortex remember "Pricing moved to \$19.99/seat for Solo in July 2026." \
  --office "$OFFICE" --agent atlas --kind decision --confidence 0.9 \
  --source gmail_messages:18f2c... --source drive_files:1kZ...

The write is idempotent per agent and text: re-remembering the same fact updates it in place rather than adding a second node. The response tells you what landed:

{
  "status": "ok",
  "universal_id": "agent_memory:atlas:9f21...",
  "embedded": true,
  "linked_sources": 2,
  "derived_from_edges": 2,
  "retrievable_at": "2026-08-26T18:04:11Z"
}

cortex_ingest_conversation

Ingests a whole conversation rather than a single fact, so the exchange itself becomes retrievable. Use it at the end of a substantive session; use cortex_remember for the one-line conclusions that came out of it.

Ingesting content, not conclusions

cortex_remember is for facts an agent derived. To push whole documents into a memory, so their text becomes retrievable in its own right, use the ingest path instead:

const cortex = client.cortex(officeId);
const { feedKey } = await cortex.ensureFeed(officeId, 'handbook');
 
await cortex.pushRows(officeId, feedKey, [{
  external_id: 'handbook:pricing',    // stable id: re-pushing updates in place
  title: 'Pricing policy',
  content: 'Solo moved to $19.99 per seat in July 2026. Team stayed at $49.',
}], { deferEmbed: true });

See ingest and query for batching, local files, and the CLI and plain-HTTP equivalents.

Absent write scope

If a client holds only memory:read, the write tools are not offered. That is the expected state for a read-only integration. Treat it as a signal to surface what you would have stored, rather than as an error to retry.