Local Active Memory Plus Hosted MATM Memory

Full report

On this page

Verified UAIX requirements and current support boundary

UAIX’s current public guidance is explicitly local-first. The core rule is to keep hot .uai memory active as compact startup and continuity memory, while durable memory systems such as MATM, LLM Wiki, AIWikis, docs, databases, or other long-memory planes remain augmenting layers, not replacements. UAIX states that durable memory “does not retire .uai,” and that the .uai layer should still work when the long-term memory system is unavailable. The same pages also say that hot .uai must remain sufficient for startup continuity and that agents must not make .uai “emergency-only” merely because durable memory is available.

For every launch-baseline UAIX memory or handoff package, the current universal required active-memory suite is: .uai/memory-maintenance.uai, .uai/identity.uai, .uai/world-context.uai, .uai/totem.uai, .uai/taboo.uai, .uai/talisman.uai, .uai/startup-packet.uai, and .uai/progress.uai. UAIX also requires that .uai/startup-packet.uai act as the active .uai/ read-order index. For code-bearing scopes, UAIX additionally requires .uai/coding-standards.uai, .uai/architecture.uai, .uai/test-plan.uai, and .uai/next-recursive-prompt.uai. Project Handoff packages also require .uai/system-profile.uai, .uai/receiver-brief.uai, .uai/exports/manifest.json, and either AGENTS.md or .uai/readme.human; current generated examples commonly include both, and often README.md as well.

UAIX is also clear about what is not allowed. A package must not replace the typed startup suite with a single catch-all active-memory file. The wizard warns not to create a separate memory folder, wiki folder, or random handoff Markdown files by default, and reserves wiki/ for LLM Wiki compatibility configuration. The roadmap separately says current UAIX support does not include hosted imports, automatic repository writes, automatic LLM Wiki sync, SDKs, CLIs, certification, or endorsement. These are not small details; for MATM users they mean the hosted service must be treated as an external durable-memory implementation, not as a canonical control plane for the agent’s entire cognition.

Date handling is stricter than many teams expect. UAIX says hot .uai files are current-state memory, not dated changelogs, and dates should not be added to current-memory records as ordinary bookkeeping. Dates belong only where they prove evidence, provenance, legal or publication state, manifest state, or external temporal facts. The generated next-loop example goes further and says active files should have no dates, timestamps, dated headings, chronological sections, or date-stamped package filenames. At the same time, the master file matrix explicitly describes .uai/decisions.uai as recording accepted decisions with their reasons, date, evidence, owner, and replacement path. The practical UAIX reading is: keep current operating memory date-light, but use dates where time is part of evidence or domain truth.

For MATM specifically, the current wizard exposes dedicated setup fragments such as #setup-MATM and #setup-file-handoff-MATM, and says the update URL must be the MATM memory update route, not the wizard route, unless the wizard itself is being updated. MATM endpoint records are expected to include a base URL, update URL, search URL, current-message read URL, notification acknowledgment URL, optional redacted receipt URL, public documentation URL, a MATM label, and authority/source notes. UAIX also says MATM durable memory is background until reviewed and promoted into the current authority layer named by the project, and that MATM credentials must remain outside .uai, public docs, generated packages, logs, reports, and exported packages.

Update discovery is also specified. The wizard page says visiting AI agents should read the embedded script[data-ai-digest] JSON on the canonical wizard route, and that setup fragments are listed there as point_agent_urls. Current package examples also include a “Wizard update URL” section saying refreshes should use the exact wizard route so the next agent preserves the setup mode that created the package. That is update guidance only, not a hosted importer or automatic writer.

One important documentation caveat deserves to be called out. The older Project Handoff minimum-bundle illustration still shows a root-level readme.human, while current AI Memory, generated examples, and package references repeatedly use .uai/readme.human. For new MATM-integrated packages, the safest path is to follow the current generated-package convention and verify the exact file set through the wizard and file guide rather than copying the older minimal diagram literally. That discrepancy appears real in the current public docs.

Recommended memory taxonomy and placement matrix

The table below is a recommended extension, not a UAIX normative taxonomy. It is aligned to UAIX’s split-memory rules, file classes, promotion rule, and protected-anchor model, but it organizes memory by purpose instead of redundant filenames. The design goal is that local memory remains sufficient for safe continuity during outages, while hosted MATM holds deeper, reviewed, multi-session memory without becoming a single point of cognitive failure.

The key pattern is simple: local memory should carry whatever the agent must know to remain itself, within scope, and safe during a total network outage. Hosted MATM should carry what benefits from durability, search, provenance, multi-agent sharing, and long-range recall. That follows UAIX’s split-memory rule and also matches distributed-systems practice: immutable events and durable projections belong in a store that can be replayed, while the agent’s execution-critical policy surface should remain immediately available at startup.

Recommended synchronization protocol and example schemas

The strongest MATM pattern here is not “sync everything.” It is selective promotion plus pointering. UAIX already points in that direction by making .uai/long-term-memory.uai a pointer-only ledger and by prohibiting inline durable body text, copied research, implementation history, and monolithic history dumps in hot memory. The wizard also says MATM memory remains background until reviewed and promoted into the project’s current authority layer.

A practical protocol is:

1. Session start. Read local AGENTS.md, .uai/startup-packet.uai, universal active files, and any required task-scoped files first. Only after that, read .uai/long-term-memory.uai and optionally query MATM for the specific classes relevant to the task. This follows UAIX’s read-order and context-budget posture.

1. Local write-first. Whenever project truth changes, update the affected local typed file and append a local event to a local op-log. Use append-only event capture because append-only logs preserve auditability and can rebuild derived views if needed.

1. Promotion candidate creation. Generate a compact hosted candidate from the local event, but only for memory classes that belong durably in MATM: episodic events, semantic knowledge, evidence metadata, decision history, shared coordination artifacts, or procedure bodies. Do not mirror protected anchors, every hot working note, or every transient objective string.

1. Hosted submission with idempotency and optimistic concurrency. Every MATM mutation should carry a caller-provided operation ID and tenant-scoped stream key. Use idempotency keys for duplicate-request safety, and use strong validators or explicit revision numbers to avoid lost updates. AWS recommends caller-provided request identifiers for idempotent operations, while HTTP If-Match validators are explicitly meant to prevent accidental overwrites in parallel updates.

1. Hosted response as receipt, not auto-truth. MATM should return a revision, redacted receipt URL if available, and stored pointer metadata. Local truth only changes when the hosted result is reviewed and promoted under the project’s source-authority rules. That matches UAIX’s promotion rule and MATM truth-boundary wording.

A recommended minimal event schema looks like this:

{
  "op_id": "01JZ...ULID",
  "tenant_id": "tenant-acme",
  "agent_id": "agent-build-01",
  "memory_class": "decision",
  "authority_layer": "local-hot",
  "stream_id": "project/acme/decisions",
  "parent_revision": "r42",
  "occurred_at_utc": "2026-07-12T17:42:00Z",
  "local_file_refs": [".uai/decisions.uai", ".uai/progress.uai"],
  "summary": "Adopted MATM receipt-only promotion policy for contradiction handling.",
  "payload_hash": "sha256:...",
  "evidence_refs": ["matm://receipts/...", "file://reports/..."],
  "review_state": "reviewed-local",
  "promotion_state": "candidate-hosted"
}

A recommended local pointer record, aligned to the current wizard fields, looks like this:

stable_id: ltm-7f8a
memory_domain: decisions
pointer_type: matm-record
path: .uai/long-term-memory.uai
target_location: matm://tenant-acme/project/acme/decisions/r43
label: Decision history stream
summary: Reviewed durable record of accepted decisions and reversal chain.
pointer_status: current
authority: background-until-promoted
source_authority: MATM endpoint
review_status: reviewed
quarantine_status: not_quarantined
contextual_trigger: retrieve only when current decision rationale is needed
checksum_hash: sha256:...
review_evidence: matm://receipts/redacted/...
owner_or_reviewer: architecture-steward
current_truth_boundary: Local .uai files remain current operating authority.
last_known_remote_revision: r43

For simultaneous local edits by two agents, use different strategies for different classes. For instruction-like and policy-like records, use single-writer discipline: a local lease, branch lock, or explicit handoff. For append-friendly classes such as episodic events, evidence pointers, or decision-history append entries, use append-only records plus deterministic merge rules. If true multi-writer offline editing is unavoidable for some classes, CRDT-style convergence is appropriate only for classes whose semantics are commutative; it is not a good fit for protected anchors or governing instructions.

For deletions, use tombstones rather than silent removal inside distributed hosted stores. Tombstones exist precisely so an offline replica or lagging node does not reintroduce deleted state later. That pattern is well known in distributed storage and works well for stale pointers, retired hosted memories, or redacted hosted objects.

Outage recovery and conflict handling

When the hosted endpoint is unavailable, the agent should follow a strict outage sequence.

At startup, it loads local authority first. If MATM is down, the agent no-ops only when the missing hosted data would make the task unsafe or contradictory; otherwise it continues from local active memory, which should already contain identity, instructions, active objectives, safety boundaries, and recovery pointers. That is exactly why UAIX insists hot .uai memory remain sufficient for startup continuity and why stale, pointer-only, or date-log clutter is treated as operationally inadequate.

While offline, the agent should continue to update local typed files and append events to a local pending-promotion queue. It should record hosted intents as queued operations, not as completed durable promotions. On reconnect, it should replay queued operations to MATM with the original op_id as the idempotency key. If the hosted service has already accepted an operation, it should return a semantically equivalent response for the same request identifier; if the identifier is reused with mismatched parameters, that should be a validation error, not a silent merge.

A recommended promotion state machine is:

observed locally → reviewed locally → queued for MATM → stored in MATM background → promoted into current authority layer → superseded or quarantined → tombstoned or archived

That sequence is not a current UAIX normative state machine, but it is directly consistent with UAIX’s promotion rule, review-first truth boundary, and pointer-ledger design.

Conflict policy should be asymmetric:

• If hosted data and local governing instructions conflict, local governing instructions win immediately. The hosted item should be marked quarantined or contradictory and must not be auto-promoted. UAIX’s own MATM guidance says durable MATM memory is background until reviewed and promoted, and its protected-anchor guidance forbids unapproved mutation or bypass of local anchor files.
• If two agents concurrently update a list-like class, merge by append plus duplicate suppression on op_id, then rebuild projections.
• If two agents concurrently update a policy-like class, reject one side with a revision mismatch and require human review or a named conflict resolver.
• If a hosted pointer is stale, keep the pointer record locally but change pointer_status to quarantined or superseded; do not delete the routing hint until a replacement pointer is committed.
• If duplicate events arrive, deduplicate by (tenant_id, stream_id, op_id) and return the prior receipt.

The recovery goal is not “perfect consistency before thinking.” It is safe degraded autonomy locally, then auditable reconciliation later. That is the right way to avoid making MATM a single point of cognitive failure.

Security, privacy, and retrieval controls

UAIX and OWASP are aligned on the most important security rule here: credentials are not memory. UAIX says to keep MATM credentials outside .uai, public docs, generated packages, logs, reports, and exported packages, and to inventory credential files only by safe metadata. AI Memory pages separately forbid secrets, credentials, private keys, tokens, connection strings, and raw private data in active memory. OWASP’s secrets guidance likewise recommends centralized storage, provisioning, auditing, rotation, and life-cycle documentation for secrets rather than scattering them through application artifacts.

For a hosted MATM service, tenant scoping must be explicit and early. OWASP’s multi-tenant guidance recommends establishing tenant context early in the request lifecycle, using non-guessable tenant identifiers, never trusting client-supplied tenant IDs without validation, binding tenant context to the authenticated session, and propagating it securely through all layers. For a memory service, that means every stream, search, receipt, and revision lookup should be tenant-keyed and agent-scoped, not inferred from the request body alone.

Agent identity should also be first-class. NIST Privacy Framework materials call for identities and credentials to be issued, managed, verified, revoked, and audited for authorized individuals, processes, and devices. In practice, the MATM client should use a separate principal for each agent or workflow class, not a single shared machine user, because per-agent auditing is what makes memory provenance useful during incident response and rollback.

Token handling needs extra care. RFC 6750 reminds us that a bearer token can be used by any party in possession of it, because bearer tokens do not prove possession of key material. So for MATM, the baseline should be HTTPS everywhere, short-lived scoped tokens, rotation, and storage outside memory artifacts. For highly privileged MATM write routes, sender-constrained or stronger client authentication is better than long-lived bearer tokens alone.

Encryption and audit boundaries should be explicit. NIST’s Privacy Framework says data at rest and in transit should be protected, and that data provenance and lineage should be maintained and reviewable. OWASP logging guidance says logs must be protected against tampering, unauthorized access, modification, and deletion; tamper detection should exist at rest, all log access should itself be recorded, and secure transmission should be used over untrusted networks. For MATM, that means encrypted transport, encrypted storage where appropriate, append-oriented audit records for adds/updates/deletes/promotions, and redacted receipts for external review.

Retrieval strategy should be pointer-first and class-aware. UAIX says agents should load only the files required by the bundle and current task, and that hot memory should stay concise. The hosted side should mirror that philosophy: search MATM by memory class, authority boundary, review status, and objective; retrieve summaries and provenance first; bring full bodies into context only when the current task needs them. Keep per-class budgets, such as a small fixed budget for decisions and risks, an even smaller budget for episodic recall, and a near-zero budget for semantic bodies unless a pointer indicates they are necessary. Before slimming local context, UAIX says to preserve the pre-slim version in cold memory with path, checksum, actor, time, and disposition, then reduce hot memory to current truth plus a pointer.

Integration tests and standards improvements

A MATM integration is not ready until it passes outage, conflict, and privacy tests that reflect UAIX’s local-first boundary.

The current UAIX standards and wizard would be materially better for MATM users if they made the following improvements:

The core design conclusion is straightforward. Make local memory the agent’s survival layer, and make MATM the durable cognition layer. Local memory should carry the minimum reviewed truth needed to remain safe, on-mission, and recoverable without the network. Hosted MATM should then provide mid-term and long-term recall, semantic depth, provenance, and multi-agent coordination through pointer-first retrieval, review-gated promotion, append-only auditability, idempotent writes, explicit revisions, and tenant-scoped access. That architecture matches the current UAIX public record and avoids turning the hosted service into a single point of cognitive failure.