TypeScript SDK

HTTP client for the Pensyve REST API. Works in Node.js, Bun, Deno, and edge runtimes.

bun add pensyve
# or
npm install pensyve

The TypeScript SDK is an HTTP client. It requires a running Pensyve REST API server.

`Pensyve`

`new Pensyve(config)`

Create a client instance.

Parameter	Type	Default	Description
`config`	`PensyveConfig`	required	Client configuration

import Pensyve from "pensyve";

const p = new Pensyve({ baseUrl: "http://localhost:8000" });
const p = new Pensyve({
  baseUrl: "https://api.pensyve.com",
  namespace: "project-x",
  timeoutMs: 10_000,
  retries: 3,
});

`entity(name, kind?)`

Create or retrieve an entity.

Parameter	Type	Default	Description
`name`	`string`	required	Entity name
`kind`	`string`	`"user"`	One of `"agent"`, `"user"`, `"team"`, `"tool"`

Returns: Promise<Entity>

const user = await p.entity("alice");
const agent = await p.entity("my-agent", "agent");

`recall(query, options?)`

Search memories matching a query.

Parameter	Type	Default	Description
`query`	`string`	required	Search query
`options`	`RecallOptions`	`{}`	Optional filters

Returns: Promise<Memory[]>

const memories = await p.recall("project X deadline");
const memories = await p.recall("deployment steps", {
  entity: "my-agent",
  limit: 10,
  types: ["procedural"],
});

`remember(options)`

Store a semantic memory.

Parameter	Type	Default	Description
`options`	`RememberOptions`	required	Memory to store

Returns: Promise<Memory>

const m = await p.remember({
  entity: "alice",
  fact: "Alice prefers dark mode",
  confidence: 0.9,
});

`forget(entityName, hardDelete?)`

Archive or delete all memories for an entity.

Parameter	Type	Default	Description
`entityName`	`string`	required	Entity name
`hardDelete`	`boolean`	`false`	Permanently delete

Returns: Promise<ForgetResult>

const result = await p.forget("alice");
const result = await p.forget("alice", true);

`consolidate()`

Trigger memory consolidation (promotion, decay, archival).

Returns: Promise<ConsolidateResult>

const stats = await p.consolidate();
// { promoted: 3, decayed: 12, archived: 1 }

`stats()`

Get runtime statistics.

Returns: Promise<Record<string, unknown>>

const stats = await p.stats();

`health()`

Check API server health.

Returns: Promise<HealthResult>

const h = await p.health();
// { status: "ok", version: "0.1.0" }

`startEpisode(participants)`

Begin an episode for recording messages.

Parameter	Type	Default	Description
`participants`	`string[]`	required	Entity names participating

Returns: Promise<EpisodeHandle>

const ep = await p.startEpisode(["alice", "my-agent"]);
await ep.addMessage("user", "What's the status?");
await ep.addMessage("assistant", "On track for Q2.");
ep.setOutcome("success");
const result = await ep.end();
// { memoriesCreated: 2 }

Types

`PensyveConfig`

interface PensyveConfig {
  baseUrl: string;
  namespace?: string;       // default: "default"
  fetch?: typeof fetch;     // custom fetch implementation
  timeoutMs?: number;       // default: 30000
  retries?: number;         // default: 2
  retryBaseDelayMs?: number; // default: 500
}

`Entity`

interface Entity {
  id: string;
  name: string;
  kind: string;
}

`Memory`

interface Memory {
  id: string;
  content: string;
  memoryType: "episodic" | "semantic" | "procedural";
  confidence: number;
  stability: number;
  score?: number;
}

`RecallOptions`

interface RecallOptions {
  entity?: string;
  limit?: number;         // default: 5
  types?: Array<"episodic" | "semantic" | "procedural">;
}

`RememberOptions`

interface RememberOptions {
  entity: string;
  fact: string;
  confidence?: number;    // default: 0.8
}

`ForgetResult`

interface ForgetResult {
  forgottenCount: number;
}

`ConsolidateResult`

interface ConsolidateResult {
  promoted: number;
  decayed: number;
  archived: number;
}

`HealthResult`

interface HealthResult {
  status: string;
  version: string;
}

`EpisodeHandle`

interface EpisodeHandle {
  addMessage(role: string, content: string): Promise<void>;
  setOutcome(outcome: "success" | "failure" | "partial"): void;
  end(): Promise<{ memoriesCreated: number }>;
}

`PensyveError`

Thrown on non-2xx responses. 4xx errors are not retried. 5xx errors are retried per the retries config.

Property	Type	Description
`status`	`number`	HTTP status code
`statusText`	`string`	HTTP status text
`detail`	`string \| null`	Error detail from API response body
`endpoint`	`string`	Description of the operation that failed

import { PensyveError } from "pensyve";

try {
  await p.recall("test");
} catch (err) {
  if (err instanceof PensyveError && err.status === 401) {
    console.error("Invalid API key");
  }
}

On this page