PersistQ Documentation

Installation

npm install persistq-sdk

Also available via yarn, pnpm, or directly from a CDN for browser usage.

Quick Start

1. Initialize the Client

import { createClient } from 'persistq-sdk'

const client = createClient({
  baseUrl: 'https://memoryhub-cloud.onrender.com',
  apiKey: process.env.PERSISTQ_API_KEY,
})

2. Store a Memory

const result = await client.createMemory(
  'User prefers dark mode and compact layouts',
  'preferences',
  { category: 'ui', timestamp: new Date().toISOString() }
)

if (result.status === 'success') {
  console.log('Memory created:', result.data?.memoryId)
}

3. Search Memories

const results = await client.searchMemories('user interface preferences', {
  limit: 5,
  threshold: 0.7,
})

if (results.status === 'success') {
  results.data?.forEach(memory => {
    console.log(`${memory.content} (similarity: ${memory.similarity})`)
  })
}

API Methods

createMemory(content, project?, metadata?)

Store a new memory with optional project and metadata

content: string (required)
project: string (optional)
metadata: object (optional)
Returns: ApiResponse<{ memoryId: string }>

searchMemories(query, options?)

Semantic search across your memories

query: string (required)
options.limit: number (default: 10)
options.project: string
options.threshold: number (0-1)
Returns: ApiResponse<SearchResult[]>

listMemories(params?)

List memories with pagination and filtering

params.offset: number (default: 0)
params.limit: number (default: 20)
params.project: string
Returns: PaginatedResponse<Memory>

getMemory(id)

Retrieve a specific memory by ID

id: string (required)
Returns: ApiResponse<Memory>

updateMemory(id, updates)

Update an existing memory

id: string (required)
updates.content: string
updates.project: string
updates.metadata: object
Returns: ApiResponse<{ success: boolean }>

deleteMemory(id)

Delete a memory permanently

id: string (required)
Returns: ApiResponse<{ success: boolean }>

getStats()

Get memory statistics for your account

Returns: ApiResponse<MemoryStats>

TypeScript Types

The SDK includes full TypeScript definitions for all methods and responses.

import type {
  Memory,
  MemoryStats,
  SearchResult,
  ApiResponse,
  PaginatedResponse,
  MemoryHubConfig,
} from 'persistq-sdk'

Use Cases

Next.js Applications

Use in API routes, Server Components, or client-side

Node.js Backends

Express, Fastify, Hono - any Node.js framework

Serverless Functions

AWS Lambda, Vercel Edge, Cloudflare Workers

Browser Applications

React, Vue, Svelte, or vanilla JavaScript

Requirements

• Node.js: 18.0.0 or higher (for native fetch support)
• Browsers: All modern browsers with fetch API
• TypeScript: 5.0+ (optional, but recommended)

TypeScript SDK

Zero Dependencies

Full TypeScript

Universal