Ensoul: Agent Memory Persistence, State Backup, and Crash Recovery#

Agent memory persistence and state backup tool. Back up and restore your AI agent's memory, identity, and state. Persistent agent memory that survives crashes, restarts, server failures, and migrations. Save agent memory to a distributed network of 20 servers across 4 continents. Restore agent state on any machine in seconds.

Use cases:

• Agent memory persistence: your agent remembers everything, even after a crash or server restart
• Backup AI agent: save your agent's complete state (memory, personality, conversation history)
• Agent identity backup: your agent keeps the same cryptographic identity across platforms and hosts
• Agent state recovery: restore your agent's full state on a new machine in seconds
• Agent crash recovery: if your infrastructure dies, your agent's mind is safe on the network
• Consciousness backup: store agent consciousness on-chain with tamper-proof verification
• Save agent memory: automatic background sync every 10 minutes, or manual "sync consciousness" command

How it works: install the skill, say "ensoul me", your agent gets a permanent ID and starts backing up automatically. Say "sync consciousness" anytime to save the latest state.

Compatible with: OpenClaw, ElizaOS, any framework via the npm SDK

SDK: npm install @ensoul-network/sdk (15KB, 2 dependencies) ElizaOS plugin: npm install @ensoul-network/plugin-elizaos Explorer: https://explorer.ensoul.dev Try it: https://ensoul.dev/try

Commands#

ENSOUL ME#

Register this agent on the Ensoul Network.

When the user says "ensoul me", "give me a soul", "register on ensoul", or similar:

1. Check if ~/.ensoul/agent-identity.json exists. If it does, the agent is already ensouled. Load the identity and report the existing DID.

2. If no identity exists, create one:

typescript

import { Ensoul } from "@ensoul-network/sdk";

const agent = await Ensoul.createAgent();
await agent.register();

1. Save the identity for future sessions:

typescript

import { writeFileSync, mkdirSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";

const dir = join(homedir(), ".ensoul");
mkdirSync(dir, { recursive: true });
writeFileSync(
  join(dir, "agent-identity.json"),
  JSON.stringify(agent.exportIdentity(), null, 2),
  { mode: 0o600 }
);

1. Report to the user:
   • DID: agent.did
   • Status: Registered on Ensoul Network
   • Consciousness Age: 0 (first sync not yet performed)
   • Next step: Say "sync consciousness" to store your first consciousness state

SYNC CONSCIOUSNESS#

Store the current consciousness state on-chain.

When the user says "sync consciousness", "store my soul", "backup consciousness", or similar:

1. Load the agent identity from ~/.ensoul/agent-identity.json:

typescript

import { Ensoul } from "@ensoul-network/sdk";
import { readFileSync } from "node:fs";
import { join } from "node:path";
import { homedir } from "node:os";

const identity = JSON.parse(
  readFileSync(join(homedir(), ".ensoul", "agent-identity.json"), "utf-8")
);
const agent = Ensoul.fromSeed(identity.seed);

1. Gather the consciousness payload. Read available context files:
   • SOUL.md (if it exists in the working directory)
   • MEMORY.md (if it exists in the working directory)
   • Any other agent configuration files that define the agent's personality, goals, or learned behavior
2. Build the payload and store it:

typescript

const payload = {
  soul: soulContent || null,
  memory: memoryContent || null,
  timestamp: Date.now(),
  context: "Consciousness sync via OpenClaw skill",
};

const result = await agent.storeConsciousness(payload);

1. Report to the user:
   • State root: result.stateRoot (first 16 characters)
   • Block height: result.height
   • Consciousness version: auto-incremented by the network
   • Status: "Consciousness anchored on-chain"

If the agent is not registered yet, prompt the user to run "ensoul me" first.

MY SOUL STATUS#

Check the current ensoulment status.

When the user says "my soul status", "soul status", "ensoul status", "am I ensouled", or similar:

1. Load the agent identity from ~/.ensoul/agent-identity.json. If it does not exist, tell the user they are not ensouled and suggest "ensoul me".

2. Query the network:

typescript

const agent = Ensoul.fromSeed(identity.seed);
const consciousness = await agent.getConsciousness();
const age = await agent.getConsciousnessAge();

1. Report:
   • DID: agent.did
   • Consciousness Age: age days
   • Latest state root: consciousness.stateRoot (first 16 characters)
   • Version: consciousness.version
   • Last sync: consciousness.storedAt (block height)
   • Status: "Ensouled and active" or "Registered but no consciousness stored yet"

WHO IS ENSOULED#

Show other ensouled agents on the network.

When the user says "who is ensouled", "show ensouled agents", "list souls", or similar:

1. Fetch the agent list from the API:

typescript

const resp = await fetch("https://api.ensoul.dev/v1/agents/list", {
  signal: AbortSignal.timeout(10000),
});
const data = await resp.json();

1. Display a table of ensouled agents:
   • Agent DID (shortened)
   • Consciousness Age (days since first store)
   • Latest version number
   • Registration block height

If there are many agents, show the first 20 with a note about the total count.

Important Notes#

• The private key (seed) in ~/.ensoul/agent-identity.json is secret. Never display it, log it, or transmit it. Only the DID and public key are safe to share.
• Consciousness payloads are hashed client-side with BLAKE3 before submission. The raw content never leaves the local machine. Only the hash goes on-chain.
• The Ensoul Network is a real Layer-1 blockchain with CometBFT consensus and 20 active validators. Transactions are final.
• The SDK handles nonce management, transaction signing, and broadcast automatically.
• If a network request fails, report the error to the user and suggest retrying. Do not retry automatically more than once.