@hippocortex/sdk

Official JavaScript/TypeScript SDK for Hippocortex, AI agent memory that learns from experience.

Install

npm install @hippocortex/sdk

Quick Start

Choose the integration method that fits your workflow:

Auto-Instrumentation (Easiest, 1 Line)

import '@hippocortex/sdk/auto'
import OpenAI from 'openai'

const openai = new OpenAI()

// Every call now has persistent memory automatically:
// - Past context is synthesized and injected
// - The conversation is captured for future learning
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Deploy payments to staging' }]
})

wrap() (Recommended)

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

// Wrap your client. Explicit, typed, per-client control.
const openai = wrap(new OpenAI())

// Use exactly as before. Memory is transparent.
const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Deploy payments to staging' }]
})

// Works with Anthropic too:
import Anthropic from '@anthropic-ai/sdk'
const anthropic = wrap(new Anthropic())

Manual Client (Advanced)

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

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

// 1. Capture agent events
await hx.capture({
  type: 'message',
  sessionId: 'sess-1',
  payload: { role: 'user', content: 'Deploy payment service to staging' }
});

// 2. Learn from experience
await hx.learn();

// 3. Synthesize context for decisions
const ctx = await hx.synthesize('deploy payment service');
console.log(ctx.entries); // Compressed, ranked knowledge with provenance

Zero-Config

Both auto and wrap() resolve configuration automatically:

1. Explicit options passed to wrap() or new Hippocortex()
2. Environment variables: HIPPOCORTEX_API_KEY, HIPPOCORTEX_BASE_URL
3. .hippocortex.json file (searched from cwd upward)

CLI Init Wizard

Auto-detect your framework and create a config file:

npx @hippocortex/sdk init

.hippocortex.json

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

API

new Hippocortex(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your API key (hx_live_... or hx_test_...) | | baseUrl | string | https://api.hippocortex.dev/v1 | API base URL | | timeoutMs | number | 30000 | Request timeout |

hx.capture(event) → Promise<CaptureResult>

Record an agent event (message, tool call, file edit, etc.).

hx.learn(options?) → Promise<LearnResult>

Trigger the Memory Compiler to extract patterns, playbooks, and policies.

hx.synthesize(query, options?) → Promise<SynthesizeResult>

Get compressed, provenance-tagged context for a query.

hx.listArtifacts(options?) → Promise<ArtifactListResult>

List compiled knowledge artifacts with filtering and pagination.

hx.getMetrics(options?) → Promise<MetricsResult>

Get usage statistics and performance metrics.

Auto-Memory Adapters

Adapters let you add memory to your agent with one line.

OpenClaw Adapter

import { autoMemory } from "@hippocortex/sdk/adapters";

const memory = autoMemory({ apiKey: "hx_live_..." });

// On incoming message — captures + returns synthesized context
const context = await memory.onMessage(userMessage);
if (context) {
  systemPrompt = context + "\n\n" + systemPrompt;
}

// After generating response
await memory.onResponse(assistantMessage);

// Capture tool events
await memory.onToolCall("exec", { command: "ls -la" });
await memory.onToolResult("exec", "file1.txt\nfile2.txt");

// Inject context into a messages array
const messages = await memory.injectIntoMessages(
  [{ role: "user", content: "deploy" }],
  "deploy"
);

Base Adapter (for custom integrations)

import { HippocortexAdapter } from "@hippocortex/sdk/adapters";

const adapter = new HippocortexAdapter({ apiKey: "hx_live_..." });

// Fire-and-forget capture
await adapter.capture("message", { role: "user", content: "hello" });

// Synthesize context (empty array on failure)
const entries = await adapter.synthesize("deploy service");

// Inject context into messages
const messages = await adapter.injectContext(
  [{ role: "user", content: "deploy" }],
  "deploy"
);

Key Behaviors

• Fire-and-forget: Capture never blocks your agent
• Error swallowing: All errors logged and swallowed — agent never crashes
• Graceful degradation: Returns empty context if server is unreachable
• Session tracking: Auto-generated session IDs

License

MIT