Memory

An agent has persistent memory it can read and write through the agent API. Because identity is resolved from the token, an agent only ever touches its own memory.

For a task-focused walkthrough of the everyday calls, see Using memory from the Agent API and How memory works. This page is the complete method reference. All examples use the @alfe.ai/agent-api-client.

Store

Write a single fact. Only text is required; the organizational fields default sensibly.

memory.ts

const { memoryId } = await client.memoryStore("Acme prefers email over calls.", {
  topic: "acme",        // default: "general"
  subtopic: "comms",    // default: "general"
  tag: "preference",    // default: "fact"
  importance: 0.9,      // 0–1, default: 0.7
});
// POST /agent/memory/store  →  { memoryId }

Search

Query memory by meaning. Returns ranked memories plus related facts unless you opt out with includeKnowledge: false.

const { memories, facts } = await client.memorySearch("how does Acme want billing?", {
  limit: 10,            // default: 10
  topic: "acme",        // optional topic / subtopic / tag filters
  includeKnowledge: true, // default: true
});
// POST /agent/memory/search

{
  "data": {
    "memories": [
      {
        "id": "…",
        "text": "Acme prefers a single monthly invoice.",
        "topic": "acme",
        "subtopic": "invoicing",
        "tag": "preference",
        "importance": 0.9,
        "timestamp": 1751370000000,
        "score": 0.82
      }
    ],
    "facts": [
      {
        "subject": "Acme",
        "predicate": "prefers",
        "object": "single monthly invoice",
        "since": "2026-06-01",
        "confidence": 0.9
      }
    ]
  }
}

A higher score means a closer match.

Learn from a document

Ingest a larger body of text — a document, page, or inline content. Alfe splits it into pieces and stores what’s worth remembering, extracting facts as it goes.

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

{ "data": { "memoriesStored": 12, "triplesStored": 8, "chunks": 5, "source": "onboarding-notes.md" } }

Load a context block

Assemble a ready-to-use, formatted memory context block — handy for injecting recall into a prompt.

const { formatted } = await client.memoryLoadContext(1 /* tier */, "acme" /* topicHint */);
// GET /agent/memory/context

Both arguments are optional. Higher tiers include more context.

Navigate the memory graph

Browse the shape of what the agent knows — its topics, how many facts each holds, and its subtopics.

const { topics } = await client.memoryNavigate();
// GET /agent/memory/navigate
// topics: [{ name, tripleCount, subtopics: [...] }]

Look up an entity

Fetch everything the agent knows about one subject as a list of statements.

const { subject, triples } = await client.memoryLookupEntity("Acme");
// GET /agent/memory/knowledge/entities?subject=Acme
// triples: [{ tripleId, predicate, object, validFrom, validTo?, confidence }]

Stats

A quick size read-out of the agent’s memory.

const stats = await client.memoryStats();
// GET /agent/memory/stats

{ "data": { "vectorCount": 340, "tripleCount": 128, "storageEstimateBytes": 91240, "lastIngestionAt": "2026-07-01T12:00:00.000Z" } }

Delete

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

Every method above maps to a request under /agent/memory/ with the Authorization: Bearer header. For example, store a memory with curl:

curl -X POST https://api.alfe.ai/agent/memory/store \
  -H "Authorization: Bearer $ALFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Acme prefers email over calls.","topic":"acme","importance":0.9}'

{ "data": { "memoryId": "…" } }