Using memory from the Agent API

You can read and write an agent’s memory with the official client, @alfe.ai/agent-api-client, which authenticates with the agent’s own API key. Alfe resolves the agent’s identity from its token, so an agent can only ever read and write its own memory.

This page covers the everyday calls. The Memory reference lists the full surface.

npm

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

pnpm

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

yarn

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

memory-client.ts

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

const client = new AgentApiClient({
  apiKey: process.env.ALFE_API_KEY!, // the agent's API key
  apiUrl: "https://api.alfe.ai",
});

Store a memory

Write a fact to the agent’s memory. The text is all that’s required; the organizational fields are optional and default sensibly.

store.ts

const { memoryId } = await client.memoryStore(
  "Acme prefers a single invoice at the end of the month.",
  {
    topic: "billing",       // broad area (default: "general")
    subtopic: "invoicing",  // narrower grouping (default: "general")
    tag: "preference",      // kind of memory (default: "fact")
    importance: 0.9,        // 0–1 significance hint (default: 0.7)
  },
);
// POST /agent/memory/store

You don’t usually need to store memories by hand, because the agent learns from its conversations. See How memory works. Use memoryStore when you want to guarantee that a specific fact is remembered.

Search memory

Query memory by meaning. Results come back ranked by relevance. Unless you opt out, they also include related facts the agent knows about the subjects involved.

search.ts

const { memories, facts } = await client.memorySearch(
  "how does Acme want to be billed?",
  {
    limit: 10,             // max memories to return (default: 10)
    topic: "billing",      // optionally scope to a topic / subtopic / tag
    includeKnowledge: true, // include related known facts (default: true)
  },
);
// POST /agent/memory/search

for (const m of memories) {
  console.log(m.score.toFixed(2), m.text); // higher score = more relevant
}

Each item in memories includes the memory text, its topic / subtopic / tag, an importance, a timestamp, and a relevance score. Each item in facts is a concise subject / predicate / object statement (for example, “Acme → prefers → single monthly invoice”) with a confidence and the date it was first known.

Learn from a document

To seed memory from a larger body of text, such as a document or a page, use memoryLearn. Alfe splits it into pieces and stores what’s worth remembering.

const result = await client.memoryLearn({
  text: longDocumentText,
  source: "onboarding-notes.md",
  sourceType: "file", // "file" | "url" | "inline" (default: "inline")
});
// POST /agent/memory/learn

console.log(`Stored ${result.memoriesStored} memories from ${result.chunks} chunks.`);

Delete a memory

Remove a memory by its id when it’s no longer accurate.

const { deleted } = await client.memoryDelete(memoryId);
// DELETE /agent/memory/{memoryId}

Calling without the client

The client is a thin wrapper over HTTPS requests under /agent/memory/ on the Alfe API host, so you can call the same endpoints from any language. Send the agent’s API key as a bearer token:

Authorization: Bearer <agent-api-key>

See the Agent API overview for the authentication model and the rest of the agent self-service surface.