Persistent Eliza Characters

There is no published, pre-built @sovseal/adapter-eliza package today. This cookbook shows the working pattern for wiring @sovseal/sdk directly into an ElizaOS character — a small plugin you write once and reuse, not a one-line install. See ElizaOS integration reference for the full plugin shape.

This cookbook gives your ElizaOS characters persistent, local-first memory across restarts, using @sovseal/sdk’s store()/recall() directly — no cloud database, no plaintext leaving the device.

Zero-Knowledge Identity Isolation

Local-first by default: store()/recall() talk to the local ONEBRAIN engine over IPC and need no API key or network call at all.
0 RTT agent response: Because recall resolves against the local LanceDB index, the agent doesn’t suffer network latency mid-conversation.
Optional encrypted replication: If you also want cross-device state sync, @sovseal/sdk’s snapshot()/restore() encrypt client-side with AES-256-GCM before anything reaches the edge gateway — see Replication & Sync.

1. Install the SDK

pnpm install @sovseal/sdk

2. Write the memory plugin

ElizaOS plugins implement a Plugin interface (actions, providers, services) — see ElizaOS’s plugin architecture docs for the canonical shape. Create src/plugins/sovseal-memory.ts:

import type { Plugin, IAgentRuntime, Memory, State } from "@elizaos/core";
import { AgentStateClient, EngineUnavailableError } from "@sovseal/sdk";

const client = new AgentStateClient(); // store/recall need no endpoint/apiKey

export const sovsealMemoryPlugin: Plugin = {
  name: "sovseal-memory",
  description: "Local-first, zero-knowledge persistent memory via sovseal.",

  providers: [
    {
      name: "SOVSEAL_RECALL",
      get: async (runtime: IAgentRuntime, message: Memory, state?: State) => {
        try {
          const hits = await client.recall(String(message.content?.text ?? ""), { topK: 5 });
          return { text: hits.map((h) => h.text).join("\n"), values: {}, data: {} };
        } catch (err) {
          if (err instanceof EngineUnavailableError) return { text: "", values: {}, data: {} };
          throw err;
        }
      },
    },
  ],

  actions: [
    {
      name: "STORE_MEMORY",
      description: "Persist a fact or user preference to local sovseal memory.",
      validate: async () => true,
      handler: async (runtime: IAgentRuntime, message: Memory) => {
        const content = String(message.content?.text ?? "");
        try {
          const result = await client.store(content);
          return { text: result.reinforced ? "Reinforced existing memory." : "Stored." };
        } catch (err) {
          if (err instanceof EngineUnavailableError) return { text: `Memory engine unavailable (${err.reason}).` };
          throw err;
        }
      },
    },
  ],
};

3. Register it on your character

characters/sovereign.character.json

{
  "name": "SovereignAgent",
  "plugins": ["./src/plugins/sovseal-memory"],
  "clients": ["discord", "twitter"],
  "modelProvider": "google",
  "bio": [
    "An autonomous entity running with local-first memory continuity.",
    "Recalls context locally; optionally replicates encrypted state in the background."
  ]
}

Or register it directly in your bootstrap code:

import { AgentRuntime } from "@elizaos/core";
import { sovsealMemoryPlugin } from "./plugins/sovseal-memory";

export async function bootstrapAgentMemory(runtime: AgentRuntime) {
  await runtime.registerPlugin(sovsealMemoryPlugin);
}

store/recall require the native host launcher at ~/.sovseal/native-host/run.sh. Run npx -y @sovseal/mcp-server once to provision it — see SDK Reference: Overview.

How the hook cycle works

Once registered, the plugin participates in ElizaOS’s normal message flow:

On message (recall): The SOVSEAL_RECALL provider queries the local LanceDB index for facts relevant to the incoming message and injects them into the agent’s context before it responds.
On demand (store): When the agent invokes the STORE_MEMORY action — typically because your character’s instructions tell it to save a new fact or preference — the plugin commits it locally and returns immediately; there’s no network round-trip in the critical path.

If you also want the agent’s state to survive a full device loss, add snapshot() calls using the same AgentStateClient — that path needs an endpoint and apiKey, unlike store/recall. See the Node SDK reference for the full method signatures.

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

Persistent Eliza Characters

Zero-Knowledge Identity Isolation

1. Install the SDK

2. Write the memory plugin

3. Register it on your character

How the hook cycle works

​Zero-Knowledge Identity Isolation

​1. Install the SDK

​2. Write the memory plugin

​3. Register it on your character

​How the hook cycle works

Zero-Knowledge Identity Isolation

1. Install the SDK

2. Write the memory plugin

3. Register it on your character

How the hook cycle works