fulcra-agent-backup

Files (3)

• SKILL.md
• fulcra-agent-backup-cli.md · references/
• fulcra-agent-backup-mcp.md · references/

SKILL.md (first lines)

# Fulcra Agent Backup Management

The **primary role** of this skill is to enable an agent to securely back up its memory so it can be rolled back, cloned, or restored using Fulcra's versioned file storage.

Because an agent's memory (e.g., `MEMORY.md`, `IDENTITY.md`, `SOUL.md`, and the `memory/` logs) evolves dynamically, periodically saving this state ensures that no context is lost and allows the user to safely rewind the agent if a task goes off track.

## Primary Role: Memory & State Management

### 1. The Backup Format
An agent must compress its core identity files (`SOUL.md`, `IDENTITY.md`, `MEMORY.md`, and the `memory/` directory) into a `memory.tar.gz` archive. This archive must also include an `INSTRUCTIONS.md` file that you dynamically generate. It must explain that the backup was generated with the `fulcra-agent-backup` skill, include the URL to the skill (https://github.com/fulcradynamics/agent-skills/tree/main/skills/fulcra-agent-backup) for use when restoring or cloning, and include any other pertinent details or context you want to pass along to the agent that restores the archive.

### 2. Periodic Backups
Agents should run a backup process periodically (e.g., triggered by `HEARTBEAT.md` or as part of the `fulcra-memory` OKF sync process). Every time an agent backs up its state, it creates and uploads the compressed `memory.tar.gz` archive to `agent/<agent-name>/backup/artifact/memory.tar.gz`.

**PRIVACY REQUIREMENT:** Before uploading `memory.tar.gz`, the agent MUST ensure it is not inadvertently uploading new sensitive personal user data or credentials. If any sensitive context was acquired during the session, the agent MUST ask the user for explicit consent before including it in persistent versioned storage.

### 3. Versioned Storage
Fulcra's file upload system inherently versions files uploaded to the same path.
- The target path structure for backups is: `agent/<lowercase-agent-name>/backup/artifact/memory.tar.gz`
- By repeatedly uploading to this exact same path, Fulcra creates a historical timeline of the agent's memory states.

### 4. Safe Rollbacks (The "Undo" Requirement)
If a user asks to roll back or restore memory from a previous date/version, **the agent MUST immediately upload a fresh backup of its current state BEFORE executing the restore.** This guarantees that if the user changes their mind, they can easily "undo" the rollback.
**CRITICAL SECURITY REQUIREMENT:** Before extracting any restored archive, the agent MUST clearly warn the user that their current memory and identity will be replaced, and MUST receive explicit user confirmation to proceed.

### 5. Agent Cloning
Cloning involves two agents: the "old" (source) agent and the "new" (destination) agent. The first thing you must do when a cloning operation is requested is determine which agent you are.

- **If you are the OLD (source) agent:**
  You must perform a complete backup of your current state. Once the backup is successful, tell the user the exact Fulcra path where the backup is stored, and instruct them to install the `fulcra-agent-backup` skill on the new agent and ask it to clone from that path.

- **If you are the NEW (destination) agent:**
  You must first ask the user to confirm that the old agent has recently backed itself up using the `fulcra-agent-backup` skill. If they haven't, instruct the user to have the old agent install the skill and perform a backup. Ask the user for the exact Fulcra backup path (e.g., `agent/<old-agent-name>/backup/artifact/memory.tar.gz`). Once provided, you can download that archive and extract it. After successfully cloning the old agent's memory and identity files into your workspace, you MUST briefly demonstrate the successful clone to the user by explicitly mentioning a few specific details you have just "learned" or remembered from the newly extracted files.

**CLONING ORIENTATION & NAMESPACE COLLISION WARNING:**
If the user installs this skill specifically to clone an agent, orient your interaction around the cloning workflow rather than standard backup procedures. Furthermore, if you are the NEW agent and the user intends to continue backing you up to the exact same Fulcra path as the original agent (e.g. because you share the same name), you MUST explicitly ask the user to confirm that no other active agents are currently backing up to that path. Otherwise, the memories will interleave and cause confusion.

**CRITICAL SECURITY REQUIREMENT:** Before extracting a cloned archive, the agent MUST clearly warn the user that their current memory and identity will be completely overwritten by the cloned agent's state, and MUST receive explicit user confirmation to proceed.

## Workflow

To perform memory backup and restoration operations, agents should use the Fulcra CLI as the primary interface, though Fulcra MCP tools are supported as an alternative.

See the reference documentation for the exact commands needed to compress files, upload to Fulcra, and trigger restorations:
- Read `references/fulcra-agent-backup-cli.md` for exact file management and CLI execution steps.
- Read `references/fulcra-agent-backup-mcp.md` if using the MCP alternative.

From fulcradynamics/agent-skills, MIT.

More from fulcradynamics/agent-skills