HarnessRouter Community Edition: the self-hosted, Apache-2.0 edition of the unified interface for agent harnesses. Run Codex, Claude Code, Hermes, PI, DSH, and more through one API, with sessions, streaming, files, cancellation, and failure handling. Implements the Unified Harness Protocol (UHP), an open standard. Your keys, your infrastructure.
Python agent-apiagent-frameworkagent-harnessai-agentsai-infrastructurecoding-agentconformance-testingdeepseek-harnessharness-engineeringhermesllmopen-protocolopen-sourceopen-standardpi-coding-agentself-hosteduhpunified-apiunified-harness-protocolunified-interface
UHP 2026-10-04: one graph. Entities are records, relationships are references (#392)
github-actions[bot]ca68fcc18aed
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.mdindex 8640df89..115b9a4c 100644--- a/protocol/CHANGELOG.md+++ b/protocol/CHANGELOG.md@@ -58,6 +58,18 @@ sets two things: `default_memory_id` and `observe`. An agent joins a group onlyit. Kinds are now `member`, `group` and, for a writer only, `provider`. Schema: `HarnessMemories`reshaped, `HarnessMemorySettings` added, `HarnessMemoryEntry` removed. Suite `2026.10.4.post5`.+**Sixth patch of 2026-10-04, same version.** One graph. Entities and the relationships between+them are not a second structure beside records: an entity is a record (new core type `entity`), a+reference is an edge, and a relationship with something to say is a `fact` that references its+`subject` and its `object`, so it has a writer, a time, a history and a source like any record.+Five reference names are defined (`derived_from`, `part_of`, `about`, `subject`, `object`). One+read, `POST /v1/memories/{id}/graph`, returns records as nodes and references as edges around a+record or for a memory, the same for every provider; a provider declares where its entities come+from in `graph.entities` (`derived`, `stated`, `none`). Also: an agent's membership of a group+follows the rule a person's does (the fifth patch forbade a server to place an agent in a group on+its own, which is not equal standing where every new person joins one). Schema: `MemoryGraph`,+`MemoryGraphRequest`, `MemoryRecordRef`. Suite `2026.10.4.post6`: ME-10.+- **Memories** ([Memories](versions/2026-10-04/memories.md)), the Harness Memories sub-protocol,optional at every class behind the `memories` capability. A memory is a named node in a tree:it holds records and may have child memories. A grant gives a principal privileges (`read`,diff --git a/protocol/conformance/pyproject.toml b/protocol/conformance/pyproject.tomlindex 075dcd22..9fa06f96 100644--- a/protocol/conformance/pyproject.toml+++ b/protocol/conformance/pyproject.toml@@ -1,6 +1,6 @@[project]name = "uhp-conformance"-version = "2026.10.4.post5"+version = "2026.10.4.post6"description = "Conformance suite for the Unified Harness Protocol (UHP)"readme = "README.md"requires-python = ">=3.10"diff --git a/protocol/conformance/uhp_conformance/checks.py b/protocol/conformance/uhp_conformance/checks.pyindex 456ef5e4..0b95b2c5 100644--- a/protocol/conformance/uhp_conformance/checks.py+++ b/protocol/conformance/uhp_conformance/checks.py@@ -2244,6 +2244,49 @@ def me09(ctx):return "text parts in order; a png kept with its description and read back byte for byte"+@check("ME-10", "Entities and relationships are records and references, read as one graph", "full",+ f"{SPEC}/memories.md#66-the-graph")+def me10(ctx):+ prov = _memories_supported(ctx)+ child = _memory_child(ctx)+ if ((prov.get("graph") or {}).get("entities") or "none") == "none":+ raise Skip("this provider keeps no record of type entity (graph.entities is none)")+ base = f"/v1/memories/{child['id']}"++ def mk(**body):+ r = ctx.client.post(base + "/records", body=body)+ assert r.status == 200, f"POST records ({body.get('type')}) returned HTTP {r.status}: {r.text[:200]}"+ return r.json or {}+ tag = uuid.uuid4().hex[:6]+ a = mk(type="entity", content=f"Ines Varga {tag}")+ b = mk(type="entity", content=f"Harlow Mills {tag}")+ assert a.get("type") == "entity", f"an entity is a core record type; it read back as {a.get('type')!r}"+ f = mk(type="fact", content=f"Ines Varga {tag} runs purchasing at Harlow Mills {tag}.", attributes={"predicate": "works_at"},+ references=[{"rel": "subject", "record_id": a["id"]}, {"rel": "object", "record_id": b["id"]}])+ deadline, g = time.time() + 40, {}+ while True:+ r = ctx.client.post(base + "/graph", body={"around": a["id"], "hops": 2})+ assert r.status == 200, f"POST graph returned HTTP {r.status}: {r.text[:200]}"+ g = r.json or {}+ if {a["id"], b["id"], f["id"]} <= {(n.get("record") or {}).get("id") for n in g.get("nodes") or []} or time.time() > deadline:+ break+ time.sleep(2)+ ctx.validate(g, "MemoryGraph")+ ids = {(n.get("record") or {}).get("id"): n for n in g.get("nodes") or []}+ assert {a["id"], b["id"], f["id"]} <= set(ids), "two hops from an entity must reach the fact about it and the entity at its other end"+ assert (ids[b["id"]].get("memory") or {}).get("id") == child["id"], "a node names the memory its record is in"++ def edge(rel, to):+ return any(e.get("rel") == rel and (e.get("from") or {}).get("record_id") == f["id"]+ and (e.get("to") or {}).get("record_id") == to and e.get("available") is True for e in g.get("edges") or [])+ assert edge("subject", a["id"]) and edge("object", b["id"]), (+ "the fact's references must be edges from the fact to its subject and to its object")+ one = ctx.client.post(base + "/graph", body={"around": a["id"], "hops": 1}).json or {}+ assert b["id"] not in {(n.get("record") or {}).get("id") for n in one.get("nodes") or []}, (+ "one hop from the subject reached the object: the fact between them is a node, one hop away")+ return f"{len(g.get('nodes') or [])} nodes, {len(g.get('edges') or [])} edges around {a['id']} on entities={prov['graph']['entities']}"++@check("ME-08", "A memory moves with its subtree, and deleting it takes the subtree", "full",f"{SPEC}/memories.md#2-the-memory-object")def me08(ctx):diff --git a/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json b/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.jsonindex d47ffa23..96092ba6 100644--- a/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json+++ b/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json@@ -2733,6 +2733,125 @@},"additionalProperties": true},+ "MemoryGraphRequest": {+ "type": "object",+ "properties": {+ "around": {+ "type": "string",+ "description": "A record to start from. Left out, every record of this memory."+ },+ "hops": {+ "type": "integer",+ "minimum": 0,+ "maximum": 3,+ "description": "References away from the start, in either direction. Default 1."+ },+ "types": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "limit": {+ "type": "integer",+ "minimum": 1+ }+ }+ },+ "MemoryRecordRef": {+ "type": "object",+ "required": [+ "memory_id",+ "record_id"+ ],+ "properties": {+ "memory_id": {+ "type": "string"+ },+ "record_id": {+ "type": "string"+ }+ }+ },+ "MemoryGraph": {+ "type": "object",+ "required": [+ "nodes",+ "edges",+ "truncated"+ ],+ "properties": {+ "object": {+ "type": "string",+ "const": "memory.graph"+ },+ "nodes": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "record",+ "memory"+ ],+ "properties": {+ "record": {+ "$ref": "#/$defs/MemoryRecord"+ },+ "memory": {+ "type": "object",+ "required": [+ "id"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "name": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "from",+ "to",+ "available"+ ],+ "properties": {+ "from": {+ "$ref": "#/$defs/MemoryRecordRef"+ },+ "to": {+ "$ref": "#/$defs/MemoryRecordRef"+ },+ "rel": {+ "type": "string",+ "description": "What the reference means. Absent when the target is not readable by the caller."+ },+ "available": {+ "type": "boolean"+ }+ }+ }+ },+ "truncated": {+ "type": "boolean"+ },+ "degraded": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "additionalProperties": true+ },"MemoryErase": {"type": "object","required": [@@ -3042,6 +3161,21 @@"type": "object","additionalProperties": true},+ "graph": {+ "type": "object",+ "properties": {+ "entities": {+ "type": "string",+ "enum": [+ "derived",+ "stated",+ "none"+ ],+ "description": "Where a memory's entities come from on this provider."+ }+ },+ "additionalProperties": true+ },"content": {"type": "object","description": "What the content of a record may carry on this provider.",diff --git a/protocol/schema/uhp-2026-10-04.openapi.yaml b/protocol/schema/uhp-2026-10-04.openapi.yamlindex 592a81eb..acb61e4f 100644--- a/protocol/schema/uhp-2026-10-04.openapi.yaml+++ b/protocol/schema/uhp-2026-10-04.openapi.yaml@@ -947,6 +947,27 @@ paths:schema: { $ref: '#/components/schemas/MemoryRecall' }'404': { $ref: '#/components/responses/NotFound' }+ /v1/memories/{memory_id}/graph:+ parameters:+ - $ref: '#/components/parameters/MemoryId'+ post:+ tags: [Memories]+ operationId: graphMemory+ summary: "Records as nodes and their references as edges"+ description: "Needs `read`. Around one record or for the whole memory. Entities are records of type `entity`; a relationship with something to say is a `fact` that references its `subject` and its `object`. A target the caller may not read is an edge marked unavailable and never a node."+ requestBody:+ required: true+ content:+ application/json:+ schema: { $ref: '#/components/schemas/MemoryGraphRequest' }+ responses:+ '200':+ description: OK+ content:+ application/json:+ schema: { $ref: '#/components/schemas/MemoryGraph' }+ '404': { $ref: '#/components/responses/NotFound' }+/v1/memories/{memory_id}/erase:parameters:- $ref: '#/components/parameters/MemoryId'@@ -2855,6 +2876,50 @@ components:degraded: { type: array, items: { type: string }, description: What the request asked for and was not done. }abstain: { type: boolean, description: True when the provider judges that nothing it returned answers the question. }additionalProperties: true+ MemoryGraphRequest:+ type: object+ properties:+ around: { type: string, description: 'A record to start from. Left out, every record of this memory.' }+ hops: { type: integer, minimum: 0, maximum: 3, description: 'References away from the start, in either direction. Default 1.' }+ types: { type: array, items: { type: string } }+ limit: { type: integer, minimum: 1 }+ MemoryRecordRef:+ type: object+ required: [memory_id, record_id]+ properties:+ memory_id: { type: string }+ record_id: { type: string }+ MemoryGraph:+ type: object+ required: [nodes, edges, truncated]+ properties:+ object: { type: string, const: memory.graph }+ nodes:+ type: array+ items:+ type: object+ required: [record, memory]+ properties:+ record: { $ref: '#/components/schemas/MemoryRecord' }+ memory:+ type: object+ required: [id]+ properties:+ id: { type: string }+ name: { type: string }+ edges:+ type: array+ items:+ type: object+ required: [from, to, available]+ properties:+ from: { $ref: '#/components/schemas/MemoryRecordRef' }+ to: { $ref: '#/components/schemas/MemoryRecordRef' }+ rel: { type: string, description: 'What the reference means. Absent when the target is not readable by the caller.' }+ available: { type: boolean }+ truncated: { type: boolean }+ degraded: { type: array, items: { type: string } }+ additionalProperties: trueMemoryErase:type: objectrequired: [record_ids]@@ -2956,6 +3021,11 @@ components:history: { type: object, additionalProperties: true }erase: { type: object, additionalProperties: true }queries: { type: object, additionalProperties: true }+ graph:+ type: object+ properties:+ entities: { type: string, enum: [derived, stated, none], description: 'Where a memory''s entities come from on this provider.' }+ additionalProperties: truecontent:type: objectdescription: What the content of a record may carry on this provider.diff --git a/protocol/schema/uhp-2026-10-04.schema.json b/protocol/schema/uhp-2026-10-04.schema.jsonindex d47ffa23..96092ba6 100644--- a/protocol/schema/uhp-2026-10-04.schema.json+++ b/protocol/schema/uhp-2026-10-04.schema.json@@ -2733,6 +2733,125 @@},"additionalProperties": true},+ "MemoryGraphRequest": {+ "type": "object",+ "properties": {+ "around": {+ "type": "string",+ "description": "A record to start from. Left out, every record of this memory."+ },+ "hops": {+ "type": "integer",+ "minimum": 0,+ "maximum": 3,+ "description": "References away from the start, in either direction. Default 1."+ },+ "types": {+ "type": "array",+ "items": {+ "type": "string"+ }+ },+ "limit": {+ "type": "integer",+ "minimum": 1+ }+ }+ },+ "MemoryRecordRef": {+ "type": "object",+ "required": [+ "memory_id",+ "record_id"+ ],+ "properties": {+ "memory_id": {+ "type": "string"+ },+ "record_id": {+ "type": "string"+ }+ }+ },+ "MemoryGraph": {+ "type": "object",+ "required": [+ "nodes",+ "edges",+ "truncated"+ ],+ "properties": {+ "object": {+ "type": "string",+ "const": "memory.graph"+ },+ "nodes": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "record",+ "memory"+ ],+ "properties": {+ "record": {+ "$ref": "#/$defs/MemoryRecord"+ },+ "memory": {+ "type": "object",+ "required": [+ "id"+ ],+ "properties": {+ "id": {+ "type": "string"+ },+ "name": {+ "type": "string"+ }+ }+ }+ }+ }+ },+ "edges": {+ "type": "array",+ "items": {+ "type": "object",+ "required": [+ "from",+ "to",+ "available"+ ],+ "properties": {+ "from": {+ "$ref": "#/$defs/MemoryRecordRef"+ },+ "to": {+ "$ref": "#/$defs/MemoryRecordRef"+ },+ "rel": {+ "type": "string",+ "description": "What the reference means. Absent when the target is not readable by the caller."+ },+ "available": {+ "type": "boolean"+ }+ }+ }+ },+ "truncated": {+ "type": "boolean"+ },+ "degraded": {+ "type": "array",+ "items": {+ "type": "string"+ }+ }+ },+ "additionalProperties": true+ },"MemoryErase": {"type": "object","required": [@@ -3042,6 +3161,21 @@"type": "object","additionalProperties": true},+ "graph": {+ "type": "object",+ "properties": {+ "entities": {+ "type": "string",+ "enum": [+ "derived",+ "stated",+ "none"+ ],+ "description": "Where a memory's entities come from on this provider."+ }+ },+ "additionalProperties": true+ },"content": {"type": "object","description": "What the content of a record may carry on this provider.",diff --git a/protocol/versions/2026-10-04/index.md b/protocol/versions/2026-10-04/index.mdindex 5407dee3..a274ce7c 100644--- a/protocol/versions/2026-10-04/index.md+++ b/protocol/versions/2026-10-04/index.md@@ -81,6 +81,7 @@ the [protocol README](../../README.md).| `GET` | `/v1/memories/{id}/records/{rid}/content/{index}` | Full, capability `memories` | [Memories](memories.md) || `POST` | `/v1/memories/{id}/records/{rid}/operations/{name}` | Full, capability `memories` | [Memories](memories.md) || `POST` | `/v1/memories/{id}/recall` | Full, capability `memories` | [Memories](memories.md) |+| `POST` | `/v1/memories/{id}/graph` | Full, capability `memories` | [Memories](memories.md) || `POST` | `/v1/memories/{id}/erase` | Full, capability `memories` | [Memories](memories.md) || `GET` | `/v1/memories/{id}/queries` | Full, capability `memories` | [Memories](memories.md) || `PUT` `POST` | `/v1/memories/{id}/queries/{name}` | Full, capability `memories` | [Memories](memories.md) |diff --git a/protocol/versions/2026-10-04/memories.md b/protocol/versions/2026-10-04/memories.mdindex dfc44002..d4d8ad50 100644--- a/protocol/versions/2026-10-04/memories.md+++ b/protocol/versions/2026-10-04/memories.md@@ -112,8 +112,8 @@ may act, and a record's `written_by` names who did.**A person and an agent are the same kind.** Both are members, granted the same way, checked thesame way, and able to belong to the same groups. Which of the two a member is, is a property ofthe member, `type`: `human` or `agent`. It is carried for a reader who wants to know, and no rule-of this chapter depends on it. An agent belongs to a group when someone adds it, as a person does;-a server MUST NOT place an agent in a group on its own.+of this chapter depends on it. A server treats an agent's membership of a group exactly as it treats a person's: whatever puts a+new person in a group puts a new agent there, and nothing else does.A kind of a server's own is `x.`-prefixed (`x.team`). A server MUST NOT use another unprefixedkind, and refuses a grant that names one.@@ -211,6 +211,7 @@ The core types every server understands:| `note` | A document an agent or a person wrote and maintains || `procedure` | A how-to with the situation it applies to || `link` | A pointer to something kept elsewhere: an address and a description, no content of its own |+| `entity` | Something records are about: a person, a company, a product, a place. Its content is its name and what is known of it in a line or two |Any other type is an extension ([§8](#8-types)). A server MUST carry a record of a type it does notunderstand unchanged, and MUST NOT refuse a read because of it.@@ -226,6 +227,32 @@ memory, or with the same provider.- Writing a reference does not require `read` on its target. A record promoted from a privatememory into a shared one keeps its source, and only those who may read the source can follow it.+**Records and references are the graph.** There is no second structure for entities and+relationships: a record is a node, and a reference is an edge from the record that holds it to the+record it names. `rel` says what the edge means. Five names have a defined meaning; any other is+carried unchanged.++| `rel` | From | To | Meaning |+|---|---|---|---|+| `derived_from` | any record | the record it came from | Provenance: this was concluded from that |+| `part_of` | any record | the record it belongs to | Structure: a section of a document, a turn of a conversation |+| `about` | any record | an `entity` | This record concerns that entity |+| `subject` | a `fact` | an `entity` | Who or what the fact says something of |+| `object` | a `fact` | an `entity` | Who or what it relates the subject to |++A relationship between two entities that has something to say is therefore a **`fact`** with a+`subject` and an `object`: "Dana is head of procurement at Quillon Freight" is a fact whose subject+is the entity Dana and whose object is the entity Quillon Freight. Being a record, it has what+every record has: a writer, a time it was true, a history, a way to be corrected and forgotten, and+its own `derived_from` to the conversation it came from. A client MAY draw such a fact as one line+between its two entities, labelled with the fact's text or its `attributes.predicate`. A+relationship with nothing to say, such as a section belonging to its document, is a bare reference+and needs no record of its own.++A provider keeps the entities and relationships it has and no more+([§10.2](#102-the-capability-document)). One that keeps none still has a graph: its records and+the references between them.+### 4.3 ContentA record's `content` is an ordered list of **parts**. Two kinds of part are defined:@@ -276,6 +303,7 @@ A record's `content` is an ordered list of **parts**. Two kinds of part are defi| `GET /v1/memories/{id}/jobs/{job}` | What an `observe` that answered `202` has written since || `POST /v1/memories/{id}/records` | **remember**: write one record as stated || `POST /v1/memories/{id}/recall` | **recall**: search this memory and what is below it ([§6](#6-recall)) |+| `POST /v1/memories/{id}/graph` | **graph**: records as nodes and their references as edges, around one record or for the whole memory ([§6.6](#66-the-graph)) || `GET /v1/memories/{id}/records` | List the records, paginated; accepts `type`, `include` and `as_of` || `GET /v1/memories/{id}/records/{rid}` | One record; accepts `as_of` || `GET /v1/memories/{id}/records/{rid}/history` | **history**: every version of a record, oldest first, each with its writer and time |@@ -462,6 +490,55 @@ out the condition that confines it, so the confinement cannot be in the statemen- The server MAY bound a free query's time and result size and reports a bound it applied in`degraded`.+### 6.6 The graph++One read returns records and the references between them as nodes and edges, for a client that+draws them or an agent that asks what something is connected to.++```json+{ "around": "hrec_dana…", "hops": 2, "types": ["entity", "fact"], "limit": 200 }+```++| Field | Meaning |+|---|---|+| `around` | A record to start from. Left out, the start is every record of this memory |+| `hops` | How many references away to go, in either direction: `0` to `3`, default `1` |+| `types` | Return only nodes of these types |+| `limit` | The most nodes to return |++```json+{+ "object": "memory.graph",+ "nodes": [+ { "record": { "id": "hrec_dana…", "type": "entity", "content": [ … ] },+ "memory": { "id": "hmem_55d1…", "name": "Acme" } },+ { "record": { "id": "hrec_job…", "type": "fact", "content": [ … ] },+ "memory": { "id": "hmem_55d1…", "name": "Acme" } }+ ],+ "edges": [+ { "from": { "memory_id": "hmem_55d1…", "record_id": "hrec_job…" },+ "to": { "memory_id": "hmem_55d1…", "record_id": "hrec_dana…" },+ "rel": "subject", "available": true },+ { "from": { "memory_id": "hmem_55d1…", "record_id": "hrec_job…" },+ "to": { "memory_id": "hmem_9f02…", "record_id": "hrec_77a1…" },+ "available": false }+ ],+ "truncated": false,+ "degraded": []+}+```++- A node is a record as any read returns it, with the memory it is in. An edge is a reference:+ `from` the record that holds it, `to` the record it names.+- Records are looked for in this memory and in what is below it that the caller may read, as a+ search does. An edge may lead into any memory. Its target is a node only when the caller may+ read it; otherwise the edge is returned with `"available": false` and without its `rel`, and the+ target is not a node. This is the rule of [§4.2](#42-references), unchanged.+- `truncated` is `true` when there were more nodes than `limit`. `degraded` says what was cut+ short, as a search's does.+- The graph is the same for every provider because it is made of what every provider has. What+ differs is how much is in it.+## 7. FilesA file enters a memory as a part of a record's content ([§4.3](#43-content)): uploaded as@@ -649,6 +726,7 @@ GET /v1/memories/providers"queries": { "named": true,"free": { "languages": ["cypher"], "write": false } },"types": true,+ "graph": { "entities": "derived" },"content": { "media": ["text/*", "image/*"], "bytes": "referenced","describes": ["image/*"] }} ] }@@ -660,6 +738,10 @@ GET /v1/memories/providersreported as `emulated`, never as `native`.- **A gap is declared.** A provider without full-text reports `signals` without `text`, and arequest that names it is answered with `degraded`.+- **`graph.entities`** says where a memory's entities come from: `derived` (the provider finds+ them in what it is given and relates them itself), `stated` (it keeps the ones a writer states+ and finds none of its own) or `none` (it keeps no record of that type). The graph read+ ([§6.6](#66-the-graph)) works on all three.### 10.3 What an adapter owes@@ -708,8 +790,10 @@ chapter reports `false` or omits it and answers its endpoints with `404`.reach either way is every memory it holds a privilege on, no more, checked by the serveron every call and for every memory a search covers. An agent that should see one branch andnothing above it is granted that branch and nothing above it.-- **An agent is granted on purpose.** It starts with nothing, and joins a group only when someone- adds it. Equal standing with a person does not mean an agent inherits what people share.+- **An agent stands where a person stands.** It reaches what it was granted and what the groups it+ belongs to were granted, and it joins a group by the same rule a person does. A server that puts+ every new person in a group puts every new agent there too, and should say so where an agent is+ created: that agent can read what the group was given from its first turn.- **Provenance is stamped, not supplied.** `written_by` and `written_at` come from the authenticatedcaller and the server's clock.- **Unknown is indistinguishable from forbidden** on reads of memories and of reference targets.