Hippocortex/Docs
GitHubDashboard

Integration Guide

This guide walks you through integrating Hippocortex into a production application. It covers choosing the right integration method, configuring sessions, structuring events, and following best practices.

Choosing an Integration Method

Hippocortex offers three integration paths. Each is production-ready. The choice depends on how much control you need.

MethodLines of CodeControl LevelBest For
Auto-instrumentation (import auto)1MinimalPrototyping, simple agents
Wrap (wrap(client))1ModerateProduction apps with OpenAI/Anthropic
Manual (new Hippocortex())VariableFullCustom agent loops, non-standard LLMs

Auto-instrumentation patches OpenAI and Anthropic SDK methods on import. Every LLM call automatically gets memory context injection and conversation capture. No other code changes needed.

Wrap creates a transparent proxy around a specific client instance. It gives you per-client control (different sessions, different configs) while keeping the same interface.

Manual gives you direct access to capture(), learn(), and synthesize(). Use this when your agent does not use the OpenAI or Anthropic SDKs, or when you need to capture custom events beyond LLM calls.

Session Management

Sessions group related events together. The compiler uses sessions to understand which events belong to the same task or conversation.

Automatic sessions: Auto-instrumentation and wrap() generate session IDs automatically. A new session starts with each process or can be set explicitly.

Explicit sessions: Pass sessionId when wrapping or capturing:

const openai = wrap(new OpenAI(), { sessionId: 'deploy-v2.4.1' })

client = wrap(OpenAI(), session_id="deploy-v2.4.1")

Good session ID patterns: task-based (deploy-api-v2), conversation-based (chat-user-123-001), or time-based (daily-report-2025-01-15).

Structuring Events for Quality Memory

The quality of your agent's memory depends on the quality of captured events. Follow these guidelines:

Include context in metadata. Add agentId, correlationId, and relevant tags to every event. This helps the compiler group related events across sessions.

Capture outcomes, not just actions. Record whether a tool call succeeded or failed. Include error messages. The compiler extracts failure playbooks from these patterns.

Use idempotency keys. If your agent might retry an action, include an idempotencyKey to prevent duplicate events.

Capture at the right granularity. Not every log line needs to be an event. Focus on significant actions: tool calls, decisions, errors, and outcomes.

Production Checklist

Before going to production:

  1. Switch to live keys. Replace hx_test_* with hx_live_* keys.
  2. Set up key rotation. Create a process for periodic key rotation.
  3. Configure error handling. The SDK fails silently by default (memory errors should not crash your agent). Verify this behavior fits your needs.
  4. Schedule learn() calls. Run incremental compilation after batches of events, not after every single capture. A good default is every 100 events or every hour.
  5. Set token budgets. Configure maxTokens in synthesize calls to match your model's context window minus your prompt and expected output.
  6. Monitor usage. Check the dashboard for event volume, compilation time, and retrieval latency.

Error Handling

The SDK is designed to be non-blocking. Memory operations should never crash your agent.

// The SDK catches errors internally and logs them
// Your agent continues even if Hippocortex is unreachable
import '@hippocortex/sdk/auto'
// If the API is down, LLM calls proceed without memory

For explicit error handling with the manual client:

try {
  await hx.capture({ type: 'tool_call', sessionId: 's1', payload: { ... } })
} catch (err) {
  console.warn('Memory capture failed:', err.message)
  // Agent continues without memory
}

Next Steps