> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Persistent Eliza Characters

> Wire @sovseal/sdk's store/recall directly into an ElizaOS character's Plugin interface for local-first, zero-knowledge persistent memory — no pre-built adapter package exists yet.

<Warning>
  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](/integrations/eliza-os) for the full plugin shape.
</Warning>

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](/platform/features/replication-sync).

***

## 1. Install the SDK

```bash theme={null}
pnpm install @sovseal/sdk
```

## 2. Write the memory plugin

ElizaOS plugins implement a `Plugin` interface (`actions`, `providers`, `services`) — see [ElizaOS's plugin architecture docs](https://docs.elizaos.ai/plugins/architecture) for the canonical shape. Create `src/plugins/sovseal-memory.ts`:

```typescript theme={null}
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

```json characters/sovereign.character.json theme={null}
{
  "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:

```typescript theme={null}
import { AgentRuntime } from "@elizaos/core";
import { sovsealMemoryPlugin } from "./plugins/sovseal-memory";

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

<Note>
  `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](/sdk-reference/overview).
</Note>

***

## How the hook cycle works

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

1. **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.
2. **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](/sdk-reference/node-sdk) for the full method signatures.