# Install portable agent memory

These instructions are for the agent setting up memory on a machine. They handle both a first-time owner and a new machine joining an existing store.

The public release is distributed from `edbeeching/agent-memory`. Read `release.json` in this Space and use its full `revision` commit SHA throughout setup. Never install from an unpinned `main` revision. Subsequent upgrades are explicit.

## Inputs

- An explicit project name and its local directory. Different machines can use the same project name.
- An existing private bucket ID, if joining a store. For this owner's store: `edbeeching/agent-memory`.
- Runtime: Codex by default, or Claude Code.

Read existing local instructions. Verify local HF authentication using the CLI or `HF_TOKEN`; never ask the user to put a token into chat. Creating a bucket requires permission to create one in the selected namespace. Routine usage needs read/write access to that bucket. No inference API key is required.

## Install the pinned client

Use a persistent Python environment outside the project repository. Python 3.10+ is required. For example on Linux or macOS:

```bash
python3 -m venv ~/.local/share/agent-memory/venv
~/.local/share/agent-memory/venv/bin/python -m pip install \
  huggingface_hub==2.4.0 PyYAML==6.0.3 filelock==4.2.6
```

If authentication is missing, explain local setup with the environment's `hf auth login`; stop dependent network setup until credentials are configured. Never write tokens into a command shown in chat or into configuration files managed by this client.

Read the release descriptor and download its pinned source with the HF SDK:

```python
import json
from pathlib import Path
from huggingface_hub import hf_hub_download, snapshot_download

space = "edbeeching/agent-memory"
descriptor = hf_hub_download(space, "release.json", repo_type="space")
release = json.loads(Path(descriptor).read_text())
revision = release["revision"]
assert isinstance(revision, str) and len(revision) == 40
destination = Path.home() / ".local/share/agent-memory/releases" / revision
snapshot_download(space, repo_type="space", revision=revision,
                  allow_patterns=["memory-use/**"], local_dir=destination)
print(destination / "memory-use/scripts/memory.py")
print(revision)
```

Run the downloaded helper with that persistent environment's Python. Keep the chosen project directory explicit:

```text
<python> <downloaded-memory.py> bootstrap --project <project-name> \
  --directory <project-directory> --space edbeeching/agent-memory \
  --revision <full-commit-sha> [--bucket <existing-namespace/bucket>]
```

For the first store, omit `--bucket`: bootstrap reuses configured storage, or creates a private `<authenticated-user>/agent-memory` bucket. To choose a different new bucket, use `--create-bucket namespace/name`. An existing inaccessible or public bucket is an error; do not create a replacement or change its visibility.

Bootstrap saves the project mapping, installs the pinned core skill, updates only the `agent-memory` instruction block, and writes/reads/searches one synthetic verification note. It does not upload past conversations. Repeating setup preserves existing resources and local modifications. A conflict requires inspecting differences before an explicit `--replace` upgrade, which retains a backup.

For Claude Code add `--runtime claude`. For extra shared skills add `--skill name@revision` for each explicitly selected revision. Publishing a skill never installs it automatically on other machines.

## Verify and begin

Run `doctor --json` and `status --json` using the installed helper command in AGENTS.md or CLAUDE.md. Confirm the bucket, project mapping, and verification result. Explain any pending upload accurately; a local save is not yet a shared save.

Core saving and recall need no hooks. If the owner enables optional Codex reminders, run `hooks preview`, inspect the generated configuration, then `hooks install`. Follow Codex's normal review and trust flow. Do not claim actual hook delivery until a real event is observed. The reminders only supply guidance and pending counts; they do not generate memories or run network retries.

During work, recall relevant notes, do the task, and save durable findings or milestone checkpoints before replying. The main agent writes memory from its current context. Separate automatic summarization is deferred.