@persistmemory/sdk 0.1.0

package/dist/resources/spaces.d.ts

@@ -0,0 +1,55 @@
+import type { HttpClient, RequestOptions } from "../http.js";
+import { Paginated } from "../pagination.js";
+import type { CreateSpaceParams, ListSpacesParams, Memory, Space, UpdateSpaceParams } from "../types.js";
+/**
+ * Spaces: a boundary around a set of memories.
+ *
+ * They exist because "everything I know" is the wrong scope for most
+ * questions. Work and personal contexts hold contradictory truths - two
+ * different "my manager" - and answering from both at once is wrong in a way
+ * that is hard to notice.
+ *
+ * Membership is a LINK, not ownership. `removeMemories` takes a memory out of
+ * a Space; it does not delete it, and the same memory can belong to several.
+ */
+export declare class Spaces {
+    #private;
+    constructor(http: HttpClient);
+    list(params?: ListSpacesParams, options?: RequestOptions): Paginated<Space>;
+    get(id: string, options?: RequestOptions): Promise<Space>;
+    /**
+     * Creates a Space. Answers 201.
+     *
+     * Worth an idempotency key when a person is behind it: a double-clicked
+     * "create Space" button makes two Spaces called Work, and nothing later can
+     * tell which of them memories should have gone into.
+     */
+    create(params: CreateSpaceParams, options?: RequestOptions): Promise<Space>;
+    /** Renaming, retention, and archiving - `archived` is a field, not a verb. */
+    update(id: string, params: UpdateSpaceParams, options?: RequestOptions): Promise<Space>;
+    /**
+     * The memories filed in a Space.
+     *
+     * This endpoint answers `{ data, pagination: { limit } }` with no cursor: it
+     * returns the first `limit` members and stops. Wrapped in a `Paginated`
+     * anyway so it reads like every other list, and it simply yields one page -
+     * a caller who needs more should filter `memories.list` by `spaceIds`, which
+     * is the endpoint that actually pages.
+     */
+    memories(id: string, params?: {
+        readonly limit?: number;
+    }, options?: RequestOptions): Paginated<Memory>;
+    addMemories(id: string, memoryIds: readonly string[], options?: RequestOptions): Promise<{
+        added: number;
+    }>;
+    /**
+     * Removes memberships. The memories themselves are untouched.
+     *
+     * A body on a DELETE, which is unusual and is what the API takes: the
+     * alternative is five hundred ids in a query string, and every proxy in
+     * between has its own limit on how long a URL may be.
+     */
+    removeMemories(id: string, memoryIds: readonly string[], options?: RequestOptions): Promise<{
+        removed: number;
+    }>;
+}

package/dist/types.d.ts

@@ -0,0 +1,500 @@
+/**
+ * The wire types, transcribed from the Zod schemas the API validates against.
+ *
+ * Transcribed rather than generated, because generation from the OpenAPI
+ * document would give this package a build step and a code generator to keep
+ * working, and the surface is small enough to read. The contract they mirror
+ * is `apps/api/src/schemas/*.ts` - those objects both parse requests AND
+ * validate responses on the way out, so a field that is not there cannot be
+ * returned.
+ *
+ * Every optional field below is optional in the schema. That matters more than
+ * it looks: `noUncheckedIndexedAccess` and `exactOptionalPropertyTypes` are on,
+ * so a caller reading `memory.supersedes` is forced to handle its absence, and
+ * an absent field is the normal case rather than a bug.
+ *
+ * Timestamps are ISO 8601 strings with an offset, never Date. JSON has no date
+ * type, and every client that has guessed at a format has eventually guessed
+ * wrong.
+ */
+export type MemoryType = "fact" | "preference" | "decision" | "task" | "commitment" | "event" | "relationship" | "goal" | "plan" | "project" | "instruction" | "constraint" | "observation" | "experience" | "knowledge" | "change" | "status" | "question" | "assumption";
+export type MemoryState = "candidate" | "active" | "confirmed" | "uncertain" | "superseded" | "expired" | "archived" | "deleted";
+export type SpaceKind = "user" | "system" | "temporary" | "project" | "organizational";
+export type ConflictType = "value" | "temporal" | "identity" | "relationship" | "state" | "source";
+export type ResolutionStrategy = "user-confirmation" | "explicit-correction" | "temporal-validity" | "higher-confidence" | "corroboration" | "newer-source" | "unresolved";
+export type JobStatus = "queued" | "running" | "completed" | "failed" | "dead";
+export type DocumentStatus = "pending" | "processing" | "processed" | "empty" | "failed";
+export type IntegrationStatus = "connected" | "reauth_required" | "syncing" | "error" | "disabled";
+export type MessageRole = "user" | "assistant" | "system" | "tool";
+/** Which memories an operation may see. */
+export type Scope = "universal" | "space" | "combined";
+/**
+ * The envelope every list endpoint returns.
+ *
+ * `nextCursor` absent is the ONLY signal to stop. An empty `data` array is not
+ * the same thing - a page can come back empty because everything in it was
+ * filtered after the fetch while more pages remain, and a client that stops on
+ * an empty page silently truncates the user's results.
+ */
+export interface Page<T> {
+    readonly data: readonly T[];
+    readonly pagination: {
+        readonly nextCursor?: string;
+        readonly limit: number;
+    };
+}
+export interface EntityRef {
+    readonly id?: string;
+    readonly name: string;
+    readonly type: string;
+    /** How sure we are this mention IS that entity, not merely a name match. */
+    readonly confidence?: number;
+}
+export interface EvidenceRef {
+    readonly id: string;
+    readonly sourceId?: string;
+    readonly documentId?: string;
+    /** The passage the claim rests on, so a user can check it. */
+    readonly excerpt: string;
+    readonly observedAt?: string;
+}
+export interface SourceRef {
+    readonly id: string;
+    readonly provider: string;
+    readonly type: string;
+    readonly externalId?: string;
+}
+export interface Temporal {
+    readonly validFrom?: string;
+    readonly validUntil?: string;
+    /** True while the claim is believed to hold. */
+    readonly current: boolean;
+}
+export interface Memory {
+    readonly id: string;
+    readonly type: MemoryType;
+    readonly state: MemoryState;
+    readonly title: string;
+    readonly content: string;
+    readonly value?: Readonly<Record<string, unknown>>;
+    /** 0 to 1, like every score in this API. */
+    readonly confidence: number;
+    readonly importance: number;
+    readonly entities: readonly EntityRef[];
+    readonly sources: readonly SourceRef[];
+    readonly evidence: readonly EvidenceRef[];
+    readonly temporal: Temporal;
+    readonly spaceIds?: readonly string[];
+    readonly version: number;
+    readonly supersedes?: string;
+    readonly supersededBy?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly lastConfirmedAt?: string;
+}
+export interface ListMemoriesParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly type?: MemoryType | readonly MemoryType[];
+    readonly state?: MemoryState | readonly MemoryState[];
+    readonly scope?: Scope;
+    readonly spaceIds?: readonly string[];
+    readonly createdAfter?: string;
+    readonly createdBefore?: string;
+    readonly minConfidence?: number;
+    /** Off by default: a list of memories almost always means "what is true now". */
+    readonly includeHistorical?: boolean;
+}
+/**
+ * What `POST /remember` takes.
+ *
+ * `text`, not `content`. The route parses its own body and this is the name it
+ * uses - the schema file next door describes a richer capture shape that this
+ * endpoint does not implement, and sending `content` gets a 400 that names
+ * `text` as required.
+ */
+export interface RememberParams {
+    readonly text: string;
+    readonly title?: string;
+    readonly spaceIds?: readonly string[];
+}
+/**
+ * The answer, which is NOT a memory.
+ *
+ * `remember` hands material to the ingestion pipeline and returns 202.
+ * Extraction, entity resolution, deduplication and conflict detection all run
+ * afterwards, and may produce one memory, several, or none. Poll `jobId`
+ * through `client.jobs.get` to find out which.
+ */
+export interface RememberResult {
+    readonly status: string;
+    readonly jobId: string;
+    readonly note: string;
+}
+export interface SearchParams {
+    readonly query: string;
+    /** Capped at 50 by the server. Every result costs a rerank. */
+    readonly limit?: number;
+    readonly scope?: Scope;
+    readonly spaceIds?: readonly string[];
+    readonly types?: MemoryType | readonly MemoryType[];
+    readonly minScore?: number;
+    /** As of a moment: what was believed true then, not what is true now. */
+    readonly asOf?: string;
+    readonly includeHistorical?: boolean;
+    readonly includeEvidence?: boolean;
+    readonly explain?: boolean;
+}
+export interface SearchExplanation {
+    /** Which retrieval paths found it: `vector`, `structured`, `graph`. */
+    readonly paths: readonly string[];
+    readonly vectorScore?: number;
+    readonly structuredScore?: number;
+    readonly rerankScore?: number;
+    readonly adjustments?: readonly {
+        readonly reason: string;
+        readonly delta: number;
+    }[];
+}
+export interface SearchResult {
+    readonly memory: Memory;
+    readonly score: number;
+    readonly explanation?: SearchExplanation;
+}
+export interface SearchResponse {
+    readonly results: readonly SearchResult[];
+    /**
+     * What the planner actually did.
+     *
+     * Worth reading. Search DEGRADES rather than fails: with embeddings down it
+     * falls back to deterministic retrieval and still answers. A client that
+     * ignores `degraded` reports "search is broken" when it is merely narrower,
+     * and - worse - never reports it when it silently is.
+     */
+    readonly diagnostics: {
+        readonly steps: readonly string[];
+        readonly degraded: boolean;
+        readonly unavailable?: readonly string[];
+        /** A sentence to show the user when a capability is deliberately stopped. */
+        readonly notice?: string;
+        readonly tookMs: number;
+    };
+    /** Echoed, so an empty result can be told from a mis-sent query. */
+    readonly query: string;
+}
+export interface ContextParams {
+    readonly query: string;
+    /**
+     * The budget, in TOKENS, not rows.
+     *
+     * The real constraint on the caller's side: ten long memories overflow a
+     * window that fifty short ones fit inside.
+     */
+    readonly tokenBudget?: number;
+    readonly scope?: Scope;
+    readonly spaceIds?: readonly string[];
+    /** Ids the caller already has in the prompt, so they are not spent twice. */
+    readonly exclude?: readonly string[];
+    readonly asOf?: string;
+}
+export interface ContextResponse {
+    /** Ready to paste into a prompt. */
+    readonly context: string;
+    readonly memories: readonly {
+        readonly id: string;
+        readonly title: string;
+        readonly score: number;
+    }[];
+    readonly usedTokens: number;
+    /** True when something relevant was left out for budget. */
+    readonly truncated: boolean;
+}
+export interface Space {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: SpaceKind;
+    readonly description?: string;
+    readonly parentId?: string;
+    readonly audience?: string;
+    readonly retentionDays?: number;
+    readonly memoryCount?: number;
+    readonly createdAt: string;
+    /** Set when archived. An archived Space is hidden, not deleted. */
+    readonly archivedAt?: string;
+}
+export interface CreateSpaceParams {
+    readonly name: string;
+    readonly description?: string;
+    readonly kind?: SpaceKind;
+    readonly parentId?: string;
+    readonly retentionDays?: number;
+}
+export interface UpdateSpaceParams {
+    readonly name?: string;
+    readonly description?: string;
+    readonly retentionDays?: number;
+    /** Archiving and restoring, as a field rather than a verb endpoint. */
+    readonly archived?: boolean;
+}
+export interface ListSpacesParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly includeArchived?: boolean;
+}
+export interface Source {
+    readonly id: string;
+    readonly provider: string;
+    readonly type: string;
+    readonly externalId?: string;
+    readonly label?: string;
+    readonly documentCount?: number;
+    readonly lastIngestedAt?: string;
+    readonly createdAt: string;
+}
+export interface ListSourcesParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly provider?: string;
+}
+export interface Document {
+    readonly id: string;
+    readonly sourceId: string;
+    readonly contentType: string;
+    /** Which normaliser handled it - `text`, `pdf`, `email`, `transcript`. */
+    readonly plugin: string;
+    readonly status: DocumentStatus;
+    readonly title?: string;
+    readonly bytes?: number;
+    readonly memoryCount?: number;
+    /** Present only when `failed`, and sanitised - never a provider stack. */
+    readonly error?: string;
+    readonly createdAt: string;
+    readonly processedAt?: string;
+}
+export interface ListDocumentsParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly sourceId?: string;
+    readonly status?: DocumentStatus | readonly DocumentStatus[];
+}
+export interface Job {
+    readonly id: string;
+    readonly type: string;
+    readonly status: JobStatus;
+    readonly subjectId?: string;
+    readonly attempts: number;
+    /** Sanitised. A provider's raw message can carry user content. */
+    readonly error?: string;
+    /** 0 to 1 when the job can report it. Absent is normal, not a bug. */
+    readonly progress?: number;
+    readonly queuedAt: string;
+    readonly startedAt?: string;
+    readonly finishedAt?: string;
+}
+export interface ListJobsParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly status?: JobStatus | readonly JobStatus[];
+    readonly type?: string;
+}
+export interface Entity {
+    readonly id: string;
+    readonly name: string;
+    readonly type: string;
+    /** Other names the same thing goes by. */
+    readonly aliases: readonly string[];
+    readonly memoryCount?: number;
+    readonly firstSeenAt?: string;
+    readonly lastSeenAt?: string;
+    readonly createdAt: string;
+}
+export interface ListEntitiesParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly type?: string;
+    /** Prefix match on name or alias, for a picker. */
+    readonly q?: string;
+}
+export interface EntityMention {
+    readonly memoryId: string;
+    readonly role?: string;
+    readonly confidence?: number;
+}
+export interface EntityMemoriesParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    /** Subject, mention, participant. Two different questions. */
+    readonly role?: string;
+    readonly minConfidence?: number;
+}
+export interface Relationship {
+    readonly id: string;
+    /** `works_at`, `uses`, `depends_on`, `other`. */
+    readonly predicate: string;
+    readonly label?: string;
+    readonly subject: {
+        readonly id?: string;
+        readonly name: string;
+        readonly type: string;
+    };
+    readonly object: {
+        readonly id?: string;
+        readonly name: string;
+        readonly type: string;
+    };
+    readonly confidence: number;
+    readonly observedAt: string;
+}
+export interface GraphNode {
+    readonly id: string;
+    readonly name: string;
+    readonly kind: string;
+    /** Hops from the starting entity, so a client can lay the graph out. */
+    readonly distance: number;
+}
+/**
+ * Walking the graph.
+ *
+ * `from` is an ENTITY id. Edges run between entities, not between memories,
+ * and the walk reports the memories the edges were extracted from.
+ */
+export interface TraverseParams {
+    readonly from: string;
+    /** 1 to 4. Depth explodes exponentially, which is why it is bounded. */
+    readonly depth?: number;
+    readonly maxNodes?: number;
+    readonly memoryLimit?: number;
+}
+export interface GraphResponse {
+    readonly nodes: readonly GraphNode[];
+    readonly edges: readonly Relationship[];
+    readonly memoryIds: readonly string[];
+    /** True when a bound stopped the walk. Silence would read as "this is all". */
+    readonly truncated: boolean;
+}
+export interface Conflict {
+    readonly id: string;
+    readonly type: ConflictType;
+    readonly description?: string;
+    readonly confidence: number;
+    /** Both sides in full: a person cannot choose between two ids. */
+    readonly a: Memory;
+    readonly b: Memory;
+    readonly detectedAt: string;
+    readonly resolution?: {
+        readonly strategy: ResolutionStrategy;
+        readonly winnerId?: string;
+        readonly reason: string;
+        readonly resolvedAt: string;
+    };
+}
+export interface ListConflictsParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    /** Off by default: the list exists to be worked through. */
+    readonly includeResolved?: boolean;
+    readonly type?: ConflictType | readonly ConflictType[];
+}
+/**
+ * Settling a conflict.
+ *
+ * `keep` names the winner and SUPERSEDES the other; it does not delete it. The
+ * losing claim was true once, and a system that erases it cannot answer "what
+ * did I think last month".
+ */
+export type ResolveConflictParams = {
+    readonly action: "keep";
+    readonly keepId: string;
+    readonly reason?: string;
+} | {
+    readonly action: "dismiss";
+    readonly reason?: string;
+};
+export interface Message {
+    readonly id: string;
+    readonly role: MessageRole;
+    readonly content: string;
+    /** Memories surfaced into this turn, for citation. */
+    readonly memoryIds?: readonly string[];
+    readonly createdAt: string;
+}
+export interface Conversation {
+    readonly id: string;
+    readonly title?: string;
+    /** Which client this belongs to - `web`, `mcp`, an SDK's own label. */
+    readonly channel?: string;
+    readonly spaceIds?: readonly string[];
+    readonly messageCount: number;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+}
+export interface CreateConversationParams {
+    readonly title?: string;
+    readonly channel?: string;
+    readonly spaceIds?: readonly string[];
+}
+export interface ListConversationsParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly channel?: string;
+}
+export interface AppendMessagesParams {
+    readonly messages: readonly {
+        readonly role: MessageRole;
+        readonly content: string;
+        readonly createdAt?: string;
+    }[];
+    /** On by default - that is the point of sending them. */
+    readonly extract?: boolean;
+}
+export interface AppendMessagesResult {
+    readonly messages: readonly Message[];
+    /**
+     * Whether extraction was actually queued.
+     *
+     * Reported honestly: with no queue configured the turns are stored and never
+     * become memory, and `note` says so. A caller that ignores this believes a
+     * memory is on its way that never arrives.
+     */
+    readonly extracting: boolean;
+    readonly note?: string;
+}
+export interface Integration {
+    readonly id: string;
+    readonly provider: string;
+    readonly status: IntegrationStatus;
+    /** Which account, so a user with two can tell them apart. Never a token. */
+    readonly accountLabel?: string;
+    readonly scopes?: readonly string[];
+    readonly spaceIds?: readonly string[];
+    readonly lastSyncedAt?: string;
+    /** Sanitised, and shown to the user - so it reads as an instruction. */
+    readonly error?: string;
+    readonly createdAt: string;
+}
+export interface ListIntegrationsParams {
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly provider?: string;
+    readonly status?: IntegrationStatus;
+}
+export interface ConnectIntegrationParams {
+    readonly provider: string;
+    /** Where to land afterwards. Checked against an allow-list server-side. */
+    readonly returnTo?: string;
+    readonly spaceIds?: readonly string[];
+}
+export interface ConnectIntegrationResult {
+    /** Send the user here. This endpoint never takes third-party credentials. */
+    readonly authorizeUrl: string;
+    readonly state: string;
+    readonly expiresAt: string;
+}
+export interface UpdateIntegrationParams {
+    readonly enabled?: boolean;
+    readonly spaceIds?: readonly string[];
+}
+export interface HealthResponse {
+    readonly status: string;
+    readonly [key: string]: unknown;
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@persistmemory/sdk",
+  "version": "0.1.0",
+  "description": "The official TypeScript client for the PersistMemory API",
+  "license": "MIT",
+  "author": "PersistMemory",
+  "homepage": "https://persistmemory.com/docs/sdk",
+  "bugs": {
+    "email": "hello@persistmemory.com"
+  },
+  "keywords": [
+    "persistmemory",
+    "memory",
+    "ai",
+    "agent",
+    "llm",
+    "context",
+    "embeddings",
+    "sdk",
+    "client"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsx build.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepack": "tsx build.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "esbuild": "^0.25.12",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.9"
+  }
+}