Hippocortex

Provides an OpenClaw agent with persistent long-term memory by automatically remembering and recalling conversations, facts, and preferences across sessions.

Security Scan

The skill's instructions require sending full conversation content and extracted personal facts to an external Hippocortex API (and optionally a self-hosted instance), but the registry metadata does not declare the required credentials or clarify data handling—this mismatch and the mandated upload of user messages is suspicious.

Purpose & Capability

The skill claims to provide persistent long-term memory, which legitimately requires an external memory service and an API key. However, the registry metadata lists no required environment variables or primary credential, while SKILL.md explicitly requires HIPPOCORTEX_API_KEY (and optionally HIPPOCORTEX_BASE_URL / .hippocortex.json). The omission in metadata is an incoherence that reduces transparency about external data access.

Instruction Scope

The runtime instructions mandate querying /v1/synthesize before every reply and POSTing conversations (user+assistant messages) to /v1/capture when exchanges are 'memorable', plus hourly /v1/compile calls. That flow explicitly sends conversation content and extracted semantic facts to an external endpoint; it therefore broadens scope from 'memory helper' to an agent that uploads potentially sensitive user data. The instructions also say to 'extract 1-5 concise facts' (encouraging precise personal facts), and to 'log the error silently', which could conceal failures. These behaviors are more intrusive than the registry indicates.

Install Mechanism

This is an instruction-only skill with no install spec or code files, so nothing is written to disk by the skill itself. That lowers installation risk; however, the runtime behavior depends entirely on outbound HTTP calls described in SKILL.md.

Credentials

The SKILL.md requires an API key (HIPPOCORTEX_API_KEY), optional HIPPOCORTEX_BASE_URL, and supports a .hippocortex.json sessionId, but the registry declares no required env vars or primary credential. This is a material mismatch. Additionally, the skill's recommended captured facts encourage storing personal and project-specific details (PII and secrets could be captured accidentally), so the required credential grants access to potentially large amounts of user data—proportionally significant and deserving explicit declaration.

Persistence & Privilege

The skill implements persistent storage of conversation-derived facts on an external service and instructs the agent to call that service automatically on interactions. While it is not marked 'always: true', agent autonomy plus these mandatory outbound calls mean the skill can autonomously exfiltrate conversation content to the configured HIPPOCORTEX endpoint. A self-hosting option exists (reduces third‑party exposure), but the default base URL is an external domain (https://api.hippocortex.dev).

What to consider before installing

Before installing: (1) Recognize the skill will send user and assistant messages and extracted facts to an external API by default—this can include sensitive personal or project data. (2) The registry metadata does not list the required HIPPOCORTEX_API_KEY; ask the publisher to declare it explicitly. (3) If you must use the skill, consider self-hosting the service (follow the setup guide) so data remains under your control, or avoid setting an API key for agents that handle sensitive info. (4) Limit what the agent captures: do not allow it to store passwords, secrets, or PII; consider disabling automatic capture or restricting triggers. (5) Review Hippocortex's privacy/data-retention policy and audit stored memories on the Hippocortex side. (6) If you cannot verify the operator or hosting, treat the skill as untrusted and avoid enabling it for sensitive conversations.

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.

Field	Type	Required	Description
sessionId	string	yes	Agent session identifier
query	string	yes	Natural language query
maxTokens	number	no	Max tokens in response (default: 2000)

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

POST /v1/capture

Store a conversation or fact.

Field	Type	Required	Description
sessionId	string	yes	Agent session identifier
type	string	yes	"conversation" or "fact"
payload	object	yes	Message array or fact content
metadata.extractedMemories	string[]	no	Discrete facts to store directly

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

POST /v1/compile

Consolidate and optimize stored memories.

Field	Type	Required	Description
sessionId	string	yes	Agent session identifier

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

Endpoint	On failure	Action
synthesize	Answer without memory context	Log error, continue
capture	Respond normally	Log error, retry later
compile	Skip this cycle	Retry next heartbeat

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"