dev.bastienrobert.memory.record Documentation (EN)

main record

A single durable memory belonging to the user. Deliberately one generic type: specialising into fact/preference/project/event types is premature until real requirements demand it. Retrieval-specific state (BM25 scores, vector ids, index cursors, caches) MUST NOT be stored here — it is derived data owned by whichever memory engine indexes this record. Consumers MUST preserve properties they do not recognise: an implementation that rewrites a record after dropping unknown fields destroys data written by a newer one.

Record Key tid Timestamp-based ID

Properties

content string Required

The memory itself: one self-contained statement that still makes sense months from now.

maxLength: 10000 bytesmaxGraphemes: 2500 graphemes

createdAt string datetime Required

When the memory was first stated.

kind string Optional

Coarse classification. Open vocabulary: an unknown value is legal and must not be dropped by a consumer.

Known values: fact, preference, decision, context

occurredAt ref #occurrence Optional

When the remembered event happened, independent of createdAt. Omit when unknown.

provenance ref #provenance Optional

Where this memory came from. Advisory: consumers must tolerate its absence.

scope string Optional

Application label within a Space, never an access boundary. Use separate Spaces for different trust boundaries.

maxLength: 512 bytes

supersedes array of string at-uri Optional

Older memories replaced by this statement, several when it merges them into one. Keep history; consumers only mask replacements within the same authorized Space and repo.

maxLength: 20 items

updatedAt string datetime Optional

When the memory was last revised, if ever.

View raw schema

{
  "key": "tid",
  "type": "record",
  "record": {
    "type": "object",
    "required": [
      "content",
      "createdAt"
    ],
    "properties": {
      "kind": {
        "type": "string",
        "description": "Coarse classification. Open vocabulary: an unknown value is legal and must not be dropped by a consumer.",
        "knownValues": [
          "fact",
          "preference",
          "decision",
          "context"
        ]
      },
      "scope": {
        "type": "string",
        "maxLength": 512,
        "description": "Application label within a Space, never an access boundary. Use separate Spaces for different trust boundaries."
      },
      "content": {
        "type": "string",
        "maxLength": 10000,
        "description": "The memory itself: one self-contained statement that still makes sense months from now.",
        "maxGraphemes": 2500
      },
      "createdAt": {
        "type": "string",
        "format": "datetime",
        "description": "When the memory was first stated."
      },
      "updatedAt": {
        "type": "string",
        "format": "datetime",
        "description": "When the memory was last revised, if ever."
      },
      "occurredAt": {
        "ref": "#occurrence",
        "type": "ref",
        "description": "When the remembered event happened, independent of createdAt. Omit when unknown."
      },
      "provenance": {
        "ref": "#provenance",
        "type": "ref",
        "description": "Where this memory came from. Advisory: consumers must tolerate its absence."
      },
      "supersedes": {
        "type": "array",
        "items": {
          "type": "string",
          "format": "at-uri"
        },
        "maxLength": 20,
        "description": "Older memories replaced by this statement, several when it merges them into one. Keep history; consumers only mask replacements within the same authorized Space and repo."
      }
    }
  },
  "description": "A single durable memory belonging to the user. Deliberately one generic type: specialising into fact/preference/project/event types is premature until real requirements demand it. Retrieval-specific state (BM25 scores, vector ids, index cursors, caches) MUST NOT be stored here — it is derived data owned by whichever memory engine indexes this record. Consumers MUST preserve properties they do not recognise: an implementation that rewrites a record after dropping unknown fields destroys data written by a newer one."
}

occurrence object

No description available.

Properties

from string datetime Required

An RFC 3339 formatted timestamp.

precision string Optional

Precision of the source statement; year and month dates are anchors, not exact event dates.

to string datetime Optional

An RFC 3339 formatted timestamp.

View raw schema

{
  "type": "object",
  "required": [
    "from"
  ],
  "properties": {
    "to": {
      "type": "string",
      "format": "datetime"
    },
    "from": {
      "type": "string",
      "format": "datetime"
    },
    "precision": {
      "enum": [
        "year",
        "month",
        "day",
        "instant"
      ],
      "type": "string",
      "description": "Precision of the source statement; year and month dates are anchors, not exact event dates."
    }
  }
}

provenance object

No description available.

Properties

agent string Optional

The agent that wrote the memory, e.g. 'claude-code', 'codex'.

maxLength: 256 bytes

client string uri Optional

OAuth client id of the application that wrote it.

sourceUri string uri Optional

What the memory was derived from, if anything.

View raw schema

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "maxLength": 256,
      "description": "The agent that wrote the memory, e.g. 'claude-code', 'codex'."
    },
    "client": {
      "type": "string",
      "format": "uri",
      "description": "OAuth client id of the application that wrote it."
    },
    "sourceUri": {
      "type": "string",
      "format": "uri",
      "description": "What the memory was derived from, if anything."
    }
  }
}