---
sidebar_position: 7
title: Memory (test)
---

# Memory skill

Query the test memory database — prior test runs, known selectors with stability metrics, page models, navigation transitions — and save insights for future runs. Dolt-backed (git-style versioned SQL).

- **ID:** `memory`
- **MCP server:** `memory` (tools exposed as `mcp__memory__*`)
- **Underlying server:** `@zibby/ui-memory/mcp-server`

For persistent **chat** memory (not test history) see [Chat memory](./chat-memory.md).

## Tools provided

| Tool | What it does |
|---|---|
| `memory_get_test_history` | Recent test runs with pass/fail + timing. Filter by `specPath` substring |
| `memory_get_selectors` | Known selectors for a page with stability metrics. Filter by `pageUrl` substring |
| `memory_get_page_model` | Page structure — elements, roles, selectors. Filter by `url` substring |
| `memory_get_navigation` | Known page-to-page transitions. Filter by `fromUrl` substring |
| `memory_save_insight` | Save an observation. Categories: `selector_tip`, `timing`, `navigation`, `workaround`, `flaky`, `general` |

## Setup

Requires [Dolt](https://docs.dolthub.com/introduction/installation) and an initialized memory database in your workspace.

```bash
# macOS
brew install dolt
# then, in your agent workspace:
zibby init --mem
```

`zibby init --mem` creates `.zibby/memory/` (a Dolt repo). The memory tools only activate after at least one completed test run — until then the skill returns `null` from `resolve()` and is skipped.

Override the bin location for development with `MCP_MEMORY_PATH`.

See [Tests → Memory](../tests/memory.md) for the full memory lifecycle.

## Use in an agent

```js
import { WorkflowAgent, WorkflowGraph } from '@zibby/core';
import { SKILLS } from '@zibby/skills';

export class FlakyTestInvestigator extends WorkflowAgent {
  buildGraph() {
    const graph = new WorkflowGraph();
    graph.addNode('investigate', {
      agent: 'claude',
      skills: [SKILLS.MEMORY, SKILLS.BROWSER],
      prompt: (state) => `Before running the test:
      1. Call memory_get_test_history with specPath="${state.specPath}" — review prior failures.
      2. Call memory_get_selectors with pageUrl matching the target page.
      Then run the test using the browser tools. When done, save a memory_save_insight
      capturing any selectors that worked when an older one failed.`,
    });
    return graph;
  }
}
```

The skill's prompt fragment auto-instructs the agent to consult prior runs and call `memory_save_insight` mid-run when a fallback selector works, and at minimum once at end-of-run.

## Output example

`memory_get_selectors`:

```json
{
  "selectors": [
    {
      "pageUrl": "/dashboard",
      "role": "button",
      "stableId": "e7a1",
      "selector": "[data-testid='new-project']",
      "successCount": 42,
      "failureCount": 1,
      "lastSeen": "2026-05-15T14:00:00Z"
    }
  ]
}
```

## Implementation notes

`resolve({ workspace })` resolves `@zibby/ui-memory/mcp-server` and spawns it with `--db-path .zibby/memory`. Before spawning it sanity-checks Dolt is on the PATH and the database has at least one `test_runs` row; if not, returns `null` (skill skipped silently) or throws a clear "install Dolt" error.

The skill also exports `middleware()` that loads `createMemoryMiddleware()` from `@zibby/ui-memory` when the package is present — this runs before/after each node to inject test history into the prompt and persist new insights.