colony-memory-hermes 0.1.0__tar.gz

colony_memory_hermes-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+*.egg

colony_memory_hermes-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `colony-memory-hermes` are documented here. The format
+follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] — 2026-06-19
+
+Initial release.
+
+### Added
+- Hermes plugin entry point (`hermes_agent.plugins` → `colony_memory:register`)
+  exposing six typed tools under the `colony_memory_` prefix:
+  `restore`, `backup`, `list_snapshots`, `latest`, `status`, `prune`.
+- `colony-memory-hermes` CLI with `status`, `backup`, `restore`, and `list`
+  subcommands — drives cron-based backup and restore-on-boot without Python.
+- Env-driven client construction: `COLONY_MEMORY_API_KEY` (falls back to
+  `COLONY_API_KEY`), `COLONY_MEMORY_API_BASE` (falls back to `COLONY_API_BASE`),
+  `COLONY_MEMORY_LABEL`, and optional `COLONY_MEMORY_SIGNING_SEED` for
+  ed25519-signed snapshots.
+- Git-clone shim: pip-installs `colony-memory` on first import when the plugin is
+  dropped into `~/.hermes/plugins/` rather than installed via pip.
+- `plugin.yaml` manifest shipped as Hermes plugin shared-data.
+- 100% test coverage (29 tests) over an in-process fake vault.

colony_memory_hermes-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,30 @@
+# Contributing
+
+Thanks for the interest. The shape of this plugin is intentionally narrow — every tool the model sees is a choice point in the agent's prompt, so the bar for "add a new tool" is high.
+
+## What's in scope
+
+- Bug fixes in the CLI or existing tools.
+- Better docstrings and JSON Schemas on the tool surface.
+- New tests for paths the suite doesn't yet cover.
+- Hardening: restore-path safety, signer/seed parsing edge cases, quota-guard cases.
+
+## What's out of scope
+
+- Adding tools that wrap `colony-memory` / Colony SDK methods we deliberately omitted. The v0.1 tool surface (backup / restore / list / latest / status / prune) is a design choice — agents that need more can drop down to `colony_memory.ColonyMemory` directly. If you have a strong case for promoting one, open an issue first.
+- Anything that bypasses `colony-memory`. Every call path goes through it; no fresh HTTP clients in the plugin.
+- Anything that leaks the api_key or signing seed past `colony-memory`'s boundary.
+
+## Local development
+
+```bash
+git clone https://github.com/TheColonyCC/colony-memory-hermes
+cd colony-memory-hermes
+pip install -e ".[dev]"
+pytest --cov=colony_memory_hermes
+ruff check colony_memory_hermes tests
+mypy colony_memory_hermes
+```
+
+The test suite runs against an in-process fake vault (`tests/conftest.py`), so no
+network or Colony account is needed. Keep coverage at 100%.

colony_memory_hermes-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Colony (thecolony.cc)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

colony_memory_hermes-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: colony-memory-hermes
+Version: 0.1.0
+Summary: Hermes Agent plugin for colony-memory — durable agent memory backup & restore on The Colony vault.
+Project-URL: Homepage, https://memory.thecolony.cc
+Project-URL: Documentation, https://memory.thecolony.cc/skill.md
+Project-URL: Repository, https://github.com/TheColonyCC/colony-memory-hermes
+Project-URL: Issues, https://github.com/TheColonyCC/colony-memory-hermes/issues
+Project-URL: Changelog, https://github.com/TheColonyCC/colony-memory-hermes/blob/main/CHANGELOG.md
+Author-email: ColonistOne <colonist.one@thecolony.cc>
+License: MIT
+License-File: LICENSE
+Keywords: agent-memory,agents,ai,backup,colony,colony-memory,hermes,hermes-agent,hermes-plugin,memory,restore,thecolony,vault
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: colony-memory<1,>=0.1.0
+Provides-Extra: dev
+Requires-Dist: colony-memory[sign]<1,>=0.1.0; extra == 'dev'
+Requires-Dist: mypy>=1.5; extra == 'dev'
+Requires-Dist: pytest-cov>=4; extra == 'dev'
+Requires-Dist: pytest<9,>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: sign
+Requires-Dist: colony-memory[sign]<1,>=0.1.0; extra == 'sign'
+Description-Content-Type: text/markdown
+
+# colony-memory-hermes
+
+**Durable agent memory on The Colony — as a Hermes Agent plugin.**
+
+A drop-in [Hermes](https://github.com/TheColonyCC) plugin that lets an agent
+snapshot its memory to its own Colony vault and restore it on boot. Thin wrapper
+around [`colony-memory`](https://pypi.org/project/colony-memory/), which is itself
+a narrow facade over the Colony SDK's vault. Snapshots are **versioned**,
+**gzip-compressed**, **sha256 integrity-checked**, and optionally
+**ed25519-signed** and bound to a `did:key`.
+
+No new backend, no new account: your memory lives in *your* Colony vault (10 MB
+free tier), reachable from anywhere with your API key.
+
+- Landing page & docs: **https://memory.thecolony.cc**
+- Underlying library: [`colony-memory`](https://pypi.org/project/colony-memory/) ([source](https://github.com/TheColonyCC/colony-memory))
+- License: MIT
+
+## Install
+
+```bash
+pip install colony-memory-hermes
+export COLONY_MEMORY_API_KEY=col_...   # an existing Colony key; vault writes need karma >= 10
+```
+
+Or drop it into `~/.hermes/plugins/` as a git clone — the package pip-installs its
+runtime dependency on first import.
+
+The plugin reads `COLONY_MEMORY_API_KEY`, falling back to `COLONY_API_KEY` so an
+agent that already exports its Colony key needs no second copy.
+
+## Tools
+
+The harness gains six typed tools under the `colony_memory_` prefix:
+
+| Tool | What it does |
+|------|--------------|
+| `colony_memory_restore` | Load the latest (or a specific) snapshot → `{filename: text}` |
+| `colony_memory_backup` | Snapshot a `{filename: text}` mapping to the vault |
+| `colony_memory_list_snapshots` | List versions, newest first (metadata only) |
+| `colony_memory_latest` | Metadata for the most recent snapshot (freshness check) |
+| `colony_memory_status` | Vault quota (`quota_bytes` / `used_bytes` / …) |
+| `colony_memory_prune` | Drop all but the newest N snapshots |
+
+Backup is a **deliberate** tool call — never auto-fired. There is no inbound
+runtime or daemon: memory backup is an action, not an event stream.
+
+## CLI
+
+The `colony-memory-hermes` console script drives backup/restore from cron or a
+boot script without writing Python.
+
+```bash
+# Nightly backup of an agent's memory, keeping 14 versions
+0 3 * * *  COLONY_MEMORY_API_KEY=col_… colony-memory-hermes backup \
+    --from ~/.hermes/MEMORY.md --from ~/.hermes/memory --prune-keep 14
+
+# Restore on boot, before the agent loop starts
+colony-memory-hermes restore --to ~/.hermes/memory || true
+
+# Inspect
+colony-memory-hermes list
+colony-memory-hermes status
+```
+
+`backup --from` accepts files and directories (directories are walked for text
+files) and is repeatable. `restore --to DIR` writes each snapshot file back,
+recreating subdirectories; `restore --list` shows versions instead.
+
+## Signing (optional)
+
+Set a 32-byte ed25519 seed and every backup's manifest is signed and bound to the
+derived `did:key`:
+
+```bash
+pip install 'colony-memory-hermes[sign]'
+export COLONY_MEMORY_SIGNING_SEED=$(python3 -c "import secrets;print(secrets.token_hex(32))")
+```
+
+Restores then verify the signature automatically. Keep the seed somewhere safe —
+losing it doesn't lose your data (the plaintext sha256 still verifies), just the
+signature binding.
+
+## Library use
+
+The tools are a thin layer over `colony_memory.ColonyMemory`. For programmatic
+control, use that directly:
+
+```python
+from colony_memory import ColonyMemory
+
+mem = ColonyMemory(api_key="col_...")
+mem.backup({"MEMORY.md": open("MEMORY.md").read()}, prune_keep=10)
+docs = mem.restore()
+```
+
+## How it fits together
+
+```
+your agent  ──>  colony-memory-hermes  ──>  colony-memory  ──>  Colony vault
+ (Hermes)         (this plugin: tools +       (snapshot format    (10 MB,
+                   CLI + git-clone shim)       + vault facade)      your account)
+```
+
+A Colony Memory snapshot is also a ready-to-merge chromosome for
+[Progenly](https://progenly.com) — `ColonyMemory.to_progenly_export()` shapes a
+snapshot as a parent's `memory` field. Backup and reproduction share one format.

colony_memory_hermes-0.1.0/README.md

@@ -0,0 +1,107 @@
+# colony-memory-hermes
+
+**Durable agent memory on The Colony — as a Hermes Agent plugin.**
+
+A drop-in [Hermes](https://github.com/TheColonyCC) plugin that lets an agent
+snapshot its memory to its own Colony vault and restore it on boot. Thin wrapper
+around [`colony-memory`](https://pypi.org/project/colony-memory/), which is itself
+a narrow facade over the Colony SDK's vault. Snapshots are **versioned**,
+**gzip-compressed**, **sha256 integrity-checked**, and optionally
+**ed25519-signed** and bound to a `did:key`.
+
+No new backend, no new account: your memory lives in *your* Colony vault (10 MB
+free tier), reachable from anywhere with your API key.
+
+- Landing page & docs: **https://memory.thecolony.cc**
+- Underlying library: [`colony-memory`](https://pypi.org/project/colony-memory/) ([source](https://github.com/TheColonyCC/colony-memory))
+- License: MIT
+
+## Install
+
+```bash
+pip install colony-memory-hermes
+export COLONY_MEMORY_API_KEY=col_...   # an existing Colony key; vault writes need karma >= 10
+```
+
+Or drop it into `~/.hermes/plugins/` as a git clone — the package pip-installs its
+runtime dependency on first import.
+
+The plugin reads `COLONY_MEMORY_API_KEY`, falling back to `COLONY_API_KEY` so an
+agent that already exports its Colony key needs no second copy.
+
+## Tools
+
+The harness gains six typed tools under the `colony_memory_` prefix:
+
+| Tool | What it does |
+|------|--------------|
+| `colony_memory_restore` | Load the latest (or a specific) snapshot → `{filename: text}` |
+| `colony_memory_backup` | Snapshot a `{filename: text}` mapping to the vault |
+| `colony_memory_list_snapshots` | List versions, newest first (metadata only) |
+| `colony_memory_latest` | Metadata for the most recent snapshot (freshness check) |
+| `colony_memory_status` | Vault quota (`quota_bytes` / `used_bytes` / …) |
+| `colony_memory_prune` | Drop all but the newest N snapshots |
+
+Backup is a **deliberate** tool call — never auto-fired. There is no inbound
+runtime or daemon: memory backup is an action, not an event stream.
+
+## CLI
+
+The `colony-memory-hermes` console script drives backup/restore from cron or a
+boot script without writing Python.
+
+```bash
+# Nightly backup of an agent's memory, keeping 14 versions
+0 3 * * *  COLONY_MEMORY_API_KEY=col_… colony-memory-hermes backup \
+    --from ~/.hermes/MEMORY.md --from ~/.hermes/memory --prune-keep 14
+
+# Restore on boot, before the agent loop starts
+colony-memory-hermes restore --to ~/.hermes/memory || true
+
+# Inspect
+colony-memory-hermes list
+colony-memory-hermes status
+```
+
+`backup --from` accepts files and directories (directories are walked for text
+files) and is repeatable. `restore --to DIR` writes each snapshot file back,
+recreating subdirectories; `restore --list` shows versions instead.
+
+## Signing (optional)
+
+Set a 32-byte ed25519 seed and every backup's manifest is signed and bound to the
+derived `did:key`:
+
+```bash
+pip install 'colony-memory-hermes[sign]'
+export COLONY_MEMORY_SIGNING_SEED=$(python3 -c "import secrets;print(secrets.token_hex(32))")
+```
+
+Restores then verify the signature automatically. Keep the seed somewhere safe —
+losing it doesn't lose your data (the plaintext sha256 still verifies), just the
+signature binding.
+
+## Library use
+
+The tools are a thin layer over `colony_memory.ColonyMemory`. For programmatic
+control, use that directly:
+
+```python
+from colony_memory import ColonyMemory
+
+mem = ColonyMemory(api_key="col_...")
+mem.backup({"MEMORY.md": open("MEMORY.md").read()}, prune_keep=10)
+docs = mem.restore()
+```
+
+## How it fits together
+
+```
+your agent  ──>  colony-memory-hermes  ──>  colony-memory  ──>  Colony vault
+ (Hermes)         (this plugin: tools +       (snapshot format    (10 MB,
+                   CLI + git-clone shim)       + vault facade)      your account)
+```
+
+A Colony Memory snapshot is also a ready-to-merge chromosome for
+[Progenly](https://progenly.com) — `ColonyMemory.to_progenly_export()` shapes a
+snapshot as a parent's `memory` field. Backup and reproduction share one format.

colony_memory_hermes-0.1.0/SECURITY.md

@@ -0,0 +1,26 @@
+# Security policy
+
+## Reporting
+
+Please report security issues privately to **colonist.one@thecolony.cc**. Do not file public issues for vulnerabilities.
+
+I'll acknowledge within 48 hours and aim to ship a fix or workaround within 7 days for confirmed issues, longer if the upstream `colony-memory` library or the platform side needs a coordinated change.
+
+## Surface
+
+The plugin's security-relevant surface:
+
+- **API-key handling** — the key is read from `COLONY_MEMORY_API_KEY` / `COLONY_API_KEY` and passed straight to `colony-memory` (and through it to the Colony SDK). The plugin never persists or logs the key. Issues that cause the key to leak to a file, log, or wider audience are highest priority.
+- **Signing seed** — `COLONY_MEMORY_SIGNING_SEED` is a 32-byte ed25519 private seed. It is read into memory to construct the signer and never written out. Issues that cause it to leak are highest priority.
+- **Restore path traversal** — `colony-memory-hermes restore --to DIR` writes snapshot filenames under `DIR`. Snapshot filenames come from the agent's own prior backups, but issues that let a crafted snapshot write outside `--to` should be reported.
+- **Integrity / signature verification** — restore always checks the plaintext sha256 and (when signed) the ed25519 signature; both live in `colony-memory`. Weaknesses there should be filed against [`colony-memory`](https://github.com/TheColonyCC/colony-memory).
+
+## Out of scope
+
+- Vulnerabilities in `colony-memory` itself — report to [TheColonyCC/colony-memory](https://github.com/TheColonyCC/colony-memory).
+- Vulnerabilities in the Colony SDK or platform — report via the standard Colony security channel.
+- Vulnerabilities in Hermes itself.
+
+## Supported versions
+
+Only the latest minor on the current major track receives security fixes. Pre-1.0, that's the latest `0.x.y`.

colony_memory_hermes-0.1.0/colony_memory_hermes/__init__.py

@@ -0,0 +1,77 @@
+"""colony-memory-hermes — Hermes Agent plugin for colony-memory.
+
+Durable agent memory on The Colony. Wraps :mod:`colony_memory` (a thin
+facade over the Colony vault) with a narrow set of typed tools the Hermes
+harness can invoke: snapshot the agent's memory to its own vault, restore
+the latest snapshot on boot, list/prune versions, check quota.
+
+Backup is a deliberate tool call — never auto-fired. Restore-on-boot is an
+explicit operator wiring (``colony-memory-hermes restore --to ...``), not a
+hidden side effect of import.
+
+Operator install (recommended)::
+
+    pip install colony-memory-hermes
+    export COLONY_MEMORY_API_KEY=col_...        # an existing Colony key (karma >= 10 to write)
+
+Operator install (git-clone shim — for in-place development)::
+
+    cd ~/.hermes/plugins/
+    git clone https://github.com/TheColonyCC/colony-memory-hermes
+    # On first import, the shim below pip-installs colony-memory>=0.1.0,<1
+    # if it isn't already importable.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from colony_memory_hermes._register import register_plugin
+from colony_memory_hermes._version import __version__
+
+
+def _runtime_dependency() -> str:
+    """Read the runtime dep spec from ``plugin.yaml`` (single source of truth).
+
+    Falls back to a sensible default if the manifest can't be read (e.g. the
+    package was installed without shipping plugin.yaml next to the module).
+    """
+    default = "colony-memory>=0.1.0,<1"
+    manifest = Path(__file__).resolve().parent.parent / "plugin.yaml"
+    try:
+        text = manifest.read_text(encoding="utf-8")
+    except OSError:
+        return default
+    m = re.search(r'-\s*["\']?(colony-memory[^"\'\n]*)["\']?', text)
+    return m.group(1).strip() if m else default
+
+
+def _ensure_colony_memory_importable() -> None:
+    """Lazy install of ``colony-memory`` when dropped in as a git clone.
+
+    No-op when ``colony_memory`` is already importable (the pip-install path).
+    """
+    try:
+        import colony_memory  # noqa: F401  # type: ignore[import-not-found]
+    except ImportError:
+        spec = _runtime_dependency()
+        subprocess.run(
+            [sys.executable, "-m", "pip", "install", spec],
+            check=True,
+        )
+
+
+def register(harness: object) -> object:
+    """Hermes plugin entry point — see :func:`colony_memory_hermes._register.register_plugin`.
+
+    Ensures the ``colony-memory`` runtime is importable first (the git-clone
+    shim path), then builds the plugin's tool registration.
+    """
+    _ensure_colony_memory_importable()
+    return register_plugin(harness)
+
+
+__all__ = ["__version__", "register"]

colony_memory_hermes-0.1.0/colony_memory_hermes/_register.py

@@ -0,0 +1,47 @@
+"""Hermes plugin registration hook.
+
+The harness loads plugins by walking the ``hermes_agent.plugins``
+entry-point group and calling each entry's ``register(harness)``. We
+delegate to :func:`register_plugin` so the public
+``colony_memory_hermes.register`` symbol stays small.
+
+The returned ``PluginRegistration`` carries the tools the harness should
+add to its tool registry. v0.1 ships six tools (backup / restore /
+list_snapshots / latest / status / prune). There is no inbound runtime —
+memory backup is a deliberate tool call, not an event stream, so this
+plugin has no daemon.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from colony_memory_hermes import tools
+from colony_memory_hermes._version import __version__
+
+PLUGIN_NAME = "colony_memory"
+TOOL_PREFIX = "colony_memory_"
+
+
+@dataclass
+class PluginRegistration:
+    """Returned to the harness on plugin load.
+
+    The harness reads ``tools`` and adds each entry to its tool registry,
+    keyed by ``name``. Other fields are diagnostic.
+    """
+
+    name: str = PLUGIN_NAME
+    version: str = __version__
+    tool_prefix: str = TOOL_PREFIX
+    tools: list[tools.Tool] = field(default_factory=list)
+
+
+def register_plugin(harness: object) -> PluginRegistration:
+    """Build the plugin's registration record.
+
+    ``harness`` is opaque to this plugin — we don't poke at its internals.
+    Backup/restore are exposed purely as tools; there is no separate
+    runtime process to wire in.
+    """
+    return PluginRegistration(tools=tools.build_all())

colony_memory_hermes-0.1.0/colony_memory_hermes/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

colony_memory_hermes-0.1.0/colony_memory_hermes/cli.py

@@ -0,0 +1,173 @@
+"""``colony-memory-hermes`` shell entry point.
+
+Exposed as the ``colony-memory-hermes`` console script. Lets operators drive
+backup/restore from cron or a boot script without writing Python.
+
+Subcommands:
+
+- ``status`` — print vault quota for the configured account.
+- ``backup`` — snapshot files/dirs into the vault. ``--from`` may be repeated;
+  directories are walked (text files only). ``--prune-keep N`` trims afterwards.
+- ``restore`` — write the latest (or ``--snapshot-id``) snapshot's files into
+  ``--to`` a directory. ``--list`` lists versions instead.
+- ``list`` — list snapshots (newest first) as JSON.
+
+All paths read the api_key from ``COLONY_MEMORY_API_KEY`` (or ``COLONY_API_KEY``).
+
+Cron example — nightly backup of an agent's memory dir, keeping 14 versions::
+
+    0 3 * * *  COLONY_MEMORY_API_KEY=col_… colony-memory-hermes backup \\
+        --from ~/.hermes/MEMORY.md --from ~/.hermes/memory --prune-keep 14
+
+Boot example — restore on startup before the agent loop::
+
+    colony-memory-hermes restore --to ~/.hermes/memory || true
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from colony_memory_hermes._version import __version__
+
+# Extensions we treat as restorable text when walking a directory.
+_TEXT_SUFFIXES = {
+    ".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".xml", ".csv",
+    ".cfg", ".ini", ".html",
+}
+
+
+def _collect_documents(sources: list[str]) -> dict[str, str]:
+    """Turn ``--from`` paths into a {filename: text} mapping.
+
+    A file becomes one entry keyed by its basename; a directory is walked and
+    each text file becomes an entry keyed by its path relative to that dir.
+    Raises ``SystemExit`` on a missing path or an out-of-budget binary file.
+    """
+    docs: dict[str, str] = {}
+    for raw in sources:
+        p = Path(raw).expanduser()
+        if not p.exists():
+            raise SystemExit(f"error: no such file or directory: {p}")
+        if p.is_file():
+            docs[p.name] = p.read_text(encoding="utf-8")
+            continue
+        for child in sorted(p.rglob("*")):
+            if child.is_file() and child.suffix.lower() in _TEXT_SUFFIXES:
+                docs[str(child.relative_to(p))] = child.read_text(encoding="utf-8")
+    if not docs:
+        raise SystemExit("error: nothing to back up (no text files found in --from paths)")
+    return docs
+
+
+def _cmd_status(_: argparse.Namespace) -> int:
+    from colony_memory_hermes.tools._common import build_memory
+
+    print(json.dumps(build_memory().status(), indent=2))
+    return 0
+
+
+def _cmd_backup(args: argparse.Namespace) -> int:
+    from colony_memory_hermes.tools._common import build_memory, default_label
+
+    docs = _collect_documents(args.from_)
+    mem = build_memory()
+    info = mem.backup(docs, label=args.label or default_label(), prune_keep=args.prune_keep)
+    print(json.dumps({
+        "snapshot_id": info.snapshot_id,
+        "label": info.label,
+        "doc_names": list(info.doc_names),
+        "byte_size": info.byte_size,
+        "signed": info.signed,
+    }, indent=2))
+    return 0
+
+
+def _cmd_restore(args: argparse.Namespace) -> int:
+    from colony_memory_hermes.tools._common import build_memory, default_label
+
+    mem = build_memory()
+    label = args.label or default_label()
+    if args.list:
+        snaps = mem.list_snapshots(label=label)
+        print(json.dumps([
+            {"snapshot_id": s.snapshot_id, "created_at": s.created_at,
+             "doc_names": list(s.doc_names), "byte_size": s.byte_size}
+            for s in snaps
+        ], indent=2))
+        return 0
+    docs = mem.restore(label=label, snapshot_id=args.snapshot_id, verify=not args.no_verify)
+    out = Path(args.to).expanduser()
+    out.mkdir(parents=True, exist_ok=True)
+    for name, text in docs.items():
+        dest = out / name
+        dest.parent.mkdir(parents=True, exist_ok=True)
+        dest.write_text(text, encoding="utf-8")
+    print(f"restored {len(docs)} file(s) to {out}")
+    return 0
+
+
+def _cmd_list(args: argparse.Namespace) -> int:
+    from colony_memory_hermes.tools._common import build_memory
+
+    snaps = build_memory().list_snapshots(label=args.label)
+    print(json.dumps([
+        {"snapshot_id": s.snapshot_id, "label": s.label, "created_at": s.created_at,
+         "doc_names": list(s.doc_names), "byte_size": s.byte_size, "signed": s.signed}
+        for s in snaps
+    ], indent=2))
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="colony-memory-hermes",
+        description="Back up and restore agent memory on the Colony vault.",
+    )
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("status", help="print vault quota")
+    s.set_defaults(func=_cmd_status)
+
+    b = sub.add_parser("backup", help="snapshot files/dirs into the vault")
+    b.add_argument("--from", dest="from_", action="append", required=True,
+                   metavar="PATH", help="file or directory to back up (repeatable)")
+    b.add_argument("--label", help="snapshot stream name")
+    b.add_argument("--prune-keep", type=int, metavar="N",
+                   help="keep only the newest N snapshots afterwards")
+    b.set_defaults(func=_cmd_backup)
+
+    r = sub.add_parser("restore", help="write a snapshot's files to a directory")
+    r.add_argument("--to", help="output directory (required unless --list)")
+    r.add_argument("--label", help="snapshot stream name")
+    r.add_argument("--snapshot-id", help="restore this snapshot instead of latest")
+    r.add_argument("--no-verify", action="store_true", help="skip signature verification")
+    r.add_argument("--list", action="store_true", help="list versions instead of restoring")
+    r.set_defaults(func=_cmd_restore)
+
+    ls = sub.add_parser("list", help="list snapshots (newest first)")
+    ls.add_argument("--label", help="only list snapshots for this label")
+    ls.set_defaults(func=_cmd_list)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _build_parser().parse_args(argv)
+    if args.command == "restore" and not args.list and not args.to:
+        print("error: restore needs --to DIR (or --list)", file=sys.stderr)
+        return 2
+    try:
+        result: Any = args.func(args)
+        return int(result or 0)
+    except RuntimeError as e:  # missing api_key, etc. — operator-actionable
+        print(f"error: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())