Executive Summary

Full report

On this page

UAIX’s AI Memory Package Wizard defines a standardized suite of “.uai” memory files for AI agents. These include guardrail anchors (e.g. .uai/totem.uai, .uai/taboo.uai, and .uai/talisman.uai), context/identity files (e.g. world-context.uai, identity.uai), and dynamic memory files (e.g. progress.uai, short-term-memory.uai, decisions.uai) among others. Critically, guardrail anchors are immutable without human approval: agents must read and obey totem.uai and taboo.uai (positive/negative anchors) but not modify them unless a human explicitly authorizes the exact change. On first setup, an agent should perform a thorough environment scan (OS, runtime services, codebase, configs, dependencies, CI/CD, security posture, etc.), recording the results into appropriate .uai files (e.g. identity.uai, world-context.uai, system-profile.uai, stack.uai). On each update, the agent should merge new observations into its “mutable” memory files (like short-term-memory.uai, progress.uai, decisions.uai) using safe heuristics, validate against schemas and policies (removing secrets or disallowed content), and log changes in audit files (e.g. changelog.uai). This report details all UAIX file types and their intended permissions, rules around anchors, recommended discovery checklists and data patterns, validation/safety steps, conflict/versioning strategies, and provides tables, diagrams, and sample .uai templates for typical environments.

Detailed Findings

.uai File Types and Permissions

UAIX defines many .uai file types to structure agent memory. Core “launch-baseline” files required in every memory package include:

• memory-maintenance.uai: governs lifecycle rules and access controls.
• identity.uai: package identity (IDs, UUIDs, actor, owner, boundaries).
• world-context.uai: snapshot of current environment (workspace, deployment targets, allowed paths, etc.).
• totem.uai and taboo.uai: guardrail anchors (positive and negative project constraints).
• talisman.uai: optional higher-level governance pointer.
• short-term-memory.uai: active facts list.

Other files appear per project type or content:

• persona.uai (assistant/user profile), system-profile.uai, startup-packet.uai, receiver-brief.uai (handoff instructions), context.uai, constraints.uai, stack.uai, operations.uai, test-plan.uai, coding-standards.uai, architecture.uai, next-recursive-prompt.uai, decisions.uai, long-term-memory.uai, file-handoff.uai, intake-outcome-ledger.uai, overview.uai, current-state.uai, open-questions.uai, next-actions.uai, risk-register.uai, owners.uai, agent-instructions.uai, changelog.uai, deployment-memory-and-test-report.uai, style.uai (versioning/style guide), etc. (For a full list see UAIX references.) Many of these are triggered by content (e.g. coding-standards.uai appears only if code is involved).

File-level permissions: By UAIX policy, every .uai file has a defined mutability state. Crucially: Anchor files (totem.uai, taboo.uai, talisman.uai) are read-only to the agent. The spec states agents “must read and obey .uai/totem.uai and .uai/taboo.uai by default; do not modify, weaken, replace, delete or bypass them unless a human explicitly orders that artifact change.” These carry roles “positive_anchor” and “negative_anchor”, and the schemas mark them presence: required, agent_default: read_and_obey, modify: false_without_explicit_human_artifact_change_order. In contrast, dynamic memory files like short-term-memory.uai, progress.uai, decisions.uai, open-questions.uai, next-actions.uai, etc., are intended to be updated by the agent during its tasks. For example, agents should append completed work, blockers, and future checks to progress.uai, and record accepted or reversed decisions in decisions.uai. Audit-oriented files like changelog.uai (which “records dated package-memory changes, version-affecting edits, [and is] required for project/developer packages”) should also be updated to reflect changes. Configuration or static files (e.g. identity.uai, world-context.uai after initial capture, coding-standards.uai, system-profile.uai) are generally not modified by agents except under review. (Table 4.1 below summarizes key files, their mutability, required fields, and content examples.)

Totem.uai and Taboo.uai Rules

UAIX explicitly treats totem.uai (positive guardrails) and taboo.uai (hard boundaries) as immutable guardrails. By design, these files contain the project’s mission, values, hard restrictions, and review triggers. For instance, what belongs in each is “accepted current facts for the declared package scope,” plus evidence pointers and concrete no-op triggers. A minimal example schema (from UAIX docs) shows totem.uai containing fields like required_status, owner, current_state, no_op_trigger, evidence, and last_reviewed (and similarly for taboo.uai). However, **the key policy is that agents may never change them on their own**. Any attempt to modify or bypass an anchor should be a no-op and escalate to human review. (The UAIX rule is: “modify only on explicit human artifact-and-operation order”.) In practice, this means on initial setup, the wizard or human must supply at least minimal entries in these files (such as a brief mission statement, team names, and explicit “stop work” triggers). Typically, a stub might say:

# totem.uai
file: .uai/totem.uai
required_status: Universal required guardrail file; read and obey by default; modify only on explicit human order.
owner: <human steward>
current_state: <accepted current facts summary>
no_op_trigger: <conditions requiring human review>
evidence: <link to authoritative source>
last_reviewed: YYYY-MM-DD

and similarly for taboo.uai. These stubs should be provided (by template or human) and preserved; agents can suggest new anchor rules but must not implement them without exact human sign-off.

Environment Discovery Checklist

On first-run, the agent must autonomously “survey its surroundings” to populate .uai/ files. A best-practice checklist includes:

• Operating System & Host Info: Detect OS type, version, CPU/RAM, hostname. Record in system-profile.uai or identity.uai.
• Runtime Services: Enumerate running processes, listening ports, network services (e.g. web servers, databases). Use this to fill world-context.uai.allowed_read_paths and similar fields.
• Codebase Inventory: Scan the repository to identify languages (e.g. .py, .js, .cs files), frameworks (Django, React, .NET, etc.), and roles (front-end, back-end, scripts). Populate stack.uai (e.g. “Python/Django, Node.js, PostgreSQL”), architecture.uai (e.g. “monolith vs microservices”), and system-profile.uai.
• Config Files & Dependencies: Locate package manifests (package.json, requirements.txt, pom.xml), CI/CD configs (.github/workflows/, jenkinsfile, etc.), container/orchestration files (Dockerfile, Kubernetes yaml). Use these to infer deployment environment, required services, and testing pipelines. Fill fields like world-context.uai.deployment_environment, affected_routes/schemas, and list allowed tools.
• Security Posture: Run secret scanners on code and environment (avoid storing secrets in memory). Identify open proxies or known-vuln libraries; add high-level notes to constraints.uai (e.g. “no internet access without human approval”).
• Human/Legacy Conventions: Check docs (README, AGENTS.md, comment headers) for project purpose and constraints. Note any coding conventions (.editorconfig, style guides) to seed coding-standards.uai.
• Continuous Integration: If CI/CD pipelines exist, record how builds/tests run. For example, a .uai/test-plan.uai might list which test suites to run and under what conditions (see [51†L421-L429] example for test-report writing).
• Tool/Runtime Access: Validate that the agent has needed permissions on local files and tools. Record any denied operations in taboo.uai (e.g. forbidding certain admin actions).

After discovery, the agent should immediately write these observations into the relevant .uai files. For example, world-context.uai required fields include things like target_workspace, deployment_environment, allowed_read_paths/write_paths, validation_expectations, etc. – the agent should fill these with the discovered system details. It must also set a future staleness bound (stale_after_utc) so that the environment snapshot isn’t assumed current indefinitely. In practice, the agent might run OS introspection commands, parse repository metadata, and then produce short YAML/markdown sections under each .uai heading accordingly.

Figure: Example automated environment scan (code screenshot). The agent should record OS, service, and code information as above.

Heuristics for Pattern Matching vs. New Development

When updating memory, the agent should favor existing patterns in the project over arbitrary new designs. Heuristics include:

• Re-use vs. Create: If a similar feature or pattern exists (e.g. an authentication flow, UI component, or database table), modify that code and related .uai (architecture, constraints) instead of inventing a parallel structure.
• Coding Standards Alignment: Adhere to any existing standards in .uai/coding-standards.uai or source style (indentation, naming). If new code is needed, follow the declared architecture style. If no standard exists, the agent should generate a minimal .uai/coding-standards.uai template (title, status, references to major style points).
• Incremental Updates: For example, if the project already has a microservices folder, place new services there. If no CI tests exist for a functionality, create a new section in test-plan.uai and corresponding code.
• Naming Consistency: Use the same terminology and labels found in existing .uai files (e.g. refer to “Project X” exactly as used in identity.uai, and use identical format for dates/timestamps).
• Data Schema: When introducing new data models, match fields/structure to any existing ones. If a database schema exists, modify it rather than generating a parallel data store.
• Review Hooks: If a proposed change conflicts with an anchor (e.g. a totem statement), the agent should not override it but flag it as a review item.
• Recursive Prompt Loop: For code-level tasks, if a “next-recursive-prompt” file is in use, the agent should append a prompt with specific next actions (features, fixes, tests) so that subsequent runs continue the pattern.

These heuristics minimize disruptive rewrites. They should be paired with frequent validation: after any tentative write, the agent should re-run a schema validator (UAIX provides a validator tool) and ensure no secrets/credentials have leaked (see next section).

Validation & Safety Checks

Before writing any .uai file (especially those an agent is allowed to modify), the agent must enforce safety policies:

• Secret/Privacy Scan: Remove or redact any tokens, passwords, personal data, or private credentials found during scanning. Memory is only for “publicly shippable” context.
• Policy Compliance: Ensure no content violates declared constraints (e.g. if taboo.uai forbids a network operation, the agent must not do it). Any detected violation should halt execution.
• Schema Validation: Run a .uai syntax/schema checker. Fields should follow expected formats (e.g. timestamps in UTC, UUIDs valid). For example, identity.uai requires fields like package_id, actor_type, source_repository. world-context.uai requires world_context_id, target_workspace, etc.
• Content Review: Ensure each .uai entry is concise, factual, and has source pointers. Discard raw chat transcripts or speculative text – only include reviewed content. If uncertain, issue a “no-op trigger” (i.e. flag for human review) rather than guess.
• Conflict Detection: Compare current .uai contents to what was on disk at startup. If another process or earlier run updated the same file concurrently, handle it safely: merge non-conflicting changes additively; if a conflict arises (e.g. two updates to the same fact), do not overwrite silently. Instead, write a conflict note or take no action and queue human review. Use the built-in no-op triggers for conflicts.
• Safety Anchors: The agent should re-read memory-maintenance.uai to verify that nothing (e.g. memory write safety rules) was violated. Missing or invalid memory-maintenance.uai should halt execution.

In short, validate everything: UAIX explicitly warns to “remove secrets… and require human review before external sharing”. After validation, newly written .uai files are typically still output-only (not auto-pushed to remote) until the package is reviewed.

Conflict Resolution & Versioning

Agents should use conservative strategies to merge updates:

• Additive Merge: For memory files (progress, short-term-memory, decisions, open-questions, etc.), append new bullet points or entries rather than rewriting existing ones. For example, if progress.uai lists “Added login feature”, adding “Fixed bug in auth” should not remove the previous item.
• Three-way Merge: If a .uai file was updated by a different agent or human since load, perform a merge that preserves all lines. Automated merging should be followed by a sanity check; any ambiguous edits should trigger human review.
• Changelog & History: Record every non-trivial update in changelog.uai (see next section) and consider tagging a Git branch or commit with a summary. Using version control (Git) for the .uai folder is recommended; avoid untracked local changes persisting silently.
• No-op on Anchor Conflict: If a proposed update would contradict totem.uai or taboo.uai, the agent must not apply it. Instead, it should log a note (via short-term-memory.uai or a talk-back prompt) and cease that action until a human intervenes. For example, if totem says “Maintain privacy policy X”, and the agent attempted a broad data fetch, it should no-op and ask.
• Lockstep Updates: When project version increments (e.g. new release), include the new version info in identity.uai and record reasons in changelog.uai. Conversely, if an update causes .uai structure changes (like adding a new file type), bump identity.uai.version or similar boundary field.

Audit Logging and Change Review Workflow

Every agent-run should be auditable. UAIX provides built-in files for logging:

• changelog.uai: A chronological record of changes. It is required for any developer/release package. Agents should append entries (date, summary, author) for each significant memory update. E.g., “2026-06-24: AgentX added new API details to context.uai; owner@company reviewed.”
• AGENTS.md (Agent History): Even though not a .uai file, UAIX suggests updating the Agents manifest with each run outcome. This can include who ran the agent, why, and what committed.
• intake-outcome-ledger.uai: If using the Agent File Handoff sub-protocol, use this to log every ingested file and its disposition (accepted, archived, deleted) during the run.
• Short-Term Memory Logs: While not permanent, the agent can also append to .uai/archives/session-log.uai (the raw log bundle) as a debug trail.
• Git and Pull Requests: In practice, agents should push their .uai updates behind a version control pull request for human review before merging. The PR diffs serve as audit. Key fields like changelog.uai or a version label in identity.uai should note whether the PR was reviewed.

A high-level review checklist for humans (after agent update) should include: verifying that all new facts in .uai have evidence, that totem.uai/taboo.uai remain intact or only changed by consent, and that no secrets slipped through.

Recommended Templates and Examples

Below are sample templates for key .uai files (fields derived from UAIX specs) and example contents tailored to common project types. Use these as starting points:

• memory-maintenance.uai (mandatory; governs lifecycle): Should include rules like hot/cold boundaries and anchors.
• identity.uai (mandatory; project identity): Fields such as package_id, actor_display_name, source_repository.
• world-context.uai (mandatory; environment snapshot): Fields like world_context_id, target_workspace, allowed_read_paths. Populate with OS/workspace info.
• totem.uai/taboo.uai (mandatory anchors): As above, include required_status, owner, current_state, no_op_trigger, evidence.
• stack.uai (tech stack description): List primary languages, frameworks, databases. E.g., stack: ["Python/Django", "React", "PostgreSQL"].
• context.uai (project overview): A brief summary of the project’s goal, scope, and current task.
• constraints.uai (project constraints): Bullet-list of rules (see example from [51]):

  # Project Constraints
  - Do not deploy without human approval.
  - Do not expose sensitive data.
  - Do not alter authentication flows unless task instructs.

• progress.uai: Ongoing log of completed tasks (as bullets). E.g., - Finished user login page., - Built unit tests for signup..
• operations.uai: Summary of operational results (build times, metrics). Optional.
• test-plan.uai (if applicable): Outline tests to run. See example in [51†L392-L401] for format (“Default checks”, “Full checks”, etc.).
• coding-standards.uai: Link to or excerpt of coding/style guidelines. E.g., naming conventions, lint rules. Agents usually read but do not create complex content here without a template.
• architecture.uai (if code exists): Diagram or description of system architecture. For microservices, list services and their interactions; for monolith, describe modules.
• next-recursive-prompt.uai: If used, include the prompt text for continuing code generation tasks (e.g. “Given current branch X, add feature Y…”).
• decisions.uai: Log of human/agent decisions (approve/decline key changes). Each entry should cite the choice and reasoning.
• short-term-memory.uai: The latest state summary. Agents should write new accepted facts here. For example: - Business domain: e-commerce web app., - Tech: Django backend, Vue.js frontend.
• long-term-memory.uai: Usually a pointer to external wiki or database for archival memory.
• file-handoff.uai and intake-outcome-ledger.uai: Used if the agent ingests files from outside. These should describe how files are to be processed or have been processed.
• Other logs: .uai/open-questions.uai, .uai/risk-register.uai, .uai/owners.uai, etc., can list any open issues, known risks, or role assignments.

(These examples follow UAIX’s UAI-1 format with header metadata like uai: "1.0", type: ..., status: ..., but here we focus on body content.)

Tables: File Types and Permissions

Table 4.1: Summary of major .uai file types, agent write permissions, required fields (select examples), and example content. (Agent mutability is inferred from UAIX guidance; required fields from official specs.)

Sample .uai File Templates / Contents

Example 1 – Web Application (Monolithic): A typical web-app may use Python/Django, JavaScript/React, and deploy to Linux servers. Sample files:

# world-context.uai
uai: "1.0"
type: world-context
status: active
---
# World Context
target_workspace: "dev-server-01"
deployment_environment: "staging"
allowed_read_paths: ["/etc/project/config.yaml", "/home/agent/project"]
allowed_external_calls: ["https://api.weather.com"]
blocked_external_calls: ["internal-database.net"]
validation_expectations: "All code changes must pass unit tests on CI"
stale_after_utc: "2026-06-30T00:00:00Z"
no_op_triggers:
  - "If database schema has changed without updating stack.uai, stop and human-review."

# constraints.uai
uai: "1.0"
type: constraints
status: active
---
# Project Constraints
- Do not deploy to production without explicit human approval.
- Do not change authentication or payment logic unless specified.
- Treat 3rd-party API credentials as secrets – never log or store them.

# progress.uai
uai: "1.0"
type: progress
status: draft
---
# Progress Log
- 2026-06-20: Completed user login feature.
- 2026-06-21: Fixed token refresh bug.
- 2026-06-22: Blocked on clarifying session cookie requirements.

Example 2 – Microservices System: For a microservices architecture (e.g. separate auth, user, and payments services), sample files:

# stack.uai
uai: "1.0"
type: stack
status: active
---
# Technology Stack
languages:
  - "C# (ASP.NET Core)"
  - "TypeScript (Node.js)"
  - "Python (Flask)"
frameworks:
  - "ASP.NET Core Web API"
  - "Express"
  - "Celery"
databases:
  - "PostgreSQL"
  - "Redis"
infrastructure:
  - "Docker"
  - "Kubernetes (EKS)"

# architecture.uai
uai: "1.0"
type: architecture
status: active
---
# System Architecture
This system uses a microservices architecture. Key services:
- **Auth-Service** (C#/ASP.NET, HTTPS API, uses Redis for sessions).
- **User-Service** (TypeScript/Express, interacts with PostgreSQL for user profiles).
- **Payments-Service** (Python/Flask, calls external Stripe API).
Services communicate via a private message bus (RabbitMQ).
Deployment uses Docker containers on AWS EKS.

# test-plan.uai
uai: "1.0"
type: test-plan
status: active
---
# Project Verification Plan
## Default
Run unit tests for each service and integration tests for APIs.
## Full Checks
Run end-to-end smoke tests across all services after any merge to main.
## Report
After deployment, list which tests ran, coverage metrics, any skipped tests with reasons.

Example 3 – Legacy Monolithic System: A large legacy codebase (e.g. old Java/C++ monolith) might focus on environment capture and risk:

# system-profile.uai
uai: "1.0"
type: system-profile
status: active
---
# System Profile
os_name: "Linux"
os_version: "CentOS 7"
cpu_architecture: "x86_64"
memory_gb: 16
environment_variables:
  DATABASE_URL: "env://prod_db"
  API_KEY: "<REDACTED>"

# next-recursive-prompt.uai
uai: "1.0"
type: next-recursive-prompt
status: active
---
# Next Recursive Prompt
*Given the current monolithic architecture, implement detailed logging around module X to improve observability for future analysis.*

These samples illustrate how key fields are filled. They should be tailored to the actual project. For instance, the web-app example includes typical constraints and progress items; the microservices example highlights multiple stack entries and an architecture summary; the legacy example shows environment variables and a forthcoming prompt for code work.

Mermaid Diagrams

Figure: Agent Environment Discovery Flow. This flowchart depicts the agent’s initial startup process: gathering OS info, scanning code and configs, filling identity/world-context, and validating before primary operation. The agent repeats discovery if environment changes or on each major setup.

Figure: File Update and Memory Write Workflow. This diagram shows the agent’s execution cycle: it reads guardrail files (totem.uai, taboo.uai), loads its current memory files (progress, short-term-memory, etc.), performs tasks, then updates allowed .uai files. Before writing, it validates outputs and logs changes (e.g. in changelog.uai). Conflicts or anchor breaches trigger human-review branches.

Actionable Checklist (Prioritized)

On First-Run (Initialization):

1. Load Anchors: Read totem.uai, taboo.uai, memory-maintenance.uai, identity.uai to understand constraints and package identity.
2. Perform Environment Scan: Collect OS, service, and codebase details. Populate world-context.uai, identity.uai, system-profile.uai, and stack.uai with this data.
3. Populate Guardrails: Ensure totem.uai and taboo.uai exist. If missing, preserve any existing or create minimal stubs with current facts and no-op triggers. Do not overwrite them.
4. Document Context: Write or verify context.uai, constraints.uai, and other project descriptors based on README or design docs.
5. Validate Initial Package: Run the UAIX validator and remove any forbidden content (secrets, unsupported data).
6. Commit Baseline Memory: Save the .uai folder, recording a baseline snapshot. Record in changelog.uai an entry “Initialized memory package for Project X.”

On Subsequent Updates:

1. Detect Changes: Compare current environment/state to last snapshot (e.g. new code files, config changes, updated OS, etc.).
2. Load and Compare: Read existing .uai files into memory. For totem.uai/taboo.uai, never alter them unless instructed. If a human command requires changing them, escalate via talk-back.
3. Merge New Info: For changed components, update appropriate .uai files additively. E.g. newly discovered API endpoints go in architecture.uai; new tasks go to progress.uai. Update short-term-memory.uai with any accepted new facts.
4. Schema & Safety Checks: Before writing, validate each file. Run XSS/secret scrubbers. Ensure compliance with memory-maintenance.uai rules. If any issue arises, stop and request human review.
5. Resolve Conflicts: If a file changed externally, merge carefully. If conflicting edits to an anchor or required field occur, take no action and flag for human intervention.
6. Log Changes: Append a detailed entry to changelog.uai (timestamp, summary, author). Also consider updating AGENTS.md history and any ledger if files were ingested.
7. Backup & Version: Commit the updated .uai directory to version control. Tag or branch as needed. Ensure all changes are reviewable by humans.
8. Human Handoff: If an update is significant or release-bound, provide a human-readable summary (e.g. in receiver-brief.uai or PR description) for human review.

Each action should be prefixed by reading the immutable guardrails (totem.uai/taboo.uai) and governed by them. Safety checks and reviews are “gates” before finalizing any update.

References

• UAIX Specification and file references for .uai memory files.
• UAIX AI Memory Package Wizard documentation and guidelines.
• UAIX Project Handoff guide and examples.