Spec, Wizard, and Docs Changes for Long-Term Memory

Full report

UAIX standards and the Memory Wizard already treat long-term memory as external “cold” memory. The .uai/long-term-memory.uai file is defined as a pointer to durable archives (LLM Wikis, archive folders, etc.), not a dump of all history. For example, UAIX Project Handoff guidance advises: when a bundle grows large, “preserve the pre-slim files in an LLM Wiki or AIWikis-style cold memory layer… then keep the active ….uai files concise and point to cold memory only when the task needs original evidence.”. In line with this, the wizard already “adds .uai/long-term-memory.uai as an active pointer required for long-memory configuration” (e.g. for LLM Wiki setups).

Spec updates: We must clarify that long-term-memory.uai is always a pointer file. The specification should explicitly state that long-term-memory.uai must list references (URLs, file paths, links to Wiki pages) to the project’s durable memory store, and must not contain raw memory content. For example, if long-term memory is kept in a wiki or docs folder, long-term-memory.uai should “point to” those sources by name or link. The spec text should use “Required for…” language consistently (no “optional”). For example:

• Memory package boundary: “If legacy memory files exist, the agent must move all active facts into .uai records and retire the old memory path. Active .uai files should then point to cold archives (LLM Wiki pages or docs) for history.”
• Long-term-memory.uai description: Emphasize that it is “Required for long-memory packages” and “points to durable wiki, archive, graph, evidence, and preservation systems without treating all stored history as current truth”. Any mention of it being optional should be replaced with “Required for X configuration.”

Wizard/UI changes: The wizard’s update logic and UI need to enforce this pointer approach. On Active Memory (Step 6) and update steps, the wizard should:

• Always create a .uai/long-term-memory.uai pointer file when any long-term memory is used. For an LLM Wiki path, that file should point to the wiki root/index as it already does. For a default file-based memory (no wiki), the wizard should similarly create long-term-memory.uai containing links (relative or absolute) to the actual memory files stored under /docs or another archive folder. For example, it could list paths to Markdown files in /docs that hold the narrative memory.
• Prevent agents from dumping history into one file. In update mode, if the agent has added new history, the wizard should re-organize memory: move new facts into short-term memory (.uai/short-term-memory.uai) or specific .uai records, and not append them to long-term-memory.uai. Instead, it should regenerate long-term-memory.uai to point to the docs or wiki where those facts reside. In other words, implement the recommended “memory reorganization” on update.
• The UI should clarify this behavior and use strict wording. For example, replace any “optional long-memory plan” toggles with “Required for LLM Wiki” or “Required for project history”. If the wizard currently offers an “Add Wiki plan (optional)” choice, change it to “LLM Wiki configuration (required for long-term memory).”

Documentation changes: All docs and examples must reflect the pointer model and use “Required for…” labels. For instance:

• In the wizard guide or tooltip explaining Step 6, say “Required for LLM Wiki setups: add .uai/long-term-memory.uai as a pointer to the wiki.” Remove any language suggesting that a long-term memory file is optional or contains all history.
• In the file specification docs, update entries to remove “optional” wording. The UAIX style guide already uses “Required for X” (see memory file taxonomy), so ensure all memory-related files follow that. For example, “.uai/long-term-memory.uai – Required for long-term-memory packages and must list external memory locations” instead of “optional LLM wiki plan.”
• Add examples or migration notes: show how to transition a project that currently keeps history in one file. The docs should instruct: “If your package now stores all memory in one file, do a memory reorg: move old content into Markdown or archive files (e.g. under /docs), then replace your long-term-memory.uai with one listing links to those files. The agent should then retire the old file.” (This follows guidance from the Memory Package “Memory boundary” rules.)

Migration guidance: For any existing package that used a single memory file, instruct users to split it. For example, create a /docs folder containing the historical notes as separate .md files (or a wiki), then update long-term-memory.uai to point to them. Record in short-term-memory.uai only the current active facts. Finally, use “Retired: old-history.md” or archive them in .uai/archives/ as per UAIX guidance. This follows the UAIX principle: “move bulky history… into the named LLM Wiki/AIWikis long-memory path or .uai/archives/ evidence… then remove or clearly retire the mistaken path”.

These changes ensure the wizard and spec enforce pointer-based long-term memory. The key is to always treat long-term-memory.uai as a required pointer (not optional), linking to environment-specific storage (Wiki or docs) rather than absorbing all history into one file. By updating the spec text, wizard logic, and docs accordingly, agents will stop dumping all memory into a single file and will instead use the appropriate structured memory layer.

Sources: UAIX memory file rules and wizard documentation.