---
title: "Graph namespacing — blend shared knowledge graphs into memory search"
description: "New graph_ids field on POST /memories/retrieve and POST /memories/search blends named, user-independent knowledge graphs into memory retrieval concurrently with the user's own memory, with per-result provenance."
date: 2026-07-08
tags: ["TIE AI Gateway"]
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash
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_id`s 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](/memory/graph-namespacing/) for naming best practices, the multi-tenant pattern, and full request and response shapes.

Source: https://truememory-docs.mvstg.com/changelog/tie-ai-gateway/2026-07-08-graph-namespacing//index.md