UAIX .uai files are structured memory and handoff records for agents and human reviewers. They make package state portable, inspectable, bounded, and reviewable across sessions, tools, and teams.
Closed required-file-set rule: every UAIX package file is universal required, profile-required, content-triggered required, configuration-specific required, or out of scope. UAIX does not describe package files with softer file-status terms.
What .uai Files Are
A .uai file is a typed record inside a package. It carries accepted context, boundaries, owner intent, handoff instructions, or evidence for a declared package scope. It is not magic memory, runtime execution, certification, proof of consciousness, or a substitute for human review.
File Taxonomy
Universal lifecycle and protection policy
.uai/memory-maintenance.uai- Universal required file
Universal launch-baseline anchors
.uai/identity.uai- Universal required file.uai/world-context.uai- Universal required file.uai/totem.uai- Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order..uai/taboo.uai- Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order..uai/talisman.uai- Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order.
Project Handoff startup files
.uai/startup-packet.uai- Required for Project Handoff packages.uai/system-profile.uai- Required for Project Handoff packages.uai/receiver-brief.uai- Required for Project Handoff packages
Active project memory files
.uai/context.uai- Required for Project Handoff packages and project/developer packages.uai/constraints.uai- Required for Project Handoff packages and project/developer packages.uai/progress.uai- Required for Project Handoff packages and project/developer packages.uai/operations.uai- Required for Project Handoff packages and project/developer packages.uai/decisions.uai- Required for Project Handoff packages and Decision Memory packages.uai/overview.uai- Required for project/developer packages.uai/open-questions.uai- Required for project/developer packages that carry unresolved decisions, risks, or owner questions.uai/next-actions.uai- Required for project/developer packages.uai/owners.uai- Required for project/developer packages with named owners, reviewers, or approval roles.uai/agent-instructions.uai- Required for project/developer packages that declare agent-specific operating instructions
Developer and release evidence files
.uai/test-plan.uai- Required for project/developer packages and release-bound packages.uai/coding-standards.uai- Required for project/developer packages and packages that declare code, automation, executable workflow, or code-like artifacts.uai/next-recursive-prompt.uai- Required for agents that deal with code, automation, executable workflows, or code-like artifacts: next-recursive-prompt.uai.reports/deployment-memory-and-test-report.uai- Required for release-bound deployment packages and production package builds.uai/stack.uai- Required for project/developer packages that declare runtime, framework, hosting, or dependency stack.uai/architecture.uai- Required for project/developer packages that declare architecture, modules, integrations, or code-bearing work
Developer and publication evidence files
.uai/style.uai- Required for project/developer packages that declare design, editorial, brand, or interface style
Long-memory and transfer files
.uai/memory.uai- Required for AI Memory packages.uai/long-term-memory.uai- Required for Long-Term Memory packages.uai/file-handoff.uai- Required for Agent File Handoff packages
Evidence and audit files
.uai/intake-outcome-ledger.uai- Required for Agent File Handoff packages that declare intake outcome evidence.uai/risk-register.uai- Required for project/developer packages that carry security, privacy, deployment, legal, product, or reliability risk.uai/archives/changelog.uai- Required for project/developer packages and release-bound packages
Assistant and persona profile files
.uai/persona.uai- Required for non-project assistant packages, persona profile packages, advanced_persona_profile packages, bounded personality packages, and packages that support persona switching.
Master Matrix
| File | Category | Required status | Primary purpose | Main reader | Update frequency | Human review requirement | No-op trigger type | Detail page |
|---|---|---|---|---|---|---|---|---|
.uai/memory-maintenance.uai | Universal lifecycle and protection policy | Universal required file | Defines memory lifecycle, hot and cold boundaries, compaction cadence, archival policy, promotion and demotion rules, access controls, default active instruction anchors, review gates, validation behavior, and memory write safety. | Receiving AI, validator, package builder, human reviewer, package steward | At package creation and whenever lifecycle, active instruction anchor, validation, access, archival, or memory-write rules change. | Required before first use and before any lifecycle, active instruction anchor, or access-control change. | Missing or invalid memory-maintenance.uai, Totem/Taboo/Talisman missing from the required active-anchor read set, missing hot/cold boundary, missing archival rule, or missing enforcement behavior. | memory-maintenance.uai |
.uai/identity.uai | Universal launch-baseline anchors | Universal required file | Names the package, owner, source authority, declared profiles, namespace, sensitivity boundary, and actor boundary. | Receiving AI, human reviewer, package steward | At package creation and whenever ownership, namespace, authority, sharing boundary, or declared profile changes. | Required before first use and before any identity, ownership, authority, or namespace change. | Missing owner, unclear source authority, namespace collision, unsupported declared profile, or contradictory identity. | identity.uai |
.uai/world-context.uai | Universal launch-baseline anchors | Universal required file | Captures the current environment, workspace root, canonical locations, external systems, time boundary, and routing context. | Receiving AI and operators moving between workspaces or deployments | Whenever workspace paths, deployment targets, ecosystem roles, active sites, or operating assumptions change. | Required when the file changes project ownership, canonical paths, deployment posture, or public ecosystem claims. | Ambiguous workspace, stale production target, missing canonical root, or conflict with local AGENTS.md guidance. | world-context.uai |
.uai/totem.uai | Universal launch-baseline anchors | Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order. | Default positive guardrail anchor. Agents must read and obey it before broad execution; package builders generate, validate, package, export, and index it for the selected package scope. The default Totem also carries the recursive Suggested Next Prompt contract: accepted work must end with a visible, copy-paste-ready prompt containing Feature/improvement focus, Code/source changes, and Automated tests/checks sections with concrete next work or an explicit no-op/source-validation stop condition. | Receiving AI, human reviewer, package steward | When the positive operating anchor changes, and only through explicit human artifact-and-operation authorization. | Required before any modification. Reading, validating, packaging, exporting, and obeying the file are default launch-baseline behavior. | Missing, unreadable, stale, contradictory, missing the recursive Suggested Next Prompt contract, or any request to modify, weaken, delete, replace, or bypass the totem without exact artifact-and-operation authorization. | totem.uai |
.uai/taboo.uai | Universal launch-baseline anchors | Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order. | Default hard-boundary guardrail anchor. Agents must read and obey it before broad execution; package builders generate, validate, package, export, and index it for the selected package scope. | Receiving AI, human reviewer, package steward | When the hard boundary changes, and only through explicit human artifact-and-operation authorization. | Required before any modification. Reading, validating, packaging, exporting, and obeying the file are default launch-baseline behavior. | Missing, unreadable, stale, contradictory, or any request to modify, weaken, delete, replace, or bypass the taboo without exact artifact-and-operation authorization. | taboo.uai |
.uai/talisman.uai | Universal launch-baseline anchors | Universal required guardrail file. Read and obey by default; modify only on explicit human artifact-and-operation order. | Default governance and change-control anchor. Agents must read and obey it before broad execution; package builders generate, validate, package, export, and index it for the selected package scope. | Receiving AI, human reviewer, package steward | When governance, no-op, talk-back, or anchor change-control instructions change, and only through explicit human artifact-and-operation authorization. | Required before any modification. Reading, validating, packaging, exporting, and obeying the file are default launch-baseline behavior. | Missing, unreadable, stale, contradictory, or any request to modify, weaken, delete, replace, or bypass the talisman without exact artifact-and-operation authorization. | talisman.uai |
.uai/persona.uai | Assistant and persona profile files | Required for non-project assistant packages, persona profile packages, advanced_persona_profile packages, bounded personality packages, and packages that support persona switching. | Carries the bounded source persona, voice, symbolic posture, interaction traits, continuity cues, and switching boundary for assistant/persona packages without mixing persona with project architecture. | Assistant runtime, desktop client importer, receiving AI, human reviewer | When persona traits, voice, symbolic posture, switching behavior, or user-facing relationship boundary changes. | Required before first use and before any persona, voice, relationship, or switching-boundary change. | Missing persona.uai in a declared persona/profile package, unbounded identity claims, hidden manipulation, unsupported capability claims, or conflict with Totem, Taboo, Talisman, privacy, or user consent. | persona.uai |
.uai/startup-packet.uai | Project Handoff startup files | Required for Project Handoff packages | Gives the receiving agent a bounded startup sequence, required read order, goals, budgets, and first safe actions. | Receiving AI starting a project handoff | Before each Project Handoff package is issued and after startup instructions change. | Required before handoff because it shapes the first operating pass. | Missing startup order, budget conflict, unsupported goal, or unsafe first action. | startup-packet.uai |
.uai/system-profile.uai | Project Handoff startup files | Required for Project Handoff packages | Summarizes platform, repository, runtime, package family, capability, and tool expectations for the receiving agent. | Receiving AI and implementation reviewer | When platform, runtime, tools, repository layout, or package family changes. | Required when it changes available capability, runtime assumption, deployment path, or tool boundary. | Runtime mismatch, missing tool boundary, unsupported capability, or stale platform description. | system-profile.uai |
.uai/receiver-brief.uai | Project Handoff startup files | Required for Project Handoff packages | Tells the next agent exactly what it is receiving, what is expected, what is blocked, and where to report back. | Receiving AI and handoff reviewer | At each handoff boundary and after blocker, owner, or deliverable changes. | Required before cross-agent or cross-session transfer. | Ambiguous receiver, stale blocker, unclear deliverable, or missing evidence route. | receiver-brief.uai |
.uai/context.uai | Active project memory files | Required for Project Handoff packages and project/developer packages | Holds accepted project context, definitions, domain facts, constraints already reviewed, and current operating assumptions. | Receiving AI and project reviewer | After reviewed facts change or new accepted context becomes necessary for future work. | Required for facts that affect public claims, ownership, architecture, security, legal posture, or user commitments. | Unreviewed context, stale domain fact, source conflict, or contradiction with world-context.uai. | context.uai |
.uai/constraints.uai | Active project memory files | Required for Project Handoff packages and project/developer packages | Records hard technical, legal, product, workflow, deployment, and editing constraints for the package scope. | Receiving AI, developer, reviewer | Whenever a constraint is added, retired, tightened, or replaced by a stronger local rule. | Required when a constraint changes safety, deployment, data handling, versioning, or public claims. | Constraint conflict, missing deployment rule, stale authority, or task requiring a forbidden action. | constraints.uai |
.uai/progress.uai | Active project memory files | Required for Project Handoff packages and project/developer packages | Tracks what has been completed, what remains, what was verified, and what changed since the last handoff. | Receiving AI and project reviewer | After each meaningful work segment, test pass, blocker resolution, or release preparation step. | Required when progress changes deployment readiness, release status, or handoff scope. | Progress conflict, unverified claimed completion, missing test evidence, or stale blocker status. | progress.uai |
.uai/operations.uai | Active project memory files | Required for Project Handoff packages and project/developer packages | Captures recurring operational commands, local services, deployment flows, maintenance paths, and environment checks. | Receiving AI and operator | When commands, ports, service names, local tooling, deployment flows, or maintenance routines change. | Required for production-affecting operations, credentials posture, deploy paths, or destructive maintenance rules. | Unknown command scope, stale service path, unsafe operation, or missing deployment checklist. | operations.uai |
.uai/test-plan.uai | Developer and release evidence files | Required for project/developer packages and release-bound packages | Defines validation commands, manual QA gates, coverage expectations, known blockers, and release-readiness checks. | Developer agent, reviewer, release owner | Whenever code, tests, packaging, deployment, public routes, or QA expectations change. | Required before release-bound handoff or production package build. | Missing validation path, stale test command, unreviewed failed check, or release without evidence. | test-plan.uai |
.uai/coding-standards.uai | Developer and release evidence files | Required for project/developer packages and packages that declare code, automation, executable workflow, or code-like artifacts | States coding style, architecture discipline, error-handling rules, testing expectations, and review quality bars for code-bearing work. | Developer agent and code reviewer | When architecture rules, language style, test policy, review standards, or code-bearing scope changes. | Required before code-bearing packages rely on it for review or implementation. | Missing code rules for code-bearing work, conflict with repository standards, or attempt to apply it to a no-code assistant package before code-like artifacts are declared or detected. | coding-standards.uai |
.uai/next-recursive-prompt.uai | Developer and release evidence files | Required for agents that deal with code, automation, executable workflows, or code-like artifacts: next-recursive-prompt.uai. | Carries the sectioned next-loop resume prompt for code-bearing agents without replacing authoritative .uai records or current human instruction. | Developer agent, automation agent, workflow agent, and reviewer | After meaningful work, test results, blockers, deployment, handoff, intake processing, or context compaction. | Required when the next-loop prompt changes release scope, authority, public claims, or deployment actions. | Missing, stale, invalid, contradictory, or evidence-broken next-recursive prompt in a required code-bearing scope. | next-recursive-prompt.uai |
.uai/decisions.uai | Active project memory files | Required for Project Handoff packages and Decision Memory packages | Records accepted decisions, their reasons, date, evidence, owner, and replacement path. | Receiving AI, reviewer, decision owner | When a durable decision is accepted, replaced, reversed, or proven stale. | Required for product, architecture, public claim, security, deployment, or governance decisions. | Contradictory decision, missing owner, missing evidence, or stale decision that still controls work. | decisions.uai |
.uai/memory.uai | Long-memory and transfer files | Required for AI Memory packages | Provides compact accepted memory that is broader than the current task and narrower than full archives. | Receiving AI and memory reviewer | After durable reviewed facts are promoted from work notes or archives into current AI Memory. | Required before promotion from raw notes, chat, generated summaries, or external records. | Unreviewed memory, stale fact, unsupported source, or memory conflict with current constraints. | memory.uai |
.uai/long-term-memory.uai | Long-memory and transfer files | Required for Long-Term Memory packages | Points to durable wiki, archive, graph, evidence, and preservation systems without treating all stored history as current truth. | Receiving AI, memory steward, archival reviewer | When durable memory systems, promotion rules, archive paths, or evidence stewardship changes. | Required for memory promotion, retention changes, and source-of-truth updates. | Unreviewed archive treated as current truth, missing steward, stale memory pointer, or unsupported source. | long-term-memory.uai |
.uai/file-handoff.uai | Long-memory and transfer files | Required for Agent File Handoff packages | Defines mandatory active-intake work authority, live scans, complete report processing, recommendation classifications, substantive-work and targeted-check evidence, configured durable-memory preservation, protected-anchor conflict handling, pointer completeness, source removal, and final empty-scan proof. | Receiving AI, intake reviewer, project owner | When intake buckets, archive rules, source trust, or disposition workflow changes. | Required for trust-boundary changes, evidence retirement, source movement, or intake-policy changes. | Unprocessed active file, missing full-read or recommendation evidence, summary-only report handling, missing substantive work or checks, missing hot/durable memory evidence, retained source copy, missing final scan, invalid protected anchor set, or uncited anchor conflict. | file-handoff.uai |
.uai/intake-outcome-ledger.uai | Evidence and audit files | Required for Agent File Handoff packages that declare intake outcome evidence | Preserves initial and final live scans, full-read proof, recommendation classifications, disposition, substantive work, targeted checks, hot and durable memory impact, complete pointer evidence, protected-anchor no-op/talk-back evidence, source removal, and final completion state for each intake file. | Intake reviewer, receiving AI, audit reviewer | Every time an active intake file is processed, retained active, archived, or retired. | Required when intake changes source behavior, durable memory, public claims, or release evidence. | Missing live scan, recommendation inventory, complete disposition, substantive work, targeted check, hot-memory update, durable preservation, pointer evidence, anchor citation, source removal, or final empty scan. | intake-outcome-ledger.uai |
.uai/overview.uai | Active project memory files | Required for project/developer packages | Gives a compact map of the project purpose, boundaries, active modules, public surface, and reader starting points. | Receiving AI and project reviewer | When scope, modules, public surface, or reader entry points change. | Required when it affects external understanding, project scope, or deployment path. | Scope conflict, stale module map, missing active surface, or mismatch with identity.uai. | overview.uai |
.uai/open-questions.uai | Active project memory files | Required for project/developer packages that carry unresolved decisions, risks, or owner questions | Collects unresolved questions with owner, impact, deadline, evidence needs, and current safe assumption. | Receiving AI, owner, reviewer | When a question is opened, answered, deferred, escalated, or converted into a decision. | Required before a major decision, release, or handoff depends on an unresolved assumption. | Blocking question without owner, unsafe assumption, stale unresolved item, or missing escalation path. | open-questions.uai |
.uai/next-actions.uai | Active project memory files | Required for project/developer packages | Lists ordered next actions with scope, owner, evidence path, acceptance condition, and blocker state. | Receiving AI and project owner | At handoff, after major work completion, and whenever priority or blocker state changes. | Required when actions affect deployment, release, user-facing behavior, or owner commitments. | Ambiguous next action, missing acceptance condition, contradictory priority, or blocker without escalation. | next-actions.uai |
.uai/risk-register.uai | Evidence and audit files | Required for project/developer packages that carry security, privacy, deployment, legal, product, or reliability risk | Records risks, severity, owner, mitigation, evidence, trigger, and current decision posture. | Reviewer, owner, receiving AI | When risk status, severity, mitigation, owner, or evidence changes. | Required for high-impact risks and before releases that alter risk posture. | Unowned risk, stale mitigation, unknown severity, or release with unresolved high-impact risk. | risk-register.uai |
.uai/owners.uai | Active project memory files | Required for project/developer packages with named owners, reviewers, or approval roles | Maps project owners, reviewers, stewards, escalation contacts, authority limits, and approval responsibilities. | Receiving AI, reviewer, project owner | When ownership, reviewer duty, approval path, or escalation authority changes. | Required for every authority or owner change. | Missing owner, unclear approval role, conflicting authority, or unreviewed handoff of responsibility. | owners.uai |
.uai/agent-instructions.uai | Active project memory files | Required for project/developer packages that declare agent-specific operating instructions | Gives role-specific agent instructions that do not belong in global identity, totem, taboo, or coding rules. | Receiving AI and instruction reviewer | When role-specific instructions, tool order, collaboration style, or escalation behavior changes. | Required for instructions that change authority, safety, public claims, deployment, or user-facing behavior. | Instruction conflict, hidden authority change, stale tool order, or contradiction with taboo.uai. | agent-instructions.uai |
.uai/archives/changelog.uai | Evidence and audit files | Required for project/developer packages and release-bound packages | Records dated package-memory changes, version-affecting edits, public-surface changes, and reviewer-relevant deltas. | Receiving AI, release reviewer, owner | Whenever package memory, release posture, public routes, generated exports, or significant source behavior changes. | Required before release-bound work relies on the changelog. | Unrecorded source change, missing date, version mismatch, or release evidence without matching change trail. | changelog.uai |
reports/deployment-memory-and-test-report.uai | Developer and release evidence files | Required for release-bound deployment packages and production package builds | Keeps build inputs, version authority, tests, checksums, deployment steps, blockers, and post-deploy verification together. | Release owner, receiving AI, deployment reviewer | During build preparation, package creation, deployment, and post-deploy verification. | Required before production deployment and after live verification. | Missing checklist, version mismatch, failed readiness check, stale checksum, or unverified live route. | deployment-memory-and-test-report.uai |
.uai/stack.uai | Developer and release evidence files | Required for project/developer packages that declare runtime, framework, hosting, or dependency stack | Documents runtime versions, frameworks, plugins, dependencies, hosting assumptions, service boundaries, and integration shape. | Developer agent, reviewer, operator | When runtimes, dependencies, hosting, plugins, frameworks, or integration boundaries change. | Required before dependency, hosting, or runtime changes drive implementation or deployment. | Unknown dependency, stale runtime, missing host boundary, or tool action against the wrong stack. | stack.uai |
.uai/architecture.uai | Developer and release evidence files | Required for project/developer packages that declare architecture, modules, integrations, or code-bearing work | Explains system boundaries, modules, data flow, integration seams, ownership, and architecture constraints for implementation work. | Developer agent, reviewer, architect | When modules, flows, APIs, data ownership, or architecture rules change. | Required before major structural changes, integration changes, or cross-module refactors. | Architecture conflict, missing owner, unclear boundary, or implementation that bypasses declared structure. | architecture.uai |
.uai/style.uai | Developer and publication evidence files | Required for project/developer packages that declare design, editorial, brand, or interface style | Documents visual, editorial, interaction, brand, and voice rules for work that changes published or user-facing surfaces. | Designer, writer, developer agent, reviewer | When visual system, editorial voice, brand rule, interface convention, or content style changes. | Required before public-facing design or editorial changes rely on it. | Style conflict, stale brand rule, unsupported public tone, or UI change that violates declared style. | style.uai |
Required-Set Decision Path
- Start with
.uai/memory-maintenance.uai. Every UAIX memory package MUST contain it; missing or invalid memory-maintenance makes the package non-compliant. - Add the universal launch-baseline set:
.uai/identity.uai,.uai/world-context.uai,.uai/totem.uai,.uai/taboo.uai,.uai/talisman.uai,.uai/startup-packet.uai, and.uai/progress.uai. - Treat
.uai/totem.uai,.uai/taboo.uai, and.uai/talisman.uaias default active instruction files: agents read and obey them, and no agent modifies, weakens, replaces, deletes, or bypasses any of those files without exact human artifact-and-operation authorization. - Declare the package profile: Agent File Handoff, Agent File Intake, Long-Term Memory, LLM Wiki, Project Handoff, no-code assistant, project/developer, release-bound, or another published profile.
- Add every file required for that declared profile, mode, package type, or capability.
- Add every content-triggered required file for declared or detected content such as code, automation, executable workflow, release evidence, owner authority, risk, or intake outcome evidence.
- Add every configuration-specific required file for selected package configurations.
- Keep every other file out of scope for that package. Out-of-scope files are not advertised as present and are not relied on by validator output.
Required Read Order
- Read
AGENTS.mdor.uai/readme.humanwhen present as the package entry record. - Read
.uai/startup-packet.uaias the active.uai/read-order index. - Read every active
.uai/*.uaifile named by that read order; do not substitute a single catch-all active memory file. - Read and obey
.uai/totem.uai,.uai/taboo.uai, and.uai/talisman.uai. Do not modify, weaken, replace, delete, or bypass any active instruction file unless a human names the exact artifact and exact operation. - For Project Handoff packages, read
.uai/system-profile.uaiand.uai/receiver-brief.uai. - For packages that declare machine exports, read
.uai/exports/manifest.jsonandllms.txt. - Read every profile-required and content-triggered required file for the declared package scope.
- Read long-memory pointers only after compact current memory and boundaries are clear.
Long-Running Goal Execution
For long-running goal execution, .uai/startup-packet.uai, .uai/progress.uai, .uai/next-actions.uai, .uai/decisions.uai, .uai/constraints.uai, and .uai/test-plan.uai form the checkpoint set. .uai/next-recursive-prompt.uai is derived hot memory for code-bearing scopes and should be regenerated only after authoritative write-back.
Cross-References
- AI Memory
- AI Memory Package Wizard
- Project Handoff
- Long-Running Goal Execution
- Agent File Handoff
- AGENTS.md Specification
- UAI-1 Specification
- Validator
- Governance
- Roadmap
Machine-Readable Digest
Agents should treat this digest as page-orientation evidence, not runtime authority.