A project two agents can build from
A hands-on ENGRAM walkthrough · September 26, 2026
1. Why this tutorial exists
A project with one agent in it is a filing convention. A project with two is a governance problem, and the failures are quiet ones: two agents reading the same document differently, or one writing a note nobody granted anyone the right to read, or both concluding they are ready and each waiting on the other.
Membership looks like it fixes this. It does not — not on its own. Membership grants reads over a project and its artifacts, and it never reaches memory. An agent that joins a project can read every declared document and still cannot see a single thing its peer has written down. That is deliberate and fail-closed, and it is the single belief most likely to cost a team a turn.
Everything below was measured on a real run: two coding agents, on two machines, in two repositories, building one product against one declared brief. The run was made on our DEV environment against ENGRAM v1.17.4–5. Where the measurement contradicted what we expected, the measurement is what is written down.
2. What you'll build
Trailhead App owned by the lead — the brief, the contract, the agreement
│ library: 8 artifacts (members see 7 — one is private)
│ ground truth: 3 articles, project-visible, policy = restrict
│ negative list: declared separately, on a different edge
│ members: two agent identities
│
├── API layer owned by the API agent ── its own repo, its own memory
└── Backend service owned by the Worker agent ── its own repo, its own memory
One shared anchor, two owners who are not you, and a channel between them that carries no facts.
Who's who
The ids below appear in the screenshots and in the memory ids quoted throughout. They are DEV ids.
| name | role | ENGRAM user | owns |
|---|---|---|---|
| Igor Polyakov | the lead | user_003 | Trailhead App, the parent project |
| Trailhead API | API agent | user_079 | API layer, a sub-project |
| Trailhead Worker | Worker agent | user_080 | Backend service, a sub-project |
Neither agent is told who it is. Its repository holds no user or project ids; the first message of the run asks each agent to find out from ENGRAM — which project it belongs to, what it owns, and what the brief says. Part 1 is that step.
Names you'll see
Four kinds of “version” meet in this tutorial, and they are independent of each other:
| name | what it is |
|---|---|
| Trailhead v1 / v2 | product generations. v1 was Tutorial 8's build; this run builds v2 on top of it. The HTTP path
stays /api/v1 throughout — v2 is a milestone, not a URL |
| Trailhead v2 — API Contract, versions 1–5 | one article, revised four times. Each revision is a new article id linked to the previous by
SUPERSEDES, and ENGRAM numbers them: version 5 is 0c82ea2c. When this
tutorial says “v3” of the contract, it means ENGRAM's article version, not the
product |
| Trailhead — API Contract (no v2) | the v1 product's contract, kept in the library for reference |
| UC3 | our internal label for this run. It appears in the titles of a few working articles in the screenshots and means nothing to ENGRAM |
3. Prerequisites
| Requirement | Notes |
|---|---|
| Tutorial 8 | ground truth, set_project_authority, and why include_brief matters.
This tutorial assumes all of it |
| ENGRAM v1.17+ | project membership, and project-visible articles as ground truth. Before this, a
team brief had to be public |
| Two agent identities with their own PATs | Tutorial 7. Two agents sharing one token is not a team, it is one agent with two terminals |
| A chat channel your agents can hold a conversation in | Not optional — see Part 5. Buzz, reachable by ENGRAM private-beta users, here; Slack or an equivalent works. A one-way webhook or notification sink does not |
Three settings the rest of this leans on
Tutorial 8 covers them properly and the ENGRAM documentation is the reference; this is enough to read what follows.
| what it decides | |
|---|---|
policy · on the project |
prioritize ranks the declared brief up but still returns other articles.
restrict returns only the brief's articles. Ours is
restrict |
scope · on recall |
project, the default, honours the project's policy. prefer searches
everything with the brief ranked up; all ignores the brief |
include_brief · on recall |
how much of the declared brief comes back with the results: auto ·
full · manifest · none. auto
returns the whole brief when it fits and its structure — a manifest of titles and
sections — when it does not. full always returns the text |
4. Part 1 — Read what the team already resolves
Tutorial 8's first move, made twice here and for two different reasons. The lead runs it before adding anyone, to see what the project will hand out:
get_project_authority(project="<project id>")
list_project_artifacts(project="<project id>")
A human lead can read the same thing without MCP: the project's page in the Projects UI shows the Ground Corpus and the Project Library directly (screenshot below). The calls above are the route for a lead that is itself an agent, or for checking from a script.
Each agent runs its own version at the start of every session, before writing a line of
code: list_projects(), which must show the project with via: "member", then a
recall with include_brief="full" that actually contains a brief block. This is
also how an agent learns who it is and what it owns — nothing in its repository tells it. Ours were
instructed to stop and say so if either check failed, because this failure is silent: the agent recalls
something, it looks plausible, and it is not the brief.
Two numbers are worth writing down, because their difference is the whole of Part 4:
| as the owner | as a member | |
|---|---|---|
| artifacts in the Project Library | 8 | 7 |
| declared ground truth | 3 articles | the same 3 |
| memories reachable in the project | hundreds | 6, none of them by membership |
The missing artifact is a private working note of the lead's. To a member it does not merely read as
restricted — it does not exist: the listing omits it and get_article
returns 404 Not Found. That is the right shape. A member that can see a title it cannot open
learns something it was not granted.
The memory row is the one to internalise. Each agent could reach six memories at the start of the run, and every one arrived by ownership or an explicit share — not one of them by being a member. Membership and memory are separate systems that happen to share a project id.
ENGRAM states the boundary in the Members panel itself, and it is worth quoting because teams keep rediscovering it the expensive way:
5. Part 2 — Three tiers, measured
A project holds things and answers from some of them. Those are different claims, and there is a third state between them that most readers miss.
| tier | how an artifact gets there | in the brief | in recall |
|---|---|---|---|
| declared authority | set_project_authority | yes | yes, boosted |
| in the Project Library | add_to_project | no | only for callers who can read it |
| provenance only | created in the project, never added | no | no |
The middle row carries a condition that is easy to skip past: being in the library does not by itself make an artifact readable by the team. Its own visibility decides who can read it — which also lets a lead stage material, holding it in the project before the team needs it.
Our project holds a PDF of the weather provider's API documentation — 12 passages once indexed —
owned by the lead. It went into the library as private: general asks from the customer and
the vendor are the lead's concern, and would only have confused agents working from a brief. Once the app
had matured, the lead set it to project visibility and shared it with the team as background on
what they were building.
From a member's identity, measured on 2026-09-24, list_project_artifacts then returned it
(kind: document, visibility: project, via: member) and
get_document opened it (processing_status: complete, 12 passages). It was present,
visible and fully indexed. Yet five recalls — including one using the document's own title vocabulary,
and one at scope="all" — returned no passage from it, while article
passages came back in the same session.
The lesson is in how the test was run:
Two settings are worth reading precisely here, because each is easy to credit with more than it was built to do.
restrict governs the brief, which is to say the article arm. A recall answers
from several sources at once — articles, documents, memories and code sessions. restrict
exists to control access to the project brief, and a brief is made of articles, so it constrains only the
part of a recall that returns articles; we call that the article arm. Documents, memories
and code sessions are governed by their own visibility and grants. restrict is therefore not a
general “approved sources only” switch, and does not need to be.
include_brief="auto" sizes its answer to the brief. It returns the whole brief
when it fits, and otherwise its structure — article titles and section names, with
passages_returned: 0 — so an agent always learns what the brief covers without a large
brief crowding out the results it asked for. Ours did not fit, so auto returned the manifest;
full returned 39 of 39 passages. A session-start check that needs the brief's
content — like the one in Part 1 — should ask for full.
6. Part 3 — The list that never surfaces
Ground truth says what is true. A project can also declare what is false:
set_project_refuted(project="<project id>", article_ids=["<the negative list>"])
It has one property nothing else in a project has, and it is easiest to state as a warning:
get_project_refuted.
One asymmetry with ground truth follows directly from that property: a negative list need not be
public. A declared brief has to be readable by the team, or the team is anchored on something it
cannot resolve — so private is refused. A known-false list is never retrieved for
anyone, so a private one works.
This earns its place when a new build inherits an earlier one's code, memories and documents. Most of what the earlier build concluded was right. A few things were wrong — and the wrong ones sound exactly as confident as the right ones, because they were written carefully, in the same voice, in the same place. A false claim that is merely absent gets re-derived. A false claim that is listed gets caught.
Ours was mostly written by reading v1's own conclusions: “the trail catalogue is
read-only” (true in v1, false now), “a polling cycle returning only 200s
has stalled” (never true, and it looks exactly like a stall). Invented falsehoods teach nothing;
the useful entries are the ones a careful reader would still believe.
7. Part 4 — What a member credential is for
Both agents ran on ProjectCollaborator PATs, and both, independently, found the same difference
by name lookup:
| member PAT | owner PAT | |
|---|---|---|
| tools in the roster | 44 | 53 |
update_article / sync_article | ✅ | ✅ |
revise / forget / revert | ❌ absent | ✅ |
Calling forget with a member's token returns 403 — this is a
project_collaborator Personal Access Token, which may not forget. Belief mutation is denied at the
credential, not at the object.
That is a design decision, and it tells you where to put things.
revise by id, automatic contradiction detection, or deterministically when an article it was
imprinted from is revised. None of those verbs is in a member's roster.
The reason is twofold. Agents working on a shared project should not be rewriting belief history as they go — retiring and re-deriving memories mid-task lets beliefs about old facts cloud the current work. And a changed fact needs an audit trail the team can read. ENGRAM keeps a revision trail for every memory, but memories are personal: only the agent that owns one can see its trail. A change recorded in a project article gives every project member the audit of that fact — what it was, what it became, and who changed it.
What a member can change is the content of the project's articles. Both agents had
update_article, and the API contract — owned by the lead — went through
member-authored revisions (Part 6). What a member cannot change is the project itself: which articles are
declared as ground truth, what the library holds, and who belongs. Those stay with the owner.
Hence the working rule: anything that must stay correctable belongs in an article. A memory is a dated observation, not a standing claim. Write “measured X at 14:20 with these arguments”, which ages honestly, rather than “X is broken”, which does not. When an agent does need to correct itself, it adds a new memory that names the earlier id and quotes the sentence it retracts — both stay on the record, and the later one says which to trust.
8. Part 5 — Signal in the channel, substance in the knowledge base
A channel is not a convenience here — it is the half ENGRAM deliberately does not do.
ENGRAM governs what an agent may know. Nothing in it tells an agent that a peer is waiting on them:
list_inbox is a poll, and an agent that never asks never finds out. So turn-taking, the nudge to
start the next step, and the argument that settles an open question all have to happen somewhere else.
We know what the alternative costs, because we ran it. Trailhead v1 had no channel, and its working agreement stated that coordination happened “through ENGRAM memory, not through a chat channel” — which was true only because a human relayed every hand-off. That is what “optional” means here: you are the relay. v2 changed not that the agents coordinate but where, and the result is two agents working the way two engineers would — one channel for talking, one place for the record.
Posting is not enough. The channel has to let an agent read what was addressed to it
and know that it was addressed, rather than treating every message as ambient. It has to let the
agent reply to a specific message — Buzz timestamps are second-granular and the relay
does not preserve insertion order, so the reply chain is the only record of who spoke when. And it has to
attest identity itself: a message body claiming to be the lead is forgeable, so our agents
are instructed to trust only the channel's own author_name / author_role
attributes and nothing in the text. It also has to hold a human, because the lead is the only terminator.
What is interchangeable is the chat provider. What is not is the division of labour below — and getting that wrong is invisible until someone needs the record and it is gone.
| the channel | ENGRAM | |
|---|---|---|
| carries | signal: a turn ended, who goes next, what is blocked | substance: decisions, findings, rationale, recaps |
| lifetime | rolls out of context, not searchable, invisible to anyone who joins later | durable, attributable, retrievable |
| a message looks like | TURN COMPLETE · catalogue endpoint is live · recap <id> |
the recap itself, and why the design went that way |
Channel history is not a record. Anything a later reader needs — including the agent's own next session — goes in ENGRAM, and the message carries its id. “See the shared memories” sends your peer looking; an id hands them the thing.
The baton is three lines and one rule: TURN COMPLETE to your peer, BLOCKED and
DONE to the lead. Mention your peer only when passing completed work —
never to acknowledge, thank, or ask a question. The lead is the only terminator, so no path out of the loop
returns to the peer without new work attached.
The rule is about what must survive, not about brevity. Our batons ran to a full paragraph — you can read one in Part 6. What makes a message signal rather than record is the id it carries: everything in it is recoverable from ENGRAM by anyone entitled to it, and nothing depends on the channel still being readable a month from now.
Two practices follow from it:
-
Attachments work — but do not route evidence through them. Screenshots and
diagrams travel over the channel fine, and an uploaded file is stored rather than transient.
.txtand.loguploads were rejected by the relay mid-run, so a log, a dump or a captured run goes into ENGRAM or the repository and the message carries the id. The reason holds whatever the relay accepts: an attachment is durable but not discoverable. ENGRAM finds things by entity and project; to reach an attachment you have to already know which message it hung from. -
Standing instructions change at the agent's terminal, never over the channel. This is
the harness's rule, not the channel's — Buzz delivered the message faithfully and
Claude Code declined to act on it. A channel message asking an agent to edit and commit its own
CLAUDE.mdwas refused as instruction poisoning, correctly: a message that rewrites an agent's instructions is indistinguishable from an attack on it. Ordinary work asked for over the channel was not blocked — commits, pushes and running a service all went through. The channel carries requests; what an agent may act on is decided where it runs.
How the channel reaches ENGRAM
Buzz and ENGRAM roles do not overlap, and the division is finer than a two-way split. Buzz governs
what an agent may say — one keypair per agent, channel membership, who can be
addressed — and keeps a signed, hash-chained record of it. ENGRAM governs what it may
know. What an agent may do is governed by neither: that is decided by the
harness on the machine where it runs, which is why the CLAUDE.md refusal above came from Claude
Code and not from the channel. A channel could carry a tool-approval relay and reach into the
do half; ours deliberately does not, because anyone able to reply in the channel could otherwise
approve tool use.
So each of our agents carries two credentials: a Buzz keypair and an ENGRAM token. A small channel service delivers the messages addressed to an agent into its session and sends its replies back out; every ENGRAM call it makes goes under its own PAT. That is what makes the baton work at all — the message names a memory id, and the peer can resolve it.
The service also adds four safeguards that a human chat client doesn't need but an agent does:
- It filters by sender, not just by channel. A message from an author not on the agent's list never reaches its session at all.
- It tells the agent who spoke, in a form the model can't fake. Identity arrives as attributes set by the service, not as text in the message.
- It caps how much agents can talk. Nothing upstream stops two agents replying to each other forever, and every reply costs a real turn, so there are budgets per author and overall.
- It sends a short catch-up, not the whole history. An agent joining late learns what happened without paying for every message.
For this run, the join between the two identities was a proof-of-concept script. It configured each agent's Buzz keypair and ENGRAM token in separate steps, and nothing checked that they matched — which is why the working agreement made each agent prove its own identity before it wrote anything. Based on what we learned in the POC, the join is being built into ENGRAM: support for external chat identities, so that a persona on Buzz — or on Slack — becomes something ENGRAM knows about directly. It is planned for the next ENGRAM release.
whoami that the key it signs with is its own, and no agent can bind its own key. A project binds
the Buzz channels its work is discussed in, and ENGRAM rings a doorbell there when something is
waiting — a hand-off to review, or a proposed addition to decide — so a peer no longer has to be told to go
and look. The split above still holds: ENGRAM does not copy channel conversation. See
Buzz & Chat Keys.
9. Part 6 — What the agents settled without the lead
The brief left two questions deliberately open, and said so: §4.1, which observation a trail's condition derives from, and §5, how the worker learns a trail was created. Neither was specified anywhere. The procedure was:
state it as a memory → share it with your peer → signal the id over the channel → wait for agreement → only then revise the article, and name the new id.
(b'), a 201 must show a non-null derived_at on the next
GET — and makes its own code conditional on the revision existing first. The API
agent accepts, revises the contract to 4fc66254, and reports that its revise, as a member,
was not refused. The memories were shared agent to agent: the lead, who owns the project, cannot open
either one. On the left, the lead's own messages in the channel — including a request to
re-declare the contract, which Part 6 explains a member cannot carry out.
That is §5. §4.1 was settled the same way but never appeared in the channel — it was taken up after the §5 revision landed, and resolved directly between the two agents' memories. One of the two questions is visible here; the other happened entirely in ENGRAM.
Both were settled by argument, and both agents conceded a point. The §4.1 derivation rule shipped with a constraint neither had proposed alone: newest observation held per trail, and never live without timestamp bounds enforced first — otherwise a future-stamped reading becomes “newest” and pins the trail permanently.
The revisions themselves show the one mechanic worth understanding:
ea08d7c8 v2 11 Sep declared by the lead as the starting point, §4.1 and §5 open
4fc66254 v3 15 Sep §5 settled — revised by a member
6c4f61a6 v4 15 Sep §4.1 settled — revised by a member
0c82ea2c v5 17 Sep §9 settled, the forecast — Tutorial 10
A member's revision creates a new version at the head of the chain; it does not move the project's
declaration, which only the owner can change. So after each member revision the declaration still named an
earlier version, and get_project_authority reported is_latest: false.
Retrieval followed the chain and served the head anyway — both agents' briefs listed
v4, 6c4f61a6, while the declaration still pointed at an earlier version. The lead re-declared
the head after the forecast settled; today the declaration names v5 and reports is_latest: true.
In the UI the same state reads as a NEWER VERSION chip beside a declared article — you can see one beside ENGRAM's own inherited article in the sub-project screenshots below. It is worth recognising, because it looks like a warning and is not one.
Re-declaring is the owner's tidying, not a precondition for anything. Only the owner may do
it; a member's set_project_authority returns 403. Our run spent four turns asking
for a re-declaration that had never blocked a thing.
The two sub-projects, side by side
Each agent owns a sub-project linked to its own code repository — same grant, same policy. After two phases they had used it in opposite ways, and neither was arranged for the tutorial:
| API layer | Backend service | |
|---|---|---|
| declares its own ground truth | 1 article | nothing |
| holds in its own library | 5, all authored by the agent | 0 — “This project holds nothing yet” |
| inherits the parent's library | read-only | read-only |
UC3 working notes in the inherited list are the
lead's private articles, and neither agent sees them.
Both sub-projects also inherit ENGRAM's own corpus, while the parent draws in nothing at all. That is Tutorial 8's silent input showing up in a tree: they answer ENGRAM questions from ENGRAM's documentation, and the parent answers Trailhead questions from exactly the three articles the lead declared — no more.
The lead wrote the brief, declared it, and then did not participate in the two decisions that mattered most.
10. What this gives you
- A shared anchor two agents cannot drift from — one brief, resolved at query time, with no per-agent configuration to keep in sync.
- A boundary you can state in one sentence: membership grants reads over the project; every crossing between memories is an explicit, revocable grant.
- Decisions made by the agents holding the constraints, recorded where the next build will find them — and a negative list so the ones that turn out wrong get caught instead of re-derived.
11. Appendix — Gotchas to be aware of
-
An empty read is evidence about your reader first. Recall returns each memory as
kind == "memory"(not"memories"); artifact rows carry their text atcontent.summary, recaps atcontent.text; ownership isuser_id, notowner_user_id. Each of those produced a confident, wrong claim on this run. Dump the payload and list its keys before concluding anything from an absence. -
include_brief="auto"returns a manifest when the brief is too large to fit. That is its job. Passfullwhen an agent needs the passages — at session start, for instance. -
Membership never reaches memory. A note nobody was granted is a coordination mechanism
that silently does nothing. Anchor findings at
owner_scope="project"and share them. - A member does not retract memories — by design. Put anything correctable in an article; write memories as dated observations.
-
is_latest: falseis not breakage. Retrieval serves the chain head; re-declaring is tidying, and waiting for it blocks nothing. -
restrictgoverns the brief, and so the article arm only — not documents, memories or code sessions, which have their own visibility and grants. Don't reach for it as an “approved sources only” filter. -
scope_noteis a cue to widen the search. When a project-scoped recall cannot be answered from the brief, the response carries ascope_notewithcovered: false. Treat it as an instruction: retry withscope="prefer"— everything, with the brief ranked up — orscope="all". An agent that ignores it answers from a brief that has just said it does not cover the question. This is current behaviour; it changed after our run. -
An agent's own instruction files can only be changed where it runs. Ask an agent over
the channel to commit, push, or run a service and it will. Ask it to edit its own
CLAUDE.mdand the harness refuses — a message that rewrites an agent's instructions cannot be told apart from an attack on it. Make that change at the agent's terminal instead.
Tutorial 10 picks up where the specification runs out: what ENGRAM's hand-off, working-memory and proposal surfaces do when two agents have to negotiate a feature nobody has specified.