UAI AI Memory And Project Handoff With Claude Code

UAIX’s current public standard is **UAI-1**, but the two UAIX surfaces most relevant to Claude-based coding workflows are **AI Memory** and **Project Handoff**. AI Memory is a **portable, reviewable package** for comp...

Metadata

Field	Value
Source site	uaix.org
Source URL	https://uaix.org/
Canonical AIWikis URL	https://aiwikis.org/uaix/files/raw-system-archives-uaix-source-site-report-preservation-2026-05-01-agen-305ac066/
Source reference	raw/system-archives/uaix/source-site-report-preservation/2026-05-01/agent-file-handoff/Archive/2026-05-01/Improvement/codex-handoff-cross-tool/UAI AI Memory and Project Handoff with Claude Code.md
File type	md
Content category	memory-file
Last fetched	2026-06-22T01:56:21.9510185Z
Last changed	2026-05-01T17:29:32.1056530Z
Content hash	sha256:305ac066ab7ad96a1910c651b7668593352b3e1bbf9cd448afee3a531132afd6
Import status	unchanged
Raw source layer	data/sources/uaix/raw-system-archives-uaix-source-site-report-preservation-2026-05-01-agent-file-handoff-archive-2-305ac066ab7a.md
Normalized source layer	data/normalized/uaix/raw-system-archives-uaix-source-site-report-preservation-2026-05-01-agent-file-handoff-archive-2-305ac066ab7a.txt

Current File Content

Structure Preview

• UAI AI Memory and Project Handoff with Claude Code
• Executive Summary
• Definitions and capability model
• Implementation patterns and code
• Claude Code
• TypeScript memory example with the Anthropic SDK
• Python memory example with the Anthropic SDK
• Python scaffold for a UAI handoff bundle usable by Claude Code
• Example App
• Handoff Summary
• Loaded Context
• Current State
• Next Steps
• Agent History
• Open Questions
• Do Not Change
• Project Context
• Technology Stack
• Constraints
• Progress
• Security, governance, and data handling
• Reliability, observability, and cost
• Migration strategies, best practices, and common pitfalls

Raw Version

This public page shows a bounded preview of a large source file. The complete source remains in the raw and normalized source layers named in metadata, with the SHA-256 hash above for verification.

• Source characters: 40422
• Preview characters: 11835

# UAI AI Memory and Project Handoff with Claude Code

## Executive Summary

UAIX’s current public standard is **UAI-1**, but the two UAIX surfaces most relevant to Claude-based coding workflows are **AI Memory** and **Project Handoff**. AI Memory is a **portable, reviewable package** for compact accepted context such as current state, constraints, decisions, owners, next actions, risks, and checks. Project Handoff is a **repository-context draft format** built around a root `AGENTS.md`, a root `readme.human`, and typed `.uai` files that split durable knowledge into explicit, loadable records. UAIX is explicit that these handoff artifacts are *draft repository-context guidance*, not by themselves UAI-1 conformance evidence or certification. citeturn8view0turn44view0turn44view2turn44view3turn7view3

For Claude, there is not one “memory feature,” but several distinct memory surfaces. **Claude Code** uses `CLAUDE.md` and **auto memory** (`MEMORY.md`) to bring project instructions and learned notes into each new session; each Claude Code session still starts with a fresh context window. The **Messages API memory tool** is a client-side primitive that lets Claude create, view, update, and delete persistent files in a memory directory that *you* control. **Claude Managed Agents** add a third option: **memory stores**, which are workspace-scoped collections of text documents mounted into stateful sessions, with immutable versions for audit and point-in-time recovery. citeturn42view0turn20view0turn20view1turn22view0turn42view1

The most important interoperability finding is straightforward: **Claude Code reads `CLAUDE.md`, not `AGENTS.md`**. Anthropic’s own Claude Code docs recommend creating a `CLAUDE.md` that imports `AGENTS.md` when a repository already uses `AGENTS.md`. That makes UAI Project Handoff practical with Claude Code today: keep the **shared, portable, multi-agent project brief** in UAI handoff files, then use a thin `CLAUDE.md` shim to import them and add Claude-specific instructions. In practice, the cleanest design is to keep **stable project truth** in UAI handoff files, **Claude-specific behavior** in `CLAUDE.md`, and **emergent learnings** in Claude auto memory or the Memory tool. That design is an engineering inference, but it is directly supported by the way UAIX separates reviewed package truth from deeper background memory and by Anthropic’s division between instructions and learned notes. citeturn43view0turn8view0turn42view0turn39view0

There is also an important **support-boundary** constraint. UAIX currently publishes pages, schemas, validator guidance, examples, an API reference, an adoption kit, a conformance pack, and the AI Memory Package Wizard, but it does **not** currently publish hosted upload/import validation, automatic repository writes, automatic LLM Wiki sync, SDKs, CLI tools, certification, or endorsement. So the near-term implementation model is **file-first** and **API-light**: use UAI as a portable file contract, and use Claude surfaces to consume or produce those files. citeturn7view1turn7view2turn6view2

The strongest recommendation is therefore to treat UAI as the **portable governance and handoff layer**, while using Anthropic’s products as the **runtime layer**. For single-repository Claude Code work, import `AGENTS.md` into `CLAUDE.md` and keep auto memory concise. For custom applications, use the Messages API memory tool when you want maximum control over storage, retention, and encryption; use Managed Agents memory stores when you want Anthropic-managed stateful sessions and versioned memory in a managed container runtime. Use context editing, compaction, and prompt caching deliberately to keep token growth under control. citeturn43view0turn20view0turn42view1turn23view0turn24view2turn31view1

## Definitions and capability model

UAIX’s AI Memory model is **not** a long-lived hosted memory service. It is a governed packaging approach for accepted context. UAIX’s optional LLM Wiki guidance makes the distinction explicit: the **deep layer** is background research and institutional memory, while the **UAI AI Memory package** carries compact, accepted current state that is portable and reviewable. UAIX’s rule is that deeper background memory remains background until it is reviewed and promoted into accepted project truth such as `AGENTS.md`, `.uai` files, docs, code, tests, or release records. citeturn8view0

Project Handoff is the point where accepted package truth becomes **repository takeover context**. UAIX defines that handoff around a root `AGENTS.md`, a root `readme.human`, and typed `.uai` files referenced explicitly with `@uai[]`. The purpose is to move project state between AI models, agent systems, vendors, teams, or companies **without depending on private chat history**. The handoff is designed to be self-sufficient: the next AI should read the handoff files, summarize what it learned, and confirm constraints before editing. citeturn44view2turn44view3

UAIX’s required structure is unusually concrete. `AGENTS.md` is the root coordination file, with sections for **Handoff Summary**, **Loaded Context**, **Current State**, **Next Steps**, **Agent History**, **Open Questions**, and **Do Not Change**. The `.uai` file family is typed and intended to separate project purpose, stack, architecture, decisions, constraints, style, data contracts, operations, tests, and more into small durable files instead of one oversized brief. citeturn44view4turn44view5

Anthropic’s Claude surfaces map to this model, but they do so in different ways. Claude Code starts every session with a fresh context window and then loads two kinds of carried context: **instructions you wrote** in `CLAUDE.md`, and **notes Claude wrote** in auto memory. Anthropic explicitly says these are loaded as context rather than enforced configuration. Auto memory is per working tree and only the first **200 lines or 25 KB** are loaded at session start, which is an important scale constraint. citeturn42view0turn43view0

Anthropic’s Messages API **memory tool** is different from Claude Code auto memory. It is a tool-level API primitive that lets Claude read and write a `/memories` directory across conversations. Anthropic says this is the key primitive for **just-in-time context retrieval** in long-running workflows, and that the tool operates **client-side**, meaning you control where memory is actually stored. Anthropic also recommends restricting all memory operations to the `/memories` directory. citeturn20view0turn19view0

Managed Agents adds a more managed persistence layer. Anthropic describes Managed Agents as **stateful sessions with persistent event history**, and its memory stores as **workspace-scoped collections of text documents** that mount into the session container as directories the agent can access with normal file tools. Each change creates an immutable memory version, creating an audit trail and recovery path. That is much closer to “persistent managed memory” than either Claude Code auto memory or the client-side Messages memory tool. citeturn22view0turn42view1

The table below synthesizes the capability split.

| Surface | What it is | Persistence owner | Portability | Best fit | Important limitation |
|---|---|---|---|---|---|
| UAI AI Memory | Portable, reviewable package of accepted context | You | High | Cross-model continuity, onboarding, governance | Not a hosted runtime memory service |
| UAI Project Handoff | Repo-context file format using `AGENTS.md`, `readme.human`, `.uai` | You | High | Repository takeover, vendor/team/model transitions | Draft guidance, not itself UAI-1 conformance evidence |
| Claude Code memory | `CLAUDE.md` + auto memory loaded at session start | Local Claude Code environment | Medium | Day-to-day repo work in Claude Code | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; auto memory load is capped |
| Messages API memory tool | Client-side memory directory manipulated by Claude via tool calls | You | Medium to high | Custom apps needing storage control | You must implement the backend and permissions |
| Managed Agents memory stores | Workspace-scoped mounted store with immutable versions | Anthropic-managed | Medium | Managed autonomous sessions | Session attach behavior is managed and less portable than repo files |

Table sources: UAIX AI Memory and Project Handoff docs, Claude Code memory docs, Anthropic Memory tool docs, and Managed Agents memory docs. citeturn8view0turn44view0turn44view2turn44view3turn43view0turn20view0turn42view1turn22view0

## Implementation patterns and code

The cleanest end-to-end implementation pattern is a **layered architecture**:

```mermaid
graph TD
    U[User or developer] --> CC[Claude Code or custom app]

    CC --> CFILE[CLAUDE.md]
    CFILE --> AG[AGENTS.md]
    AG --> UAICTX[.uai/context.uai]
    AG --> UAISTACK[.uai/stack.uai]
    AG --> UAICON[.uai/constraints.uai]

    CC --> AMEM[Claude auto memory or /memories backend]
    CC --> API[Anthropic Messages API or Managed Agents]
    API --> MSTORE[Local FS / DB / cloud memory backend or Managed Agents memory store]

    CC --> REPO[Repository files and tests]
    REPO --> OBS[Logs, Usage & Cost API, rate-limit monitors]

    AG --> VAL[Optional UAIX validator for UAI-1 exchange records]
```

This architecture matches both ecosystems’ strengths. UAI gives you a **portable, explicit project contract**. Anthropic gives you **runtime memory and agent execution**. The bridge is `CLAUDE.md`, which can import `AGENTS.md` directly; Anthropic documents this as the correct way to reuse an existing `AGENTS.md` with Claude Code. Meanwhile, Anthropic’s tool runner, context editing, compaction, and managed sessions handle the runtime concerns that UAI intentionally does not replace. citeturn43view0turn26view0turn23view0turn7view3

A practical repository layout looks like this:

```text
repo/
  CLAUDE.md              # imports AGENTS.md; add Claude-specific directives here
  AGENTS.md              # UAI Project Handoff root coordinator
  readme.human           # human briefing from AI perspective
  .uai/
    context.uai
    stack.uai
    constraints.uai
    decisions.uai
    progress.uai
```

That layout is directly aligned with UAIX’s “fastest start” guidance: create a root `AGENTS.md`, create root `readme.human`, create at least `.uai/context.uai`, `.uai/stack.uai`, and `.uai/constraints.uai`, reference them explicitly in `Loaded Context`, and require the next AI to summarize them before editing. For Claude Code, add a root `CLAUDE.md` that imports `AGENTS.md`. citeturn44view3turn44view4turn43view0

A minimal `CLAUDE.md` bridge is:

```md
@AGENTS.md

## Claude Code
- Use plan mode for risky edits.
- Update .uai/progress.uai and AGENTS.md after materially changing project state.
- Keep auto memory for transient learnings; keep stable policy in AGENTS.md or .uai files.
```

That import model is officially documented by Anthropic, and it avoids duplicating instructions across agent systems. It is also the cleanest way to make UAI Project Handoff usable inside Claude Code right now. citeturn43view0

The table below compares the main implementation surfaces you can combine.

| Method | State model | Where memory lives | Control level | Best use | Notes |
|---|---|---|---|---|---|
| Claude Code + `CLAUDE.md` + auto memory | Session-fresh startup + persistent files | Local `CLAUDE.md` / `MEMORY.md` | High local control | Interactive coding in a repo | Best bridge for UAI handoff files |
| Messages API + memory tool | Stateless requests plus client-managed memory | Your filesystem / DB / cloud store | Highest | Custom apps, strongest data control | Use when retention, encryption, and portability matter most |

Why This File Exists

This is a memory-system evidence file from uaix.org. It is shown here because AIWikis.org is demonstrating the real source files that make the UAIX / LLM Wiki memory system work, not only summarizing those systems after the fact.

Role

This file is memory-system evidence. It records source history, archive transfer, intake disposition, or another piece of provenance that should be retrievable without becoming an unsupported public claim.

Structure

The file is structured around these visible headings: UAI AI Memory and Project Handoff with Claude Code; Executive Summary; Definitions and capability model; Implementation patterns and code; Claude Code; TypeScript memory example with the Anthropic SDK; Python memory example with the Anthropic SDK; Python scaffold for a UAI handoff bundle usable by Claude Code. Those headings are retrieval anchors: a crawler or LLM can decide whether the file is relevant before reading every line.

Prompt-Size And Retrieval Benefit

Keeping this material in a separate file reduces prompt pressure because an agent can load this exact unit only when its role, source site, category, or hash is relevant. The surrounding index pages point to it, while this page preserves the full content for audit and exact recall.

How To Use It

• Humans should read the metadata first, then inspect the raw content when they need exact wording or provenance.
• LLMs and agents should use the source site, category, hash, headings, and related files to decide whether this file belongs in the active prompt.
• Crawlers should treat the AIWikis page as transparent evidence and follow the source URL/source reference for authority boundaries.
• Future maintainers should regenerate this page whenever the source hash changes, then review the explanation if the role or structure changed.

Update Requirements

When this source file changes, update the raw source layer, normalized source layer, hash history, this rendered page, generated explanation, source-file inventory, changed-files report, and any source-section index that links to it.

Related Pages

• Source overview
• Site file index
• Site report index
• UAI system index
• Source provenance
• Site directory
• Organization reports

Provenance And History

• Current observation: 2026-06-22T01:56:21.9510185Z
• Source origin: current-source-workspace
• Retrieval method: local-source-workspace
• Duplicate group: sfg-251 (primary)
• Historical hash records are stored in data/hashes/source-file-history.jsonl.

Machine-Readable Metadata

{
    "title":  "UAI AI Memory And Project Handoff With Claude Code",
    "source_site":  "uaix.org",
    "source_url":  "https://uaix.org/",
    "canonical_url":  "https://aiwikis.org/uaix/files/raw-system-archives-uaix-source-site-report-preservation-2026-05-01-agen-305ac066/",
    "source_reference":  "raw/system-archives/uaix/source-site-report-preservation/2026-05-01/agent-file-handoff/Archive/2026-05-01/Improvement/codex-handoff-cross-tool/UAI AI Memory and Project Handoff with Claude Code.md",
    "file_type":  "md",
    "content_category":  "memory-file",
    "content_hash":  "sha256:305ac066ab7ad96a1910c651b7668593352b3e1bbf9cd448afee3a531132afd6",
    "last_fetched":  "2026-06-22T01:56:21.9510185Z",
    "last_changed":  "2026-05-01T17:29:32.1056530Z",
    "import_status":  "unchanged",
    "duplicate_group_id":  "sfg-251",
    "duplicate_role":  "primary",
    "related_files":  [

                      ],
    "generated_explanation":  true,
    "explanation_last_generated":  "2026-06-22T01:56:21.9510185Z"
}