> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/Gentleman-Programming/engram/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Note>
  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.
</Note>

## Progressive Disclosure Pattern

This tool implements the **3-layer progressive disclosure** pattern:

<Steps>
  <Step title="mem_search">
    Search for relevant observations (returns compact results with IDs)
  </Step>

  <Step title="mem_timeline">
    Get chronological context around a result (what happened before/after)
  </Step>

  <Step title="mem_get_observation">
    Get full untruncated content (if needed)
  </Step>
</Steps>

## Parameters

<ParamField path="observation_id" type="number" required>
  The observation ID to center the timeline on

  Get this ID from:

  * [`mem_search`](/mcp/mem-search) results
  * [`mem_context`](/mcp/mem-context) results
  * TUI observation view

  **Example:** `42`
</ParamField>

<ParamField path="before" type="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.
</ParamField>

<ParamField path="after" type="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.
</ParamField>

## Response

<ResponseField name="timeline" type="object">
  Timeline result with session info, focus observation, and surrounding entries
</ResponseField>

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)

```json theme={null}
{
  "observation_id": 42
}
```

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

### Narrow Timeline (2 before, 2 after)

```json theme={null}
{
  "observation_id": 42,
  "before": 2,
  "after": 2
}
```

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

### Wide Timeline (10 before, 10 after)

```json theme={null}
{
  "observation_id": 42,
  "before": 10,
  "after": 10
}
```

Shows broader context with 10 entries on each side.

### Asymmetric Timeline

```json theme={null}
{
  "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

<Tip>
  The `Total observations in session` count tells you how many total observations exist in that session.
</Tip>

## 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`](/mcp/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

<Warning>
  Adjust `before` and `after` parameters based on your context window. Start with the default and narrow if needed.
</Warning>

## Example Workflow

<Steps>
  <Step title="Search for a memory">
    ```json theme={null}
    {
      "query": "FTS5 sanitization"
    }
    ```

    Returns observation #42 in the results.
  </Step>

  <Step title="View timeline context">
    ```json theme={null}
    {
      "observation_id": 42,
      "before": 5,
      "after": 5
    }
    ```

    See what happened before and after the FTS5 fix.
  </Step>

  <Step title="Get full content (if needed)">
    ```json theme={null}
    {
      "id": 42
    }
    ```

    Retrieve the full untruncated observation.
  </Step>
</Steps>

## Error Handling

<AccordionGroup>
  <Accordion title="Observation not found">
    If the observation ID doesn't exist:

    ```
    Timeline error: observation not found
    ```

    Verify the ID from `mem_search` results.
  </Accordion>

  <Accordion title="Deleted observations">
    Soft-deleted observations are excluded from timelines. If you request a timeline for a deleted observation:

    ```
    Timeline error: observation not found
    ```
  </Accordion>

  <Accordion title="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 <<<
    ...
    ```
  </Accordion>
</AccordionGroup>

## Related Tools

* [`mem_search`](/mcp/mem-search) - Search for observations to timeline
* [`mem_get_observation`](/mcp/mem-get-observation) - Get full content of an observation
* [`mem_context`](/mcp/mem-context) - Get recent chronological context (not session-scoped)