Cortex Memory

Cortex 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:

• Recall information across past sessions
• Understand how concepts, people, or projects relate to each other
• Track what changed over time (superseded facts, belief drift)
• Find things that memory_search returns noisy or incomplete results for

Do 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 <cortex_memories> tag. If you see <cortex_memories> in the current context, Cortex has already been queried for this turn — do NOT call recall again unless you need a different query (e.g., a follow-up entity lookup or a different query type).

Setup

Requires CORTEX_API_KEY and CORTEX_BASE_URL environment variables. These are set in ~/.openclaw/openclaw.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"
        }
      }
    }
  }
}

Verify Connection

curl -s "$CORTEX_BASE_URL/health" -H "x-api-key: $CORTEX_API_KEY" | jq .

Expected: {"status": "ok"}

Recall — Search Long-Term Memory

When you need to recall facts, entities, or relationships from past sessions:

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.