feat(eliza): Hindsight long-term memory integration for elizaOS

.github/workflows/test.yml

@@ -32,6 +32,7 @@ jobs:
       integration-tests: ${{ steps.filter.outputs.integration-tests }}
       integrations-openclaw: ${{ steps.filter.outputs.integrations-openclaw }}
       integrations-ai-sdk: ${{ steps.filter.outputs.integrations-ai-sdk }}
+      integrations-eliza: ${{ steps.filter.outputs.integrations-eliza }}
       integrations-agent-framework: ${{ steps.filter.outputs.integrations-agent-framework }}
       integrations-composio: ${{ steps.filter.outputs.integrations-composio }}
       integrations-chat: ${{ steps.filter.outputs.integrations-chat }}
@@ -133,6 +134,8 @@ jobs:
             - 'hindsight-integrations/openclaw/**'
           integrations-ai-sdk:
             - 'hindsight-integrations/ai-sdk/**'
+          integrations-eliza:
+            - 'hindsight-integrations/eliza/**'
           integrations-agent-framework:
             - 'hindsight-integrations/agent-framework/**'
           integrations-composio:
@@ -762,6 +765,37 @@ jobs:
       working-directory: ./hindsight-integrations/ai-sdk
       run: npm run test:deno
 
+  build-eliza-integration:
+    needs: [detect-changes]
+    if: >-
+      (github.event_name == 'workflow_dispatch' ||
+      needs.detect-changes.outputs.integrations-eliza == 'true' ||
+      needs.detect-changes.outputs.ci == 'true')
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.event.pull_request.head.sha || '' }}
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: '22'
+
+    - name: Install dependencies
+      working-directory: ./hindsight-integrations/eliza
+      run: npm ci
+
+    - name: Run tests
+      working-directory: ./hindsight-integrations/eliza
+      run: npm test
+
+    - name: Build
+      working-directory: ./hindsight-integrations/eliza
+      run: npm run build
+
   test-opencode-integration:
     needs: [detect-changes]
     if: >-

hindsight-dev/hindsight_dev/generate_changelog.py

@@ -44,6 +44,7 @@ class IntegrationMeta:
     "agent-framework": IntegrationMeta("hindsight-agent-framework", "Microsoft Agent Framework"),
     "ag2": IntegrationMeta("hindsight-ag2"),
     "ai-sdk": IntegrationMeta("@vectorize-io/hindsight-ai-sdk", "AI SDK"),
+    "eliza": IntegrationMeta("@vectorize-io/hindsight-eliza", "elizaOS"),
     "chat": IntegrationMeta("@vectorize-io/hindsight-chat", "Chat SDK"),
     "openclaw": IntegrationMeta("@vectorize-io/hindsight-openclaw", "OpenClaw"),
     "langgraph": IntegrationMeta("hindsight-langgraph", "LangGraph"),

hindsight-docs/docs-integrations/eliza.md

@@ -0,0 +1,94 @@
+---
+title: "elizaOS Long-Term Memory with Hindsight | Integration"
+description: "Give elizaOS agents persistent long-term memory. The Hindsight plugin recalls relevant memories into the prompt before each model call and retains conversations after each turn."
+---
+
+# elizaOS
+
+The `@vectorize-io/hindsight-eliza` package gives [elizaOS](https://github.com/elizaOS/eliza) agents long-term memory backed by [Hindsight](https://hindsight.vectorize.io).
+
+It registers two components on your agent:
+
+- A **provider** (`HINDSIGHT_MEMORY`) that recalls relevant memories and injects them into the prompt before each model call.
+- An **evaluator** (`HINDSIGHT_RETAIN`) that retains conversation messages to Hindsight after each turn.
+
+Both are enabled by default, layer on top of elizaOS's existing memory, and fail safe — a memory-service hiccup never blocks your agent from responding.
+
+[View Changelog →](/changelog/integrations/eliza)
+
+## Installation
+
+```bash
+npm install @vectorize-io/hindsight-eliza @vectorize-io/hindsight-client
+```
+
+This package targets `@elizaos/core` `^1.7.2` (declared as a peer dependency).
+
+## Usage
+
+Create the plugin and add it to your character's plugin list:
+
+```ts
+import { createHindsightPlugin } from "@vectorize-io/hindsight-eliza";
+import { Hindsight } from "@vectorize-io/hindsight-client";
+
+const hindsightPlugin = createHindsightPlugin({
+  client: new Hindsight({ apiKey: process.env.HINDSIGHT_API_KEY }),
+  recall: { budget: "high", includeEntities: true },
+  retain: { tags: ["source:eliza"] },
+});
+
+export const character = {
+  name: "Ada",
+  plugins: [
+    // ...your other plugins
+    hindsightPlugin,
+  ],
+};
+```
+
+By default each agent message is stored under a memory **bank** keyed by the
+message's `entityId`, giving every user an isolated memory store.
+
+## Configuration
+
+```ts
+createHindsightPlugin({
+  client,
+
+  // Which memory bank to read/write. A string uses one fixed bank for all
+  // messages; a function derives the bank per message. Defaults to
+  // `message.entityId` (one bank per user).
+  bank: (message) => message.entityId,
+
+  recall: {
+    enabled: true,            // set false to disable recall
+    budget: "mid",            // "low" | "mid" | "high" — latency vs. depth
+    types: ["world", "experience"], // restrict to fact types
+    maxTokens: 1000,          // cap recalled tokens
+    includeEntities: false,   // include entity observations
+    heading: "# Relevant long-term memories", // prompt heading
+  },
+
+  retain: {
+    enabled: true,            // set false to disable retain
+    async: true,              // fire-and-forget; never adds turn latency
+    tags: ["source:eliza"],   // tags on every retained memory
+    metadata: { env: "prod" },
+    includeAgentMessages: false, // also store the agent's own replies
+  },
+});
+```
+
+### Using only recall or only retain
+
+Disable either side with `recall.enabled: false` or `retain.enabled: false`. You
+can also build the components directly with `createHindsightProvider` and
+`createHindsightEvaluator` if you want to wire them into a plugin yourself.
+
+## How it works
+
+| Component | elizaOS seam | When it runs | What it does |
+| --- | --- | --- | --- |
+| `HINDSIGHT_MEMORY` | Provider | During prompt composition, before the model call | Calls Hindsight `recall` with the incoming message and injects the results into context |
+| `HINDSIGHT_RETAIN` | Evaluator | After the agent processes the turn | Calls Hindsight `retain` to persist the message (and optionally the agent's replies) |

hindsight-docs/src/data/integrations.json

@@ -1,5 +1,15 @@
 {
   "integrations": [
+    {
+      "id": "eliza",
+      "name": "elizaOS",
+      "description": "Give elizaOS agents long-term memory. A plugin that recalls relevant memories into the prompt and retains conversations to Hindsight.",
+      "type": "official",
+      "by": "hindsight",
+      "category": "framework",
+      "link": "/sdks/integrations/eliza",
+      "icon": "/img/icons/eliza.png"
+    },
     {
       "id": "litellm",
       "name": "LiteLLM",

hindsight-integrations/eliza/.gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+*.tsbuildinfo
+.DS_Store

hindsight-integrations/eliza/README.md

@@ -0,0 +1,72 @@
+# @vectorize-io/hindsight-eliza
+
+Long-term memory for [elizaOS](https://github.com/elizaOS/eliza) agents, backed by [Hindsight](https://hindsight.vectorize.io).
+
+The plugin registers two components on your agent:
+
+- **`HINDSIGHT_MEMORY` provider** — recalls relevant memories and injects them into the prompt before each model call.
+- **`HINDSIGHT_RETAIN` evaluator** — retains conversation messages to Hindsight after each turn.
+
+Both are enabled by default, layer on top of elizaOS's existing memory, and fail safe — a Hindsight outage never blocks the agent from responding.
+
+## Installation
+
+```bash
+npm install @vectorize-io/hindsight-eliza @vectorize-io/hindsight-client
+```
+
+Requires `@elizaos/core` `^1.7.2` (peer dependency).
+
+## Usage
+
+```ts
+import { createHindsightPlugin } from "@vectorize-io/hindsight-eliza";
+import { Hindsight } from "@vectorize-io/hindsight-client";
+
+const hindsightPlugin = createHindsightPlugin({
+  client: new Hindsight({ apiKey: process.env.HINDSIGHT_API_KEY }),
+  recall: { budget: "high", includeEntities: true },
+  retain: { tags: ["source:eliza"] },
+});
+
+export const character = {
+  name: "Ada",
+  plugins: [hindsightPlugin],
+};
+```
+
+By default memories are stored per user (keyed by the message `entityId`). Pass a
+`bank` string or `(message) => string` function to control this.
+
+## Options
+
+| Option                        | Description                                 | Default                         |
+| ----------------------------- | ------------------------------------------- | ------------------------------- |
+| `client`                      | A Hindsight client instance                 | required                        |
+| `bank`                        | Fixed bank string, or `(message) => string` | `message.entityId`              |
+| `recall.enabled`              | Enable the recall provider                  | `true`                          |
+| `recall.budget`               | `"low" \| "mid" \| "high"`                  | `"mid"`                         |
+| `recall.types`                | Restrict to fact types                      | all                             |
+| `recall.maxTokens`            | Cap recalled tokens                         | API default                     |
+| `recall.includeEntities`      | Include entity observations                 | `false`                         |
+| `recall.heading`              | Heading above recalled memories             | `# Relevant long-term memories` |
+| `retain.enabled`              | Enable the retain evaluator                 | `true`                          |
+| `retain.async`                | Fire-and-forget (no turn latency)           | `true`                          |
+| `retain.tags`                 | Tags on every retained memory               | —                               |
+| `retain.metadata`             | Metadata on every retained memory           | —                               |
+| `retain.includeAgentMessages` | Also store the agent's replies              | `false`                         |
+
+You can also use `createHindsightProvider` and `createHindsightEvaluator`
+directly if you want to assemble your own plugin.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run build
+```
+
+## License
+
+MIT