Skip to main content

Replay

The Replay router provides time-travel debugging for your memory store. Browse the full timeline of operations, reconstruct state at any point in time, diff between timestamps, and track the complete lifecycle of individual memories.

Base URL: https://novyx-ram-api.fly.dev

Tier: Pro+ (Counterfactual Recall and Drift require Enterprise)

Backend: Requires Postgres

Timeline​

GET /v1/replay/timeline

Get a chronological feed of all memory operations — creates, updates, deletes, and rollbacks.

Query parameters​

ParameterTypeRequiredDefaultDescription
sincestringNo—Start of time range (ISO 8601)
untilstringNo—End of time range (ISO 8601)
operationsstringNo—Comma-separated filter: create, update, delete, rollback
agent_idstringNo—Filter by agent ID
limitnumberNo100Max results (1–1000)
offsetnumberNo0Pagination offset

Response fields​

FieldTypeDescription
entriesarrayArray of timeline entries
total_countnumberTotal matching entries
has_morebooleanWhether more pages exist
period_startstringStart of returned period (ISO 8601)
period_endstringEnd of returned period (ISO 8601)

Each timeline entry includes:

FieldTypeDescription
timestampstringISO 8601 timestamp
operationstringOperation type: create, update, delete, rollback
memory_idstringAffected memory ID
observation_previewstringTruncated observation text
agent_idstring | nullAgent that performed the operation
importancenumberMemory importance score
content_hashstringSHA-256 content hash
metadataobjectOperation metadata

Examples​

from novyx import Novyx

nx = Novyx(api_key="nram_your_key")

# Get recent timeline
timeline = nx.replay_timeline(limit=20)
for entry in timeline["entries"]:
    print(f"{entry['timestamp']} {entry['operation']} {entry['observation_preview']}")

# Filter by operation type and time range
creates = nx.replay_timeline(
    since="2026-03-01T00:00:00Z",
    until="2026-03-09T00:00:00Z",
    operations="create,update",
)

Response​

{
  "entries": [
    {
      "timestamp": "2026-03-09T14:30:00Z",
      "operation": "create",
      "memory_id": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "observation_preview": "User prefers dark mode and compact...",
      "agent_id": "agent-1",
      "importance": 8,
      "content_hash": "e3b0c44298fc1c149afbf4c8996fb924...",
      "metadata": {}
    }
  ],
  "total_count": 156,
  "has_more": true,
  "period_start": "2026-03-01T00:00:00Z",
  "period_end": "2026-03-09T14:30:00Z"
}

Errors​

StatusCodeCause
403FEATURE_NOT_AVAILABLERequires Pro+ plan
501REQUIRES_POSTGRESPostgres backend required

Snapshot​

GET /v1/replay/snapshot

Reconstruct the complete state of your memory store at any point in time — including all memories and graph edges that existed at that moment.

Query parameters​

ParameterTypeRequiredDefaultDescription
atstringYes—Point in time to reconstruct (ISO 8601)
limitnumberNo500Max memories (1–5000)
offsetnumberNo0Pagination offset

Response fields​

FieldTypeDescription
snapshot_atstringRequested timestamp (ISO 8601)
total_memoriesnumberTotal memories at that time
memoriesarrayArray of memory snapshots
edgesarrayArray of graph edges at that time
total_edgesnumberTotal edge count

Each memory snapshot includes:

FieldTypeDescription
uuidstringMemory identifier
observationstringMemory content
contextstring | nullContext metadata
agent_idstring | nullAgent identifier
tagsstring[]Tags
importancenumberImportance score
confidencenumberConfidence score
created_atstringCreation timestamp
space_idstring | nullSpace identifier

Examples​

# See what your memory store looked like yesterday
snapshot = nx.replay_snapshot(at="2026-03-08T12:00:00Z")
print(f"{snapshot['total_memories']} memories at that time")

for mem in snapshot["memories"]:
    print(f"  {mem['observation'][:60]}...")

Response​

{
  "snapshot_at": "2026-03-08T12:00:00Z",
  "total_memories": 87,
  "memories": [
    {
      "uuid": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "observation": "User prefers dark mode and compact layouts",
      "context": null,
      "agent_id": "agent-1",
      "tags": ["preferences", "ui"],
      "importance": 8,
      "confidence": 1.0,
      "created_at": "2026-03-07T10:00:00Z",
      "space_id": null
    }
  ],
  "edges": [
    {
      "edge_id": "urn:uuid:ed1a2b3c-0000-0000-0000-000000000001",
      "source_id": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_id": "urn:uuid:b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "relation": "similar",
      "weight": 0.92
    }
  ],
  "total_edges": 12
}

Errors​

StatusCodeCause
403FEATURE_NOT_AVAILABLERequires Pro+ plan
501REQUIRES_POSTGRESPostgres backend required

Diff​

GET /v1/replay/diff

Compare your memory store between two points in time. Shows what was added, removed, and modified.

Query parameters​

ParameterTypeRequiredDefaultDescription
fromstringYes—Start timestamp (ISO 8601)
tostringYes—End timestamp (ISO 8601)

Response fields​

FieldTypeDescription
from_timestampstringStart of diff range
to_timestampstringEnd of diff range
addedarrayMemories created in this period
removedarrayMemories deleted in this period
modifiedarrayMemories updated in this period
summaryobjectCounts: { added, removed, modified }

Each diff entry includes:

FieldTypeDescription
memory_idstringMemory identifier
change_typestringadded, removed, or modified
observation_previewstringTruncated observation text
importancenumberImportance score

Examples​

# What changed in the last 24 hours?
diff = nx.replay_diff(
    from_ts="2026-03-08T12:00:00Z",
    to="2026-03-09T12:00:00Z",
)
print(f"Added: {diff['summary']['added']}")
print(f"Removed: {diff['summary']['removed']}")
print(f"Modified: {diff['summary']['modified']}")

Response​

{
  "from_timestamp": "2026-03-08T12:00:00Z",
  "to_timestamp": "2026-03-09T12:00:00Z",
  "added": [
    {
      "memory_id": "urn:uuid:c3d4e5f6-a7b8-9012-cdef-123456789012",
      "change_type": "added",
      "observation_preview": "New deployment config uses blue-green...",
      "importance": 7
    }
  ],
  "removed": [],
  "modified": [
    {
      "memory_id": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "change_type": "modified",
      "observation_preview": "User prefers dark mode and compact...",
      "importance": 9
    }
  ],
  "summary": {
    "added": 1,
    "removed": 0,
    "modified": 1
  }
}

Errors​

StatusCodeCause
403FEATURE_NOT_AVAILABLERequires Pro+ plan
422INVALID_RANGEfrom must be before to
501REQUIRES_POSTGRESPostgres backend required

Memory Lifecycle​

GET /v1/replay/memory/{memory_id}

Track the complete lifecycle of a single memory — from creation through updates, recalls, links, and deletion.

Path parameters​

ParameterTypeDescription
memory_idstringMemory identifier

Response fields​

FieldTypeDescription
memory_idstringMemory identifier
observationstringOriginal memory content
created_atstringCreation timestamp
current_statestringCurrent observation (if modified)
eventsarrayChronological list of lifecycle events
versionsarrayVersion history
linksarrayGraph edges to/from this memory
recall_countnumberNumber of times recalled
last_recalled_atstring | nullLast recall timestamp

Each lifecycle event includes:

FieldTypeDescription
timestampstringEvent timestamp
event_typestringcreate, update, delete, recall, link
detailobjectEvent-specific details

Examples​

lifecycle = nx.replay_lifecycle("urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890")
print(f"Created: {lifecycle['created_at']}")
print(f"Recalled {lifecycle['recall_count']} times")

for event in lifecycle["events"]:
    print(f"  {event['timestamp']} — {event['event_type']}")

Response​

{
  "memory_id": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "observation": "User prefers dark mode and compact layouts",
  "created_at": "2026-03-07T10:00:00Z",
  "current_state": "User prefers dark mode, compact layouts, and monospace fonts",
  "events": [
    {
      "timestamp": "2026-03-07T10:00:00Z",
      "event_type": "create",
      "detail": { "importance": 8 }
    },
    {
      "timestamp": "2026-03-08T09:15:00Z",
      "event_type": "recall",
      "detail": { "query": "user preferences" }
    },
    {
      "timestamp": "2026-03-09T11:00:00Z",
      "event_type": "update",
      "detail": { "fields": ["observation", "importance"] }
    }
  ],
  "versions": [
    {
      "observation": "User prefers dark mode and compact layouts",
      "importance": 8,
      "timestamp": "2026-03-07T10:00:00Z"
    },
    {
      "observation": "User prefers dark mode, compact layouts, and monospace fonts",
      "importance": 9,
      "timestamp": "2026-03-09T11:00:00Z"
    }
  ],
  "links": [
    {
      "edge_id": "urn:uuid:ed1a2b3c-0000-0000-0000-000000000001",
      "source_id": "urn:uuid:a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "target_id": "urn:uuid:b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "relation": "similar",
      "weight": 0.92
    }
  ],
  "recall_count": 3,
  "last_recalled_at": "2026-03-09T14:00:00Z"
}

Errors​

StatusCodeCause
403FEATURE_NOT_AVAILABLERequires Pro+ plan
404NOT_FOUNDMemory does not exist
501REQUIRES_POSTGRESPostgres backend required