Entities

Entities group memory versions together. When a fact is updated, the new version shares the same entity_id. This lets you track how knowledge evolves over time.

How entity_id Works

When retain decides that new content updates an existing fact rather than creating a new one, the new memory gets the same entity_id. The old version gets a valid_to timestamp; the new version becomes current.

entity_id: "alice-location"

Version 1: "Alice lives in Berlin"
  valid_from: 2024-01-15  valid_to: 2024-06-01

Version 2: "Alice lives in London"
  valid_from: 2024-06-01  valid_to: null (current)

---

GET /api/v1/entities/:entity_id/history

Get all versions of an entity ordered by time.

curl https://api.memlayer.dev/api/v1/entities/alice-location/history

Response:

[
  {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "entity_id": "alice-location",
    "content": "Alice lives in Berlin",
    "layer": 2,
    "importance": 0.75,
    "system_time": "2024-01-15T10:30:00Z",
    "valid_from": "2024-01-15T10:30:00Z",
    "valid_to": "2024-06-01T14:00:00Z"
  },
  {
    "id": "e5f6a7b8-c9d0-1234-5678-abcdef012345",
    "entity_id": "alice-location",
    "content": "Alice lives in London",
    "layer": 2,
    "importance": 0.75,
    "system_time": "2024-06-01T14:00:00Z",
    "valid_from": "2024-06-01T14:00:00Z",
    "valid_to": null
  }
]

Results are ordered by valid_from. The last entry with valid_to: null is the current version.

Temporal Queries with Recall

Use as_of on the recall endpoint to query what was known at a specific time:

curl "https://api.memlayer.dev/api/v1/recall?query=where+does+Alice+live&as_of=2024-03-01T00:00:00Z"

Returns “Alice lives in Berlin” because that was current on March 1, 2024.