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 LLM Wiki knowledge-graph planning required for graph-memory configuration.
- 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.
This is not a hosted graph database; it is guidance for deriving graph-ready projections from reviewed Project Handoff files while keeping source files authoritative.
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.
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-guideStandards 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, .uai/readme.human, and .uai. |
| Vector or graph-assisted 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
- Parse the handoff bundle: read
AGENTS.md,.uai/readme.human, loaded.uairecords, selected docs, public routes, and evidence ledgers. - Normalize identity: mint stable IDs for projects, records, sections, claims, constraints, decisions, checks, files, routes, and snapshots; keep titles and slugs as labels.
- Extract reviewed facts first: use front matter, headings, explicit
@uai[]links, route registries, roadmap IDs, test-plan rules, and intake ledgers before LLM extraction. - Attach provenance: every claim, constraint, decision, check, and archive pointer should say which source file, section, route, checksum, review event, or release produced it.
- Validate: run schema checks, graph lint, SHACL-style shape checks, golden handoff queries, and support-claim checks before export or retrieval use.
- Project outward: emit JSON-LD/RDF/Turtle or a property-graph load only after the reviewed file state is coherent.
- 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?
Graph-assisted retrieval boundary
Graph-assisted retrieval 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 LLM Wiki knowledge-graph fields required for graph-memory configuration for projects that deliberately use a deeper wiki layer. Those fields should name graph strategy, stable ID policy, validation policy, export policy, and 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.
Related records
- Project HandoffThe canonical repo-local memory bundle.
- AI MemoryPortable memory framing and supported starter bundles.
- AI Memory Package WizardGenerated local files and long-term pointer ledger configuration.
- Context BudgetKeep hot handoff memory compact while bulky graph evidence moves to cold memory.
- Agent File HandoffDisposition active intake before graph or memory promotion.
- LLMWikis.org Knowledge GraphsDeeper handbook guidance for LLM Wiki graph design.
- RoadmapCurrent versus planned graph, adapter, sync, SDK, CLI, and conformance boundaries.
- ChangelogDated public change trail.
Hierarchical Goal Memory
Pair graph-ready handoff records with Hierarchical Goal Memory by treating the graph as a Derived Memory Hierarchy, not as the source of truth.