Hippocortex SDK Overview

The Hippocortex SDKs provide client libraries for integrating agent memory into any AI application. Available in TypeScript and Python with framework-specific adapters.

Integration Methods

The SDK offers three integration paths, from zero-effort to full manual control:

Method	Effort	Description	Best For
`import auto`	1 line	Sentry-style monkey-patching of OpenAI/Anthropic SDKs	Fastest start, prototyping
`wrap(client)`	1 line	Transparent client wrapping with full type safety	Production apps, explicit control
`new Hippocortex()`	Manual	Direct capture/learn/synthesize calls	Custom agent loops, non-OpenAI/Anthropic LLMs

Auto-Instrumentation (Easiest)

// TypeScript: one import, zero config
import '@hippocortex/sdk/auto'

# Python: one import, zero config
import hippocortex.auto

Every OpenAI and Anthropic SDK call automatically gets memory context injection and conversation capture. No other code changes required.

wrap() (Recommended)

import { wrap } from '@hippocortex/sdk'
import OpenAI from 'openai'

const openai = wrap(new OpenAI())
// Use exactly as before. Memory is transparent.

from hippocortex import wrap
from openai import OpenAI

client = wrap(OpenAI())
# Use exactly as before. Memory is transparent.

Manual Client (Advanced)

The manual client exposes three core operations:

Operation	What It Does	When to Call It
`capture()`	Record an agent interaction event	After every significant agent action
`learn()`	Trigger memory compilation	Periodically or after a batch of events
`synthesize()`	Retrieve relevant context for a query	Before the agent needs to make a decision

This three-function model keeps integration simple: instrument your agent with capture calls, periodically compile knowledge, and retrieve context when needed.

Zero-Config

All integration methods support automatic configuration resolution:

Explicit arguments passed to wrap(), new Hippocortex(), etc.
Environment variables: HIPPOCORTEX_API_KEY, HIPPOCORTEX_BASE_URL
Config file: .hippocortex.json (searched from cwd upward to filesystem root)

.hippocortex.json

{
  "apiKey": "hx_live_your_key_here",
  "baseUrl": "https://api.hippocortex.dev/v1"
}

Language Support

Language	Package	Install Command	Min Version
TypeScript	`@hippocortex/sdk`	`npm install @hippocortex/sdk`	Node 18+
Python	`hippocortex`	`pip install hippocortex`	Python 3.10+

Both SDKs provide identical functionality and API parity.

Framework Adapters

Adapters wrap the core SDK to integrate with popular AI agent frameworks. They handle event translation from framework-specific formats to Hippocortex event types.

Adapter	Framework	Language	Auto-captures
OpenAI Agents	OpenAI Agents	Python	Messages, tool calls, tool results
LangGraph	LangGraph	Python	Node events, tool calls, state
CrewAI	CrewAI	Python	Task events, agent actions
AutoGen	AutoGen	Python	Messages, function calls
OpenClaw	OpenClaw	Both	All event types

Adapters are installed as optional dependencies alongside the core SDK.

Authentication

All SDK operations require an API key:

const hx = new Hippocortex({
  apiKey: 'hx_live_your_key_here'
});

API Key Formats

Prefix	Environment	Purpose
`hx_live_`	Production	Production data operations
`hx_test_`	Test	Test environment, no billing

API keys are created in the Hippocortex Dashboard or via the API Keys endpoint.

Key Permissions

Each API key carries read and/or write permissions:

Permission	Operations
`read`	synthesize, listArtifacts, getArtifact, getMetrics
`write`	capture, captureBatch, learn

Error Handling

Both SDKs throw typed errors with structured error information:

TypeScript

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

try {
  await hx.capture(event);
} catch (error) {
  if (error instanceof HippocortexError) {
    console.error(`Code: ${error.code}`);
    console.error(`Status: ${error.statusCode}`);
    console.error(`Message: ${error.message}`);
    console.error(`Details:`, error.details);
  }
}

Python

from hippocortex import HippocortexError

try:
    await hx.capture(event)
except HippocortexError as e:
    print(f"Code: {e.code}")
    print(f"Status: {e.status_code}")
    print(f"Message: {e}")
    print(f"Details: {e.details}")

Error Codes

Code	HTTP Status	Description
`validation_error`	400	Invalid request body
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	Insufficient permissions
`not_found`	404	Resource does not exist
`rate_limited`	429	Too many requests
`internal_error`	500	Server-side error
`duplicate_event`	409	Event already captured (idempotency)

Rate Limits

Rate limits are enforced per API key based on the account plan:

Plan	Requests/Minute	Burst Allowance
Free	60	10
Developer	600	100
Pro	3,000	500
Enterprise	Unlimited	Unlimited

Rate limit headers are included in every response:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1709251200

When rate limited, the SDK receives a 429 response. Implement exponential backoff in your retry logic.

Configuration Options

TypeScript

const hx = new Hippocortex({
  apiKey: 'hx_live_...',       // Required: API key
  baseUrl: 'https://...',      // Optional: API base URL (default: https://api.hippocortex.dev/v1)
  timeoutMs: 30000,            // Optional: Request timeout in ms (default: 30000)
});

Python

hx = Hippocortex(
    api_key="hx_live_...",           # Required: API key
    base_url="https://...",          # Optional: API base URL
    timeout=30.0,                    # Optional: Timeout in seconds (default: 30.0)
)

Next Steps

TypeScript SDK Reference -- Full method reference (auto, wrap, manual client)
Python SDK Reference -- Full method reference (auto, wrap, manual client)
Adapters Guide -- Framework adapter setup and usage
API Reference -- REST API documentation