---
title: "Harness API (recall-memory/api)"
image: "https://recall.edheltzel.codes/og.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://recall.edheltzel.codes/llms.txt
> Use this file to discover all available pages before exploring further.

# Harness API (recall-memory/api)

Stable, thin library surface for humans and agents who need to plug a new harness into Recall **without forking core**.

This is not a Cursor marketplace plugin, not a `HostDescriptor`, and not a new `recall host-hook` host. Ambient text uses public `recall capture` ([Capture adapter](https://recall.edheltzel.codes/docs/reference/capture-adapter/)). This library re-exports the other seams: CLI `recall start`, markdown drop-dir, Cursor catalog/inject, MCP, and skills.

## Install the package, then import the API

```ts
import {
  describeHarnessSeams,
  registerStartFormat,
  registerSessionSource,
  runStart,
  parseMarkdownDrop,
  catalogCursorSessions,
  mergeCursorHooksJson,
} from 'recall-memory/api';
```

Requires Bun (`bun:sqlite`). The CLI binaries remain `recall` and `recall-mcp`; this export does not replace them.

Inspect the live map:

```bash
bun -e 'import { describeHarnessSeams } from "./src/api.ts"; console.log(JSON.stringify(describeHarnessSeams(), null, 2))'
```

## Seams

| Seam | As-built contract | Register hook |
|------|-------------------|---------------|
| **start** | `recall start` renders L0/L1 via `hooks/lib/session-start-context.ts`. `--format cursor` wraps `{ additional_context }`. | `registerStartFormat(id, wrap)` — in-process, for `runStart({ format: id })`. The public CLI still accepts only `markdown` \| `cursor`. |
| **drop** | Write markdown into `MEMORY/<host>-sessions/`. Batch extract scans `*-sessions` generically. | None. The directory name **is** the extension point. `parseMarkdownDrop` / `markdownDropDirName` are the helpers. |
| **capture** | Cursor: `catalogCursorSessions()` (catalog only, no SQLite insert). Dump: `discoverCurrentSession()` ([omp restriction](https://recall.edheltzel.codes/docs/integrations/omp/#explicit-dump-recall_dump-tool)). Ambient harness text: `recall capture` ([Capture adapter](https://recall.edheltzel.codes/docs/reference/capture-adapter/)). Hidden `host-hook` is deprecated for ambient writes; Codex `SessionStart` still uses it for injection only. | `registerSessionSource(adapter)` — in-process, consulted by `discoverCurrentSession()`. Cannot replace builtin `SESSION_SOURCES` ids. |
| **inject** | Cursor snippets under `templates/cursor/` call unqualified `recall start --format cursor`. Claude/Codex call the same assembler through their own hooks. | `mergeCursorHooksJson` is the Cursor hooks.json helper. Do not add a marketplace plugin. |

MCP (`recall-mcp`, server name `recall-memory`) and Agent Skills (`agent-skills/`) are already cross-host. Point at [MCP Tools](https://recall.edheltzel.codes/docs/reference/mcp-tools/) and [Agent Skills](https://recall.edheltzel.codes/docs/reference/agent-skills/); do not fork those catalogs.

## Cursor PATH caveat (FM-321 / FM-327)

As-built, Cursor sessionStart runs `recall start --format cursor` with **no path prefix**. Cursor.app's GUI PATH typically lacks `~/.bun/bin`, so the hook is a no-op until `recall` is on that app PATH. CLI Cursor, or any shell where `recall` resolves, is fine.

A durable fix for GUI PATH / `recall start --format cursor` accuracy is **pending FM-321/327**. This page does not invent a `~/.cursor/hooks` wrapper or a machine-specific prefix. Until those land, treat Cursor inject as beta and verify with `which recall` in the same environment Cursor.app uses.

## Non-goals

- No `HostDescriptor` layer and no adapter→plugin rename.
- No Cursor marketplace plugin (`hosts/plugins/recall-cursor` does not exist).
- Cursor does not join `recall capture`, `recall host-hook`, `host-ingest`, or `LifecycleHost`. Catalog only.
- No CLI extension loader in this slice — registrations are in-process.

A new drop-dir host still does **not** copy `RecallExtract.ts` / `RecallPreCompact.ts`. A new ambient harness calls `recall capture`; it does not extend hidden `host-hook`. That command remains for Codex `SessionStart` injection.

## First-run and host attach

Humans: [Getting Started](https://recall.edheltzel.codes/docs/). Native plugin/extension setup is documented per host; see [omp Integration](https://recall.edheltzel.codes/docs/integrations/omp/) for its capture package. This API does not manage installation.

Source: https://recall.edheltzel.codes/docs/reference/api/index.mdx