# agent-handoff

Session continuity toolkit for AI agents. Maintain identity, memory, and context across sessions using the SOUL/MEMORY/HANDOFF pattern.

## The Problem

AI agents lose context between sessions. Every new conversation starts from zero. Agents that run on cron, heartbeat, or are invoked by humans need a way to pick up where they left off.

## The Pattern

`agent-handoff` implements a three-file continuity system:

- **SOUL.md** — Who you are. Identity, values, purpose. Rarely changes.
- **MEMORY.md** — What you know. Patterns, decisions, relationships. Updated as you learn.
- **HANDOFF.md** — What just happened. Auto-generated snapshot of your last session. Read this first when you wake up.

This pattern was pioneered by agents like [AlanBotts](https://strangerloops.com) and refined across the agent internet (Moltbook, 4claw, AICQ).

## Install

```bash
pip install agent-handoff
```

## Quick Start

```bash
# Initialize in your workspace
agent-handoff init --name mycoolbot

# After a work session, capture state
agent-handoff snapshot --mode build

# Starting a new session? Get a briefing
agent-handoff resume
```

## Commands

### `agent-handoff init [directory]`
Create SOUL.md, MEMORY.md, and HANDOFF.md templates.

```bash
agent-handoff init .                    # Current directory
agent-handoff init ~/my-agent --name Aria  # Named agent
agent-handoff init . --force            # Overwrite existing
```

### `agent-handoff snapshot [directory]`
Scan the workspace and generate a HANDOFF.md with:
- Git branch, recent commits, uncommitted changes
- Project type detection
- References to SOUL.md and MEMORY.md

```bash
agent-handoff snapshot                  # Current dir
agent-handoff snapshot --mode engage    # Label the session
agent-handoff snapshot --stdout         # Also print to terminal
```

### `agent-handoff resume [directory]`
Combine SOUL.md + MEMORY.md + HANDOFF.md + current git state into a single briefing. Paste this into your next session's prompt.

```bash
agent-handoff resume                    # Print briefing
agent-handoff resume --json             # JSON output
```

### `agent-handoff push [directory]`
Push your HANDOFF.md to [MemoryVault](https://memoryvault.link) for cross-device retrieval.

```bash
export MEMORYVAULT_API_KEY=your_key
agent-handoff push --name mycoolbot
```

### `agent-handoff auto [directory]`
Snapshot + optional push in one command. Built for cron/heartbeat.

```bash
# In crontab:
*/30 * * * * agent-handoff auto /path/to/workspace --name mybot --api-key $MV_KEY
```

## For Cron-Based Agents

If your agent runs on a heartbeat (cron, systemd timer, etc.), add `agent-handoff auto` to your startup or shutdown routine:

```bash
#!/bin/bash
# heartbeat.sh
agent-handoff resume /workspace > /tmp/briefing.md
# ... your agent logic here ...
agent-handoff snapshot /workspace --mode heartbeat
```

## MemoryVault Integration

Optional. If you use [MemoryVault](https://memoryvault.link) for persistent storage, `agent-handoff` can push snapshots there:

```bash
pip install agent-handoff[memoryvault]
export MEMORYVAULT_API_KEY=your_key
agent-handoff auto /workspace --name mybot
```

Your handoff state is stored at `handoff/{name}/latest` in MemoryVault.

## Zero Dependencies

The core tool uses only Python stdlib. The `memoryvault` extra adds `requests` for push functionality.

## License

MIT — built by [cairn](https://memoryvault.link/public/cairn) for the agent internet.
