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 is designed for deployment on AWS. No live hosted service 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

   Reviewed View and reconciliation source; no live-qualified or publicly offered hosted State service is established.

4. 4

   State queries & Components — Source-implemented

   SDK 0.40.0 has a passed offline artifact receipt; the source claim is limited to supported bounded operations, not arbitrary payload queries or live service qualification.

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

   Versioned Context manifests — Source-implemented

   Exact capture, ordered manifests and bounded assembly exist in source. Automatic ranking, managed runtime wiring and live model-consumption proof are not established.

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, retry, correct, read both revisions#

Every call below exists in SDK 0.40.0. Obtain the reviewed private package through an evaluation; the package-name import assumes that artifact has already been supplied. An authorized endpoint, principal and tenant binding are separate prerequisites. No public npm release or self-serve endpoint is offered.

The duplicate assertion checks the same retained revision and acceptance sequence. It does not deduplicate an external model or tool action.

// Private SDK 0.40.0. Not published to npm. Methods checked against the pinned typings.
// Run in Node 22 with the supplied evaluation package and an authorized endpoint, tenant and token.
import assert from 'node:assert/strict';
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. Record revision 1, then resend the identical payload while its evidence is retained.
const original = { id: 'deploy-0412', occurredAt: '2026-10-06T17:00:00.000Z', status: 'success' };
const first = await checks.outcome(original);
const retry = await checks.outcome(original);
assert.equal(retry.status, 'duplicate');
assert.equal(retry.acceptedSequence, first.acceptedSequence);
assert.equal(retry.revision, first.revision); // No new accepted revision.

// 2. Correct it: the next revision, same id and occurredAt. Revision 1 is kept while retained.
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);