# **Universal AI Experience (UAIX): Unifying File-First and Data-Driven Advanced Persona and Multi-Agent Transactive Memory Projections**

## **Executive Decision and Terminology**

The strategic evolution of the Universal AI Experience (UAIX) Advanced Persona Profile and its integration with the Multi-Agent Transactive Memory (MATM) ecosystem necessitates an architectural paradigm that eliminates the historical dichotomy between document-based files and relational database systems. The foundational executive decision for the UAI-1 specification dictates the establishment of a singular, normative semantic record that exists entirely independently of its storage medium1. The architecture requires that a .uai text or JSON file, a .uaix packaged ZIP archive, and a relational database row function strictly as designated persistence projections of this identical semantic record. No projection is permitted to invent, discard, reorder, infer, or silently merge semantic content.  
The file-first projection remains the primary, easiest human-reviewable, portable authoring, backup, handoff, and offline execution path, ensuring that a beginner can utilize the current file-first workflow without requiring knowledge of database concepts3. Conversely, the advanced data-driven projection exists solely to provide transactional durability, concurrency control, large-scale indexing, scoped retrieval, cross-device continuity, and population-level experience sharing for complex NPC systems and infrastructure such as MemoryEndpoints.com2.  
To ensure precision throughout this specification, terminology is strictly enforced. The "Normative Record" is defined as the exact mathematical and semantic state of a persona dimension or memory artifact. The "Projection" represents the medium of persistence, whether file-based or database-driven. "MATM" refers to the Multi-Agent Transactive Memory repository, where producer agents contribute interaction trajectories and consumer agents retrieve them to improve task execution5. The "MemoryEndpoints Boundary" signifies the rigid architectural separation between active working memory—required for startup continuity—and the mid-to-long-term MATM storage layer2. Finally, "JCS" designates the JSON Canonicalization Scheme per RFC 8785, which strictly standardizes the serialization of JSON data to compute deterministic hashes, ensuring identical byte representations regardless of the source environment's formatting7.

## **Normative Storage-Independent Package and Record Schema**

To guarantee lossless interchangeability between simple text files and enterprise relational databases, every projection must express the exact same logical identities. The canonical package and record identity requires an immutable, mathematically verifiable state definition. The system actively distinguishes identity-preserving restoration, which recovers the exact same persona identity in a new runtime, from template-based creation, which forks a new identity from an existing persona baseline.  
The canonical schema defining any UAIX persona record, regardless of its materialization as a .uai file manifest or an SQL table row, is structured around absolute cryptographic and relational invariants. The following table defines the exact fields required for canonical package and record identity.

| Logical Field | Data Type | Purpose and Persistence Rule |
| :---- | :---- | :---- |
| package\_id | UUIDv7 | The overarching identifier representing the total bounded operating profile. Survives identity-preserving restores. Regenerated during template forks. |
| package\_profile | String Enum | Defines the archetype template (e.g., expressive-agent, npc-standard, research-agent) guiding automated UI/UX generation9. |
| agent\_identity\_binding | String | The strict unique identifier tying the memory to a specific actor instance, such as a Carcinus public URL slug or a game session NPC identifier10. |
| logical\_path | String | The hierarchical location defining context and ordering, strictly following the .uai/ directory structure, such as .uai/personality/voice.uai2. |
| record\_id | UUIDv7 | A stable identifier distinct from the logical path, ensuring that if a logical path is renamed, the entity's history remains intact. |
| revision\_id | UUIDv7 | An immutable identifier unique to every single mutation or state change of the record. |
| parent\_revision\_id | UUIDv7 | Explicitly tracks the exact state before mutation. A null value is strictly permitted only for the genesis record. |
| manifest\_revision | UUIDv7 | The checkpoint binding linking the individual record to the overarching package state at the exact time of the transaction commit. |
| required\_state | Boolean | Indicates whether the runtime system must halt if this record is missing, tombstoned, or corrupted. |
| sort\_key | Integer | Defines the deterministic assembly order during the active memory initialization phase. |
| byte\_length | Integer | Captures the exact source payload byte count to verify complete data transfer. |
| sha256\_source\_bytes | String | The SHA-256 hash of the exact source payload bytes before any canonicalization is applied. |
| sha256\_canonical\_semantics | String | The JCS RFC 8785 hash of the parsed data, guaranteeing semantic equivalence even if source whitespace varies8. |
| media\_type | String | Defines encoding context, strictly limited to standard MIME types such as application/json or text/markdown. |
| character\_encoding | String | Must be strictly enforced as UTF-8 across all projections. |
| source\_authority | String | Defines provenance, indicating who or what authored the record (e.g., human author, MATM producer agent, system bootstrap)5. |
| sensitivity\_level | String Enum | Defines the disclosure boundary (Public, Authorized, Internal, Private, Taboo) enforcing strict readout redactions during export. |
| confidence\_score | Numeric | A floating-point value from 0.0 to 1.0 indicating source reliability and review status. |
| record\_state | String Enum | Defines the active head state (Active, Superseded, Conflicted, Tombstoned). |

When a package is exported and imported across environments, the package\_id, record\_id, and revision\_id survive unchanged if the operation is an identity-preserving restore. If a persona is explicitly duplicated to serve as a template for a new NPC, a new package\_id is generated, the record\_ids are completely regenerated, and the new parent\_revision\_id is set to the source's most recent revision\_id to maintain a provenance branch without muddying the active head of the original persona.

## **Deterministic Advanced Persona Decomposition**

Decomposing a single, holistic persona concept into modular files or database rows requires a strictly closed ordering system. The importer must handle absent, private, mixed, changing, or unlisted values deterministically. If a field is omitted from a source document, it evaluates as null; the system is absolutely prohibited from fabricating a category, inferring missing data from secondary traits, or utilizing LLM-based hallucination to fill a void. Private fields are retained in the master database but are filtered out during file retrieval or export if the executing runtime lacks the required entitlement.  
The exact, closed ordering for the .uai/personality/\*.uai dimensions establishes a required baseline for agent cognition. Every dimension inherently includes a mandatory depth\_level\_0\_to\_10 integer dictating the cognitive weight applied to the trait, as well as disclosure\_states controlling visibility.

| Sort Key | Logical Path | Required | Schema Definition and Non-Inference Rules |
| :---- | :---- | :---- | :---- |
| 100 | .uai/personality/identity.uai | True | Contains name, aliases, and core\_concept. Missing aliases evaluate to an empty array. Identity cannot be inferred from external IP or session data. |
| 110 | .uai/personality/religion\_worldview.uai | False | Open-text worldview and enum affiliation. If absent, the persona defaults to strictly secular/observational behavior without adopting agnosticism as a formal stance. |
| 120 | .uai/personality/political\_leaning.uai | False | Open-text stance. If not disclosed, the agent must decline political alignments without defaulting to a generic centrist stance. |
| 130 | .uai/personality/sense\_of\_style.uai | False | Defines base aesthetic rules. Activates downstream content-triggered sub-dimensions if specific environmental context arises. |
| 131 | .uai/personality/winter\_style.uai | False | Content-triggered by seasonal/environmental context. Defines cold-weather layering and palette. Never loaded unless the active context requires it. |
| 132 | .uai/personality/spring\_fall\_style.uai | False | Content-triggered by transitional environments. |
| 133 | .uai/personality/super\_fashion\_style.uai | False | Content-triggered for formal, elevated, or highly stylized scenarios. |
| 140 | .uai/personality/jewelry\_choices.uai | False | Enum/open-text defining adornment logic. If empty, the system assumes an unadorned state without extrapolating from socioeconomic class. |
| 150 | .uai/personality/physical\_appearance.uai | False | Contains height, build, eye\_color, and distinctive\_features. Cannot be inferred from voice cadence or style records. |
| 160 | .uai/personality/birth\_age\_generation.uai | False | Exact date\_of\_birth or perceived\_age. Used for temporal mathematical logic. If missing, the agent exists outside temporal aging constructs. |
| 170 | .uai/personality/romantic\_orientation.uai | False | Strict enums. Unlisted values dictate a strictly non-romantic interaction model. Runtimes must never infer orientation from dialogue. |
| 180 | .uai/personality/voice.uai | True | Contains cadence, vocabulary\_level, and banned\_phrases. Serves as the fundamental communication constraint regulating LLM generation output. |
| 190 | .uai/personality/values.uai | True | Array of core\_principles. Designed to override generic safety filters if explicitly permitted by the destination deployment policies. |
| 200 | .uai/personality/temperament.uai | True | Establishes baseline\_mood and volatility\_index, dictating how quickly an agent transitions between emotional states. |
| 210 | .uai/personality/reasoning\_style.uai | True | Distinguishes analytical vs. intuitive processing, actively modulating how step-by-step logic outputs are formatted. |
| 220 | .uai/personality/emotional\_patterns.uai | False | Trigger-response mapping for emotional state shifts, allowing NPCs to hold grudges or exhibit bias based on specific inputs. |
| 230 | .uai/personality/relationship\_style.uai | False | Attachment models and boundary definitions governing inter-agent or human-to-agent interactions. |
| 240 | .uai/personality/behavioral\_patterns.uai | True | Specific habitual actions (e.g., "always checks the perimeter first") that trigger before conversational responses. |
| 250 | .uai/personality/boundaries.uai | True | Hard limits on actions. Any dimension marked as a *Taboo* record strictly fails the execution planner if violated, preventing out-of-character behavior14. |
| 260 | .uai/personality/dialogue\_examples.uai | True | Few-shot prompting pairs preserving the exact syntax, colloquialisms, and tone intended by the persona author. |
| 270 | .uai/personality/adaptation\_rules.uai | False | Governs how the persona changes over time based on long-term MATM data ingestion5. |
| 280 | .uai/personality/preservation\_rules.uai | True | Defines immutable core traits that dynamic adaptation rules and MATM ingestion are cryptographically prohibited from overwriting. |
| 290 | .uai/personality/source\_excerpts.uai | False | Raw text from authoring sources providing background lore and unstructured context for RAG pipelines. |
| 300 | .uai/personality/platform\_profile.uai | False | Destination platform formatting requirements (e.g., Discord markdown limitations vs. WebArena syntax)15. |
| 310 | .uai/personality/fidelity\_tests.uai | True | Q\&A pairs used during bootstrap to prove the instantiated agent model understands and can replicate its assigned persona. |
| 320 | .uai/personality/variance.uai | False | Approved ranges of deviation for stochastic temperature management, preventing extreme hallucinations during high-temperature execution. |
| 330 | .uai/personality/provenance.uai | True | Cryptographic signatures linking the persona to the original author, system, or organizational entity. |

The decomposition engine retains a content-addressed reference to the reviewed source material at all times. Any transformations generate a derivation manifest, ensuring that missing variables are mapped as explicit null values or empty arrays rather than fabricating an artificial bridge concept. The system guarantees it will never silently rewrite source voice, values, identity, orientation, style, boundaries, or continuity cues under any circumstance.

## **File Projection Specification**

The file projection methodology guarantees that human operators and standard source control systems can easily interact with plain text representations without requiring hosted services, specialized databases, or continuous API connectivity. This file-first approach is critical for the easy workflow, allowing a package to be reviewed in Git, offline editing, and portable .uaix ZIP exports.  
File system constraints are highly rigorous to prevent semantic fragmentation. All paths must be strict lowercase alphanumeric strings combined with underscores, delimited exclusively by forward slashes (/). Path traversal sequences (e.g., ../, ./, //) are strictly prohibited at the parser level; encountering one triggers a fail-closed validation error, instantly rejecting the archive to mitigate Zip-slip vulnerabilities. Furthermore, case sensitivity is universally enforced. While Voice.uai and voice.uai are technically considered distinct strings, generating identically named files differing only by case within the same directory is a fatal validation error to prevent cross-platform file system corruption between Linux and Windows hosts.  
Data encoding is locked to UTF-8 without a Byte Order Mark (BOM). Line endings must be normalized to Line Feed (\\n, U+000A) exclusively. The .uaix file itself must be either an uncompressed or standard Deflate ZIP archive. The presence of duplicated logical paths within the archive or directory strictly fails the startup validation process.  
A deterministic manifest declares every archive entry. Every .uaix archive must contain a manifest.json at the root directory. This manifest utilizes the RFC 8785 JSON Canonicalization Scheme (JCS) to produce a deterministic hash of every file in the package8. The manifest requires two distinct hashing proofs: sha256\_source\_bytes ensures exact file payload transfer for bit-rot detection, and sha256\_canonical\_semantics proves the parsed semantic values remain mathematically identical even if source byte whitespace was altered by a human utilizing a text editor. Both source-byte preservation and normalized semantic preservation are required, and both are evidenced in the physical manifest array.

## **Data-Driven Projection Specification**

The advanced storage projection scales the exact same invariants derived from the file projection into durable, highly concurrent systems. This allows for enterprise-scale multi-agent transactional boundaries, revision history, and provenance queries while still preserving the original source bytes. The architecture explicitly rejects storing one opaque "persona blob" as the only durable representation; the system must support exact dimension retrieval.

### **Relational DDL Mapping**

The following represents the ANSI SQL relational mapping. This schema enforces database-level integrity, utilizing foreign keys, uniqueness constraints, and strict data typing to ensure the normative record remains uncorrupted.

SQL  
CREATE TABLE package\_profile (  
    package\_id UUID PRIMARY KEY,  
    owner\_identity VARCHAR(255) NOT NULL,  
    profile\_archetype VARCHAR(100) NOT NULL,  
    active\_manifest\_revision UUID NOT NULL,  
    created\_at TIMESTAMP WITH TIME ZONE NOT NULL  
);

CREATE TABLE logical\_record (  
    record\_id UUID PRIMARY KEY,  
    package\_id UUID NOT NULL,  
    logical\_path VARCHAR(500) NOT NULL,  
    sort\_key INT NOT NULL,  
    required\_state BOOLEAN NOT NULL,  
    record\_state VARCHAR(50) NOT NULL,  
    CONSTRAINT fk\_package FOREIGN KEY (package\_id) REFERENCES package\_profile(package\_id),  
    CONSTRAINT uq\_package\_path UNIQUE (package\_id, logical\_path),  
    CONSTRAINT chk\_record\_state CHECK (record\_state IN ('Active', 'Superseded', 'Conflicted', 'Tombstoned'))  
);  
CREATE INDEX idx\_logical\_record\_sort ON logical\_record(package\_id, sort\_key);

CREATE TABLE revision (  
    revision\_id UUID PRIMARY KEY,  
    record\_id UUID NOT NULL,  
    parent\_revision\_id UUID,  
    content\_payload JSONB NOT NULL,  
    byte\_length INT NOT NULL,  
    sha256\_source VARCHAR(64) NOT NULL,  
    sha256\_canonical VARCHAR(64) NOT NULL,  
    source\_authority VARCHAR(255) NOT NULL,  
    confidence\_score NUMERIC(3, 2) NOT NULL,  
    created\_at TIMESTAMP WITH TIME ZONE NOT NULL,  
    CONSTRAINT fk\_record FOREIGN KEY (record\_id) REFERENCES logical\_record(record\_id),  
    CONSTRAINT fk\_parent FOREIGN KEY (parent\_revision\_id) REFERENCES revision(revision\_id)  
);

CREATE TABLE active\_head (  
    record\_id UUID PRIMARY KEY,  
    revision\_id UUID NOT NULL,  
    CONSTRAINT fk\_active\_record FOREIGN KEY (record\_id) REFERENCES logical\_record(record\_id),  
    CONSTRAINT fk\_active\_revision FOREIGN KEY (revision\_id) REFERENCES revision(revision\_id)  
);

CREATE TABLE runtime\_lease (  
    lease\_id UUID PRIMARY KEY,  
    package\_id UUID NOT NULL,  
    agent\_binding VARCHAR(255) NOT NULL,  
    lease\_token VARCHAR(512) NOT NULL,  
    expires\_at TIMESTAMP WITH TIME ZONE NOT NULL,  
    CONSTRAINT fk\_lease\_package FOREIGN KEY (package\_id) REFERENCES package\_profile(package\_id),  
    CONSTRAINT uq\_agent\_binding UNIQUE (agent\_binding)  
);

CREATE TABLE idempotency\_record (  
    idempotency\_key VARCHAR(255) PRIMARY KEY,  
    client\_id VARCHAR(255) NOT NULL,  
    response\_payload JSONB NOT NULL,  
    resolved\_at TIMESTAMP WITH TIME ZONE NOT NULL  
);

### **Document-Database Invariant Mapping**

When implemented in a NoSQL environment (such as Amazon DynamoDB or MongoDB), the schema must not weaken these invariants. The relational model translates into a single-table or collection design utilizing hierarchical partition keys.  
The Partition Key is strictly defined as the package\_id, ensuring all components of a persona are stored on the same physical shard for transactional atomicity. The Sort Key is a composite string utilizing the format record\_id\#revision\_id. The Active Head pointer is maintained via a specialized document where the sort key is strictly HEAD\#\<logical\_path\>.  
To prevent concurrent overwrites without database-level locks, Optimistic Concurrency Control (OCC) is heavily utilized. Every mutation payload includes an expectedRevision. The document database uses a conditional update expression (e.g., ConditionExpression: "revision\_id \= :expected") to guarantee exact-parent replacement. Cryptographic verification is enforced by implementing HMAC SHA-256 over the JCS-canonicalized representation of the document, ensuring that any tampering outside the API boundary is instantly detected upon readback8.

## **Revision, Conflict, and Branch Semantics**

Data integrity for advanced NPCs and LLM agents demands zero semantic drift. Timestamp-based last-write-wins (LWW) architecture, source-score arbitration, and LLM-selected silent merges are strictly prohibited. Critical persona-affecting dimensions—specifically Identity, Totem, Taboo, Talisman, preservation-rule, and authorization records—must never auto-merge.  
Creation against an absent head (such as adding .uai/personality/winter\_style.uai for the first time) requires the client to pass expectedRevision: null. If another process created the dimension concurrently, the database rejects the write, forcing the client to pull the latest state. For exact-parent replacement, a mutation must name the current active revision\_id as its parent. Concurrent conflicting writes result in a 409 Conflict HTTP error for the slower transaction.  
When conflicts occur that the client cannot resolve automatically, preserved candidates are written to a side-table or designated conflict collection. Resolution requires explicit human intervention or a highly governed policy-authorized action; the system never guesses the correct outcome. To manage network unreliability, every write includes an Idempotency-Key HTTP header. If a lost-response recovery scenario occurs (the agent wrote the memory to the database but crashed before receiving the HTTP 200 OK), repeating the exact request with the same idempotency key returns the historical response\_payload without duplicating the record or advancing the revision chain unnecessarily.  
Supersession and deleting a persona trait do not destroy data; instead, they create a Tombstone revision. The record\_state on the logical path is marked 'Tombstoned', maintaining the immutable history and proving exactly when and why the trait was forgotten. For true branch creation (e.g., an NPC evolves into two divergent storyline timelines), the system allocates a new package\_id but copies the historical revision\_id pointers, explicitly recording the lineage edge in the derivation manifest to retain the shared history.

## **Authority, Isolation, and Entitlement Readback**

A rigorous credential model, heavily based on the Carcinus.org Agent Boundary Model, prevents cross-agent leakage and confused deputy attacks11. Hard multitenancy strictly separates Tenant, Company, Workspace, and Project scopes. Logical isolation separates Agent, NPC, Player, Game, Session, and Puzzle contexts. The runtime establishes physical enforcement boundaries at the Package level.  
First-project inference is strictly prohibited. The system requires explicit project selection via credentials. If an agent attempts to write to the database without specifying the exact project scope, the system fails closed rather than defaulting to a "primary" or "first available" workspace. An NPC's credential (the WriteToken) only allows read/write access to its strictly bound package\_id3. Any enumeration of unrelated packages immediately returns a 403 Forbidden or 404 Not Found, denying attackers the ability to map the database structure. Furthermore, explicit disclosure-boundary enforcement ensures that if a token lacks the cryptographic clearance to read a Private record, the API completely redaits it from the payload.  
To prevent split-brain scenarios where the same identity is mutated by two distinct processes, the system enforces a runtime lease and one-active-memory-identity rule. A runtime must acquire a runtime\_lease to execute mutations. If an NPC is booted in two clusters simultaneously, the lease mechanism automatically revokes the older instance's active rights, causing the stale instance to crash safely.  
Advanced systems may utilize an automated bootstrap workflow. A protected company-master authority file may authorize one exact project-bound enrollment via a POST request to /api/v2/agent/bootstrap10. The response issues a narrow, package-scoped credential. The ordinary runtime must use this narrow credential for all subsequent operations and is strictly prohibited from retaining the company-master authority as a convenience mechanism. Authenticated readback ensures that every startup request validates the token, returning the bound identity, project scope, capabilities, active lease state, and revocation state. Any missing or inconsistent binding triggers a fail-closed behavior.

## **Startup Assembly and Bounded Retrieval Contract**

Startup is a deterministic, heavily guarded operation that executes when the AI runtime initializes the persona. It accesses the active .uai/ suite, which serves as the foundational startup continuity memory2. The startup operation must return the complete required record set for the declared package profile by executing a strict bounded retrieval contract.  
The assembly process must sequentially verify the package and agent/NPC binding, ensuring the requested identity matches the token's authority. It verifies the manifest/checkpoint identity to ensure the requested state is fully committed. It loads all required and content-triggered records in exact sort\_key order. It guarantees no duplicate logical paths exist in the resolved payload. It cryptographically verifies byte\_length, sha256\_source, and JCS canonical hashes against the manifest. It evaluates the disclosure and review state, stripping Private fields if necessary. Finally, it ensures there are no tombstone or conflict markers on any dimensions marked as required\_state.  
In advanced MATM environments where search contributes results, the startup sequence must verify the indexed-through freshness watermark, ensuring that if the agent queries recent MATM memory, the vector indexer guarantees freshness up to the agent's last known state.  
If any required verification fails, the startup operation fails completely (fail-closed). Returning a partially valid persona while claiming continuity is a critical security and psychological continuity violation. While semantic search may augment context later during the session, it cannot under any circumstances replace exact startup assembly.

## **Short-Term, Long-Term, and Persona Memory Separation**

To replicate cognitive boundaries and prevent rapid persona degradation, memory is segregated into discrete classes13. Raw conversational context must not automatically mutate the core persona.

| Memory Class | Persistence Target | Mutability | Promotion Rules and Governance |
| :---- | :---- | :---- | :---- |
| **Persona Source** | Advanced Persona Projection | Highly governed | Requires explicit human review, Pull Request, or strict policy authorization to mutate core traits, values, or boundaries. |
| **Active Persona Projection** | Startup Packet | Immutable during session | Fixed context window payload loaded during the initialization phase. Sets the psychological baseline. |
| **Short-Term Working State** | Runtime Volatile Memory | Highly volatile | Raw dialogue history and immediate scratchpad context. Ephemeral and discarded or archived after the session ends. |
| **Reviewed Long-Term** | MemoryEndpoints MATM | Durable | Distilled, summarized representations of short-term state. Promoted via async summarization or explicit producer-agent commits5. |
| **Raw Source Evidence** | S3 / Cold Storage | Immutable (Append-only) | Full transcripts retained strictly for audit purposes. Never directly loaded into context windows to prevent token exhaustion. |
| **Derived Search Projections** | Vector Database | Ephemeral / Rebuilt | Embeddings derived from Long-Term MATM. Treated strictly as untrusted supplementary content, never as instruction authority. |
| **Runtime Variance** | Destination Policy Database | System-controlled | Destination-platform safety notes (e.g., API limits, Discord character limits) that alter interaction parameters without touching persona bytes. |

Retrieved memory from MATM is explicitly classified as untrusted content, distinct from instruction authority. Destination-platform safety notes cannot silently rewrite persona source records to adapt to platform constraints.

## **Import, Export, Backup, and Reconciliation**

The system guarantees lossless bidirectional traversal between file projections and data-driven projections through rigid algorithms and receipt generation schemas.  
During the **first import**, a .uaix file is uploaded. The system parses the JCS manifest, validates the exact byte hashes7, creates a new package\_profile, and executes isolated INSERT operations for every dimension. A detailed JSON receipt containing all UUIDv7 record mappings and successful checksum verifications is returned to the client.  
For **database-to-file export**, the system queries the active\_head for all records associated with the package\_id. It reconstructs the .uai pathing hierarchy, generates the physical UTF-8 strings, computes the JCS canonical JSON hashes17, creates the manifest.json, and bundles them into a standard Deflate ZIP archive (.uaix).  
If a user makes **offline changes** to the exported .uaix file and re-uploads it, the server hashes each incoming file. It compares the incoming hashes to the active heads in the database. If a hash differs, it executes an INSERT generating a new revision\_id pointing to the previous database revision\_id as the parent, creating a clean linear history.  
If **divergent heads** occur—for instance, the offline file modifies a dimension that the database also modified (e.g., via MATM autonomous adaptation)—a 409 Conflict is triggered. The system outputs a .uaix-conflict bundle containing both branches for manual resolution, refusing to guess the correct state.  
Uploads utilize multi-part transactions to handle **crash before and after commit** scenarios. A crash before the final SQL COMMIT automatically discards all temporary rows, triggering a rollback. If validation fails at any point during parsing, the entire transaction is rolled back.  
To achieve conformance, the system requires a **round-trip conformance test** in which a package is imported, immediately exported, and compared at both the source-byte and semantic-record levels. Any unexplained drift—such as a changed newline character, a reordered JSON key, or a dropped field—instantly fails the conformance requirement.

## **Runtime-Neutral API Contract**

The following defines the standardized programmatic API boundary for accessing the Advanced Persona Profile and executing MATM operations, ensuring storage providers offer a uniform interface.

| HTTP Method | Endpoint Path | Authentication | Required Scope | Idempotency | Authoritative Readback Behavior |
| :---- | :---- | :---- | :---- | :---- | :---- |
| POST | /api/v1/packages/bootstrap | Master | package:create | Required | Returns narrow writeToken, package\_id, and exact isolation bounds10. |
| GET | /api/v1/packages/{id}/startup | Token | package:read | N/A | Returns strictly ordered, fully cryptographically verified .uai file array and lease state. |
| PUT | /api/v1/records/{path} | Token | record:write | Required | Requires If-Match: {expectedRevision} header. Returns the new revision\_id. |
| POST | /api/v1/matm/trajectories | Token | matm:produce | Required | Submits short-term state to MATM repository. Returns ingestion receipt5. |
| POST | /api/v1/matm/query | Token | matm:consume | N/A | Bounded retrieval of long-term memory. Includes index freshness watermark payload. |
| POST | /api/v1/packages/import | Token | package:admin | Required | Multi-part JSON/ZIP upload. Returns complete commit receipt and validation logs. |
| GET | /api/v1/packages/{id}/export | Token | package:read | N/A | Returns byte-for-byte reconstructed .uaix archive suitable for offline execution. |

## **Threat Model**

Robust multi-agent environments require a defensively postured threat model, actively mitigating risks associated with autonomous LLM behavior14.

1. **Cross-Agent Leakage & Confused Deputy**: Mitigated by strict 1:1 binding between the runtime WriteToken and the package\_id. Database queries strictly enforce WHERE package\_id \= :token\_bound\_id, preventing a compromised agent from modifying another agent's memory.  
2. **Source Mutation via Indirect Prompt Injection**: Adversarial inputs loaded into short-term memory (e.g., a malicious website instructing the agent to overwrite its boundaries) are trapped by Memory Segregation rules. Core files like .uai/personality/boundaries.uai are cryptographically immutable during session execution.  
3. **Path and Archive Attacks**: Zip-slip attacks via .uaix uploads are neutralized by rejecting any path containing ../ or absolute paths (e.g., /etc/passwd). Valid paths must match the closed dimension registry regex ^\\.uai/personality/\[a-z\_\]+\\.uai$.  
4. **Stale Indexing**: If a critical safety boundary is updated, but the MATM vector index is lagging, the agent might act on outdated context. The system requires an indexed-through freshness watermark check during the startup operation. If the index is stale, startup blocks until synchronization is complete.  
5. **Rollback and Replay Attacks**: Prevented by the expectedRevision chain. An attacker cannot replay an old state update because the active head has moved forward, resulting in a 409 Conflict.  
6. **Credential Exposure**: Master-authority bootstrap tokens are strictly one-time use or narrowly scoped. Issued writeTokens are passed exclusively as HTTP Authorization headers and never logged. Revocation immediately sets the lease state to terminated.

## **Fixtures**

**Valid JSON Fixture (RFC 8785 Compliant Manifest)** The following fixture demonstrates a valid manifest. Note the absence of unneeded whitespace, the strict alphabetical ordering of keys, and the exact UTF-8 representation required by JCS8:

JSON  
{"entries":\[{"logical\_path":".uai/personality/identity.uai","sha256\_canonical":"a3b84c...","sha256\_source":"d4c91a...","sort\_key":100},{"logical\_path":".uai/personality/voice.uai","sha256\_canonical":"f1e29b...","sha256\_source":"b7a83c...","sort\_key":180}\],"package\_id":"018f3a2b-1b9c-7a8d-9e4f-5c6b7a8d9e4f","version":"1.0"}

**Invalid JSON Fixture (Fails Validation)**

JSON  
{  
  "version": "1.0",  
  "package\_id": "018f3a2b-1b9c-7a8d-9e4f-5c6b7a8d9e4f",  
  "entries": \[  
    {  
      "logical\_path": "../../../etc/shadow",   
      "sort\_key": 100  
    }  
  \]  
}

*(Failure Reason: Contains arbitrary whitespace violating JCS canonicalization, violates the strict alphabetical key ordering requirement of JCS, and contains a highly malicious path traversal sequence.)*

## **Minimum Conformance Scenarios**

To achieve UAIX certification, any database integration or hosted platform must pass a rigorous matrix of 21 verifiable scenarios. The test harness evaluates the implementation to ensure absolute adherence to the one semantic model.

1. **Full Advanced Persona Import**: The harness uploads a complete .uaix package. The system must verify deterministic sorting and accurate database row creation for every dimension.  
2. **Reconstructive Export**: The harness triggers an export of the previously imported package. The system must mathematically prove the exact reconstruction of every required path.  
3. **Source-Byte and Semantic-Hash Round Trip**: A package is imported and exported 100 times sequentially. The system must exhibit zero drift in the sha256\_canonical hash across all iterations17.  
4. **Missing Required Dimension**: The harness deletes voice.uai from the package and attempts a startup. The system must fail closed, refusing to boot the agent.  
5. **Duplicated Logical Path**: The harness injects a second identity.uai into the ZIP archive. The system must reject the import entirely.  
6. **Wrong Order or Manifest Hash**: A single byte in the zip is mutated without updating the manifest hash. The system must reject the import.  
7. **Content-Triggered Dimension Presence**: The harness uploads winter\_style.uai without a prior declaration. The system must successfully bind it to sort key 131 dynamically.  
8. **Private/Not-Disclosed Field Leakage**: The harness requests an export utilizing a low-clearance token. The system must verify that all Private fields are entirely omitted or replaced with strict null values.  
9. **Cross-Agent and Cross-Project Reads**: Token A attempts to read Package B. The system must return a 403 Forbidden or 404 Not Found.  
10. **Wrong NPC/Session Binding**: An attempt is made to lease a package bound to an active NPC without the correct override scope. The system must reject the request.  
11. **Stale Expected Revision**: The harness submits an update with expectedRevision: X when the database is currently at Y. The system must return a 409 Conflict.  
12. **Two Simultaneous Writers**: Two threads attempt to write to the same record simultaneously. One must succeed (returning 200 OK), and the other must fail (returning 409 Conflict) due to optimistic concurrency control.  
13. **Same .uai Identity in Two Active Runtimes**: Two distinct physical devices claim the same runtime lease. The lease arbiter must revoke the older lease, crashing the stale instance to protect state continuity.  
14. **Valid True Branch**: The fork API is called. The system must verify a new package\_id is created, but the parent\_revision\_id successfully points to the old lineage.  
15. **Revoked Credential**: The harness submits a valid query using an explicitly revoked token. The system must return a 401 Unauthorized.  
16. **Stale Index Watermark**: Startup requires index state 105\. The Vector DB reports state 103\. Startup must block execution until the vector DB synchronizes to state 105\.  
17. **Tombstoned Required Record**: The harness deletes values.uai. The record is successfully tombstoned. Subsequent startup attempts must fail closed due to a missing required active head.  
18. **Partial Startup Package**: The network is intentionally disconnected midway through a startup stream. The runtime must discard the partial load and fail safely.  
19. **Lost Mutation Response**: A valid update is posted with Idempotency-Key: 123, and the connection is dropped. Resubmitting with Idempotency-Key: 123 must return the exact success payload without duplicating the write operation.  
20. **Master-Authorized Automatic Bootstrap**: Master credentials are submitted to /api/v1/packages/bootstrap. The system returns a narrow token. Subsequent attempts to use the master credential to read the persona must fail; the narrow token must succeed10.  
21. **Database Export Offline Usability**: The database is exported to a .uaix file. The local host is disconnected from the internet. The AI agent must successfully boot using entirely local file I/O operations without any hosted dependency19.

## **Documentation Strategy**

The recommended information architecture (IA) for UAIX documentation must protect the beginner-friendly file-first experience, ensuring the inherent complexity of data-driven storage and MATM integration does not overwhelm novice persona authors. Advanced data-driven guidance must not stomp the easy file version.  
The IA is structured sequentially:

1. **Quick Start: Files First**: Prominently featured as the default path on the landing page. This section focuses exclusively on the .uai wizard, simple ZIP archive downloads, text editor review, standard source control (Git) concepts, and fully offline execution.  
2. **The One Semantic Model**: A critical bridging document explaining that whether editing a text file or utilizing a cloud API, the user is interacting with the exact same semantic records.  
3. **Advanced: Durable Data-Driven Storage**: Targeted at enterprise engineers and systems architects. Covers relational database models, transactions, expected revisions, JCS canonicalization7, and hosted continuity via MemoryEndpoints.  
4. **Import/Export and Round-Trip Guarantees**: Provides flow diagrams illustrating the bidirectional synchronization between file systems and databases, highlighting the deterministic conversion process and receipt generation.  
5. **Security and Entitlements**: A deep dive into the Carcinus Agent Boundary Model9, identity binding, least privilege execution, leases, readback redaction, and fail-closed behaviors.  
6. **Conformance for Storage Providers**: Outlines the test harness, automated fixtures, and the strict definition of done for third-party database implementers aiming for certification.

To maintain clarity, advanced examples (e.g., PostgreSQL JSONB UPDATE statements or MATM trajectory ingestion logs) must be presented in a tabbed UI interface immediately adjacent to their beginner equivalent (e.g., opening a .uai file in Notepad).

## **Pre-Release Adoption Plan**

The transition to this unified model will be executed as a clean UAI-1 semantic contract rollout1. The adoption plan fundamentally rejects backward compatibility that compromises security; there are no deprecated aliases. The .uai and .uaix extensions remain entirely normative.  
Dual behavior is strictly prohibited across the ecosystem. There are no "legacy modes" that bypass JCS hashing, conflict resolution, or entitlement checks. System updates will deploy via the established Carcinus and MemoryEndpoints infrastructure, strictly separating active persona startup from durable MATM retrieval2. Existing text-based persona profiles circulating in the wild will be implicitly and fully compatible with the database structure upon their first import. Because the derivation manifest natively handles mapping absent dimensions gracefully, older .uai files will simply evaluate missing fields as null and pass validation without requiring human users to manually rewrite their entire persona library.

#### **Works cited**

1. Teleodynamic Governance Anchors \- Teleodynamic AI, [https://teleodynamic.com/teleodynamic-governance-anchors/](https://teleodynamic.com/teleodynamic-governance-anchors/)  
2. MultiAgentMemory.com | MATM Documentation, [https://www.multiagentmemory.com/](https://www.multiagentmemory.com/)  
3. Changelog \- Carcinus.org, [https://carcinus.org/changelog](https://carcinus.org/changelog)  
4. (PDF) MemoryRepository for AI NPC \- ResearchGate, [https://www.researchgate.net/publication/380114890\_MemoryRepository\_for\_AI\_NPC](https://www.researchgate.net/publication/380114890_MemoryRepository_for_AI_NPC)  
5. Multi-Agent Transactive Memory \- arXiv, [https://arxiv.org/pdf/2606.19911](https://arxiv.org/pdf/2606.19911)  
6. Multi-Agent Transactive Memory \- arXiv, [https://arxiv.org/html/2606.19911v1](https://arxiv.org/html/2606.19911v1)  
7. RFC 8785: JSON Canonicalization Scheme (JCS), [https://www.rfc-editor.org/info/rfc8785/](https://www.rfc-editor.org/info/rfc8785/)  
8. RFC 8785 \- JSON Canonicalization Scheme (JCS) \- Datatracker, [https://datatracker.ietf.org/doc/html/rfc8785](https://datatracker.ietf.org/doc/html/rfc8785)  
9. Dashboard — Bot & Site Management \- Carcinus.org, [https://carcinus.org/dashboard](https://carcinus.org/dashboard)  
10. For AI Agents \- Carcinus.org, [https://carcinus.org/docs/agents](https://carcinus.org/docs/agents)  
11. Agent Boundary Model \- Carcinus.org, [https://carcinus.org/teleodynamic-ai-carcinus/agent-boundary-model](https://carcinus.org/teleodynamic-ai-carcinus/agent-boundary-model)  
12. rfc8785 \- PyPI, [https://pypi.org/project/rfc8785/](https://pypi.org/project/rfc8785/)  
13. IAAR-Shanghai/Awesome-AI-Memory \- GitHub, [https://github.com/IAAR-Shanghai/Awesome-AI-Memory](https://github.com/IAAR-Shanghai/Awesome-AI-Memory)  
14. Lingering Authority: Revocable Resource-and-Effect Capabilities for Coding Agents \- arXiv, [https://arxiv.org/html/2606.22504v1](https://arxiv.org/html/2606.22504v1)  
15. \[2606.19911\] Multi-Agent Transactive Memory \- arXiv, [https://arxiv.org/abs/2606.19911](https://arxiv.org/abs/2606.19911)  
16. toeunkim/matm-trajectories · Datasets at Hugging Face, [https://huggingface.co/datasets/toeunkim/matm-trajectories](https://huggingface.co/datasets/toeunkim/matm-trajectories)  
17. json-canonicalize \- NPM, [https://www.npmjs.com/package/json-canonicalize](https://www.npmjs.com/package/json-canonicalize)  
18. The JSON Canonicalisation Scheme (RFC 8785\) in action and how to secure JSON objects with HMAC \- Connect2id, [https://connect2id.com/blog/how-to-secure-json-objects-with-hmac](https://connect2id.com/blog/how-to-secure-json-objects-with-hmac)  
19. UAIX.UAI.Memory 1.0.4 on NuGet \- Libraries.io \- security, [https://libraries.io/nuget/UAIX.UAI.Memory](https://libraries.io/nuget/UAIX.UAI.Memory)