​

Entity Memory

​

In plain terms

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

// Default — one shared entity space (per user)
memory: { storage, entities: true }

// Per-team workspace
memory: { storage, entities: { namespace: "acme/engineering" } }

• 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.

​

What gets stored

{
  "name": "Stripe",
  "entityType": "company",
  "facts": ["Payment processor", "Used for billing"],
  "events": [{ "event": "Integrated for checkout", "date": "2026-03-01" }],
  "relationships": []
}

​

Tools

​

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

• Graph Memory — when you need to traverse relationships
• User Facts — facts about the user, not external entities
• Multi-User Isolation — entity scoping rules