Learn API

The Learn endpoint triggers the Memory Compiler, which processes accumulated events into semantic memories and compiled artifacts. This is the step where raw interactions become usable memory.

How Compilation Works

When you call Learn, the system queues an async compilation job that:

1. Retrieves events. Fetches unprocessed events for the tenant.
2. Extracts patterns. Identifies recurring patterns across events.
3. Generates artifacts. Creates structured knowledge objects from detected patterns.
4. Scores confidence. Assigns confidence based on evidence count and recency.

The compiler produces several artifact types:

Type	What It Extracts
Task Schema	Step-by-step procedures from successful task completions
Failure Playbook	Failure modes with symptoms, root causes, and recovery steps
Causal Pattern	Cause-and-effect relationships observed across events
Decision Policy	Conditional rules extracted from decision patterns

POST /v1/learn

The endpoint accepts an optional request body. An empty body processes all unprocessed events for the tenant.

curl -X POST https://api.hippocortex.dev/v1/learn \
  -H "Authorization: Bearer hx_live_..." \
  -H "Content-Type: application/json" \
  -d '{}'

Request Body

All fields are optional. An empty body {} is valid and processes all unprocessed events.

Field	Type	Description
agentId	string	Limit compilation to events from a specific agent
sessionId	string	Limit compilation to events from a specific session
eventIds	string[]	Process specific event IDs only
options.maxEvents	number	Maximum number of events to process
options.artifactType	string	Filter to a specific artifact type

Response

{
  "ok": true,
  "data": {
    "jobId": "job-abc123",
    "status": "queued"
  },
  "meta": {
    "requestId": "req-xyz",
    "tenantId": "tenant-abc",
    "durationMs": 5
  }
}

Compilation runs asynchronously. The response confirms the job has been queued. Results are visible via the artifacts endpoint once processing completes.

Auto-Compile

You do not need to call Learn manually in most cases. The auto-compile pipeline triggers automatically after every 10 captured events, with a 5-minute sweep for stragglers. This ensures your agent's knowledge base grows continuously without intervention.

Best Practices

1. Let auto-compile handle it. Manual Learn calls are rarely needed in production.
2. Use eventIds for targeted recompilation. When you know specific events need processing.
3. Use agentId or sessionId filters. To scope compilation to a specific agent or session.