Tools
Plugin Hindsight Memory
By OpenClaw plugin from ani6439walc/openclaw-plugin-hindsight-memory
Install
npm install --frozen-lockfileConfiguration Example
{
"dynamicBankId": true,
"dynamicBankGranularity": ["agent", "channel", "user"],
"agentBankMap": {
"inbound": "ps-technology",
"outbound": "ps-technology",
"limpieza": "ps-limpieza"
}
}README
# Hindsight Memory Plugin for OpenClaw
Biomimetic long-term memory for [OpenClaw](https://openclaw.ai) using [Hindsight](https://vectorize.io/hindsight). Automatically captures conversations and intelligently recalls relevant context.
## This fork
This repository contains only the OpenClaw integration from Vectorize's Hindsight
monorepo, with automatic recall progress events for
[discord-activity](https://github.com/ani6439walc/openclaw-plugin-discord-activity).
The Hindsight engine and SDK dependencies remain upstream packages. See
[UPSTREAM.md](UPSTREAM.md) for the exact source revision and update procedure.
Original code is copyright Vectorize AI, Inc., licensed under [MIT](LICENSE).
The package name is `hindsight-memory`; the OpenClaw plugin ID is
`hindsight-memory`. Use this fork **in place of** the official integration, not
alongside it. This README does not assume the fork is published to npm.
## Quick Start
Requires OpenClaw `2026.10.4`, Node.js `>=24.16.0 <25 || >=26.1.0`,
and `[email protected]` (matching `package.json`).
Build and check the package:
```bash
git clone https://github.com/ani6439walc/openclaw-plugin-hindsight-memory.git
cd openclaw-plugin-hindsight-memory
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
npm pack --pack-destination /tmp
```
Installing or replacing the plugin is a separate operator action. Save your
OpenClaw configuration first, then install the archive produced above (adjust the
version after updates):
```bash
openclaw plugins install npm-pack:/tmp/hindsight-memory-2026.10.4.tgz --force
# Optional: configure a new installation using this checkout's setup wizard.
node dist/setup.js
openclaw plugins inspect hindsight-memory --runtime --json
```
`--force` replaces an existing installation of the same plugin. Existing
installations do not need to rerun the setup wizard. Verify
`plugins.entries.hindsight-memory.config` and the hook permissions below before
using the plugin. The `npm-pack:` install path exercises OpenClaw's managed
runtime dependency installation, as recommended by the
[official plugin guide](https://docs.openclaw.ai/plugins/building-plugins).
For an existing checkout, `pnpm build` only rebuilds `dist/`. After deliberately
installing/replacing the package or updating the loaded checkout, reload its code
with `openclaw plugins reload hindsight-memory`. Building and testing alone do
not reload plugin code or restart the Gateway. With the default hybrid reload
mode, plugin configuration and hook-policy changes replace the plugin runtime
automatically.
Recall progress uses the `plugin:hindsight-memory` agent event stream through
`emitAgentEvent` from `openclaw/plugin-sdk/agent-harness-runtime`. A compatible
discord-activity version can display the recall status, elapsed time, and result
count. Events do not include the query or recalled memory content; a reporting
failure must not prevent recall.
`node dist/setup.js` walks you through picking one of three modes:
- **Cloud** — managed Hindsight. Paste your cloud API token, done.
- **External API** — your own running Hindsight deployment. Prompts for the URL and optional token.
- **Embedded daemon** — spawns a local `hindsight-embed` daemon on this machine. Prompts for the LLM provider (OpenAI / Anthropic / Gemini / Groq / Claude Code / Codex / Ollama) and its API key.
The interactive wizard stores credentials **inline** in `openclaw.json` for simplicity — the value is masked as you paste it. For CI / production you can store credentials as a `SecretRef` (resolved from an env var, file, or exec source at startup) by using the non-interactive flags with `--token-env` / `--api-key-env`, or by switching an existing field afterwards with `openclaw config set ... --ref-source env --ref-id …`.
The plugin ID is `hindsight-memory`; migrate the previous entry, allow/deny references,
and memory slot from `hindsight` when upgrading. The npm package and CLI
commands keep their existing names, and recall progress emits to the `plugin:hindsight-memory`
event stream.
### Recall progress event contract
Events use stream `plugin:hindsight-memory` and the host's `runId` and
`sessionKey` envelope fields. Emission requires a hook context `runId`. The host
SDK emitter works inside agent-scoped prompt hooks, where the registration API
method `api.agent.events.emitAgentEvent` can return `global side effects disabled`.
Expired hook invocations do not emit events.
The `data` payload contains:
| Field | Meaning |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `kind` | Always `hindsight-memory.recall`. |
| `pluginId` | Plugin ID (`hindsight-memory`). |
| `recallId` | A unique ID for each hook invocation that starts recall. |
| `sessionKey` | Session routing key, when available. |
| `state` | `started`, followed by at most one terminal state: `completed`, `failed`, `cancelled`, or `skipped`. |
| `durationMs` | Terminal events only: elapsed milliseconds since `started`, including client initialization and readiness waits. |
| `resultCount` | Completed events only: number of retrieved results, including zero. |
| `reason` | Failure: `timeout` or `error`; cancellation: `service_stopped`; skipped after starting: `client_unavailable`. |
Provider/session filters, disabled automatic recall, and other prechecks that
return before recall starts emit no events. Correlate events by `recallId` and
reject stale run/session events; do not infer recall success from silence.
### Manual configuration (without the wizard)
The wizard is a convenience wrapper — all of the same fields can be set directly with `openclaw config set`:
```bash
# Embedded daemon with OpenAI
openclaw config set plugins.entries.hindsight-memory.config.llmProvider openai
openclaw config set plugins.entries.hindsight-memory.config.llmApiKey \
--ref-source env --ref-provider default --ref-id OPENAI_API_KEY
# Or: Claude Code (no API key needed)
openclaw config set plugins.entries.hindsight-memory.config.llmProvider claude-code
# Or: point at an external Hindsight API
openclaw config set plugins.entries.hindsight-memory.config.hindsightApiUrl https://mcp.hindsight.example.com
openclaw config set plugins.entries.hindsight-memory.config.hindsightApiToken \
--ref-source env --ref-id HINDSIGHT_API_TOKEN
```
## Migrating from 0.5.x
0.6.0 removes all process-environment reads from the plugin. Configuration that
previously came from shell env vars must now go through OpenClaw's plugin config
(with SecretRef for credentials). Concrete mappings:
| Old (0.5.x) | New (0.6.0) |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OPENAI_API_KEY=…` (auto-detected) | `openclaw config set plugins.entries.hindsight-memory.config.llmProvider openai` <br> `openclaw config set plugins.entries.hindsight-memory.config.llmApiKey --ref-source env --ref-id OPENAI_API_KEY` |
| `HINDSIGHT_API_LLM_PROVIDER=…` | `openclaw config set plugins.entries.hindsight-memory.config.llmProvider …` |
| `HINDSIGHT_API_LLM_MODEL=…` | `openclaw config set plugins.entries.hindsight-memory.config.llmModel …` |
| `HINDSIGHT_API_LLM_API_KEY=…` | `openclaw config set plugins.entries.hindsight-memory.config.llmApiKey --ref-source env --ref-id …` |
| `HINDSIGHT_API_LLM_BASE_URL=…` | `openclaw config set plugins.entries.hindsight-memory.config.llmBaseUrl …` |
| `HINDSIGHT_EMBED_API_URL=…` | `openclaw config set plugins.entries.hindsight-memory.config.hindsightApiUrl …` |
| `HINDSIGHT_EMBED_API_TOKEN=…` | `openclaw config set plugins.entries.hindsight-memory.config.hindsightApiToken --ref-source env --ref-id …` |
| `HINDSIGHT_BANK_ID=…` | `openclaw config set plugins.entries.hindsight-memory.config.bankId …` |
| `llmApiKeyEnv: "MY_KEY"` (plugin config) | `llmApiKey` configured as a SecretRef with `--ref-id MY_KEY` |
If your shell already exports `OPENAI_API_KEY`, the SecretRef config above resolves
to the same value at startup — no need to change your shell setup, just point the
plugin at the vari
... (truncated)
tools
Comments
Sign in to leave a comment