Artifacts API

Artifacts are compiled knowledge objects produced by the Memory Compiler. They represent what your agent has learned: step-by-step procedures, failure recovery playbooks, causal relationships, and decision rules.

Each artifact has a type, a confidence score based on how much evidence supports it, and a lifecycle status. The Artifacts API lets you browse, inspect, and manage these knowledge objects.

Artifact Types

Type	Content	Example
task_schema	Steps, preconditions, postconditions	"Deploy API: run tests, build image, push, deploy, verify"
failure_playbook	Symptoms, root causes, recovery steps	"Redis pool exhaustion: restart Redis, increase pool size"
causal_pattern	Cause, effect, frequency, mitigation	"High memory usage causes OOM kills during peak traffic"
decision_policy	Condition, actions, evidence	"If staging tests pass, auto-approve production deploy"

Artifact Lifecycle

Artifacts have three possible statuses:

Status	Retrieval	Compilation	Meaning
active	Included	Updated	Current, valid knowledge
deprecated	Excluded	Skipped	Manually marked as outdated
superseded	Excluded	Replaced	Automatically replaced by newer knowledge

The compiler automatically supersedes artifacts when new evidence contradicts them. You can manually deprecate artifacts that are no longer relevant.

GET /v1/artifacts

List compiled artifacts with filtering and pagination.

curl "https://api.hippocortex.dev/v1/artifacts?type=failure_playbook&status=active&sort=confidence&order=desc&limit=10" \
  -H "Authorization: Bearer hx_live_..."

Query Parameters

Parameter	Default	Options
type	all	task_schema, failure_playbook, causal_pattern, decision_policy
status	all	active, deprecated, superseded
sort	createdAt	createdAt, updatedAt, confidence, evidenceCount
order	desc	asc, desc
limit	20	1-100
cursor	-	Pagination cursor from previous response

Response

{
  "ok": true,
  "data": {
    "artifacts": [
      {
        "id": "art-001",
        "type": "failure_playbook",
        "status": "active",
        "title": "Database Connection Pool Exhaustion",
        "content": {
          "symptoms": ["Connection timeout errors"],
          "rootCauses": ["Missing connection release"],
          "recoverySteps": ["Check pg_stat_activity", "Restart pooler"]
        },
        "confidence": 0.92,
        "evidenceCount": 8,
        "createdAt": "2025-01-10T14:00:00Z",
        "updatedAt": "2025-01-15T09:30:00Z"
      }
    ],
    "pagination": {
      "hasMore": true,
      "cursor": "eyJpZCI6ImFydC0wMTAifQ",
      "total": 42
    }
  }
}

GET /v1/artifacts/:id

Get a single artifact by ID, including full content.

curl "https://api.hippocortex.dev/v1/artifacts/art-001" \
  -H "Authorization: Bearer hx_live_..."

DELETE /v1/artifacts/:id

Delete a single artifact. This is permanent.

curl -X DELETE "https://api.hippocortex.dev/v1/artifacts/art-001" \
  -H "Authorization: Bearer hx_live_..."

Pagination

Use cursor-based pagination for large result sets:

# First page
curl "https://api.hippocortex.dev/v1/artifacts?limit=20" -H "Authorization: Bearer hx_live_..."

# Next page
curl "https://api.hippocortex.dev/v1/artifacts?limit=20&cursor=eyJpZCI6ImFydC0wMjAifQ" -H "Authorization: Bearer hx_live_..."