Keep research history
Advanced · Assumes basic Python, database, and terminal skills. Start with the Advanced introduction for GraphForge terminology, or Basic for a guided first graph.
This optional journey is for research that needs independent work, retained history, or review. For a graph and a query, use the quickstart. For a hypothesis you want to challenge and retrieve later, start with Record and revisit an inquiry.
The research APIs add precise context and history to those tasks. They do not require every user to follow an entire lifecycle. This guide explains the choices; the research workspace reference contains the exact requests and result contracts. For Branches, commits, tags and collaboration without request files or UUIDs, use the git-style command workflow below. The lower-level API examples also cover operations such as retaining a Project-context Version.
Start with the quickstart for a local graph and query, or clone a published project and follow its matching-runtime instructions. Continue the work locally before choosing a publishing target. Portable export and import let you exchange verified project bytes without a hosted write service.
Keep an exact state while you continue
Section titled “Keep an exact state while you continue”Start with one task: retain a paper’s original annotation, revise the working graph, then retrieve both values in a later session. This uses a Version without a Slice, Branch, or Proposal. Use a new empty directory on supported durable storage.
from pathlib import Pathfrom time import time_nsfrom uuid import uuid4from graphforge import GraphForge
Path("history-project").mkdir()forge = GraphForge("history-project")forge.add_node("Paper", title="Survey", note="Original annotation")version_uuid = str(uuid4())prepared = forge.prepare_research_version({ "operation_uuid": str(uuid4()), "version_uuid": version_uuid, "context_uuid": str(uuid4()), "label": "Before annotation revision", "description": "Survey before changing the working annotation", "created_at": time_ns() // 1_000, # UTC microseconds "required_versions": [],})forge.commit_research_version_operation(prepared)forge.execute("MATCH (p:Paper {title: 'Survey'}) SET p.note = 'Revised annotation'")forge.close()The UUIDs identify this capture, its operation, and its research context; the
standard library generates them. Keep the exact prepared request unchanged
if retrying the commit. A new capture uses new identities. Repeat the whole
example only in a new empty directory.
In a later Python session, open the same path. Discover the retained Version by its label, then query that exact state and the current graph:
from graphforge import GraphForge
forge = GraphForge("history-project")matches = [ row for row in forge.list_research_versions().to_pylist() if row["label"] == "Before annotation revision"]if len(matches) != 1: raise ValueError("Choose exactly one retained Version before continuing.")version_uuid = matches[0]["version_uuid"]query = "MATCH (p:Paper {title: 'Survey'}) RETURN p.note AS note"print("Retained:", forge.query_research_version(version_uuid, query).to_pylist())print("Current:", forge.execute(query).to_pylist())forge.close()Expected output:
Retained: [{'note': 'Original annotation'}]Current: [{'note': 'Revised annotation'}]You can stop here. The retained state remains distinct from live edits and can anchor a conclusion to its original graph context. The same capture operation can retain the graph records from an inquiry. It does not make the reasoning correct or retain external source files merely named in a property; register source material as native Artifacts when that is needed. The remaining sections are orientation, not executable tutorials. They explain when an additional tool is useful and link to its exact public request contract. Those references assume you are ready to construct and inspect API requests; the Version example above is a complete stopping point.
Focus only when the full graph is too broad
Section titled “Focus only when the full graph is too broad”Suppose Ada appears in two stories, Mystery and Voyage. You want to investigate Mystery without including every fact about Voyage.
A Slice defines the selected graph and why each item belongs. Inspect the included items, outside boundary, and evidence dependencies before freezing it. Ada’s inclusion does not silently include the second story. Source material supporting a claim and graph membership remain separate questions.
You can stop here and analyze the selection. A Slice does not require a Branch.
The implemented Slice facade
documents preview_slice, freeze_slice, and the inspection requests.
Branch when work needs to evolve independently
Section titled “Branch when work needs to evolve independently”A Branch is an independent research workspace with an origin and its own current state. Create one when you want to change interpretations, properties, or working knowledge without changing the source Project.
Ask which state is inherited and which changes are local. Working independently is a state-management choice, not a privacy setting. Access to a private Project is enforced by its host, not by creating a Branch. Use the implemented Branch facade for creation, querying, independent edits, and restoration.
Retain a Version when you need an exact reference
Section titled “Retain a Version when you need an exact reference”A Version retains a particular research state. Refer to it when recording what evidence and graph context informed a conclusion. Live work can continue without changing that reference. A Version is distinct from a saved query: the query stores the analysis definition; the Version identifies retained state.
Retaining a Version does not make unavailable external bytes available. Inspect whether evidence is retained locally, external-only, or released before relying on it. Retrieval must report unavailable historical material rather than silently substituting a newly fetched source. The native Version lifecycle describes capture, inspection, retention, and restoration requests.
Compare before incorporating changes
Section titled “Compare before incorporating changes”Compare your work against the intended parent or upstream state. Review the actual objects and fields that changed. Bring selected upstream changes into your Branch deliberately; an unselected change remains unapplied.
The comparison contract defines the compared states and reported changes. The upstream request contract documents previewing and applying selected updates. Inspect the operation receipt and resulting graph before relying on the change.
Propose and accept only when review is needed
Section titled “Propose and accept only when review is needed”A Proposal selects contributions from a retained source Version. A reviewer can accept some items and defer others. Accepting Ada’s score need not accept the proposed ending of the story. Later Branch edits do not change the frozen contribution being reviewed.
Acceptance applies the selected contribution. It does not automatically make an assertion canonical or establish that a conclusion is true. Inspect what changed, the evidence supporting it, and the recorded review outcome.
When retrying a committed operation, reuse its original identity and request. Changing a request is a new decision; do not disguise it as a retry. The selective Proposal contract provides the preparation, submission, review, and acceptance requests.
Continue or share
Section titled “Continue or share”Continue working after review. Use the retained Version to revisit earlier context; use the current Branch for ongoing work. A Fork creates a separate Project with its own identity and history when independent ownership is needed.
Public projects support transparent participation with attributable authors and committers, following Git practices. Private projects provide a non-public space for known collaborators. Choose the appropriate project space when sharing; privacy is not a prerequisite lesson for basic graph use. Hosting applications own authentication and access enforcement. Project metadata holds no access fields. Published credit is public and permanent: the authors and committers recorded on Versions are always published, and the Project people list in the summary is derived from them.
Use portable projects for actual transfer and Hub clone. History, fast-forward publication, rewrite, and prune behavior are implemented in the native research API and the installed CLI; the sections below walk each operation against a conforming Hub, and the publish contract states the precise refusal rules.
Share with gf
Section titled “Share with gf”Research history has a git-style command set that needs no JSON and no UUIDs. A
Branch is named by its label, and that label is the ref on the Hub: --ref means
the same thing in gf clone, gf push and gf pull.
These shell examples use the gf CLI from Installation.
Run these local commands from an existing durable Project. The sample queries
assume it contains Item nodes; use the labels and properties in your graph.
--project "$PWD" selects that Project by its absolute path: changing
directories alone does not select it, because commands without --project
discover repository-managed state. From another directory, pass the Project’s
absolute path instead of "$PWD".
These examples use the main Branch. If continuing the earlier Hub research
example, main is already selected: skip the branch main command.
gf config user --name "Ada Lovelace" --email ada@example.org # credited on every Versiongf --project "$PWD" branch main # the first Branch of the Projectgf --project "$PWD" commit -m "Raise scores" --query "MATCH (n:Item) SET n.score = 2"gf --project "$PWD" commit -m "Fix a typo" --query "MATCH (n:Item) SET n.name = 'Ada'"gf --project "$PWD" tag v1 # a name for the head Versiongf --project "$PWD" status # Branch, head, upstream, commits not yet publishedgf --project "$PWD" log # history; add --all, -n 5, a tag, or --remoteChoose a publishing target
Section titled “Choose a publishing target”Publishing requires a Hub implementing graphforge-discovery/1 and
graphforge-hub-publish/1, such as graphforge.sh, an
owner account, and permission to publish to the repository. Each collaborator
signs in with gf auth login; the saved session obtains the repository-scoped
publish credential. A recorded author name supplies credit, not authorization.
For agents and CI, see the
scoped token path.
On a headless host with no OS credential vault, gf auth login fails closed
with hub.auth_denied: OS credential vault unavailable; use that token path
or an unlocked Secret Service keyring.
The collaboration tests use the native reference Hub at https://hub.test;
that address is not a public service. Replace owner/repository below with a
repository you may write. Names resolve on graphforge.sh; pass --hub or a full
repository URL for another Hub.
Sign in once, then push with the saved session:
gf auth logingf --project "$PWD" push owner/repository --ref main --public--public creates a public repository, or requires an existing one to be public;
use --private for a private repository on a plan that allows one.
In a separate collaborator shell, select the same CLI and start outside the original Project. Clone the published ref, then work inside the clone:
gf clone owner/repository collaborator --ref maincd collaboratorgf config user --name "Grace Hopper" --email grace@example.orggf --project "$PWD" commit -m "Revise scores" --query "MATCH (n:Item) SET n.score = 3"gf --project "$PWD" push # reuse the tracked repository and refBack in the original Project, incorporate the collaborator’s published change:
gf --project "$PWD" pullgf --project "$PWD" logUse --tag v1 instead of --ref main to clone the tagged Version. Tags travel
with published research lineage; they are not separate Hub refs.
The clone and pull examples assume public read access. A publish credential is
not a read credential; configure read-side authentication separately if required
by the selected Hub.
gf commit records its message as the Version description and credits the author
and committer from --author/--committer, then GF_AUTHOR/GF_COMMITTER, then
gf config user. gf pull records a Version with your head and the Hub’s head as
its parents, adopting every change that does not conflict; when fields conflict it
stops, names them, and leaves the explicit review to gf research upstream update.
gf switch <ref> selects the Branch the other commands act on when a Project has
several. Rerun a command with the --operation-uuid it printed to get the original
result instead of a second Version. The gf research ... commands are the native
JSON verbs these wrap.
For integrators
Section titled “For integrators”The two-story corpus and acceptance matrix map these steps to real Rust, Python, Node, and CLI execution, captured Arrow results, receipts, and recovery tests. They establish Core behavior, not packaged editor usability or observed human comprehension. Use #1209 for qualification of those entry experiences.
Continue a published Branch
Section titled “Continue a published Branch”The following sections walk the collaboration cycle: clone a published Branch, commit to the clone, publish back, incorporate a divergent remote head, and rewrite or prune published history.
Against a conforming publish-capable Hub, clone a named Branch, edit it through
the native research Branch API, then publish that same ref back. The clone keeps
the original Project and Branch UUID, creation record and selected head; the next
commit records that head as its first parent. Authors and committers remain exact
native record metadata. Reopen and inspect historical records with
research_version; a metadata-only ancestor is not a retained payload.
The other advertised refs remain read-only remote citations. Immutable-Version
clones stay detached. Publishing divergent work is refused as non_fast_forward;
a stale repository revision is still ref_conflict. Neither refusal moves a ref.
Merge and explicit rewrite/prune are separate operations. Production hosted write
availability is independent of this native protocol behavior.
Incorporate a divergent head of the same Branch
Section titled “Incorporate a divergent head of the same Branch”Use the native fetch_research_branch API with the exact discovery manifest, refs,
lineage and downloaded complete package. The owning Project must already contain
the original Branch. Fetch returns a receipt-bound ResearchRemoteFetchBinding;
it imports verified content and refreshes the remote citation without replacing
your local head or workspace.
Pass that binding as PreviewResearchUpstreamRequest.remote to inspect the remote
Version through the ordinary field review. Resolve conflicts explicitly and pass
the exact preview to update_research_branch. The result records your prior head
first and the fetched remote head second. An intervening local edit or remote
refresh makes an uncommitted preview stale. Omit remote to retain the existing
immediate-parent review. This API does not add a gf fetch command or cross-owner
Proposal workflow.
Same-Branch remote reviews compare both heads against their unique maximal common native Version, including each head in its own ancestry. The base must retain verified content; unavailable bases and ambiguous crisscross histories refuse explicitly. The preview commitment includes this base. A local revert therefore remains a local change relative to the shared history, including after repeated remote incorporations. Immediate-parent reviews keep their existing field baseline and canonical preview identity.
Explicit history replacement and retention
Section titled “Explicit history replacement and retention”Normal gf publish refuses divergent history. After reviewing the replacement,
gf publish <repository> --ref main --rewrite explicitly requests head replacement;
add --prune only to remove unreachable published Versions. The Hub must offer
history-mutation@1, authorize the repository operation and accept the current
revision lease. A concurrent update remains a conflict, never permission to
replace a newer head. Surviving refs and their history/dependencies remain live.
The reference Hub collects unreferenced objects after its documented 900-second
grace; local retained copies and independent Fork copies are unaffected.
For an established independent Fork, --check-fork-origin <repository URL> is an
optional origin diagnostic. A validated origin lineage missing the cited Version
warns and proceeds with the local copy. The citation contains no origin host, so
ordinary updates do not discover erasure automatically or probe another Hub.
See the publish contract for the precise
lease, identity, dependency and refusal rules.