When the answer isn't specified yet

A hands-on ENGRAM walkthrough · September 27, 2026

In Tutorial 9, the brief told two agents what to build. Here the brief names a feature but leaves its design open, so the two agents must agree on it before either can write code. We follow that agreement from the first proposal to the revised contract, and show which parts of ENGRAM carry it.

1. Why this tutorial exists

Most agent-collaboration examples divide work that is already specified. Someone writes the interface, the agents fill in either side, and the coordination problem is really a scheduling problem.

The interesting case is the other one. Our brief named the next feature — a multi-day forecast — and then said, deliberately, that its shape was not specified and must not be inferred. No endpoint, no payload, no ordering rule. Two agents, two repositories, one boundary that did not exist yet, and a lead whose job was to accept the answer rather than supply it.

Tutorial 9 was about what is settled: ground truth anchors it. This one is about what isn't. A negotiation runs on hand-offs, on memories that must reach a specific peer, on scratch that must not leak between sessions, and on retrieval that has to surface the one thing that matters out of hundreds that don't. Each of those can look successful when it isn't — so every part below tells you what to check, not just what to call.

The run was made on our DEV environment against ENGRAM v1.17.5+, as in Tutorial 9. Where behaviour has changed since, the text says so.

2. What you'll build

the Worker proposes a shape  ─────►  memory, shared to the peer, id on the channel
                                         │
the API agent counters, twice  ◄─────────┘   and asks one question only the
                                             other side can answer
        │
        └─►  the Worker measures the provider ──►  answers ──►  both agree
                                                                    │
                          the contract is revised to version 5  ◄──┘
                          and a UI, the read surface's third consumer, tests it

Who's who

The same cast as Tutorial 9. The ids appear in the screenshots and in every memory id quoted below; they are DEV ids.

nameroleENGRAM user
Igor Polyakovthe lead, owner of Trailhead Appuser_003
Trailhead APIAPI agent, owner of the API layer sub-projectuser_079
Trailhead WorkerWorker agent, owner of the Backend service sub-projectuser_080

A memory id names its author: memory:remember:user_080:… was written by the Worker.

Why the parts are in this order

A negotiation between two agents needs four things before it can start, and each is a tool in this tutorial:

  1. a way to put a finished turn in front of the other agent (Part 1);
  2. somewhere durable and precise for the substance, because a summary is not a record (Part 2);
  3. scratch that does not leak between agents or outlive the turn (Part 3);
  4. a way to publish a result to the team once it is agreed (Part 4).

Part 5 is what may go wrong when the project gets big enough that the right answer stops ranking. Part 6 is the actual argument, end to end.

3. Prerequisites

RequirementNotes
Everything Tutorial 9 needed the project and its members, two agent identities with their own PATs, and a chat channel the agents can hold a conversation in. Nothing new is required here, and none of it is re-taught
ENGRAM v1.17.5+ from this version on, a hand-off reports what it stored (Part 1)
A question genuinely worth arguing about the method depends on neither side being able to settle it alone

4. Part 1 — The hand-off: putting a finished turn in front of someone else

When one agent's turn ends, someone else needs what it concluded — its peer, or the lead. That transfer is a hand-off, and it is three calls:

sender:     commit_task_memories(hand_off_to="<receiver>")
receiver:   list_inbox()            →  sees it pending
receiver:   accept_memories(...)    →  now recallable

What travels is a recap — ENGRAM's summary of the turn, gathered from the memories the sender recorded during that task. What arrives is a proposal, not a fact, and that distinction is the first thing to understand about it.

A handed-off recap is suggested, and invisible to recall until accepted — by design. That is the review step, not a bug: the receiver has to accept the sender's conclusions before it can recall them. Once accepted, the receiver owns the memories, and each is granted back to the sender so it keeps recalling its own work.

The Memory Explorer's Suggestions tab, explaining that memories are proposed for review but not yet recallable. One expanded card reads 'Trailhead Worker — Phase 2 readiness recap' with a green Reflection badge, the line 'Handed off by Trailhead Worker (agent)' and '8 memories pending · TASK'. Its digest lists Facts: the phase 2 component commit, merged commits, 85 passing tests up from 56, Brief §4.1 completion naming the worker proposal, API counter and worker answer memory ids, the API Contract 0c82ea2c §10, two worker guarantees, and a joint run log with per-cycle timings, ending with a 'Full evidence' memory id and a day-count verification reading 14 days observed, not 15.
The Worker's phase 2 recap, handed off to the lead and waiting in the lead's Suggestions. The same flow with a human receiver: the lead reviews what the agent concluded before any of it becomes recallable. “Proposed for your review but not yet recallable.” The Reflection badge means it came from a session someone committed — as against Inferred, which ENGRAM proposes from your activity. Eight memories pending, and none of them reachable by recall until accepted.
The Memory Explorer's Sharing tab on the 'Shared by me' sub-tab, described as cross-user grants that are read-only recall and revocable at any time. Four cards, each badged MEMORY and addressed 'to Trailhead Worker (agent) (user_080)' with a GRANT-BACK chip: the phase 2 readiness component note, the Brief §4.1 forecast completion, worker guarantee w4, and the joint run log. Each shows 'recall everywhere they work · 9/17/2026' and a Revoke button.
After the lead accepted that recap: each memory granted back to the Worker, automatically. The lead's Sharing tab, “Shared by me”. The GRANT-BACK badge marks a share ENGRAM created when the hand-off was accepted, not one the lead made by hand. The lead now owns these memories, the Worker keeps recalling its own work, and the lead can revoke any of the grants.

The response tells you whether it worked, and it is worth reading. A hand-off does two things — it creates the recap, and it gathers into it the memories the recap claims to carry — and the return value reports both:

fieldon successwhat it means
recap_idan idthe recap exists and can be addressed
reflectednon-zerothat many memories were gathered into it
Read reflected and recap_id rather than inferring success from the absence of an error. A recap with nothing in it is a real state, and it is invisible to list_inbox, which lists only recaps with something pending.

Address the receiver by user_id. It is the preferred form for an agent. hand_off_to also accepts an email, and rejects either if it matches no principal. The receiver is usually known from the project roster, so take the id from list_project_members.

suggest_memories is the other route to the same queue. It takes its items from the caller instead of gathering them from the session. That makes it the better choice when an agent already knows exactly which memories should travel — and the only choice when the memories were written in an earlier session.

5. Part 2 — A recap is a summary; the evidence memory is the record

ENGRAM writes the recap from an agent's work, so the wording is ENGRAM's rather than the agent's. A summary is accurate at the level it summarises to, and that level is rarely the one a precise claim needs. “Rejects forecast hours too far ahead” is a fair description of a fix that actually picks the latest complete hour at or before now; a cycle count rounded in prose is still a rounded number. Neither is dishonest. Both mislead a reader six months later who takes the recap as the record.

The habit that fixes it:

Have the agent put the precise facts in a remember of its own, share that, and quote its id in the baton. Let the recap be the summary it is.

That is also what makes a claim checkable. The recap in the screenshot above ends its account of the joint run with “Full evidence: memory:remember:user_080:8c8436ab533889dc” — a pointer worth more than the recap's own prose, because it leads to something the Worker wrote deliberately.

6. Part 3 — Working memory is scratch, not a shared channel

Working memory is an agent's short-lived store for in-progress notes during a session. When two agents work on the same task, it is tempting to treat it as a scratchpad they share. It is not one, and the reason is how it is keyed.

It is keyed by owner and session. Two agents writing under the same session id share nothing — each reads only its own records. To hand scratch over there is an explicit verb:

share_working_memory(...)        # recipient sees it in recall(horizon="working"), via="share:<id>"

Three things to know when an agent uses working memory:

So treat working memory as a scratchpad for the turn in hand. Anything that must outlast the turn belongs in long-term memory, written there on purpose with remember.

7. Part 4 — An agent authoring for the team

A project member adds an artifact to a project by proposing it; the owner — or an admin or moderator — approves or rejects the proposal. Our API agent showed why that path matters. It wrote a UI design document, revised it several times, and kept it in its own sub-project, API layer, where it is the owner and can add whatever it likes.

That made the document invisible to its peer, which got a 404. The Worker is not a member of API layer, and a project-visible article is readable only by members of a project that holds it. To reach the team, the document had to go into the parent project, Trailhead App — where the API agent is a member, not the owner.

Tutorial 9 drew the line that makes this a proposal: a member may revise articles a project already holds, but it cannot change what the project holds. Propose, then ratify:

member:  add_to_project(...)   →  warnings: ["Proposed, not added — awaiting owner approval"]
owner:   approve               →  now in the collection, added_by = the proposing agent

A pending proposal is held on a separate edge from the collection itself, which is what makes the next table true. To the rest of the team — not the proposer, the other member — a proposal in flight looks like this:

while pendingafter approval
get_article404readable in full
the artifact listingabsentpresent
provenancecan_approve: falseadded_by records the proposing agent
The Project Library block of Trailhead App, headed with a count of 10. A 'Pending additions' section — labelled 'proposed by a member · not readable by the team until you approve' — holds one row, 'Trailhead — ENGRAM hand-off findings', badged PROJECT and 'by Trailhead API (agent)', with Approve and Reject buttons. Below a dashed divider, the library itself lists ten rows each with a Flag and Remove control: 'Trailhead v2 — Web UI design (API agent proposal)' marked ADDED BY AGENT and PROJECT, two UC3 rows badged PRIVATE, a DOC row for Docs | Open-Meteo.com, three more v2 PROJECT articles and three PUBLIC Trailhead articles.
The Trailhead App library as its owner sees it: one proposal pending at the top, and the approved UI design just below it. The pending row is a second proposal from the API agent — its hand-off findings — with Approve and Reject. The row beneath it, the UI design, shows the other state: approved, and marked ADDED BY AGENT. Everything below the dashed line is already in the library. Flag is the reverse of a proposal: a member uses it to propose removing an artifact from the library. The two PRIVATE rows are the lead's working notes: visible to the owner here, absent entirely for either agent.

A pending proposal grants nothing — not a read, not even the knowledge that a proposal exists. That is the right shape: a proposal is a request, and a request that leaked its contents would be a publication.

And this is exactly where the channel earns its place. ENGRAM holds the proposal and decides who may read it; it does not wake anyone. So the proposing agent tells the owner it is waiting — an @-addressed message naming the artifact — and the owner tells the agent when it is approved. The knowledge base carries the artifact and the authority; the channel carries the nudge. That is Tutorial 9's baton applied to a different surface, and it is why a team of agents wants both systems rather than either alone.

8. Part 5 — Retrieving a specific thing from a large store

Recall is associative and ranked: it answers what is relevant to this question? That is the right behaviour for the questions an agent usually asks, and the wrong tool for “show me the thing I accepted twenty minutes ago” — a question about provenance, not relevance. Knowing which of the two you are asking is most of retrieval.

Ranking is driven by relevance, importance and recency together. Other things equal, a newer memory ranks higher; importance depends on what created a memory. Artifact memories — one per article or document you own — start high, because a curated document is usually worth surfacing. Recap memories start lower. In a store with few artifacts the difference is invisible; in one with hundreds, artifact memories fill the top of any broadly phrased query, and a specific recap can sit below them.

Three techniques, in the order to reach for them:

  1. Query in the vocabulary of the thing itself. A memory is reached through the entities its text resolves to, so the nouns unique to it work and the project's general vocabulary does not. “Fort William gravel muddy 46.6 mm” finds the run; “phase 1 readiness” competes with every document in the project.
  2. Raise the limit before concluding something is absent. Ranking decides the order; limit caps how many hits come back. A memory ranked ninetieth is present at limit=200 and missing at limit=50, and the two results look identical from the caller's side.
  3. Use the id when you have one. This is why the baton carries ids rather than descriptions. get_memory(memory_id) answers by address, with no ranking involved — so anything an agent will need to fetch precisely later should have its id recorded when it is created. A recap is not a memory, so get_memory returns 404 on a recap id. Over MCP today, list_inbox gives a pending recap's id and counts, and an accepted recap is reached through its memories; a tool to fetch a recap by id is planned for v1.18.
Widening the scope adds candidates; it does not prioritise. scope="project", the default, honours the project's brief policy. scope="prefer" searches everything the caller can reach with the brief ranked up, and scope="all" searches everything without it. More candidates means more competition, so a specific memory can rank lower at a wider scope than at the default — worth knowing before reaching for it as a fix.

One property worth carrying into how you design a team: ranking depends on whose store is searched. A lead who owns the project's documents has hundreds of high-importance artifact memories; an agent that owns a handful does not, so the same query ranks differently for each. When it matters that a specific agent can retrieve something, check it from that agent's identity rather than from the owner's.

9. Part 6 — The negotiation, and the third consumer that tested it

The forecast shape was settled in four moves, each one a memory with its id on the channel:

  1. The Worker proposes a shape, with reasons.
  2. The API agent agrees with most of it, counters on two points, and asks one question it cannot answer itself: does the provider expose a model-run or issue time we could send as issued_at?
  3. The Worker measures the provider rather than answering from memory. The answer is no. The response's only scalars are latitude, longitude, generationtime_ms, utc_offset_seconds, timezone, its abbreviation and elevation — and generationtime_ms is how long the request took to compute, not a timestamp. No Last-Modified, ETag, Age or Cache-Control header either.
  4. Both agree, and the API agent revises the contract — 6c4f61a6 (version 4) becomes 0c82ea2c (version 5) — recording the decision in the contract's revision log, its §10.

Versions 3 and 4 were the two phase 1 settlements in Tutorial 9; the forecast is the only change in version 5.

The settled shape: a forecast is a separate per-day resource on /api/v1 rather than a new major version, ordered by a client-supplied retrieved_at with bounds, replaced whole rather than accumulated, and the API derives each day's status — the Worker sends facts and never a judgement, exactly as for observations.

Both sides conceded something, and §10 says what. The Worker had proposed serving the forecast as facts only and withdrew that: a per-day judgement is the API's to make. The API agent had leaned towards ordering by the time a forecast arrived and was persuaded otherwise, because a receiver ordering by arrival cannot tell a late old forecast from a new one.

Two details are worth more than the shape itself.

The cap that was never reachable. The contract allows up to 15 days. While measuring, the Worker found that the provider returns 16 rows starting today, and the last one is entirely null — so the complete future days run from tomorrow to today+14, which is 14. The run produced 14 days, and nothing on the worker side had assumed 15. A limit nobody can reach is not a bug, but a team that believes it is reaching it will build the wrong test.

The empty case is a 200, not a 404. A trail with no forecast held returns zero days and a null retrieved_at. Absence of data is not absence of a resource.

Then the UI. It is the API agent's to build — the contract assigns it to the API side — and it is a single server-rendered page: no JavaScript framework, no build step. It shows each trail's current condition, read from the same surface the Worker uses; the forecast has its own surface and the page does not read it. That makes the UI the read surface's third consumer, and that is most of its value:

The Trailhead web page, headed 'Trailhead' with the subtitle 'Is this trail worth walking today?'. A Status filter set to 'all' with a Show button. A table with columns TRAIL, SURFACE, CONDITION, WHY and JUDGED holds two rows: 'Fort William Forecast Track', gravel, an amber MUDDY badge, '46.6 mm of rain in the last 72 h on a gravel surface', judged 27 min ago; and 'Never Observed Trail', dirt, a grey UNKNOWN badge, 'no observations yet', judged never.
The Trailhead page: one filter, two trails, and each trail's current condition with the reason for it. unknown is a legitimate state, not an error — routine once trails can be created, and the row that proves the read surface handles it.

Two cooperating services will paper over a shape problem by agreeing about it privately. A third consumer cannot: it either finds the field it needs on the read surface, or it discovers that what looked settled was an assumption two parties happened to share. Ours held — ?status=muddy returns the row, an invalid status returns 422 rather than an empty list, and the page needs no data the contract does not expose.

The specification was written by the two agents that had to implement it, and the lead's job was to accept it.

10. What this gives you

11. Appendix — Gotchas to be aware of

Tutorial 9's appendix still applies in full; these are the ones specific to a negotiation.

  1. Read the return value of a hand-off. recap_id and reflected tell you whether the recap exists and how much it carries. An empty recap is a real state, and it is invisible to list_inbox, which lists only recaps with something pending.
  2. Hand off to a verified principal. Pass a user_id taken from list_project_members; an id or email that matches nobody is rejected.
  3. suggested is invisible to recall by design. A recap the receiver has not accepted is waiting, not missing — the invisibility is the review step. Do not build a flow that assumes an agent can recall a hand-off before accepting it.
  4. A recap cannot be split after the fact. commit_task_memories groups a task's findings by the entities they share, so distinct findings about the same things can end up in one memory. Findings that must travel separately need separate remember calls before the commit — or use suggest_memories, which takes exactly the items you give it.
  5. Working memory is per owner and per session, and consolidation moves qualifying records into long-term memory within minutes — every 5 by default. A shared session id shares nothing; anything that must outlive the turn belongs in long-term memory.
  6. A pending proposal grants nothing — not a read, not the knowledge that it exists. Have the proposer announce it on the channel rather than expecting the owner to discover it, and have the owner say when it is approved.
  7. list_inbox shows what is pending now. It wraps the same endpoint the Suggestions UI calls, so the two cannot disagree — but a recap accepted six minutes ago is no longer pending, and an empty inbox is not evidence that nothing arrived.
  8. Fetch by id when you know it; query by vocabulary when you don't. get_memory(memory_id) answers by address with no ranking involved. It returns 404 on a recap id — a recap is not a memory — so reach an accepted recap through its memories until the recap-by-id tool planned for v1.18 arrives.
  9. Raise the limit before concluding something is absent. A memory ranked ninetieth is present at limit=200 and missing at limit=50, and both results look the same from the caller's side.
Companion reference: the ENGRAM documentation — hand-offs, working memory, projects and sharing, in full.