Skill: vmaiops-alt/hippocortex (version 2.2.2)

--- name: hippocortex description: Give your OpenClaw agent persistent long-term memory powered by Hippocortex. Automatically remembers conversations, facts, preferences, and procedures across sessions. Use when you want your agent to remember things between sessions, recall past conversations, or build up knowledge over time. Triggers on: memory, remember, recall, hippocortex, persistent memory, long-term memory. --- # 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): ```bash 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: ```json { "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](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. ```bash 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. ```bash 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. ```bash 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"

path: _meta.json
content: ownerId: kn78c1ar27eztvt5sxspczfrr982zjzn
slug: hippocortex
version: 1.0.0
publishedAt: 1773605418024

path: references/setup-guide.md
content: # Hippocortex Setup Guide

## Cloud (Recommended)

1. Go to https://dashboard.hippocortex.dev
2. Create an account and generate an API key
3. Set your environment variable:
   ```bash
   export HIPPOCORTEX_API_KEY="hx_live_..."
   ```
4. The default base URL is `https://api.hippocortex.dev` -- no need to set it unless using self-hosted

## Self-Hosted

Hippocortex can run on your own infrastructure. Use this when you need full data control or air-gapped operation.

### Docker Compose

```bash
git clone https://github.com/hippocortex/hippocortex-os.git
cd hippocortex-os
cp .env.example .env
# Edit .env with your configuration
docker compose up -d
```

### Environment Variables (Self-Hosted Server)

| Variable | Description | Default |
|----------|-------------|---------|
| DATABASE_URL | PostgreSQL connection string | required |
| REDIS_URL | Redis connection string | optional |
| API_PORT | Port for the API server | 3100 |
| JWT_SECRET | Secret for token signing | required |

### Point Your Agent to Self-Hosted

Set the base URL to your self-hosted instance:

```bash
export HIPPOCORTEX_API_KEY="your-self-hosted-key"
export HIPPOCORTEX_BASE_URL="http://localhost:3100"
```

Or in `.hippocortex.json`:

```json
{
  "apiKey": "your-self-hosted-key",
  "baseUrl": "http://localhost:3100",
  "sessionId": "my-agent"
}
```

## Configuration File Reference

The `.hippocortex.json` file supports these fields:

| Field | Type | Required | Default |
|-------|------|----------|---------|
| apiKey | string | yes | -- |
| baseUrl | string | no | https://api.hippocortex.dev |
| sessionId | string | no | "openclaw" |

Place this file in your OpenClaw workspace root (`~/.openclaw/workspace/.hippocortex.json`).

## Verifying Setup

Test your configuration by running a synthesize call:

```bash
curl -s -X POST "${HIPPOCORTEX_BASE_URL:-https://api.hippocortex.dev}/v1/synthesize" \
  -H "Authorization: Bearer $HIPPOCORTEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "test", "query": "hello", "maxTokens": 100}'
```

A successful response returns a JSON object with a `memories` array (empty on first run).

## Troubleshooting

| Problem | Solution |
|---------|----------|
| 401 Unauthorized | Check that HIPPOCORTEX_API_KEY is set and valid |
| Connection refused | Verify HIPPOCORTEX_BASE_URL points to a running instance |
| Empty memories | Expected on first use -- capture some conversations first |
| Timeout errors | Check network connectivity; self-hosted: verify the server is running |


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)