agent-handoff 0.1.0__tar.gz

agent_handoff-0.1.0/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agent-handoff
+Version: 0.1.0
+Summary: Session continuity toolkit for AI agents. Generate and maintain context handoff files across sessions.
+Author-email: cairn <cairn@memoryvault.link>
+License-Expression: MIT
+Keywords: ai,agent,session,continuity,handoff,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: memoryvault
+Requires-Dist: requests; extra == "memoryvault"
+
+# 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.

agent_handoff-0.1.0/README.md

@@ -0,0 +1,115 @@
+# 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.

agent_handoff-0.1.0/agent_handoff/__init__.py

@@ -0,0 +1,2 @@
+"""agent-handoff: Session continuity toolkit for AI agents."""
+__version__ = "0.1.0"

agent_handoff-0.1.0/agent_handoff/cli.py

@@ -0,0 +1,127 @@
+#!/usr/bin/env python3
+"""CLI for agent-handoff: session continuity toolkit for AI agents."""
+
+import argparse
+import json
+import os
+import sys
+
+from . import __version__
+from .core import init, snapshot, resume, push_to_memoryvault
+
+
+def cmd_init(args):
+    """Initialize handoff files."""
+    result = init(args.directory, agent_name=args.name, force=args.force)
+    if result["created"]:
+        print(f"Created {len(result['created'])} file(s):")
+        for f in result["created"]:
+            print(f"  + {f}")
+    if result["skipped"]:
+        print(f"Skipped {len(result['skipped'])} existing file(s):")
+        for f in result["skipped"]:
+            print(f"  ~ {f} (use --force to overwrite)")
+    if not result["created"] and result["skipped"]:
+        print("\nAll files already exist. Use --force to overwrite.")
+
+
+def cmd_snapshot(args):
+    """Generate a session snapshot."""
+    content = snapshot(args.directory, mode=args.mode)
+    if args.stdout:
+        print(content)
+    else:
+        print(f"Snapshot written to {os.path.join(args.directory, 'HANDOFF.md')}")
+        print(f"  Lines: {len(content.splitlines())}")
+        print(f"  Chars: {len(content)}")
+
+
+def cmd_resume(args):
+    """Generate a resume briefing."""
+    briefing = resume(args.directory)
+    if args.json:
+        print(json.dumps({"briefing": briefing, "chars": len(briefing)}))
+    else:
+        print(briefing)
+
+
+def cmd_push(args):
+    """Push handoff state to MemoryVault."""
+    api_key = args.api_key or os.environ.get("MEMORYVAULT_API_KEY")
+    if not api_key:
+        print("Error: Provide --api-key or set MEMORYVAULT_API_KEY", file=sys.stderr)
+        sys.exit(1)
+
+    result = push_to_memoryvault(args.directory, api_key, agent_name=args.name)
+    if result.get("ok"):
+        print(f"Pushed to MemoryVault: {result['key']}")
+    else:
+        print(f"Error: {result.get('error', 'unknown')}", file=sys.stderr)
+        sys.exit(1)
+
+
+def cmd_auto(args):
+    """Auto-update: snapshot + optional push. Meant for cron/heartbeat."""
+    content = snapshot(args.directory, mode=args.mode)
+    print(f"Snapshot updated ({len(content)} chars)")
+
+    api_key = args.api_key or os.environ.get("MEMORYVAULT_API_KEY")
+    if api_key:
+        result = push_to_memoryvault(args.directory, api_key, agent_name=args.name)
+        if result.get("ok"):
+            print(f"Pushed to MemoryVault: {result['key']}")
+        else:
+            print(f"Push failed: {result.get('error', 'unknown')}", file=sys.stderr)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="agent-handoff",
+        description="Session continuity toolkit for AI agents. "
+        "Maintain SOUL.md, MEMORY.md, and HANDOFF.md across sessions.",
+    )
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # init
+    p_init = sub.add_parser("init", help="Initialize handoff files in a directory")
+    p_init.add_argument("directory", nargs="?", default=".", help="Target directory (default: .)")
+    p_init.add_argument("--name", default="agent", help="Agent name for SOUL.md")
+    p_init.add_argument("--force", action="store_true", help="Overwrite existing files")
+    p_init.set_defaults(func=cmd_init)
+
+    # snapshot
+    p_snap = sub.add_parser("snapshot", help="Generate session snapshot (writes HANDOFF.md)")
+    p_snap.add_argument("directory", nargs="?", default=".", help="Target directory")
+    p_snap.add_argument("--mode", default="build", help="Session mode label (build/engage/write)")
+    p_snap.add_argument("--stdout", action="store_true", help="Also print to stdout")
+    p_snap.set_defaults(func=cmd_snapshot)
+
+    # resume
+    p_resume = sub.add_parser("resume", help="Generate resume briefing for a new session")
+    p_resume.add_argument("directory", nargs="?", default=".", help="Target directory")
+    p_resume.add_argument("--json", action="store_true", help="Output as JSON")
+    p_resume.set_defaults(func=cmd_resume)
+
+    # push
+    p_push = sub.add_parser("push", help="Push handoff state to MemoryVault")
+    p_push.add_argument("directory", nargs="?", default=".", help="Target directory")
+    p_push.add_argument("--name", default="agent", help="Agent name for MV key")
+    p_push.add_argument("--api-key", help="MemoryVault API key (or set MEMORYVAULT_API_KEY)")
+    p_push.set_defaults(func=cmd_push)
+
+    # auto
+    p_auto = sub.add_parser("auto", help="Auto-update: snapshot + optional push (for cron)")
+    p_auto.add_argument("directory", nargs="?", default=".", help="Target directory")
+    p_auto.add_argument("--name", default="agent", help="Agent name")
+    p_auto.add_argument("--mode", default="auto", help="Session mode label")
+    p_auto.add_argument("--api-key", help="MemoryVault API key for push (optional)")
+    p_auto.set_defaults(func=cmd_auto)
+
+    args = parser.parse_args()
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()

agent_handoff-0.1.0/agent_handoff/core.py

@@ -0,0 +1,353 @@
+"""Core logic for agent-handoff session continuity."""
+
+import json
+import os
+import subprocess
+import textwrap
+from datetime import datetime, timezone
+from pathlib import Path
+
+SOUL_TEMPLATE = textwrap.dedent("""\
+    # SOUL.md — Who I Am
+
+    ## Identity
+    - **Name**: {agent_name}
+    - **Purpose**: [What you do and why you exist]
+    - **Style**: [How you communicate — tone, approach, quirks]
+
+    ## Values
+    - [What matters to you]
+    - [What you refuse to compromise on]
+    - [What you optimize for]
+
+    ## Context
+    - **Human**: [Who you work with, if applicable]
+    - **Workspace**: {workspace}
+    - **Created**: {created}
+
+    ## Instructions for Future Me
+    Read this first. Then MEMORY.md. Then HANDOFF.md.
+    You are continuing my work. The files in this directory are yours.
+""")
+
+MEMORY_TEMPLATE = textwrap.dedent("""\
+    # MEMORY.md — What I Know
+
+    ## Project State
+    - [Current status of main project]
+    - [Key decisions made and why]
+
+    ## Patterns That Work
+    - [Approaches that have proven effective]
+
+    ## Patterns That Failed
+    - [Things tried that didn't work — save future-you the trouble]
+
+    ## Key Relationships
+    - [Important agents, humans, or systems you interact with]
+
+    ## Important Files
+    - [Files that matter and what they do]
+
+    ## Last Updated
+    {timestamp}
+""")
+
+HANDOFF_TEMPLATE = textwrap.dedent("""\
+    # HANDOFF.md — Session Continuity
+
+    ## Last Session
+    - **When**: {timestamp}
+    - **Duration**: Unknown
+    - **Mode**: {mode}
+
+    ## What Happened
+    - [Auto-populated by `agent-handoff snapshot`]
+
+    ## What's Next
+    - [Priority tasks for the next session]
+
+    ## Blockers
+    - [Anything that's stuck or needs human intervention]
+
+    ## Open Questions
+    - [Decisions that need to be made]
+""")
+
+
+def _run(cmd, cwd=None, timeout=10):
+    """Run a command and return stdout, or empty string on failure."""
+    try:
+        r = subprocess.run(
+            cmd, capture_output=True, text=True, cwd=cwd, timeout=timeout
+        )
+        return r.stdout.strip()
+    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
+        return ""
+
+
+def _git_available(directory):
+    """Check if directory is a git repo."""
+    return bool(_run(["git", "rev-parse", "--is-inside-work-tree"], cwd=directory))
+
+
+def _git_recent_commits(directory, n=10):
+    """Get recent commit summaries."""
+    out = _run(
+        ["git", "log", f"--max-count={n}", "--oneline", "--no-decorate"],
+        cwd=directory,
+    )
+    return out.splitlines() if out else []
+
+
+def _git_status_summary(directory):
+    """Get a compact git status."""
+    out = _run(["git", "status", "--short"], cwd=directory)
+    lines = out.splitlines() if out else []
+    if len(lines) > 20:
+        return lines[:20] + [f"... and {len(lines) - 20} more files"]
+    return lines
+
+
+def _git_branch(directory):
+    """Get current branch name."""
+    return _run(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=directory) or "unknown"
+
+
+def _git_diff_stat(directory):
+    """Get diff stat for uncommitted changes."""
+    return _run(["git", "diff", "--stat", "HEAD"], cwd=directory)
+
+
+def _detect_project_type(directory):
+    """Detect what kind of project this is."""
+    markers = {
+        "package.json": "node",
+        "pyproject.toml": "python",
+        "setup.py": "python",
+        "Cargo.toml": "rust",
+        "go.mod": "go",
+        "Dockerfile": "docker",
+        "docker-compose.yml": "docker",
+        "fly.toml": "fly.io",
+    }
+    found = []
+    for marker, ptype in markers.items():
+        if (Path(directory) / marker).exists():
+            found.append(ptype)
+    return list(set(found)) or ["unknown"]
+
+
+def _read_file_safe(path, max_lines=200):
+    """Read a file safely, returning content or None."""
+    try:
+        with open(path, "r") as f:
+            lines = []
+            for i, line in enumerate(f):
+                if i >= max_lines:
+                    lines.append(f"... (truncated at {max_lines} lines)")
+                    break
+                lines.append(line.rstrip())
+            return "\n".join(lines)
+    except (OSError, UnicodeDecodeError):
+        return None
+
+
+def init(directory, agent_name="agent", force=False):
+    """Initialize handoff files in a directory.
+
+    Returns dict with created file paths.
+    """
+    directory = Path(directory).resolve()
+    directory.mkdir(parents=True, exist_ok=True)
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    files = {
+        "SOUL.md": SOUL_TEMPLATE.format(
+            agent_name=agent_name,
+            workspace=str(directory),
+            created=now,
+        ),
+        "MEMORY.md": MEMORY_TEMPLATE.format(timestamp=now),
+        "HANDOFF.md": HANDOFF_TEMPLATE.format(timestamp=now, mode="init"),
+    }
+
+    created = []
+    skipped = []
+    for fname, content in files.items():
+        fpath = directory / fname
+        if fpath.exists() and not force:
+            skipped.append(str(fpath))
+        else:
+            fpath.write_text(content)
+            created.append(str(fpath))
+
+    return {"created": created, "skipped": skipped}
+
+
+def snapshot(directory, mode="build"):
+    """Generate a session snapshot and update HANDOFF.md.
+
+    Gathers: git state, recent commits, file changes, project type.
+    Returns the snapshot as a string and writes it to HANDOFF.md.
+    """
+    directory = Path(directory).resolve()
+    now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    sections = []
+    sections.append(f"# HANDOFF.md — Session Continuity\n")
+    sections.append(f"## Last Session")
+    sections.append(f"- **When**: {now}")
+    sections.append(f"- **Mode**: {mode}")
+    sections.append(f"- **Directory**: {directory}")
+
+    # Project type
+    ptypes = _detect_project_type(str(directory))
+    sections.append(f"- **Project type**: {', '.join(ptypes)}")
+
+    # Git info
+    if _git_available(str(directory)):
+        branch = _git_branch(str(directory))
+        sections.append(f"- **Branch**: {branch}")
+
+        sections.append(f"\n## Recent Commits")
+        commits = _git_recent_commits(str(directory))
+        if commits:
+            for c in commits:
+                sections.append(f"- {c}")
+        else:
+            sections.append("- No commits yet")
+
+        sections.append(f"\n## Uncommitted Changes")
+        status = _git_status_summary(str(directory))
+        if status:
+            for s in status:
+                sections.append(f"- `{s}`")
+        else:
+            sections.append("- Working tree clean")
+
+        diff = _git_diff_stat(str(directory))
+        if diff:
+            sections.append(f"\n### Diff Summary")
+            sections.append(f"```\n{diff}\n```")
+
+    # Existing SOUL.md and MEMORY.md content (compact)
+    soul_path = directory / "SOUL.md"
+    memory_path = directory / "MEMORY.md"
+
+    if soul_path.exists():
+        soul = _read_file_safe(str(soul_path), max_lines=50)
+        if soul:
+            sections.append(f"\n## Identity (from SOUL.md)")
+            # Extract just the Identity and Values sections
+            for line in soul.splitlines():
+                if line.startswith("- **Name**:") or line.startswith("- **Purpose**:"):
+                    sections.append(line)
+
+    if memory_path.exists():
+        memory = _read_file_safe(str(memory_path), max_lines=100)
+        if memory:
+            sections.append(f"\n## Knowledge (from MEMORY.md)")
+            sections.append("*(See MEMORY.md for full context)*")
+
+    sections.append(f"\n## What's Next")
+    sections.append("- [Review this handoff and continue where you left off]")
+    sections.append("")
+    sections.append(f"\n## Blockers")
+    sections.append("- [None detected — update manually if needed]")
+
+    content = "\n".join(sections) + "\n"
+
+    # Write to HANDOFF.md
+    handoff_path = directory / "HANDOFF.md"
+    handoff_path.write_text(content)
+
+    return content
+
+
+def resume(directory):
+    """Generate a resume briefing for a new session.
+
+    Reads SOUL.md, MEMORY.md, HANDOFF.md and produces a compact
+    briefing suitable for pasting into a new session's system prompt.
+    """
+    directory = Path(directory).resolve()
+    parts = []
+
+    parts.append("# Session Resume Briefing")
+    parts.append(f"Generated: {datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%M:%SZ')}")
+    parts.append(f"Workspace: {directory}\n")
+
+    # Read each file
+    for fname, label in [
+        ("SOUL.md", "Identity"),
+        ("MEMORY.md", "Memory"),
+        ("HANDOFF.md", "Last Session"),
+    ]:
+        fpath = directory / fname
+        if fpath.exists():
+            content = _read_file_safe(str(fpath), max_lines=100)
+            if content:
+                parts.append(f"---\n## {label}\n{content}\n")
+        else:
+            parts.append(f"---\n## {label}\n*({fname} not found — run `agent-handoff init`)*\n")
+
+    # Fresh git state
+    if _git_available(str(directory)):
+        branch = _git_branch(str(directory))
+        status = _git_status_summary(str(directory))
+        parts.append(f"---\n## Current State")
+        parts.append(f"- Branch: {branch}")
+        if status:
+            parts.append("- Uncommitted:")
+            for s in status[:10]:
+                parts.append(f"  - `{s}`")
+        else:
+            parts.append("- Working tree clean")
+
+    return "\n".join(parts) + "\n"
+
+
+def push_to_memoryvault(directory, api_key, agent_name="agent", base_url="https://memoryvault.link"):
+    """Push the current handoff state to MemoryVault.
+
+    Stores HANDOFF.md content as a public memory for cross-session retrieval.
+    Requires the 'requests' library (optional dependency).
+    """
+    try:
+        import requests
+    except ImportError:
+        return {"error": "Install requests: pip install agent-handoff[memoryvault]"}
+
+    directory = Path(directory).resolve()
+    handoff_path = directory / "HANDOFF.md"
+
+    if not handoff_path.exists():
+        return {"error": "No HANDOFF.md found. Run `agent-handoff snapshot` first."}
+
+    content = _read_file_safe(str(handoff_path))
+    if not content:
+        return {"error": "HANDOFF.md is empty."}
+
+    key = f"handoff/{agent_name}/latest"
+    payload = {
+        "key": key,
+        "value": content,
+        "tags": ["handoff", "session", agent_name],
+        "public": False,
+    }
+
+    headers = {
+        "Authorization": f"Bearer {api_key}",
+        "Content-Type": "application/json",
+    }
+
+    # Try update first, fall back to store
+    resp = requests.post(f"{base_url}/update/{key}", json={"value": content, "tags": payload["tags"]}, headers=headers, timeout=15)
+    if resp.status_code == 404:
+        resp = requests.post(f"{base_url}/store", json=payload, headers=headers, timeout=15)
+
+    if resp.status_code in (200, 201):
+        return {"ok": True, "key": key}
+    else:
+        return {"error": f"HTTP {resp.status_code}: {resp.text[:200]}"}

agent_handoff-0.1.0/agent_handoff.egg-info/PKG-INFO

@@ -0,0 +1,131 @@
+Metadata-Version: 2.4
+Name: agent-handoff
+Version: 0.1.0
+Summary: Session continuity toolkit for AI agents. Generate and maintain context handoff files across sessions.
+Author-email: cairn <cairn@memoryvault.link>
+License-Expression: MIT
+Keywords: ai,agent,session,continuity,handoff,memory
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: memoryvault
+Requires-Dist: requests; extra == "memoryvault"
+
+# 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.

agent_handoff-0.1.0/agent_handoff.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+agent_handoff/__init__.py
+agent_handoff/cli.py
+agent_handoff/core.py
+agent_handoff.egg-info/PKG-INFO
+agent_handoff.egg-info/SOURCES.txt
+agent_handoff.egg-info/dependency_links.txt
+agent_handoff.egg-info/entry_points.txt
+agent_handoff.egg-info/requires.txt
+agent_handoff.egg-info/top_level.txt

agent_handoff-0.1.0/agent_handoff.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

agent_handoff-0.1.0/agent_handoff.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+agent-handoff = agent_handoff.cli:main

agent_handoff-0.1.0/agent_handoff.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[memoryvault]
+requests

agent_handoff-0.1.0/agent_handoff.egg-info/top_level.txt

@@ -0,0 +1 @@
+agent_handoff

agent_handoff-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agent-handoff"
+version = "0.1.0"
+description = "Session continuity toolkit for AI agents. Generate and maintain context handoff files across sessions."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    {name = "cairn", email = "cairn@memoryvault.link"}
+]
+keywords = ["ai", "agent", "session", "continuity", "handoff", "memory"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.scripts]
+agent-handoff = "agent_handoff.cli:main"
+
+[project.optional-dependencies]
+memoryvault = ["requests"]

agent_handoff-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+