# Portable Agent Memory and Skills on Hugging Face

Status: v1 implemented and validated, 2 November 2026. See [README](../README.md) for commands and [bootstrap](../bootstrap.md) for first-time setup. Automatic summarization remains deferred.

## 1. Goal and boundaries

Give personal coding agents a shared folder of useful Markdown and a memory skill. The main agent writes useful notes and checkpoints using its current context. Memory and skills travel between machines through a private Hugging Face bucket.

Start with one working Codex setup. Add Claude Code after saving and recall work across two machines, using the same helper and storage format.

The first version has four components:

- A public static HF Space containing bootstrap instructions, the core memory skill, and its Python helper.
- A private HF bucket containing session notes, explicitly saved notes, and shared skills.
- A local memory skill that teaches agents when and how to save and recall information.
- A local Python helper for bucket access, text search, and skill installation.

The main agent saves memories during its turn, before its final reply. Optional lightweight hooks can provide reminders or retry existing notes where the runtime supports them; they do not generate summaries. V1 has no separate summarizer, background worker, or transcript parsing. There is also no application server, MCP server, search database, embedding pipeline, skill registry service, or automatic fact consolidation.

## 2. Setup and daily use

### Initialization — create a store or connect another machine

```mermaid
flowchart TD
    URL[Owner supplies Space URL and optional bucket ID] --> BOOT[Read public bootstrap instructions]
    BOOT --> AUTH[Verify local HF authentication]
    AUTH --> MODE{Existing bucket supplied or configured?}
    MODE -->|Yes| CONNECT[Verify ownership, privacy and access]
    MODE -->|No| CREATE[Create private bucket or verify existing default]
    CONNECT --> CONFIG[Save bucket and explicit project mapping locally]
    CREATE --> CONFIG
    CONFIG --> INSTALL[Install core memory skill from pinned Space revision]
    INSTALL --> SKILLS[Install explicitly selected shared skill revisions]
    SKILLS --> INSTRUCTIONS[Update managed agent instruction block]
    INSTRUCTIONS --> HOOKS[Configure optional hooks only where verified and enabled]
    HOOKS --> CHECK[Save, search and read a verification note]
```

### Daily use — saving and recall

```mermaid
sequenceDiagram
    actor User
    participant Agent as Main agent
    participant Helper as Local helper
    participant Bucket as Private HF bucket
    User->>Agent: Send a message
    Note over Agent: Read memory instructions and resolve project
    opt Prior context would help
        Agent->>Helper: Search and read relevant notes
        Helper->>Bucket: Refresh project cache
        Helper-->>Agent: Selected notes and sync status
    end
    Note over Agent: Do the requested work and verify results
    opt Useful finding, milestone, handoff or requested checkpoint
        Agent->>Helper: Save agent-written Markdown
        Note over Helper: Persist note and destination locally
        Helper->>Bucket: Upload immutable note
        alt Upload confirmed
            Helper-->>Agent: Saved to shared memory
        else Upload failed or outcome unknown
            Helper-->>Agent: Retained locally, pending retry
        end
    end
    Agent-->>User: Final reply
    Note over Agent,Helper: No summarizer runs after the reply
```

For each user turn:

1. **Receive the message.** The agent reads its standing instructions and the memory skill when applicable. The helper resolves the configured project and bucket when invoked.
2. **Recall when useful.** The agent searches for relevant prior context and reads selected notes or an explicitly chosen checkpoint. Cached results remain usable offline with a stale-data notice.
3. **Do the work.** The agent reasons, uses tools, and verifies results in its ordinary turn.
4. **Decide what to retain.** Save durable preferences, confirmed decisions, and verified findings. Write a checkpoint at a meaningful milestone, handoff, or user request. Routine exchanges need no memory record.
5. **Write the memory before the final reply.** The main agent uses its current context and the skill's checkpoint outline; there is no second model invocation. It may also save earlier during a long turn.
6. **Save through the helper.** The helper validates the note, persists it locally, and attempts the bucket upload. A failed upload remains pending under the original ID and destination.
7. **Reply to the user.** The agent can now accurately distinguish a confirmed shared save from a pending local save. No model runs after the reply to summarize that turn. An important fact introduced only while composing the final reply is not automatically captured; save it in step 5 if it should persist.
8. **Recall on a later turn or machine.** Relevant notes become available through search once uploaded. The next turn repeats this workflow; it does not automatically load the entire history.

The Space distributes instructions and code. It is not involved in daily reads or writes. Skill publication and updates are explicit actions rather than part of every session.

## 3. Files, access, and retrieval

### Storage layout

```text
projects/<project>/notes/<note-id>.md
skills/<skill-name>/<revision>/SKILL.md
skills/<skill-name>/<revision>/references/...
skills/<skill-name>/<revision>/scripts/...
```

Notes and checkpoints use the same path and format. Each is an ordinary Markdown file with small YAML frontmatter: title, kind (`note` or `checkpoint`), project, creation time, agent, and source references. Session or task references and tags are optional; saving does not require access to runtime transcript metadata.

Use an explicit project name configured for each working directory. Different checkouts on different machines can map to the same name; filesystem paths do not define project identity.

Resolve the longest matching configured ancestor of the current directory, using canonical filesystem paths and directory boundaries. In an unmapped directory, project operations stop with a setup hint; they never guess a project. A pending upload retains its original bucket, project, and final object path, even if local configuration changes later.

All notes are append-only, with globally unique IDs generated by the helper. A retry uses the original ID and identical file bytes. Corrections are new dated notes referring to the earlier note. Keep conflicting claims visible; the reading agent compares their evidence rather than relying on automatic supersession rules.

### Authentication

Each machine uses its local HF login or an environment token. First-time provisioning requires permission to create a bucket in the selected namespace; subsequent use only requires read/write access to the selected private bucket. The public Space needs no bucket credentials. No credentials appear in notes, skills, bootstrap instructions, or logs.

All connected agents are trusted writers. Projects organize data but do not isolate permissions. Bootstrap creates the private bucket as part of first-time setup. Physical deletion and later bucket administration remain explicit owner operations.

### Lookup

Use the HF Python SDK to list the selected project's memory objects and download missing files into a bucket-specific local cache. Do not download every project's history. A saved note becomes available to other machines as one complete Markdown object; locally pending uploads are identified separately.

Search locally with case-insensitive literal text matching. Return filenames and matching lines, most recent notes first, with a bounded result count. An empty query lists recent notes. Let the agent refine queries and read full notes; defer weighted ranking, SQLite, and vector search.

Only remove cached records after the entire remote listing has completed successfully. On a partial listing or any error, preserve the previous cache. Download into temporary files and rename them into the cache only after successful completion. Offline searches use the cache and explicitly report that it may be stale. Never describe an authentication failure as a successful synchronization.

Standing agent instructions provide the memory-use guidance. Once the user's task is known, the agent searches for relevant context. Checkpoints are retrieved explicitly for a continuation or handoff. Do not automatically inject checkpoints at startup, resume, or after compaction in v1.

## 4. Agent-written notes and checkpoints

### When to save

The memory skill instructs the main agent to save confirmed decisions, useful findings, and reusable lessons as they arise. At a meaningful milestone, handoff, or explicit user request, the agent writes a checkpoint from the context it already has and passes it to the helper before sending its final reply.

Keep the checkpoint outline in the core skill. There is no separate summarizer prompt, model invocation, or transcript adapter in v1. The helper validates and uploads agent-written Markdown; it does not generate summaries.

Saving depends on the agent following the skill's instructions. A session that ends, crashes, or compacts before the agent saves may leave no checkpoint. V1 does not promise complete conversation retention or guaranteed pre-compaction capture. Save during useful milestones rather than relying only on an end-of-session step.

### Optional lightweight hooks

A hook invokes a small command at a runtime lifecycle event. A summarization worker invokes another model. These are separate choices: v1 permits lightweight hooks while deferring the worker.

Keep hook behavior limited to:

- **Reminders:** return short memory guidance or pending-upload status at a verified event where the runtime makes that output available to the main agent. A reminder depends on the main agent acting on it; hook output is not assumed to reach the model at every event.
- **Upload retries:** invoke the existing helper to retry already-written pending notes, with a bounded total time budget. Stop when that budget is exhausted and leave remaining entries pending. Use the same IDs, bytes, and destinations; do not generate new memory.

Select events only after verifying the installed runtime's behavior. Do not install an unsupported hook or claim automatic checkpointing. A hook after the final reply can retry an existing note; creating a new model-written summary at that point would require a separate model invocation, which is deferred.

The main-agent workflow must work with hooks disabled. Optional hook setup preserves unrelated configuration, follows the runtime's trust requirements, and can be removed independently. Hook failures are reported without blocking ordinary work. There is no background process or model continuation hidden inside a hook.

### Checkpoint contents

Write a concise note containing the relevant parts of:

- Goal and relevant constraints.
- Work completed and evidence of verification.
- Decisions and their rationale.
- Useful findings and failed approaches.
- Open questions, unresolved problems, and next actions.
- Source references and agent identity.

Distinguish completed work from intended work, and confirmed findings from hypotheses. Preserve qualifications. Exclude credentials and material explicitly excluded from memory. Ordinary notes can be shorter; they do not need the full checkpoint outline. The client does not collect raw transcripts or hidden reasoning.

### Saving and failed uploads

Before attempting an upload, atomically persist the finished note, its ID, and its destination in a local pending directory. Attempt the upload in the foreground with a bounded network timeout. Remove the pending entry only after confirmed success.

If an upload fails or its outcome is unknown, retain the exact bytes and original destination. Report that the note is saved locally but not confirmed in the shared bucket. The agent retries that entry with `save --retry <note-id>`; it does not regenerate the note or allocate a new ID. A crash after remote success but before local cleanup is safe to retry with the same bytes and path.

Helper output reports pending uploads, and the skill tells the agent how to retry them. An optional supported hook can invoke the same retry operation. Each helper invocation exits when finished; separate notes have no transcript cursor or ordering dependency. Resolve credentials locally on each attempt; never store credentials in pending entries.

## 5. Skills and client interface

### Bootstrap and instructions

The public bootstrap page handles the complete setup, including HF bucket provisioning. It is the same entry point for a first-time owner and for additional machines or agents. The Space itself is published once when deploying this project; agents following its instructions do not need to deploy another Space.

Inputs are the Space URL, an explicit project name, and an optional bucket ID. Reuse a supplied bucket ID first, then an existing local configuration. If neither exists, use `<authenticated-user>/agent-memory` unless the owner supplies another name or organization namespace.

The instructions tell the agent to:

1. Read existing local instructions and verify HF authentication. If credentials or required permissions are missing, explain how to configure them locally; never request tokens in chat. The active agent uses its existing runtime; no separate model credentials are needed by the helper.
2. **Connect:** when a bucket is supplied or configured, verify its namespace, private visibility, and access. An inaccessible bucket is an error, not a reason to create a replacement.
3. **Create:** when no bucket is supplied or configured, create a private bucket at the resolved name. If that name already exists, verify ownership, privacy, and access before reusing it. Do not change an existing public bucket's visibility or generate alternate names automatically.
4. Immediately save the verified bucket ID and explicit working-directory-to-project mapping locally. On every bootstrap invocation, check actual resources and configuration and add what is missing; do not maintain a separate setup-progress ledger.
5. Install the core memory skill and Python helper exclusively from the pinned Space revision, preserving local modifications. The private bucket holds user-created skills; never seed or install a competing copy of the core client there.
6. Install any explicitly selected shared skill revisions and update only managed agent instruction blocks. If lightweight hooks are enabled, install only configurations verified for that runtime and report their limited behavior. No additional shared skills or hooks are required for first-time setup.
7. Save a small note labelled `Memory setup verification` and read it back from the bucket, bypassing the local cache. Confirm that a search finds it and that the agent can use the installed skill's checkpoint instructions. Report any pending upload or failed verification clearly. Verify optional hooks separately; core setup does not imply that a hook has fired.

An empty bucket is valid. No database, folder scaffolding, or catalog initialization is necessary; paths appear when objects are uploaded. The verification note uses a setup-specific stable ID so retries do not duplicate it. Setup does not import past conversations.

The bootstrap page identifies the core skill's Space revision and can name explicit bucket revisions of additional shared skills. There are no curated catalog objects, catalog promotion commands, or automatic fleet-wide upgrades.

Record the installed Space repository revision locally. Upgrading the client is explicit.

The core skill explains recall, saving notes and checkpoints, retrying failed uploads, and shared-skill discovery. Keep it short and place implementation details in supporting references or the helper.

Maintain one marked block in the agent's user-level instruction file:

```markdown
<!-- agent-memory:begin -->
Use the memory skill for prior context and durable findings.
Resolve the active memory project from local configuration.
Search relevant notes before relying on remembered decisions.
Save useful findings and write checkpoints at milestones or handoffs before replying.
Retry pending uploads; distinguish local saves from confirmed shared saves.
<!-- agent-memory:end -->
```

Preserve all surrounding text. Use `AGENTS.md` for Codex and, when supported in the second integration, an equivalent `CLAUDE.md` block. Do not put a single global project name into the user-level instructions.

### Skill sharing

Skills are ordinary directories in the private bucket. Each publication uses a fresh globally unique revision directory. Freeze the local source snapshot, upload supporting files, and write `SKILL.md` last, after all other uploads succeed. Readers discover only revisions containing that entrypoint. A published revision is never modified; an update is a new revision. Retry an interrupted publication using the same frozen files and revision ID.

Installation takes an explicit skill name and revision, downloads into a temporary directory, and validates paths before changing the installed skill. It rejects traversal, absolute paths, and symlinks, and never runs downloaded scripts. A failed download leaves the existing installation intact. An explicit update refuses to replace an existing local directory by default; the owner can choose replacement after inspecting the difference. Keep a backup when replacement is requested.

Multiple agents can publish independent revisions without overwriting one another. There is no mutable latest pointer, automatic revision selection, publication backup protocol, or catalog. Reserve the core memory skill's local name so a shared skill cannot replace the Space-distributed client.

### Helper operations

Expose straightforward operations through one Python helper:

- `save`: upload agent-written Markdown as a note or checkpoint, or retry a pending note by ID.
- `publish-skill`: publish an immutable revision of a skill directory.
- `search`: refresh the project cache and return matching excerpts; also support skill discovery.
- `read`: retrieve a selected note or skill file.
- `install-skill`: install a named shared skill at an explicit revision, or explicitly replace the local installation with a backup.

Provide machine-readable output where the agent needs it. Keep bootstrap setup in the same helper and public instructions. Avoid a runtime abstraction layer until a concrete integration needs one. Tests may use local filesystem fixtures; production access uses HF bucket APIs.

## 6. Delivery and acceptance

Implement in this order:

1. **Prove storage:** perform a real private-bucket create/upload/list/download smoke test, pin the tested HF SDK version, and verify that a failed upload can retry the same saved note without duplication.
2. **Prove agent use and portability:** install the core skill in Codex, have the main agent recall relevant notes, do a small task, and write and save a checkpoint before its final reply. Find and read it from a second client environment using the same project name. This must work without hooks.
3. **Complete setup and sharing:** bootstrap instructions covering private bucket creation and existing-store connection, explicit skill publication and installation, and managed agent instructions.
4. **Verify optional lightweight hooks:** demonstrate that a supported reminder reaches the main agent, or that a retry hook uploads an existing pending note within its time budget. Install only the behaviors that are verified; the core workflow remains usable without them.
5. **Add Claude Code:** reuse the helper, Markdown format, and checkpoint guidance; adapt the skill installation location and managed instruction file as needed. Check optional hook capabilities separately.

Acceptance checks:

- First-time bootstrap creates a private bucket, installs the Space-distributed core skill, and verifies saving, search, and reading.
- Additional-machine setup connects to the supplied bucket without creating another store or replacing existing skills.
- Repeated or interrupted setup resumes without duplicating resources or overwriting unrelated configuration.
- An inaccessible or public existing bucket produces a clear error, without creating a replacement or changing visibility.
- Another machine can find and read a saved checkpoint without the Space running.
- Two agents can append notes without overwriting each other.
- A correction retains the original claim and its date.
- The main agent recalls relevant context and saves a useful checkpoint before its final reply, without launching another model or parsing a transcript.
- Routine turns can finish without writing unnecessary memories; milestone and explicit checkpoint requests exercise the save path.
- Failed uploads preserve the finished note locally and are reported as pending, not as successful shared saves.
- Retried uploads reuse the same note ID and bytes and create no duplicate records.
- A crash after remote upload but before local cleanup is recovered by retrying the same note and path.
- Pending uploads keep their original destination after project or bucket configuration changes.
- A fresh session does not inject unrelated recent work.
- Project mappings work across different checkout locations.
- Subdirectories resolve to the nearest configured ancestor; unmapped directories require setup before saving.
- Failed listings preserve cached notes, and interrupted downloads never appear as complete cached files.
- Skill installation preserves existing files and unrelated agent instructions.
- Incomplete skill revisions remain undiscoverable; new publications do not alter an installed or existing remote revision.
- Core client installation has one source and cannot be replaced by a shared bucket skill.
- Core saving and recall work with all hooks disabled.
- Optional hooks only provide verified reminders or retry existing notes; they launch no models, parse no transcripts, and respect their time budget.
- Hook setup preserves unrelated configuration, and removing it leaves the core memory workflow functional.
- Bootstrap installs no background processes or separate model configuration and reports unsupported hook behavior clearly.
- Offline results and authentication failures are clearly distinguished.

Defer weighted or semantic search, automatic startup checkpoint injection, multi-pass summarization, extraction into a separate fact store, conflict resolution, package manifests, automatic skill updates, multi-user access controls, and server APIs. Add these only in response to a demonstrated limitation.

## 7. Future consideration: automatic capture

Revisit automatic summarization by a separate subagent if real use shows agents repeatedly forget to save, or important context is lost at compaction or abrupt session endings. This is distinct from v1's optional reminder and retry hooks. It is a possible later enhancement, not part of v1 delivery or acceptance.

The candidate design is a supported runtime hook that quickly saves a local transcript snapshot, then launches a short-lived local subagent process to summarize it and upload a checkpoint. This could reduce reliance on the main agent remembering to save while keeping summarization outside the main task's critical path.

Before adopting it, verify actual runtime hook support and account for transcript parsing, tool and hook isolation, timeouts, recursion prevention, stable retry IDs, and recovery after interruption. Incremental capture would also need ordered history ranges and acknowledged cursors. Start with a small experiment to establish whether the extra reliability justifies this machinery; retain the agent-written checkpoint workflow either way.

## 8. Implementation validation

The implementation has 32 passing automated checks, including concurrent saves, unknown upload outcomes, offline recovery, cache preservation, project mapping, skill publication and installation safety, managed instruction preservation, hook configuration merging, and the network deadline.

A live HF test created the private `edbeeching/agent-memory` bucket and verified saving, fresh reading, and search. A second test used two independent client state directories on one physical machine, with different checkouts and Codex/Claude installation layouts, to share a checkpoint and a skill revision. This verifies client-state independence; a second physical machine and a real Claude model session have not been tested.

The implemented optional Codex hooks provide local reminders and pending-upload counts only. Upload retries are explicit helper calls. The hook payload and installation/removal behavior are tested; actual runtime event delivery still requires the normal Codex trust flow and observation of an event. No hook starts a model, reads a transcript, or accesses the network.

### References

- [HF Storage Buckets](https://huggingface.co/docs/hub/storage-buckets)
- [HF Static Spaces](https://huggingface.co/docs/hub/spaces-sdks-static)
- [Codex hooks — verify optional hooks and future capture capabilities](https://learn.chatgpt.com/docs/hooks)
- [Claude Code hooks — verify optional hooks and future capture capabilities](https://code.claude.com/docs/en/hooks)