Hippocortex OS — Beta Quickstart

Welcome to the Hippocortex private beta. This guide gets you from zero to integrated in under 30 minutes.

---

Prerequisites

• Docker installed and running
• Node.js 22+ (for SDK) or Python 3.10+ (for Python SDK)
• Your beta API key (provided in your invitation email)

---

Step 1: Start the Server

Option A: Docker (Recommended)

# Create a data directory
mkdir -p ~/hippocortex-data

# Run the server
docker run -d \
  --name hippocortex \
  -p 3100:3100 \
  -v ~/hippocortex-data:/data \
  -e HIPPOCORTEX_STORAGE_PATH=/data/hippocortex.db \
  -e HIPPOCORTEX_API_KEYS=hx_beta_YOUR_KEY_HERE \
  hippocortex:beta-v1.0.0

# Verify it's running
curl http://localhost:3100/api/v1/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 5
}

Option B: Local Node.js

# Clone the repo
git clone <repo-url> hippocortex-os
cd hippocortex-os

# Install and build
pnpm install
pnpm build

# Start
HIPPOCORTEX_STORAGE_PATH=./hippocortex.db \
HIPPOCORTEX_API_KEYS=hx_beta_YOUR_KEY_HERE \
pnpm --filter @hippocortex/server start

---

Step 2: Install the SDK

JavaScript / TypeScript

npm install @hippocortex/sdk

Python

pip install hippocortex

---

Step 3: Capture Your First Event

JavaScript

import { Hippocortex } from '@hippocortex/sdk';

const hx = new Hippocortex({
  apiKey: 'hx_beta_YOUR_KEY_HERE',
  baseUrl: 'http://localhost:3100/v1'  // your local server
});

// Capture a conversation event
const result = await hx.capture({
  type: 'message',
  sessionId: 'session-001',
  payload: {
    role: 'user',
    content: 'What deployment strategy did we use for the payment service?'
  }
});

console.log('Captured:', result.id);

Python

from hippocortex import Hippocortex

hx = Hippocortex(
    api_key="hx_beta_YOUR_KEY_HERE",
    base_url="http://localhost:3100/v1"
)

result = hx.capture(
    type="message",
    session_id="session-001",
    payload={
        "role": "user",
        "content": "What deployment strategy did we use for the payment service?"
    }
)

print(f"Captured: {result['id']}")

---

Step 4: Trigger Learning

After capturing events, tell Hippocortex to consolidate them into memories:

JavaScript

const learnResult = await hx.learn();
console.log('Memories created:', learnResult.memoriesCreated);
console.log('Entities found:', learnResult.entitiesDiscovered);

Python

learn_result = hx.learn()
print(f"Memories created: {learn_result['memoriesCreated']}")
print(f"Entities found: {learn_result['entitiesDiscovered']}")

---

Step 5: Synthesize Context

Retrieve relevant context for your agent's next decision:

JavaScript

const ctx = await hx.synthesize('payment service deployment');

for (const entry of ctx.entries) {
  console.log(`[${entry.type}] ${entry.content} (confidence: ${entry.confidence})`);
}

// Pass ctx.entries to your LLM as system context

Python

ctx = hx.synthesize("payment service deployment")

for entry in ctx["entries"]:
    print(f"[{entry['type']}] {entry['content']} (confidence: {entry['confidence']})")

---

Step 6: Verify Everything Works

# Check detailed health (requires API key)
curl -H "X-API-Key: hx_beta_YOUR_KEY_HERE" \
  http://localhost:3100/api/v1/health/detailed

# Check metrics
curl http://localhost:3100/api/v1/metrics | grep events_captured_total

If events_captured_total shows your captured events, you're integrated.

---

What to Do Next

1. Integrate with your agent — Replace the test calls above with real event capture from your agent's conversation loop
2. Call learn() periodically — After every session, or on a schedule (every 15–60 minutes)
3. Call synthesize() before LLM calls — Inject the returned context into your agent's system prompt
4. Monitor health — Check /api/v1/health occasionally
5. Back up your data — cp ~/hippocortex-data/hippocortex.db ~/hippocortex-data/backup-$(date +%Y%m%d).db

---

Common Integration Patterns

Pattern 1: Wrap Your Agent Loop

// Before each LLM call
const memory = await hx.synthesize(userMessage);
const systemPrompt = `${basePrompt}\n\nRelevant context:\n${memory.entries.map(e => e.content).join('\n')}`;

// After the LLM responds
await hx.capture({ type: 'message', sessionId, payload: { role: 'assistant', content: response } });

Pattern 2: Capture Tool Calls

// When your agent calls a tool
await hx.capture({
  type: 'tool_call',
  sessionId,
  payload: { tool: 'deploy', args: { service: 'payments', env: 'staging' } }
});

// When the tool returns
await hx.capture({
  type: 'tool_result',
  sessionId,
  payload: { tool: 'deploy', result: { success: true, url: 'https://staging.example.com' } }
});

Pattern 3: Session Boundaries

// Start of a new agent session
const sessionId = `session-${Date.now()}`;

// ... capture events throughout the session ...

// End of session — trigger learning
await hx.learn({ scope: sessionId });

---

Need Help?

• Bug or crash? Email beta-support or post in the beta Discord/Slack channel
• Integration question? Check BETA-FAQ.md first, then ask in the beta channel
• Something broke? See BETA-TROUBLESHOOTING.md