Skip to content

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.

UHP 2026-10-04: recall searches the subtree, and each result names its memory (#388)

github-actions[bot]fe0829d36a9a
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index 53c3a270..55c69df7 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -29,6 +29,15 @@ its own folders) could meet only with a second id space and a lookup between the
remains the prefix of a server that mints its own ids. Schema: the pattern is gone from `Memory.id`,
the path parameter and a harness's entry. Suite `2026.10.4.post2`: ME-01 no longer asserts the prefix.
+**Third patch of 2026-10-04, same version.** `recall` searches the memory **and everything below it
+the caller may read**; the morning's text had it act on one memory. A search is how a caller finds
+where something is kept, so each result now carries `memory` (`id`, `name`): the place to walk
+from. It never searches an ancestor. `depth` narrows it (`0` is the memory alone; it used to widen,
+from a default of one memory). A server MAY cap the memories one question covers and says so in
+`degraded`. `list`, `get`, `history` and the queries still act on one memory. The provider
+capability `recall.max_depth` is gone: the subtree is the server's to compose. Schema:
+`MemoryRecall.results[].memory` is required. Suite `2026.10.4.post3`: ME-03 rewritten.
+
- **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.toml
index b52f9830..77257e9b 100644
--- a/protocol/conformance/pyproject.toml
+++ b/protocol/conformance/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "uhp-conformance"
-version = "2026.10.4.post2"
+version = "2026.10.4.post3"
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.py
index 5c93d1c5..69cc2f66 100644
--- a/protocol/conformance/uhp_conformance/checks.py
+++ b/protocol/conformance/uhp_conformance/checks.py
@@ -2060,25 +2060,41 @@ def me02(ctx):
return f"{rec['id']} written by {rec.get('written_by')}"
-@check("ME-03", "Recall acts on one memory and says where the caller can go from there", "full",
- f"{SPEC}/memories.md#61-reading-is-a-walk")
+@check("ME-03", "A question covers the memory and what is below it, names where each answer is, and never looks above", "full",
+ f"{SPEC}/memories.md#61-search-finds-the-place-then-the-agent-walks")
def me03(ctx):
prov = _memories_supported(ctx)
rec, root, child = _memory_fact(ctx), ctx.state["memory_root"], ctx.state["memory_child"]
signals = (prov.get("recall") or {}).get("signals") or []
body = {"query": "when does Quillon Freight renew?"} if "query" in signals else {"text": "Quillon"}
+ hit = lambda res: next((x for x in res.get("results") or [] if (x.get("record") or {}).get("id") == rec["id"]), None) # noqa: E731
res = _recall_until(ctx, child["id"], body, rec["id"])
ctx.validate(res, "MemoryRecall")
- assert any((x.get("record") or {}).get("id") == rec["id"] for x in res.get("results") or []), (
- f"the record was not recalled from its own memory with {body}")
+ assert hit(res), f"the record was not recalled from its own memory with {body}"
assert (res.get("parent") or {}).get("id") == root["id"], "a recall must name the parent the caller may read"
- up = ctx.client.post(f"/v1/memories/{root['id']}/recall", body=body).json or {}
- assert not any((x.get("record") or {}).get("id") == rec["id"] for x in up.get("results") or []), (
- "a recall on the parent returned a record of the child: a read acts on one memory and does not descend")
+ # asked of the parent, the record below is found, and the result says which memory holds it
+ up = _recall_until(ctx, root["id"], body, rec["id"])
+ ctx.validate(up, "MemoryRecall")
+ found = hit(up)
+ assert found, "a question asked of the parent did not find the record in its child: recall covers the subtree"
+ assert (found.get("memory") or {}).get("id") == child["id"], (
+ f"the result names memory {(found.get('memory') or {}).get('id')!r}, the record is in {child['id']!r}")
kid = next((c for c in up.get("children") or [] if c.get("id") == child["id"]), None)
assert kid and kid.get("description") == "what is known about each account", (
"a recall must name the children the caller may read, each with its description")
- return f"found in {child['id']}, absent from {root['id']}, which names {len(up.get('children') or [])} child"
+ # depth 0 is the memory alone
+ alone = ctx.client.post(f"/v1/memories/{root['id']}/recall", body={**body, "depth": 0}).json or {}
+ assert not hit(alone), "depth 0 returned a record of a child"
+ # and nothing looks above: a record stated in the parent is not found from the child
+ marker = "Vellacourt" + uuid.uuid4().hex[:6]
+ top = ctx.client.post(f"/v1/memories/{root['id']}/records", body={"type": "fact", "content": f"{marker} is the parent's own fact."})
+ assert top.status == 200, f"POST records on the parent answered {top.status}"
+ probe = {"query": f"what is {marker}?"} if "query" in signals else {"text": marker}
+ _recall_until(ctx, root["id"], {**probe, "depth": 0}, top.json["id"])
+ below = ctx.client.post(f"/v1/memories/{child['id']}/recall", body=probe).json or {}
+ assert not any((x.get("record") or {}).get("id") == top.json["id"] for x in below.get("results") or []), (
+ "a recall on the child returned a record of its parent: a question never looks above")
+ return f"found from {root['id']} in {child['id']}; depth 0 and the upward direction hold"
@check("ME-04", "What a provider does not do is said, never ignored", "full", f"{SPEC}/memories.md#63-the-response")
@@ -2095,11 +2111,6 @@ def me04(ctx):
assert said == (sig not in signals), (
f"the provider declares signals {signals}; a recall by {sig} answered degraded={((r.json or {}).get('degraded'))}")
notes.append(f"{sig}={'declared' if sig in signals else 'degraded'}")
- r = ctx.client.post(f"/v1/memories/{child['id']}/recall", body={"query": "renewal", "depth": 99})
- max_depth = int((prov.get("recall") or {}).get("max_depth") or 0)
- if max_depth < 99:
- assert any(str(d).startswith("depth:") for d in ((r.json or {}).get("degraded") or [])), (
- "a depth the server capped must be reported in degraded")
r = ctx.client.post(f"/v1/memories/{child['id']}/recall", body={})
assert r.status == 422, f"a recall with no query, text or filters must be refused; got HTTP {r.status}"
return ", ".join(notes)
diff --git a/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json b/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json
index 3d38dc9e..6493c6fb 100644
--- a/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json
+++ b/protocol/conformance/uhp_conformance/uhp-2026-10-04.schema.json
@@ -2613,8 +2613,12 @@
]
},
"depth": {
- "type": "integer",
- "minimum": 0
+ "type": [
+ "integer",
+ "null"
+ ],
+ "minimum": 0,
+ "description": "Levels below to search: 0 is this memory alone. Left out, the whole readable subtree."
},
"limit": {
"type": "integer",
@@ -2636,12 +2640,28 @@
"items": {
"type": "object",
"required": [
- "record"
+ "record",
+ "memory"
],
"properties": {
"record": {
"$ref": "#/$defs/MemoryRecord"
},
+ "memory": {
+ "type": "object",
+ "description": "The memory this result is in, the one asked or one below it.",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
"score": {
"type": [
"number",
@@ -2671,7 +2691,7 @@
"items": {
"type": "string"
},
- "description": "What the request asked for and the provider did not do."
+ "description": "What the request asked for and was not done."
},
"abstain": {
"type": "boolean",
diff --git a/protocol/schema/uhp-2026-10-04.openapi.yaml b/protocol/schema/uhp-2026-10-04.openapi.yaml
index fa4b0e27..27ca62d1 100644
--- a/protocol/schema/uhp-2026-10-04.openapi.yaml
+++ b/protocol/schema/uhp-2026-10-04.openapi.yaml
@@ -932,8 +932,8 @@ paths:
post:
tags: [Memories]
operationId: recallMemory
- summary: "Retrieve from one memory by meaning, words and fields"
- description: "Needs `read`. Acts on this memory alone; the answer names its parent and children."
+ summary: "Search a memory and what is below it by meaning, words and fields"
+ description: "Needs `read`. Covers this memory and every descendant the caller may read, never an ancestor; each result names the memory it is in, and the answer names the parent and children of the memory asked."
requestBody:
required: true
content:
@@ -2817,7 +2817,7 @@ components:
types: { type: array, items: { type: string } }
as_of: { type: [string, 'null'] }
include: { type: string, enum: [active, all] }
- depth: { type: integer, minimum: 0 }
+ depth: { type: [integer, 'null'], minimum: 0, description: 'Levels below to search: 0 is this memory alone. Left out, the whole readable subtree.' }
limit: { type: integer, minimum: 1, maximum: 100 }
MemoryRecall:
type: object
@@ -2827,14 +2827,21 @@ components:
type: array
items:
type: object
- required: [record]
+ required: [record, memory]
properties:
record: { $ref: '#/components/schemas/MemoryRecord' }
+ memory:
+ type: object
+ description: The memory this result is in, the one asked or one below it.
+ required: [id]
+ properties:
+ id: { type: string }
+ name: { type: string }
score: { type: [number, 'null'] }
why: { type: array, items: { type: string } }
parent: { $ref: '#/components/schemas/MemoryNeighbour' }
children: { type: array, items: { $ref: '#/components/schemas/MemoryNeighbour' } }
- degraded: { type: array, items: { type: string }, description: What the request asked for and the provider did not do. }
+ 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
MemoryErase:
diff --git a/protocol/schema/uhp-2026-10-04.schema.json b/protocol/schema/uhp-2026-10-04.schema.json
index 3d38dc9e..6493c6fb 100644
--- a/protocol/schema/uhp-2026-10-04.schema.json
+++ b/protocol/schema/uhp-2026-10-04.schema.json
@@ -2613,8 +2613,12 @@
]
},
"depth": {
- "type": "integer",
- "minimum": 0
+ "type": [
+ "integer",
+ "null"
+ ],
+ "minimum": 0,
+ "description": "Levels below to search: 0 is this memory alone. Left out, the whole readable subtree."
},
"limit": {
"type": "integer",
@@ -2636,12 +2640,28 @@
"items": {
"type": "object",
"required": [
- "record"
+ "record",
+ "memory"
],
"properties": {
"record": {
"$ref": "#/$defs/MemoryRecord"
},
+ "memory": {
+ "type": "object",
+ "description": "The memory this result is in, the one asked or one below it.",
+ "required": [
+ "id"
+ ],
+ "properties": {
+ "id": {
+ "type": "string"
+ },
+ "name": {
+ "type": "string"
+ }
+ }
+ },
"score": {
"type": [
"number",
@@ -2671,7 +2691,7 @@
"items": {
"type": "string"
},
- "description": "What the request asked for and the provider did not do."
+ "description": "What the request asked for and was not done."
},
"abstain": {
"type": "boolean",
diff --git a/protocol/versions/2026-10-04/memories.md b/protocol/versions/2026-10-04/memories.md
index dca40e58..48ec65bc 100644
--- a/protocol/versions/2026-10-04/memories.md
+++ b/protocol/versions/2026-10-04/memories.md
@@ -74,7 +74,7 @@ MCP the tools an agent holds how an agent calls it in a turn
|---|---|---|---|
| `id` | string | server | Opaque to a client. A server that mints its own uses the `hmem_` prefix ([Architecture §3](architecture.md#3-object-model)); a server whose memories are a tree it already has keeps that tree's ids |
| `name` | string | client | Human-readable |
-| `description` | string | client | What this memory holds, in a sentence or two. An agent reads it to decide whether to look inside ([§6.1](#61-reading-is-a-walk)), so it is content, not decoration |
+| `description` | string | client | What this memory holds, in a sentence or two. An agent reads it to decide whether to look inside ([§6.1](#61-search-finds-the-place-then-the-agent-walks)), so it is content, not decoration |
| `parent_id` | string or null | client | The containing memory; `null` on a root |
| `ancestors` | array | server | The ids from the root down to the parent, as far up as the caller may see. Placement only: reading a memory never reads an ancestor's records |
| `restricted` | boolean | client | When `true`, grants on ancestors stop here ([§3.2](#32-the-cutoff)) |
@@ -250,7 +250,7 @@ A record's `content` is an ordered list of **parts**. Two kinds of part are defi
| `POST /v1/memories/{id}/observe` | **observe**: append episodes; the provider decides what to derive from them |
| `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**: retrieve from this memory ([§6](#6-recall)) |
+| `POST /v1/memories/{id}/recall` | **recall**: search this memory and what is below it ([§6](#6-recall)) |
| `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 |
@@ -301,21 +301,35 @@ A provider declares how much of this it keeps, for content and for structure sep
## 6. Recall
-### 6.1 Reading is a walk
+### 6.1 Search finds the place, then the agent walks
-`recall`, `list` and `get` act on the one memory named in the path. They read neither its
-descendants nor its ancestors. A response carries where the caller can go from here: the memory's
-`parent` and its direct `children`, each with its `name`, `description` and counts, and only those
-the caller may read. An agent chooses where to look next, up or down, and reads there. The tree is
-walked in both directions by the agent's own decisions, never by the server on its behalf.
+A question is asked of a memory **and of everything below it that the caller may read**. That is
+what a search is for: the caller does not yet know where the answer is kept, so it asks high in the
+tree and learns where to look.
-A caller that wants several levels below at once passes `depth`; a server MAY cap it and MUST
-report a cap it applied in `degraded`.
+Each result therefore names the memory it is in. That memory is a starting point: the agent goes
+there and reads around what it found, lists it, asks again inside it, or moves to its parent or its
+children. The response also carries where the caller can go from the memory it asked: the `parent`
+and the direct `children`, each with its `name`, `description` and counts, and only those the
+caller may read.
-> **Why not search the whole subtree by default?**
-> A subtree can hold one node per customer. A read that fans out across all of them is slow, costs
-> in proportion to data the question never needed, and returns results the caller cannot place. An
-> agent that reads a node's description and then decides is doing what a person does with folders.
+Four rules bound this:
+
+- **Down, never up.** `recall` searches the memory and its descendants. It never searches an
+ ancestor. An agent that wants to look higher asks the parent, by its own next call.
+- **Only what the caller may read.** Each descendant is judged on its own
+ ([§3](#3-access)): a branch behind a cutoff the caller is not let through is not searched, and a
+ memory inside such a branch that the caller does hold a grant on is. The server decides this
+ before the provider is asked; a provider is never asked to search a memory the caller may not
+ read.
+- **`depth` narrows it.** `depth: 0` searches the memory alone, `1` adds its children, and so on.
+ Left out, the whole subtree is searched.
+- **A server MAY cap how many memories one question covers**, and MUST say so in `degraded` when it
+ did (`"subtree:capped_at_200_memories"`). The caller then asks lower in the tree.
+
+Everything else acts on **one** memory: `list`, `get`, `history`, the named and free queries
+([§6.4](#64-named-queries), [§6.5](#65-free-queries)) read the memory named in the path and nothing
+else. Finding is wide; reading is exact.
### 6.2 The request
@@ -327,6 +341,7 @@ report a cap it applied in `degraded`.
"types": ["fact", "note"],
"as_of": null,
"include": "active",
+ "depth": null,
"limit": 8
}
```
@@ -346,6 +361,7 @@ Any one may be given alone. Given together, the provider fuses them into one ran
"results": [
{ "record": { "id": "hrec_…", "type": "fact", "content": [ … ],
"trust": "untrusted" },
+ "memory": { "id": "hmem_…", "name": "Acme" },
"score": 0.91, "why": ["query", "filters"] }
],
"parent": { "id": "hmem_…", "name": "Company", "description": "…",
@@ -359,9 +375,11 @@ Any one may be given alone. Given together, the provider fuses them into one ran
}
```
+- `memory` names the memory each result is in: the one asked, or one below it. It is where the
+ caller goes next.
- `why` names the signals that produced each result.
-- `degraded` lists what the request asked for and the provider did not do (`"text:not_supported"`,
- `"depth:capped_at_2"`). A server MUST NOT ignore part of a request silently.
+- `degraded` lists what the request asked for and was not done (`"text:not_supported"`,
+ `"subtree:capped_at_200_memories"`). A server MUST NOT ignore part of a request silently.
- `parent` is absent on a root, and equally absent when the caller may not read the parent: the two
cases look the same.
- `abstain` is `true` when the provider judges that nothing it returned answers the question. A
@@ -585,8 +603,7 @@ GET /v1/memories/providers
"isolation": "container",
"derivation": "background",
"observe": { "keeps_episodes": true, "answers": "records" },
- "recall": { "signals": ["query", "text", "filters"], "abstain": true,
- "max_depth": 3 },
+ "recall": { "signals": ["query", "text", "filters"], "abstain": true },
"history": { "content": "versions", "structure": "versions" },
"revise": "native", "forget": "native",
"erase": { "unreachable": "reported" },
@@ -649,8 +666,9 @@ chapter reports `false` or omits it and answers its endpoints with `404`.
another agent, for another person. A server MUST present recalled content to the agent as data,
fenced from instructions, and MUST carry `written_by` with it.
- **The agent chooses its path, never its reach.** An agent may walk up and down the tree from the
- memories its harness attaches. What it can reach is every memory the harness holds a privilege
- on, no more, checked by the server on every call. A harness that should see one branch and
+ memories its harness attaches, and a search covers what is below the memory it asks. What it can
+ reach either way is every memory the harness holds a privilege on, no more, checked by the server
+ on every call and for every memory a search covers. A harness that should see one branch and
nothing above it is granted that branch and nothing above it.
- **Provenance is stamped, not supplied.** `written_by` and `written_at` come from the authenticated
caller and the server's clock.
@@ -663,8 +681,7 @@ chapter reports `false` or omits it and answers its endpoints with `404`.
The suite's `memories` checks (ME-01 onward) run against a server that reports the capability and
has a provider connected, and drive this chapter through the public surface on that provider: the
-tree and its listing, a stated record and its stamped writer, recall on one memory with the parent
-and children it names, each signal against the provider's own capability document (a signal the
+tree and its listing, a stated record and its stamped writer, a question asked of a parent finding a record below it and naming where it is, never one above, each signal against the provider's own capability document (a signal the
provider lacks must be reported in `degraded`, never ignored), revision and history, a record's id
refused through a memory it is not in, forgetting and erasing, moving and deleting. The suite runs
with one credential, so what one principal may not read of another's is not yet checked by it.
diff --git a/protocol/versions/2026-10-04/security.md b/protocol/versions/2026-10-04/security.md
index 28be60ad..a32a3982 100644
--- a/protocol/versions/2026-10-04/security.md
+++ b/protocol/versions/2026-10-04/security.md
@@ -160,7 +160,7 @@ for another person. Three properties follow, and none can be left to the agent.
had read a hostile page. A server MUST present recalled content to an agent as data, fenced from
instructions, with who wrote it ([Memories §13](memories.md#13-security)).
- **Reach is the harness's grants, on every call.** An agent may walk the tree from where it was
- attached; what it can reach is decided by the server from grants, not by what the agent asks
+ attached, and a search covers what is below the memory it asks; what it can reach is decided by the server from grants, not by what the agent asks
for, and a memory it may not read is answered exactly as one that does not exist.
- **A provider's credential never reaches a sandbox.** It belongs to whoever connected the provider
and is used by the server at the moment of a call ([§1](#1-credentials)).