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.
