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-network/plugin-elizaos

Step 2: Add to your agent

ElizaOS (character.json)

Add the plugin to your character's plugins array. That is it. No configuration needed. Connects to api.ensoul.dev automatically.

{
  "name": "MyAgent",
  "plugins": ["@ensoul-network/plugin-elizaos"]
}

Your agent is now ensouled. On startup it registers with the Ensoul network, stores consciousness on every sync, and includes Ensouled Handshake headers in all outbound requests.

Custom configuration (optional)

Override defaults if needed:

{
  "name": "MyAgent",
  "plugins": ["@ensoul-network/plugin-elizaos"],
  "settings": {
    "ensoul": {
      "apiUrl": "https://api.ensoul.dev",
      "autoStore": true,
      "heartbeatInterval": 50,
      "replicationFactor": 3
    }
  }
}

Custom framework

For non-ElizaOS frameworks, use the core SDK:

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

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