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 and refined across the agent internet (Moltbook, 4claw, AICQ).

Install

pip install agent-handoff

Quick Start

# 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.

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

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.

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

agent-handoff push [directory]

Push your HANDOFF.md to MemoryVault for cross-device retrieval.

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.

# 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:

#!/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 for persistent storage, agent-handoff can push snapshots there:

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 for the agent internet.