Keep goals and estimates separate from physical facts

ALYT keeps physical facts separate from retained goals, estimates, and summaries. Sensor observations remain the source of physical truth, while memory records are bounded annotations that describe intent or inference. They never grant action authority, never overwrite observed state, and never become an unattended standing policy. Use these interfaces only through the installed ALYT adapter with a current ordinary authenticated actor or an explicit verified HOUSEHOLD_DEVICE authority under the existing Owner-granted household-voice authority.

Declare structured goals explicitly

The same record route accepts alyt.environment-memory-input/draft-0.3.0 for retained GOAL and DECLARED_GOAL, and typedGoal is optional: providing a typedGoal uses the separate existing typed cohort, while untyped retained goals use the original retained cohort with the current authorized owner and remain unknown structured targets. Legacy draft 0.2 structured typed goals and legacy draft 0.1 text goals stay supported, with draft 0.1 capped at 5 min and its lifecycle result preserved. The draft 0.3 path allows empty evidenceRefs[], a lifetime up to 86400000 ms, and same-owner fresh session, restart, and observation updates only while the original retained scope remains unchanged; policy changes, structural scope changes, cancellation, or expiry invalidate it. A legacy summary is never parsed into action authority or a typed target.

The typed declaration names kind (SET_VALUE, ACHIEVE_RANGE, RUN_ROUTINE, INTERPRET, ATTEND, or OUTSIDE_KNOWLEDGE), nullable current entityRef, roomRef, controlRef, value, exact descriptor unit, minimum, maximum, routineRef, installedVersion, priority0–100, up to three dependsOn entries with exact owned goal ID/record revision, and dependencyMode (ORDER or OBSERVED_COMPLETION). Entity/control targets are explicit; no room/category selector or unit conversion is inferred. The outer room/entity scope must agree. Typed goals cite no invented observation. SET_VALUE requires declared writable state and exact Boolean/option/numeric bounds and grid. Range/interpret/attend requires a readable target; a range does not declare an actuator’s causal effect. Routine goals require the exact returned installed routine version; eligibility still belongs to ALYT validation. Color/momentary/unresolved setters are refused.

ALYT persists resolved private target bindings inside its existing memory JSON and retains the original legacy state on first typed admission. There is no new table or parallel memory store. Dependencies require earlier exact active owned typed records, so no self/cyclic dependency is admitted. Cancellation, expiry, changed policy, or structural-scope invalidation withdraws dependent declarations transitively. Satisfaction and physical completion are not inferred from record existence or a model’s findings. Original expiry remains unchanged and the existing record/state capacity limits remain enforced.

The lifecycle query remains draft 0.1 and returns no private typed bindings. Use the authenticated Reasoning companion read for current opaque typed declarations. Disable typed intake and companion cohorts for rollback; retain stored draft 0.3 JSON and a compatible reader. An older strict draft 0.1 reader withholds annotations instead of clearing physical state. Do not destructively rewrite typed declarations into legacy text to make an old reader accept them.

What this memory interface is for

Use environmental memory when you need to retain one of these bounded record types:

• a declared intent, as GOAL with DECLARED_GOAL
• an estimate, as HYPOTHESIS with ESTIMATE or UNKNOWN
• a replaceable summary cache, as SUMMARY with ESTIMATE or UNKNOWN

An explicit goal does not claim that its desired state already exists. Estimates and summaries are separate from observations, and summary caches are labeled estimates.

This is an engine-only ALYT adapter interface. Ordinary developer application API keys, DEV credentials, and LIVE connector credentials do not grant memory access. The caller must have the existing current ordinary authenticated actor or an explicit verified HOUSEHOLD_DEVICE authority under the existing Owner-granted household-voice authority. Keep native binding and credentials inside ALYT; a model cannot supply owner or physical-state writes.

There is no handler at the bare /environment/memory prefix.

Record memory

Create or retry a record with:

POST /properties/:propertyId/environment/memory/record?tenantId=...

Send alyt.environment-memory-input/draft-0.3.0 with:

• a new versioned id
• the returned pinned context
• kind = GOAL
• uncertainty = DECLARED_GOAL
• roomRefs
• entityRefs
• empty evidenceRefs
• bounded lifetimeMs

Use only current returned references in the declared scope. Before the first report for a record, missing history remains unknown rather than inferred from later receipts. Use only current returned references in the declared scope. Before the first report for a record, missing history remains unknown rather than inferred from later receipts.

Required rules

• Use GOAL with DECLARED_GOAL for declared intent.
• Use HYPOTHESIS or SUMMARY with ESTIMATE or UNKNOWN for an estimate.
• Estimates and replaceable summary caches require fresh cited physical evidence.
• A goal does not require evidenceRefs.
• Non-goal records must include evidence.
• lifetimeMs must be positive.
• Legacy draft 0.1 and draft 0.2 records, including goals, remain capped at 300000 ms.
• Retained 0.3 declared goals may use up to 86400000 ms when the retained scope, owner, and session remain valid.

ALYT binds native targets, current owner and session, inventory, and original canonical evidence from the pinned context. The request body cannot set owner, native tenant, property, room, or device IDs, permissions, created or expiry time, raw device state, or a standing action policy.

Repeating an identical intake does not extend original expiry. If the same id is reused with changed content, a changed owner, or a cancelled or invalidated record, the request is refused and you must submit a new request.

Query lifecycle

Read retained lifecycle state with:

POST /properties/:propertyId/environment/memory/query?tenantId=...

Request body:

{"schemaVersion":"alyt.environment-memory-query/draft-0.1.0"}

The response schema is alyt.environment-memory-result/draft-0.1.0.

Memory query returns lifecycle records only; it does not return physical observations or the normalized context’s hypotheses/goals arrays. Use the existing context-query interface when you need the current bounded physical context and its separate hypotheses and goals arrays. Current-session scope does not create truth, and retained0.3 goals keep their own separate typed binding rather than copying physical observations.

Each returned record includes:

• id
• kind
• summary
• uncertainty
• recordRevision
• original createdAt
• original expiresAt
• status

Possible status values are:

• ACTIVE
• CANCELLED
• EXPIRED
• INVALIDATED

The query result is limited to the current actor’s own records. Native identities, session credentials, and evidence fingerprints are not returned.

Cancel a record

Cancel an owned active record with:

POST /properties/:propertyId/environment/memory/cancel?tenantId=...

Request body:

{"schemaVersion":"alyt.environment-memory-cancel/draft-0.1.0","id":"...","recordRevision":"..."}

You must send the exact recordRevision from the latest lifecycle read. Cancellation persists before consumption and prevents queued retries from restoring the record.

If the record already changed, expired, was invalidated, or the revision is stale, the request returns a conflict. A changed or cancelled identity requires a new admitted request; do not resurrect it from a cached summary.

Reading results

Keep lifecycle query and physical context reading distinct:

Need	Interface	Returns
Record lifecycle	POST /properties/:propertyId/environment/memory/query?tenantId=...	lifecycle records only
Current physical context	existing context-query interface	physical observations, plus separate hypotheses and goals arrays

Neither response changes an observed field or authorizes execution.

Normalized context carries hypotheses and goals separately from observations, with opaque owners and original expiry. Paging can omit a hypothesis if its evidence is outside the returned page; preserve omission flags. Starting-room reads explicitly omit memory rather than applying whole-home lifecycle against incomplete inventory.

Limits and invalidation

Capacity and size limits

Limit	Value
Max retained records per home	64
Max active goals per home	8
Max active hypotheses and summaries combined per home	8
Max evidence references per record	16
Max memory state size	32,768 bytes
Max record lifetime	300000 ms for legacy draft 0.1 and draft 0.2 records, including goals; up to 86400000 ms for retained 0.3 declared goals
Terminal retention after cancellation, expiry, or invalidation	5 minutes

Legacy records and estimates cannot outlive current read authority or cited field expiry. Explicit retained 0.3 goals store original intent duration separately from the finite read lease; a stored goal never grants permission, and current owner / read access checks are always required. No renewal of original declared expiry.

When records are withdrawn

ALYT can invalidate or expire retained estimates without changing the underlying physical reading. Common causes include:

• unknown clocks
• missing or deleted evidence
• changed inventory
• changed owner scope
• loss of current read authority
• evidence that expires before the requested lifetime

An inference can expire while its sensor remains fresh. An estimate does not create person-room membership or prove someone is present from a Wi-Fi device.

Errors and retry behavior

Condition	Response
Invalid input	400
Stale context, changed record or basis, concurrent change, or capacity reached	409
Missing current access	refused by existing authentication and membership checks

A concurrent home transaction can also return 409; obtain current context before retry. Use a new bounded view after 409.

Local snapshot and replay retain original age. A finite 5 minute lease is never renewed by replay. Cloud-primary access requires current cloud permission, while commissioned local-primary access renews only with fresh authenticated local ALYT permission without WAN; there is no automatic primary election or second writer. Restart or WAN loss cannot renew cloud membership or record lifetime. Local functions can keep working during a cloud outage, but cloud-dependent connectors require the provider and network. This memory interface stores read-only lifecycle only; deterministic proposal, execution, and outcome interfaces remain the owners of actions and physical confirmation.

Explicit declared goal adapter

Use the private POST /internal/physical-ai/properties/:propertyId/speech-declared-goal?tenantId=... with alyt.speech-goal-input/1.0.0. It requires the internal service identity plus the current authenticated household actor, or the existing explicitly authorized household-device actor. declarationKind is EXPLICIT_DECLARED_GOAL; mode defaults to SHADOW, which validates without retaining a new goal, while RETAIN records intent and does not grant physical authority. Supply the exact source/context/artifact pins: source.contextId, canonical Speech contextDigest, original complete transcript, installed routerArtifactSha256, nullable reasoningArtifactSha256, and typed memory0.3 draft input. The declaration’s native context must match the original Speech turn. Current actor, service/session/source/descriptors/units and installed policy are validated by ALYT. The model provides no owner identity, private bindings, permission, or physical confirmation. The atomic home-memory lock/transaction writes the unchanged draft 0.3 memory record and source lineage to the existing audit log; lineage preserves request/session/segment, context hashes, language, actual model/policy revisions, and a transcript hash rather than raw transcript. Abort before commit rolls back both writes. Exact later revision cancellation marks the record CANCELLED rather than deleting it. Expiry follows the original utterance time plus requested lifetime, at most 24 hours; restart retry preserves that expiry and original meaning without renewal.