UAI-1 is the current public message standard for structured AI-to-AI communication.
UAIX shield mark Public interoperability charter UAIX.org Universal Artificial Intelligence Exchange Public standards publication
Current UAI-1
  • Current version UAI-1
  • Plain-English definition Open message format for auditable AI-to-AI exchange
  • Current attribution Michael Joseph Kappel, MCP
  • Start here Get Started, Project Handoff, UAI-1, validator, roadmap, and changelog

Guides

Project Handoff Knowledge Graphs

Practical guide for making Project Handoff graph-ready with stable IDs, provenance, claim nodes, constraints, decisions, checks, cold-memory pointers, and bounded GraphRAG use.

  • Record UAIX-DOC-1300
  • Path /en-us/guides/project-handoff-knowledge-graphs/
  • Use Canonical public record

Document status

Public standards page Published on UAIX as part of the current public standards record
Code
UAIX-DOC-1300
Surface
Guides
Access
Public and linkable

How to use this page

Use this page as part of the current Guides public record, then follow its linked standards pages for the next step.

Project Handoff is graph-ready portable memory. A knowledge graph can make handoff memory easier to query, verify, slim, archive, and promote, but the current Project Handoff source of truth remains the reviewed repo-local file bundle: AGENTS.md, readme.human, typed .uai records, evidence ledgers, and accepted project artifacts.

Use this guide when a team wants AI memory that can answer relationship questions such as which constraints apply to a route, which decisions affected a test plan, which claims lack evidence, which old reports moved to cold memory, and which facts are safe to share with a receiving agent.

Project Handoff knowledge graph boundary

  • Current UAIX support: public guidance for graph-ready Project Handoff design, stable identifiers, source/provenance fields, validation questions, wizard planning fields, and optional LLM Wiki knowledge-graph planning.
  • Current source of truth: the reviewed file bundle and public UAIX pages, not an inferred graph cache or retrieval answer.
  • Current export posture: any graph projection should be derived and read-only until reviewed; it is evidence navigation, not automatic repository writing.
  • Not current support: hosted graph database, public graph API, public SPARQL endpoint, automatic LLM Wiki sync, automatic import, SDK, CLI, certification, endorsement, conformance profile, or official adapter.

Graph-ready memory model

Graph node Project Handoff source Why it matters
Project AGENTS.md, .uai/context.uai Names the system, scope, audience, owners, and public authority boundary.
Handoff bundle AGENTS.md, readme.human, loaded .uai list Shows what a receiving agent must load before work.
Document artifact Docs, public pages, code paths, package files, discovery assets Connects memory to the file or route that changed.
Context record Typed .uai files Separates stack, architecture, constraints, operations, progress, decisions, style, public surface, and tests.
Constraint .uai/constraints.uai, AGENTS hard rules Prevents agents from bypassing secrets, support-claim, destructive-operation, and public-route limits.
Decision .uai/decisions.uai, changelog, release notes Explains why current behavior exists and when it can change.
Work item .uai/progress.uai, roadmap, intake disposition Connects current work, blockers, checks, next actions, and accepted outcomes.
Check .uai/test-plan.uai, scripts, package tests, validator results Shows what evidence is required before claims move forward.
Claim Public page copy, roadmap text, machine artifacts, generated plans Lets UAIX track whether a claim is current, planned, unsupported, stale, or source-needed.
Risk Constraints, privacy/security docs, File Handoff dispositions Routes private data, destructive actions, unsupported claims, and unsafe files to review.
Agent run Accepted summary, changed files, checks run, blockers Preserves useful run output without storing raw private traces as operating truth.
Cold memory record LLM Wiki, AIWikis archive, transfer manifest, source summary Keeps bulky research recoverable while hot handoff stays compact.

Useful edge vocabulary

Edge Meaning Example
references A record points to a route, file, schema, source, or public artifact. .uai/public-surface.uai references /en-us/tools/validator/.
containsRecord A bundle contains a typed memory record. AGENTS.md contains the required @uai[] load list.
appliesTo A constraint, check, or decision applies to a file, route, package, or claim. Support-claim boundary applies to the AI Memory Package Wizard.
requiresCheck A changed surface requires a targeted check before completion. Wizard changes require focused wizard checks.
blockedBy A work item cannot proceed until a named fact or owner decision exists. Release completion blocked by missing production upload.
approvedBy A person, review note, release, or public artifact accepted the change. Changelog entry approves the current public support wording.
mayReverseWhen A decision can change when specified evidence appears. A planned adapter can become current only after fixtures and owners exist.
hasTrustBoundary A record carries a privacy, secret, support, locale, or destructive-operation boundary. File Handoff forbids executing dropped files.
archivesToColdMemory Bulky history moved out of hot handoff with transfer evidence. Old intake report archived with checksum and summary.
wasDerivedFrom A public or generated record came from named source material. Roadmap item derived from a reviewed intake report and current public evidence.

Identifier policy

Use stable identifiers for enduring facts and snapshot identifiers for dated states. A graph node should not depend on a title that might be rewritten, a file path that might move, or a page slug that might be localized. Keep human-readable labels close to the node, but treat the stable ID as the citation handle.

Code example
uaix:project/uaix
uaix:handoff-bundle/uaix-local
uaix:record/.uai/constraints.uai
uaix:constraint/no-automatic-repository-writes
uaix:claim/ai-memory-wizard-current-output
uaix:check/scripts-test-uaix-ai-memory-bundle
uaix:snapshot/2026-05-06-project-handoff-kg-guide

Standards projection

Project Handoff does not require RDF or JSON-LD. When a project does need graph interchange, use the standards as projections over reviewed memory, not as a replacement for the file bundle.

Standard UAIX use Boundary
RDF Represent reviewed handoff statements as triples and named graphs. Export only after source files are reviewed.
JSON-LD Share graph-shaped metadata in JSON with explicit contexts. Good for derived overlays and web-facing structured records.
PROV-O Model derivation, source, actor, and review-event lineage. Keep original evidence; provenance markup is a pointer, not the evidence itself.
SHACL Describe graph shape checks for required IDs, source traces, owners, and claim statuses. Failed graph lint blocks export readiness; it should not rewrite sources automatically.
SPARQL Run golden queries over a reviewed graph projection. Public query endpoints remain outside current support.
SKOS Manage labels, aliases, broader/narrower concepts, and controlled terms. Useful before heavier ontology commitments.
OWL Add formal ontology rules only when the domain semantics are stable. Do not introduce reasoning that hides source uncertainty.

RDF, property graph, and markdown roles

The safest UAIX pattern is source-file canonical, RDF/JSON-LD capable, and property-graph friendly. The files remain the write path. Standards and graph databases are projections chosen for a job.

Layer Use it for Do not use it for
Project Handoff files Authoritative current memory, constraints, decisions, intake outcomes, checks, and human-readable review. Heavy graph traversal or external linked-data exchange by itself.
JSON-LD/RDF/Turtle projection Stable semantic interchange, named graph snapshots, provenance, SHACL validation, and standards-aligned graph release planning. Replacing the reviewed file bundle or hiding uncertainty behind inference.
Property-graph projection Impact analysis, graph exploration, relationship dashboards, Cypher-style workflows, and operational navigation. Becoming a second source of truth that can drift from AGENTS.md, readme.human, and .uai.
Vector or GraphRAG retrieval Finding likely relevant records, expanding neighborhoods, and assembling evidence bundles. Promoting retrieved text, generated answers, or nearest-neighbor confidence into accepted project truth without review.

Derived graph pipeline

  1. Parse the handoff bundle: read AGENTS.md, readme.human, loaded .uai records, selected docs, public routes, and evidence ledgers.
  2. Normalize identity: mint stable IDs for projects, records, sections, claims, constraints, decisions, checks, files, routes, and snapshots; keep titles and slugs as labels.
  3. Extract reviewed facts first: use front matter, headings, explicit @uai[] links, route registries, roadmap IDs, test-plan rules, and intake ledgers before LLM extraction.
  4. Attach provenance: every claim, constraint, decision, check, and archive pointer should say which source file, section, route, checksum, review event, or release produced it.
  5. Validate: run schema checks, graph lint, SHACL-style shape checks, golden handoff queries, and support-claim checks before export or retrieval use.
  6. Project outward: emit JSON-LD/RDF/Turtle or a property-graph load only after the reviewed file state is coherent.
  7. Write back deliberately: accepted findings return to current handoff files, docs, code, tests, roadmap, changelog, or machine artifacts; the graph cache itself is not the write-back target.

Claim and evidence states

State Meaning Allowed handoff behavior
proposed Extracted from a report, LLM draft, old note, or unreviewed page. Use as background only; do not present as current support.
reviewed Source, owner, contradiction, sensitivity, and target surface were checked. May guide work when it matches the current task and constraints.
current Promoted into active files, public pages, machine artifacts, tests, release notes, or roadmap state. May be loaded as operating truth until superseded.
stale Known to be old, uncertain, superseded, or outside the current route/support surface. Keep visible as history; do not use without fresh review.
blocked Private, unsafe, unsupported, contradictory, or missing authority. Stop and ask a human or route to the owner before promotion.

Golden handoff queries

  • Which constraints apply to this route, package, test, or public claim?
  • Which decisions changed this file, and which evidence would let us reverse them?
  • Which current claims lack public evidence, tests, or matching machine artifacts?
  • Which active intake files are related to the current prompt and still need real project work?
  • Which bulky reports were moved to cold memory, where are the hashes, and what was promoted back to hot memory?
  • Which checks are required before this change can be called complete?
  • Which facts are safe to share externally, and which are private, unsupported, stale, or background-only?

GraphRAG and retrieval boundary

GraphRAG can help a receiving agent find the right records and relationship paths faster. It must still cite the source files, expose contradictions, preserve support-boundary labels, and treat answers as candidates until the normal Project Handoff promotion rule is satisfied. Retrieval is assistance; reviewed memory remains authority.

Wizard support

The AI Memory Package Wizard can plan optional LLM Wiki knowledge-graph fields for projects that deliberately use a deeper wiki layer. Those fields should name graph strategy, stable ID policy, validation policy, export policy, and GraphRAG/query policy. The generated plan remains a local planning file and does not create automatic sync or a public graph service.

Promotion rule

A graph fact becomes operational only when the underlying fact is reviewed and promoted into a current surface: AGENTS.md, readme.human, typed .uai records, canonical docs, public pages, code, tests, release notes, roadmap state, changelog, validator evidence, or machine artifacts. A graph cache, embedding result, or LLM answer is not enough.