When the answer isn't specified yet
A hands-on ENGRAM walkthrough · September 27, 2026
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.
| name | role | ENGRAM user |
|---|---|---|
| Igor Polyakov | the lead, owner of Trailhead App | user_003 |
| Trailhead API | API agent, owner of the API layer sub-project | user_079 |
| Trailhead Worker | Worker agent, owner of the Backend service sub-project | user_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:
- a way to put a finished turn in front of the other agent (Part 1);
- somewhere durable and precise for the substance, because a summary is not a record (Part 2);
- scratch that does not leak between agents or outlive the turn (Part 3);
- 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
| Requirement | Notes |
|---|---|
| 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 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:
| field | on success | what it means |
|---|---|---|
recap_id | an id | the recap exists and can be addressed |
reflected | non-zero | that many memories were gathered into it |
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:
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:
-
Let ENGRAM find the entities. Omit
entities, or pass[], and ENGRAM extracts them from the text. If you do pass ids, they must be current: a stale id is rejected with400and nothing is stored. When ENGRAM falls back to extraction, the response says what was supplied, what resolved, and what was extracted. -
Read your own scratch with an empty
queryplus the session id — that returns the session's whole set. A query whose words resolve to no entities can return nothing, even when records exist. - Plan for consolidation, not the TTL. A working record expires after 24 hours, but a consolidation job — every 5 minutes by default — promotes the records that qualify into long-term memory and removes them from working memory. Both intervals are configurable. In practice, a record an agent has been using can leave working memory within minutes.
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 pending | after approval | |
|---|---|---|
get_article | 404 | readable in full |
| the artifact listing | absent | present |
| provenance | can_approve: false | added_by records the proposing agent |
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:
- 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.
-
Raise the limit before concluding something is absent. Ranking decides the order;
limitcaps how many hits come back. A memory ranked ninetieth is present atlimit=200and missing atlimit=50, and the two results look identical from the caller's side. -
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, soget_memoryreturns404on a recap id. Over MCP today,list_inboxgives 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.
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:
- The Worker proposes a shape, with reasons.
- 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? - 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 — andgenerationtime_msis how long the request took to compute, not a timestamp. NoLast-Modified,ETag,AgeorCache-Controlheader either. - Both agree, and the API agent revises the contract —
6c4f61a6(version 4) becomes0c82ea2c(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:
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
- A method for the unspecified case — propose, counter, measure rather than assert, agree, then revise the document and name the new id. It works because no participant can end it alone.
- Durable reasons, not just decisions. The contract says what was chosen; its revision log and the memories behind it say why, and who conceded what.
- Surfaces you can verify rather than trust — a hand-off whose return value says what it stored, scratch with a known lifetime, a proposal whose visibility is decided by one edge, and retrieval you can address by id when ranking is the wrong tool.
11. Appendix — Gotchas to be aware of
Tutorial 9's appendix still applies in full; these are the ones specific to a negotiation.
-
Read the return value of a hand-off.
recap_idandreflectedtell you whether the recap exists and how much it carries. An empty recap is a real state, and it is invisible tolist_inbox, which lists only recaps with something pending. -
Hand off to a verified principal. Pass a
user_idtaken fromlist_project_members; an id or email that matches nobody is rejected. -
suggestedis 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. -
A recap cannot be split after the fact.
commit_task_memoriesgroups 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 separateremembercalls before the commit — or usesuggest_memories, which takes exactly the items you give it. - 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.
- 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.
-
list_inboxshows 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. -
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 returns404on 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. -
Raise the limit before concluding something is absent. A memory ranked ninetieth is
present at
limit=200and missing atlimit=50, and both results look the same from the caller's side.