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

# Terminal UI

> Interactive Bubbletea-based TUI for browsing Engram memories

Engram includes an interactive terminal UI (TUI) built with [Bubbletea](https://github.com/charmbracelet/bubbletea) v1, [Lipgloss](https://github.com/charmbracelet/lipgloss), and [Bubbles](https://github.com/charmbracelet/bubbles) components.

## Launch the TUI

```bash theme={null}
engram tui
```

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/gentleman-programming-engram/images/tui-dashboard.png" alt="TUI Dashboard" />
</Frame>

## Features

<CardGroup cols={2}>
  <Card title="Catppuccin Mocha" icon="palette">
    Beautiful color palette optimized for terminal use
  </Card>

  <Card title="Vim Navigation" icon="keyboard">
    j/k keys, Enter to drill in, Esc to go back
  </Card>

  <Card title="FTS5 Search" icon="magnifying-glass">
    Full-text search from the TUI with live results
  </Card>

  <Card title="Live Refresh" icon="arrows-rotate">
    Data refreshes on back-navigation to parent screens
  </Card>
</CardGroup>

## Screens

The TUI provides 8 different screens for browsing your memory system:

### Dashboard

Stats overview showing:

* Total sessions tracked
* Total observations stored
* Total prompts saved
* List of projects with memories
* Navigation menu to other screens

**Navigation**: Select a menu item with `↑/↓` or `j/k`, press `Enter` to navigate.

### Search

FTS5 full-text search with text input.

**Navigation**:

* Type your query
* Press `Enter` to search
* Press `Esc` to return to dashboard

**Quick Access**: Press `s` or `/` from any screen to jump to search.

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/gentleman-programming-engram/images/tui-search.png" alt="TUI Search Results" />
</Frame>

### Search Results

Browsable list of search results with:

* Observation title
* Content preview (truncated to fit)
* Type badge (decision, bugfix, etc.)
* Project name

**Navigation**:

* `j/k` or `↑/↓` to navigate list
* `Enter` to view full observation detail
* `t` to view timeline for selected observation
* `Esc` to return to search

### Recent Observations

Browse all observations, newest first.

**Features**:

* Shows observations from ALL sessions (including active, non-completed sessions)
* Active session observations are sorted to the top with an `(active)` badge
* 2-line items: title + content preview
* Scroll indicators show position in long lists (e.g. "showing 1-20 of 50")

**Navigation**:

* `j/k` or `↑/↓` to navigate list
* `Enter` to view full observation detail
* `t` to view timeline for selected observation
* `Esc` to return to dashboard

### Observation Detail

Full content of a single observation, scrollable.

**Displays**:

* ID and title
* Type badge
* Full content (no truncation)
* Project, scope, topic key (if set)
* Tool name (if set)
* Revision count and duplicate count
* Created/updated timestamps
* Session ID

**Navigation**:

* `j/k` or `↑/↓` to scroll long content
* `t` to view timeline for this observation
* `Esc` to return to previous screen (search results or recent observations)

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/gentleman-programming-engram/images/tui-detail.png" alt="TUI Observation Detail" />
</Frame>

### Timeline

Chronological context around a specific observation — shows what happened before and after within the same session.

**Displays**:

* Session info (project, start time, summary if available)
* Total observations in the session
* **Before** section: observations before the focus (chronological)
* **Focus observation** (highlighted with `>>>` markers)
* **After** section: observations after the focus (chronological)

**Navigation**:

* `j/k` or `↑/↓` to scroll
* `Esc` to return to previous screen (observation detail or search results)

### Sessions

Browse all sessions.

**Features**:

* Shows ALL sessions regardless of status (active and completed)
* Active sessions (not yet ended) are sorted to the top with an `(active)` badge
* Displays session ID, project, start time, summary (if available)
* Shows observation count per session

**Navigation**:

* `j/k` or `↑/↓` to navigate list
* `Enter` to view observations within the selected session
* `Esc` to return to dashboard

### Session Detail

Observations within a specific session, in chronological order.

**Displays**:

* Session header (ID, project, start/end times, summary)
* List of all observations in the session
* Each observation shows title + content preview

**Navigation**:

* `j/k` or `↑/↓` to navigate observations
* `Enter` to view full observation detail
* `Esc` to return to sessions list

## Navigation Reference

### Global Keys

| Key        | Action                       |
| ---------- | ---------------------------- |
| `s` or `/` | Quick search from any screen |
| `Ctrl+C`   | Force quit from anywhere     |

### List Navigation

| Key          | Action                                 |
| ------------ | -------------------------------------- |
| `j` or `↓`   | Move down in list                      |
| `k` or `↑`   | Move up in list                        |
| `Enter`      | Select item / drill into detail        |
| `t`          | View timeline for selected observation |
| `Esc` or `q` | Go back to previous screen             |

### Detail Screen Navigation

| Key        | Action                             |
| ---------- | ---------------------------------- |
| `j` or `↓` | Scroll down                        |
| `k` or `↑` | Scroll up                          |
| `t`        | View timeline for this observation |
| `Esc`      | Return to previous screen          |

## Visual Features

### Color Palette (Catppuccin Mocha)

The TUI uses the Catppuccin Mocha color scheme:

* **Rosewater** (`#f5e0dc`): Headers and titles
* **Lavender** (`#b4befe`): Highlights and accents
* **Blue** (`#89b4fa`): Links and interactive elements
* **Mauve** (`#cba6f7`): Secondary highlights
* **Text** (`#cdd6f4`): Primary text
* **Subtext** (`#a6adc8`): Metadata and secondary text
* **Surface** (`#313244`): Borders and dividers
* **Base** (`#1e1e2e`): Background

### Active Session Badge

Observations and sessions from active (non-completed) sessions show an `(active)` badge next to their title and are sorted to the top of every list.

**Why?** Active sessions represent ongoing work. Sorting them to the top makes it easy to see what's currently in progress vs. what's completed.

### Scroll Indicators

Long lists show position indicators:

```
showing 1-20 of 50
```

### 2-Line Items

Each observation in a list shows:

1. **Line 1**: Title with type badge and project
2. **Line 2**: Content preview (truncated to fit terminal width)

This provides enough context to identify relevant memories without overwhelming the screen.

## Architecture (Gentleman Bubbletea Patterns)

The TUI follows the Gentleman Bubbletea skill patterns:

<AccordionGroup>
  <Accordion title="model.go — Screen constants, Model struct, Init()">
    * Screen constants as `Screen int` iota
    * Single `Model` struct holds ALL state (no separate screen structs)
    * `Init()` loads initial data (dashboard stats)
    * Custom messages for async data loading (e.g. `statsLoadedMsg`, `searchResultsMsg`)
  </Accordion>

  <Accordion title="styles.go — Lipgloss styles by concern">
    * Layout styles (container, header, footer)
    * Dashboard styles (stat card, menu item)
    * List styles (item, selected item, scroll indicator)
    * Detail styles (content area, metadata)
    * Timeline styles (before/after sections, focus highlight)
    * Search styles (input, results)
  </Accordion>

  <Accordion title="update.go — Update() with type switch">
    * `Update()` switches on `msg` type
    * `handleKeyPress()` routes to per-screen key handlers
    * Each handler returns `(tea.Model, tea.Cmd)`
    * Handlers: `handleDashboardKeys()`, `handleSearchKeys()`, `handleSearchResultsKeys()`, etc.
  </Accordion>

  <Accordion title="view.go — View() routes to per-screen renderers">
    * `View()` switches on `m.Screen`
    * Per-screen renderers: `renderDashboard()`, `renderSearch()`, `renderSearchResults()`, etc.
    * Shared `renderObservationListItem()` for consistent list formatting across screens
  </Accordion>
</AccordionGroup>

## Store Methods (TUI-Specific)

The TUI uses dedicated store methods that don't filter by session status:

| Method                           | Description                                                        |
| -------------------------------- | ------------------------------------------------------------------ |
| `AllSessions()`                  | All sessions regardless of status, active sorted first             |
| `AllObservations()`              | All observations regardless of session status, active sorted first |
| `SessionObservations(sessionID)` | All observations for a specific session, chronological order       |

<Note>
  These are different from `RecentSessions()` and `RecentObservations()`, which only show **completed** sessions for MCP context injection.

  The TUI shows everything (active + completed) because you want to see ongoing work, not just finished sessions.
</Note>

## Related

<CardGroup cols={2}>
  <Card title="MCP Tools" icon="wrench" href="/features/mcp-tools">
    Explore all 14 MCP tools available to agents
  </Card>

  <Card title="CLI Reference" icon="rectangle-terminal" href="/cli/commands">
    Command-line interface for Engram
  </Card>

  <Card title="Git Sync" icon="git-alt" href="/features/git-sync">
    Share memories using git-based sync
  </Card>

  <Card title="Architecture" icon="sitemap" href="/concepts/architecture">
    Technical architecture of Engram
  </Card>
</CardGroup>