> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity Memory

> Remember the companies, people, projects, and products mentioned in conversations.

# 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](/memory/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.

```typescript theme={null}
memory: { storage, entities: true }
```

## When NOT to use it

* **Personal preferences about the user** → use [User Facts](/memory/user-facts).
* **Relationships you need to *traverse*** ("who reports to whom, two levels up") → use [Graph Memory](/memory/graph-memory), which is built for multi-hop relationship queries. Entity Memory stores relationships but isn't optimized for deep traversal.

## Configuration

| Property    | Type     | Default    | What it controls                                                                                 |
| ----------- | -------- | ---------- | ------------------------------------------------------------------------------------------------ |
| `namespace` | `string` | `"global"` | A label that partitions entities into separate buckets, on top of the automatic per-user scoping |

```typescript theme={null}
// 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.

<Tip>Start with the default. Only set a `namespace` once you actually have separate teams or tenants whose entity knowledge should not mix.</Tip>

## What gets stored

Each entity is a structured record with facts, events, and relationships:

```json theme={null}
{
  "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

| Tool              | What it does                          |
| ----------------- | ------------------------------------- |
| `search_entities` | Find known entities by name or type   |
| `create_entity`   | Create 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

```typescript theme={null}
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](/memory/graph-memory) — when you need to *traverse* relationships
* [User Facts](/memory/user-facts) — facts about the user, not external entities
* [Multi-User Isolation](/memory/isolation) — entity scoping rules