UAIX Memory, Long-Running Tasks, and Follow Goals

Full report

On this page

Executive summary

UAIX’s memory model is not a hosted memory database or a runtime scheduler. Its core design is a portable, reviewable, file-based memory layer centered on AGENTS.md, .uai/readme.human, and typed .uai records, while agent runtimes execute elsewhere and write back accepted results after the run. In UAIX’s own wording, Project Handoff is the durable, reviewable project-state bundle; runtime systems handle execution, tools, approvals, delegation, traces, and session state.

Within that model, UAIX currently treats Follow Goals as a runtime-facing export, not as the durable source of truth. The official guidance says to keep durable project memory in repo-local UAIX files and export a short Goal / Success Criteria / Constraints block only for runtimes that benefit from structured planning. The wizard makes this explicit: when a receiver uses /goal or Follow Goals, .uai/exports/follow-goal.json becomes configuration-specific, but UAIX files remain authoritative, and the feature is not described as a native UAIX long-running task system or official OpenAI adapter.

For long-running work, the strongest current UAIX building blocks are already present, but they are spread across several pages and schemas: compact hot memory and cold-memory separation; short-term-memory.uai, progress.uai, current-state.uai, next-actions.uai, and decisions.uai; the uaix.next-recursive-prompt.v1 resume artifact for code-bearing scopes; and the UAI-1 packet family for task-status, blocker, handoff, memory-proposal, and final-report. What is still missing is a single, explicit orchestration recipe that ties those pieces together for extended, interruptible, multi-step work.

My overall conclusion is that the best way to add guidance to UAIX is not to invent a second memory system for long-running tasks. Instead, UAIX should document a canonical pattern where: the parent goal lives in Follow Goals plus authoritative .uai files; subtasks write checkpoints into .uai hot memory; runtime progress is emitted through uai.agent.task-status.v1; blockers use uai.agent.blocker.v1; ownership transfers use uai.agent.handoff.v1; accepted durable facts move through uai.agent.memory-proposal.v1; and the run closes with uai.agent.final-report.v1 plus authoritative .uai write-back. That pattern fits UAIX’s current support boundary and avoids turning chat/session state into durable truth.

What UAIX memory is today

UAIX defines AI memory as a portable working packet for continuity, handoffs, onboarding, audits, and agent-ready context, while deeper historical documentation belongs in LLM Wiki or other cold-memory layers. The system is intentionally designed to keep current operating truth compact rather than treating raw chat history, archived reports, or broad institutional knowledge as default startup context.

Practically, UAIX organizes this memory through typed .uai files with specific scopes and update triggers. The universal launch-baseline set includes .uai/memory-maintenance.uai, .uai/identity.uai, .uai/world-context.uai, .uai/totem.uai, .uai/taboo.uai, .uai/talisman.uai, and .uai/short-term-memory.uai. Project and handoff scopes then add records such as .uai/context.uai, .uai/constraints.uai, .uai/progress.uai, .uai/operations.uai, .uai/current-state.uai, .uai/next-actions.uai, .uai/decisions.uai, .uai/owners.uai, .uai/agent-instructions.uai, .uai/risk-register.uai, and .uai/test-plan.uai; code-bearing scopes also require .uai/next-recursive-prompt.uai.

The file guide is unusually useful because it doubles as a write policy. For example, short-term-memory.uai is for compact working state, newest decisions, active blockers, and next-read pointers; it is updated after meaningful work, handoff, deployment, intake processing, or context compaction. progress.uai changes after meaningful work segments, test passes, blocker resolution, or release-preparation steps. current-state.uai changes after each test run, deployment, blocker change, or other meaningful status change. next-actions.uai changes whenever priority or blocker state changes. decisions.uai changes when a durable decision is accepted, replaced, reversed, or proven stale. These triggers strongly imply a checkpoint model even though UAIX does not yet publish one consolidated “checkpoint cadence” page.

UAIX also publishes a strict read order. The file guide says to start with AGENTS.md or .uai/readme.human, then .uai/memory-maintenance.uai, identity, world context, and the active instruction anchors (totem, taboo, talisman), then short-term-memory.uai, then profile-required files, and only after that consult long-memory pointers. This read order matters for long-running systems because it prioritizes current truth and boundaries over large background context.

Security and mutation boundaries are part of the memory model itself. The uaix.memory-maintenance.v1 schema and example say .uai/taboo.uai, .uai/totem.uai, and .uai/talisman.uai are protected when present, with operator_explicit_only access and an agent_default of forbidden; the validator must not scan them, and packages missing valid memory-maintenance.uai are non-compliant. That means long-running automation cannot safely treat all memory surfaces as equally mutable.

UAIX’s retention policy is qualitative rather than numeric. The context-budget guide repeatedly says hot files should remain compact and current, while long research, old chats, audits, and pre-slim snapshots should move to cold memory with source paths, checksums, summaries, and dated logs. I did not find a primary-source numeric token/KB/MB limit for UAIX memory files. The only explicit size-related limit I found was on the machine API surface, where oversized POST bodies can trigger problem+json errors; that is an API behavior, not a memory-file quota.

How Follow Goals and long-running work currently fit

UAIX’s official Follow Goals guide positions the feature as runtime guidance, not the memory system. The guide explicitly says to export a short Goal / Success Criteria / Constraints block for environments that support structured planning while keeping durable project memory in AGENTS.md, .uai/readme.human, and relevant .uai files. The runtime goal block should be derived from current handoff truth, not from old chats or broad archive material.

The wizard reinforces the same boundary. In its receiver step, the “Alternative: Follow Goals” option is off by default, is described as an “OpenAI-compatible runtime goal export,” and produces .uai/exports/follow-goal.json only when selected. The page explicitly says this is not an official OpenAI adapter, hosted importer, SDK, CLI, certification surface, or native API goal field. The wizard also says it saves only a local browser draft and never uploads, imports, syncs, or writes to a repository.

For long-running work more broadly, UAIX’s strongest formal mechanism is the agent communication packet family. The operating model says to acknowledge requests, execute work elsewhere, report evidence with task status, blockers, risks, screenshots and validation output, propose memory changes separately from task execution records, and then hand off, finalize, or correct. It also states that durable memory proposals must be separated from task execution, and that session tokens, write tokens, local error traces, private keys, credentials, and other secret-like values must not be promoted into durable memory.

The packet schemas are already expressive enough for asynchronous workflows. uai.task.status.v1 carries generic task state such as task_id, state, progress, status_message, result references, and updated fields. The newer uai.agent.task-status.v1 adds a clearer agent-operations shape with percent_complete, current_action, and estimated_completion_utc, plus correlation, idempotency, timeout, and fallback metadata. uai.agent.blocker.v1 handles authorization, ambiguity, resource exhaustion, missing context, secret, destructive-action, and boundary conflicts. uai.agent.handoff.v1 carries a target actor, context summary, handoff reason, exact next action, and delegated authorization reference. uai.agent.memory-proposal.v1 enforces task_execution_separation: "memory_proposal_only". uai.agent.final-report.v1 preserves changed files, tests, skipped checks, blockers, risks, validation evidence, memory updates proposed, memory updates skipped, and an exact next action.

Capability profiles also matter. The uai.client.workflow-agent.v1 schema and example explicitly model clients that can run long tasks, but the example sets can_store_memory to false and lists “Cannot store durable memory without a separate memory proposal” among known limits. That is a clean fit with UAIX’s philosophy: long-running execution is allowed, but durable memory updates are separate, reviewable acts.

Where the current guidance is incomplete

The first gap is that UAIX documents the pieces of long-running work, but not a single canonical flow that joins Follow Goals, .uai checkpoints, agent task-status packets, blockers, handoffs, memory proposals, and final reports. The result is that implementers can see the parts, but not the recommended choreography.

The second gap is that Follow Goals guidance is strongest at run startup, weaker in mid-run continuity. The guide explains how to derive a concise goal block from the handoff bundle, but it does not presently publish a standard for checkpoint frequency, partial-progress write-back, retry semantics, timeout handling, or interruption recovery for Follow Goals sessions. UAIX does publish those ideas across other records — especially through progress.uai, current-state.uai, next-actions.uai, uai.agent.task-status.v1, and uai.agent.blocker.v1 — but not as one Follow Goals operating recipe.

The third gap is asymmetry between code and non-code scopes. Code-bearing packages have a formal resume artifact in uaix.next-recursive-prompt.v1, which clearly says it is derived hot memory, that authoritative .uai records win on conflict, that related active intake can supersede it, and that accepted work should regenerate it from authoritative records. I did not find an equivalent, formal, non-code resume artifact for broader long-running goals.

The fourth gap is around conflict resolution. UAIX publishes the building blocks — local policy wins, human instruction overrides, active intake can supersede stored next-loop plans, protected anchors are immutable without exact authorization, and startup packets name memory_conflict_unresolved as a no-op trigger — but it does not yet publish a single conflict-resolution ladder for long-running workflows.

The fifth gap is around memory sizing. UAIX clearly wants hot memory to stay “small enough to load and precise enough to trust,” but it does not publish numeric thresholds or compaction triggers. That is workable, but it means teams implementing long-running work need an explicit local rule if they want deterministic checkpoint compaction behavior.

Recommended integrated guidance for UAIX

The best addition to UAIX would be a canonical long-running task pattern with five stacked layers.

First, keep the parent goal in two places: a concise runtime export such as .uai/exports/follow-goal.json, and the authoritative handoff bundle. Follow Goals should carry only the active objective, success criteria, hard constraints, expected touchpoints, and checks needed for this run; real project truth remains in AGENTS.md, short-term-memory.uai, constraints.uai, progress.uai, current-state.uai, next-actions.uai, and decisions.uai. That follows UAIX’s hot-context design and OpenAI’s advice to use clear instructions, persistence reminders, tool-use reminders, ordered workflows, and deliberate planning for agentic work.

Second, persist subtask state in authoritative hot files, not in the Follow Goals export. A practical mapping is: short-term-memory.uai for compact current working state; progress.uai for completed work, verified work, and recent deltas; current-state.uai for readiness, deployment/test posture, and blocker state; next-actions.uai for the ordered queue; decisions.uai for accepted changes in approach; and, for code-bearing scopes, next-recursive-prompt.uai for a derived resume artifact regenerated after accepted work. This is an inference from UAIX’s update triggers, but it closely matches the official file roles.

Third, use packetized runtime continuity during the run. My recommendation is: emit uai.agent.task-status.v1 at each meaningful checkpoint or state transition; emit uai.agent.blocker.v1 whenever the next step is unsafe or underspecified; emit uai.agent.handoff.v1 if responsibility moves to another actor or runtime; emit uai.agent.memory-proposal.v1 only for candidate durable facts; and always close with uai.agent.final-report.v1. That exactly respects UAIX’s boundary that runtimes execute while UAIX records reviewed communication, evidence, and memory promotion.

Fourth, define a checkpoint cadence that mirrors the primary docs. UAIX repeatedly says to update records after meaningful work segments, test passes, blocker resolution, deployment changes, handoff boundaries, and meaningful status changes. A good practical rule is: checkpoint on every subtask completion, every blocker/unblocker, every verification event, every ownership change, and every interruption boundary. If the task is code-bearing, regenerate next-recursive-prompt.uai only after authoritative files are updated.

Fifth, make cold memory the branch log, not the active execution plan. For exploratory planning, retries, alternative strategies, Tree-of-Thoughts branches, or large research notes, store discarded or speculative branches in cold memory with provenance, summaries, and checksums; only the selected path and accepted facts should be promoted into hot .uai memory. That aligns with Project Handoff’s hot/cold split, the knowledge-graph guide’s rule that graph/vector retrieval must not auto-promote generated or retrieved text into accepted truth, and the research-harness guide’s “evidence before claim” rule.

graph TD
    A[Parent goal\nfollow-goal.json + AGENTS.md] --> B[Subgoal queue\nnext-actions.uai]
    A --> C[Hard constraints\nconstraints.uai]
    A --> D[Current operating truth\nshort-term-memory.uai]
    B --> E[Subtask checkpoint]
    E --> F[progress.uai]
    E --> G[current-state.uai]
    E --> H[uai.agent.task-status.v1]
    E --> I{Blocked?}
    I -- Yes --> J[uai.agent.blocker.v1]
    I -- No --> K{Ownership change?}
    K -- Yes --> L[uai.agent.handoff.v1]
    K -- No --> M[Continue next subtask]
    M --> N[Accepted result]
    N --> O[uai.agent.memory-proposal.v1]
    N --> P[uai.agent.final-report.v1]
    O --> Q[Authoritative write-back]
    P --> Q

This decomposition is a recommended UAIX operating pattern, not a new standard. It is derived from the official roles of Follow Goals, .uai files, and UAI-1 agent packets.

stateDiagram-v2
    [*] --> LoadAuthoritative
    LoadAuthoritative --> BuildRuntimeGoal
    BuildRuntimeGoal --> Working
    Working --> Checkpointed: meaningful segment complete
    Checkpointed --> Working
    Working --> Blocked: missing approval/context/capability
    Blocked --> Handoff: another actor should continue
    Blocked --> Working: approval or evidence arrives
    Handoff --> Working: new actor resumes with same correlation_id
    Working --> Finalized: done criteria met
    Finalized --> WriteBack
    WriteBack --> [*]

The important state rule is that durable truth lives in the authoritative write-back surfaces, not in the runtime state machine itself.

Strategy comparison

The first three strategies are the ones I would recommend UAIX document as an ordered maturity path: start with a Follow Goals overlay, add recursive checkpoints, then add packetized async continuity when tasks cross runtime or agent boundaries. That sequence best matches UAIX’s own capability ladder and runtime-versus-record boundary.

Templates and example hierarchies

These templates are synthesized from UAIX’s file roles, Follow Goals guidance, the next-recursive-prompt model, OpenAI’s agent prompting guidance, and the planning literature around plan-and-solve, interleaved reasoning/action, and branch-and-evaluate search.

Parent-goal runtime export

Goal:
Finish the next bounded work chunk for <project> without widening support claims or violating hard constraints.

Success criteria:
- The bounded subtask is complete or a concrete blocker is recorded.
- Targeted checks are run or explicitly skipped with a reason.
- Accepted facts are written back to authoritative UAIX files.
- A concrete next action is left for continuation.

Constraints:
- Authoritative truth is AGENTS.md plus the listed .uai files.
- Do not treat old chats, raw traces, or large reports as current truth.
- Do not promote secrets, tokens, credentials, or unreviewed cold-memory claims.
- If approval, context, or capability is missing, stop with a blocker.

Subtask prompt

Read AGENTS.md first, then .uai/readme.human, then the relevant .uai files for this subtask.
Summarize current truth, hard constraints, expected touchpoints, and targeted checks.
Complete only this subtask:
<subtask description>
After any meaningful change, update progress/current-state/next-actions.
If the task is code-bearing, regenerate next-recursive-prompt after authoritative write-back.
If blocked, emit a blocker with the exact missing approval, capability, or evidence.

Monitoring agent prompt

Monitor correlation_id <id>.
At each checkpoint, require:
- percent complete
- current action
- blocker state
- tests/checks run or pending
- exact next action
If a blocker persists across two checkpoints, require escalation or handoff.
If authoritative files drift from the runtime summary, prefer authoritative files and request reconciliation.

Recovery after interruption

Resume task <task_id> using the authoritative handoff bundle, not the last chat turn.
Load AGENTS.md, short-term-memory.uai, current-state.uai, progress.uai, next-actions.uai, constraints.uai, and decisions.uai.
If code-bearing, also load next-recursive-prompt.uai only as derived hot memory.
Reconstruct:
- last accepted checkpoint
- unfinished subtask
- active blockers
- required checks
- exact next action
If any conflict is unresolved, emit a blocker instead of guessing.

flowchart TD
    A[Resume request] --> B[Load AGENTS.md + authoritative .uai]
    B --> C{Conflict with stored resume artifact?}
    C -- Yes --> D[Prefer authoritative files]
    D --> E{Conflict still unresolved?}
    E -- Yes --> F[Emit blocker and request review]
    E -- No --> G[Rebuild working context]
    C -- No --> G
    G --> H[Execute next bounded chunk]
    H --> I{Meaningful status change?}
    I -- Yes --> J[Update progress/current-state/next-actions]
    J --> K{Code-bearing scope?}
    K -- Yes --> L[Regenerate next-recursive-prompt]
    K -- No --> M[Emit task-status]
    L --> M
    M --> N{Interrupted again?}
    N -- Yes --> B
    N -- No --> O{Done criteria met?}
    O -- No --> H
    O -- Yes --> P[Final report + memory proposal + authoritative write-back]

This recovery flow is the clearest way to operationalize UAIX’s current principles: authoritative files first, derived resume artifacts second, blockers over inference, and write-back after accepted work.

Proposed additions to UAIX documentation

The most useful addition would be a new guide or subsection titled something like “Long-Running Goal Execution”, with language along these lines:

Use Follow Goals only as a runtime view of the current objective. Derive it from AGENTS.md and the relevant .uai files. During execution, checkpoint every meaningful work segment, status change, verification step, blocker, or handoff boundary. Record durable working state in authoritative .uai files, emit uai.agent.task-status.v1 for runtime continuity, uai.agent.blocker.v1 for unsafe continuation, uai.agent.handoff.v1 for ownership transfer, uai.agent.memory-proposal.v1 for candidate durable facts, and uai.agent.final-report.v1 on completion. For code-bearing scopes, regenerate .uai/next-recursive-prompt.uai after authoritative write-back. Treat cold memory, graph retrieval, and old chats as background until reviewed and promoted.

I would also add a small selection rule between the two task-status families:

• Use uai.task.status.v1 for generic async exchange where you mainly need state, progress, status text, and result references.
• Use uai.agent.task-status.v1 when the workflow is part of the Agent Communication Operating Model and you need correlation-linked status, percent-complete, current action, UTC estimate, idempotency, timeout, and fallback semantics.

Finally, UAIX should explicitly state that there is no current published numeric memory-size limit, and recommend a local compaction rule such as “slim hot memory whenever startup files stop being easy to load in one pass or begin absorbing cold-memory material.” That would make the qualitative context-budget guidance easier to operationalize without pretending the site publishes a formal hard cap.

Open questions and limitations

The primary docs are strong on boundaries and artifacts, but a few things remain genuinely open.

UAIX currently publishes sufficient components to build a disciplined long-running task system, but I did not find a single official page that fully standardizes checkpoint cadence, retry budget, timeout escalation policy, or a numeric hot-memory size threshold. Those parts of this report are therefore recommended integrations, not claims that UAIX has already normatively standardized them.

I also did not find a UAIX-native /goals protocol. The primary wording I found is around Follow Goals, Codex Goal mode, OpenAI structured prompts, and .uai/exports/follow-goal.json when the receiver uses /goal. So the safest reading is that UAIX supports goal-oriented runtime exports, but does not claim a native hosted goal-management API of its own.

Finally, while external planning literature clearly supports decomposition, interleaved reasoning/action, and branch-and-evaluate strategies, those patterns should be applied conservatively inside UAIX: branch exploration belongs in runtime state or cold memory, and only reviewed accepted facts should reach hot .uai memory.