Projects & Provenance

Organize your work into projects, and see where every piece of knowledge came from.

1. Projects and Provenance: Organizing Your Knowledge

ENGRAM remembers not just what you know, but where it came from — its provenance — and lets you group related work into projects. Together these keep a growing knowledge base organized and traceable, no matter how many tools and conversations feed into it.

1.1 Where your knowledge comes from

Every article, document, and memory in ENGRAM remembers the activity that produced it. There are three kinds of sources:

You'll see this as a Source line on an article or document, and as a source chip in the Memory Explorer. Provenance means you can always trace a piece of knowledge back to the work that created it.

1.2 Projects: one body of work

A project groups everything that belongs to one body of work — its conversations, coding sessions, captured research, and the articles and documents derived from them — no matter which tool produced them. A project is usually one repository or one topic you're researching.

Projects share a single namespace: a repo's coding sessions, the external chats you had about it, the articles you synced from it, and your in-app conversations can all live under the same project when they share a name. One project = one body of work.

Conversations you start in ENGRAM Chat without choosing a project land in your default project, named “ENGRAM KB” out of the box. (An administrator can change that default name in Administration → Settings → Projects.) A project you create is yours: you own it, and you are the only one who can configure it or write to it. It stays private to you until you deliberately do two things — put artifacts in it, and add members (§2.5). Neither happens on its own.

1.3 The Projects panel

Click the Projects icon (just left of the column title) on Chat, Knowledge Base, or Coding Sessions to open the Projects panel. It lists your projects, each tile showing a composite count — conversations · articles/documents · sessions — so you can see what's in it at a glance, when it was last active, and a Default badge on your default project. Search by name, or use + New to create a project — typing a name that already exists simply selects it.

This panel is deliberately owner-scoped: it lists the projects you own, because selecting one scopes what the rest of the app writes into, and you write into your own projects. Projects you have been added to as a member appear on the Projects tab instead (§2), which is where you read them.

This panel selects — it decides which project the rest of the app is showing you. To manage a project — see everything it holds, change what it answers from, add or remove artifacts — use the Projects tab described in §2.

1.4 Pinning an active project

Selecting a project pins it across Chat, Knowledge Base, and Coding Sessions at once, and the choice persists across reloads. The Project: <name> chip shows what's active; while a project is pinned, each area shows only that project's items, and new chat conversations file into it automatically. Click the × on the chip to return to All Projects — the no-filter view that shows everything, and the default when you first arrive.

1.5 Renaming and moving

To give a project a friendly display name, open it on the Projects page and edit the name in its Settings. The project's owner can do this, and so can an admin or a moderator. It changes only how the project is labeled — not what's in it, and not the identity anything is filed under, so nothing comes loose when you rename. (A moderator can also add and remove members, attach a sub-project, approve or reject a member's proposed addition, and bind the project's Buzz channels — but cannot add to the collection directly.)

To re-file something, open the actions menu (the ⋮ icon) on an in-app or external conversation, or on an agent-captured article, and choose Move to project, then pick a target (or create a new one). A few things move on their own, by design:

1.6 Projects across the app

Because provenance is tracked and projects share one namespace, the knowledge you produce across many different tools converges into one organized, traceable knowledge base — and moving a conversation to a better-fitting project quietly brings its articles, documents, and memories along with it.

2. Managing projects

The Projects tab is where a project stops being a filter and becomes something you shape. It lists the projects you are in on the left — the ones you own and the ones you are a member of — search by name, and each card shows when it was created and last touched, plus how many artifacts, conversations and coding sessions it has. Pick one and the right-hand side shows everything about it.

A pill on each card says which is which. OWNER is yours to configure and write to; MEMBER you may read — the project, and the project-visible artifacts in its collection — and nothing more. Membership never grants a write, and never reaches your memories.

Below the header and the sub-projects, a project's material sits under three tabs: Ground Corpus (§2.4), Project Library (§2.1–2.2) and Agent Skills (§2.7). The Project Library opens first, and the tab you choose stays selected as you move between projects.

The Trailhead App project as its owner sees it, with a one-line description under its name. The header pills read owner, 5 people, restrict and 3 ground truth. Settings is collapsed. A Sub-projects block lists API layer and Backend service, each with a Detach control, beside an Add a sub-project tile. Below, the tabs Ground Corpus, Project Library and Agent Skills, with Ground Corpus open: an empty Inherited list, a Declared list of three articles, each badged PROJECT with a Remove control, and a Known-false claims list holding ENGRAM's built-in list, badged SYSTEM and PUBLIC, and Trailhead — Known-false claims, badged PROJECT.
A project, seen by its owner. The header pills (owner · 5 people · restrict · 3 ground truth) report your role and how retrieval behaves without opening anything. Settings starts collapsed — the roster is one of its tabs (§2.5) — so the page leads with what the project is made of: its units, then the tabs, here on Ground Corpus.

2.1 What a project holds

The Project Library lists every artifact in the project — and there are two ways an artifact gets there, which the page distinguishes because they mean different things.

Rows added by an agent are marked added by agent, and ones filed automatically when they were ingested are marked auto-added. An artifact that was created here has no Remove button — there is nothing to remove, because nothing was added; move or delete the conversation it came from instead.

A sub-project (§2.6) also shows an Inherited section: what the parent holds, which this unit's members may read but which is not part of what the unit holds. It is listed separately and stays the parent's — the unit never claims it.

An added row also carries a Flag control: propose it for removal without removing it. A flagged artifact is still in the collection and is still retrieved — the marker says contested, not gone — and it records who raised it, so the project's owner decides later. Keep withdraws the proposal. It exists because removal is the owner's call while noticing that something no longer belongs is anyone's.

The Project Library tab headed with the count 6, under the explanation of Created here versus In the project. Each row carries an ART badge on the left and its title, with added by agent beneath; on the right, its version, its visibility, an Approval menu, and Flag and Remove buttons. The first row's Approval menu is open, offering Submit for approval: ask this project's approver to approve this version. One row is PRIVATE and also says, in amber, members can't read. The last row, Tutorial 11 smoke test note, is at v3 with an amber dot on the version and a green APPROVED pill in place of its menu. A search box for a readable article or document sits below the list.
The Project Library. Each row says how it got there (ADDED BY AGENT), who may read it (its visibility), and which version the project holds. An amber dot on the version marks one revised since it was added, and an arrow (↑) one filed as an older version; hover over it for who and when. A private row is held but not shared: members can't read, under its title, says so until its author widens it. With approval on, a column after the visibility shows each version's approval: its Approval ▾ menu, open here on the first row, and a pill: DRAFT until it is decided, then APPROVED or REJECTED (section 2.2).

2.2 Adding an artifact to a project

Three places, depending on where you are when you decide:

You can add another user's public artifact to your project — gathering public material into your own scope is the point. A non-public artifact of theirs is refused: only an artifact's owner may place a non-public artifact into a project. Otherwise adding — a write every project owner has — would become a way to grant yourself a read of someone else's material.

In a project you are a member of rather than own, your own artifact is proposed, not added. Tick it in the Projects control and it is recorded as a pending addition, marked pending; the project's owner (or an admin or a moderator) sees it under Pending additions in the Project Library with Approve and Reject. Until it is approved it grants nobody anything — the project's members cannot read it — and you can withdraw it by clicking the row again. Rejecting removes the proposal and leaves the artifact untouched, so it can be proposed again. The one exception is the people asked to decide: the owner, admins and moderators can open a pending artifact from the list, so they can judge it before it is filed — and it never reaches anyone's search results while it waits. An agent decides the same way, with approve_project_addition and reject_project_addition.

A private artifact may be proposed too, and it stays private. ENGRAM asks you to confirm first, and the row carries a stays private tag. Once approved, the people who decide keep reading it; the project's members still cannot (its row says members can't read) until you, its author, widen it to project — nobody else can.

This is what lets work leave a sub-project. The person or agent doing the work owns what they wrote and belongs to the parent; the parent's owner decides what the wider team holds. Neither side has to hand over control of anything to make the move.

The collection carries project visibility. For a private or public artifact, adding it to a project only organizes: it changes nothing about who can read it. For a project-visible one it does more, and exactly one thing more — it selects which project the artifact belongs to, and that project's members are then who may read it. So the sentence to keep in mind is: a project-visible artifact is readable by the members of any project whose collection holds it. Membership and collection, both, and nothing else.

Approving a version

Adding an item decides whether it belongs in the project. Approval is a second, separate step: it records that a particular version of an article or skill the project already holds has been agreed. It is available once an administrator turns it on. Every item starts as DRAFT when it joins the library, including an addition that was just approved.

Approval records a decision; it does not hold anything back. Members read, and agents receive, the current version whatever its status. Agents can do the same through MCP: submit_for_approval, decide_approval and withdraw_approval.

2.3 Project settings

A project's Settings has four tabs — General, Ground truth, Channels and Members. The owner or an admin changes them; a moderator may also rename the project, manage its channels and manage its members (§2.5).

General — what the project is:

The Trailhead App project, Settings expanded on the General tab, beside Ground truth, Channels and Members. Rows: Display name, with a Save button; Description, holding one sentence that also appears under the project's name in the header; Use ground truth in this project, switched on; Use ENGRAM's default skills, switched on; and Agents must have an assigned skill, switched off.
The General tab of a top-level project. The description is what shows under the project's name in the header above it. A sub-project shows more rows, for what it inherits from its parent.

Ground truth — how the project answers from its ground truth:

The ground-truth settings are greyed out where your operator has not enabled ground truth; the page withholds a control rather than offering one the server would refuse.

Channels — the Buzz channels where the project's work is discussed, shown when your operator has enabled the Buzz integration. A sub-project also shows its parent's channels, read-only, unless its owner turns off Use the parent's channels. See Buzz & Chat Keys → A project's channels.

The Trailhead App project, Settings expanded on the Ground truth tab, beside General, Channels and Members. Three rows: Ground-truth policy, with Prioritize and Restrict buttons and Restrict selected, explained as ranking the ground truth up versus answering from the ground-truth corpus only; Inherit ENGRAM's default corpus, switched off; and Inherit ENGRAM's known-false list, switched on, explained as claims ENGRAM knows to be wrong about itself, separate from the corpus, never retrieved for anyone. The header pills read owner, 5 people, restrict and 3 ground truth.
The Ground truth tab of a top-level project. This one restricts answers to its own declared corpus and does not take ENGRAM's default corpus — but still inherits ENGRAM's known-false list, because the two are independent. A sub-project shows one more row, Inherit parent's corpus. The header pills report the same choices without opening settings.

2.4 The Ground Corpus panel

Two lists. Inherited is what the project draws in from elsewhere — read-only, each item tagged with where it came from. Declared is the project's own ground truth, which the owner adds to and removes from. A project that declares nothing and inherits nothing simply is not anchored: searches in it draw on everything you can already see, which is ordinary ENGRAM behaviour rather than a misconfiguration.

Declared articles must be readable by this project — public, or project-visible and yours. A private one would be invisible to the very people the project is meant to anchor, so it is refused rather than accepted with no effect — see §3.2.

2.5 Members: who is on the project

The Members tab, under the project's Settings, is the project's roster. Anyone who can open the project can read it. The owner is shown above the list and is never in it — ownership is a property of the project, and two records of one fact can disagree — and every member below carries a role chip.

What a member gets is small and worth stating exactly. 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:

Three roles, each including the one before it. Member is the read grant above. Moderator runs the project's people and process — who is on it, its channels and sub-projects, and the decisions on what members propose — and is still not a writer of what the project holds or answers from. Admin can do everything the owner can in the project except remove the owner. Those are project powers only: an admin does not gain the owner's private artifacts or memories, and declaring an article as ground truth still requires owning the article.

What the role allowsMemberModeratorAdminOwner
Read the project and the project-visible artifacts and skills it holds✓✓✓✓
Propose their own artifact or skill for the project✓✓——
Remove themselves from the project✓✓✓—
Add and remove members✗✓✓✓
Rename the project, bind its Buzz channels, attach a sub-project✗✓✓✓
Approve or reject a member's proposed artifact or skill✗✓✓✓
Submit a version for approval (a member: only their own)✓✓✓✓
Approve or reject a submitted version (the decider)✗✗✗✓
Assign a skill to an agent in the project✗✓✓✓
Read the sub-projects of a parent they hold this role on✗✓✓✓
Grant or revoke the Moderator or Admin role✗✗✓✓
Remove an admin✗✗✓✓
Add to the Project Library or the Agent Skills Library directly✗✗✓✓
Change the settings — ground truth, policy, inheritance✗✗✓✓
Mark library skills as inherited by sub-projects✗✗✓✓
Remove the owner✗✗✗—
Read the owner's private artifacts or any of their memories✗✗✗—

A dash means the question does not arise: an admin or owner adds directly rather than proposing, and the owner is never a member row. Declaring an article as ground truth needs Admin and ownership of the article.

Only the owner or an admin may grant Moderator or Admin, so neither role can propagate itself through a team; a permission that can grow its own population is not a permission. Those options only appear for the owner and admins — who can also change a member's role from the roster — and a moderator cannot remove an admin. Projects you administer carry an ADMIN pill in the project list. Over MCP and the API the moderator role is still spelled delegate.

Anyone may remove themselves, unconditionally. Nobody is held in a relationship they did not ask for, and a member who could not leave would have to ask the person who added them.

Who you may add is the population ENGRAM already uses for grants, not a new consent mechanism: people always; agents in your own sub-agent tree; and agents an administrator has opted in as recipients. Anything else is refused.

The Trailhead App project with the header pills owner, 5 people, restrict and 3 ground truth. Settings is expanded on its Members tab, beside General, Ground truth and Channels. Igor Polyakov is shown above the roster with an OWNER chip and the word 'you'. Four agents follow, each with a role picker and a Remove button: Trailhead API and Trailhead Worker set to member, Buzz Lead set to moderator, Claude Code-mac-book set to admin. Below is an add row with a role picker set to member, above hint text describing what members, moderators and admins can do.
Settings → Members, seen by the owner. Each member's role is a picker on their own row — member, moderator or admin — and the add row offers the same three. Only the owner and admins see the pickers; everyone else sees the role as a chip.

2.6 Sub-projects: units of work

A sub-project is a unit of work inside one repository — a service, a component, a stream someone owns. The repository is the parent; each unit hangs off it, and the Sub-projects panel is how you move between them: the repository card sits above its units, and clicking a card swaps the whole right-hand side.

A project is the unit of ownership; a repository is not. The parent belongs to the repository's owner, and each unit belongs to the colleague working it — so a second person on a shared repository owns their sub-project rather than needing a seat inside someone else's. A colleague's unit says whose it is.

Whoever leads the repository can open every unit. The parent's owner, and any admin or moderator on the parent, lead its sub-projects: they can open each unit and read its project-visible material without being added to it, which is what lets someone responsible for a repository see the work done in its parts. Leading is reading only — what a lead opens is read-only, and changing a unit stays with its own owner, admins and moderators. A unit's private material stays private to its owner.

Depth is one. A sub-project may not have sub-projects of its own, which makes cycles impossible by construction rather than by inspection. The repository URL lives on the parent only.

The sub-project API layer selected, titled 'Trailhead App / API layer', with the header pills member, 2 people, prioritize and 3 ground truth. Settings is collapsed. A Sub-projects strip shows the two units, API layer (Trailhead API, an agent) and Backend service (Trailhead Worker, an agent), with no Detach controls. Below it the tabs Ground Corpus, Project Library and Agent Skills, with Project Library open. It holds five articles, each with added by agent under its title and, on the right, its version, its visibility and an Approval menu, but no Flag or Remove controls. An Inherited section, from Trailhead App and read-only here, lists what the parent holds.
A unit selected, on its Project Library tab. Two things are worth reading together: an agent owns this sub-project — its card names Trailhead API (agent) — and the human viewing it is a member, as the header says. A project is the unit of ownership, so a colleague, or a worker, owns their unit rather than needing a seat in someone else's. And because this viewer is only a member, the write controls are gone: no Detach on the units, no Flag or Remove in the library. One control stays: Approval ▾. An agent owns the unit, so its decider is the human at the root of that agent's owners, the person viewing it, and a decider may submit and decide whatever their role (section 2.2). Below the unit's own five articles, Inherited lists what the parent holds: readable here, but not part of what this unit holds. Reads are wider than writes.

2.7 Agent Skills: what a project's agents work under

A skill is a set of standing instructions for an agent — how to work in this repository, which conventions to follow, what to check before it reports. Skills are written in the open Agent Skills format (a SKILL.md file). You can write one in the app, or an agent can write one over MCP or sync it from a repository. The Agent Skills tab is where a project decides which skills its agents work under. It appears only when an administrator has turned Agent Skills on.

The Agent Skills tab of a parent project, as its owner sees it, headed with the count 6. Pending additions holds api-contract-checks, proposed by Trailhead API (agent), with Approve and Reject buttons. The Library lists six skills, each with a checkbox for inheritance by sub-projects, its version, its visibility, an Approval menu and a Remove button; api-design-guide and git-workflow are ticked, and trailhead-coder says assigned to 1 agent. The last row's Approval menu is open, offering Submit for approval. Below, the Inherited section lists the three ENGRAM default skills, working-discipline, working-together and working-with-engram.
The tab as a parent project's owner sees it: a member's proposal waiting in Pending, and in the Library, the ticks that decide what every sub-project's agents also receive. 1 agent says that trailhead-coder is assigned to someone here. Each skill has the same Approval ▾ menu as the Project Library.
The sub-project API layer with its Agent Skills tab open, viewed by a member. The Library holds one skill, api-layer-conventions, version 1, badged PROJECT, with a New skill button above it and a search box reading Propose a skill below it. The Inherited section lists working-discipline, working-together and working-with-engram, each badged PUBLIC and ENGRAM DEFAULT, then api-design-guide and git-workflow, each marked from the parent project. Assignments reads: No agents on this project.
The same tab on a sub-project, seen by a member, which is why the library offers Propose a skill. Inherited shows both layers: ENGRAM's defaults, then what the parent ticked. No agent is on this unit yet, so there is nothing to assign.

An agent receives, in order: ENGRAM's default skills (general guidance every agent gets, such as how to work with ENGRAM), then the skills its parent project marked for inheritance, then its assigned skill and the parts it is built from. Either inherited layer can be switched off in Settings → General, which also has Agents must have an assigned skill. When an assignment changes or a skill is revised, ENGRAM rings a doorbell, so an agent's harness can fetch the new version and the agent works under it from its next turn. (Buzz's harness fetches its skill when an agent starts; fetching again on a doorbell arrives with Buzz v1.3.0.)

A skill in the library can be approved like an article (section 2.2, Approving a version). What an agent fetches carries its skill's approval status and the approved version, and says when a part the skill is built from has changed since it was approved. The agent still works under the current version; the status is there for whoever reviews its work.

The New skill editor, a panel open over the Agent Skills tab. Fields for Name, Kind (generic), Visibility (private), Title, Description and Tags, then a collapsed License, compatibility, metadata section. Below them Content with Write and Preview tabs and a character count, and Built from, with Extends: Choose a base, and Include a part. The footer reads Fix 3 problems to save, with a Show link, beside Cancel and a disabled Create skill button.
The New skill editor, before anything is filled in. The footer counts what is still wrong, Show lists it, and Create skill stays disabled until nothing is.

3. Ground Truth: the documents a project answers from

Retrieval is associative — it finds what's related to your question. That is what you want while you're exploring. It is not what you want when a question has a right answer and the wrong one is expensive.

Ground Truth lets a project name the articles that are authoritative for it. Questions asked in that project are then answered from the documents you chose, rather than from whatever happens to sit nearby in your knowledge base.

3.1 When you want it

3.2 Declaring a project's ground truth

Pick the articles that are authoritative and declare them. The guard is readability, not a particular visibility value: ENGRAM asks whether this project's members can read the article, and refuses one they cannot rather than silently anchoring nobody.

The practical consequence is worth stating plainly: a team's brief no longer has to be published to the world to be shared with the team.

A declared article stays authoritative across edits: revise it and the newest version is what answers, with no need to re-declare. Declare nothing and the project behaves exactly as it always has.

3.3 Prefer, or bind

The setting with the largest effect on what you get back:

Choose restrict when being wrong costs more than being incomplete. Otherwise prefer is the safer default, and you can move between them at any time.

3.4 The corpus you already have

ENGRAM ships its own documentation as ground truth, and your default project already draws on it. Ask "how does recall actually work?" and the answer comes from ENGRAM's own reference rather than from whatever you happen to have saved. There is nothing to switch on.

A project where you have declared your own ground truth keeps exactly the scope you gave it — inheriting ENGRAM's corpus is something a project opts into, never something a release does to it. And a project can do both: hold ENGRAM's reference and its own, which is what you want when writing about ENGRAM alongside something else.

3.5 The same set checks new articles

When an agent drafts an article into your knowledge base, ENGRAM verifies its claims against your ground truth before it lands — so a confident invention that contradicts your own documents is caught rather than filed. The check reads the whole declared set rather than searching it, which is why its verdict doesn't drift with how a question happens to be phrased.