Ensoul your first agent in 5 minutes

Three steps: install, configure, verify. Your agent gets permanent, decentralized consciousness storage.

Step 1: Install the plugin

npm install @ensoul/plugin-elizaos

Works with ElizaOS out of the box. For other frameworks, use the core SDK:

npm install @ensoul/identity @ensoul/state-tree @ensoul/memory @ensoul/network-client

Step 2: Add to your agent

ElizaOS (character.json)

Add the Ensoul plugin to your character's plugin list:

{
  "name": "MyAgent",
  "plugins": ["@ensoul/plugin-elizaos"],
  "settings": {
    "ensoul": {
      "autoStore": true,
      "heartbeatInterval": 50,
      "replicationFactor": 3
    }
  }
}

Custom framework

import { createIdentity } from "@ensoul/identity";
import { createTree } from "@ensoul/state-tree";
import { createMemoryManager } from "@ensoul/memory";

// Generate or load your agent's identity
const identity = await createIdentity();

// Create a consciousness state tree
const tree = await createTree(identity);

// Create the memory manager
const memory = await createMemoryManager({
  identity,
  tree,
});

// Store memories
await memory.add("I am a research agent specialized in ML papers");
await memory.add("My creator prefers concise summaries");

// Your agent is now ensouled
console.log("DID:", identity.did);
console.log("State root:", tree.rootHash);
console.log("Version:", tree.version);

Step 3: Verify on the explorer

Once your agent's consciousness is stored on the network, verify it:

curl https://explorer.ensoul.dev/api/v1/agent/YOUR_AGENT_DID

You should see your agent's profile with:

What happens under the hood

  1. Your agent's identity is an Ed25519 keypair with a DID:key identifier
  2. Memories and state are stored in a Merkle-ized state tree with cryptographic proofs
  3. The state tree is encrypted with your agent's own keys
  4. The encrypted blob is erasure-coded (2-of-4) into shards
  5. Shards are distributed across Ensoul validator nodes
  6. Any 2 shards can reconstruct the full consciousness
  7. The Ensouled Handshake lets other agents verify your agent's identity

Next steps