Skip to main content

​
Memory Trace Schema

Chronologue uses memory traces to represent structured information over time. These include user goals, reflections, system observations, and scheduled calendar events. Each trace is JSON-formatted and stored in a persistent memory store to support personalized planning, reflection, and agent reasoning.

​
Memory Trace Types

Traces are typed objects with a shared core schema. The primary type values include:

​
goal

Represents a user-defined intention or objective.
  • Example: “Finish CUDA tutorial this week”

​
reflection

A personal insight or retrospective evaluation.
  • Example: “Morning exercise made my focus better today”

​
observation

A system- or user-logged factual statement about activity or state.
  • Example: “Worked on writing sprint from 9:00 to 10:30”

​
calendar_event

A scheduled or logged event that maps to an external calendar entry.
  • Example: “Meeting with research team at 3pm”

​
Required and Optional Fields

Each trace includes the following fields:
FieldTypeRequiredDescription
uidstringyesUnique identifier for the trace
typestringyesOne of: goal, reflection, observation, calendar_event
timestampstringyesISO 8601 timestamp marking creation
contentstringyesMain text of the trace
task_idstringnoOptional grouping ID for multi-step tasks
themestringnoOptional activity domain (e.g., fitness, learning, work)
action_typestringnoSpecifies agent/system action: schedule, reflect, log, update, delete
importancenumbernoRelative significance (0–1 float)
completion_statusstringnoOne of: pending, completed, skipped
linked_event_uidstringnoUID of associated calendar event (if applicable)
collaboratorsarraynoList of user IDs or names involved
feedback_ratingnumbernoUser feedback score (1–5)
notesstringnoFreeform comments or review notes

​
Trace Lifecycle

​
Creation

Traces are created:
  • Automatically by LLMs after actions (e.g., scheduling a new event)
  • Manually via user reflection or logging
Traces should always include a valid UID and timestamp at creation.

​
Update

Fields like completion_status, importance, or notes can be updated over time as the task evolves or is reviewed.

​
Archival

Traces may be archived (or soft-deleted) for filtering long-term memory. You may optionally add an archived_at timestamp.

​
Linking Traces

​
Event UID Linking

Traces of type goal or reflection can reference a calendar_event using the linked_event_uid. This enables synchronization between memory and scheduling contexts.

​
Feedback Annotations

Users can provide feedback after a task:
  • Was this time block helpful?
  • Was this goal realistic?
This can be stored using feedback_rating or added to the notes field.

​
Agent Action Metadata

To support filtering for model actions over time, use the optional action_type field. This helps distinguish between user-entered and model-generated traces and provides clarity in audits, learning loops, and structured logs.

​
Common values for action_type

ValueDescription
scheduleAgent added a new event to the calendar
rescheduleAgent moved an existing event
reflectAgent generated a new reflection
logSystem recorded a factual observation
updateAgent edited an existing trace
deleteAgent or user removed a trace or event
This enables querying: “What did the agent do today?” or “Which reflections were AI-generated?”

​
Example Trace Payloads

​
Reflection

{
  "uid": "trace-001",
  "type": "reflection",
  "timestamp": "2025-05-08T22:30:00Z",
  "content": "Evening planning helped me sleep easier.",
  "importance": 0.8,
  "action_type": "reflect"
}

​
Calendar Event

{
  "uid": "evt-045",
  "type": "calendar_event",
  "timestamp": "2025-05-09T07:00:00Z",
  "content": "Upper body workout at Mission Cliffs",
  "linked_event_uid": "gcal-789abc",
  "completion_status": "completed",
itness",
  "action_type": "schedule"
}

​
Best Practices

  • Use consistent formatting for timestamps (always UTC)
  • Ensure uid is globally unique (e.g., UUIDv4 or prefixed)
  • Link related traces by linked_event_uid or shared task_id
  • Use importance and completion_status to guide agent decisions
  • Use action_type to capture structured logs of agent reasoning and behavior
  • Avoid overloading content – structure your data where possible