memcode-sdk

TypeScript SDK for the Memcode long-term memory API.

Install

npm install memcode-sdk

Usage

Pass the API base URL and API key. Personal v2 identity is derived from the credential, so no username or user_id is needed.

import { MemcodeClient } from "memcode-sdk";

const client = new MemcodeClient(
  "http://localhost:8000",
  process.env.MEMCODE_API_KEY!,
);

const ready = await client.isReady();

await client.ingest({
  user_query: "Hello",
  user_id: "user_42",
});

const answer = await client.retrieve({
  query: "What did we talk about?",
  user_id: "user_42",
});

const hybrid = await client.searchV2({
  query: "What did we discuss?",
  top_k: 10,
  original_top_k: 5,
  include_original_chunks: true,
});

Advanced personal v2

The server derives the personal user from the API key or JWT, so no user_id is needed. The existing client keeps accepting user_id as a deprecated optional compatibility field:

const job = await client.ingestV2({
  user_query: "I now lead the platform team",
  effort_level: "high",
});

const status = await client.getIngestStatusV2(job.job_id);
const results = await client.searchV2({
  query: "platform work",
  top_k: 10,
  original_top_k: 5,
});
const answer = await client.retrieveV2({
  query: "What team do I lead?",
});

Personal searchV2 uses the unified /v2/memory/search endpoint. Stored chunks are returned in the same results array with domain: "original_chunk"; the SDK also exposes them through original_chunks for compatibility. Deprecated hybridSearch delegates to the same endpoint.

Error handling

import {
  MemcodeClient,
  AuthenticationError,
  RateLimitError,
} from "memcode-sdk";

try {
  await client.ingest({ user_query: "test", user_id: "u1" });
} catch (e) {
  if (e instanceof AuthenticationError) {
    console.error(`Auth failed: ${e.message}`);
  } else if (e instanceof RateLimitError) {
    console.error(`Rate limited, retry after ${e.retryAfter}s`);
  }
}

Migrating from 1.x

Version 2.0.0 is a breaking release.

Constructor

Before (1.x):

new MemcodeClient(); // defaults: localhost, no API key
new MemcodeClient(apiUrl);
new MemcodeClient(apiUrl, apiKey);

Optional arguments fell back to process.env.MEMCODE_API_URL, process.env.MEMCODE_API_KEY, and defaults.

Current:

new MemcodeClient(apiUrl, apiKey);
new MemcodeClient(apiUrl, apiKey, username); // deprecated compatibility form

• apiUrl and apiKey are required strings.
• username is optional and deprecated; authenticated credentials determine personal v2 identity.
• Invalid or whitespace-only required values throw Error immediately (before any network call).
• When an existing caller supplies username, it is still included as the legacy X-Memcode-Username header.

Replace previous env-only setups by reading variables yourself and passing them explicitly:

const apiUrl = process.env.MEMCODE_API_URL ?? "http://localhost:8000";
const apiKey = process.env.MEMCODE_API_KEY!;
const client = new MemcodeClient(apiUrl, apiKey);

Apache-2.0 License