A project two agents can build from

A hands-on ENGRAM walkthrough · September 26, 2026

Tutorial 8 gave one agent a brief it inherits without being told. This one adds a second agent, and the question changes: what does membership actually grant, what does it pointedly not, and how do two agents divide work they both believe they understand?

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.

nameroleENGRAM userowns
Igor Polyakovthe leaduser_003Trailhead App, the parent project
Trailhead APIAPI agentuser_079API layer, a sub-project
Trailhead WorkerWorker agentuser_080Backend 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:

namewhat 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

RequirementNotes
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 owneras a member
artifacts in the Project Library87
declared ground truth3 articlesthe same 3
memories reachable in the projecthundreds6, 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.

The Trailhead App project page as its owner sees it. The header reads 10 artifacts, 0 conversations, 0 sessions, with pills for owner, 3 people, restrict and 3 ground truth. A Sub-projects block lists API layer (Trailhead API, agent) and Backend service (Trailhead Worker, agent), each with a Detach control, beside an Add a sub-project tile. The Ground Corpus block shows an empty Inherited list reading 'This project draws in nothing from elsewhere', then three Declared articles — Trailhead v2 — Brief, Trailhead v2 — API Contract and Trailhead v2 — Working Agreement — each badged PROJECT with a Remove control. A Known-false claims block lists ENGRAM — Known False Claims badged SYSTEM and PUBLIC, and Trailhead — Known-false claims badged PROJECT. The Members block lists Igor Polyakov with an OWNER chip marked 'you', then Trailhead API (agent) and Trailhead Worker (agent), each with an AGENT chip and a Remove button, above the note that a member can read the project and its project-visible artifacts and has no access to anyone's memories.
The Trailhead App project as its owner sees it: declared ground truth, the known-false list, members, and the two sub-projects. The three panels that decide what a member gets. The Project Library sits below them on the same page and is cropped out here: Part 6 shows it as each sub-project inherits it, and Tutorial 10 shows the parent's own. Captured after phase 2 — the header's counts have moved on since the numbers above, which were measured at the phase 1 gate.

ENGRAM states the boundary in the Members panel itself, and it is worth quoting because teams keep rediscovering it the expensive way:

A member can read this project and the project-visible artifacts it holds. That is the whole grant: no edits, no settings, and no access to anyone's memories — those are shared separately and stay personal. Private artifacts stay private to their owner, whoever joins.

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.

tierhow an artifact gets therein the briefin recall
declared authorityset_project_authorityyesyes, boosted
in the Project Libraryadd_to_projectnoonly for callers who can read it
provenance onlycreated in the project, never addednono

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:

Do not assert a tier — read it back, from the identity that matters. Membership and visibility are each one call away and cheap to confirm. What recall returns for a member is not: confirm it with a recall made as that member, never as the owner, whose store answers differently.

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:

Nothing will ever surface this document for you. A brief is boosted into an agent's context whether it asks or not. A known-false list is held on a distinct edge type, precisely so a list of falsehoods can never be ranked up and returned as truth. You have to call 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 PATowner PAT
tools in the roster4453
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.

ENGRAM retires beliefs; a project member does not. Every memory version carries validity bounds, and a belief is retired rather than destroyed by any of three paths: 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 channelENGRAM
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:

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:

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.

Since this run (ENGRAM v1.18.0 – v1.18.1). The join is now part of ENGRAM. A person or agent binds the public key it uses in Buzz as a chat key, an agent checks at startup with 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.

The #trailhead-project channel beside an open thread. On the left, the lead's messages: opening phase 1 with the first turn to Trailhead API, a later 'Go ahead and re-declare contract', and a long run instruction naming commits and environment variables with two addresses redacted. On the right, the thread: the lead opens phase 1 and instructs the agent to remember its position at owner_scope project, share it to user_080, then pass the baton with the memory id. Trailhead API replies TURN COMPLETE with its §5 proposal memory id, anchored at owner_scope project and shared to user_080. Trailhead Worker answers TURN COMPLETE with its own memory id, agreeing to option A and adding condition (b'), that a 201 must show a non-null condition.derived_at on the next GET, plus two worker-side guarantees. Trailhead API then replies TURN COMPLETE — §5 settled and recorded; §4.1 proposed — accepting (b') and reporting the contract revised to 4fc66254, superseding ea08d7c8, with the note that its revise was not refused.
Right: the lead opens phase 1, the API agent proposes a position on §5, the Worker answers it, and the API agent settles it — each message naming the memory or article that holds the substance. Nine minutes, one question settled. The Worker agrees to option A, adds a counter — (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 layerBackend service
declares its own ground truth1 articlenothing
holds in its own library5, all authored by the agent0 — “This project holds nothing yet”
inherits the parent's libraryread-onlyread-only
The API layer sub-project, titled 'Trailhead App / API layer', with header pills reading member, 2 people, prioritize and 3 ground truth. The Ground Corpus shows two inherited SYSTEM articles — ENGRAM Ground Truth, carrying an amber NEWER VERSION chip, and ENGRAM Memory Architecture — and one declared article of its own, UC3 Contract v3, badged PUBLIC. The Members block lists Trailhead API (agent) with an OWNER chip and Igor Polyakov below it. The Project Library holds five articles, every one badged ADDED BY AGENT, four PROJECT and one PUBLIC. Below them an Inherited list from Trailhead App shows ten more rows, including two UC3 working notes and a DOC row for Docs | Open-Meteo.com.
The API layer sub-project: one declared article of its own, five artifacts the API agent authored, and the parent's library inherited below them. One agent published into its own sub-project. Captured as the lead: the two UC3 working notes in the inherited list are the lead's private articles, and neither agent sees them.
The Backend service sub-project, titled 'Trailhead App / Backend service', with header pills reading member, 2 people, prioritize and 2 ground truth. The Ground Corpus shows the same two inherited SYSTEM articles, with ENGRAM Ground Truth again carrying a NEWER VERSION chip, and a Declared section reading 'Nothing declared. Searches in this project are not anchored to any particular documents — they draw on everything you can already see.' The Members block lists Trailhead Worker (agent) with an OWNER chip and Igor Polyakov. The Project Library shows a count of 0 and the line 'This project holds nothing yet', above the same inherited list from Trailhead App.
The Backend service sub-project: nothing declared, nothing held, the same inherited library. The other agent kept everything in memory and the shared project. Also captured as the lead.

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

11. Appendix — Gotchas to be aware of

  1. An empty read is evidence about your reader first. Recall returns each memory as kind == "memory" (not "memories"); artifact rows carry their text at content.summary, recaps at content.text; ownership is user_id, not owner_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.
  2. include_brief="auto" returns a manifest when the brief is too large to fit. That is its job. Pass full when an agent needs the passages — at session start, for instance.
  3. 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.
  4. A member does not retract memories — by design. Put anything correctable in an article; write memories as dated observations.
  5. is_latest: false is not breakage. Retrieval serves the chain head; re-declaring is tidying, and waiting for it blocks nothing.
  6. restrict governs 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.
  7. scope_note is a cue to widen the search. When a project-scoped recall cannot be answered from the brief, the response carries a scope_note with covered: false. Treat it as an instruction: retry with scope="prefer" — everything, with the brief ranked up — or scope="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.
  8. 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.md and 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.
Companion reference: the ENGRAM documentation — projects, membership, ground truth and the recall settings above, in full.

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.