Neurophic
SDK

JavaScript SDK

Learn about how to install the SDK, create a client and call every endpoint

The neurophic package is a typed client for the REST API. It has no dependencies, uses the runtime's native fetch and needs Node 20.3 or later.

Install

npm install neurophic

Create a client

import { Neurophic } from 'neurophic';

const client = new Neurophic({
  apiKey: process.env.NEUROPHIC_API_KEY,
  baseURL: 'https://api.neurophic.ai',
  timeout: 10_000,
});
  • apiKey: a project key. Falls back to the NEUROPHIC_API_KEY environment variable; if neither is set the constructor throws.
  • baseURL: where requests go. Defaults to the production API.
  • timeout: milliseconds before the client stops waiting.

Every method takes an optional last argument { signal } to abort a call; your own abort rejects with the runtime's AbortError.

Note

Pass identifier on every call. Keep keys server-side; see Get started > API keys.

Memory

Ingest

Stores a memory. The write is queued, not written on the spot.

const receipt = await client.ingest({
  identifier: 'user-123',
  content: 'Prefers window seats on long flights.',
  name: 'Ada',
  metadata: { topic: 'personal' },
});

Learn more under API reference > Ingest.

Context

Fetches a short, ready-to-prompt summary for a query.

const { result } = await client.context({
  identifier: 'user-123',
  query: 'Booking a flight to Lisbon next month',
});

Learn more under API reference > Context.

Retrieve

Searches memory. The return type follows format.

const { result } = await client.retrieve({
  identifier: 'user-123',
  query: 'travel preferences',
  goal: 'book a flight for the user',
  since: '2026-08-01T00:00:00Z',
  limit: 10,
  format: 'json',
});

Learn more under API reference > Retrieve.

List

Pages through every memory stored for an identifier, newest first.

const page = await client.memory.list({
  identifier: 'user-123',
  page: 2,
  perPage: 10,
});

Learn more under API reference > List.

Get

Fetches one memory by id.

const memory = await client.memory.get('5f1d2c3e-...', { identifier: 'user-123' });

Learn more under API reference > Get.

Delete

Deletes one memory by id.

await client.memory.delete('5f1d2c3e-...', { identifier: 'user-123' });

Learn more under API reference > Delete.

Errors

Any response outside the 2xx range is thrown as a NeurophicError carrying:

status
number
The HTTP status; 0 for timeouts and connection failures.
code
string
The API error code, for example VALIDATION_ERROR; see API reference > Errors. UNKNOWN when the body is not the standard envelope, for example a plain-text 413 from the edge.
message
string
The API message.
details
{ field, message }[]
The field-level problems on a VALIDATION_ERROR.
balance, required
number
On INSUFFICIENT_CREDIT: the project's balance and the balance needed before the call is accepted.
retryAfter
number
Seconds until the period resets, from the Retry-After header on 429 responses.
body
unknown
The raw response body, parsed as JSON when possible.

Two subclasses cover failures that never reach the API:

  • NeurophicTimeoutError. The client stopped waiting; the API may still have handled the request.
  • NeurophicConnectionError. A network failure, exposed as cause.

Tip

The client never retries; add your own backoff if you need it.
import { Neurophic, NeurophicError, NeurophicTimeoutError } from 'neurophic';

const client = new Neurophic();

try {
  await client.ingest({ identifier: 'user-123', content: 'Prefers window seats.' });
} catch (err) {
  if (err instanceof NeurophicTimeoutError) {
    console.error('No reply in time; the write may still go through.');
  } else if (err instanceof NeurophicError) {
    switch (err.code) {
      case 'VALIDATION_ERROR':
        console.error(err.message, err.details);
        break;
      case 'REQUEST_LIMIT_REACHED':
      case 'WRITE_LIMIT_REACHED':
        console.error(`Allowance used. Retry after ${err.retryAfter} seconds.`);
        break;
      case 'INSUFFICIENT_CREDIT':
        console.error(`Balance ${err.balance}, required ${err.required}. Top up the project.`);
        break;
      default:
        console.error(err.status, err.code, err.message);
    }
  } else {
    throw err;
  }
}

Licence

The SDK is MIT-licensed; use of the API it calls is governed by the Terms of Use.

Delete

Learn about how to delete a memory

Vercel AI SDK

Easily integrate memory into your models with the Vercel AI SDK