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.

All SDK methods access the full pipeline: capture, synthesize (semantic search, graph retrieval, collective brain, behavioral context), learn, vault, and collective brain.

---

Integration Methods

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

Method	Effort	Description	Reliability	Best For
Gateway	0 lines	Change base URL, no SDK needed	~99%	Most users, any language
import auto	1 line	Monkey-patching of OpenAI/Anthropic SDKs	~95%	Quick start, prototyping
wrap(client)	1 line	Transparent client wrapping with type safety	~95%	Production apps, explicit control
new Hippocortex()	Manual	Direct capture/learn/synthesize/vault calls	~95%	Custom agent loops, non-OpenAI LLMs

Gateway (Recommended)

No SDK installation required. See the Gateway guide.

from openai import OpenAI

client = OpenAI(
    base_url="https://api.hippocortex.dev/v1",
    api_key="hx_live_...",
    default_headers={"X-LLM-API-Key": "sk-..."},
)

Auto-Instrumentation

// 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.

wrap()

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

The manual client exposes the full API:

Operation	What It Does	When to Call It
capture()	Record an agent interaction event	After every significant agent action
captureBatch()	Record multiple events at once	Batch processing
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
vaultQuery()	Search vault for secrets (metadata only)	When agent needs to find stored secrets
vaultReveal()	Retrieve decrypted secret value	When agent needs to use a secret
listArtifacts()	List compiled knowledge artifacts	Inspection and debugging
getMetrics()	Get usage and performance metrics	Monitoring and billing

---

Zero-Config

All integration methods support automatic configuration resolution:

1. Explicit arguments passed to wrap(), new Hippocortex(), etc.
2. Environment variables: HIPPOCORTEX_API_KEY, HIPPOCORTEX_BASE_URL
3. 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	Version	Install Command	Min Version
TypeScript	@hippocortex/sdk	1.2.1	npm install @hippocortex/sdk@1.2.1	Node 18+
Python	hippocortex	1.2.1	pip install hippocortex==1.2.1	Python 3.9+

Both SDKs provide identical functionality and API parity.

Package Exports (TypeScript)

Export	Description
@hippocortex/sdk	Core client (Hippocortex, wrap, types)
@hippocortex/sdk/auto	Auto-instrumentation (monkey-patching)
@hippocortex/sdk/register	Registration utilities
@hippocortex/sdk/adapters	Framework adapters

---

Framework Adapters

Adapters wrap the core SDK to integrate with popular AI agent frameworks.

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

---

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

Key Permissions

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

---

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}, Status: ${error.statusCode}`);
  }
}

Python

from hippocortex import HippocortexError

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

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
Pro	600	100
Unlimited	3,000	500
Team	Custom	Custom

---

Next Steps

• TypeScript SDK Reference — Full method reference
• Python SDK Reference — Full method reference
• Adapters Guide — Framework adapter setup and usage
• Gateway Guide — Zero-code integration (recommended)
• API Reference — REST API documentation