Contracts and routes

Use this section when you already understand the product shape and need route-level or SDK-level detail.

Reference map

This section is the bridge between product docs and raw repository contracts. Use it when you need to know which public surface exists, which route backs it, and where the literal source of truth lives.

MemoryPolicy memoryHandoffReplayAutomation + sandboxRaw contracts

Route family

Memory

/v1/memory/*

Write, recall, planning, task start, lifecycle reuse, sessions, tools, and review helpers.

Cross-cutting surface

Policy Memory

feedback -> experience -> review -> governance

Persisted policy contracts, evolution inspect, and the retire/reactivate governance path.

Route family

Handoff

/v1/handoff/*

Pause and resume through explicit handoff packets and anchor-based recovery.

Route family

Replay

/v1/memory/replay/*

Run lifecycle, playbooks, promotion, dispatch, repair, and local reuse.

Route family

Review

/v1/memory/*review*

Continuity review packs, evolution review packs, and replay repair review.

Route family

Automation

/v1/automations/*

Validate, create, run, inspect, resume, and cancel Lite automation graphs.

Route family

Sandbox

/v1/memory/sandbox/*

Create sessions, execute bounded commands, and inspect logs and artifacts.

How to read this page

Think in route families first, not single endpoints. Most integration mistakes happen when teams read one method in isolation and miss the surrounding continuity loop.

Best entry points

Start with the page that matches the runtime surface you are integrating:

• Memory
• Policy Memory and Evolution
• Handoff
• Replay and Playbooks
• Review Runtime
• SDK Quickstart
• Lite Config and Operations
• Automation
• Sandbox

Reference family

Memory

Write, recall, planning, task start, sessions, tools, review packs, and delegation-learning helpers.

Cross-cutting surface

Policy Memory and Evolution

Read how feedback can materialize policy memory, how review exposes evolution inspect, and how governance retires or reactivates learned policy.

Reference family

Handoff

Structured pause and resume, task anchors, and the handoff path into host-task sessions.

Reference family

Replay and Playbooks

Replay lifecycle, playbook compilation, promotion, repair, and Lite execution reuse.

Reference family

Review Runtime

Continuity review packs, evolution review packs, and replay repair review in the Lite governed subset.

How to use this section

Use this section in two passes:

1. stay in the docs site for the public surface and family-level understanding
2. only open raw contracts when you need exact field names or source-level debugging

For most integrations, you should not need to start from raw TypeScript files.

Public route families

Family	Main job	Start here
Memory	Write, recall, planning, task start, sessions, lifecycle	Memory
Action retrieval	Retrieve the next move explicitly, with evidence, uncertainty, and gate surfaces	Action Retrieval
Policy memory	Persist, inspect, and govern self-evolving policy state	Policy Memory and Evolution
Handoff	Pause, store, recover, and resume task state	Handoff
Replay	Record runs, compile playbooks, promote and reuse	Replay and Playbooks
Review	Build continuity/evolution review material and review replay repairs	Review Runtime
Automation	Validate, create, run, pause, and resume local automation graphs	Automation
Sandbox	Execute bounded local runtime actions and inspect logs/artifacts	Sandbox
Runtime operations	Boot, health, config, Lite boundary	Lite Runtime
SDK integration	Call the runtime from TypeScript	SDK Quickstart

Common lookup tasks

If you are trying to answer...	Read this page first
"How do I ask for a better first action?"	Memory
"How do I ask what the agent should do next, and why?"	Action Retrieval
"How do I know when the runtime wants inspect / widen recall / rehydrate first?"	Uncertainty and Gates
"How do I turn gate output into a host action?"	Operator Projection and Action Hints
"How do I inspect or govern self-evolving policy state?"	Policy Memory and Evolution
"How do I pause work and resume it later?"	Handoff
"How do I turn a successful run into something reusable?"	Replay and Playbooks
"How do I validate or run an automation graph?"	Automation
"How do I execute bounded local commands and inspect outputs?"	Sandbox
"How do I get review-ready runtime state?"	Review Runtime
"Which route families are really in Lite?"	Lite Runtime
"How do I integrate this from code?"	SDK Quickstart

What the public docs already cover

The docs site already explains:

• the runtime model
• the main continuity surfaces
• the explicit action-retrieval and gate surfaces
• the public SDK integration path
• the Lite runtime boundary
• the most important memory, handoff, and replay families

That means the raw repository references should be the second stop, not the first one.

Reference rule

Use the docs site for shape and meaning. Use raw contracts only when you need exact field names, support boundaries, or source-level debugging.

Raw sources when you need exactness

Sometimes you do need the literal source of truth. Use the raw sources below only when the docs page above is not enough.

SDK contracts

The main typed SDK request and response shapes live here:

• packages/full-sdk/src/contracts.ts

Use that file when you need:

• memory request shapes
• replay payload shapes
• handoff envelopes
• automation and sandbox contracts

Runtime capability matrix

The best raw route-level reference today is:

• LOCAL_RUNTIME_API_CAPABILITY_MATRIX.md

Use it to answer:

1. which routes are supported
2. which are Lite subsets
3. which are conditional
4. which are intentionally unavailable in Lite

Runtime boundary

For public product boundary and open-core distribution stance:

• OPEN_CORE_BOUNDARY.md

Package-level references

• @ostinato/aionis
• @aionis/doc

How to use this page

Use this page for the public shape and integration path first.

When you need exact field-level detail, continue into:

1. the repository contract files
2. the capability matrix
3. the SDK contract sources