Projects & Living Briefs
A Project is a governed workspace around a question, decision, client, or initiative. It admits a specific set of sources, keeps retrieval inside that corpus, and maintains a cited brief as the evidence changes.
Use Projects when an organization-wide search would be too broad. The source boundary, project roles, citations, and version history make the result useful for real work rather than a one-off summary.
The workflow
- Create the Project. State the question or outcome the team is working toward.
- Admit sources. Add only the documents, transcripts, and records that should ground this work.
- Ask the Project. Project-scoped retrieval searches admitted sources and returns source-backed answers.
- Generate the brief. MindGraph produces findings, tensions, open questions, and an executive summary with citations.
- Keep it current. New sources make the brief stale; regenerate to see what materially changed.
PartOfProject edge admits a source to the corpus. It does not grant a person or agent access to that Project. Authorization comes from Project roles.Source boundary
Project Ask and brief generation retrieve from admitted sources only. If a relevant source is missing, add it deliberately rather than letting organization-wide knowledge leak into the answer. Every brief assertion points back to the document and source node that supports it.
In the dashboard, open Projects, choose a Project, then use its Sources, Ask, and Brief views.
Living brief
A brief is a versioned decision artifact, not a chat response. It contains:
- Executive summary — the smallest useful account of the current evidence.
- Findings — supported conclusions and material observations.
- Tensions — contradictory claims or evidence that should not be flattened away.
- Open questions — evidence gaps and unresolved decisions.
- What changed — additions, removals, and revisions since the previous version.
| State | Meaning |
|---|---|
| missing | No brief has been generated yet. |
| ready | The current brief matches the admitted source fingerprint. |
| stale | The source corpus changed after the current version was generated. |
| unavailable | The brief cannot currently be generated; the API returns the reason rather than presenting an empty result as healthy. |
Regeneration reuses the existing brief when the source fingerprint has not changed. If a regeneration fails, the last valid version remains visible. You can pin an important item, unpin it, or correct its wording with replacement citations; each action creates an audited version.
Project roles
- Viewer — read the Project and its admitted corpus.
- Editor — read and change Project-scoped knowledge.
- Agent — run with Project-scoped context and write within the Project boundary.
Owners and admins manage roles through the dashboard or the JWT Management API. Revocation takes effect on the next request; API keys cannot administer Project authority. See Project role management.
Brief API
/projects/{project_uid}/briefGet the current state and latest valid brief/projects/{project_uid}/brief/regenerateGenerate a new version, or reuse the current one when sources are unchanged/projects/{project_uid}/brief/items/{item_id}Pin, unpin, or correct an item with optimistic version checking/projects/{project_uid}/brief/historyList version summaries and material changes/projects/{project_uid}/brief/history/{version}Retrieve a specific historical version# Get the current brief state
curl https://api.mindgraph.cloud/projects/proj_abc/brief \
-H "Authorization: Bearer mg_..."
# Regenerate after adding sources
curl -X POST https://api.mindgraph.cloud/projects/proj_abc/brief/regenerate \
-H "Authorization: Bearer mg_..." \
-H "Content-Type: application/json" \
-d '{"expected_version": 3}'
From gap to action
Open questions are meant to drive the next research step. Use Investigate to start scoped follow-up work, or Add source when the answer exists outside the current corpus. Regenerate after the evidence arrives so the brief records how the conclusion changed.