Glossary: the terms these guides use
Name State, recall and execution separately in an AgentCore design.
Guide context
Distinguish recorded State, exact History, recall and execution when designing an AgentCore application. Each Kam term names a defined responsibility and limit.
Use one word for each responsibility in an AgentCore design. A revision names a saved version; membership fixes which references belong together; a View answers a declared State question. Recall, model reasoning and tool execution remain separate from those recorded facts.
On this page · 21 sections
Name one responsibility at a time
Identity and membership
Which exact State versions belong to the requested fixed list?
View and evidence
Which declared question do those references answer?
Recall and execution
Memory recalls context; the AgentCore application decides and acts.
One State 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.
Calendar periods · Derivable from existing primitives
What exact History belongs to this year, month, week, day, or saved date range? The frontend calendar builds normalized yearById, monthById, weekById, dayById, and customById selectors over supplied exact History. Ordered year, month and day children share one occurrence catalogue; structural dates have unknown source coverage. One displayed year can include 366 calendar dates without widening the 365-date read or custom-range limits. Browser presets save date preferences only; cross-page collection, scheduling, and Google Calendar synchronization are not implemented.
Recommended reviews · Derivable from existing primitives
Which supplied changes and recorded readers match a declared review rule? A frontend review policy groups exact input-version differences, reported failed checks and unavailable lookups into bounded, inspectable review roots. Candidates preserve source coordinates, recorded paths, coverage and work limits. Calendar containment is separate from dependency reads. The authorized console does not supply exact dependency edges today; it cannot infer them from opaque source references. Recommendations do not certify importance, confidence, safety, or action eligibility, and do not execute work.
Calendar summaries and patch notes · Derivable from existing primitives
What changed in this period, and which exact versions have recorded readers? A bounded frontend selector summarizes supplied occurrences, compares successive exact revisions of the same State identity, and searches recorded labels, values and reader references. A prior supplied revision may sit outside the chosen dates; its boundary remains visible. Patch notes show supplied before/after evidence and name recorded readers without implying that a newer revision was consumed. Summaries use deterministic counts and templates, not model inference. Missing pages, prior revisions and dependency evidence remain unknown.
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.
Since my last review · Derivable from existing primitives
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.
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.
Operational memory · Planned
What work can a replacement agent recover? History and obligations are retained; an explicitly opened local SQLite host can recover accepted records and pending projection work. Managed recovery of whole agent tasks remains planned; the explorer runs no agent.
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.
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.
History · Implemented in source
What exactly was recorded? allIds() names exact revision references; byIds() returns exactly those revisions.
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.
Snapshot · Implemented in source
What did this collection look like when it was published? A generation fixes ordered membership; pages are read against it.
Difference · Derivable from existing primitives
What changed between two publications? Compare exact membership from two generations. The SDK also has bounded diffRevisions over two declared selected-reference arrays; it does not establish a generic generation-diff endpoint or external source completeness.
Dependency · Implemented in source
What relies on this information? Views register versioned dependencies; a reverse index finds dependents.
Invalidation · Implemented in source
Which derived State must be recomputed after this change? Reconciliation pages through affected Views and recomputes only those.
Freshness · Implemented in source
Is this current enough to act on? Active State reports current, stale, blocked or absent. Only current carries usable items; the application still decides whether to act.
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.
Expiration · Implemented in source
When does this evidence stop being usable? Reads report expired at the deadline, before storage cleanup.
Receipt · Implemented in source
What work is still owed, and what was acknowledged? Delivery keeps one obligation per eligible generation and separate receipts.
Bounded query · Implemented in source
Which current evidence matches, within declared work limits? explain() reports the query plan and fixed work limits; value() executes the query over one Active State’s evidence references.
Context budget · Implemented in source
Which selected exact evidence fits this context budget? An ordered, versioned Context manifest selects exact captured evidence and full, descriptor or excluded representations. Assembly enforces item and byte limits; unavailable required evidence blocks a complete package. Automatic relevance ranking and provider-token budgeting remain planned.
Subscription · Planned
Which agents should wake when this changes? watch() is planned; the internal event path is not a customer subscription.
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.
Decision · AgentCore or your runtime
What should the agent do next? Your agents and application on AgentCore plan, decide, and call tools. Kam records the outcome and the exact State the application reported as input.
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.
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 e16b81b4; storage behavior links to the AWS documentation it depends on.
Context manifest#
Standard concept: An ordered, versioned selection of exact evidence references with an explicit representation for each entry.
In Kam: A consumer manifest keeps up to 16 selected evidence entries as full, descriptor or excluded. Hide and restore create new manifest versions; earlier retained selections still name their original evidence.
Limits: Capture and assembly are implemented in source. A manifest is not a model-submission receipt, automatic ranking, a universal memory record or a live-qualified managed service.
Evidence: server/trajectory/test/context-manifest-integration.test.cjs — “real Rust and SDK preserve exact capture, ordered manifests, hide/restore and recovery against simulated durable storage”.
Bounded Context assembly#
Standard concept: Construct a consumer representation from a declared selection while checking authorization, availability and fixed item and byte limits.
In Kam: assembleContext resolves at most 32 exact keys for up to 16 manifest entries and a caller budget up to 192 KiB. Required evidence that is unavailable or expired blocks a complete package; inspection does not hydrate payloads.
Limits: The budget counts captured evidence bytes, not provider tokens or a complete model request. There is no scan, semantic fallback, automatic ranking or substitution of a newer revision.
Evidence: server/trajectory/test/context-manifest-integration.test.cjs — “assembly enforces exact references, required coverage, byte limits and serving-boundary authority”.
History inspection#
Standard concept: A read-only projection of exact hydrated records that preserves request order and distinguishes recorded facts from unobserved effects.
In Kam: inspectHistory performs one byIds request and reports ready or partial entries in requested-reference order. The client explicitly supplies local, remote or unknown acceptance location; unknown is the default.
Limits: Adapter-supplied acceptance location is not independently observed delivery. Model consumption and tool effects remain not_observed; inspection invokes no models, tools or replay.
Evidence: server/trajectory/test/trajectory-inspection.test.cjs — “exact hydration, explicit partial dispositions and acceptance context do not synthesize invocation or effect evidence”.
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”.
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”.
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”.
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”.
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”.
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”.
Standard terms Kam does not claim#
Event sourcing
Kam stores outcomes your application declares, not every domain event, and it does not rebuild your application state.
CQRS framework
Kam separates its own write path from its read models, but it does not provide command handling for your application.
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.
Exactly-once execution
Acceptance is idempotent and processing is at-least-once. External effects need their own idempotency.
Cryptographic authenticity
Content hashes detect change; nothing is signed.
Permanent immutability
Revisions are immutable while retained and expire on explicit deadlines.
Arbitrary point-in-time recovery
Generations pin published snapshots; Kam does not restore any past instant on request.
Delivery and comparison terms#
Outcome
A completed success or failure result declared by your application.
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.
Directory
Bounded, authorized discovery of scopes and Views. A general managed Directory remains planned; the SDK has workspace discovery.
View
A versioned declaration of required or optional evidence, source identities, freshness and selection limits. A bounded owner-configured registry now exists in source.
Active State
The maintained deterministic projection and current reuse assessment over exact source versions, freshness limits and authority boundaries.
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.
Observation
An immutable structured assessment at a defined boundary. It does not establish that a model received, used, or agreed with the evidence.
Snapshot
An exact, typed published-version coordinate. Existing generation fields and historical identities are not renamed.
Turn Lifecycle
Resolve, detect, reconcile, assemble, reason, commit, and revalidate. The native toolkit prepares local references; a separate controlled adapter can record request stages. Automatic runtime interception remains planned.
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.
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.
ReadSet
The planned exact dependency set a turn relied on, used to decide whether later changes require reassembling the context or revalidating an action.
Action Barrier
A planned optimistic revalidation boundary before consequential external effects. It is not implemented action authorization.
Receipt
Evidence for one named operation and stage. Acceptance, reconciliation, submission, completion and verification establish different facts.