A single-page dashboard for monitoring and exploring observations stored by the Engram memory service. Search, browse, and manage AI agent sessions, observations, prompts, and stats from a local Engram HTTP server.
Table of Contents
- Node.js
>=20(usenvm useif you have an.nvmrc) - pnpm
>=9—npm install -g pnpm - Engram
>= v1.12.0and running locally onhttp://127.0.0.1:7437- The dev script will attempt to start Engram automatically if it is not already running
- Install Engram:
go install github.com/Gentleman-Programming/engram/v2/cmd/engram@latest(or see its installation guide)
1. Clone the repository
git clone https://github.com/egdev6/engram-monitor.git
cd engram-monitor2. Use the correct Node version
nvm use3. Install dependencies
pnpm install4. Start the dev server
pnpm devThis command runs two processes concurrently:
- Waits for Engram on
http://127.0.0.1:7437/health(startsengram serveif not reachable) - Starts Vite once Engram is healthy
The app will be available at http://localhost:5173.
Tip: If Engram is already running separately,
pnpm devwill skip starting it and go straight to Vite.
| Command | Description |
|---|---|
pnpm dev |
Start Engram (if needed) + Vite dev server concurrently |
pnpm build |
Type-check with tsc then build with Vite |
pnpm preview |
Preview the production build locally |
pnpm reinstall |
Clean all deps/dist and reinstall from scratch |
pnpm biome-all |
Run Biome linter + formatter across the entire project |
pnpm pre-commit |
Run staged Biome check + tsc + git add -A (runs via Lefthook) |
The project follows Atomic Design with a container/presentational split for pages.
src/
├── app/ # Entry point, router, providers
├── components/
│ ├── atoms/ # BackButton, Button, DateInput, EmptyState, FilterSelect,
│ │ # IconButton, SearchInput, StatCard, Text, TypeBadge
│ ├── molecules/ # ClearFiltersBar, MarkdownPanel, ObservationRow, TabBar
│ ├── organisms/ # EmptySessionsTab, Footer, Header, MemoriesTab,
│ │ # MergeProjectsModal, PromptsTab, SessionCard,
│ │ # SessionDetailCard, SessionsTab, SettingsModal,
│ │ # TimelineTab, TopicsTab
│ └── templates/ # Layout
├── config/ # Axios instances, React Query client
├── hooks/ # use-engram, use-settings, use-theme, use-loading
├── models/ # TypeScript interfaces for Engram domain types
├── pages/
│ ├── engram-dashboard/ # Main dashboard (Sessions, Memories, Prompts, Topics,
│ │ # Timeline, Empty Sessions tabs)
│ └── session-detail/ # Session drill-down with observation list
├── services/ # All Engram API calls (engramService)
├── styles/ # Global CSS: base, theme tokens, fonts, utilities
└── utils/
├── constants/ # TYPE_COLORS, PROJECT_COLORS, INPUT_CLS, KNOWN_TYPES
└── helpers/ # timeAgo(), projectColor(), cn()
Key concepts:
- API proxy — Vite proxies
/engram-api→http://127.0.0.1:7437in dev. All calls use theengramApiAxios instance. - Session derivation — Active sessions (with observations) are derived client-side by grouping observations by
session_id. Empty sessions are fetched directly from theGET /sessionsendpoint. - Data fetching — Services wrap raw API calls. Hooks compose services with TanStack Query and expose clean interfaces to components.
- Global state — Zustand for UI state (theme, settings modal, loading overlay). TanStack Query for all server state.
- Atomic components — Reusable atoms (Button, DateInput) follow consistent patterns with typed props, variants, and sizes.
Path aliases (defined in vite.config.ts):
| Alias | Path |
|---|---|
@ |
src/ |
@atoms |
src/components/atoms/ |
@molecules |
src/components/molecules/ |
@organisms |
src/components/organisms/ |
@templates |
src/components/templates/ |
@hooks |
src/hooks/ |
@services |
src/services/ |
@models |
src/models/ |
@pages |
src/pages/ |
@config |
src/config/ |
@constants |
src/utils/constants/ |
@helpers |
src/utils/helpers/ |
@styles |
src/styles/ |
- Sessions tab — grid view of all agent sessions with agent name, project, type badges, latest title, topic key, and date. Filterable by project, type, and date range.
- Memories tab — grid view of individual observations. Filterable by project, type, scope, and limit with active filter badges. Click any row to open a Markdown detail panel with inline editing.
- Topics tab — grouped view of observations organized by
topic_key. Expandable groups show observation timeline with revision counts. Filterable by project and search. - Timeline tab — chronological view of all observations grouped by day (Today, Yesterday, or formatted date). Filterable by project, type, and search with visual timeline dots colored by observation type.
- Prompts tab — list of saved user prompts with inline search and per-row delete.
- Empty sessions tab — dedicated list of sessions with no observations, with inline search and per-row delete to clean up stale entries.
- Session detail — drill into a session to see all its observations in order, with inline search and type filtering.
- Settings modal — centralized configuration panel accessible from header with Export JSON, Import JSON, and Merge Projects actions.
- Responsive tabs — horizontal scrollable tab bar on mobile with scroll-snap and hidden scrollbar.
- Live health indicator — header shows online/offline status with auto-polling every 2 seconds.
- Stats bar — projects, sessions, observations, prompts, and empty session counts at a glance.
- Markdown panel — full observation detail viewer with inline editing support for title, content, type, scope, and topic_key fields.
- Merge projects — dedicated modal to merge observations from one project into another with confirmation flow.
- Delete support — delete individual prompts or empty sessions directly from the dashboard.
- Export/Import — export all data as JSON or import from a JSON file to restore/migrate observations.
- Unified typography — Geist (sans-serif) used consistently throughout the entire app.
- Light & dark themes — full theme toggle support with persistent storage and automatic system preference detection.
- Atomic design — reusable components (Button, DateInput, FilterSelect) with consistent API and variants.
- Accessible — proper ARIA labels, keyboard navigation (Esc to close modals/panels), and semantic HTML.
Distributed under the MIT License.
