Graph namespacing — blend shared knowledge graphs into memory search

Memory retrieval can now draw on knowledge that belongs to no user. A graph namespace is a named knowledge graph — a product catalog, company policies, a coaching methodology — identified by a freeform graph_id slug. Pass up to four of them and TIE blends their facts with the user’s own memory:

POST /memories/retrieve
{
  "query": "what running program fits a beginner",
  "agent_id": "chatbot",
  "graph_ids": ["acme__coaching_kb"]
}

What it does

• The user’s graph and each namespace are searched concurrently, then fused into one ranked list. When a user fact and a namespace fact are equally relevant, the user fact wins.
• Every result carries provenance: scope: "user", or scope: "graph" plus the graph_id it came from. Existing callers are unaffected — omit graph_ids and responses are unchanged.
• The same field works on POST /memories/search for raw ranked fact edges without the context block.
• A namespace that is empty, unknown, or unreachable contributes nothing; user results always come back. Malformed ids fail fast with 400 VALIDATION_ERROR.

Populate a namespace

POST /memories/graph accepts a graph_id target instead of agent_id — provide exactly one. Namespace writes require a service token; ingestion is asynchronous with the existing job_id polling contract, and writers to one namespace serialize cluster-wide. Namespaces are never written automatically — chat auto-ingest and the memory_write agent tool only touch the user’s own graph.

Use a namespace in chat

POST /v1/chat/completions accepts graph_ids — TIE blends namespace facts into the injected memory context for that turn. Read-only: conversation ingestion still targets the user’s graph.

Inspect and manage a namespace

• GET /memories/graph?graph_id=… and GET /memories/timeline?graph_id=… show one namespace on its own — no user data, no subject user required, so service-only tokens work. Omit graph_id for the user’s own view; graph_id and agent_id are mutually exclusive. This maps directly onto a dashboard filter: “my memories” versus “organization”.
• DELETE /memories/{agent_id}/{memory_id}?graph_id=… and merge with a body graph_id operate on namespace facts. Both require a service token — namespace changes affect every reader; end-user tokens receive 403 AUTH_SERVICE_REQUIRED.

Naming rules

graph_ids are lowercase slugs (letters, digits, underscores, hyphens; 3–64 characters; starts with a letter). A bare leading UUID is rejected — that shape is reserved for user memory scopes. For UUID-based uniqueness, prefix it: org_9f8e4b2a-….

Caveats

• Whole-namespace lifecycle ships separately. Listing all namespaces and exporting or deleting an entire namespace are not in this release; individual fact delete/merge are.
• Never written automatically. Chat auto-ingest and the memory_write agent tool only touch the user’s own graph.

See Graph Namespacing for naming best practices, the multi-tenant pattern, and full request and response shapes.