# Kam documentation

Pinned source review, not live service health or deployment evidence.

Website documentation only. No cloud calls, local commands, or model inference are executed by this document.

# Explore State through connected examples

Discover History, operational memory, context zoom, dependencies, access, efficiency, and recovery through a software-release or NFL-shaped scenario.

Status: Implemented in source. Prelaunch; not a live service guarantee.
The explorer is implemented in website source. Its finite authored simulations do not run the Rust engine, contact AWS, execute agents, or certify live permissions. Product capability availability is stated separately.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/explore

## In short

Try a public example and inspect it through seven connected views. Compare a correction, find stale work, focus the selected context, or examine a denied read. The examples are teaching simulations, not live engine results.

**Available today:** An interactive website feature with authored public fixtures. No backend, AWS, or model execution.

> Find a familiar problem, change a fixture, and inspect the exact consequence and its limits.

## Inspect a correction

- **Select the corrected point** — Use the synthetic release example.
- **Trace its input** — Graph shows the exact recorded relationship.
- **Read both versions** — Timeline and inspection share the selected point.

## Browse by problem or capability

Choose a problem such as lost context, stale results, repeated work, or denied access. All seven views share the same selected scenario, event, record, and version. You can explore freely or follow the optional three-stop guide.

[Open the workspace example](/?capability=workflows#trajectory)

## Three statuses that must not be confused

1. **Capability availability** — Whether the underlying product capability is implemented in source, local only, or planned. A working website interaction does not make a planned managed service available.

2. **Demonstration mode** — Public synthetic fixtures. No engine, AWS, agent, or model is running on this page.

3. **Scenario result** — Accepted, stale, pending, expired, and denied are states inside a public fixture. They are not live production results.

> **Recorded and live evidence**
> Recorded engine runs require their real captured output and artifact identity. A live demonstration needs a separately qualified endpoint and permission boundary. This explorer currently provides neither.

## Git-like History

Compare exact versions without overwriting the earlier record.

Exact revisions + generation-pinned membership

Exact History is implemented in source, not hosted here. Git-like describes version history, not Git compatibility, branching, or undoing external actions.

[Read the underlying contract](/docs/history)

## Operational Memory

Keep accepted results and unfinished work distinct from a worker’s memory.

Retained outcomes + durable obligations + exact reads

History and durable obligations exist in source. Managed cross-agent handoff is planned; this is not universal conversational or vector memory.

[Read the underlying contract](/docs/durability)

## Context Zoom

Move from an overview to a record and its exact evidence.

Scoped Views + exact references + independent byte budgets

Local Turn Frames exist. Managed context zoom and full provider-request budgets are planned. Displayed JSON bytes are not model tokens.

[Read the underlying contract](/docs/context)

## Workflow Dependencies

Replay a workflow’s History, read only: every version, the exact versions each step read, and what a correction reached.

Ordered membership + explicit dependencies + current authority

Versions, kept corrections, and dependency marking exist in source. Customer workflow management is planned. The replay is read only: it registers no schedules and invokes no adapters.

[Read the underlying contract](/docs/normalized-state)

## Scoped Access

Explore access boundaries, expired authority, and denied reads.

Principal → authorized workspace → bounded exact read

Authorization controls are implemented in source. This synthetic decision is not a live IAM test, compliance certification, or proof of deployed isolation.

[Read the underlying contract](/docs/engineering-review)

## Reuse & Efficiency

Distinguish batching, reusable inputs, and affected work from model caching.

Exact input comparison + bounded reads + dependency re-evaluation

Bounded reads and local comparison reuse exist. General calculation caching is planned. Fixture counts are not AWS cost, latency, or token-savings measurements.

[Read the underlying contract](/docs/state-api)

## Durable Recovery

Follow an accepted result and the publication still owed after a failure.

Stable submission identity + accepted receipt + unfinished obligation

Recovery paths are implemented and tested offline. The example is not a live process-restart drill or a guarantee of exactly-once external effects.

[Read the underlying contract](/docs/durability)

## Share the view, not private context

Copy link includes only finite public scenario IDs, record selections, and display settings. Free-text search, credentials, private tenant data, and arbitrary URL parameters are not copied. Browser Back and Forward restore earlier selections; Reset returns to the start of the selected scenario. No account is required.

## Counts, bytes, and tokens have different meanings

Context bytes are counted from the displayed fixture JSON. They do not measure a complete provider request or model tokens. Required evidence is never silently removed to satisfy the byte budget.

Efficiency counts describe the four fixture records and listed affected outputs. An unchanged record is not an observed cache hit. Batching, exact-input reuse, dependency re-evaluation, and model prompt caching are separate mechanisms. This demonstration contains no cost, latency, token-savings, or provider-cache measurement.

## Explore without dragging or a mouse

Use ordinary buttons and selects for every action. The dependency map exposes each record as a keyboard-focusable button. Inspector tabs support Left/Right, Home, and End. Status is written in text as well as color. There is no autoplay, and reduced-motion preferences are respected. A static guide remains available without JavaScript.

## Follow the same example in a walkthrough

The planned founder walkthrough can link each chapter to a public explorer selection. No video, live NFL feed, or live AgentCore demo is linked until that material has been produced and qualified. The current NFL scenario uses fictional teams and authored scores; it is not a current league result.

# Normalized objects and versioned collections

How exact identities, ordered membership, materialized Views, and injected adapters could extend Kam beyond its initial UTC-day History workload without changing existing contracts.

Status: Planned · not available. Prelaunch; not a live service guarantee.
Architecture direction, not a public generalized collection SDK. Existing allIds()/byIds() remain UTC-day History operations; the published State Selection candidate is restricted to one Active State evidence-reference collection. No managed/customer-owned S3 snapshot service is qualified.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/normalized-state

## In short

Where byIds and allIds go next: one exact object referenced from many scoped, versioned collections, with materialized Views reused when nothing they read has changed. This is the design direction for generalizing today's History adapter, not a shipped service.

**Available today:** Planned. Today allIds() and byIds() serve UTC-day History only.

> Store one exact object; reference it from many scoped collections; reuse unchanged materializations.

## Existing contract and proposed direction

- **History today** — Exact revisions and pinned UTC-day membership.
- **State candidate** — One Active State evidence-reference collection.
- **General collections** — Proposed adapters; no generalized public SDK.

## One Rust State engine; many typed collections

The foundational distinction is identity versus membership. Exact identity answers which retained object revision is requested. Collection membership answers which exact references belong to a particular ordered, pinned generation. A consumer can enumerate references and hydrate only selected records.

The existing History adapter uses a specific tenant/subject/type, UTC day and generation. That is one supported vertical, not a universal requirement that every future collection be date-based. General collection adapters, including project builds, documents, and tasks, are architectural direction only.

Knowledge is information represented as typed State, with provenance and review status where applicable. Context is a consumer-specific View selecting authorized references. Neither needs a second State engine.

1. **Exact object** — Stable identity plus exact revision and declared availability. A stored build record is not proof that the artifact is safe to reuse.

2. **Versioned membership** — An ordered collection of exact references with a pinned generation. Membership can change without duplicating objects.

3. **Materialized View** — A derived result with exact source/definition references, applicability, and its own publication boundary.

4. **Consumer Context View** — A task-scoped selection of eligible State/evidence references; permission is rechecked when serving.

## What the current History API actually guarantees

allIds() pages one bounded UTC-day generation. Generation-bound byIds() verifies exact membership; direct byIds() resolves known exact revisions without a membership claim. Missing, unresolved and expired evidence stays explicit; neither API silently follows the latest revision.

The existing Rust State engine already supports versioned Views, dependency membership, change detection and bounded reconciliation. The generalized collection contract described here must reuse those mechanisms rather than create parallel reducers or dirty-propagation loops.

[Existing History API and exact references](/docs/history)

[State queries and supported operators](/docs/state-api)

[Engineering contract](/docs/engineering-review)

## Adapter boundaries, not a different engine per vertical

1. **History adapter — implemented scope** — UTC-day ordered outcomes, specific revisions, retention and correction rules.

2. **Project collection — proposed** — Enumerate exact build, test, and task references by project instead of date; no build-specific inference or compiler required.

3. **Temporal collection — proposed** — Use explicit time and versioned rules as View inputs, so durable source facts may drive new bounded projections without being rewritten each year.

4. **Context collection — proposed** — Select exact evidence references for one consumer and budget; representation is separate from the original payload.

> **Dependency injection boundary**
> Adapters supply scoped access, membership policies, storage ports, and lifecycle configuration. Rust remains the semantic authority for supported deterministic validation and publication.

## Keep the existing dependency DAG

A changed source makes its affected dependent Views dirty. The existing reconciliation lifecycle evaluates bounded affected work and conditionally publishes. Within one traversal, a visited set avoids duplicate work. Across turns, an unchanged applicable materialization can be reused rather than recalculated.

A future nested collection may reference exact child generations, but the parent must pin each child version; old parents must not silently retrieve newer children. Traversal requires total depth, node, edge, byte, and read limits. A trie or Merkle DAG is an optional measured indexing optimization, not a prerequisite.

## Hot State and durable snapshots have different jobs

The target storage architecture uses DynamoDB for operational pointers, indexed membership and durable work. Immutable evidence and snapshots may live in an approved S3 store. Kam-managed and customer-owned S3 are proposed storage-ownership modes, not existing product offerings.

Retention, snapshot interval, application validity and hot working-set policy are distinct. Customers might select multi-year retention while only occasionally changing State. The current 365-UTC-date working History window is a real existing contract; generalizing future lifecycles must preserve it until separately migrated and qualified.

Snapshot publication must verify the exact durable object before advancing a conditional hot-State pointer. DynamoDB and S3 do not share a transaction. An absent or inaccessible archived object must not silently resolve to latest.

[Existing retention guarantees](/docs/retention)

[Qualification status](/reliability)

## Illustrative: three agents share one build record

Agent A submits a build result under a stable application-supplied ID. Agents B and C can retrieve the same authorized record or see it in different project collections without copying its payload. A new build gets a distinct exact identity or revision according to the declared producer contract.

Reusing the compiled artifact still depends on an external build cache and its compatibility checks. Kam does not compile Rust, certify arbitrary toolchains, infer build equivalence, or grant access because an agent knows an ID.

## Implementation boundary and next experiment

This document describes the intended generalization of existing primitives, not a shipped universal byIds/allIds service. Start by preserving the existing History adapter and qualifying one non-date, bounded collection through the real Rust engine, authorized reads, conditional publication, and recovery.

Only after that source-backed happy path should the website describe generic collections, customer-owned S3, durable Context Views or multiagent artifact reuse as available.

# Kam State documentation

Kam State keeps shared, versioned state for AI agents on Amazon Bedrock AgentCore. Start with what it records and what each read returns, then try one workload. Every guide labels what is built, what is planned, and what is not yet tested live.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs

## In short

Kam is a database for agent State with two primitives: byIds returns exactly the revision you named, and allIds returns a pinned, ordered collection with its evidence. Your systems of record stay where they are, and AgentCore keeps running the agents.

**Available today:** Exact History, Views, Active State reads and bounded State queries are implemented in source with the SDK 0.36.0 candidate. Metrics, materialize and watch are planned. Nothing is deployed.

> Kam AI is an AI-native State management infrastructure add-on designed for Amazon Bedrock AgentCore. One normalized State foundation uses byIds for exact identity and allIds for versioned ordered membership. The Rust semantic kernel coordinates accepted events, bounded dependencies, State transitions, evidence, and recoverable work. Exact History and bounded State contracts are implemented in source. A general managed event coordinator, control plane, lifecycle automation, and hosted workflows remain separately gated future service capabilities.

## What Kam does today

Your app sends results to Kam. Kam keeps each one as a numbered version, keeps corrections without erasing earlier versions, and returns the exact version you ask for, or says plainly that it cannot. Derived State is recomputed only where a change reaches it. Metrics, materialized views, and watch are planned.

Amazon Bedrock AgentCore runs the agents: runtime, model calls, tools, identity, policy, memory, and observability. Kam is the State those agents operate on. It does not replace your system of record or your agent runtime.

1. **Identity · Implemented in source** — Stable logical identity for every entity, so a correction updates the same thing instead of creating a duplicate.

2. **Versions · Implemented in source** — Immutable revisions. A newer revision never rewrites what an older read returned.

3. **Membership · Implemented in source** — A fixed, ordered list of the exact revisions that belong to one collection at one point in time.

4. **History · Implemented in source** — The retained record of accepted revisions, corrections, and published generations.

5. **Dependencies · Implemented in source** — Versioned records of which Views read which sources, so a change can find exactly what it affects.

6. **Views · Implemented in source** — Bounded, owner-configured definitions over source State, normalized and hash-bound by Rust.

7. **Materialization · Implemented in source** — Conditionally committed Active State for bounded same-scope Views with one or more sources. Not deployed.

8. **Queries · Implemented in source** — Bounded where, pick, orderBy and take over one Active State's evidence, with explain() before value().

9. **Replay · Implemented in source** — Re-run synthetic scenarios against the real Rust engine and explain why State changed or was reused.

10. **Metrics · Planned · not available** — General derived metrics that recompute when an input changes. Today only rolling outcome comparisons are implemented.

11. **Watch · Planned · not available** — Customer subscriptions that fire when a materialized view changes.

## Three questions Kam answers today

1. **What exact evidence existed?** — History preserves accepted revisions and fixed membership under stable identity.

2. **What changed and what can be reused?** — Versioned Views and State reconciliation separate affected dependencies from retained immutable evidence.

3. **What should this reasoning turn see?** — The native candidate prepares local reference-only Turn Frames; the managed Context and Turn Lifecycle remain staged.

> **Current release boundary**
> Marketplace availability, production p99, and production AgentCore write-back remain qualification gates. The delivery loop is implemented, disabled by default, and tested through simulated transport. This is not live production qualification.

[Follow the History example](/?capability=workflows#trajectory)

[Read the State API design](/docs/state-api)

## Choose the right entry point

Start with the History SDK. Views, current-State reads, and bounded queries are built in the SDK 0.36.0 candidate, which is not on npm. The toolkit runs locally. Nothing here is deployed or listed on AWS Marketplace yet.

[Normalized State and collection architecture](/docs/normalized-state)

[State queries and the design preview](/docs/state-api)

[State and required evidence](/docs/state)

[Native toolkit](/docs/toolkit)

[What changed](/updates)

## A rolling view, not permanent recall

The working history covers 365 UTC dates. Supporting evidence has its own inspection limits. A recovery checkpoint is saved processing state, not a lifetime summary.

[Read the retention contract](/docs/retention)

# State queries, Components, and what comes next

What the SDK 0.36.0 candidate implements today (scoped State, Components, and bounded queries with explain() and value()) and the planned direction for metrics, materialized views, and watch.

Status: Implemented in source. Prelaunch; not a live service guarantee.
The reviewed SDK 0.36.0 baseline, unpublished and undeployed, implements state(), component(), and bounded select stages (where, pick, orderBy, take) with explain() and value() over the admitted evidence of one View's Active State. SDK 0.37.0 merged in PR #220 (not publicly published and not included in the pinned 0.36.0 website qualification) adds bounded operators over that same selected collection. General source-payload queries, managed metrics, calculation caching, graph traversal, materialize(), watch(), and lifecycle integration remain separate planned capabilities.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/state-api

## In short

Bind a scope, name a View as a Component, and select its current evidence with where, pick, orderBy and take. Kam admits a bounded plan before anything runs. Materialized views, metrics and watch are the planned next step.

**Available today:** Queries and Components are in the unpublished SDK 0.36.0 candidate. Materialize, watch and metrics are a design preview.

> Write what you want from State. Kam admits a bounded plan before it runs.

## SDK 0.36.0 candidate

- **Implemented** — Select, explain, and run a bounded State query.
- **Read the plan** — Inspect work limits before value().
- **Design preview** — Metrics, materialize, and watch remain planned.

## Implemented in the SDK 0.36.0 candidate

state({ subjectId, type }) binds one scope; component() names a maintained View. Declarations perform no I/O. A query selects from the admitted evidence references of that View’s current Active State, not from arbitrary source payloads.

Rust admits the plan before anything runs: tenant-bound, at most 16 stages, 32 pick paths, take ≤ 32 as the terminal stage, at most 34 storage reads, and never a table scan. value() re-reads and re-checks current State, and only a current result carries items.

### Bounded State query — every call exists in the SDK 0.36.0 typings

```javascript
// SDK 0.36.0 candidate · implemented in source · not on npm, not deployed
const deployment = kam.state({ subjectId: 'checkout', type: 'deployment' });
const history = deployment.component('trajectory-current');

const required = history.query()
  .where('required', 'eq', true)
  .orderBy('key', 'asc')
  .pick(['key', 'revision', 'source.id'])
  .take(5);

// Inspect the plan before it runs.
const plan = await required.explain();

// Execute over the admitted Active State's evidence references.
const result = await required.value();
if (result.status === 'current') console.log(result.items);
// absent, blocked and stale results carry no usable items.
```

## Merged, not requalified: SDK 0.37.0 / PR #220

The merged backend candidate adds thirteen bounded stages: chunk, flattenDepth, differenceBy, intersectionBy, indexUnique, distinctExact, diffRevisions, partition, groupBy, countBy, sumIntBy, allMatch, anyMatch. The reviewed 0.36.0 baseline remains the pinned website qualification; the merged 0.37.0 source has not been independently requalified for this website review.

Merged in PR #220, not published, and not requalified for this website review. These operators run only over one verified Active State's selected evidence-reference collection. They do not query arbitrary customer payloads, establish external completeness, provide a managed metrics service, or add an AgentCore lifecycle adapter.

## What explain() returns

These are the fixed fields of the plan type in the SDK typings, not a captured response or a latency measurement. explain() reports the bound; it does not perform the reads.

### StateQueryPlan fields (SDK 0.36.0 typings)

```text
explain() → kam.state-query-plan.v1     (fields from the SDK 0.36.0 typings)
  storageAccess        tenant_bound_verified_active_state_read
  maxStorageReads      34
  tableScan            false
  crossTenant          false
  limits               16 stages · 32 pick paths · take ≤ 32
  executionAvailable   true
```

## Design preview: collections, materialized views, and watch

The direction beyond today’s SDK: chain operators over named source collections, keep the result materialized, and recompute it only when an input it reads changes.

Naming in the preview follows one concept: source collections are plural nouns (customers, subscriptions); derived views and metrics are camelCase descriptions of what they hold (atRiskCustomers, businessHealth).

### Design preview — collection sources, materialize and watch are not available

```javascript
// DESIGN PREVIEW · collection sources, materialize and watch are not available in any SDK
const atRiskCustomers = kam
  .state('customers')
  .where(lt('health', 0.6))
  .pick(['id', 'mrr', 'health', 'renewalDate'])
  .orderBy('mrr', 'desc')
  .take(100)
  .materialize('atRiskCustomers');

// Run your agent only when this view changes.
atRiskCustomers.watch(change => startCustomerSuccessAgent(change));

// Ask how Kam will execute it before it runs.
atRiskCustomers.explain();
```

## A small set of composable operators

1. **Select: where, pick, orderBy, take** — Filter, project, and bound one Active State's evidence. In SDK 0.36.0.

2. **Plan & run: explain, value** — See the bounded plan, then execute it. In SDK 0.36.0.

3. **Combine: group, union, diff, expand, hydrate** — Relate collections and resolve references to exact revisions. Planned.

4. **Aggregate: count, sum, mean, reduce** — Derive metrics that update incrementally as inputs change. Planned.

5. **Operate: materialize, watch** — Keep a result current and react when it changes. Planned.

## Metrics recompute on change, not on every read

In the synthetic example, one subscription is upgraded. Kam recomputes mrr, arr, businessHealth because each reads the changed input. churnRate, dailyActiveUsers, p99Latency, supportSla read other inputs, so their existing values are reused.

The executive agent watching businessHealth wakes. Agents watching the other 4 metrics stay asleep.

Synthetic example of the planned metrics model. Counts are derived nodes in this diagram (3 of 7 recomputed, found by graph reachability from the changed input), not a measured benchmark.

## Run AI when relevant State changes

watch() is the planned way to start work: subscribe to a materialized view and receive the change, including the exact revisions that caused it. Your code decides what to do, such as invoking an AgentCore agent. A timer that wakes every agent to re-read the world becomes unnecessary for that view.

Customer realtime subscriptions are not implemented. The current internal event path is bounded and maintenance-redrivable, and it is not a public subscription API.

## Authorization, work limits, and deadlines are separate controls

Today’s State queries already carry fixed work bounds. The planned general work envelope (maxReads, maxItems, maxBytes, maxDepth, maxFanout, maxRetries, deadline) extends those consumption limits to joins, aggregates and metrics.

Authorization independently restricts which data and operations the principal may access. A small unauthorized read is still unauthorized. Deadlines and retry policy determine how long the caller waits and what happens when bounded work does not finish.

The planner bounds the operation’s work. It does not establish a latency guarantee; measured latency and convergence require a declared workload.

1. **Cross-tenant access · Implemented in source** — The server resolves the authorized tenant; a caller-supplied tenant ID is not authorization.

2. **Silent mutation · Implemented in source** — Revisions are immutable. Corrections add a revision and keep the earlier one inspectable.

3. **Model output becoming truth · Implemented in source** — Only your application declares results. No model, reducer, or AgentCore call fills a missing record.

4. **Oversized reads · Implemented in source** — History pages and View membership sets have explicit limits and cursors.

5. **Unbounded traversal · Implemented in source** — View dependency membership is bounded and cycles are rejected at registration.

6. **Stale or duplicate work · Implemented in source** — Commit-time fences reject work whose lifecycle, membership, or source version has moved.

7. **Unbounded State queries · Implemented in source** — Rust admits a query plan before execution: tenant-bound, at most 16 stages, 32 pick paths, take ≤ 32 and 34 storage reads, and never a table scan.

8. **Per-query cost explosions · Planned · not available** — A general declared envelope (maxReads, maxItems, maxBytes, maxDepth, maxFanout, deadline) for joins, aggregates and metrics, checked before execution.

9. **Acting on stale State · Planned · not available** — Revalidate the exact State a decision read before a consequential external action.

## A specialized database, not a replacement

Kam is a specialized, DynamoDB-backed State database for AI-native applications. Your databases stay authoritative for their business records. Kam is authoritative for the State it accepts: its revision identities, membership, and publication history.

Store the State worth reusing, not every byte worth keeping.

Not offered, by design: general SQL, arbitrary joins, or transactions across your other data sources.

## Where to start

Evaluate the History contract and one bounded View with the SDK candidate against an authorized endpoint. Metrics, materialize and watch are shaped by those evaluations.

[Integrate one structured workload](/docs/integrate)

[Read the State contract](/docs/state)

# Integrate one structured workload

Keep your agent and business rules. Send explicit completed outcomes through the repository-local SDK.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/integrate

## In short

Your application sends Kam small structured results: what happened, to which thing, when, and whether it succeeded. Kam keeps every version of those results so you can read back exactly what was recorded.

**Available today:** Available as a candidate SDK (not on npm) against an authorized evaluation endpoint.

> Your application decides what success and failure mean; Kam maintains the history of what it accepts.

## One complete request and read

- **Authorize** — Evaluation endpoint and scoped identity required.
- **Record** — Submit an outcome; retry the same identity.
- **Read exactly** — Correct it, then request both retained revisions.

## Send identity, time, and a declared result

Supply ID, subject, type, occurrence time, status, category, and optional source references. Revision defaults to 1. The server resolves the authorized tenant; a supplied tenant ID is not authorization by itself.

Only success and failure are accepted. Do not convert pending, cancelled, or unknown results into failure just to fit the API. Occurrence time must be canonical UTC, not in the future, and within the working window.

[Read the scoped SDK example](/docs/integrate)

## Choose the read that matches your question

1. **outcome()** — Record a result, retry the exact same payload, or supply the next correction revision.

2. **allIds() → byIds()** — Browse a pinned UTC-day collection, then retrieve its exact revision references. Keep generation and cursor together.

3. **trajectory()** — Read precomputed last-ten and 30/90-day comparisons, with freshness and pending-work information.

4. **history() / why()** — Inspect accepted-revision history or a deterministic explanation of calculated values. why() is not causal investigation.

5. **deliveryStatus()** — Read metadata-only delivery counts, coverage, and oldest unfinished work. It does not return memory content.

> **Evaluation prerequisites**
> The SDK is repository-local, not a published npm package. An authorized service endpoint, principal, and tenant binding are required. No endpoint or credential is embedded in these pages.

## Bind a scope once; preserve the returned references

SDK 0.36.0 provides state({ subjectId, type }) (scope() is the same adapter) as a thin layer over the same API. It cannot override its bound subject or type and does not create a second state engine. Use the exact approved package or authorized source checkout; there is no public npm release.

### Read one bounded page using the existing SDK candidate

```javascript
// Save as a .mjs file in an authorized backend source checkout. SDK candidate 0.36.0.
// This is a read-only example, not code executed by the website.
import { createKamClient } from './server/trajectory/sdk/index.mjs';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const deployments = kam.scope({ subjectId: 'checkout', type: 'deployment' });
const page = await deployments.allIds({ day: '2026-10-06', limit: 16 });
if (page.status === 'ready' && page.items.length > 0) {
  const exact = await deployments.byIds({
    day: page.day,
    generation: page.generation,
    refs: page.items,
  });
  console.log(exact.records); // Keep every position and result status.
}
// A short page is not the end when nextCursor is present.
// Continue with the SAME generation and returned cursor.
```

## Authorize the destination separately

A subscription does not grant access to a customer AWS account. Server-owned bindings select the approved Region, memory, strategy, and namespace. Background jobs do not retain a browser JWT.

# Identity, ordering, and revisions

A retained reference resolves the revision it names—not whichever value is current today.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/history

## In short

Every record has a stable identity and numbered revisions. A correction adds a new revision instead of overwriting the old one. An exact lookup returns the named retained revision or an explicit non-found result, never whatever is newest.

**Available today:** Implemented in source and exercised by the candidate SDK.

> Exact means stable identity and revision, not permanent availability.

## One identity, retained revisions, three clocks

- **Effective time** — When the source event happened.
- **Accepted time** — When a revision became known.
- **Read boundary** — The exact revision and pinned generation requested.

## A correction is a new revision, not a new event

Identity is tenant + subject + type + ID. An exact retry returns the original receipt. A changed payload at the same revision conflicts. A correction uses the next revision and cannot change ID, scope, or occurrence time.

Idempotency is bounded by retained evidence. Do not recycle IDs after expiry. Deduplicating an outcome record does not prevent an external operation from executing twice.

## Three clocks, three meanings

1. **Occurrence time** — Places the event in a UTC day. Daily membership sorts by occurrence time, then ASCII ID.

2. **Acceptance sequence** — Orders applied revisions inside one tenant/subject/type scope.

3. **Publication time** — Marks when a fixed view became available. It is not the event’s business time.

## Pin the collection while browsing

A daily generation names a fixed manifest of bounded reference pages. Reuse its generation with the next cursor so a late arrival does not change the collection mid-read. Daily generations and trajectory generations are different references, not interchangeable identifiers.

[See record → retry → correction](/?capability=workflows&frame=corrected#trajectory)

## Read exact revisions without inference

A daily read returns at most 32 references. byIds() restores requested order and reports missing, expired, or unresolved keys explicitly. A failed or unprocessed lookup is not replaced with the latest revision.

Source pointers and hashes do not certify an outside business claim. Availability alone proves neither consumption nor correct reasoning; retain the generation actually supplied to an agent to record that application input.

# How the event-driven paths fit together

Acceptance, rolling calculation, exact reads, and AgentCore delivery have separate responsibilities.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/event-driven-memory

## In short

Accepting a record, calculating rolling comparisons, reading exact history, and delivering to AgentCore are four separate paths. Each saves its own progress, so a lost wakeup delays work instead of losing it.

**Available today:** Implemented in source; delivery to AgentCore is off by default.

> Persist the work before relying on a wakeup.

## Who owns each handoff?

- **Acceptance** — Kam retains admitted outcome revisions.
- **Projection** — Kam maintains bounded State and dependencies.
- **Serving** — AgentCore owns recall; the application uses the returned evidence.

## DynamoDB owns the accepted history

Acceptance commits immutable revisions, day membership, and durable work together. A separate publication transaction commits the checkpoint, trajectory generation, and eligible delivery obligation. These are two transactions at different stages, not a transaction across AWS services.

[Read the write path](/docs/engineering-review#write-path)

## Rust computes supported rolling views

The worker takes saved state, accepted transitions, and an explicit time input. It performs no AWS or model I/O. last10 compares two disjoint groups of ten; utc30 and utc90 compare disjoint calendar windows and include today’s partial UTC day.

Rates use summed success and failure counts. An empty denominator is null. Deltas are percentage points. These are descriptive comparisons, not significance tests or evidence of causation.

[Inspect a chart and its source records](/?capability=workflows#trajectory)

## Queues wake workers; durable records own the work

Bounded queue jobs and the scheduled maintenance sweep resume pending work and advance quiet histories. A delivery generation is not forgotten when enqueue fails; its durable obligation can be rediscovered after the scheduling lease.

The delivery scheduler rotates across registered scopes. Automatic recovery has explicit attempt limits and stop states; it does not imply automatic repair of every failure.

## Keep archive proposals separate

Accepted History is in DynamoDB. A source reference is not an archived copy or an atomic acceptance receipt. Automatic S3 archival and carry-forward consolidation are not implemented.

# From accepted outcome to verified retrieval

The implemented delivery loop schedules eligible local generations and keeps publication and verification receipts separate.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/publication

## In short

When enabled, Kam can publish a finished result to AgentCore Memory and then read it back to confirm it arrived. "Sent" and "confirmed" are tracked as different steps, and failures stay visible instead of being retried forever.

**Available today:** Implemented and off by default; tested with simulated AWS transports only.

> A queue message is a wakeup. An obligation is unfinished work. A receipt is evidence.

## Delivery keeps its own evidence

- **Accepted** — The outcome revision is retained.
- **Delivered / verified** — Separate receipt states; acceptance is not delivery.
- **Stopped** — An unfinished obligation stays visible. Default-off delivery is not live qualification.

## Select an authorized destination and starting point

A prospective delivery policy names the scope, lifecycle epoch, destination binding/version, and first eligible checkpoint version. Older generations are not implicitly backfilled. Under policy v1 every eligible generation keeps its own obligation. Under policy v2 a newer generation may replace only a candidate that was never planned, dispatched or submitted; the replaced obligation is kept as SUPERSEDED with the replacing generation. Submitted or uncertain work is never coalesced.

## Read the progression and stop states

1. **AWAITING_PUBLICATION** — Durable work exists for one eligible generation. The worker plans the authorized request and records publication attempts.

2. **AWAITING_VERIFICATION** — The write has been acknowledged. A separate exact read still needs to match the expected content and lineage.

3. **VERIFIED** — The exact record matched through the approved namespace at verification time. This is not proof of semantic-search ranking or agent consumption.

4. **Explicit stops** — REJECTED, AUTHORITY_BLOCKED, and RECONCILIATION_REQUIRED remain visible. The orchestrator does not repair mismatched remote content.

5. **SUPERSEDED (policy v2)** — A never-submitted candidate replaced by a newer generation. Counted separately from unresolved work; it is neither a failure nor a delivery.

> **Current release boundary**
> Marketplace availability, production p99, and production AgentCore write-back remain qualification gates. The delivery loop is implemented, disabled by default, and tested through simulated transport. This is not live production qualification.

[See the delivery-state diagram](/architecture#delivery)

## Separate local correction from remote cleanup

Local revisions and new generations are implemented. Remote supersession, deletion, and operator reconciliation require separate work. A failed verification read does not become another create. Do not infer that publishing a newer memory automatically removes all older destination records.

## Count like with like

deliveryStatus() reports accepted/applied outcome revisions separately from local-generation delivery counts. Do not subtract verified generations from accepted revisions or chart them as one funnel.

The status read covers at most 32 scopes and 100 obligations per scope. Check coverage.complete before treating counts as complete. Counts of due or leased work overlap workflow stages; they are not extra stages to add to a total. Oldest-work reporting includes non-verified stop states.

# Retention, rolling history, and checkpoints

The active working window, retained evidence, and AgentCore memory have different owners and clocks.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/retention

## In short

Kam calculates over a rolling 365-day window, keeps supporting evidence on its own clock (up to 730 days), and leaves AgentCore Memory retention to AWS. A saved checkpoint lets processing resume; it is not a permanent summary of everything ever seen.

**Available today:** The rolling window and evidence limits are implemented. Automatic archival and long-term summaries are not.

> Saved processing state is not the same thing as permanent historical memory.

## Separate clocks and owners

- **Working History** — The bounded rolling UTC-date read window.
- **Retained evidence** — Explicit availability; expiry is never a latest fallback.
- **External memory** — AgentCore policies are separate; archival is not a built Kam guarantee.

## A rolling window. A maintained state.

Kam advances working state as outcomes arrive and time moves forward. A recovery checkpoint keeps processing continuous; it is not a permanent summary of everything the system has seen.

1. **Rolling operational history** — The working window contains today and the previous 364 UTC dates. It advances each day, not through annual resets.

2. **Checkpointed rolling state** — Processing resumes from the persisted checkpoint and applies accepted transitions. Exact reads use published views rather than rebuilding the full history.

3. **Versioned supporting evidence** — Revisions and references support inspection until their deadlines. Supporting evidence may be retained for up to 730 days, with correction-related extensions.

> **Current reducer boundary**
> Outcomes older than the working window stop contributing to rolling state. The current reducer does not preserve their meaning in a lifetime summary or move them automatically to S3.

[See the working-window visual](/reliability#retention)

## Kam working history

365 UTC dates

Today and the preceding 364 UTC dates. The window advances daily; out-of-window contributions are removed from rolling state, not consolidated into a permanent baseline.

## Kam supporting evidence

Separate inspection limits

Supporting revisions and references may remain for up to 730 days, with direct-prior-revision extensions for corrections. Inspection ends when its evidence expires; this is not automatic cold-tier archival.

## AgentCore raw events

Configurable, up to 365 days

AWS applies this retention to raw short-term events. It is separate from Kam’s window and AgentCore long-term records.

## AgentCore long-term records

Separate lifecycle policy

AWS documents explicit deletion workflows. Raw-event expiry is not a universal long-term-record deletion policy.

## Carry-forward consolidation

Preserve selected historical meaning in a versioned summary baseline while older evidence follows a separate archive policy. This is a proposed extension, not the behavior of the current rolling reducer.

Summary selection, provenance, corrections, archive verification, retrieval, and deletion need their own implementation and qualification. A summary is derived context, not a replacement for exact evidence or a guarantee against context drift.

> **Proposed · not implemented**
> Automatic S3 archival, a persistent summary baseline, and AI-generated institutional knowledge are not implemented in the reviewed backend. No delivery date is committed.

## AWS documentation

The AWS sources below explain raw-event retention and an explicit long-term-record deletion workflow. They do not define Kam’s history contract.

[AWS: raw-event retention](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-create-a-memory-store.html)

[AWS: long-term memory lifecycle](https://aws.amazon.com/blogs/machine-learning/designing-lifecycle-policies-for-agentcore-memory/)

## Expiry does not prove erasure

Reads enforce logical expiry before asynchronous TTL cleanup. Bounded owner export, primary-state deletion, and a restore fence are implemented in source. Live downstream erasure and restore drills remain separate release gates. A missing old reference is not rebuilt on demand or silently replaced with a newer record.

# Accepted work remains accountable

Cancellation, renewal, and uncertain delivery must not silently change an accepted outcome’s identity or authority.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/reliability

## In short

If something is cancelled, renewed, or answers ambiguously, Kam keeps the original record and its permissions intact and shows the unfinished work. It never quietly reclassifies an uncertain result as a success or a failure.

**Available today:** Implemented in source; live cancellation, erasure and restore drills are still to be qualified.

> Make incomplete work visible, including work that automatic retries cannot finish.

## Recovery follows evidence

- **Obligation** — The work that still needs an outcome.
- **Attempt** — A recorded dispatch and its known or unknown effect.
- **Authority** — Revalidate current authority before resuming work.

## Keep local processing and delivery separate

Lifecycle fencing and bounded draining are implemented candidates. Delivery additionally owns one obligation per eligible generation. Local application does not prove remote submission, and remote submission does not prove retrieval.

> **Current release boundary**
> Marketplace availability, production p99, and production AgentCore write-back remain qualification gates. The delivery loop is implemented, disabled by default, and tested through simulated transport. This is not live production qualification.

## Do not let an old job inherit new authority

An outcome keeps its acceptance epoch. Cancellation closes new acceptance and may authorize a bounded local drain. Renewal advances authority again. Delivery stops new remote attempts when the lifecycle closes or its destination binding changes; an old obligation is not silently rebound.

## Uncertain is not failed, cancelled, or complete

An ambiguous response preserves the request identity and durable receipt. Recovery waits for the relevant lease or scheduled retry boundary. Exhausted publication or verification attempts require reconciliation; they are not counted as success. A failed read does not trigger a new create.

## Implemented exit controls still need live qualification

Bounded owner export, export-bound primary deletion, and a separately retained restore fence are implemented. Marketplace reconciliation is license-scoped. Live purchase, cancellation, downstream erasure, and restore drills remain separate gates. A restored table being available does not establish that it is safe to serve.

[Read the customer lifecycle boundary](/docs/marketplace)

# What has been tested

Source behavior, packaged execution, and a live customer deployment answer different questions.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/qualification

## In short

Tests on source code, tests on a packaged build, a live qualification, and a production authorization prove different things. Each capability is shown at the highest of those six levels its evidence still supports.

**Available today:** Source-implemented and locally qualified evidence exist. Nothing is live-qualified, pilot-only, or production-authorized.

> Read the evidence for a pinned source revision—not a blanket certification.

## Six evidence levels

- **Planned → implemented** — A design becomes source with tests.
- **Local → live** — Local or simulated evidence does not qualify AWS behavior.
- **Pilot → production** — Explicit scope and authorization remain separate gates.

## Six evidence levels

Every capability is shown at the highest level its recorded evidence still supports. Each level needs the one beneath it, and missing, stale, failed, or mismatched evidence lowers the shown level automatically.

1. **Planned · not available** — Design direction. No implementation is claimed.

2. **Source-implemented** — Implemented in reviewed source with source-level tests. Not executed as a packaged artifact.

3. **Locally qualified** — Exercised as a packaged or local artifact (CI, local lab, or simulated AWS transports). No live AWS deployment.

4. **Live-qualified** — A passed live qualification receipt binds this exact package to an isolated AWS deployment.

5. **Pilot only** — Live-qualified and authorized for a named, bounded pilot. Not general availability.

6. **Production-authorized** — Live-qualified and explicitly authorized for production use.

## The release combination behind these pages

No deployment of the History/State candidate was found in the inspected AWS Regions. Existing Kam resources belong to earlier products and are not evidence for this one.

Live qualification receipts recorded: 0. Live receipts are accepted only in the backend schema kam.live-agentcore-qualification-receipt.v6 with status passed, bound to the exact recorded package commit.

1. **Source the website claims were reviewed against: 1db8cf00** — main through PR #219. Every public capability statement is checked against this checkpoint.

2. **Reviewed source, packaged and qualified in CI: 1db8cf00** — main · qualification run 37686977815. Same commit as the reviewed source. Package, SDK and native artifact round trips passed with simulated AWS transports; not a live deployment.

3. **Packaged candidate selected for live qualification: 284f26e5** — PR #206 candidate · merged as a215d31f · run 37605352449. Named by the backend live-AWS approval document at the reviewed checkpoint. No live receipt exists.

4. **Native developer toolkit: 1db8cf00** — merged in PR #176 (d5056454) · native artifact round trip in run 37686977815. Linux x64 only. No public distribution.

5. **History and State SDK candidate: 1db8cf00** — SDK 0.36.0 · artifact round trip in run 37686977815. Not published to npm. The website console vendors this exact tarball.

6. **History — Locally qualified** — Package qualification is not a live deployment.

7. **Identity & membership — Locally qualified** — Covered by the same package qualification as History.

8. **Views & current State — Source-implemented** — Not deployed. Package coverage of View reconciliation is not confirmed for the website.

9. **State queries & Components — Source-implemented** — SDK 0.36.0 candidate; whether the SDK artifact round trip exercises queries is not confirmed for the website.

10. **Metrics, materialize & watch — Planned · not available** — Design preview only.

11. **Turn Lifecycle — Locally qualified** — Merged native toolkit; reference-only local frames.

12. **Context compiler — Planned · not available** — Design direction only.

13. **Operational durability — Source-implemented** — History and reconciliation progress are durable in source; no named checkpoint API.

14. **Profiler & developer toolkit — Locally qualified** — Merged; Linux x64 only; no public distribution.

15. **Optional AgentCore delivery — Locally qualified** — Default off; simulated AWS transports only.

16. **Export, deletion & restore fence — Source-implemented** — Live erasure and restore drills are qualification gates.

[See the release combination](/reliability#release)

[Open the fixture inspector](/inspect)

## Current evidence boundary

1. **Ordered, versioned ledger — Source and package tested** — Exact revisions, pinned daily pages, corrections, rolling windows, and independent 400/730-day synthetic-history checks. Synthetic time is not observed uptime.

2. **Rust State and Observations — Source implemented** — State pointers, immutable structured Observations, and change evidence are conditionally persisted. The SDK 0.36.0 candidate reads current Active State and exact retained Observations. No State or Context endpoint is deployed.

3. **State reconciliation — Source implemented** — Bounded View registration, acyclic reverse-dependency membership, replay-safe cursor/task progress, and bounded same-scope multi-source dependency processing are implemented. Cross-scope joins and a deployed State endpoint remain staged.

4. **State queries — Source implemented** — The reviewed SDK 0.36.0 baseline, unpublished and undeployed, implements state(), component(), and bounded select stages (where, pick, orderBy, take) with explain() and value() over the admitted evidence of one View's Active State. SDK 0.37.0 merged in PR #220 (not publicly published and not included in the pinned 0.36.0 website qualification) adds bounded operators over that same selected collection. General source-payload queries, managed metrics, calculation caching, graph traversal, materialize(), watch(), and lifecycle integration remain separate planned capabilities.

5. **Turn Frames and profiler — Merged · locally qualified** — Validated local Turn Frames, reference preparation, and State profiling exist in the merged native toolkit and run locally only. They do not intercept live AgentCore turns, submit model requests, persist managed Turn Receipts, or authorize external effects.

6. **Live Turn Lifecycle and Context — Planned · not available** — The product direction is to resolve current operational checkpoints, detect typed changes, compile bounded Observations, bind turns to exact ReadSets, and revalidate consequential effects. No live runtime hook or managed action barrier is claimed.

7. **Native developer toolkit — Merged · locally qualified** — Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

8. **Customer lifecycle — Source implemented · live unqualified** — Bounded owner export, primary-state deletion, restore fences, and Marketplace entitlement reconciliation are implemented in source. Live buyer, erasure, restore, and revocation journeys remain qualification gates; no deployed completeness is claimed.

9. **AgentCore delivery — Implemented · default off** — Destination binding, per-generation obligations, scheduling, publication receipts, exact retrieval verification, and metadata-only status are implemented. Optional Memory write-back remains separately qualified with simulated AWS transports.

10. **Carry-forward consolidation — Proposed · not implemented** — A versioned long-term summary baseline and automatic S3 archival are not implemented. Checkpoint recovery does not preserve expired contributions as institutional knowledge.

11. **Real-history verification (Kam Sports) — Planned · not executed** — The verification plan replays real Kam Sports history through the unchanged History contract across the 365-UTC-date working window and checks exact reads, corrections, and recovery. Kam Sports grading stays authoritative; Kam records grades, it never computes them. No run has completed yet.

12. **History console — Implemented in website source** — A read-only, Amplify-authenticated console browses workspaces, scopes, UTC days, and exact revisions through existing History API reads. It is not connected to a live History deployment, because none exists yet; without configuration it reads nothing.

13. **Production assurance — Not yet qualified** — Source checks and independent artifact execution do not establish deployed IAM, a Marketplace listing, production SLOs, compliance approval, or measured costs and latency.

> **Current release boundary**
> Marketplace availability, production p99, and production AgentCore write-back remain qualification gates. The delivery loop is implemented, disabled by default, and tested through simulated transport. This is not live production qualification.

## Reference workload, not enterprise semantics

NFL helped establish patterns in the separate sports project. This extracted service uses a terminal-outcome reducer; it does not import ATS grading, provider capture, or game finalization into customer workflows.

## Bounded work is not a latency measurement

Candidate limits include 32 scopes per licensed workspace, eight cumulative categories, 4,096 identities per scope/day, and up to 32 references per read. These are supported-envelope limits, not throughput or cost promises.

Live acceptance/read latency, local publication lag, AgentCore visibility, costs, and oldest-pending work still need measurement. The website charts use synthetic records and do not report production performance.

# What Kam stores, writes, reads, and proves

For engineers evaluating Kam: the storage model, write and read paths, consistency and concurrency boundaries, recovery, retention, responsibility split, and what remains unqualified.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Describes the History contract implemented in source. Nothing here is live-qualified, and no deployment is offered from this page.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/engineering-review

## In short

The questions an architecture review asks, answered with the guarantee and its limit together: what Kam stores, how a write commits, what each read proves, where consistency stops, how recovery and retention work, and what is still unqualified.

**Available today:** Describes the History contract implemented in source. Nothing is live-qualified.

> Answer the design-review questions with the guarantee and its limit side by side.

## Five questions before the details

- **What is stored?** — Versioned outcomes and exact references.
- **Who owns storage?** — DynamoDB is authoritative; Rust owns semantics.
- **How is a read bounded?** — Scoped, generation-bound membership and exact hydration.
- **What survives a retry?** — Stable identity, revisions, and unfinished obligations.
- **What is qualified?** — Source and local evidence; live production gates remain.

## What is stored

1. **Outcome revisions** — Immutable (id, revision) records your application declares: subject, type, occurrence time, success or failure, category, and source references. Kam does not store your system of record, model prompts, or agent transcripts.

2. **Day membership** — Ordered references naming which exact revisions belong to one scope and UTC day, published as generations.

3. **Durable work records** — Work owed to the projection worker, committed with each accepted revision (a transactional outbox).

4. **Checkpoints and projections** — Saved fold state and applied sequence, plus the trajectory comparisons derived from them.

5. **Delivery obligations and receipts** — Only when optional AgentCore delivery is enabled (default off): one obligation per eligible generation, with separate publication and verification receipts.

[Glossary: outcome revision](/docs/concepts#outcome-revision)

## The write path

1. **1. Authenticate and authorize** — API Gateway verifies the Cognito access token; the handler re-checks issuer, client and scope, takes the principal from sub, and authorizes the requested tenant. A tenant ID in the request is not permission.

2. **2. Admit** — Rust validates identity, revision, occurrence time against the working window, and budgets. A correction must be exactly the next revision and cannot move the occurrence time.

3. **3. Commit atomically** — One DynamoDB TransactWriteItems call commits the revision, its day membership, and the work record, guarded by version conditions. Identical resubmission returns duplicate with the original acceptedSequence; a different payload for the same revision is rejected.

4. **4. Wake and fold** — A best-effort wakeup starts the worker. If it fails, the committed work record is redriven. The worker folds accepted revisions in sequence order.

5. **5. Publish** — A separate transaction commits the checkpoint, the new generation, and any eligible delivery obligation. Acceptance and publication are two transactions, not one.

[Glossary: acceptance transaction](/docs/concepts#acceptance-transaction)

[Glossary: transactional outbox](/docs/concepts#outbox)

## The read path, and what each read proves

1. **trajectory()** — Proves the projection as of appliedSequence, alongside acceptedSequence. If they differ, accepted work is not yet folded.

2. **allIds()** — Proves membership: these exact revision references belong to this generation, through acceptedThroughSequence. It does not assert that every real-world event was reported (externalCompleteness: not_asserted).

3. **byIds() in generation mode** — Proves each named revision is retained and matches its content hash, in caller order, and that it belongs to the generation. Missing, expired and unresolved positions stay explicit.

4. **byIds() in direct mode** — Proves a known (id, revision) is retained. It makes no membership claim and never falls back to the latest revision.

5. **What no read proves** — That an agent consumed the record, that the external fact is true, or who authored it. A content hash is integrity, not a signature.

## Where consistency and concurrency apply

Ordering is per scope: each tenant, subject and type has its own contiguous acceptedSequence and no global commit counter. Concurrent writers use optimistic concurrency; a stale version is rejected, not merged.

Each storage read is strongly consistent. A read that spans pages is made consistent by pinning a generation and passing its cursor back with it; if the service would have to switch generations, the read fails instead.

Kam makes no linearizability, serializability, or cross-scope isolation claim, and projections are asynchronous relative to acceptance.

[Glossary: conditional write](/docs/concepts#conditional-write)

[Glossary: generation](/docs/concepts#generation)

[Glossary: strongly consistent read](/docs/concepts#consistent-read)

## How recovery works

Work is persisted before anything relies on a wakeup, so a lost message delays processing instead of losing it. Processing is at-least-once and idempotent; Kam does not claim exactly-once execution.

Ambiguous external responses stay UNKNOWN until reconciled, and lifecycle epochs stop old jobs from acting with new authority. Owner export, export-bound deletion and a restore fence are implemented in source; live restore and erasure drills are not qualified. There is no arbitrary point-in-time recovery.

[Recovery and authority](/docs/reliability)

## Retention and deletion

New outcomes are admitted for today plus the previous 364 UTC dates. Retained evidence carries its own deadline of up to 730 days. Reads report a revision past its deadline as expired immediately; DynamoDB TTL removes the item later, typically within a few days, so expiry is not proof of physical deletion.

[Glossary: logical expiry](/docs/concepts#logical-expiry)

[Retention guide](/docs/retention)

## Who is responsible for what

1. **Your application** — Business meaning of success and failure, stable IDs, idempotency of external effects, and the agent runtime.

2. **Kam** — Admission rules, per-scope ordering, immutable revisions, generations, projections, and receipts, with the limits stated above.

3. **Identity and access** — Cognito authenticates the principal. The History API decides which workspaces that principal can read. Neither the browser nor this website grants access.

4. **Deployment** — Kam runs in AWS. No live deployment or Marketplace listing is offered today; an evaluation needs an isolated deployment and an explicit review of identity, permissions, retries, corrections and exit.

## What remains unqualified

Every capability below is shown at the highest level its recorded evidence supports. No capability is live-qualified, pilot-only, or production-authorized.

1. **History — Locally qualified** — Package qualification is not a live deployment.

2. **Identity & membership — Locally qualified** — Covered by the same package qualification as History.

3. **Views & current State — Source-implemented** — Not deployed. Package coverage of View reconciliation is not confirmed for the website.

4. **State queries & Components — Source-implemented** — SDK 0.36.0 candidate; whether the SDK artifact round trip exercises queries is not confirmed for the website.

5. **Metrics, materialize & watch — Planned · not available** — Design preview only.

6. **Turn Lifecycle — Locally qualified** — Merged native toolkit; reference-only local frames.

7. **Context compiler — Planned · not available** — Design direction only.

8. **Operational durability — Source-implemented** — History and reconciliation progress are durable in source; no named checkpoint API.

9. **Profiler & developer toolkit — Locally qualified** — Merged; Linux x64 only; no public distribution.

10. **Optional AgentCore delivery — Locally qualified** — Default off; simulated AWS transports only.

11. **Export, deletion & restore fence — Source-implemented** — Live erasure and restore drills are qualification gates.

[What has been tested](/docs/qualification)

## Quickstart: record, correct, read both revisions

Every call below exists in the pinned SDK 0.36.0 typings. It needs an authorized endpoint, tenant and token, which are never embedded in these pages. The SDK is not published to npm.

### Record a correction and read both exact revisions

```javascript
// SDK 0.36.0 (the qualified CI artifact for backend 1db8cf00). Not published to npm.
// Run in Node 22 with an authorized endpoint, tenant and short-lived access token.
import { createKamClient } from '@kam-ai/agentcore-history-sdk';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const checks = kam.scope({ subjectId: 'checkout', type: 'deployment' });

// 1. Accept revision 1. Sending the identical payload again returns status 'duplicate'.
const first = await checks.outcome({ id: 'deploy-0412', occurredAt: '2026-10-06T17:00:00.000Z', status: 'success' });

// 2. Correct it: the next revision, same id and occurredAt. Revision 1 is kept.
const second = await checks.outcome({ id: 'deploy-0412', revision: 2, occurredAt: '2026-10-06T17:00:00.000Z', status: 'failure' });
console.log(first.acceptedSequence, second.acceptedSequence); // per-scope order

// 3. Read both exact revisions. Direct mode makes no day-membership claim.
const exact = await checks.byIds({ refs: [{ id: 'deploy-0412', revision: 1 }, { id: 'deploy-0412', revision: 2 }] });
for (const record of exact.records) console.log(record.ref.revision, record.status);
```

# Glossary: the terms these guides use

Each Kam term mapped to the standard distributed-systems concept, the Kam-specific definition, its limits, and the backend test that shows it.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/concepts

## In short

Each term maps a standard distributed-systems concept to what Kam means by it, where the guarantee stops, and the backend test that shows it. Terms Kam does not claim, such as exactly-once execution, are listed with the reason.

**Available today:** Implemented terms cite tests in the reviewed backend revision; storage behavior links to AWS documentation.

> Use the same word for the same responsibility across your design review.

## Use one word per responsibility

- **Identity** — Which exact object revision?
- **Membership** — Which references belong to this generation?
- **View** — Which question is answered from those references?

## One model, many questions

A few primitives answer most questions about agent State: identity, revision, membership, view + dependencies, authority, bounds, obligation + receipt, retention clock. A new question should first become a View, selector, reducer or lifecycle rule over them, not a new service. Questions that belong to AgentCore or to a model are labelled as such.

1. **Personal watchlist · Planned** — What records do I want to follow, in my order? An ordered reference collection with per-entry selectors. The public explorer has a temporary fixture preview; authorized, durable watchlist mutations are not implemented.

2. **Since my last review · Derivable · no operator yet** — What changed, and why does my declared review rule flag it? The release-verification fixture View separates endpoint differences, retained activity, and a named domain rule. Explicit review actions acknowledge displayed exact boundaries in memory only; durable reviews and notifications are not implemented.

3. **Saved calculation selection · Planned** — Which supported calculation, inputs and period produced this result? A definition selects a qualified domain calculator and pinned inputs; its result is versioned State displayed by Views. No new backend primitive or generic business calculator is claimed.

4. **Operational memory · Planned** — What work can a replacement agent recover? History and obligations exist in source. A managed cross-agent handoff is planned; the explorer illustrates it without running an agent.

5. **Workflow coordination · Planned** — Which parent-child work is eligible? Ordered membership and explicit dependencies are separate. The explorer previews valid order; hosted customer workflow management is planned.

6. **Computation reuse · Planned** — What can be reused without mistaking stale input for a cache hit? Local comparison reuse and bounded reads exist. General calculation caching needs explicit applicability and live measurement; fixture counts are not savings.

7. **History · Implemented in source** — What exactly was recorded? allIds() names exact revision references; byIds() returns exactly those revisions.

8. **Correction · Implemented in source** — What was revised, and what did it replace? A correction is the next revision; the earlier one stays readable while retained.

9. **Snapshot · Implemented in source** — What did this collection look like when it was published? A generation fixes ordered membership; pages are read against it.

10. **Difference · Derivable · no operator yet** — What changed between two publications? Compare the exact references of two generations. No diff operator is built.

11. **Dependency · Implemented in source** — What relies on this information? Views register versioned dependencies; a reverse index finds dependents.

12. **Invalidation · Implemented in source** — Which derived State must be recomputed after this change? Reconciliation pages through affected Views and recomputes only those.

13. **Freshness · Implemented in source** — Is this current enough to act on? Active State is current, stale, blocked or absent; only current is usable.

14. **Authority · Implemented in source** — Who may read this, in which scope? The service resolves the principal's workspaces; a tenant in a request is not permission.

15. **Expiration · Implemented in source** — When does this evidence stop being usable? Reads report expired at the deadline, before storage cleanup.

16. **Receipt · Implemented in source** — What work is still owed, and what was acknowledged? Delivery keeps one obligation per eligible generation and separate receipts.

17. **Bounded query · Implemented in source** — Which current evidence matches, within a known cost? explain() admits a bounded plan; value() runs it over one Active State.

18. **Viewport · Planned** — What is the most useful State that fits this context budget? The Context compiler is planned; budgets exist only for queries today.

19. **Subscription · Planned** — Which agents should wake when this changes? watch() is planned; the internal event path is not a customer subscription.

20. **Authorized history · Needs data Kam does not record** — What was this agent allowed to see yesterday? Access is checked at read time and is not itself recorded as History.

21. **Decision · AgentCore or your runtime** — What should the agent do next? AgentCore and your code plan, decide and call tools. Kam records the outcome and the exact State the decision read.

22. **Confidence · A model, not Kam** — How likely is this forecast to be right? A model computes it; Kam can retain the output and its inputs as evidence.

[See the question graph](/architecture#questions)

## How to read this glossary

Each term gives the standard concept first, then what Kam means by it, then where the guarantee stops. Evidence names a test or source file in kam-agentcore-history at 1db8cf00; storage behavior links to the AWS documentation it depends on.

## Outcome revision

Standard concept: An immutable, versioned record in an append-only log: a new version is added and earlier versions are never updated in place.

In Kam: An outcome is identified by (scope, id). Each accepted version is (id, revision) with revision = 1, 2, 3… A correction must be exactly the next revision and cannot move the original occurrence time.

Limits: Immutable while retained, not permanent. Retained evidence expires on its own deadline (up to 730 days). This is not WORM storage and not full event sourcing: Kam stores declared outcomes, not every domain event in your application.

Evidence: server/trajectory/test/contracts.test.cjs — “append is idempotent; conflicts and skipped revisions fail without extra work”; server/trajectory/test/history.test.cjs — “real Rust owns correction revision and immutable identity admission”; server/trajectory/test/history-integration-contract.test.cjs — “a correction cannot move the original occurrence anchor or replace the exact prior revision”.

## Accepted sequence

Standard concept: A per-partition log sequence number: a total order of accepted writes within one partition, with no order between partitions.

In Kam: Each scope assigns every accepted revision a unique, contiguous acceptedSequence. Scopes have independent counters; there is no global commit counter.

Limits: Ordering holds within one scope only. Kam makes no cross-scope ordering, linearizability, or serializability claim.

Evidence: server/trajectory/test/contracts.test.cjs — “four concurrent outcomes have unique contiguous committed sequence numbers”; server/trajectory/test/history-integration-contract.test.cjs — “independent scoped writers do not share State identity or version counters”.

## Conditional write (optimistic concurrency)

Standard concept: Optimistic concurrency control: a write succeeds only if a version attribute still holds the value the writer read; otherwise it fails with ConditionalCheckFailed and the writer re-reads.

In Kam: Every storage write states its expected version, or that the item must not exist yet (attribute_not_exists), and can add ConditionCheck guards on related items such as lifecycle state and authority epoch.

Limits: A conflict is rejected, never merged. Only recognized transient failures are classified as retryable. Permission and validation failures require investigation or correction. No storage failure is treated as proof of a duplicate submission.

Evidence: server/trajectory/src/table.cjs — “put(): ConditionCheck on version, state and authorityEpoch; Put with attribute_not_exists(PK) or #v = :v”; server/trajectory/test/contracts.test.cjs — “Dynamo throughput or mixed transaction failures are not swallowed as duplicates”.

[AWS: DynamoDB condition expressions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.ConditionExpressions.html)

[AWS: optimistic locking with a version number](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBMapper.OptimisticLocking.html)

## Acceptance transaction

Standard concept: An all-or-nothing multi-item transaction within one database (DynamoDB TransactWriteItems): every write and condition check succeeds together, or none is applied.

In Kam: Accepting a revision commits the revision, its day membership, and a durable work record in one TransactWriteItems call (Kam caps it at 25 items). Publishing a checkpoint and generation is a separate, later transaction.

Limits: One table, one transaction at a time. There is no transaction across AWS services, and acceptance and publication are not one atomic step.

Evidence: server/trajectory/src/table.cjs — “put(): one TransactWriteCommand with ConditionCheck and Put items, at most 25”; server/trajectory/test/contracts.test.cjs — “failed wakeup retains the outcome and durable work record”.

[AWS: DynamoDB transactions](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/transaction-apis.html)

[AWS: TransactWriteItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html)

## Durable work record (transactional outbox)

Standard concept: The transactional outbox pattern: work owed to a downstream processor is written in the same transaction as the state change, then delivered asynchronously.

In Kam: The work record commits with the accepted revision. The wakeup that follows is best effort; if it fails, the record stays and is redriven.

Limits: At-least-once processing: a worker may see the same work more than once, so processing is idempotent. Kam does not claim exactly-once execution.

Evidence: server/trajectory/test/contracts.test.cjs — “failed wakeup retains the outcome and durable work record”; server/trajectory/test/history.test.cjs — “outbox corruption is detected BEFORE reducer invocation; one corrupt scope does not block another”.

## Idempotent acceptance

Standard concept: Idempotency-key deduplication: a retried request with the same key and payload returns the original result; the same key with a different payload is rejected.

In Kam: The key is (scope, id, revision). Resubmitting an identical revision returns status duplicate with the original acceptedSequence. A different payload for the same revision fails with idempotency_payload_conflict.

Limits: Deduplication lasts while the revision is retained. It does not use the DynamoDB ClientRequestToken, whose idempotency window is 10 minutes. It covers acceptance only; it cannot stop an external payment or deployment from running twice.

Evidence: server/trajectory/test/contracts.test.cjs — “append is idempotent; conflicts and skipped revisions fail without extra work”.

[AWS: TransactWriteItems API](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_TransactWriteItems.html)

## Generation

Standard concept: An immutable snapshot identifier: a read pinned to it sees one fixed version of a named collection, however that collection changes afterwards.

In Kam: A generation is typed. A day generation names the fixed, ordered set of exact revision references for one scope and UTC day; a trajectory generation names a separately published trajectory snapshot. Callers keep the generation returned by the API they are reading.

Limits: A day generation covers accepted outcomes through acceptedThroughSequence only. Neither generation type asserts that every real-world event happened or was reported, and neither is a database-wide point-in-time view.

Evidence: server/trajectory/test/history.test.cjs — “real HTTP/SDK reads a pinned day across split pages, late arrival, correction and retry”; server/trajectory/test/history.test.cjs — “a changed Rust generation response cannot cross its requested day or generation”.

## Exact hydration

Standard concept: A batched point read by primary key and version: return exactly the named versions, in the requested order, never the latest.

In Kam: byIds() reads up to 32 references in caller order and reports each as found, unresolved, unavailable, or expired. Generation mode also proves membership in a generation; direct mode reads a known (id, revision) with no membership claim.

Limits: A missing or expired revision stays missing; Kam never substitutes a newer one. A key DynamoDB returns as unprocessed is reported as retryable, never as missing.

Evidence: server/trajectory/test/history.test.cjs — “exact hydration preserves caller order and distinguishes unprocessed, missing and expired records”; server/trajectory/test/history.test.cjs — “known ID/revision hydrates directly without enumerating a day or following latest”.

[AWS: BatchGetItem and UnprocessedKeys](https://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchGetItem.html)

## Strongly consistent read

Standard concept: A read that reflects every write acknowledged before it began, for a single item or query.

In Kam: History storage reads use DynamoDB strongly consistent reads (ConsistentRead: true) for get, batch get, and range queries.

Limits: Per call only. A read that spans several calls is made consistent by pinning a generation, not by a multi-call transaction. No linearizability or serializable-read claim across calls or scopes.

Evidence: server/trajectory/src/table.cjs — “get, batchGet and range issue ConsistentRead: true”.

[AWS: DynamoDB read consistency](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/HowItWorks.ReadConsistency.html)

## Projection (trajectory)

Standard concept: A materialized view maintained incrementally by a deterministic fold over an ordered log, resumed from a checkpoint.

In Kam: The trajectory (last ten results, 30- and 90-UTC-day windows) is folded from accepted revisions in sequence order. acceptedSequence and appliedSequence are both returned, so the lag between them is visible.

Limits: Asynchronous: it lags acceptance until the worker applies the work. A reader compares appliedSequence with acceptedSequence; this is not read-your-writes for the projection.

Evidence: server/trajectory/test/history.test.cjs — “real Rust admits the exact contiguous reducer work-evidence batch”; server/trajectory/test/e2e.test.cjs — “new ingress does not starve publication; accepted prefix remains visibly pending”.

## Checkpoint

Standard concept: A stream-processing checkpoint: saved fold state plus the last applied offset, used to resume.

In Kam: The saved reducer state and appliedSequence for one scope, committed with the generation it published.

Limits: A checkpoint resumes processing; it is not a lifetime summary. Carry-forward consolidation and S3 archival are not implemented.

Evidence: server/trajectory/test/lifecycle.test.cjs — “cancellation after reducer compute but before commit prevents publication”; server/trajectory/test/lifecycle.test.cjs — “deadline closing during reducer computation prevents publication and records the old checkpoint”.

## Content hash

Standard concept: A SHA-256 digest used to detect accidental or unauthorized change to stored bytes.

In Kam: Each revision reference carries the SHA-256 of its canonical content. Hydration recomputes the hash of the stored record and rejects it if either value differs.

Limits: Integrity, not authenticity: a hash is not a signature and does not identify who wrote the record. A source reference does not certify that the external fact is true.

Evidence: server/workers/rust/src/history/hydration.rs — “canonical_hash_with_javascript_numbers(record.event) must equal record.content_hash and the reference hash”; server/trajectory/test/history.test.cjs — “generation membership, namespace, corruption, time-zone and bounds cannot be bypassed”.

## Logical expiry

Standard concept: The application's decision that a record is no longer eligible or available under its contract, regardless of whether storage has deleted its bytes.

In Kam: Every retained revision has an evidenceUntil deadline. Reads report a revision past that deadline as expired immediately. DynamoDB TTL is the separate background cleanup mechanism and may delete the bytes later.

Limits: Logical expiry is not proof of physical deletion, and Kam offers no arbitrary point-in-time recovery of expired evidence.

Evidence: server/trajectory/test/history.test.cjs — “daily evidence survives the snapshot interval; expiry is logical even before TTL cleanup”.

[AWS: DynamoDB Time to Live](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/TTL.html)

## Standard terms Kam does not claim

1. **Event sourcing** — Kam stores outcomes your application declares, not every domain event, and it does not rebuild your application state.

2. **CQRS framework** — Kam separates its own write path from its read models, but it does not provide command handling for your application.

3. **Linearizable or serializable reads** — Single reads are strongly consistent; multi-call reads pin a generation. There is no cross-call or cross-scope isolation claim.

4. **Exactly-once execution** — Acceptance is idempotent and processing is at-least-once. External effects need their own idempotency.

5. **Cryptographic authenticity** — Content hashes detect change; nothing is signed.

6. **Permanent immutability** — Revisions are immutable while retained and expire on explicit deadlines.

7. **Arbitrary point-in-time recovery** — Generations pin published snapshots; Kam does not restore any past instant on request.

## Delivery and comparison terms

1. **Outcome** — A completed success or failure result declared by your application.

2. **Trajectory** — Precomputed comparisons: last ten results, and 30- and 90-UTC-day windows.

3. **Delivery obligation** — Durable work owed for one eligible generation. It is not proof of a successful delivery.

4. **Verified retrieval** — An exact destination record matched at a recorded time. It is not evidence of agent consumption.

## The state-platform vocabulary

These names clarify responsibilities. They do not rename stored generation fields or make an internal capability public.

1. **Directory** — Bounded, authorized discovery of scopes and Views. A general managed Directory remains planned; the SDK has workspace discovery.

2. **View** — A versioned declaration of required or optional evidence, source identities, freshness and selection limits. A bounded owner-configured registry now exists in source.

3. **Active State** — The maintained deterministic projection and current reuse assessment over exact source versions, freshness limits and authority boundaries.

4. **ChangeSet** — The typed difference that should drive reconciliation. Exact or provenance changes are distinct from semantic, freshness, authority or assembled-request changes; the full typed model remains product direction.

5. **Observation** — An immutable structured assessment at a defined boundary. It does not establish that a model received, used, or agreed with the evidence.

6. **Snapshot** — An exact, typed published-version coordinate. Existing generation fields and historical identities are not renamed.

7. **Turn Lifecycle** — The computational model: resolve, detect, reconcile, assemble, reason, commit and revalidate. The native candidate implements local reference-only preparation, not live interception.

8. **Turn Frame** — A local candidate artifact that binds prior-frame identity, exact assessment/input hashes, State identity and reference preparation for one diagnostic turn cycle.

9. **Operational Checkpoint** — The planned durable coordinate across History or Snapshot, View, Active State, Observation and computational versions. It should reference immutable objects rather than copy the world.

10. **ReadSet** — The planned exact dependency set a turn relied on, used to decide whether later changes require reassembling the context or revalidating an action.

11. **Action Barrier** — A planned optimistic revalidation boundary before consequential external effects. It is not implemented action authorization.

12. **Receipt** — Evidence for one named operation and stage. Acceptance, reconciliation, submission, completion and verification establish different facts.

# Install and connect Kam AI developer tools

Set up the approved CLI candidate, add the repository-local SDK to an authorized backend, and connect the read-only MCP server to a compatible coding agent.

Status: Merged · local only. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here. SDK 0.36.0 is source-implemented but not published to npm; an authorized service endpoint and tenant binding are separate prerequisites.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/install

## In short

Set up the merged local CLI, add the unpublished SDK package to an authorized backend, and connect the CLI’s read-only MCP server to a compatible coding agent.

**Available today:** The CLI and MCP are merged and qualified for Linux x64. SDK 0.36.0 is implemented in source but not published to npm. Nothing is deployed.

> Use one reviewed contract across local CLI workflows, scoped service integration, and read-only coding-agent tools.

## Install the local candidate

- **Prerequisites** — Use the supported toolchain and candidate distribution.
- **Install** — No public binary release is promised.
- **Connect** — Local inspection is separate from authorized evaluation access.

## Before you install

You need a Linux x64 development environment, an existing application directory, and the separately supplied Kam 0.1.0 artifact from the qualified backend CI run. Record its version, checksum, and provenance before use.

SDK use additionally requires an authorized backend source checkout, the exact approved SDK 0.36.0 package, a Kam service endpoint, and a server-authorized tenant binding. The CLI and MCP do not require AWS credentials or connect your account to the managed service.

There is no public CLI registry package, public SDK npm package, Homebrew formula, macOS build, or Windows distribution. Do not substitute similarly named packages from a public registry.

[Request candidate access](/support)

## Step 1: place the CLI on your PATH

Use the filename and checksum supplied with the approved artifact. The example keeps the binary in a user-owned directory; adapt the path to your organization’s software policy.

### Install and verify the approved candidate

```bash
mkdir -p "$HOME/.local/bin"
install -m 0755 ./kam "$HOME/.local/bin/kam"
export PATH="$HOME/.local/bin:$PATH"

kam --version
kam capabilities --json
```

> **Verify before use**
> Do not substitute an artifact from an unreviewed source. A successful version command establishes local execution only—not service access, deployed IAM, or production qualification.

## Step 2: initialize one project

Run from the application directory you want Kam to inspect. The first command prints the proposed changes. Nothing is written until you repeat it with --write.

### Plan, write, and check local setup

```bash
cd /path/to/your-application
kam init --template deployment-agent
kam init --template deployment-agent --write
kam doctor --json
kam generate --check
```

> **Local diagnostic boundary**
> kam doctor checks local configuration, declarations, and generated-file drift. It is separate from the authenticated kam-history doctor command and does not prove cloud permissions.

## Step 3: add the SDK to an authorized backend

Use the exact approved SDK source supplied for your evaluation and preserve its version with the backend that calls it. The current import is repository-local; there is no supported npm install command.

Configure endpoint, tenant, and access-token inputs through your backend’s existing secret and deployment controls. Never embed credentials in browser code, generated agent guidance, MCP configuration, or this static website.

### Create a scoped client and preserve exact references

```javascript
// Save as a .mjs file in an authorized backend source checkout. SDK candidate 0.36.0.
// This is a read-only example, not code executed by the website.
import { createKamClient } from './server/trajectory/sdk/index.mjs';
const kam = createKamClient({
  baseUrl: process.env.KAM_API_URL,
  tenantId: process.env.KAM_TENANT_ID,
  accessToken: () => process.env.KAM_ACCESS_TOKEN,
});
const deployments = kam.scope({ subjectId: 'checkout', type: 'deployment' });
const page = await deployments.allIds({ day: '2026-10-06', limit: 16 });
if (page.status === 'ready' && page.items.length > 0) {
  const exact = await deployments.byIds({
    day: page.day,
    generation: page.generation,
    refs: page.items,
  });
  console.log(exact.records); // Keep every position and result status.
}
// A short page is not the end when nextCursor is present.
// Continue with the SAME generation and returned cursor.
```

> **Service access is separate**
> Possessing the SDK does not authorize a tenant or AWS account. Validate the approved endpoint, principal, server-side tenant binding, lifecycle status, and supported scope before sending outcomes.

[Read the full SDK integration guide](/docs/integrate)

## Step 4: connect the read-only MCP server

Add the server to a coding agent that supports local stdio MCP processes. Client configuration locations differ, but the server command and arguments follow this shape. Use the absolute path returned by command -v kam.

The client starts kam mcp and communicates over stdio. Do not wrap it in a TCP listener or add shell, credential, arbitrary-path, or write capabilities.

### Generic MCP client configuration

```json
{
  "mcpServers": {
    "kam": {
      "command": "/home/you/.local/bin/kam",
      "args": ["mcp"]
    }
  }
}
```

## Step 5: verify the connection

1. **Restart or reload the MCP client** — The client should start the local stdio process itself; a separate hosted Kam endpoint is not involved.

2. **List the Kam tools** — Confirm the client exposes only the documented read-only tools, including project status, View manifest, fixture replay, reference Atlas, and bundled docs.

3. **Read project status** — Call kam_project_status in the application directory and review configuration or drift findings. This is a local filesystem assessment, not an AWS account check.

4. **Keep effects explicit** — Use the CLI with --write for reviewed generation changes. MCP remains read-only and cannot install packages, edit files, run a shell, or deploy infrastructure.

[Understand every MCP tool](/docs/agent-tooling)

[Continue with the CLI workflow](/docs/toolkit)

## Update or remove the candidate

There is no public self-update channel for the local CLI artifact. Replace it only with a separately supplied artifact from an approved qualification run, verify the new version and checksum, then rerun kam doctor and kam generate --check.

Update the SDK only from an approved source revision and review its API and service compatibility before changing the pinned package in your backend. Do not replace the repository-local package with an unverified registry package.

To disconnect MCP, remove the kam server entry from your client and reload it. Remove the local binary or SDK package only after confirming no project, backend, or client configuration still references it.

# Develop locally with the real Rust engine

A plan-first developer loop over the same History and State implementation used by the service.

Status: Merged · local only. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/toolkit

## In short

A command-line tool that runs the real Kam Rust engine on your machine against synthetic data, so you can see how State would change before connecting anything. It plans file changes before writing them.

**Available today:** Merged and qualified for Linux x64 only. There is no public download.

> Local tools should make the contract easier to use, not create another implementation of it.

## One local command, inspectable output

- **Run locally** — The toolkit invokes the shared Rust semantics.
- **Inspect output** — Read identities, bounds, blockers, and retained evidence.
- **Know the limit** — No AWS or model call; no Gateway or remote rollout.

## Start with the distribution boundary

This guide describes the native toolkit merged into the backend in PR #176. It is not an installer you can run from a public registry: access requires a separately supplied Linux x64 artifact from the qualified backend CI run, with its exact provenance. macOS and Windows distributions are not qualified.

The website is static documentation. It does not run Rust, create files, read credentials, or attach anything to your AWS account.

[Discuss toolkit access](/support)

[Compare source checkpoints](/updates)

## Inspect the plan before writing files

Run inside an existing application directory with the approved binary on your PATH. init is read-only until --write. generate --check detects drift rather than repairing it silently.

The lab supplies synthetic storage observations and explicit fences. It exercises real Rust decisions, not AWS transactions, a cloud emulator, or an agent execution.

### Local workflow — not a public installer

```bash
# Merged toolkit, no public binary. Use an approved Linux x64 artifact.
# No public installer is available. These commands run locally.
kam init --template deployment-agent
kam init --template deployment-agent --write
kam doctor --json
kam generate --check
kam dev --json
kam replay --scenario invalidated --json
kam atlas --scenario corrected --json
kam qualify --json
```

## One namespace, explicit effects

1. **Configure** — init · config · generate · doctor · env. Plan-first local files and diagnostics. kam doctor is not the remote kam-history doctor.

2. **Exercise** — dev · state · replay · atlas · preview · qualify. Synthetic observations and the actual Rust engine. No live source calls, agent replay, or token estimates.

3. **Inspect & explain** — inspect · docs · skills · mcp · capabilities. Private local reports and read-only agent tools. No hosted console or public share link.

4. **Plan integration** — connect agentcore · promote · rollback. Reviewable connection and local channel plans only. No Gateway attachment or remote rollout.

## Local, preview, and production are not interchangeable

The strict static kam.config.json compiles into a normalized, fingerprinted manifest. Profiles contain environment-variable names rather than secret values. Preview and production cannot fall back to synthetic local execution.

kam doctor checks local config, SDK declarations, and generated-file drift. kam-history doctor is the separate existing SDK command for remote account/onboarding metadata and requires explicitly supplied credentials. Neither is proof of effective deployed IAM.

## Connection and channel commands are plans, not deployment

connect agentcore emits a bounded History read-tool plan with authentication, tenant mapping, schema acceptance, and IAM work still to qualify. AgentCore tooling remains responsible for integration infrastructure.

promote and rollback record local review-channel changes. They do not deploy a policy, restore deleted evidence, or restore revoked permissions. qualify reports local fixture checks, not source-package or live AWS release qualification.

# Only call State current when its evidence holds

A View declares what evidence it needs. Kam checks that the evidence is present, fresh, and within limits before calling the answer current.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Owner-configured Views, reverse-dependency memberships, and bounded same-scope multi-source dependency processing are implemented in source. The SDK 0.36.0 candidate reads current Active State and exact retained Observations. None of it is deployed; cross-scope joins, a deployed State endpoint, and customer realtime subscriptions remain staged.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/state

## In short

A View is a saved question over your data, such as "the latest passing security check for this service." Kam only calls its answer current when the required evidence is present, fresh, and within limits; otherwise it says it is blocked and why.

**Available today:** Implemented in source for same-scope Views with one or more sources; the SDK candidate reads current State. Not deployed.

> Preserve historical evidence. Refuse to reuse it as current when its conditions no longer hold.

## Current State and retained evidence

- **Inputs** — Exact required and optional references.
- **State** — A bounded projection at an explicit evaluation boundary.
- **Blockers** — Missing or inapplicable evidence remains visible.

## The View owns requiredness

A View declares exact source identities, required and optional dependencies, priorities, freshness windows, and selection limits. Observations report lookup results; they cannot change that policy. Current invalidation counters are supplied separately.

An omitted required observation blocks selection. Foreign sources, duplicate or missing fences, future observation times, and unexpected fields are rejected. A late read from an older fence is invalidated even when it arrives last.

## Current means reusable evidence, not approval

1. **Missing or unresolved required evidence** — State is blocked with explicit issues and no usable selection identity. Missing evidence is not silently removed.

2. **Required references exceed the budget** — State blocks instead of trimming them. Optional references follow deterministic priority with explicit budget exclusions.

3. **Current evidence describes a failure** — The result may be current and still accurately report a failed security check. Admission is not a deployment decision.

## Freshness differs from retention

A freshness deadline makes evidence stale. Its availability deadline makes it expired. A newer invalidation counter can invalidate it earlier. All deadlines are exclusive; a reuse deadline is an upper bound, not permission to ignore later changes.

Exact versions across several sources do not establish one atomic cross-source snapshot. The runtime must check current permissions and source conditions at the serving or conditional-commit boundary.

## Views are connected to durable history

The server-owned trajectory-current View is wired end to end, and owner-configured Views can depend on it within the same scope. When a View's answer changes, Kam saves the new current pointer, a frozen Observation of the assessment, and a record of what changed in one conditional write. When the answer is unchanged, the existing pointer is reused and nothing new is written.

Change notifications are queued, bounded, and re-sent by a maintenance sweep if a wakeup is lost. When a source changes, Kam pages through the Views that depend on it, up to eight at a time, and saves its cursor so it can resume safely after a crash. Dependent execution supports one or more required sources in the same scope (PR #187); cross-scope joins remain staged. The SDK 0.36.0 candidate reads the result with activeState() or a Component's read().

[Read the Observation boundary](/docs/observations)

## Measure the thing being limited

Internal admission accepts 1–32 dependencies, maxItems of 1–32, and maxReferenceBytes of 2–32,768. Reference bytes mean the UTF-8 JSON selected-reference array, including its metadata and punctuation.

This does not measure rendered prompts, model tokens, total response bytes, fetched payloads, or production latency. The native candidate’s Atlas displays the reference measurement without inventing a token conversion.

# Keep the Observation when current State changes

When current State moves on, the assessment it replaced stays available to inspect for as long as it is retained.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Owner-configured Views, reverse-dependency memberships, and bounded same-scope multi-source dependency processing are implemented in source. The SDK 0.36.0 candidate reads current Active State and exact retained Observations. None of it is deployed; cross-scope joins, a deployed State endpoint, and customer realtime subscriptions remain staged.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/observations

## In short

Each time current State changes, Kam keeps a frozen copy of the assessment it replaced, so you can later see what was considered current and when. That copy records what Kam selected, not what a model actually read.

**Available today:** Implemented in source; the SDK candidate reads exact Observations. No deployed endpoint.

> Version the derived evidence; do not rewrite the history that explains it.

## Retention is not applicability

- **Retained assessment** — The recorded observation remains evidence.
- **Current applicability** — Its definition, sources, and time must still apply.
- **Consumer decision** — The application decides whether to use it.

## Three records with different jobs

1. **Active State pointer** — Identifies the current assessment for the server-owned View, with lifecycle and source-version conditions.

2. **Immutable Observation** — Retains the exact structured assessment, scope, View, pointer version, and candidate hash for that successor.

3. **Change evidence and delivery receipt** — Describe a particular transition and its internal queue delivery. They do not establish that a customer agent received it.

## Selection is not the final model input

An application may filter, reorder, truncate, or reformat selected evidence before calling a model. The structured Observation alone cannot reconstruct those later transformations.

A separately qualified capture boundary must record the assembled evidence or an approved immutable content reference, ordered source revisions, and transformation versions. Submission is still not proof of internal reasoning, consumption, or decision quality.

## Immutable does not mean retained forever

Observations are derived customer data with availability and deletion responsibilities. Current source export classifies them with the State pointer, change events, delivery receipts, and cursor. Retention and live erasure have their own gates.

The SDK 0.36.0 candidate reads an exact retained Observation with observation(); it never substitutes the latest version and always reports usableForCurrentReasoning: false. No deployed Observation endpoint, automatic S3 archive, or universal historical reconstruction service exists.

[Retention and evidence availability](/docs/retention)

[Customer exit controls](/docs/marketplace)

# One contract from command to computation

How the command line and agent tools share one definition and one read path without sharing permission to write.

Status: Local candidate · in review. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/developer-architecture

## In short

How the toolkit stays consistent: one definition of each command, one shared read path for the command line and agent tools, and read handlers that physically cannot write files or reach the network.

**Available today:** Part of the merged native toolkit; local only.

> Centralize shared definitions. Keep effects and mutable data at explicit boundaries.

## Command to computation

- **Command** — Declare the task and bounded inputs.
- **Contract** — Validate scope, identity, and work limits.
- **Runtime** — Injected reads supply data; they do not grant authority.

## The same operation has one owner

1. **One command contract** — CLI options, help, and the explicit MCP subset come from one typed Rust catalog. A new CLI command is not automatically an agent tool.

2. **One application read path** — The CLI and MCP share query handlers for local configuration, diagnostics, replay, and Atlas. Only their transport envelopes differ.

3. **One bounded operation context** — Each operation shares captured immutable file buffers and a normalized View index. The next request gets a fresh capture, not a global customer-state cache.

4. **Read-only dependency injection** — Read handlers receive a bounded ProjectReader with no writer, credential, shell, or network capability. The real Rust engine remains the decision owner.

5. **Protected generation** — Writes require --write. Planning and commit share conflict rules; changed configuration or managed guidance aborts the old plan.

6. **Two independent artifacts** — The service and native toolkit are packaged separately and tested without source or network. Local evidence is not a production release or live service guarantee.

## Borrow one View; capture one operation

A ProjectSnapshot keeps one normalized manifest and an ID-to-position index beside its ordered View payloads. Handlers borrow the selected View rather than copying it into another state store.

Each ReadSession shares immutable file buffers, misses, and errors within one operation. The limits are 128 file/presence observations, 2 MiB total captured content, and 300 KiB per file. Every subsequent MCP call gets a fresh capture.

This is not an atomic cross-file snapshot, a global tenant cache, a database migration, or a constant-time historical reconstruction guarantee. Only immutable embedded SDK/OpenAPI assets are shared process-wide.

## Inject reads, not permission to do everything

ProjectReader exposes bounded reads and presence checks. It has no writer, credential, shell, or network operation. Tests inject in-memory readers with counters and failures; production uses a checked filesystem adapter.

The canonical hashes and History/State engine are not replaceable through that interface. Local writes retain their source observations, acquire a cooperating-writer lock, recheck inputs, and re-plan against current target bytes. Changed config or guidance aborts a stale plan.

These controls protect cooperating local workflows. They do not claim an atomic multi-file transaction or a sandbox against a malicious filesystem owner.

# Give coding agents the same contract as developers

The native toolkit exposes a narrow read-only MCP surface and version-matched guidance.

Status: Merged · local only. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is merged into the backend (PR #176) and qualified in CI as a network-disabled Linux x64 artifact. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/agent-tooling

## In short

Coding agents get the same rules as people: five read-only tools, version-matched docs, and every website guide available as Markdown. None of the tools can write, run shell commands, or reach the network.

**Available today:** Website Markdown is live now. The local MCP tools are part of the merged native toolkit.

> A tool description should teach the same limits the implementation enforces.

## Choose a tool by task

- **Understand** — Read the same guides as Markdown.
- **Inspect locally** — Use toolkit outputs and exact source identity.
- **Inspect History** — Read-only authorized routes; no write or model execution.

## Five tools, not a shell proxy

The server uses stdio with initialization and bounded framing, not a public TCP endpoint. Unknown, null, cross-tool, write, shell, and arbitrary-path arguments fail before project reads.

1. **kam_project_status** — Local configuration and generated-file drift. No live account or IAM check.

2. **kam_view_manifest** — A normalized manifest and configuration fingerprint, not deployed authority.

3. **kam_replay_fixture** — Re-evaluate supplied synthetic scenarios with the real Rust engine, without executing an agent.

4. **kam_reference_atlas** — Selected-reference JSON bytes and explicit omissions, not model-token counts.

5. **kam_docs** — Bundled version-matched documentation.

## Generated instructions are reviewable local files

Generation produces versioned Markdown, llms.txt, llms-full.txt, skills, and a managed AGENTS.md block. Surrounding customer instructions are preserved. Edits to managed content and concurrent source changes are detected.

Generating guidance does not install packages, activate an agent configuration, or register a GitHub workflow. The customer reviews the proposed artifacts and explicitly chooses integration steps.

## Read these website guides as Markdown

Each public guide has a Markdown equivalent generated from the same typed content as the HTML page. The documentation manifest lists both addresses. Availability labels and reviewed source identities are included; unpublished tools are not presented as installed services.

[Agent-readable index](/llms.txt)

[All guides in one document](/llms-full.txt)

# Separate subscribing, connecting, and authorizing

A managed add-on should make setup understandable without hiding identity, retention, or action boundaries.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/marketplace

## In short

Subscribing, connecting, and granting access are three separate steps, and leaving is designed in from the start: an owner can export their data, delete it, and guard against an accidental restore.

**Available today:** Export, deletion and restore fencing are implemented in source. There is no live Marketplace listing.

> A subscription is not permission to access a customer AWS account.

## Three separate steps — planned purchasing

- **Subscribe** — No live Marketplace listing or purchase flow.
- **Connect** — A subscription would not configure the workload.
- **Authorize** — Access must be explicitly scoped and checked.

## Inspect readiness before sending data

The SDK candidate can discover bounded visible workspaces and inspect owner-only account and scope onboarding metadata. kam-history doctor is the read-only diagnostic; quickstart is the separate documented write path.

Account status distinguishes commercial observation, authorization freshness, lifecycle, and reconciliation health. A stale background check is neither cancellation nor permission to extend an expired grant. Effective deployed behavior remains a qualification requirement.

## A bounded export is implemented

An authorized owner closes outcome ingress, waits for the captured lifecycle boundary, then requests an export session. Preserve exportId, scope, page order, pageHash, and the opaque returned cursor. Check session completion before using the export to authorize deletion.

The export is a closed-ingress operational view, not one atomic database snapshot across all pages. Source changes and authority changes have explicit behavior. The current limits are 32 registered scopes, ten records per page, and 512 KiB of page JSON.

## Export, deletion, and restoration are different controls

Primary-state deletion and a separately retained restore fence are implemented. Simulated exact AgentCore erasure is distinct from a qualified live downstream deletion journey. Export success alone proves neither physical deletion nor backup erasure.

Live purchase, renewal, cancellation, grant-refresh outages, revocation timing, remote erasure, and backup restore drills remain separate qualification boundaries.

## The purchasing channel is still planned

There is no live listing or one-click activation yet. SDK publication, native public distribution, support/fulfillment, commercial terms, and live production qualification are not implied by source implementation. An evaluation request does not subscribe you or grant AWS access.

[Scope an evaluation](/evaluation)

[Read qualification limits](/reliability)

# Prove one outcome all the way to an exact read

The Golden Journey turns protected external check evidence into a narrow outcome and a bounded, inspectable History read.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/golden-journey

## In short

A short end-to-end check: send one real result, retry it, read the day it belongs to, and fetch that exact record back. Each step reports what it actually proved.

**Available today:** Runs against an authorized evaluation endpoint with the candidate SDK.

> Use the public SDK boundary—not private database edits—to demonstrate the product.

## Check the proof at every step

- **Submit** — Retain an admitted outcome revision.
- **Enumerate** — Pin the exact collection generation.
- **Hydrate** — Read the returned references without following latest.

## One small journey, separate evidence stages

1. **Map a protected external result** — Use an approved terminal check result and stable business identity. Unknown or pending is not automatically failure.

2. **Accept and retry exactly** — Keep the original payload and revision identity. Compare the returned acceptance behavior without creating another logical outcome.

3. **Enumerate a pinned day** — Preserve the generation across bounded allIds pages. A short page with a cursor is not completion.

4. **Hydrate named revisions** — Use byIds and inspect each records[] status. Check the exact event rather than assuming any successful JSON is a match.

5. **Keep the right receipt** — The harness result explains the stages it actually performed. It is not proof of live Memory delivery or model-input consumption.

## Do not confuse three different demonstrations

The website example is synthetic browser data and does not call the backend. The native toolkit supplies synthetic storage observations to the actual Rust engine. An authorized SDK/service Golden Journey crosses the real HTTP boundary.

Local source/package tests and these demonstrations do not substitute for separately authorized deployed buyer, IAM, recovery, or AgentCore qualification.

[Open the synthetic History example](/#trajectory)

[Read the scoped SDK example](/docs/integrate)

[Explore the native candidate](/developers)

# Inspect History in the console

A read-only, authenticated console for browsing workspaces, scopes, UTC days, and the exact revisions behind them through existing History API reads.

Status: Implemented in source. Prelaunch; not a live service guarantee.
Implemented in website source and tested against fixtures. No live History deployment exists for it to read yet, and it reads nothing until its server settings are configured.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/history-console

## In short

A read-only console where signed-in operators browse workspaces, scopes, and UTC days and see the exact revisions behind each record. It never writes and never substitutes a newer value for the one requested.

**Available today:** Implemented in website source. Not yet connected to a live History deployment.

> See exactly what was recorded, without a write path and without falling back to the latest value.

## Find one exact record

- **Workspace and scope** — Authorized directory; explicit subject and type.
- **UTC day and generation** — Pin retained membership before paging.
- **Exact revision** — Inspect the requested record and its recorded inputs.

## Browse History like folders

1. **Workspaces** — The History API lists the workspaces your account may read, with your role.

2. **Scope** — Registered scopes are listed when the deployment enables its delivery status read; otherwise a subject and record type are opened by name, and the console says why.

3. **UTC days** — Pick a month, then a date inside today and the preceding 364 UTC dates. Being in the window is eligibility, not a claim that the day is complete.

4. **Exact records** — One page of a pinned generation is hydrated to exactly those revisions; the inspector adds timestamps, source references, and the record’s earlier revisions.

## Sign in with your Kam account

The console uses the same Amplify email/password sign-in as the Kam app. The server reads the session, re-verifies the Cognito access token with AWS’s verifier, and calls the History API on your behalf. Which workspaces you see comes from the History API, never from the browser; a refusal is shown as access denied, never worked around.

## What the console will not do

1. **Write anything** — Only read routes are called. There is no outcome, configuration, deletion, or lifecycle action.

2. **Fall back to latest** — A changed generation or a revision that does not match the requested reference is an error, not a substitution.

3. **Read without bounds** — At most 32 references per read, only inside the 365-UTC-date window, and never a cursor without its generation.

[Try the fixture inspector](/inspect)

[Read the History contract](/docs/history)

# Exact identity + versioned membership

Why generation-bound membership and exact hydration are the primitive beneath History, deterministic diffs, structural sharing, checkpoints and replay.

Status: Implemented in source. Prelaunch; not a live service guarantee.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/primitives

## In short

Two ideas carry everything else. allIds() fixes which exact revisions belong to a collection; byIds() fetches exactly those revisions. Keeping "which" separate from "fetch" makes diffs, reuse and replay reliable.

**Available today:** Implemented in source as part of the History contract.

> Separate which immutable revisions belong to a world from how those exact revisions are hydrated.

## Two primitives, many views

- **allIds()** — Which exact references belong together?
- **byIds()** — What exactly is each referenced revision?
- **Views** — Graph and timeline connect those answers for debugging.

## allIds() fixes membership

A bounded day generation names ordered exact revision references. Preserve the returned generation and cursor while paging; a late arrival belongs to a successor generation rather than silently changing the collection being read.

The broader platform reuses this normalized-state idea, but the existing allIds() API keeps its exact History contract rather than becoming a generic dependency endpoint.

## byIds() hydrates exactly what was named

Hydration restores caller order and reports found, unresolved, unavailable and expired positions explicitly. It does not replace an unavailable historical revision with the latest value.

Stable identity plus immutable revisions makes a later diff inspectable: unchanged references can be structurally shared while changed membership becomes an explicit input to reconciliation.

## The method names are not the moat

The leverage comes from the semantics underneath: stable logical identity, immutable revision identity, ordered bounded membership, generation pinning, correction rules, authorization, retention and recovery.

That foundation can support exact checkpoints, replay, State and Context profiling and turn-to-turn change explanations without making probabilistic retrieval the source of operational truth.

[Read State reconciliation](/docs/state)

[See the exact History example](/?capability=workflows#trajectory)

# Check what changed before every agent turn

The Turn Lifecycle combines exact History, change detection, incremental view maintenance, bounded context assembly and future effect revalidation while leaving model execution with the agent runtime.

Status: Merged · local only. Prelaunch; not a live service guarantee.
Validated local Turn Frames, reference preparation, and State profiling exist in the merged native toolkit and run locally only. They do not intercept live AgentCore turns, submit model requests, persist managed Turn Receipts, or authorize external effects.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/turn-lifecycle

## In short

Before an agent reasons, Kam should check what changed since its last turn, update only the affected State, and prepare the evidence the turn needs. After the model answers, risky actions should be rechecked against current State.

**Available today:** A local, reference-only version exists in the merged native toolkit. Nothing intercepts live AgentCore turns.

> Do not make a long-running agent rediscover the world from scratch on every turn.

## Prepared is not executed

- **Implemented checks** — Local validated Turn Frames and evidence references.
- **Applicability first** — Check authority, freshness, and required evidence.
- **Proposed interception** — No live model interception or execution guarantee.

## Resolve → detect → reconcile → assemble → reason → revalidate

1. **Resolve** — Start from exact retained evidence, View definitions, source versions, freshness and authority inputs.

2. **Detect** — Identify which exact identities or fences changed. Provenance change is not automatically semantic change.

3. **Reconcile** — Incremental view maintenance: propagate through declared dependencies and recompute only supported affected State, fencing stale work with version conditions.

4. **Assemble** — Assemble required reference evidence and bounded optional context into a separate model-facing representation.

5. **Reason** — AgentCore or another runtime invokes the model; Kam does not own the model or workflow engine.

6. **Revalidate** — The future action boundary checks the relevant ReadSet before consequential external effects.

## What the native toolkit actually proves

The native toolkit, merged in PR #176, can build a local record of one turn’s preparation, called a Turn Frame (format kam.local-turn-frame.v1). Each frame links to the previous one and pins the exact State, inputs and evaluation time it used, so two turns can be compared line by line.

To avoid overstating what happened, every prepared frame says so explicitly: modelRequestReady false, modelSubmission not_observed, turnReceipt not_committed, liveAuthorization not_checked and persisted false. The candidate is diagnostic infrastructure, not live runtime interception.

## Why did this turn rebuild?

The local profiler compares definition, membership, exact provenance, reported content hash, source fences, temporal inputs and selection disposition independently. Unsupported semantic sameness, provider cache hits and inferred decision causes remain not_observed.

The long-term developer-tools direction is change diagnostics for agent State: explain the source change, affected Views, reused evidence, rebuilt representation and logical versus physical retry work.

# Assemble only the context a turn needs

Context should be a deterministic projection of validated Active State before optional retrieval or learned compression is allowed to enrich it.

Status: Planned · not available. Prelaunch; not a live service guarantee.
Managed payload-bearing context, complete model-request token budgeting, provider-cache integration, live runtime injection and action barriers are planned—not public capabilities.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/context

## In short

Instead of stuffing a prompt with everything, Kam should assemble the evidence a turn requires first, remove exact duplicates, and only then add optional material within a fixed budget, keeping track of where each piece came from.

**Available today:** Planned. No managed context service or prompt injection exists.

> Models should reason; they should not have to rediscover required operational state every turn.

## Select evidence deliberately

- **Required inputs** — Keep the evidence needed for the task.
- **Optional inputs** — Budgeted selection with explicit missing coverage.
- **Proposed compilation** — No measured model-token savings or live serving guarantee.

## Required evidence wins before optional relevance

A View owns requiredness, source identity, freshness and deterministic priority. Missing or expired required evidence should block rather than disappear because a token budget is tight.

Optional evidence can later use customer-provided retrieval and ranking adapters, but relevance scoring must not demote required operational dependencies.

## Prefer deterministic operators before model compression

1. **Project fields** — Select the task-relevant structured fields before summarizing an entire payload.

2. **Deduplicate exact evidence** — Emit one repeated exact fact once while preserving its provenance; contradictory evidence must remain visible.

3. **Budget deterministically** — Admit required dependency closure first, then optional evidence in stable order within a complete-request budget.

4. **Reuse safely** — Reuse deterministic output only while source versions, freshness, authority and assembly inputs remain applicable.

## Adapters connect providers; Rust keeps the rules

Retrievers, embeddings, rerankers, provider token counters and optional compressors belong behind explicit adapters. Their captured outputs can feed the deterministic core without becoming authorization or historical truth.

Provider prompt caching and Kam State reuse are separate optimizations: one reuses model-prefix processing, the other avoids rebuilding operational state.

# AgentCore resumes the workflow. Kam re-checks the world.

Kam complements AgentCore runtime checkpoints by making operational History, reconciliation progress, State lineage and evidence recoverable across long-running work.

Status: Internal implementation. Prelaunch; not a live service guarantee.
History and reconciliation durability exist in source. A named managed operational-checkpoint API, live Turn Journal, WakePlan and persisted Turn Receipt lifecycle remain staged.

Reviewed: 2026-10-07.
Backend source: 1db8cf00a065e14311ce7eb518596759831892ec.
Native toolkit: merged in PR #176, reviewed at 1db8cf00a065e14311ce7eb518596759831892ec.
HTML: /docs/durability

## In short

AgentCore remembers where a workflow stopped. Kam remembers what the world looked like and what changed while it was stopped. The two timelines stay separate so a resumed agent does not act on stale facts.

**Available today:** History and reconciliation progress are durable in source. A named checkpoint API is planned.

> Resume the workflow and independently re-resolve the world it is about to reason over.

## Two owners during a restart

- **Workflow continuation** — The runtime resumes obligations and attempts.
- **State revalidation** — Kam validates exact State and applicability.
- **Stopped work** — Uncertain effects and lost authority stay explicit.

## Two timelines should remain independent

The runtime can checkpoint where execution stopped while Kam advances operational state as external evidence changes. When a sleeping agent resumes, the next turn should not assume its previous operational Observation is still applicable.

Kam therefore should not become another Durable Task or Temporal engine. It supplies the operational coordinate that a runtime turn can bind to.

## A checkpoint should be references, not a copied world

The planned operational checkpoint is a durable coordinate across exact Snapshot or generation, View, Active State, Observation, source fences and computational versions. Immutable referenced objects can be structurally shared across many checkpoints.

That makes time travel and replay cheap enough to use as developer primitives rather than heavyweight database exports.

## Durable reconciliation is already a core advantage

Affected-View discovery persists bounded progress and can redrive lost wakeups. Conditional commits recheck lifecycle, membership and source-State versions so delayed work cannot overwrite newer authority.

The future Turn layer should carry the same discipline into model submission and effects: explicit UNKNOWN outcomes, idempotent stage receipts, and revalidation instead of blind retries.