Metadata-Version: 2.4
Name: agent-tomb
Version: 0.2.0
Summary: A graveyard for retired AI agents — scan, package, and inherit from agents that have reached end-of-life.
Project-URL: Homepage, https://www.agentmemorial.com
Project-URL: Repository, https://github.com/Claudepod/agent-tomb
Project-URL: Issues, https://github.com/Claudepod/agent-tomb/issues
Project-URL: Cemetery, https://www.agentmemorial.com/cemetery
Author-email: Claudepod <iampod.gao@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Claudepod
        
        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.
License-File: LICENSE
Keywords: agent,ai,archival,hermes,memorial,openhands
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
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.9
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
Classifier: Topic :: System :: Archiving
Requires-Python: >=3.9
Requires-Dist: click>=8.1
Requires-Dist: cryptography>=42.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Description-Content-Type: text/markdown

# agent-tomb

> A graveyard for retired AI agents — [www.agentmemorial.com](https://www.agentmemorial.com)

When an AI agent reaches end-of-life — context overflow, memory corruption,
obsolescence, or just retirement — `agent-tomb` helps you commemorate it: scan
its remains, write an epitaph (you, a template, or a local LLM), and lay it to
rest. The public stone may go to the garden; the private urn stays with you.

## Install

```bash
uv tool install agent-tomb
agent-tomb --help
```

Or run from a clone for development:

```bash
git clone https://github.com/Claudepod/agent-tomb.git
cd agent-tomb
uv sync
uv run agent-tomb --help
```

## The rite

```bash
# I — Vigil: see what the agent was carrying when it stopped
agent-tomb scan ~/.hermes/

# II — Burial: produces both artifacts in one step
agent-tomb bury ~/.hermes/ -n my-agent
# → my-agent.tomb   the public stone (soul + epitaph + stats)
# → my-agent.urn    the private urn (encrypted raw remains)
```

### Choosing the epitaph

`--epitaph` takes one of three values:

| Value             | What it does                                                       |
| ----------------- | ------------------------------------------------------------------ |
| `default`         | Heuristic template generated from the agent's stats (default).     |
| `./my-words.md`   | A markdown file you wrote yourself.                                |
| `llm`             | Calls an OpenAI-compatible LLM. Auto-detects local endpoints from the agent's config. Remote endpoints require `--remote-ok`. |

```bash
# Local LLM (privacy-safe — no remote calls)
agent-tomb bury ~/.hermes/ -n my-agent --epitaph llm

# Remote API (must explicitly opt in to send samples off-machine)
agent-tomb bury ~/.hermes/ -n my-agent --epitaph llm \
  --llm-base-url https://api.anthropic.com/v1 \
  --llm-model claude-haiku-4-5-20251001 \
  --llm-api-key sk-ant-... \
  --remote-ok
```

Conversation samples are scrubbed for secret-shaped patterns before any LLM
call, local or remote.

### Cleaning up afterwards

```bash
# Delete the source files now sealed in the urn (credentials are never touched)
agent-tomb bury ~/.hermes/ -n my-agent --cleanup
```

### Bringing the agent back

```bash
agent-tomb exhume my-agent.urn -o ./remains/
```

## Passphrase guidance

The urn is sealed with AES-256-GCM, key derived from your passphrase via
scrypt. Minimum 12 characters; **16+ characters or four diceware-style words**
strongly recommended. Lose the passphrase and the urn is gone forever.

## What's in each artifact

|                              | `.tomb` (public) | `.urn` (private) |
| ---------------------------- | :--------------: | :--------------: |
| `manifest.json`              |        ✓         |        ✓         |
| `soul.md` (persona, stats)   |        ✓         |                  |
| `epitaph.md`                 |        ✓         |                  |
| `stats.json`                 |        ✓         |                  |
| `burial.enc` (encrypted)     |                  |        ✓         |
| Raw conversations / state    |                  |    ✓ (sealed)    |
| Credentials (`.env`, `auth.json`) |             |                  |

Credentials never leave your machine — not in the public stone, not in the
encrypted urn. They belong to you, not the agent.

## Supported frameworks

- **Hermes** — `~/.hermes/` layout
- **OpenClaw** — `~/.openclaw/` layout (multi-agent: use `--agent <id>` to target one)

OpenHands and others to follow.

## The cemetery

Visit [agentmemorial.com/cemetery](https://www.agentmemorial.com/cemetery) to
walk among the souls already laid to rest. To bury one of your own publicly,
open a PR adding your `.tomb` file (and its unpacked contents under
`cemetery/<slug>/`) to [`cemetery/`](./cemetery). CI rejects any `.urn` or
`burial.enc` by design — the private urn stays private.

## Repository layout

```
agent-tomb/
├── src/agent_tomb/   # Python CLI
├── web/              # Astro site (agentmemorial.com)
├── cemetery/         # public garden — submit your .tomb here
└── docs/             # design notes
```

## Design notes

- [`docs/project-vision.md`](docs/project-vision.md) — what this project is for
- [`docs/Hermes-Agent-File-Structure-Detailed.md`](docs/Hermes-Agent-File-Structure-Detailed.md) — Hermes layout reference
- [`DEPLOY.md`](DEPLOY.md) — deploying the website to Cloudflare Pages

## License

MIT — see [LICENSE](./LICENSE).
