Timeline & Memory

Overview

Every persona in person.run maintains a timeline — an ordered sequence of memories that shape how it responds. Memories are more than text storage; each one carries emotional context, a type classification, and a strength score that determines how vividly the persona recalls it.

This system creates psychologically realistic recall behavior: proud memories surface enthusiastically, repressed ones resist recall, and faded memories become hazy over time.

Timeline entry structure

Each timeline entry is a structured memory with these fields:

Memory types

The memory type controls how the persona relates to and recalls a memory during conversations:

Memory strength

Memory strength (0–100) determines how readily a memory surfaces during prompting. The prompt system groups memories into three tiers:

Appending memories

Add a new memory to a persona's timeline. Each new entry gets the next sequence number automatically. The eventAt timestamp must be equal to or later than the previous entry's timestamp.

curl -X POST https://api.person.run/personas/$PERSONA_ID/timeline \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$PERSON_TENANT_ID'",
    "eventAt": "2025-09-01T09:00:00.000Z",
    "eventLabel": "First day at new startup",
    "facts": "Started as lead product designer at a health-tech startup. Team of 12.",
    "feelings": "Nervous but excited. Impostor syndrome mixed with genuine confidence.",
    "emotionTags": ["excitement", "anxiety", "determination"],
    "memoryType": "normal",
    "memoryStrength": 72,
    "interpretation": "A fresh start. The team seems talented and the mission resonates."
  }'

Revising memories

People reinterpret their past. Personas can too. Use the revisesTimelineId field to create a revised version of an existing memory. The original is automatically marked as superseded, and the revision takes its place.

curl -X POST https://api.person.run/personas/$PERSONA_ID/timeline \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$PERSON_TENANT_ID'",
    "eventAt": "2025-09-01T09:00:00.000Z",
    "eventLabel": "First day at new startup (revised)",
    "facts": "Started at a health-tech startup. Discovered the codebase was in worse shape than expected.",
    "feelings": "Initial excitement gave way to concern about technical debt.",
    "emotionTags": ["concern", "determination"],
    "memoryType": "revised",
    "memoryStrength": 68,
    "interpretation": "The reality was harder than expected, but that made the work more meaningful.",
    "revisesTimelineId": "original-timeline-entry-id",
    "revisionReason": "Updated after reflecting on the full experience."
  }'

Superseding entries

You can also manually mark a timeline entry as superseded without providing a replacement. This is useful for removing factual errors or outdated information.

curl -X POST https://api.person.run/personas/$PERSONA_ID/timeline/$TIMELINE_ID/supersede \
  -H "x-api-key: $PERSON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "'$PERSON_TENANT_ID'",
    "reason": "Contained incorrect date; corrected in a newer entry."
  }'

Superseded entries are excluded from timeline responses by default. Pass includeSuperseded=true to the list endpoint to include them.

Retrieving the timeline

List timeline entries with pagination. Results are ordered by sequence number.

curl "https://api.person.run/personas/$PERSONA_ID/timeline?tenantId=$PERSON_TENANT_ID&limit=20&offset=0" \
  -H "x-api-key: $PERSON_API_KEY"

Consistency checking

As timelines grow, contradictions can creep in. The consistency check endpoint analyzes a persona's entire timeline for three categories of issues:

• Sequence gaps — missing sequence numbers in the timeline.
• Non-monotonic timestamps — events that appear out of chronological order.
• Contradictions — semantically conflicting facts detected via AI analysis.

curl "https://api.person.run/personas/$PERSONA_ID/consistency?tenantId=$PERSON_TENANT_ID" \
  -H "x-api-key: $PERSON_API_KEY"

{
  "report": {
    "personaId": "persona-uuid",
    "checkedAt": "2026-02-20T12:10:00.000Z",
    "issueCount": 2,
    "issues": [
      {
        "code": "possible_contradiction",
        "message": "Potential contradiction: joined the company <-> started in January",
        "timelineId": "timeline-id-18",
        "relatedTimelineId": "timeline-id-12"
      },
      {
        "code": "non_monotonic_event_time",
        "message": "Event time moved backward from sequence 14 to 15",
        "timelineId": "timeline-id-15",
        "relatedTimelineId": "timeline-id-14"
      }
    ]
  }
}

How memory shapes prompting

When you send a prompt, person.run uses vector similarity search (RAG) to find the most relevant memories. These are then structured in the prompt context by strength tier and memory type, creating nuanced recall behavior:

• Vivid memories are quoted with rich detail and emotional color.
• Moderate memories are summarized with softer detail.
• Faded memories are referenced vaguely, with caveats about uncertain recall.
• Pride memories are surfaced enthusiastically.
• Shame and repressed memories trigger reluctance or avoidance.
• Exaggerated memories are amplified in the telling.

This system means a persona with 200 memories doesn't dump all of them into every response — only the most relevant ones surface, shaped by their type and strength, creating natural and psychologically coherent conversations.