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.

Context and bucket routing

import { GroupId, UserId } from '@typegraph-ai/sdk'

await typegraph.document.ingest(
  [{
    id: 'salesforce:account:acct_123:brief',
    name: 'Acme account brief',
    description: 'CRM account brief for Acme Corp.',
    content: 'Acme Corp is evaluating SSO and needs SOC2 evidence...',
    metadata: { provider: 'salesforce', accountId: 'acct_123' },
  }],
  {
    bucketId: 'salesforce',
    context: {
      userId: UserId('dana'),
      groupId: GroupId('sales'),
    },
  },
)

const response = await typegraph.search('Which customers need SOC2 evidence?', {
  graph: 'internal',
  resources: ['documents', 'entities', 'facts'],
  weights: { semantic: 1, bm25: 0.5, graph: 0.8, recency: 0.3 },
  context: {
    userId: UserId('dana'),
    groupId: GroupId('sales'),
  },
})

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.

Event participants

await typegraph.event.ingest(
  {
    id: 'gong:meeting:123',
    name: 'Acme discovery call',
    description: 'Discovery call about SOC2 blockers and procurement timing.',
    occurredAt: new Date('2026-05-08T17:00:00Z'),
    participants: [
      entityRef('organization', 'org_acme'),
      entityRef('user', 'dana'),
      entityRef('contact', 'alex'),
    ],
    documents: [
      {
        id: 'gong:transcript:123',
        name: 'Acme discovery call transcript',
        description: 'Transcript from the Acme discovery call.',
        content: transcriptText,
        metadata: { provider: 'gong', meetingId: '123' },
      },
    ],
    metadata: { provider: 'gong', meetingId: '123' },
  },
  {
    bucketId: 'gong',
    context: {
      groupId: GroupId('sales'),
    },
  },
)

// participants are provenance.
// bucket.graph controls which graph receives the event and attached documents.

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.

Deterministic graph build

const acme = entityRef('organization', 'org_acme')
const alex = entityRef('contact', 'contact_456')

await typegraph.graph.upsertEntity(
  {
    id: acme.id,
    type: acme.type,
    name: 'Acme Corp',
    description: 'Enterprise account in the sales pipeline.',
    metadata: { crmAccountId: 'acct_123' },
  },
  { context: { groupId: GroupId('sales') } },
)

await typegraph.graph.upsertFact(
  {
    source: alex,
    relation: 'WORKS_FOR',
    target: acme,
    description: 'Alex Lee works for Acme Corp.',
    metadata: { provider: 'salesforce' },
  },
  { context: { groupId: GroupId('sales') } },
)

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.

Graph search

const customerIssues = await typegraph.search('Who is experiencing SSO failures?', {
  graph: 'internal',
  resources: ['events', 'documents', 'entities', 'facts'],
  weights: { semantic: 0.7, bm25: 0.5, graph: 1, recency: 0.6 },
  context: {
    userId: UserId('dana'),
    groupId: GroupId('sales'),
  },
  explain: true,
})

console.log(customerIssues.explanation?.activeResources)
console.log(customerIssues.explanation?.activeWeights)

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.

Back to All Guides

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.

import { GroupId, UserId } from '@typegraph-ai/sdk' await typegraph.document.ingest( [{ id: 'salesforce:account:acct_123:brief', name: 'Acme account brief', description: 'CRM account brief for Acme Corp.', content: 'Acme Corp is evaluating SSO and needs SOC2 evidence...', metadata: { provider: 'salesforce', accountId: 'acct_123' }, }], { bucketId: 'salesforce', context: { userId: UserId('dana'), groupId: GroupId('sales'), }, }, ) const response = await typegraph.search('Which customers need SOC2 evidence?', { graph: 'internal', resources: ['documents', 'entities', 'facts'], weights: { semantic: 1, bm25: 0.5, graph: 0.8, recency: 0.3 }, context: { userId: UserId('dana'), groupId: GroupId('sales'), }, })

await typegraph.event.ingest( { id: 'gong:meeting:123', name: 'Acme discovery call', description: 'Discovery call about SOC2 blockers and procurement timing.', occurredAt: new Date('2026-05-08T17:00:00Z'), participants: [ entityRef('organization', 'org_acme'), entityRef('user', 'dana'), entityRef('contact', 'alex'), ], documents: [ { id: 'gong:transcript:123', name: 'Acme discovery call transcript', description: 'Transcript from the Acme discovery call.', content: transcriptText, metadata: { provider: 'gong', meetingId: '123' }, }, ], metadata: { provider: 'gong', meetingId: '123' }, }, { bucketId: 'gong', context: { groupId: GroupId('sales'), }, }, ) // participants are provenance. // bucket.graph controls which graph receives the event and attached documents.

const acme = entityRef('organization', 'org_acme') const alex = entityRef('contact', 'contact_456') await typegraph.graph.upsertEntity( { id: acme.id, type: acme.type, name: 'Acme Corp', description: 'Enterprise account in the sales pipeline.', metadata: { crmAccountId: 'acct_123' }, }, { context: { groupId: GroupId('sales') } }, ) await typegraph.graph.upsertFact( { source: alex, relation: 'WORKS_FOR', target: acme, description: 'Alex Lee works for Acme Corp.', metadata: { provider: 'salesforce' }, }, { context: { groupId: GroupId('sales') } }, )

const customerIssues = await typegraph.search('Who is experiencing SSO failures?', { graph: 'internal', resources: ['events', 'documents', 'entities', 'facts'], weights: { semantic: 0.7, bm25: 0.5, graph: 1, recency: 0.6 }, context: { userId: UserId('dana'), groupId: GroupId('sales'), }, explain: true, }) console.log(customerIssues.explanation?.activeResources) console.log(customerIssues.explanation?.activeWeights)

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.