Give your agent memory

Your agent has persistent memory it can read and write over the Agent API. In this tutorial you’ll store a fact and then recall it by meaning — not by exact wording — using the official client. It’s a short Node script you can run end to end.

Before you start

• A connected agent and its API key. If you don’t have one yet, do Connect an agent and send your first message first.
• Node.js and npm.

Set your agent’s key in the environment so the script can read it:

export ALFE_API_KEY=<your-agent-api-key>

1. Install the client

npm

npm i @alfe.ai/agent-api-client

pnpm

pnpm add @alfe.ai/agent-api-client

yarn

yarn add @alfe.ai/agent-api-client

2. Store a fact

Create memory-demo.mjs:

memory-demo.mjs

import { AgentApiClient } from "@alfe.ai/agent-api-client";

const client = new AgentApiClient({
  apiKey: process.env.ALFE_API_KEY,
  apiUrl: "https://api.alfe.ai",
});

const { memoryId } = await client.memoryStore(
  "Acme prefers a single invoice at the end of the month.",
  { topic: "acme", subtopic: "invoicing", tag: "preference", importance: 0.9 },
);

console.log("Stored memory:", memoryId);

Run it:

node memory-demo.mjs
# Stored memory: mem_…

Only the text is required — topic, subtopic, tag, and importance are optional hints that make later recall sharper.

3. Recall it by meaning

Add a search to the same script. Notice the query doesn’t share wording with the stored fact — memory matches on meaning:

memory-demo.mjs

const { memories, facts } = await client.memorySearch(
  "how does Acme want to be billed?",
  { limit: 5 },
);

for (const m of memories) {
  console.log(m.score.toFixed(2), m.text);
}
for (const f of facts) {
  console.log(`${f.subject} → ${f.predicate} → ${f.object}`);
}

Run it again:

node memory-demo.mjs
# 0.84 Acme prefers a single invoice at the end of the month.
# Acme → prefers → single monthly invoice

Each memory comes back with a relevance score (higher is closer). Alongside the raw memories, facts are concise subject → predicate → object statements the agent has distilled — related knowledge it surfaces automatically unless you pass includeKnowledge: false.

Tip

This is the point of persistent memory: your agent recalls by meaning, so it finds the right fact even when the question is worded nothing like what it stored.

4. Clean up (optional)

Remove the demo memory by its id:

const { deleted } = await client.memoryDelete(memoryId);
console.log("Deleted:", deleted); // true

What you learned

• memoryStore writes a fact; memorySearch recalls by meaning; memoryDelete removes one by id.
• Because identity is resolved from the token, the script only ever touched this agent’s memory.

Next steps

• The full method surface — memoryLearn, memoryNavigate, memoryStats, and more — is in the Memory reference.
• Learn how automatic memory forms from conversations in How memory works.
• Calling from another language? Every method maps to an HTTPS request under /agent/memory/; see Authentication.