Context, Access, and External IDs
Understand TypeGraph context, graph overlays, graph entities, and deterministic external IDs.
The Mental Model
TypeGraph separates tenant isolation, actor context, graph overlays, and graph relationships.
| Concept | Role | Example |
|---|---|---|
| Tenant | The hard graph and namespace boundary, supplied during init/deploy or by the Cloud X-Tenant-Id header. | TenantId("tenant_acme") |
| Context | The caller identity for a single operation. | { userId: UserId("dana"), groupId: GroupId("sales") } |
| Graph | Logical knowledge boundary inside a tenant. Reads include the graph plus ancestors. | graph: "internal" |
| Bucket | Ingestion/index config and write-graph routing. | { id: "gong", graph: "internal" } |
| Entity refs | Canonical business objects used in participants, graph writes, and memory subjects. | entityRef("organization", "org_acme") |
Record-level access lists are not the primary model. Graph relationships come from documents, events, participants, seeded entities, facts, and provenance links. Graph access comes from graph config.
Write With Context and Buckets
Use one context object on writes. Put actor fields such as organizationId, userId, groupId, agentId, and threadId in context. Choose a bucket to route the write to a graph; omit the bucket to write to public.
Events: Participants Are Provenance
Events model business occurrences. participants capture who or what was involved. They do not grant read access. In a B2B app, this lets you ask broad questions like “Which customers have SSO blockers?” from an internal graph while public users stay on the public graph.
Seed Deterministic Entities and Facts
When your application already knows the graph, seed it directly. Use stable public IDs from your system as entity IDs, and keep structured system data in metadata.
Search From A Graph Perspective
Search chooses a graph perspective. Searching public only sees public data. Searching a child graph such as internal sees that graph plus its ancestors.
Common Patterns
| Scenario | Recommended Shape |
|---|---|
| Separate customer graphs | Use separate tenantId values. |
| Shared public docs | Use the public bucket and graph. |
| Internal-only records | Route the bucket to graph internal and grant graph access to internal groups. |
| Personal agent memory | Use typegraph.memory.* with context.userId or context.agentId; memory writes into a private memory graph. |
| Thread-specific turns | Use thread.addTurn(threadId, { role, content, timestamp, metadata }, { context }). |
| CRM account graph | Use entityRef("organization", "org_acme") in participants, facts, and seeded entities. |