Tools
Synapcores Openclaw Memory
By The AI-native database giving OpenClaw a real memory — vectors, graph & AutoML in one engine.
Install
npm install @synapcores/openclaw-memory@0.5.0`.Configuration Example
{
"plugins": {
"allow": ["memory-synapcores"],
"slots": { "memory": "memory-synapcores" },
"entries": {
"memory-synapcores": {
"enabled": true,
"hooks": {
"allowConversationAccess": true
},
"config": {
"synapcores": {
"host": "localhost",
"port": 8080,
"apiKey": "${SYNAPCORES_API_KEY}",
"useHttps": false
},
"collection": "openclaw_memories",
"graph": "openclaw_memory_graph",
"autoCapture": false,
"autoRecall": false,
"autoLinkSimilar": false
}
}
}
}
}README
# @synapcores/openclaw-memory
A long-term memory plugin for [OpenClaw](https://github.com/openclaw/openclaw) that uses a **SynapCores AIDB** gateway you host as the storage backend. Drop-in alternative to `@openclaw/memory-lancedb`, plus four SynapCores-only extensions: SQL-filtered semantic recall, graph-relation walks, AutoML relevance scoring, and a model-training helper.
> **What it does with your conversations (read this first).** By default the
> plugin is **passive**: it stores or recalls memory only when you explicitly
> call a tool (`memory_store` / `memory_recall` / `memory_forget`) or the `ltm`
> command. It also offers an **opt-in automatic lifecycle** (`autoCapture` /
> `autoRecall`, both **off by default**). When you turn `autoCapture` on, the
> plugin becomes proactive: at the **end of every agent turn** and again **just
> before OpenClaw compacts the context**, it inspects the conversation, infers
> durable personal facts, preferences, and decisions, and **persists them (in
> the model's own words) to your SynapCores gateway** — and `autoRecall` injects
> matching memories back into the model's context on later turns. This is real
> long-term memory of personal conversation details; enable it deliberately. See
> [Privacy & data handling](#privacy--data-handling).
> **0.8.0 shipping note — the full memory-object surface.** The `CREATE MEMORY`
> backend introduced in 0.7.0 is now reachable end to end:
>
> - **`CREATE MEMORY ... WITH (...)` is now configurable.** Before 0.8.0 the
> plugin created every memory object on the engine's blind defaults — including
> the embedding model and width. Set `memory.create.embeddingModel` /
> `memory.create.dimensions` to match your deployment's `EMBED` model (a
> mismatch silently breaks semantic recall), toggle `memory.create.llmExtraction`,
> `FOR AGENT`, and the episodic/semantic/temporal/consolidation knobs. Applied
> only when the plugin auto-creates the object; an unset block keeps the old
> default behaviour exactly.
> - **New `memory_history` tool** — the timeline of how a remembered attribute's
> value changed over time ("what did I used to prefer?"), distinct from the
> current value (`memory_current`) and related context (`memory_recall`).
> - **Honest `ltm stats`** — now reads the engine's own `status`/`DESCRIBE`
> instead of a client-side `COUNT(*)` that returned the wrong number under a
> credential-pinned identity.
> - **New `ltm` subcommands:** `describe`, `history`, `consolidate`, `supersede`,
> `reconcile`, `drop` — the memory-object lifecycle and reasoning verbs, all
> gated to the memory-object backend.
> **0.7.0 shipping note — the `CREATE MEMORY` backend.** SynapCores engine
> `v1.14.3-ce` introduced a first-class memory object: one logical thing with
> episodes, durable facts, temporal validity, relationships, provenance and an
> authoritative current state, driven by five verbs (`REMEMBER`, `RECALL`,
> `CURRENT`, `FORGET`, `TRACE`). The plugin now **detects it at runtime and uses
> it when it is there**, and keeps running on the legacy `MEMORY_*` primitives
> when it is not. Nothing to configure — `memory.backend` defaults to `auto`.
>
> What you get on `v1.14.3-ce+`:
>
> - **Two new tools.** `memory_current` — the authoritative present value of one
> attribute, a deterministic state lookup rather than a similarity search, with
> an explicit `conflict` outcome the agent must handle instead of guessing.
> `memory_trace` — why a value is believed: the source statement verbatim, when
> it was recorded versus when it happened, the extraction method, and what it
> superseded.
> - **Recall that separates authority from similarity.** `memory_recall` and the
> auto-recall hook now use the engine's `RECALL`, injecting its
> `context.prompt_ready` projection instead of a hand-assembled list — so
> current state outranks a semantically similar older episode, and the token
> budget truncates the low-priority half rather than the authoritative half.
> - **Per-identity isolation, with no configuration.** `memory.identityFrom`
> defaults to `credential`: the plugin sends no identity and the gateway
> resolves it from the token's `memory_identity` pin, so the plugin cannot
> address another identity because it never names one. **This needs an
> ordinary user token** — API keys and admin tokens are never pinned; with
> one of those, set `memory.identityFrom: "static"`. See
> [Identity](#identity--who-a-memory-belongs-to).
> - **The engine owns dedup.** The old client-side "is this a near-duplicate?"
> probe before every store is gone on this backend; consolidation, supersession
> and conflict policy are the database's job.
> - **`confidence` and `relevance` stay separate.** Relevance is the retrieval
> score; confidence is evidence strength. `MemorySearchResult.score` remains
> relevance, and `confidence` is its own optional field.
>
> Trade-offs and the full mapping (including what the legacy path can do that
> the new one cannot — `importance` / `category` are **not persisted** on the
> memory object) are in [MIGRATION.md](./MIGRATION.md).
> **0.5.0 shipping note:** the core memory ops (`memory_store` / `memory_recall` / `memory_forget`) ride the engine-side `MEMORY_STORE` / `MEMORY_RECALL` / `MEMORY_FORGET` primitives via `@synapcores/sdk@^0.6.0`'s `client.memory` surface. The plugin's public API (tools, CLI, extensions, types) is unchanged.
>
> - **Requires SynapCores gateway `v1.8.5-ce` or newer** (the version that ships the `MEMORY_*` SQL functions).
> - **Fully engine-native embeddings — zero external-LLM dependency.** The `memory_store` / `memory_recall` hot path embeds server-side inside the engine's `MEMORY_STORE` / `MEMORY_RECALL` primitives; the relevance extensions (`predictRelevance` / `trainRelevanceModel`) and the `autoLinkSimilar` graph-node embedding call the gateway's native `client.embed()`. All embeddings come from the SynapCores gateway (embedding dimension is the gateway model's, e.g. 384 for `all-minilm`). OpenAI has been removed entirely — no OpenAI key, no `openai` dependency.
> - **Migration from 0.3.x: the engine-managed table is `_memory_<namespace>`, a different storage backend from the v0.3.x vector collection. Existing v0.3.x memories WILL NOT appear after upgrade — re-capture them.** See "Upgrading from 0.3.x" below.
> - **`collection` config field becomes the engine `namespace`.** It must now match `^[A-Za-z_][A-Za-z0-9_]*$`. The default `openclaw_memories` continues to work; other custom values with hyphens or other non-identifier characters need updating.
> - **`recallFiltered` WHERE clauses are applied client-side.** The engine cannot apply a `WHERE` to the table-valued `MEMORY_RECALL(?, ?, ?)` result-set (it drops every row), so the plugin fetches an oversampled, unfiltered recall and evaluates the predicate in JS. Legacy column shorthands (`category`, `importance`, `createdAt`, `text`) and the JSON-extract form (`metadata->>'…'`) are both understood directly — no rewriting required.
## Upgrading from 0.3.x
`@synapcores/openclaw-memory@0.5.0` is a **hard cut** from 0.3.x: the storage backend changed (at 0.4.0), so old memories will not migrate automatically. Steps:
1. Upgrade the SynapCores gateway to `v1.8.5-ce` or newer.
2. `npm install @synapcores/openclaw-memory@0.5.0`.
3. If your `collection` config value contains hyphens or other non-identifier characters, rename it to match `^[A-Za-z_][A-Za-z0-9_]*$` before restarting.
4. (Optional) export any high-value memories from the v0.3.x vector collection (the legacy `openclaw_memories` collection in your gateway) and re-store them via `memory_store` so they land in the new `_memory_<namespace>` table.
5. (Optional) drop the old vector collection from the gateway once you're sure the export is done.
If your `recallFiltered` callers use plain column names (`category`, `importance`, `createdAt`, `text`), they continue to work — the client-side filter understands those column names directly. Callers filtering on arbitrary metadata keys use the JSON-extract form (`metadata->>'…'`).
## Why use this over `@openclaw/memory-lancedb`?
| Capability | memory-lancedb | memory-synapcores |
| --- | --- | --- |
| Vector recall + capture | yes | yes |
| Auto-recall / auto-capture hooks | yes | yes |
| GDPR-style forget by ID or query | yes | yes |
| SQL-scoped semantic recall (`recallFiltered`) | no | **yes** |
| Graph relation walks (`recallRelated`) | no | **yes** |
| AutoML relevance scoring (`predictRelevance`) | no | **yes** |
| Backend | local LanceDB files | SynapCores gateway (HTTP) |
If you only need a private, single-user, file-backed vector store, stay on `@openclaw/memory-lancedb`. If you want any of: cross-session/multi-device shared memory, SQL filtering across metadata, graph relations between memories, or per-user relevance models — install this package.
## Install
```bash
pnpm add @synapcores/openclaw-memory
# or
npm install @synapcores/openclaw-memory
```
`openclaw` (the host) is declared as a peer dependency — install it in your OpenClaw workspace.
## Prerequisites
You need a running SynapCores gateway. The Community Edition is free:
```bash
# Linux/macOS one-liner installer (see https://synapcores.com/install)
curl -fsSL https://synapcores.com/install.sh | sh
# Then start it:
synapcores start
```
Create an API key from the SynapCores admin UI (default `http://localhost:8095`) and copy it into your OpenClaw config below.
## Configure
Requires OpenClaw **`>=2026.4.10`**. Install the plugin, then add its config and
give it the **memory slot**:
```bash
openclaw plugins install @synapcores/openclaw-memory
```
Add this to your OpenClaw config (run `openclaw config file` to find the path,
typically `~/.openclaw/openclaw.json`). Three things matter: the
`plugins.entries.<id>.config` nesting, the `plugins.allow` entry, and
**`plugins.slots.memory`**:
```json
{
"plugins": {
"allow
... (truncated)
tools
Comments
Sign in to leave a comment