> ## 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.

# ElizaOS Agent Memory Integration

> Build a minimal ElizaOS plugin wiring @sovseal/sdk's local-first, zero-knowledge store/recall memory into your agent's Plugin interface.

Wire `@sovseal/sdk`'s local `store()`/`recall()` into an ElizaOS agent as a small custom plugin. ElizaOS agents maintain state continuity and can securely sync encrypted snapshots using sovseal's zero-knowledge, client-side-encrypted replication when you also use `snapshot`/`restore`.

<Info>
  By using `sovseal`'s zero-knowledge client-side encryption (AES-256-GCM) for the replication path, ElizaOS agents can persist facts and state across restarts without exposing plaintext data to third-party database servers.
</Info>

<Warning>
  There is currently no published, pre-built `@sovseal/adapter-eliza` package. The plugin below is a minimal, working example you copy into your own ElizaOS project — wiring `@sovseal/sdk` directly into ElizaOS's standard `Plugin` interface (`actions`/`providers`/`services`). It is not a one-line install.
</Warning>

## Installation

Add `@sovseal/sdk` to your ElizaOS project workspace:

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

***

## Build a minimal sovseal plugin

ElizaOS plugins are plain objects implementing the `Plugin` interface — `actions` (what the agent can *do*), `providers` (what the agent can *see*), `services` (long-lived connections). Create `src/plugins/sovseal-memory.ts`:

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

// store/recall need no endpoint/apiKey — they talk to the local native host.
const client = new AgentStateClient();

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

  // Provider: injects recalled context into the agent's state before it responds
  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: {} }; // fail open
          }
          throw err;
        }
      },
    },
  ],

  // Action: lets the agent explicitly persist a fact
  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;
        }
      },
    },
  ],
};
```

Register it in your character file (`characters/my-agent.character.json`) alongside your other plugins:

```json theme={null}
{
  "name": "SovereignAgent",
  "plugins": ["./src/plugins/sovseal-memory"]
}
```

Or register it directly on the runtime in your bootstrap code:

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

export async function startAgent(runtime: AgentRuntime) {
  await runtime.registerPlugin(sovsealMemoryPlugin);
  console.log("sovseal memory plugin registered.");
}
```

<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). Consult [ElizaOS's plugin architecture docs](https://docs.elizaos.ai/plugins/architecture) for the full `Action`/`Provider` interface — the shapes above are illustrative of the pattern, not a copy of ElizaOS's type definitions.
</Note>

***

## Zero-knowledge state replication (optional)

If you also want encrypted multi-device sync of full agent state (not just semantic recall), use `@sovseal/sdk`'s `snapshot()`/`restore()` methods — see the [Node SDK reference](/sdk-reference/node-sdk) for the full API. That path requires an `endpoint` and `apiKey`; `store`/`recall` above do not.