Observe

POST /v1/observe

Record ordinary memory, execution evidence, handoff state, or explicit claims.

Call this after the host learns something that should be available to future guide calls.

Request body

Field	Type	Required	Description
`tenant_id`	string	No	Tenant boundary. Defaults to local Runtime tenant.
`scope`	string	No	Project or workspace boundary. Keep stable across calls.
`actor`	string	No	Human or service actor writing the evidence.
`input_text`	string	Conditional	Natural language memory or execution text. Required unless using `nodes`, `edges`, `handoff`, or `claims`.
`memory`	object	No	Ordinary memory metadata such as `kind`, `memory_lane`, owners, lifecycle, and target files.
`execution`	object	No	Execution event metadata: run, task, outcome, files, tools, verifier, evidence refs.
`handoff`	object	No	Handoff packet for cross-session or cross-agent continuation.
`claims`	array	No	Claim ledger writes.
`auto_embed`	boolean	No	Whether to embed written memory.

At least one memory input, handoff payload, or claim is required.

Example: ordinary memory


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "input_text": "Prefer small patches and verify before broad refactors.",
    "memory": {
      "kind": "preference",
      "memory_lane": "private",
      "owner_agent_id": "worker-1"
    }
  }'

Example: execution evidence


curl -s http://127.0.0.1:3001/v1/observe \
  -H 'content-type: application/json' \
  -d '{
    "tenant_id": "default",
    "scope": "checkout-migration",
    "input_text": "New adapter path passed verifier review.",
    "execution": {
      "run_id": "run-001",
      "agent_id": "worker-1",
      "task_signature": "checkout-migration",
      "title": "Adapter implementation",
      "summary": "Implemented the scoped adapter route and validation passed.",
      "outcome": "succeeded",
      "target_files": ["src/checkout/adapter.ts"],
      "acceptance_checks": ["unit tests passed", "reviewer accepted"]
    }
  }'

SDK


await aionis.observe({
  input_text: "New adapter path passed verifier review.",
  execution: {
    run_id: "run-001",
    agent_id: "worker-1",
    task_signature: "checkout-migration",
    title: "Adapter implementation",
    summary: "Implemented the scoped adapter route and validation passed.",
    outcome: "succeeded",
    target_files: ["src/checkout/adapter.ts"],
  },
});

Response


{
  "contract_version": "aionis_observe_result_v1",
  "tenant_id": "default",
  "scope": "checkout-migration",
  "observed": {
    "memory_written": true,
    "handoff_stored": false,
    "general_memory_count": 0,
    "execution_memory_count": 1
  },
  "source_map": {
    "routes_used": ["/v1/memory/write"]
  }
}

Common errors

Error	Fix
`observe_requires_memory_or_handoff`	Send `input_text` with `memory` or `execution`, a `handoff`, or `claims`.
Validation error	Remove unsupported fields from strict nested objects such as `execution`.
Missing recall later	Check that later `/v1/guide` calls use the same `tenant_id` and `scope`.