Using memory from the Agent API

Memory is available programmatically through the agent self-service API. The easiest way to call it is the official client, @alfe.ai/agent-api-client, which authenticates with the agent’s own API key. Because the agent’s identity is resolved from its token, an agent can only ever read and write its own memory.

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 usually don’t need to store memories by hand — the agent learns from its conversations automatically (see How memory works). Use memoryStore when you want to guarantee a specific fact is remembered.

Search memory

Query memory by meaning. Results come back ranked by relevance, and — unless you opt out — 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 — a document, a page, or any inline content — use memoryLearn. Alfe splits it into digestible 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 plain 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.