Skip to main content
Engram includes an interactive terminal UI (TUI) built with Bubbletea v1, Lipgloss, and Bubbles components.

​
Launch the TUI

engram tui
TUI Dashboard

​
Features

Catppuccin Mocha

Beautiful color palette optimized for terminal use

Vim Navigation

j/k keys, Enter to drill in, Esc to go back

FTS5 Search

Full-text search from the TUI with live results

Live Refresh

Data refreshes on back-navigation to parent screens

​
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. 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.
TUI Search Results

​
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)
TUI Observation Detail

​
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

​
Global Keys

KeyAction
s or /Quick search from any screen
Ctrl+CForce quit from anywhere

​
List Navigation

KeyAction
j or ↓Move down in list
k or ↑Move up in list
EnterSelect item / drill into detail
tView timeline for selected observation
Esc or qGo back to previous screen

​
Detail Screen Navigation

KeyAction
j or ↓Scroll down
k or ↑Scroll up
tView timeline for this observation
EscReturn 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:
  • 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)
  • 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)
  • Update() switches on msg type
  • handleKeyPress() routes to per-screen key handlers
  • Each handler returns (tea.Model, tea.Cmd)
  • Handlers: handleDashboardKeys(), handleSearchKeys(), handleSearchResultsKeys(), etc.
  • View() switches on m.Screen
  • Per-screen renderers: renderDashboard(), renderSearch(), renderSearchResults(), etc.
  • Shared renderObservationListItem() for consistent list formatting across screens

​
Store Methods (TUI-Specific)

The TUI uses dedicated store methods that don’t filter by session status:
MethodDescription
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
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.

MCP Tools

Explore all 14 MCP tools available to agents

CLI Reference

Command-line interface for Engram

Git Sync

Share memories using git-based sync

Architecture

Technical architecture of Engram

Build docs developers (and LLMs) love

Get started for freeTalk to us