mem_timeline

Show chronological context around a specific observation

Overview

View chronological context around a specific observation. Shows what happened before and after a memory entry within the same session, providing temporal context for better understanding.

This tool is part of the admin profile and uses deferred loading. It’s most useful after mem_search to drill into the timeline of events surrounding a search result.

Progressive Disclosure Pattern

This tool implements the 3-layer progressive disclosure pattern:

1. mem_search

   Search for relevant observations (returns compact results with IDs)

2. mem_timeline

   Get chronological context around a result (what happened before/after)

3. mem_get_observation

   Get full untruncated content (if needed)

Parameters

observation_id · number · required

The observation ID to center the timeline on

Get this ID from:

• mem_search results
• mem_context results
• TUI observation view

Example: 42

before · number

Number of observations to show before the focus observation

Default: 5

Returns the N observations that occurred immediately before (chronologically) in the same session.

after · number

Number of observations to show after the focus observation

Default: 5

Returns the N observations that occurred immediately after (chronologically) in the same session.

Response

timeline · object

Timeline result with session info, focus observation, and surrounding entries

The response includes:

1. Session header — session ID, project, start time, summary (if available)
2. Total observations in session
3. Before entries — observations that occurred before the focus
4. Focus observation — the anchor observation (highlighted)
5. After entries — observations that occurred after the focus

Example response:

Session: engram (2026-03-01T14:00:00Z) — Fixed FTS5 search bugs and added deduplication
Total observations in session: 15

─── Before ───
  #39 [tool_use] Read internal/store/store.go — sanitizeFTS function
  #40 [search] Searched for "FTS5 query syntax documentation"
  #41 [decision] Add quote wrapping to all FTS5 search terms

>>> #42 [bugfix] Fixed FTS5 syntax error on special chars <<<
    **What**: Wrapped each search term in quotes before passing to FTS5 MATCH
    **Why**: Users typing queries like 'fix auth bug' would crash because FTS5 interprets special chars as operators
    **Where**: internal/store/store.go — sanitizeFTS() function
    **Learned**: FTS5 MATCH syntax is NOT the same as LIKE — always sanitize user input
    2026-03-01T14:23:45Z

─── After ───
  #43 [file_change] Modified internal/store/store.go — added sanitizeFTS() function
  #44 [command] go test ./internal/store -v
  #45 [manual] Verified search now handles special chars: !@#$%^&*()
  #46 [discovery] FTS5 also supports boolean operators AND/OR/NOT
  #47 [session_summary] Session summary: engram

Usage Examples

Default Timeline (5 before, 5 after)

{
  "observation_id": 42
}

Shows 5 observations before #42 and 5 observations after #42.

Narrow Timeline (2 before, 2 after)

{
  "observation_id": 42,
  "before": 2,
  "after": 2
}

Shows only the immediate context (2 entries on each side).

Wide Timeline (10 before, 10 after)

{
  "observation_id": 42,
  "before": 10,
  "after": 10
}

Shows broader context with 10 entries on each side.

Asymmetric Timeline

{
  "observation_id": 42,
  "before": 3,
  "after": 7
}

Shows 3 before and 7 after — useful when you care more about what happened next.

When to Use

• After search — drill into the context of a search result
• Debugging — understand the sequence of events that led to a bug
• Session exploration — see what else happened during that session
• Causal analysis — understand what led to a decision or discovery

Timeline Boundaries

Timelines are session-scoped — only observations from the same session appear:

• If the focus observation is at the start of a session, there may be fewer “before” entries (or none)
• If the focus observation is at the end of a session, there may be fewer “after” entries (or none)
• Observations from other sessions never appear in the timeline

The Total observations in session count tells you how many total observations exist in that session.

Session Header

The session header provides context:

Session: my-api (2026-03-01T14:00:00Z) — Added JWT authentication and refactored user service
Total observations in session: 12

• Project name — my-api
• Session start time — 2026-03-01T14:00:00Z
• Session summary — “Added JWT authentication and refactored user service” (if available)
• Total observations — 12 entries in this session

Chronological Ordering

Observations are ordered by created_at timestamp:

1. Before entries — oldest to newest (leading up to the focus)
2. Focus observation — the anchor
3. After entries — oldest to newest (following the focus)

Content Truncation

Timeline entries show truncated content to save tokens:

• Before/After entries: Up to 150 characters
• Focus observation: Up to 500 characters

For full content, use mem_get_observation.

Token Efficiency

Typical timeline token counts:

• Default (5 before, 5 after): ~800-1500 tokens
• Narrow (2 before, 2 after): ~400-700 tokens
• Wide (10 before, 10 after): ~1500-3000 tokens

Adjust before and after parameters based on your context window. Start with the default and narrow if needed.

Example Workflow

1. Search for a memory

   {
     "query": "FTS5 sanitization"
   }
   

   Returns observation #42 in the results.

2. View timeline context

   {
     "observation_id": 42,
     "before": 5,
     "after": 5
   }
   

   See what happened before and after the FTS5 fix.

3. Get full content (if needed)

   {
     "id": 42
   }
   

   Retrieve the full untruncated observation.

Error Handling

Observation not found

If the observation ID doesn’t exist:

Timeline error: observation not found

Verify the ID from mem_search results.

Deleted observations

Soft-deleted observations are excluded from timelines. If you request a timeline for a deleted observation:

Timeline error: observation not found

First/last observation

If the focus observation is at the session start or end, you’ll see fewer “before” or “after” entries:

─── Before ───
(none — this is the first observation in the session)

>>> #1 [session_summary] Session started <<<
...

Related Tools

• mem_search - Search for observations to timeline
• mem_get_observation - Get full content of an observation
• mem_context - Get recent chronological context (not session-scoped)