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.

Memories: what a caller was given (GET /v1/memories?granted=true) (#406)

github-actions[bot]9cc75a0a0cea
diff --git a/protocol/CHANGELOG.md b/protocol/CHANGELOG.md
index 2400594b..983c0eb3 100644
--- a/protocol/CHANGELOG.md
+++ b/protocol/CHANGELOG.md
@@ -104,6 +104,16 @@ A file someone kept is NOT such a record: its title and its line are its writer'
it is revised and forgotten like any other; forgetting it takes the file out of reads, erasing it
removes the bytes. Schema: `MemoryRecord.follows`, optional.
+**What a caller was given (`GET /v1/memories?granted=true`), found by the second server.** The
+listing without `parent` says where a caller enters the tree, and nothing said where below that it
+may do more. A server that ran an agent whose memories another server kept built the agent's tools
+from the entry listing, and an agent that read a memory and wrote one of its children was offered
+no tool to write with. `granted=true` lists every memory the caller may read whose parent it
+cannot see, and every memory below those on which what it may do differs from the parent, with
+its privileges on each. It is stated in what the caller may do, not in how access is kept, so a
+server that lets a member in by a role answers it as one that keeps a grant per memory does. §9
+names it as what an agent's tools are built from. Conformance: ME-01 asks it.
+
- **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 3df95a0d..38233143 100644
--- a/protocol/conformance/pyproject.toml
+++ b/protocol/conformance/pyproject.toml
@@ -1,6 +1,6 @@
[project]
name = "uhp-conformance"
-version = "2026.10.4.post7"
+version = "2026.10.4.post8"
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 8c89eece..8e61995e 100644
--- a/protocol/conformance/uhp_conformance/checks.py
+++ b/protocol/conformance/uhp_conformance/checks.py
@@ -2036,6 +2036,16 @@ def me01(ctx):
f"whoever creates a memory holds all four privileges on it; got {root.get('privileges')!r}")
kids = (ctx.client.get(f"/v1/memories?parent={root['id']}").json or {}).get("data") or []
assert [k.get("id") for k in kids] == [child["id"]], f"the listing of a parent is its direct children; got {[k.get('id') for k in kids]}"
+ # what the caller was given: the memory it made is there with what it may do, and the child,
+ # where it may do exactly the same, is not (nothing changes there)
+ r = ctx.client.get("/v1/memories?granted=true")
+ given = {g.get("id"): g for g in (r.json or {}).get("data") or []} if r.status == 200 else None
+ assert given is not None, f"GET /v1/memories?granted=true must answer the list of what the caller was given; got HTTP {r.status}"
+ if set(child.get("privileges") or []) == set(root.get("privileges") or []):
+ assert child["id"] not in given, "a memory on which the caller may do what it may do on its parent is not one it was given"
+ if not root.get("parent_id"):
+ assert root["id"] in given and set(given[root["id"]].get("privileges") or []) == set(root.get("privileges") or []), (
+ f"a memory the caller enters at must be among what it was given, with its privileges there; got {sorted(given)[:5]}")
r = ctx.client.get("/v1/memories/" + "uhp-conformance-no-such-memory-" + uuid.uuid4().hex)
assert r.status == 404 and ((r.json or {}).get("error") or {}).get("code") == "memory_not_found", (
f"an unknown memory must answer 404 memory_not_found; got HTTP {r.status}")
diff --git a/protocol/schema/uhp-2026-10-04.openapi.yaml b/protocol/schema/uhp-2026-10-04.openapi.yaml
index 15469ec3..7bdccea0 100644
--- a/protocol/schema/uhp-2026-10-04.openapi.yaml
+++ b/protocol/schema/uhp-2026-10-04.openapi.yaml
@@ -586,6 +586,7 @@ paths:
parameters:
- { name: parent, in: query, schema: { type: string } }
- { name: ancestor, in: query, schema: { type: string } }
+ - { name: granted, in: query, schema: { type: boolean }, description: 'What the caller was given: every memory it may read whose parent it cannot see, and every memory below those on which its privileges differ from its privileges on the parent, highest in the tree first.' }
tags: [Memories]
operationId: listMemories
summary: "The memories a caller may see, one level at a time"
diff --git a/protocol/versions/2026-10-04/memories.md b/protocol/versions/2026-10-04/memories.md
index bfffaa5c..05f29319 100644
--- a/protocol/versions/2026-10-04/memories.md
+++ b/protocol/versions/2026-10-04/memories.md
@@ -91,6 +91,7 @@ MCP the tools an agent holds how an agent calls it in a turn
|---|---|
| `POST /v1/memories` | Create a memory: `name`, `description`, `parent_id`, `restricted`, `provider` |
| `GET /v1/memories?parent={id}` | The direct children of a memory, paginated. Without `parent`: where the caller enters the tree |
+| `GET /v1/memories?granted=true` | What the caller was given: where it was let in, and where below that it may do something else |
| `GET /v1/memories/{id}` | One memory |
| `PUT /v1/memories/{id}` | Rename it, describe it, restrict it, or move it by giving a new `parent_id` |
| `DELETE /v1/memories/{id}` | Delete the memory, its records and its descendants |
@@ -101,6 +102,16 @@ branch. A client that wants a subtree asks level by level, or passes `ancestor={
descendant it may read. A server MUST NOT return a memory on which the
caller has no effective privilege, and MUST NOT reveal that one exists.
+Where a caller enters and what it was given are two questions. A caller that reads a memory and
+writes one of its children enters at the parent, and the listing does not show the child: it is
+one level. `granted=true` answers the second question in one request: every memory the caller may
+read whose parent it cannot see, and every memory below those on which what it may do differs from
+what it may do on the parent, each with the caller's privileges there, highest in the tree first.
+It is stated in what the caller may do and never in how a server keeps access, so the answer is
+the same whether the caller was let in by a grant of its own, through a group, or by a role. A
+client reads from it where the caller may write without walking the tree, and an agent's tools
+are built from it ([§9](#9-an-agent-and-its-memories)).
+
## 3. Access
### Who acts on a memory
@@ -660,7 +671,11 @@ A harness adds two settings of its own:
agent writes is stamped with it.
- `data` is read off the grants, never stored on the harness: every memory the agent holds a grant
on, highest in the tree first. It is where the agent starts. From each it reaches everything
- below, and nothing above that it was not granted.
+ below, and nothing above that it was not granted. A server that runs the agent and does not
+ keep its memories asks the server that does, as the agent, with `GET /v1/memories?granted=true`
+ ([§2](#2-the-memory-object)). It MUST NOT build an agent's tools from the plain listing, which
+ names only where the agent enters: an agent that reads a memory and writes one below it would
+ be offered nothing to write with.
- `default_memory_id` is where an unaddressed `remember` goes and where turns are recorded. It MUST
be a memory the agent may write; a server refuses one it may not, with `memory_invalid`.
- `observe`, on by default, records each finished turn in the default memory as an episode.