OpenClaw plugin for Cortex long-term memory. Gives your agent persistent memory that survives across sessions — who you are, what your project does, decisions you made weeks ago, and how things changed over time.
- Auto-Recall — injects relevant memories before every agent turn via
before_agent_starthook - Auto-Capture — extracts facts from conversations via
agent_endhook - Session Goals — agent sets the session objective via
cortex_set_session_goal, biasing recall toward goal-relevant memories and tagging captured facts - Agent Tools —
cortex_search_memory,cortex_save_memory,cortex_set_session_goal, and more — tools the LLM can invoke directly - Commands —
/checkpointto save session context,/sleepto mark a clean end,/auditto toggle local logging - CLI Commands —
openclaw cortex {status,memories,search,config,pair,reset}for terminal access - Recovery Detection — detects unclean prior sessions and prepends recovery context at session start
- Heartbeat — periodic health, knowledge state refresh, and activity-aware reflect triggering via
gateway:heartbeat - Gateway RPC —
cortex.statusmethod for programmatic health and metrics access - Deduplication — client-side dedupe window and novelty threshold to prevent redundant memory saves
- Resilience — retry queue with exponential backoff, cold-start detection, latency metrics
- Node.js
>=20 - OpenClaw with plugin support (
openclawpeer dependency is>=0.1.0)
openclaw plugins install @ubundi/openclaw-cortex
openclaw config set plugins.entries.openclaw-cortex.config.apiKey "your-cortex-api-key"
openclaw gateway restartOr link locally for development:
openclaw plugins install -l ./path/to/openclaw-cortex-
Install the plugin:
openclaw plugins install @ubundi/openclaw-cortex
-
Set the tools profile to
fullso the agent can access memory tools:openclaw config set tools.profile full openclaw gateway restartNote: OpenClaw defaults to the
messagingtools profile, which excludes memory tools. The plugin's own tools (cortex_search_memory,cortex_save_memory) are registered directly and work on any profile, but the built-inmemory_search,read,write, and other tools requirefull. This must be re-applied after runningopenclaw configureas the wizard resets it. -
Add your API key to the plugin config:
openclaw config set plugins.entries.openclaw-cortex.config.apiKey "your-cortex-api-key" openclaw gateway restart
Alternatively, set the
CORTEX_API_KEYenvironment variable:export CORTEX_API_KEY="your-cortex-api-key"
Note: OpenClaw registers the plugin under the install name
openclaw-cortex(without the npm scope). Always useopenclaw-cortexwhen referencing the plugin in config keys.On first run the plugin generates a unique ID for this installation, persists it at
~/.openclaw/cortex-user-id, and scopes all memories to that ID. -
Run an agent turn. If configured correctly, recall data is prepended in a
<cortex_memories>block before the model turn.
Add to your openclaw.json:
{
plugins: {
entries: {
"openclaw-cortex": {
enabled: true,
config: {
apiKey: "your-cortex-api-key", // required — or set CORTEX_API_KEY env var
autoRecall: true,
autoCapture: true,
recallLimit: 20,
recallTimeoutMs: 60000,
toolTimeoutMs: 60000,
// userId: "my-team-shared-id", // override the auto-generated install ID
},
},
},
slots: {
memory: "openclaw-cortex",
},
},
}| Option | Type | Default | Description |
|---|---|---|---|
apiKey |
string | — | Required. Your Cortex API key. Can also be set via the CORTEX_API_KEY environment variable. |
userId |
string | auto | Memory scope ID. Auto-generated per install and persisted at ~/.openclaw/cortex-user-id. Override to share memory across machines or team members. |
autoRecall |
boolean | true |
Inject relevant memories before each agent turn |
autoCapture |
boolean | true |
Extract and store facts after each agent turn |
recallLimit |
number | 20 |
Max number of memories returned per recall |
recallTopK |
number | 10 |
Max memories returned after scoring (applied after recallLimit) |
recallQueryType |
string | "combined" |
Recall query mode: "factual", "emotional", "combined", or "codex" |
recallProfile |
string | "auto" |
Recall profile: "auto", "default", "factual", "planning", "incident", "handoff". auto picks the best profile based on context. |
recallTimeoutMs |
number | 60000 |
Auto-recall timeout in ms. Scales with knowledge tier via deriveEffectiveTimeout. |
recallReferenceDate |
string | now | Optional fixed ISO 8601 date as temporal anchor for recall. For benchmarks only — leave unset in production. |
toolTimeoutMs |
number | 60000 |
Timeout for explicit tool calls (cortex_search_memory, /checkpoint). Longer than auto-recall since the user is actively waiting. |
captureMaxPayloadBytes |
number | 262144 |
Max byte size of capture payloads (256KB default). Oversized transcripts are trimmed from the oldest messages. |
captureFilter |
boolean | true |
Enable built-in filter to drop low-signal content (heartbeat messages, TUI artifacts, token counters) before ingestion. |
auditLog |
boolean | false |
Enable local audit log. Records every payload sent to Cortex at .cortex/audit/ in the workspace. Also toggleable at runtime via /audit on. |
dedupeWindowMinutes |
number | 30 |
Time window (minutes) for client-side deduplication of explicit memory saves. Set to 0 to disable. |
noveltyThreshold |
number | 0.85 |
Similarity score (0–1) above which an existing memory is considered a duplicate. Lower = stricter. |
namespace |
string | "openclaw" |
Memory namespace. Auto-derived from workspace directory when not set explicitly. |
sessionGoal |
boolean | true |
Enable session goal detection. When active, the agent sets a goal that biases recall and tags captures. |
agentRole |
string | — | Agent specialization: "developer", "researcher", "manager", "support", "generalist". Tunes capture categories and recall context. |
src/
index.ts # Public package entrypoint
cortex/
client.ts # HTTP client for all Cortex API endpoints
plugin/ # Plugin wiring, config, CLI, tools, commands
index.ts
config.ts
cli.ts
commands.ts
tools.ts
search-query.ts
types.ts
features/ # Feature modules
capture/ # After-turn fact extraction
checkpoint/ # /checkpoint command handler
heartbeat/ # gateway:heartbeat hook
recall/ # Before-turn memory injection + context profiles
internal/ # Shared utilities (not stable public API)
agent-instructions.ts
api-key.ts
audit-logger.ts
capture-watermark-store.ts
cleaner.ts
dedupe.ts
heartbeat-detect.ts
latency-metrics.ts
message-provenance.ts
message-sanitizer.ts
recall-echo-store.ts
retry-queue.ts
safe-path.ts
session-goal.ts
session-state.ts
user-id.ts
For npm consumers, import from the package root (@ubundi/openclaw-cortex). Internal module paths are implementation details and may change between versions.
Before every agent turn, the plugin queries Cortex's /v1/recall endpoint and prepends results to the agent's context:
<cortex_memories>
- [0.95] User prefers TypeScript over JavaScript
- [0.87] Project uses PostgreSQL with pgvector
</cortex_memories>If the request exceeds recallTimeoutMs, the agent proceeds without memories (silent degradation). After 3 consecutive hard failures (connection errors, not timeouts), recall is disabled for 30 seconds (cold-start detection) to avoid hammering a dead service. Timeouts from a slow-but-running backend do not trigger the cold-start gate.
If the previous session ended uncleanly (e.g. the process crashed or you reset without /sleep), the plugin detects this on the next before_agent_start and prepends a recovery block before the first turn:
<cortex_recovery>
Unclean session detected. Last known context: ...
</cortex_recovery>This lets the agent pick up where it left off without you having to re-explain. Use /checkpoint before /sleep or /new to make this context more useful.
After each agent turn completes, the plugin flattens the turn's new user and assistant messages into a role: content transcript and submits it to Cortex's /v1/jobs/ingest endpoint (async job queue). The job returns immediately and processes in the background — this avoids Lambda proxy timeouts that occur with synchronous ingestion. A watermark tracks how much of the conversation has already been ingested, so each message is sent exactly once — no overlap between turns. A heuristic skips trivial exchanges (short messages, turns without a substantive response).
Capture is fire-and-forget — it never blocks the agent. Failed ingestions are queued for retry with exponential backoff (up to 5 retries).
The agent automatically identifies the user's primary objective at session start and sets it via cortex_set_session_goal. This biases recall queries toward goal-relevant memories and tags captured facts with the active goal for better future retrieval. If the session crashes, the goal is persisted and restored automatically on recovery.
The goal is passed as a dedicated session_goal parameter to the Cortex retrieval pipeline, where it computes a separate embedding for clean alignment scoring — no contamination of the primary query's BM25 matching or classification. On the capture side, the goal is sent as metadata on the ingest payload so the backend can tag SESSION and FACT nodes.
Session goals are cleared automatically when the session changes (e.g. /new). Disable with sessionGoal: false in config.
The plugin registers tools the LLM agent can invoke directly:
cortex_set_session_goal— set the session's primary objective to bias recall and tag captures. Called automatically at session start; updated if the goal shifts.cortex_search_memory— search long-term memory with a natural language query. Returns matching memories with confidence scores. Use when the agent needs to recall something specific.cortex_save_memory— explicitly save a fact, preference, or piece of information to long-term memory. Use when the user asks "remember this" or the agent identifies something worth persisting.cortex_forget— selectively remove memories by entity name or session ID. Always searches first and confirms before deleting.cortex_get_memory— fetch a specific memory by its node ID for detailed inspection.
These work alongside Auto-Recall/Auto-Capture — the automatic hooks handle background memory flow, while the tools give the agent explicit control when needed.
Agent tools require the OpenClaw runtime to support
api.registerTool(). On older runtimes, the plugin gracefully skips tool registration.
The plugin registers auto-reply commands that execute without invoking the AI agent:
/checkpoint # Auto-summarize recent messages and save to Cortex
/checkpoint <summary> # Save a custom summary to Cortex
/sleep # Mark the session as cleanly ended (clears recovery state)
/audit # Show audit log status
/audit on # Start recording all data sent to Cortex
/audit off # Stop recording (existing logs preserved)
/checkpoint is designed to be run before /new or resetting the agent. It saves what you were working on so the next session can recover context without manual re-explanation.
/sleep marks the session as cleanly ended. Without it, the next session will see a recovery warning. Use /checkpoint first if you want the context saved.
The audit log writes to .cortex/audit/ in your workspace — an index.jsonl with metadata and a payloads/ directory with full content of every transmission. Useful for compliance, debugging, or verifying exactly what data leaves your machine.
The plugin registers terminal-level commands under openclaw cortex:
openclaw cortex status # API health check with latency and memory counts
openclaw cortex memories # Memory count, session count, maturity, top entities
openclaw cortex search [query...] # Search memories from the terminal with natural-language questions
openclaw cortex search --mode decisions what database did we choose
openclaw cortex config # Show current plugin configuration
openclaw cortex pair # Generate a TooToo pairing code to link your agent
openclaw cortex reset # Permanently delete all memories (prompts for confirmation)
openclaw cortex reset --yes # Skip confirmationThe cortex.status RPC method exposes plugin health and metrics programmatically:
{
"version": "1.7.5",
"healthy": true,
"knowledgeState": { "hasMemories": true, "totalSessions": 42, "maturity": "mature", "tier": 3 },
"recallMetrics": { "count": 120, "p50": 95, "p95": 280, "p99": 450 },
"retryQueuePending": 0,
"config": { "autoRecall": true, "autoCapture": true, "namespace": "myproject-a1b2c3d4" }
}On session start, the plugin logs a single status line:
Cortex v1.7.5 ready
Cortex connected — 1,173 memories, 4 sessions (cold), tier 1
Recall latency percentiles are logged at debug level on shutdown. Enable verbose logging to see them, or run openclaw cortex status for live metrics.
This plugin sends data to the Cortex API to provide memory functionality. Here's what leaves your machine:
| Data | When | How to disable |
|---|---|---|
| Conversation messages (user + assistant) | After each agent turn | autoCapture: false |
| Your current prompt | Before each agent turn | autoRecall: false |
| Session goal (if set) | With recall and capture requests | sessionGoal: false |
Additionally, a randomly generated installation ID (userId) and a workspace namespace hash are sent with every request to scope your data. No personally identifiable information is collected.
Before transmission, the plugin strips runtime metadata from captured messages and removes prior recalled memories to prevent feedback loops.
All data is transmitted over HTTPS. Each installation's data is isolated server-side by its unique userId — no other installation can access your memories. This isolation has been verified via cross-user recall testing.
Capture payloads are capped at 256KB by default (captureMaxPayloadBytes) to prevent oversized transmissions from pasted files or verbose replies.
To see exactly what data leaves your machine, enable the audit log with /audit on or auditLog: true in your config. This records every payload to .cortex/audit/ in your workspace.
To disable all network activity, set autoRecall: false and autoCapture: false in your config.
The plugin ships a cortex-memory skill that teaches the agent how to use Cortex memory tools effectively. The skill is declared in openclaw.plugin.json and loaded automatically by the OpenClaw runtime when the plugin is enabled — no manual installation needed.
The skill is also available on ClawHub if you want to install it independently or override the bundled version at the workspace level.
If both the plugin and the skill are active, the <cortex_memories> tag in the prepended context signals to the skill that recall has already happened — the agent can skip manual curl calls.
- Agent not using plugin tools: Check
tools.profileinopenclaw.json— OpenClaw defaults to"messaging", which excludes memory tools. Runopenclaw config set tools.profile full && openclaw gateway restart. The configure wizard resets this, so re-check after any reconfiguration. - Plugin installed but no memory behavior: verify both
"enabled": trueand"slots.memory": "openclaw-cortex"inopenclaw.json. Note: config uses the install nameopenclaw-cortex, not the npm scope. Cannot find module 'zod'during plugin load (older installs): runnpm install --prefix ~/.openclaw/extensions/openclaw-cortex --omit=dev zod.- Frequent recall timeouts: increase
recallTimeoutMsfor auto-recall ortoolTimeoutMsfor explicit searches. - No useful memories returned: ensure prior sessions were captured (
autoCapture) or saved explicitly withcortex_save_memoryor/checkpoint.
npm install
npm run build # TypeScript → dist/
npm test # Run vitest (504 tests)
npm run test:watch # Watch mode
npm run test:integration # Live Cortex API tests (uses the baked-in API key)Manual proof scripts live under tests/manual/.
openclaw-cortex is an open-source project by Ubundi — a South African venture studio shaping human-centred AI. Based in Cape Town, Ubundi builds at the intersection of AI capability and African context, developing tools that ensure the benefits of AI reach their continent first.
openclaw-cortex was built as part of the infrastructure behind Cortex, Ubundi's long-term memory layer for AI agents — where robust cross-session recall is foundational to delivering contextually relevant, grounded responses.
MIT