Hebbrix Documentation - AI Memory API Reference

Turn eligible execution evidence into reviewable hypotheses, then separately authorize one tightly constrained dispatch. A lesson, confidence score or ACT label is never a permit.

This workflow is separate from ordinary caller-reported Outcome Memory. It requires owner enrollment, authenticated source evidence, distinct scoped credentials and a constrained execution adapter. It does not run arbitrary tools, prove a lesson true, or automatically deploy a learned policy.

Authority boundaries

Role	What it may do
Owner session	Enroll/stop programs; define and explicitly activate a bounded permission policy. An API key cannot perform owner-only administration.
Registered worker · learning:reflect	Claim, bind one provider request, complete or report uncertainty. No automatic retry after dispatch.
Reviewer · learning:review	Review exact candidate and sequence/digest; mark eligible, blocked or retracted. Eligibility is not proof of truth.
Actor · learning:execute	Request and consume one short-lived permit for the exact invocation through the enrolled adapter.

Worked sandbox flow

All routes below use prefix /v1/learning/experiences. IDs and digests are placeholders from prior successful responses, not reusable credentials. First enroll and finish the separately protected source episode through the evidence-loop API. Ordinary POST /learning/decisions outcomes do not become authenticated source history merely by linking an ID. When no eligible sources exist, claim returns no_job: true; stop there.

As owner, register the program and its small fixed reflection budget.
As worker, claim with a stable request key. Read the returned canonical JSON input and verify its SHA-256. Bind the actual provider request before sending it once.
Complete with the real response digest, structured hypotheses and reported cost. On uncertain delivery, use the uncertainty route instead of retrying or inventing success.
As reviewer, inspect source evidence and exact candidate, then record a sequence-bound review. Poll any resulting memory’s indexing status before assuming it is searchable.
As owner, define then explicitly activate a permission policy bound to one sandbox target, actor, tool, action set and dispatch cap.
As actor, obtain a fresh ordinary decision for the program’s exact scope/context and selected allowed action. Request a permit referencing that decision and eligible lesson; then dispatch the exact invocation digest once. The API admits dispatch but does not execute the remote tool.

1. Owner: POST /programs

{
  "collection_id": "SOURCE_COLLECTION_ID",
  "memory_collection_id": "LESSON_COLLECTION_ID",
  "user_id": "sandbox-user", "policy_key": "sandbox.reply",
  "worker_key_id": "WORKER_KEY_ID", "reviewer_key_id": "REVIEWER_KEY_ID",
  "config": {
    "schema_version": "experience-reflection-config-v1",
    "model": "OWNER_APPROVED_MODEL", "applicability_keys": ["channel"],
    "maximum_attempts": 1, "budget_microusd": 100000,
    "per_attempt_microusd": 100000, "lease_seconds": 300
  }
}

2–3. Worker: bind the actual request and response

POST /programs/PROGRAM_ID/claim
{"request_key":"sandbox-reflection-1"}

POST /jobs/JOB_ID/dispatch
{"input_digest":"RETURNED_64_HEX_INPUT_DIGEST","request_digest":"ACTUAL_64_HEX_REQUEST_DIGEST"}

POST /jobs/JOB_ID/complete
{
  "request_digest":"ACTUAL_64_HEX_REQUEST_DIGEST",
  "provider_response_digest":"ACTUAL_64_HEX_RESPONSE_DIGEST",
  "reported_microusd":23000,
  "output":{"schema_version":"experience-reflection-output-v1","hypotheses":[{
    "advice":"Consider concise replies in this sandbox support channel.",
    "rationale":"The enrolled attempt received a favorable outcome.",
    "limitations":"One association does not establish causality or transfer.",
    "future_verification":"Compare fresh tasks against a fixed baseline with quality guards."
  }]}
}

The hypothesis above illustrates the format; do not submit it as a provider result. Costs are worker-reported with reservations, not independently audited invoices. Invalid output uses POST /jobs/{id}/reject-output. Uncertain delivery uses /uncertain with the bound request digest and an allowed reason such as completion_delivery_uncertain.

4. Reviewer: POST /lessons/LESSON_ID/reviews

{
  "expected_sequence":0, "expected_digest":null,
  "candidate_digest":"RETURNED_64_HEX_CANDIDATE_DIGEST",
  "verdict":"eligible",
  "rationale":"Reviewed only for the stated disposable sandbox context; limitations retained."
}

5. Owner: define, then activate

POST /programs/PROGRAM_ID/permission-policies
{
  "schema_version":"execution-permission-policy-v1",
  "actor_key_id":"ACTOR_KEY_ID", "tool_key":"sandbox.reply",
  "target_digest":"SHA256_OF_CANONICAL_TARGET_JSON",
  "action_keys":["concise"], "maximum_argument_bytes":1000,
  "maximum_dispatches":1, "permit_seconds":30,
  "capability_contract":"Disposable network-disabled sandbox only; no production, secrets or host files."
}

POST /programs/PROGRAM_ID/permission-activation
{"policy_id":"RETURNED_POLICY_ID","expected_sequence":0,"expected_digest":null,
 "rationale":"Owner explicitly authorizes this sandbox capability only."}

6. Actor: one exact invocation, one dispatch

POST /programs/PROGRAM_ID/permits
{
  "lesson_id":"REVIEWED_LESSON_ID", "decision_id":"FRESH_SCOPED_DECISION_ID",
  "request_key":"sandbox-dispatch-1",
  "invocation":{"tool_key":"sandbox.reply",
    "target":{"sandbox_id":"disposable","network":"disabled"},
    "arguments":{"text":"Synthetic sandbox response"}}
}

POST /permits/PERMIT_ID/dispatch
{"invocation_digest":"SHA256_OF_THE_EXACT_CANONICAL_INVOCATION"}

Canonical digests use SHA-256 of UTF-8 JSON with sorted keys, compact separators, ASCII escaping and no NaN. Compute them from actual documents; never copy the placeholders. Only a successful dispatch admission returns authorization_granted: true, scoped to that exact invocation through the constrained adapter. Issuance and subsequent GETs do not grant permission. Replays, expiry, revocation, changed evidence or changed review/policy state must fail closed. A permit is not remote execution attestation.

Inspect, stop and revise

Use GET /programs/{id}/lessons, GET /lessons/{id}, GET /lessons/{id}/reviews, GET /programs/{id}/permission-state and GET /permits/{id} with the appropriate identity. Reviews and revisions use compare-and-set sequence/digests. Stop a program with owner-only POST /programs/{id}/stop; deactivate permission by activating policy_id: null against the current permission sequence/digest. Do not restart closed experiments or reinterpret unknown outcomes as failures.

See the canonical nested request schemas for complete bounds and diagnostic variants, and ordinary learning and advisory autonomy for the simpler caller-reported loop. This page documents existing interfaces; it does not enroll a program or authorize spend.

Experiences, lessons & permits

Authority boundaries

Worked sandbox flow

Inspect, stop and revise