Ground truth & projects

Retrieval finds what's relevant. It doesn't know what's true.

Associative recall is good at reaching for what relates to a question. It has no opinion about which of two related documents is the one your team actually decided on. Point five agents at a knowledge base containing last quarter's design, this quarter's revision, and a colleague's exploratory note, and they will each answer from a different one — confidently, and without telling you which.

Ground truth is the missing claim. A project declares which articles are authoritative for it, and retrieval performed under that project prefers them. The claim being made is “this is true” — not “this is relevant”, and not “we are working on this”. That distinction drives everything else on this page.

Declaring a brief

Declaring replaces rather than appends: each call defines the complete set, so re-declaring the same articles changes nothing and declaring an empty set clears the brief. It is idempotent by construction, which makes it safe to put in a setup script that runs more than once.

The guard on what may be declared is readability: can this project's members read the article? A brief they cannot read is not strict, it is broken — a success response and no effect, which you discover months later. So a private article is refused loudly rather than accepted quietly.

A declared article stays authoritative across edits: revise it and the newest version is what answers, with no need to re-declare.

Prefer, or bind

Two policies, and the difference is how much room the agent has:

• Prioritize (the default) — declared articles are ranked up; other content is still returned. Use it when the brief is the best answer but not the only one.
• Restrict — answers come from the brief, not from ambient content. Use it when answering from anything else would be wrong.

There is also a negative list: articles that enumerate false claims. Note the shape carefully — a refuted article is one that lists things which are wrong, not an article that is itself wrong. It is a deliberately separate kind of link rather than a flag on the same one, so that a single missing filter can never cause the list of known falsehoods to be read as ground truth.

Workers inherit it automatically

This is the most commonly misunderstood point, because people go looking for a “use ground truth” flag on the call and there isn't one. An agent declares which project it is working in — by id, or by the repository URL, which ENGRAM resolves — and the brief follows. Nothing else is passed, and nothing has to be threaded through a fan-out.

Two things that sound alike and are not: membership grants the read — a member can read a project-visible artifact whether or not they declare the project — while declaring the project grants the authority, which is what makes the brief outrank ambient content. So “I got the passages either way” is not evidence the anchor does nothing; it changes what wins.

A project is a team, not a folder

Ground truth needs something to be true for. That is the project — and a project does four separate jobs that are worth keeping apart, because they compose in one direction only:

• Visibility — who may read an artifact at all: private, project, or public.
• The collection — what a project holds.
• Ground truth — what a project answers from. Declaring auto-adds to the collection, so a brief is always something the project holds.
• Members — who is in a project.

The sentence the whole model rests on: a project-visible artifact is readable by the members of any project whose collection holds it. Membership and collection, both, and nothing else.

What a member actually gets

A member can read the project, and the project-visible artifacts in its collection. That is the entire grant. Stated negatively, because people reliably assume more: no writes — not the settings, not the brief, not the collection — and no memory access at all. Memory is personal; putting an agent on your project gives it none of your memories.

A delegate adds three verbs — add or remove members, attach a sub-project, and rename the project's display label — and is still not a writer: it cannot add to the collection, declare ground truth, or change a retrieval setting. Only the owner may grant it, so the role cannot propagate itself through a team. Anyone may remove themselves, unconditionally.

Units of work

A repository is rarely one body of work. A sub-project is a unit inside one — a service, a component, a stream someone owns — and the important part is that a project is the unit of ownership, a repository is not. A second person on a shared repository owns their unit rather than needing a seat inside someone else's.

A unit can draw on its parent's brief, because what is true of a repository is true of its parts. Inheritance flows down only: a unit deciding something for itself is not the repository deciding it. And prefer declaring in each unit over declaring high and opting out — a claim on the parent that is only true for two of five units is a claim about the repository that is false.

The same set checks new writing

Ground truth is not only a retrieval preference. When an agent drafts an article into your knowledge base, ENGRAM verifies its claims against the corpus before the draft reaches your review queue, and flags or rejects the ones that contradict it. A memory layer that lets agents write into it needs an answer to “what stops them writing something untrue?”, and this is it.