---
sidebar_position: 3
title: "@zibby/memory"
---

# @zibby/memory

Version-controlled test memory database powered by [Dolt](https://www.dolthub.com/). Learns from every test run — selectors that worked, pages that were visited, patterns that failed, workarounds that helped.

```bash
npm install @zibby/memory
```

## Why Memory?

Without memory, every test run starts from scratch. The AI has no idea which selectors are stable, which pages have changed, or what workarounds were discovered in previous runs.

With `@zibby/memory`:
- **Selectors** — the AI knows which CSS/XPath selectors are reliable and which are flaky
- **Page models** — the AI has a map of page elements, roles, and structure before it even navigates
- **Navigation patterns** — the AI knows which URL transitions are valid
- **Test history** — the AI sees pass/fail trends and avoids repeating past failures
- **Insights** — the AI reads and writes tips (timing quirks, workarounds, selector alternatives)

## Setup

### 1. Install Dolt

Dolt is a version-controlled SQL database (Git for data):

```bash
# macOS
brew install dolt

# Linux
sudo bash -c 'curl -L https://github.com/dolthub/dolt/releases/latest/download/install.sh | bash'
```

### 2. Initialize Memory Database

```bash
zibby init --mem
```

This creates a Dolt database at `.zibby/memory/` with the schema for test runs, selectors, page models, navigation, and insights.

### 3. Enable Memory in Your Workflow

Add `SKILLS.MEMORY` to any node that should have memory access:

```javascript
import { SKILLS } from '@zibby/core';

export const executeLiveNode = {
  name: 'execute_live',
  skills: [SKILLS.BROWSER, SKILLS.MEMORY],
  // ...
};
```

The built-in `execute_live` node already has memory enabled by default.

## How It Works

### During a Test Run

1. **Before execution** — the memory middleware loads relevant history:
   - Previous runs for this spec (pass/fail, timing)
   - Known selectors for the target pages
   - Saved insights and tips

2. **During execution** — the AI can call memory tools:
   - `memory_get_selectors` to find stable selectors
   - `memory_get_page_model` to understand page structure
   - `memory_save_insight` to record a finding

3. **After execution** — the result handler persists new data:
   - Test result (pass/fail, duration)
   - Selectors used and their success/failure
   - Page model updates
   - Navigation transitions discovered

### Version Control

Every persist operation creates a Dolt commit. You can:

```bash
# View memory history
cd .zibby/memory
dolt log

# Diff between runs
dolt diff HEAD~1 HEAD

# Branch for experiments
dolt branch experiment
dolt checkout experiment
```

## Database Schema

### `test_runs`

| Column | Type | Description |
|---|---|---|
| `session_id` | VARCHAR | Unique session identifier |
| `spec_path` | VARCHAR | Path to the test spec file |
| `passed` | BOOLEAN | Whether the test passed |
| `duration_ms` | INT | Total execution time |
| `agent_type` | VARCHAR | Which agent ran the test |
| `created_at` | DATETIME | Timestamp |

### `selectors`

| Column | Type | Description |
|---|---|---|
| `page_url` | VARCHAR | URL where this selector was used |
| `selector` | VARCHAR | The CSS/XPath selector string |
| `stable_id` | VARCHAR | Zibby stable ID (if available) |
| `success_count` | INT | Times this selector worked |
| `fail_count` | INT | Times this selector failed |
| `last_used` | DATETIME | Last usage timestamp |

### `page_model`

| Column | Type | Description |
|---|---|---|
| `url` | VARCHAR | Page URL |
| `element_role` | VARCHAR | ARIA role |
| `element_name` | VARCHAR | Accessible name |
| `selector` | VARCHAR | Best known selector |
| `updated_at` | DATETIME | Last update |

### `navigation`

| Column | Type | Description |
|---|---|---|
| `from_url` | VARCHAR | Source page URL |
| `to_url` | VARCHAR | Destination page URL |
| `trigger` | VARCHAR | What caused the navigation (click, submit, etc.) |
| `count` | INT | Times this transition was observed |

### `insights`

| Column | Type | Description |
|---|---|---|
| `category` | ENUM | `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |
| `content` | TEXT | The insight text |
| `spec_path` | VARCHAR | Related spec |
| `session_id` | VARCHAR | Session that created it |
| `created_at` | DATETIME | Timestamp |

## MCP Tools

The memory MCP server exposes five tools:

```
memory_get_test_history   — Query recent test runs (filter by spec path)
memory_get_selectors      — Query selectors with stability metrics (filter by page URL)
memory_get_page_model     — Query page elements and roles (filter by URL)
memory_get_navigation     — Query page-to-page transitions (filter by source URL)
memory_save_insight       — Save a useful observation for future runs
```

### Example: AI Querying Memory

During execution, the AI might call:

```json
{
  "tool": "memory_get_selectors",
  "input": { "pageUrl": "myapp.com/login", "limit": 10 }
}
```

And receive:

```json
[
  { "selector": "[data-testid='email']", "success_count": 12, "fail_count": 0 },
  { "selector": "#login-email", "success_count": 8, "fail_count": 3 },
  { "selector": "input[name='email']", "success_count": 5, "fail_count": 1 }
]
```

The AI then prefers `[data-testid='email']` because it has the highest success rate.

## Middleware Integration

Memory provides automatic middleware that injects history into the node context:

```javascript
import { createMemoryMiddleware } from '@zibby/memory';

const middleware = createMemoryMiddleware();

const graph = new WorkflowGraph({ middleware: [middleware] });
```

The memory skill registers this middleware automatically when `SKILLS.MEMORY` is declared on a node.

## CLI Commands

```bash
# Initialize memory database
zibby init --mem

# View memory stats
zibby memory status

# Sync memory (push to Dolt remote)
zibby memory sync
```

## Exports

```javascript
import {
  createMemoryMiddleware,
  memoryEndRun,
  memorySyncPush,
} from '@zibby/memory';
```