Capture API

The Capture endpoints ingest agent interaction events into Hippocortex memory. Every event your agent records becomes raw material for the Memory Compiler to analyze and extract knowledge from.

Capture is the entry point of the memory pipeline. Events flow through capture into the event store, where they wait for compilation (Learn) and can be retrieved as raw context (Synthesize). Each event is validated, assigned a salience score based on its content and type, and written to the database.

POST /v1/capture

Capture a single event.

curl -X POST https://api.hippocortex.dev/v1/capture \
  -H "Authorization: Bearer hx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool_call",
    "sessionId": "sess-42",
    "payload": {
      "tool": "deploy",
      "args": { "service": "api", "environment": "staging" }
    },
    "metadata": {
      "agentId": "agent-1",
      "correlationId": "corr-123"
    },
    "idempotencyKey": "idem-abc-123"
  }'

Request Body

Field	Type	Required	Description
type	string	Yes	Event type (see below)
sessionId	string	Yes	Session identifier grouping related events
payload	object	Yes	Event-specific data
metadata	object	No	Additional context (agentId, tags, etc.)
idempotencyKey	string	No	Client-provided deduplication key
namespace_id	string	No	Target namespace (enterprise)

Event Types

Type	Use For
message	User or assistant messages
tool_call	Agent invoking a tool
tool_result	Result returned from a tool
outcome	Final task outcome (success/failure)
observation	Agent observation or reasoning
file_change	File created, modified, or deleted
test_run	Test execution results

Response

{
  "ok": true,
  "data": {
    "eventId": "evt-abc123",
    "status": "ingested",
    "salienceScore": 0.72,
    "traceId": "trace-xyz"
  }
}

The salienceScore (0.0 to 1.0) indicates how important the event is for memory compilation. Higher scores mean the event contains more novel or significant information.

If you send the same idempotencyKey twice, the response returns "status": "duplicate" and the event is not stored again.

POST /v1/capture/batch

Capture up to 100 events in a single request. This is more efficient than individual calls when you have multiple events to record.

curl -X POST https://api.hippocortex.dev/v1/capture/batch \
  -H "Authorization: Bearer hx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "message", "sessionId": "s1", "payload": { "role": "user", "content": "Deploy" } },
      { "type": "tool_call", "sessionId": "s1", "payload": { "tool": "deploy" } }
    ]
  }'

Response

{
  "ok": true,
  "data": {
    "results": [...],
    "summary": {
      "total": 2,
      "ingested": 2,
      "duplicates": 0,
      "errors": 0
    }
  }
}

Best Practices

• Include metadata. The agentId and correlationId fields help the compiler group related events.
• Capture outcomes. Recording success/failure results enables the compiler to build failure playbooks.
• Use idempotency keys. Prevents duplicates when your agent retries operations.
• Batch when possible. Use /capture/batch to reduce HTTP overhead.
• Do not over-capture. Focus on significant actions (tool calls, decisions, errors), not every log line.