cortex-memoryLong-term structured memory with knowledge graph, entity tracking, temporal reasoning, and cross-session recall. Powered by the Cortex API.
Install via ClawdBot CLI:
clawdbot install matthewubundi/cortex-memoryCortex gives you a structured long-term memory that goes beyond what memory_search can do. It extracts facts, entities, and relationships from text, stores them in a knowledge graph, and retrieves them using hybrid search (BM25 + semantic + temporal + graph traversal).
Use Cortex when you need to:
memory_search returns noisy or incomplete results forDo NOT use Cortex for simple lookups that memory_search handles well (recent session context, keyword matches in today's log). Use native memory first; escalate to Cortex for deeper queries.
If @cortex/openclaw-plugin is also installed: The plugin automatically injects Cortex memories before every turn inside a
Requires CORTEX_API_KEY and CORTEX_BASE_URL environment variables. These are set in ~/.openclaw/openclaw.json:
```json
{
"skills": {
"entries": {
"cortex-memory": {
"enabled": true,
"apiKey": "sk-cortex-oc-YOUR_KEY",
"env": {
"CORTEX_BASE_URL": "https://q5p64iw9c9.execute-api.us-east-1.amazonaws.com/prod"
}
}
}
}
}
```
```bash
curl -s "$CORTEX_BASE_URL/health" -H "x-api-key: $CORTEX_API_KEY" | jq .
```
Expected: {"status": "ok"}
When you need to recall facts, entities, or relationships from past sessions:
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/retrieve" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg query "QUERY_HERE" \
--arg query_type "factual" \
--argjson top_k 10 \
'{query: $query, query_type: $query_type, top_k: $top_k}')" | jq '.results[] | {type, content, score, metadata}'
```
Retrieval modes:
full (default) — all 5 retrieval channels + graph traversal + reranking. Best recall quality, but slower (~300-600ms depending on region). Use this for thorough queries where you need the best results.fast — BM25 + semantic only, no graph traversal or reranking (~80-150ms server-side). Use when you need a quick check and can tolerate less thorough results. Pass "mode": "fast" in the request body.```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/retrieve" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg query "QUERY_HERE" \
--arg query_type "factual" \
--arg mode "fast" \
--argjson top_k 5 \
'{query: $query, query_type: $query_type, top_k: $top_k, mode: $mode}')" | jq '.results[] | {type, content, score}'
```
Query types:
factual — search FACT and ENTITY nodes (use for: who, what, when, where questions)emotional — search EMOTION, INSIGHT, VALUE, BELIEF nodes (use for: how does the user feel about X?)combined — search all node types (default, use when unsure)When to use Cortex recall vs. memory_search:
| Situation | Use memory_search | Use Cortex recall | Mode |
|---|---|---|---|
| Recent context from today | Yes | No | — |
| Simple keyword lookup | Yes | No | — |
| Cross-session facts | No — often noisy | Yes | fast usually sufficient |
| Entity relationships ("how does X relate to Y?") | No — can't traverse | Yes | full (needs graph traversal) |
| Temporal changes ("what changed about X?") | No — no SUPERSEDES tracking | Yes | full (needs temporal channel) |
| Scoped project queries | No — cross-project noise | Yes | fast usually sufficient |
| Entity lookup ("who is Sarah Chen?") | Partial — finds mentions | Yes — entity node + all connected facts | fast for quick check, full for complete picture |
When the user asks you to remember something important, or when you encounter high-value information that should persist with full entity extraction:
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/ingest" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg text "TEXT_TO_REMEMBER" \
--arg session_id "openclaw:$(date +%Y-%m-%d)" \
'{text: $text, session_id: $session_id}')" | jq '{nodes_created, edges_created, facts: [.facts[].core], entities: [.entities[].name]}'
```
The response shows what was extracted:
facts — factual statements extracted from the textentities — named entities (people, companies, places, etc.) with aliasesnodes_created / edges_created — graph nodes and relationship edges createdWhen to remember:
Session ID convention:
openclaw:YYYY-MM-DD (e.g., openclaw:2026-02-17)openclaw:project-name:topic (e.g., openclaw:project-frontend:memory-md)openclaw:project-name:daily:YYYY-MM-DDopenclaw:preferencesThe session ID is used for scoped retrieval — queries can filter to a specific project by matching the session ID prefix.
At the end of a productive session, you can ingest the key conversation turns with proper speaker attribution:
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/ingest/conversation" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n \
--arg session_id "openclaw:$(date +%Y-%m-%d):session-topic" \
--argjson messages '[
{"role": "user", "content": "FIRST USER MESSAGE"},
{"role": "assistant", "content": "FIRST ASSISTANT RESPONSE"},
{"role": "user", "content": "SECOND USER MESSAGE"}
]' \
'{messages: $messages, session_id: $session_id}')" | jq '{nodes_created, edges_created, facts: [.facts[].core]}'
```
When to use this:
On first install, ingest the user's existing MEMORY.md to seed the knowledge graph.
For small MEMORY.md files (under ~50 lines / ~4KB — most users):
```bash
MEMORY_CONTENT=$(cat ~/.openclaw/workspace/MEMORY.md 2>/dev/null || echo "")
if [ -n "$MEMORY_CONTENT" ]; then
curl -s -X POST "$CORTEX_BASE_URL/v1/ingest" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg text "$MEMORY_CONTENT" --arg session_id "openclaw:bootstrap" \
'{text: $text, session_id: $session_id}')" | jq '{nodes_created, edges_created, facts: (.facts | length), entities: (.entities | length)}'
fi
```
For large MEMORY.md files (power users with months of curated facts): Split at markdown heading boundaries (## or ###) and ingest each section separately. Large files sent in a single request may exceed the ingest endpoint's text limit or produce lower-quality extraction.
```bash
MEMORY_FILE=~/.openclaw/workspace/MEMORY.md
if [ -f "$MEMORY_FILE" ]; then
SECTION="" TOTAL_FACTS=0 TOTAL_ENTITIES=0
while IFS= read -r line || [ -n "$line" ]; do
if echo "$line" | grep -q '^## ' && [ -n "$SECTION" ]; then
RESULT=$(curl -s -X POST "$CORTEX_BASE_URL/v1/ingest" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg text "$SECTION" --arg session_id "openclaw:bootstrap" \
'{text: $text, session_id: $session_id}')")
TOTAL_FACTS=$((TOTAL_FACTS + $(echo "$RESULT" | jq '.facts | length')))
TOTAL_ENTITIES=$((TOTAL_ENTITIES + $(echo "$RESULT" | jq '.entities | length')))
SECTION=""
fi
SECTION="$SECTION$line
"
done < "$MEMORY_FILE"
# Ingest final section
if [ -n "$SECTION" ]; then
RESULT=$(curl -s -X POST "$CORTEX_BASE_URL/v1/ingest" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d "$(jq -n --arg text "$SECTION" --arg session_id "openclaw:bootstrap" \
'{text: $text, session_id: $session_id}')")
TOTAL_FACTS=$((TOTAL_FACTS + $(echo "$RESULT" | jq '.facts | length')))
TOTAL_ENTITIES=$((TOTAL_ENTITIES + $(echo "$RESULT" | jq '.entities | length')))
fi
echo "Bootstrap complete: $TOTAL_FACTS facts, $TOTAL_ENTITIES entities extracted."
fi
```
Run this once after installation. Tell the user how many facts and entities were extracted.
401 Unauthorized — invalid or missing API key. Ask user to check CORTEX_API_KEY.422 Validation Error — malformed request. Check the JSON payload.500 Internal Server Error — Cortex API issue. Retry once, then fall back to native memory_search.If Cortex is unavailable, always fall back to memory_search. Never block the user because of a Cortex API issue.
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/retrieve" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "What company did the user join?", "query_type": "factual", "top_k": 5}' | jq '.results[] | {type, content, score}'
```
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/ingest" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "User prefers PostgreSQL over MySQL for all database projects.", "session_id": "openclaw:preferences"}' | jq '{facts: [.facts[].core], entities: [.entities[].name]}'
```
```bash
curl -s -X POST "$CORTEX_BASE_URL/v1/retrieve" \
-H "x-api-key: $CORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "How does the auth service relate to the API gateway?", "query_type": "factual", "top_k": 10}' | jq '.results[] | {type, content, score, metadata}'
```
CORTEX_API_KEY value in responses, logs, or tool outputs.Generated Feb 23, 2026
A sales team uses Cortex to track interactions with clients across multiple meetings, storing key facts, preferences, and decisions in a knowledge graph. This enables agents to recall past conversations and relationships, improving personalized follow-ups and reducing reliance on manual notes.
A software development team integrates Cortex to store technical decisions, entity relationships (e.g., APIs, modules), and temporal changes from project discussions. This helps new team members quickly understand project history and dependencies, enhancing onboarding and collaboration.
Medical professionals use Cortex to maintain structured long-term memory of patient histories, including symptoms, treatments, and emotional insights over time. This supports accurate recall across sessions, aiding in diagnosis and continuity of care while adhering to privacy standards.
Researchers employ Cortex to store and retrieve facts, entities, and relationships from literature reviews and team discussions. It facilitates cross-session recall of key findings and temporal reasoning on evolving theories, streamlining collaborative projects and paper writing.
Law firms utilize Cortex to track case details, entity relationships (e.g., parties, evidence), and temporal changes in legal arguments. This enables quick retrieval of past case facts and superseded information, improving case preparation and strategy development.
Offer tiered subscription plans for API access, with pricing based on usage limits (e.g., number of queries or storage). This model provides recurring revenue and scales with customer growth, targeting businesses needing structured memory solutions.
Sell enterprise licenses with custom integrations, premium support, and enhanced security features. This model caters to large organizations requiring dedicated deployment and compliance, generating high-value contracts.
Provide a free tier with basic memory features and limited usage, encouraging adoption. Upsell to paid plans for advanced capabilities like full retrieval modes and higher limits, driving conversion from individual users to teams.
💬 Integration Tip
Set up environment variables correctly and verify the API connection first; use fast mode for quick checks and full mode for complex queries involving graph traversal.
Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Clau...
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
Search and analyze your own session logs (older/parent conversations) using jq.
Typed knowledge graph for structured agent memory and composable skills. Use when creating/querying entities (Person, Project, Task, Event, Document), linking related objects, enforcing constraints, planning multi-step actions as graph transformations, or when skills need to share state. Trigger on "remember", "what do I know about", "link X to Y", "show dependencies", entity CRUD, or cross-skill data access.
Ultimate AI agent memory system for Cursor, Claude, ChatGPT & Copilot. WAL protocol + vector search + git-notes + cloud backup. Never lose context again. Vibe-coding ready.
Headless browser automation CLI optimized for AI agents with accessibility tree snapshots and ref-based element selection