Client Spaces

A useful staff reference, built from your real business.

Start a small restaurant, gym, or general client pilot with approved operating knowledge. Each client gets an explicitly chosen Space for capture and recall.

Run a focused pilot

Create one private Space for an authorized client. Choose a template and edit its purpose. Templates add no facts, documents, or sample memories. Create a Space.
Capture a few approved sources. For a restaurant, use its current menu information, service handbook, and opening checklist. For a gym, use membership policies, class operations, and front-desk FAQs. Keep the gym pilot about staff operations; do not upload health or medical records.
Check the capture’s job. Open Processing and match the returned job ID. This is your account’s queue, not a client-filtered view. A completed job may yield one, several, or no memories; review what was saved.
Test with known questions. Use “Ask this Space” from its page. Check the answer and sources against your approved material, and test a question whose answer is absent. For separate clients, use distinct test documents and confirm each stays out of the other client’s results.
Connect an actual system you control. Start with one reviewed export or a small server integration. Confirm permission, Space mapping, processing, and retrieval before automating additional material.

These templates do not provision POS, booking, or medical-record connectors. An integration with those systems would need its own authorized implementation. Creating a Space sends no invitations or emails. Public signup remains disabled; use an existing authorized account for the pilot.

Connect through your server

Start with a runnable integration

The Node.js starter gives each client’s backend its own credential and maps it to one Space. It includes capture, job status, and search endpoints, setup instructions, and tests. Configure it on your server, then connect the client’s approved source or export. This starter needs no additional database.

Download integration starter

Requires Node.js 22+, a server API key and one private Space per client. Your developer must connect the existing business software and staff authentication.

Create an API key in Settings and keep it in your server’s secret store. API keys are account credentials with API permissions, not tenant-scoped credentials. Naming a key after a client does not restrict it to that client’s Space. Never expose the key in a browser bundle or hand it to a customer.

Authenticate and authorize the caller in your application. Resolve their client-to-Space mapping from your database and include that exact Space in every capture and retrieval. Never trust a customer-posted spaceId, client ID, or conversation ID as authorization. Refuse requests with missing mappings or failed access checks; do not retry without a Space.

The example below uses the actual TypeScript SDK methods. Implement the two application adapters in ./your-server for your own authentication, authorization, and approved source data. Store returned job IDs against the same client and check that association before exposing job status.

npm install @persistmemory/sdk

import { PersistMemory } from "@persistmemory/sdk";
// Application adapters you must implement: authenticate staff,
// authorize their client, then read that client's approved material.
import { requireStaffClient, loadApprovedProcedure } from "./your-server";

const apiKey = process.env.PERSISTMEMORY_API_KEY;
if (!apiKey) throw new Error("Missing server API key");
const memory = new PersistMemory({ apiKey });

export async function captureProcedure(request: Request) {
  const client = await requireStaffClient(request);
  // Read this mapping from your server database, never request JSON.
  const spaceId = client.persistMemorySpaceId;
  if (!spaceId) throw new Error("Client has no configured Space");
  const procedure = await loadApprovedProcedure(client.id);

  const accepted = await memory.memories.remember({
    text: procedure.text,
    title: procedure.title,
    spaceIds: [spaceId]
  }, {
    idempotencyKey: "client:" + client.id + ":procedure:" + procedure.id + ":v" + procedure.version
  });
  // Store this association on your server so job access is client-checked.
  // accepted.jobId is a processing job, not a memory ID.
  return accepted;
}

export async function recallProcedures(request: Request, query: string) {
  const client = await requireStaffClient(request);
  const spaceId = client.persistMemorySpaceId;
  if (!spaceId) throw new Error("Client has no configured Space");
  return memory.search.query({ query, spaceIds: [spaceId], limit: 5 });
}

Use a stable idempotency key for the same source revision and client. Change it when approved source content changes. Search returns ranked memories and diagnostics, not a generated answer. Use those records as evidence in your own staff interface, or use the Space’s Ask page to test answers.

Acceptance is the start of processing

memory.memories.remember calls POST /api/v1/remember (also mounted as POST /v1/remember) with { text, title, spaceIds: [spaceId] }. It returns HTTP 202 with jobId, not a memory. Poll memory.jobs.get(jobId) with a bounded retry policy, or check later from a background worker.

// Use a job ID stored for this authorized client, not an unchecked
// jobId supplied by a customer. Check on a later request or poll with
// a fixed limit; do not keep a browser request waiting forever.
const job = await memory.jobs.get(storedJobId);
switch (job.status) {
  case "completed":
    // Review the saved material, then test scoped retrieval.
    break;
  case "failed":
  case "dead":
    // Surface job.error; review before resubmitting material.
    break;
  case "queued":
  case "running":
    // Still processing. Check again later.
    break;
}

For file ingestion, the SDK also offers memory.memories.uploadFile with bytes, filename, contentType, and an explicit spaceId. It returns a jobId and documentId for processing and document review.

Keep the client boundary explicit

A Space is a knowledge boundary inside an account. A memory may be filed in multiple Spaces, so do not file one client’s material into another’s Space or merge client Spaces. Sharing gives an accepted collaborator access to that Space; it does not create a separate tenant account.

Start a new conversation for each client context. If your application resumes threads, store and verify the client-to-conversation association on your server. Account connections and live tools may have broader access than a single Space: a selected Space limits saved-memory retrieval, not the authority of an account’s Gmail, Drive, or computer tools. Use only approved sources and tools for the pilot.

Full SDK reference Your Spaces