Data model · Fields

Every field keeps its full history.

Fields are the fine-grained state on a topic. When a value changes, MemState never silently overwrites it — the previous value is preserved with its timestamp and source, so retrieval can tell the current truth from what used to be true.

Value history (formal view)

Fix a semantic unit u_i (a topic) and a field name f. MemState stores an ordered sequence of revisions; write each revision as a tuple (value, time, provenance) matching the wire shape value, valid_from, provenance, with optional rationale fields why_changed and impact_expected. That sequence is the empirical trace of how the field evolved — what the agent and tools asserted, when, and from which surface.

Query soundness (default). Unless the caller enables temporal expansion, retrieval treats the newest revision as current truth and does not mix older values into the default bundle. When explain or temporal stages are on, the same ordered trace is exposed so the model can answer “how did we get here?” without contradicting the append-only discipline on disk. See also the GEM state overview for how D_t and S_t relate.

Why history and not overwrite

Overwriting a value loses information the agent may need later: when did this change, who changed it, what was the old value? It also breaks any form of audit, rollback, or "what did we believe before" reasoning.

MemState treats every field as a stack of revisions, newest first. Writes append. Reads return the newest revision by default. Callers that explicitly ask for history get the full timeline.

Each field is a time-ordered stack of revisions. Writes append. Reads default to the newest one; history is opt-in.

What a revision contains

Every entry in a field's history carries enough metadata to explain the change.

Attribute	Description
`id`	Unique revision id (UUID).
`value`	The value at this point in time.
`valid_from`	Timestamp the revision was recorded.
`provenance`	Where the change came from: `api`, `ui`, `llm`, `mcp`, or an internal revision event.
`why_changed`	Optional reason, usually written by the agent or the caller.
`impact_expected`	Optional forward-looking note about consequences of the change.

Field record

{
  "owner": {
    "field_type": "string",
    "ref_topic_id": null,
    "salience": 1.2,
    "history": [
      {
        "id": "6f3...",
        "valid_from": "2026-04-22T12:00:00+00:00",
        "value": "Aya",
        "provenance": "ui",
        "why_changed": "handoff from Priya"
      },
      {
        "id": "2a1...",
        "valid_from": "2026-03-10T09:10:00+00:00",
        "value": "Priya",
        "provenance": "llm"
      }
    ]
  }
}

Supported types

Type	Typical value	Notes
`string`	Free text	Default type when none is specified.
`int`	Integer number	Stored as JSON number in history.
`float`	Decimal number	Stored as JSON number in history.
`bool`	`true` / `false`
`date`	Date string	Convention-based; not strictly parsed.
`datetime`	Date-time string	Convention-based; not strictly parsed.
`list`	JSON array	Nested content allowed.
`json`	Any JSON shape	Opaque to MemState; size affects latency.

The write path

An observation reaches MemState. Typically via /v1/ingest, a UI tool, or a chat-driven tool call that forwards what the agent noticed.
MemState builds a new revision. It assigns a UUID, stamps the time, records the provenance, and carries any reason the caller provided.
The revision is prepended. It becomes the new current value; previous revisions remain in the stack.
Limits are enforced. If the stack exceeds the configured history cap, the oldest revisions are trimmed.
Topic salience is refreshed. The topic's importance score is recomputed from its fields so retrieval stays in sync.

Field-level salience

Each field carries its own salience score between 0 and 10.
Retrieval bumps salience on read; forgetting consults it when deciding what to attenuate.
The topic's overall salience tracks the average of its field saliences, so the node-level signal is always consistent with its parts.

Limits

History length is capped at 500 revisions per field by default (max_field_history). Oldest revisions are trimmed beyond the cap.
Field salience is clamped to the range [0, 10].
JSON payload size is not enforced by MemState but affects retrieval and API response latency.

Code map

memstate.datamodel.fields.TopicField — field shape, type coercion, salience clamp.
memstate.datamodel.fields.FieldHistoryEntry — revision payload.
memstate.store.GraphStore.append_field_history — write path and trimming.
memstate.core.Executor._field_bundle — read path for current-only and history expansions.