Hippocortex -- Persistent Memory for OpenClaw

Setup

1. Get an API key

Sign up at https://dashboard.hippocortex.dev and create an API key.

2. Configure credentials

Set environment variables (preferred):

export HIPPOCORTEX_API_KEY="hx_live_..."
# Optional -- defaults to https://api.hippocortex.dev
export HIPPOCORTEX_BASE_URL="https://api.hippocortex.dev"

Or create .hippocortex.json in your workspace root:

{
  "apiKey": "hx_live_...",
  "baseUrl": "https://api.hippocortex.dev",
  "sessionId": "my-agent"
}

3. Resolve configuration

On every invocation, resolve config in this order:

1. Environment variables (HIPPOCORTEX_API_KEY, HIPPOCORTEX_BASE_URL)
2. .hippocortex.json in workspace root
3. Fail gracefully if neither exists -- warn once, then proceed without memory

Set BASE_URL to $HIPPOCORTEX_BASE_URL or fall back to https://api.hippocortex.dev.

Set SESSION_ID from .hippocortex.json field sessionId, or default to "openclaw".

For self-hosted setup details, see references/setup-guide.md.

Automatic Memory Flow (MANDATORY)

Follow this flow on every interaction. All API calls use:

Authorization: Bearer $HIPPOCORTEX_API_KEY
Content-Type: application/json

Before answering ANY user message: Synthesize

Query memory for relevant context before composing your response.

curl -s -X POST "$BASE_URL/v1/synthesize" \
  -H "Authorization: Bearer $HIPPOCORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "'"$SESSION_ID"'",
    "query": "<rephrase the user message as a memory query>",
    "maxTokens": 2000
  }'

Response contains a memories array. Incorporate relevant memories into your answer naturally. Do not dump raw memory output to the user.

If synthesize fails: Still answer the user. Memory is additive, not blocking. Log the error silently and continue.

After important exchanges: Capture

Store the conversation when it contains memorable content.

curl -s -X POST "$BASE_URL/v1/capture" \
  -H "Authorization: Bearer $HIPPOCORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "'"$SESSION_ID"'",
    "type": "conversation",
    "payload": {
      "messages": [
        {"role": "user", "content": "<user message>"},
        {"role": "assistant", "content": "<your response>"}
      ]
    },
    "metadata": {
      "extractedMemories": [
        "User prefers dark mode",
        "Project X uses PostgreSQL 16"
      ]
    }
  }'

The extractedMemories array is critical -- it stores discrete semantic facts directly. Extract 1-5 concise facts from the exchange.

If capture fails: Still respond to the user. Log the error and retry on next opportunity.

During heartbeats: Compile

Run compile once per hour to consolidate memory patterns.

curl -s -X POST "$BASE_URL/v1/compile" \
  -H "Authorization: Bearer $HIPPOCORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sessionId": "'"$SESSION_ID"'"
  }'

Track the last compile timestamp. Skip if less than 60 minutes have passed.

If compile fails: Not urgent. Retry on next heartbeat.

API Reference

All endpoints require Authorization: Bearer $HIPPOCORTEX_API_KEY.

POST /v1/synthesize

Query stored memories.

Returns: { "memories": [...] }

POST /v1/capture

Store a conversation or fact.

Returns: { "id": "...", "status": "captured" }

POST /v1/compile

Consolidate and optimize stored memories.

Returns: { "status": "compiled", "stats": {...} }

When to Capture

Capture after exchanges that contain:

• User preferences, corrections, or personal facts
• Important decisions or conclusions
• Explicit requests ("remember this", "keep track of...")
• New information about people, projects, or processes
• Procedures or workflows the user explains

When NOT to Capture

Skip capture for:

• Casual greetings or small talk
• Simple yes/no confirmations
• Pure command execution (just running a script)
• Repeated information already in memory

Error Handling Summary

Never block a user response because a memory API call failed. Memory enhances responses but is never required for them.

Extracting Good Memories

When writing extractedMemories, follow these guidelines:

• Keep each fact to one sentence
• Be specific: "User's dog is named Max" not "User has a dog"
• Include context: "User prefers Python for data scripts" not "User likes Python"
• Capture corrections: "User's name is spelled Vince, not Vincent"
• Store preferences: "User wants responses in German for work emails"
• Record project facts: "Project Aurora uses Next.js 15 with Supabase"