What Kam stores, writes, reads, and proves

What is stored

1. 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. 2

   Day membership

   Ordered references naming which exact revisions belong to one scope and UTC day, published as generations.

3. 3

   Durable work records

   Work owed to the projection worker, committed with each accepted revision (a transactional outbox).

4. 4

   Checkpoints and projections

   Saved fold state and applied sequence, plus the trajectory comparisons derived from them.

5. 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.

The write path

1. 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

   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

   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

   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

   5. Publish

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

The read path, and what each read proves

1. 1

   trajectory()

   Proves the projection as of appliedSequence, alongside acceptedSequence. If they differ, accepted work is not yet folded.

2. 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. 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. 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. 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.

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.

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.

Who is responsible for what

1. 1

   Your application

   Business meaning of success and failure, stable IDs, idempotency of external effects, and the agent runtime.

2. 2

   Kam

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

3. 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. 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. 1

   History — Locally qualified

   Package qualification is not a live deployment.

2. 2

   Identity & membership — Locally qualified

   Covered by the same package qualification as History.

3. 3

   Views & current State — Source-implemented

   Not deployed. Package coverage of View reconciliation is not confirmed for the website.

4. 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. 5

   Metrics, materialize & watch — Planned · not available

   Design preview only.

6. 6

   Turn Lifecycle — Locally qualified

   Merged native toolkit; reference-only local frames.

7. 7

   Context compiler — Planned · not available

   Design direction only.

8. 8

   Operational durability — Source-implemented

   History and reconciliation progress are durable in source; no named checkpoint API.

9. 9

   Profiler & developer toolkit — Locally qualified

   Merged; Linux x64 only; no public distribution.

10. 10

    Optional AgentCore delivery — Locally qualified

    Default off; simulated AWS transports only.

11. 11

    Export, deletion & restore fence — Source-implemented

    Live erasure and restore drills are qualification gates.

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.

// 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);