Skip to main content

​
Entity Memory

​
In plain terms

Entity Memory tracks the things that come up in conversation — companies, people, projects, products — and what the agent knows about each. Where User Facts is about the person you’re talking to, entities are about everyone and everything else they mention.
The analogy: the address book and the company wiki rolled together. “Acme Corp is their employer,” “Raj is the frontend lead,” “Project Atlas is the migration.”

​
When to use it

  • B2B / sales / support — remember the customer’s company, their team members, their projects across conversations.
  • Research / analysis agents — accumulate structured knowledge about companies, people, and products over many sessions.
  • Any domain where the same named things recur and the agent benefits from remembering them.
memory: { storage, entities: true }

​
When NOT to use it

  • Personal preferences about the user → use User Facts.
  • Relationships you need to traverse (“who reports to whom, two levels up”) → use Graph Memory, which is built for multi-hop relationship queries. Entity Memory stores relationships but isn’t optimized for deep traversal.

​
Configuration

PropertyTypeDefaultWhat it controls
namespacestring"global"A label that partitions entities into separate buckets, on top of the automatic per-user scoping
// Default — one shared entity space (per user)
memory: { storage, entities: true }

// Per-team workspace
memory: { storage, entities: { namespace: "acme/engineering" } }
Understanding namespace: entities are always scoped to the user who created them (privacy). namespace adds a second, orthogonal partition — think “team workspace.”
  • Leave it "global" (default) for a single product.
  • Use a per-tenant value ("acme") to keep each organization’s entity knowledge separate.
  • Use a hierarchical path ("acme/engineering") for sub-divisions within a tenant.
Start with the default. Only set a namespace once you actually have separate teams or tenants whose entity knowledge should not mix.

​
What gets stored

Each entity is a structured record with facts, events, and relationships: 
{
  "name": "Stripe",
  "entityType": "company",
  "facts": ["Payment processor", "Used for billing"],
  "events": [{ "event": "Integrated for checkout", "date": "2026-03-01" }],
  "relationships": []
}
Extraction runs automatically after each conversation — the agent identifies entities and stores them. Relevant entities are injected into the prompt on future runs.

​
Tools

ToolWhat it does
search_entitiesFind known entities by name or type
create_entityCreate or update an entity with facts
Both require a userId in context — the agent can never read or write another user’s entities.

​
Direct access

const entities = agent.memory!.getEntityMemory()!;
const all = await entities.listEntities("user-123");
await entities.upsertEntity("user-123", { name: "Acme", entityType: "company" });

​
Cross-references