npm package: @hippocortex/sdk
Description: Official Hippocortex SDK — AI agent memory that learns from experience
Author: Hippocortex
Latest version: 1.2.1

# @hippocortex/sdk

Official JavaScript/TypeScript SDK for [Hippocortex](https://hippocortex.dev), AI agent memory that learns from experience.

## Install

```bash
npm install @hippocortex/sdk
```

## Quick Start

Choose the integration method that fits your workflow:

### Auto-Instrumentation (Easiest, 1 Line)

```typescript
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)

```typescript
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)

```typescript
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:

```bash
npx @hippocortex/sdk init
```

### .hippocortex.json

```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

```typescript
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)

```typescript
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