/hindsight-docs

Programmatic API (Node.js)

The @vectorize-io/hindsight-all npm package is the Node.js equivalent of the Python hindsight-all package. It lets your Node code spawn and supervise a local Hindsight daemon without deploying any server infrastructure — pair it with @vectorize-io/hindsight-client for memory operations.

The daemon runs as a separate OS process on 127.0.0.1 (not in your Node process). Your code talks to it over HTTP via HindsightClient.

This package does not ship an HTTP client — it only owns the server process. Once the daemon is running, talk to it with @vectorize-io/hindsight-client against server.getBaseUrl(). The two packages compose: one owns the process, the other owns the API surface.

How it works

1. server.start() resolves the underlying hindsight-embed command (via uvx from PyPI, or uv run --directory <path> for a local checkout).
2. Runs profile create <name> --merge --port <port> [--env KEY=VALUE ...] with every entry from options.env forwarded as --env.
3. Runs daemon --profile <name> start.
4. Polls http://host:port/health until it returns 200 or the readyTimeoutMs budget is exhausted.
5. server.stop() runs daemon --profile <name> stop.

The server is intentionally transparent: new daemon env vars or CLI flags never require a wrapper release — pass them through env, extraProfileCreateArgs, or extraDaemonStartArgs.

Requirements

• Node.js ≥ 22 — uses global fetch and AbortSignal.timeout.
• uv / uvx on PATH — used to download and run the Hindsight daemon. Install via docs.astral.sh/uv.

Install

npm install @vectorize-io/hindsight-all @vectorize-io/hindsight-client

Example

import { HindsightServer, consoleLogger } from '@vectorize-io/hindsight-all';
import { HindsightClient } from '@vectorize-io/hindsight-client';

const server = new HindsightServer({
  profile: 'my-app',
  port: 9077,
  env: {
    HINDSIGHT_API_LLM_PROVIDER: 'anthropic',
    HINDSIGHT_API_LLM_API_KEY: process.env.ANTHROPIC_API_KEY,
    HINDSIGHT_API_LLM_MODEL: 'claude-sonnet-4-20250514',
  },
  logger: consoleLogger,
});

await server.start();

const client = new HindsightClient({ baseUrl: server.getBaseUrl() });
await client.retain('user-123', 'User prefers dark mode.');
const recall = await client.recall('user-123', 'what are the user preferences?');

await server.stop();

For a remote Hindsight API, skip the server entirely and point HindsightClient directly at the remote URL.

HindsightServerOptions

Server methods

For memory operations (retain, recall, reflect, bank management) use @vectorize-io/hindsight-client.