# How PrimeAgent Manages Conversation History: Session-Scoped Prompt Storage in the TUI Editor

> PrimeAgent stores conversation history in memory using session-scoped prompt storage within the TUI editor. Learn how it manages up to 100 entries for seamless navigation.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: internals
- Published: 2026-08-14

---

**PrimeAgent maintains conversation history as an in-memory array of trimmed prompt strings inside the TUI editor component, capping at 100 entries and supporting Up/Down arrow navigation that exits automatically on new input.**

PrimeAgent's terminal user interface (TUI) implements conversation history management directly within its core editor component rather than relying on external storage or the underlying terminal's scrollback buffer. This design keeps prompt history session-scoped, fast, and fully controllable. Below is a detailed breakdown of the implementation based on the PrimeIntellect-ai/prime-agent source code.

## Where History Lives: The Editor Component

History management is concentrated in [`packages/tui/src/components/editor.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/components/editor.ts), which serves as the primary text input widget for the TUI. This component maintains two key instance properties:

- `history: string[]` — the array of stored prompts (most recent first)
- `historyIndex: number` — the current navigation position (-1 when not browsing)

These properties are private to the editor and reset per session, ensuring no cross-session prompt leakage.

## Adding Prompts to History

When a user successfully submits a message, the editor stores it via `addToHistory(trimmed: string)`:

```typescript
// packages/tui/src/components/editor.ts#L434-L438
addToHistory(trimmed: string): void {
  this.history.unshift(trimmed);           // newest entry at index 0
  if (this.history.length > 100) {
    this.history.pop();                    // discard oldest beyond cap
  }
}

```

The **unshift** operation places the most recent prompt at the front, while a hard **100-entry limit** prevents unbounded memory growth. Entries are stored **trimmed** — leading and trailing whitespace removed — to keep history clean and consistent.

## Accessing and Clearing History

The component exposes minimal, controlled access to the history array:

```typescript
// packages/tui/src/components/editor.ts#L442-L444
getHistory(): string[] {
  return this.history;
}

```

Session transitions trigger a complete reset via `clearHistory()`:

```typescript
// packages/tui/src/components/editor.ts#L447-L450
clearHistory(): void {
  this.history = [];
  this.historyIndex = -1;
}

```

This is called when a new conversation session begins, ensuring each session starts with a blank history slate.

## Navigating History with Arrow Keys

The editor implements **context-aware arrow key handling**. Navigation only activates when the editor is empty — if the user has typed any text, Up/Down move the cursor instead of touching history.

### Entering History Mode

When the editor is empty and the user presses **Up**, the editor enters history-browsing mode:

```typescript
// Simplified from packages/tui/src/components/editor.ts#L475-L491
navigateHistory(direction: -1 | 1): void {
  if (this.history.length === 0) return;

  if (this.historyIndex === -1 && direction === -1) {
    // First Up press: enter history mode
    this.historyIndex = 0;
    this.setText(this.history[0]);
    return;
  }

  // Subsequent navigation...
}

```

### Cycling Through Entries

Once in history mode, continued Up/Down presses move through the array:

| Key Press | Effect |
|-----------|--------|
| **Up** (`direction = -1`) | Increment `historyIndex` → older entries |
| **Down** (`direction = 1`) | Decrement `historyIndex` → newer entries |
| **Down past index 0** | Exit mode (`historyIndex = -1`), restore empty editor |
| **Up past final entry** | Stay at last valid index (bounded) |

The `navigateHistory` method handles boundary checks and text injection:

```typescript
navigateHistory(direction: -1 | 1): void {
  const newIndex = this.historyIndex + direction;

  if (newIndex >= this.history.length) {
    // Hit the oldest entry, stay there
    return;
  }

  if (newIndex < -1) {
    // Should not happen due to prior checks
    return;
  }

  if (newIndex === -1) {
    // Exiting history mode downward
    this.historyIndex = -1;
    this.setText('');  // restore original empty state
    return;
  }

  this.historyIndex = newIndex;
  this.setText(this.history[newIndex]);
}

```

### Detecting History Mode

Other editor methods check `isBrowsingHistory()` to alter behavior:

```typescript
// packages/tui/src/components/editor.ts#L470
isBrowsingHistory(): boolean {
  return this.historyIndex > -1;
}

```

## Automatic Exit Triggers

History mode exits cleanly through multiple pathways, all resetting `historyIndex = -1`:

| Trigger | Location | Reason |
|---------|----------|--------|
| Typing any character | Multiple points (e.g., L1148, L1167, L1230) | User starts new input |
| Pressing Down past newest entry | `navigateHistory` | Natural navigation boundary |
| Cursor movement (Left/Right/Home/End) | Various key handlers | User intends cursor control |
| Undo operation | Editor internals | State change invalidates history context |

This multi-point exit strategy ensures the editor never traps the user in history mode unintentionally.

## Integration with the TUI System

The editor component operates within a broader architecture:

- **[`packages/tui/src/editor-component.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/editor-component.ts)** — wraps the core editor, forwarding raw key events and managing terminal focus
- **[`packages/tui/src/tui.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/tui.ts)** — orchestrates the full interface, creating editor instances and binding them to session lifecycle events (new session → `clearHistory()`)

This separation keeps history logic encapsulated in the editor while allowing higher layers to control session boundaries.

## Key Implementation Summary

| Method | Purpose | Source Lines |
|--------|---------|--------------|
| `addToHistory(trimmed)` | Store new prompt, enforce 100-entry cap | L434-L438 |
| `getHistory()` | Expose read-only array access | L442-L444 |
| `clearHistory()` | Reset for new session | L447-L450 |
| `navigateHistory(direction)` | Handle Up/Down navigation | L475-L491 |
| `isBrowsingHistory()` | Check active browsing state | L470 |

## Summary

- **PrimeAgent stores conversation history in-memory within the TUI editor component**, not in external databases or terminal scrollback.
- **Newest prompts are unshifted to index 0** with a hard 100-entry limit to control memory.
- **Navigation requires an empty editor** — Up enters history mode, subsequent Up/Down cycles through entries, Down past newest exits.
- **Any character typed while browsing immediately exits** history mode, preserving the original or selected text.
- **Sessions are fully isolated** via `clearHistory()`, preventing prompt leakage across conversations.

## Frequently Asked Questions

### Does PrimeAgent persist conversation history across application restarts?

No. History is maintained only in-memory within the `Editor` class instance. When the application closes or a new session begins via `clearHistory()`, all history is discarded. There is no file or database backing for prompt history in the current implementation.

### Why does history navigation only work when the editor is empty?

This design prevents accidental history activation while editing. If you've already typed partial text, Up/Down control cursor movement instead. The editor checks for existing content before invoking `navigateHistory()`, ensuring predictable behavior based on context.

### What happens if I press Up more times than there are history entries?

The navigation bounds prevent out-of-range access. When `historyIndex` reaches the last valid entry (oldest prompt), further Up presses are ignored. You remain at that entry until you press Down or start typing to exit history mode.

### Is the 100-entry history limit configurable?

The limit is hardcoded as `100` in `addToHistory()` at [packages/tui/src/components/editor.ts#L436](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/tui/src/components/editor.ts#L436). There is no exposed configuration option in the current codebase; modifying this requires editing the source constant directly.