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

# Operational state for long-running agents

Start with exact History, then follow versioned Views, incremental Active State, validated local Turn Frames, receipts, and the staged live Turn Lifecycle without confusing source implementation with production availability.

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

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs

> Kam is an independent managed operational-state layer for long-running AI agents. History is the durable kernel; exact identity and versioned membership feed Rust-owned reconciliation, Active State, and the Turn Lifecycle.

## Three questions Kam helps answer

1. **What exact operational evidence existed?** — History preserves admitted 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](/explore)

[Read the Turn Lifecycle](/docs/turn-lifecycle)

## Choose the right entry point

The History SDK remains the established integration surface. Bounded owner-configured View definitions and dependency registration are source-implemented; current-State and Observation serving remain internal. The native developer toolkit is a separately reviewed, unmerged candidate. None of these source checkpoints is a live Marketplace listing.

[Native toolkit candidate](/docs/toolkit)

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

[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)

# 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/integrate

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

## 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 annotated SDK example](/explore#sdk)

## 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.31.0 provides scope({ subjectId, type }) as a thin adapter 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.29.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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/history

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

## 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](/explore#walkthrough)

## 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/event-driven-memory

> Persist the work before relying on a wakeup.

## 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 data-flow diagram](/architecture#data-flow)

## 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](/explore)

## 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

The reviewed outcome ledger 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/publication

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

## 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. New corrections and time-only refreshes do not replace unfinished earlier obligations.

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

> **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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/retention

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

## 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/reliability

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

## 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/qualification

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

## 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 — Internal implementation** — The server-owned trajectory-current slice conditionally persists a State pointer, immutable structured Observation, and change evidence. No public State or Context endpoint is activated.

3. **State reconciliation — Internal implementation** — Bounded View registration, acyclic reverse-dependency membership, replay-safe cursor/task progress, and one required same-scope dependent-View execution path are implemented. General multi-source joins and public current-State serving remain staged.

4. **Turn Frames and profiler — Local candidate · in review** — Validated local Turn Frames, reference preparation, and State profiling exist in the unmerged native-toolkit candidate. They do not intercept live AgentCore turns, submit model requests, persist managed Turn Receipts, or authorize external effects.

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

6. **Native developer toolkit — Local candidate · in review** — Native toolkit 0.1.0 is an unmerged review candidate, locally qualified on Linux x64. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

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

8. **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.

9. **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.

10. **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.

# Seven terms used in this contract

Small definitions for the ledger, rolling views, and delivery loop.

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

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/concepts

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

## Outcome

A completed success or failure result declared by your application.

## Revision

One version of an outcome. A correction adds the next revision under the same identity.

## Generation

A fixed published view. Daily and trajectory generations are different views; use the reference returned by the relevant API.

## Checkpoint

The saved reducer state and applied sequence used to resume processing.

## Trajectory

Precomputed comparisons: last ten results, and 30- and 90-UTC-day windows.

## Delivery obligation

Durable work owed for one eligible generation. It is not proof of a successful delivery.

## 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 rendered-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, render, 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 rerender or action revalidation.

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.

# Develop locally with the real Rust engine

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

Status: Local candidate · in review. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is an unmerged review candidate, locally qualified on Linux x64. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/toolkit

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

## Start with the distribution boundary

This guide describes the unmerged native toolkit review candidate, not an installer you can run from a public registry. Access requires a separately supplied, approved Linux x64 artifact and its exact provenance. macOS and Windows distributions are not qualified here.

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

[Discuss candidate 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 candidate workflow — not a public installer

```bash
# Review candidate only. 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.

# Admit the evidence before calling State current

Requiredness, freshness, retention, and invalidation are separate parts of the contract.

Status: Internal implementation. Prelaunch; not a live service guarantee.
A bounded owner-configured View registry and reverse-dependency memberships are implemented in source. The managed execution path currently supports one required same-scope source; multi-source joins, public current-State serving, live Turn interception, and customer realtime subscriptions remain staged.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/state

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

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

## One internal View is connected to durable history

The server-owned trajectory-current View uses the durable scope head as its source fence. Rust authors the pointer and lifecycle/source-version conditions. Every pointer successor commits with an immutable Observation and change evidence. An unchanged eligible result reuses its prior pointer without another event.

Internal change delivery is bounded, queue-backed, and maintenance-redrivable. The affected-View planner admits membership pages of up to eight rows. A bounded adapter now reads memberships and atomically persists the Rust-authored cursor and pending tasks, with replay-safe continuation. Membership registration and pending dependent-View execution remain staged.

[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

A current pointer can advance while its earlier structured assessment remains separately inspectable under retention.

Status: Internal implementation. Prelaunch; not a live service guarantee.
A bounded owner-configured View registry and reverse-dependency memberships are implemented in source. The managed execution path currently supports one required same-scope source; multi-source joins, public current-State serving, live Turn interception, and customer realtime subscriptions remain staged.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/observations

> Version the derived evidence; do not rewrite the history that explains 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.

No public Observation read endpoint, general View registry, automatic S3 archive, or universal historical reconstruction service is introduced by these internal records.

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

[Customer exit controls](/docs/marketplace)

# One contract from command to computation

Unify the developer interfaces without putting all responsibilities into one module or global cache.

Status: Local candidate · in review. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is an unmerged review candidate, locally qualified on Linux x64. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/developer-architecture

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

## 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 local toolkit candidate exposes a narrow read-only MCP surface and version-matched guidance.

Status: Local candidate · in review. Prelaunch; not a live service guarantee.
Native toolkit 0.1.0 is an unmerged review candidate, locally qualified on Linux x64. No public binary release, macOS/Windows distribution, or live AWS connection is offered here.

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/agent-tooling

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

## 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/marketplace

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

## 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](/pricing)

[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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/golden-journey

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

## 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 candidate 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](/explore)

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

[Explore the native candidate](/developers)

# 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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/primitives

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

## 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](/explore)

# Every agent turn is a validated render cycle over evolving Active State

The Turn Lifecycle combines exact History, change detection, reconciliation, bounded rendering and future effect revalidation while leaving model execution with the agent runtime.

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

Reviewed: 2026-10-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/turn-lifecycle

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

## Resolve → detect → reconcile → render → 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** — Propagate through declared dependencies and rebuild only supported affected State while fencing stale work.

4. **Render** — Prepare required reference evidence and bounded optional context as 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 current native candidate actually proves

PR #176 adds local kam.local-turn-frame.v1 artifacts and canonical reference observations. Frames bind prior-frame identity, exact assessment and input hashes, evaluation time, State identity and preparation status.

Prepared local frames explicitly report 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 DevTools direction is React-like change diagnostics for agent state: explain the source change, affected Views, reused evidence, rebuilt representation and logical versus physical retry work.

# Compile bounded context from reconciled state

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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/context

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

## 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** — Render one repeated exact fact 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 renderer 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.

# Durable execution outside. Durable operational state inside.

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-06.
Backend source: 16f1e66d303a43e245a5cff5c392e9ebd3adf201.
Native toolkit review candidate: fe3df1c237b48d04347b6f159cc49e2f0d830a2c (unmerged).
HTML: /docs/durability

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

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