# Cross-layer linking

How authoritative documents and experiential facts relate in the unified graph.

Authoritative and experiential memory live in **one graph**. Document extraction and turn extraction both produce `entity`, `attribute`, and `relation` records. Provenance (`source.kind`, `source.ref`, `source.span`) records whether a fact came from a **document** or a **turn**.

## How linking works

**Same entity, multiple sources.** When a user mentions “AirPods Pro” in chat and the product manual is uploaded as a document, extraction may create or update the same `entity` (for example `Product/airpods_pro`) with:

- Turn-sourced attributes (`source.kind = "turn"`) - “purchased last week”
- Document-sourced attributes (`source.kind = "document"`) - “return_policy = 30 days”

The **reconciler** applies authority and calibration rules: cross-provenance conflicts emit **`uncertainty`** records instead of silent overwrites; same-provenance updates form supersession chains (`valid_until` on the prior assertion).

**Unified recall.** `POST /api/v1/{ctx}/query` ranks across facts and document passages in one router (structured lookup → response cache → hybrid retrieval → full-context fallback). Filter with `include` (facts vs passages) when you need a narrower slice.

**Elaboration.** Background **elaboration** can add `relation` edges between entities ingested from different sources but sharing context.

## Operational implications

| Task | Approach |
| --- | --- |
| Ground an agent on manuals | Upload documents; recall with `/query` |
| Capture conversation | `POST /facts` or `/facts/batch` |
| Prefer curated policy over chat hearsay | Trust and confidence floors; higher default trust for documents |
| Debug a conflict | Inspect `uncertainty` records and entity history |

## Manual entity maintenance

```http
GET /api/v1/{context_id}/entities/{entity_type}/{entity_name}
DELETE /api/v1/{context_id}/entities/{entity_type}/{entity_name}
```

Two **streams** in one store are described in [Unified substrate and authority](/docs/agent-memory/mental-model/two-layer-architecture.md).