​

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:

​

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

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",
  "theme": "fitness",
  "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