/cortexdb-memory-openclaw

name: cortexdb-memory-openclaw
description: Give a Node.js agent (such as OpenClaw) durable, local-first memory plus a queryable SPARQL knowledge graph, backed by CortexDB through its gRPC sidecar and the cortexdb-client npm package. Use when a Node agent needs to remember facts about a user across turns/sessions, recall them by meaning, store entities and relations, or answer multi-hop questions — and when the user mentions CortexDB, agent memory, long-term memory, RAG, knowledge graph, OpenClaw, or "remember this".
license: MIT
compatibility: Requires Node.js 18+, npm, and the cortexdb-grpc sidecar binary (Go install or prebuilt release). Optional embeddings via any OpenAI-compatible endpoint (e.g. Ollama).
metadata: {"author": "liliang-cn", "project": "cortexdb", "version": "1.0"}

CortexDB memory for a Node agent (OpenClaw)

Wire CortexDB in as the memory layer for a Node.js agent. CortexDB is a pure-Go, single-file database; the Node agent talks to it over gRPC via the `cortexdb-client` package. Beyond vector/lexical recall, it gives the agent a real **knowledge graph** (RDF + SPARQL) — the thing most agent-memory layers lack. It fits OpenClaw's local-first philosophy: one binary, one SQLite file, no separate service to stand up.

When to use this

• The agent should remember user facts/preferences across turns or sessions.
• The agent should recall memories by meaning, not exact match.
• The agent needs entities + relations and multi-hop questions ("who, among the

people Alice knows, works on X").

• You're integrating with OpenClaw (or any Node agent/skill).

Step 1 — Run the sidecar (once)

# install the binary (or download a prebuilt release)
go install github.com/liliang-cn/cortexdb/v2/cmd/cortexdb-grpc@latest

# lexical mode — zero config, no API key:
CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc
# → listening on 127.0.0.1:47821

Enable vector/semantic recall by pointing it at any OpenAI-compatible embeddings endpoint (e.g. a local Ollama):

OPENAI_BASE_URL=http://localhost:11434/v1 \
CORTEXDB_EMBED_MODEL=embeddinggemma CORTEXDB_EMBED_DIM=768 \
CORTEXDB_PATH=agent.db CORTEXDB_GRPC_TOKEN=s3cret cortexdb-grpc

Step 2 — Install the client

npm install cortexdb-client

Step 3 — The two core moves: remember + recall

const { CortexClient } = require('cortexdb-client');

const client = CortexClient.connect('127.0.0.1:47821', { token: 's3cret' });

// remember a fact about the user (scoped per user)
await client.memory.SaveMemory({
  memoryId: 'pref-coffee', userId: 'alice', scope: 'user',
  content: 'Alice prefers dark roast coffee and runs OpenClaw locally.',
});

// later turn / next session: recall by meaning
const hits = await client.memory.SearchMemory({
  query: 'what does the user like to drink?',
  userId: 'alice', scope: 'user', topK: 3,
});
for (const h of hits.results) console.log(h.memory.content, h.score);

Every RPC is a promise; request fields are camelCase. **Memory scopes** isolate data: `scope: 'user'` (per `userId`), `scope: 'session'` (per `sessionId`), or `scope: 'global'`.

Step 4 — Knowledge instead of plain memory (RAG)

await client.knowledge.SaveKnowledge({
  knowledgeId: 'doc-1', title: 'Project brief',
  content: 'The user is building an autonomous agent in TypeScript.',
});
const res = await client.knowledge.SearchKnowledge({
  query: 'what is the user building?', topK: 3,
});

Step 5 — The differentiator: a knowledge graph

const iri = (v) => ({ kind: 'iri', value: v });
await client.graph.UpsertNamespace({ prefix: 'ex', uri: 'https://example.com/' });
await client.graph.UpsertKnowledgeGraph({ triples: [
  { subject: iri('ex:alice'), predicate: iri('ex:knows'), object: iri('ex:bob') },
] });
const ans = await client.graph.QuerySparql({
  query: 'SELECT ?o WHERE { <https://example.com/alice> <https://example.com/knows> ?o . }',
});
console.log(ans.result.count, 'result(s)');

Expose CortexDB as OpenClaw tools

OpenClaw skills teach the agent how and when to call tools. A ready-to-use helper module wraps the calls above into `remember`, `recall`, `saveKnowledge`, `searchKnowledge`, `relate`, and `askGraph`. `recallContext` uses the unified KnowledgeMemory facade to fuse scoped memory, durable knowledge, and graph facts:

• `scripts/memory-tools.js` — import these and register them as OpenClaw tools,

or call them directly from a custom skill/plugin.

For automatic OpenClaw memory lifecycle integration, install the native plugin at `plugins/openclaw-cortexdb-memory` and select `cortexdb-memory` in `plugins.slots.memory`. The native plugin replaces OpenClaw's built-in `memory-core` slot; this skill alone does not.

In your skill's instructions, tell the agent: *to remember a durable fact about the user, call `remember(text)`; to recall, call `recall(query)`; to record a relationship, call `relate(subject, predicate, object)`; to answer a structured "who/what is related to X" question, call `askGraph(sparql)`.*

Install this skill into OpenClaw

OpenClaw follows the agentskills.io spec and discovers skills under `<workspace>/skills`, `<workspace>/.agents/skills`, `~/.agents/skills`, and `~/.openclaw/skills`.

# from this repo (local directory):
openclaw skills install ./skills/cortexdb-memory-openclaw --as cortexdb-memory

# or from git / ClawHub:
openclaw skills install git:liliang-cn/cortexdb@main --global

`--global` installs to `~/.openclaw/skills`. The skill becomes eligible automatically once the `cortexdb-grpc` binary is present and a sidecar is running.

Sub-clients (full surface)

`client.knowledge`, `client.memory`, `client.graph` (RDF/SPARQL/SHACL/inference/ ontology), `client.graphrag`, `client.tools` (generic dispatch, same shape as MCP), `client.admin`. Each RPC is available in both PascalCase (`SaveMemory`) and camelCase (`saveMemory`). Auth is a bearer token; pass `{ token }` to `connect`.

Notes & gotchas