Skip to main content

​
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 onGet this ID from:Example: 42
​
before
number
Number of observations to show before the focus observationDefault: 5Returns the N observations that occurred immediately before (chronologically) in the same session.
​
after
number
Number of observations to show after the focus observationDefault: 5Returns 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

If the observation ID doesn’t exist:
Timeline error: observation not found
Verify the ID from mem_search results.
Soft-deleted observations are excluded from timelines. If you request a timeline for a deleted observation:
Timeline error: observation not found
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 <<<
...

Build docs developers (and LLMs) love

Get started for freeTalk to us