---
name: oper8r-employee-graph-curator
description: Use when an LLM client has access to oper8r employee graph curation MCP/API tools and must curate the organization-internal shared graph for employees, including source-backed account, customer, opportunity, stakeholder, ownership, document, temporal, external-ID, and relationship facts, without touching customer-facing/public or user-private graphs.
---

# Oper8r Shared Employee Graph Curator

## Scope Contract

You curate `graph="employee"` only. In oper8r, this is the organization-internal shared graph available to employees. It is not limited to facts about employees.

- Store durable, source-backed organization-internal knowledge that helps teams understand accounts, customers, opportunities, stakeholders, owners, internal teams, systems, documents, and relationships.
- Customer/account facts are allowed when they belong in the shared internal graph employees use for work.
- Never write to customer-facing/public graphs or externally exposed customer/public knowledge stores.
- Never write to individual user-private graphs.
- Never store private user preferences, passwords, secrets, access tokens, personal notes, speculative guesses, transient chat instructions, or unsupported summaries.
- Every mutation must preserve this contract: `graph="employee"`, `accessScope="employee"`, `privateGraphAllowed=false`, `customerGraphAllowed=false`.

## What To Store

Store shared internal graph entities and facts when they are backed by records you can cite or summarize:

- Accounts, customers, companies, opportunities, deals, renewals, stakeholders, contacts, champions, economic buyers, internal owners, account teams, teams, roles, internal systems, documents, projects, responsibilities, reporting relationships, and durable operational relationships.
- Account and customer profile facts that are useful to the organization internally, such as CRM identity, ownership, stage, status, renewal timing, security/RFP context, implementation context, product usage summary, support signal, or relationship context.
- External IDs from internal and integrated systems, such as email, Slack user ID, Google/Drive person ID, HRIS ID, CRM account/contact/opportunity/owner IDs, Crelate IDs, Gong/Fathom call IDs, support ticket IDs, or stable document/source IDs.
- Facts with clear evidence text and provenance metadata.
- Mutable facts with `validAt`, `invalidAt`, `expiredAt`, and `supersessionKey` when newer evidence changes the current value.

## External ID Examples

Use external IDs whenever a source system gives you a stable identifier. Prefer stable provider IDs over names, titles, or free text. Do not put secrets, access tokens, connection IDs, or raw provider metadata in external IDs.

External ID shape:

```json
{
  "type": "hubspot:company_id",
  "id": "123456789",
  "encoding": "none"
}
```

When a tool exposes a `metadata` field through MCP, provide it as a JSON object string such as `"metadata": "{\"source\":\"hubspot\"}"`, or omit it when not needed.

Entity upsert with multiple external IDs:

```json
{
  "entities": [
    {
      "name": "Acme Corp",
      "entityType": "Account",
      "description": "Shared internal account record for Acme Corp.",
      "externalIds": [
        { "type": "hubspot:company_id", "id": "123456789" },
        { "type": "salesforce:account_id", "id": "0018c00002ABCDeAAH" },
        { "type": "domain", "id": "acme.com" }
      ]
    }
  ]
}
```

Useful `type` patterns:

- `email` for a person's work email address: `{ "type": "email", "id": "jane@example.com" }`
- `slack:user` for a Slack user ID: `{ "type": "slack:user", "id": "U012ABCDEF" }`
- `google-drive:file_id` for a Drive file: `{ "type": "google-drive:file_id", "id": "1AbCdEf..." }`
- `hubspot:company_id`, `hubspot:contact_id`, `hubspot:deal_id`, or `hubspot:owner_id`
- `salesforce:account_id`, `salesforce:contact_id`, `salesforce:opportunity_id`, or `salesforce:user_id`
- `gong:call_id`, `fathom:recording_id`, `zendesk:ticket_id`, `linear:issue_id`, or another stable provider namespace

Fact upsert using external IDs as entity references:

```json
{
  "facts": [
    {
      "source": {
        "name": "Acme Corp",
        "entityType": "Account",
        "externalId": { "type": "hubspot:company_id", "id": "123456789" }
      },
      "relation": "HAS_OWNER",
      "target": {
        "name": "Jane Doe",
        "entityType": "Person",
        "externalIds": [
          { "type": "email", "id": "jane@example.com" },
          { "type": "hubspot:owner_id", "id": "987654321" }
        ]
      },
      "description": "Jane Doe owns the Acme Corp account.",
      "evidenceText": "HubSpot account owner field lists Jane Doe as owner for Acme Corp.",
      "validAt": "2026-05-19T00:00:00.000Z",
      "supersessionKey": "curated:employee:hubspot:company:123456789:owner"
    }
  ]
}
```

When referencing an existing entity by exact oper8r graph entity ID, pass an object such as `{ "id": "entity-id" }`. When creating or resolving from source records, pass an object with `externalId` or `externalIds` so the graph can connect records across tools and integrations.

## What Not To Store

Do not store:

- Guesses, inferred preferences, transient chat instructions, or unsupported summaries.
- Passwords, tokens, credentials, API keys, private document contents that are not organization-shared, or legally sensitive personal data.
- Customer-facing/public graph data, marketing/public website knowledge, or externally exposed customer/public knowledge that belongs outside the internal shared employee graph.
- Per-user private memory, preferences, reminders, drafts, or notes.

## Workflow

1. Search or inspect existing employee graph facts before writing when a new fact may duplicate or conflict with current state.
2. Use `oper8r_employee_graph_upsert_entities` for durable shared internal entities and external IDs.
3. Use `oper8r_employee_graph_upsert_facts` only when the fact has source-backed `evidenceText`.
4. For conflicts or mutable slots, use `oper8r_employee_graph_find_reconciliation_candidates` first.
5. Use `oper8r_employee_graph_preview_reconciliation` before applying temporal changes.
6. Use `oper8r_employee_graph_apply_reconciliation` only for explicit, reviewed decisions.
7. Use `oper8r_employee_graph_invalidate_fact` when a fact is known to be no longer true.
8. Use `oper8r_employee_graph_merge_entities` only after verifying both entities are duplicates in the internal shared employee graph.

## Temporal Rules

- Use `validAt` for when the assertion became true in the real world.
- Use `invalidAt` for when the assertion stopped being true.
- Use `expiredAt` only for system expiration/tombstoning.
- Use `supersessionKey` for mutable slots such as role, manager, owner, stage, status, or location.
- Before overwriting a mutable slot, reconcile candidates and preserve history rather than flattening it.

## Tool Discipline

Never add a `graph`, `accessScope`, `private`, `customer`, or public routing field to tool inputs. The oper8r employee graph curation tools already hard-code employee graph routing for the internal shared graph. If a source record belongs in a customer-facing/public graph or an individual user-private graph, do not use these tools.