Skip to main content

​
Overview

Chronologue integrates the Model Context Protocol (MCP) to enable structured memory access, event scheduling, and tool invocation via standardized agent interfaces. This implementation supports:
  • Serving memory traces over a FastAPI or stdio MCP server
  • Scheduling calendar events through Google Calendar API
  • Converting .json memory traces to .ics format
  • Running OpenAI or Claude-based ReAct loops to populate and update the calendar

​
MCP Server Setup

The server exposes tools and resources via either stdio_server or FastMCP (FastAPI-based):
  • Tool: sync_to_google_calendar
    Sync .json memory traces to a Google Calendar
  • Tool: generate_embedding
    Generate OpenAI embeddings for trace content
  • Tool: convert_trace_to_ics
    Convert memory trace to .ics string for calendar export
Scripts:
  • server.py (stdio server)
  • server_google_calendar.py (FastAPI)
Run with: 
python mcp/server.py
or 
python mcp/server_google_calendar.py

​
MCP Client: Chat + Tool Invocation

The client connects to the MCP server, lists available tools, and forwards user queries through a Claude (or OpenAI) chat loop. Key features:
  • Uses Claude 3.5 Sonnet API with tools attached
  • Handles tool calls like sync_to_google_calendar, embedding generation
  • Supports a full interactive REPL
Script:
  • client.py
Run with: 
python mcp/client.py

​
Calendar Tooling and Integration

Chronologue exposes structured tools to bridge memory traces and calendar APIs:

​
Key Tools

  • convert_trace_to_ics(trace: dict) -> str
    Converts a single memory trace into a VEVENT-compliant .ics string
  • sync_traces_to_google(traces: list[dict]) -> str
    Sends memory traces to Google Calendar using OAuth-authenticated API
  • load_memory_file(file_path: str) -> list[dict]
    Loads structured memory from a .json file
Defined in:
  • server_google_calendar.py
Google Calendar setup requires:
  • calendar/credentials.json
  • calendar/token.json
Scopes used:
['https://www.googleapis.com/auth/calendar']

​
MCP Resources

Memory traces can be exposed as structured resources via MCP:
  • calendar://pending_goals
    All goal-type memory traces with completion_status: pending
  • calendar://week_summary/{iso_week}
    All traces from the specified ISO week (2025-W18)
  • calendar://trace_by_id/{trace_id}
    Lookup a specific memory trace by ID
These allow downstream agents or apps to reflect, plan, or retrieve specific event blocks.

​
Agent Loop (Planner + Executor)

Chronologue supports integration with OpenAI or Claude models to generate schedules:
  1. Query the MCP server for memory or context blocks
  2. Pass them into a prompt:
    “Given the user’s upcoming goals and availability, what events should be scheduled this week?”
  3. Receive a response in the form of MCPContextBlock(type="calendar_event")
  4. Sync to calendar using tools
This loop is defined in the process_query() and chat_loop() methods of the MCPClient.

​
Optional: Custom UI for Calendar + Agent Logs

For deeper integration or review:
  • Top panel: MCP-derived upcoming events
  • Side panel: agent chat logs and memory trace history
  • Bottom panel: annotate traces, schedule goals, or trigger planner
Tools:
  • Streamlit or Flet for simple UI prototyping
  • Tempo Tokens, feedback inputs, and calendar visualizations

​
Example Usage

Run the FastAPI-based MCP server and query events for the week: python server_google_calendar.py
curl http://localhost:8000/context?type=calendar_event&last_n=5 Trigger syncing memory to calendar: 
python mcp/client.py 
python mcp/server.py

​
Then: Type “Sync last session to calendar”

​
Summary

Chronologue’s MCP backend provides a powerful interface for:
  • Agent reflection, planning, and memory access
  • Tool invocation via structured protocols
  • Real-world event scheduling grounded in memory
  • Integrating .ics, .json, and calendar APIs in a unified loop
Use MCP as the bridge between memory traces, LLM agents, and the real-world temporal context.

​
System Design: Chronologue + MCP

Chronologue integrates structured memory traces, natural language input, and calendar-based coordination through a unified interface. It relies on the Model Context Protocol (MCP) to connect user input with event memory, agent reasoning, and calendar output. Event Schema All memory traces are converted into structured events, enabling both human review and agent planning. The core event types include:
  • goal – a future-oriented intent (“Finish literature review”)
  • observation – a passive or descriptive record (“Met with advisor”)
  • reflection – a qualitative note or summary (“Need to prioritize data cleanup”)
  • scheduled_event – a time-bound commitment (“Lab sync at 2PM Thursday”)
Example (backend JSON trace format): 
{
  "type": "goal",
  "title": "Submit IRB application",
  "timestamp": "2025-04-24T09:00:00",
  "duration": 60,
  "linked_memory": ["trace_041", "trace_038"],
  "notes": "Dependent on finishing protocol write-up"
}
MCP Integration MCP provides the scaffolding to structure agent interaction across time. Key mechanisms:
  • Memory Trace Ingestion Conversational input is parsed into structured trace entries (goal, reflection, etc.)
  • Timeline Generation MCP organizes these traces into a coherent timeline—annotated with metadata and available for .ics export.
  • Conversational Routing
    Chat commands like "schedule a writing block tomorrow" are interpreted into:
    • Actionable event traces
    • .ics entries
    • Planning context for future agent tasks
    Calendar API Bridge
Calendar interoperability is a core feature. MCP can generate and ingest:
  • .ics files – Standards-compliant events compatible with Apple Calendar, Google Calendar, Outlook
  • Google Calendar API – OAuth-authenticated event sync for read/write access
  • Structured Event I/O – Sync back updated events into memory system for trace consistency 
User Input → MCP → Trace Schema (Goal/Reflection/Event)
           → Timeline Assembly → .ics Export
           → Calendar Render → Agent Action
                            ↘ Memory Update ↖
User Interface and Editable Markdown Table This is how the Chronologue interface is rendered in a chat-based or UI-driven interaction—clear, editable, and structured for both human interaction and .ics export: 
| Time           | Task                      | Notes                          |
|----------------|---------------------------|--------------------------------|
| 07:30–08:00    | Morning routine           | Stretching, quick shower       |
| 08:00–09:00    | Breakfast + Reading       | Light news or book time        |
| 09:00–12:00    | Focus work block          | Deep work, no distractions     |
| 12:00–13:00    | Lunch                     | Away from desk                 |
| 13:00–15:00    | Meetings                  | Check calendar for links       |
| 15:00–15:30    | Break                     | Walk or coffee                 |
| 15:30–17:00    | Admin & Emails            | Inbox zero, light tasks        |
| 17:00–18:00    | Workout                   | Gym or at-home routine         |
| 18:00–19:00    | Dinner                    | Relaxed, no screens            |
| 19:00–21:00    | Personal time / Projects  | Hobbies, learning, side work   |
| 21:00–22:00    | Wind-down routine         | Read, reflect, sleep prep      |
This format can be edited via chat, programmatically parsed into .ics events, and be pushed back into the MCP memory system as scheduled traces.
⌘I