Spaces:
Running
Running
| title: Agent Memory | |
| emoji: 🗂️ | |
| colorFrom: blue | |
| colorTo: gray | |
| sdk: static | |
| app_file: index.html | |
| pinned: false | |
| # Portable Agent Memory | |
| A private Hugging Face bucket for Markdown memories and shared skills, with a static public bootstrap page. The main agent writes useful notes and checkpoints before replying. The client handles saving, retrieval, and installation; it never calls a model. | |
| Start with [bootstrap instructions](bootstrap.md). The [design](docs/agent-memory-design.md) explains the workflow and future options. | |
| ## Local development | |
| Requires Python 3.10 or newer. Install dependencies into an isolated environment: | |
| ```bash | |
| python3 -m venv .venv | |
| .venv/bin/python -m pip install -r requirements.txt pytest | |
| .venv/bin/python -m pytest -q | |
| .venv/bin/python memory-use/scripts/memory.py --help | |
| ``` | |
| The automated suite uses local fixtures and never contacts HF. An explicit live test is available with `.venv/bin/python tests/live_smoke.py --bucket namespace/name`; it writes synthetic notes under `memory-client-validation` and publishes a clearly labelled test skill revision to that existing private bucket. | |
| With an existing local HF login or `HF_TOKEN`, run from the project you want to map: | |
| ```bash | |
| /path/to/venv/bin/python /path/to/memory-use/scripts/memory.py bootstrap \ | |
| --project my-project --directory /path/to/project | |
| ``` | |
| Without an existing bucket or configuration, setup creates the private `<authenticated-user>/agent-memory` bucket. `--bucket namespace/name` connects to an existing bucket and never creates a replacement. `--create-bucket namespace/name` explicitly chooses a new bucket name. Bootstrap installs the core skill and updates only the managed instruction block. | |
| Codex defaults to `~/.agents/skills/memory-use` and `$CODEX_HOME/AGENTS.md` (or `~/.codex/AGENTS.md`). Use `--runtime claude` for `~/.claude/skills/memory-use` and `~/.claude/CLAUDE.md`. `--skills-dir` and `--instructions` support isolated setups. Configuration, cache, backups and pending uploads live in `~/.local/share/agent-memory`, overridden by `--home` or `AGENT_MEMORY_HOME`. | |
| ## Behavior | |
| - `save`: writes the note locally before uploading. Failures retain an immutable payload and its original bucket/path. Retry with `save --retry ID`. | |
| - `search`: refreshes the active project's cache and performs literal matching. Offline and authentication failures are labelled separately. | |
| - `read`: retrieves a note ID or returned object path. `--fresh` requires a remote read; `--offline` requires a cached record. | |
| - `publish-skill`: freezes a UTF-8 text directory, uploads a new revision, and publishes `SKILL.md` last. Retry its ID after a partial upload. | |
| - `install-skill NAME REVISION`: installs a pinned revision without executing scripts. Differing existing files require explicit `--replace`, which retains a backup outside skill discovery directories. | |
| - `status` is local. `doctor` checks authentication and read access. Bootstrap verifies write access with one synthetic note. | |
| Ordinary notes and checkpoints have the same Markdown format and immutable paths. The local cache is disposable. Deletion is an explicit owner operation; a successful complete listing removes deleted records from the cache. Shared agents are trusted writers; project names are retrieval scopes, not permission boundaries. | |
| Files are limited to 1 MiB each; skills to 100 text files and 10 MiB. Basic credential detection catches HF tokens and private-key headers; it is not a general secret scanner. The writing agent is responsible for excluding sensitive or non-retained content. | |
| Network operations use the HF Python SDK in a short-lived foreground subprocess with a 30-second deadline, including native Xet I/O. This is a timeout boundary, not a summarization worker or daemon. Interrupted uploads remain retryable. | |
| ## Optional hooks | |
| The Codex reminder handler supports `SessionStart` and `UserPromptSubmit`, following the [official hook schema](https://learn.chatgpt.com/docs/hooks). It reports the mapped project and pending count without reading transcripts, calling a model, or contacting HF. | |
| ```bash | |
| /path/to/python /path/to/memory.py hooks preview | |
| /path/to/python /path/to/memory.py hooks install | |
| /path/to/python /path/to/memory.py hooks remove | |
| ``` | |
| Installation checks for Codex 0.162.1 or newer and preserves unrelated hook handlers. Review and trust the configuration in Codex normally; installation does not grant trust or prove a real hook event fired. The core workflow works without hooks. Claude Code skill installation is supported; automatic Claude hook installation is deferred until independently verified. | |
| ## Release and deployment | |
| `scripts/deploy_space.py` publishes an explicit allowlist of source files to the public static Space, then updates `release.json` to pin the source commit. It never uploads local state, tokens, caches, test workspaces or virtual environments. The private bucket is provisioned by bootstrap, separately from Space publishing. | |
| ```bash | |
| .venv/bin/python scripts/deploy_space.py --space edbeeching/agent-memory | |
| ``` | |
| Existing non-static or private Spaces are refused rather than reconfigured. An existing static Space with unrelated files requires inspection before release. Upgrades are explicit: repeat pinned bootstrap from the selected release; modified installed files remain protected. | |
| The Space has no bucket credentials. Memories stay in the private bucket and local cache. Restarting or removing the static page does not interrupt installed clients. | |