TypeScript SDK - MemContext

memcontext-sdk is the official TypeScript SDK for the MemContext public API. It is a small typed wrapper around the REST API with API key auth, scope/project helpers, typed responses, and normalized API errors.

Install

npm install memcontext-sdk

Quickstart

import { MemContextClient } from "memcontext-sdk";

const client = new MemContextClient({
  apiKey: process.env.MEMCONTEXT_API_KEY!,
});

const userMemory = client.withScope("user_123");
const projectMemory = userMemory.withProject("memcontext");

await projectMemory.save({
  content: "User prefers concise release notes",
  category: "preference",
});

const results = await projectMemory.search({
  query: "How should release notes be written?",
});

Use withScope() for the hard end-user or tenant boundary. Use withProject() only as a grouping filter inside that scope.

Client Setup

const client = new MemContextClient({
  apiKey: process.env.MEMCONTEXT_API_KEY!,
  baseUrl: "https://api.memcontext.in",
  scope: "user_123",
  project: "memcontext",
});

Option	Required	Description
`apiKey`	Yes	MemContext API key from the dashboard.
`baseUrl`	No	API base URL. Defaults to `https://api.memcontext.in`.
`scope`	No	Default hard isolation boundary for this client instance.
`project`	No	Default project grouping inside the selected scope.
`fetch`	No	Custom fetch implementation for tests or custom runtimes.

Scope Helpers

`withScope(scope)`

Creates a new client with a default scope. Use this when one API key serves multiple app users, workspaces, organizations, or tenants.

const userMemory = client.withScope("user_123");

`withProject(project)`

Creates a new client with a default project. Projects are soft grouping filters inside the current scope.

const projectMemory = userMemory.withProject("memcontext");

Methods

`save(request, options?)`

Saves durable memory. MemContext automatically handles embeddings, deduplication, relationship classification, and versioning. Larger notes may be accepted for asynchronous extraction into atomic memories.

await client.save({
  content: "User prefers TypeScript over JavaScript",
  category: "preference",
  scope: "user_123",
  project: "memcontext",
});

Returns a save result with status set to saved, updated, extended, duplicate, or accepted. When status is accepted, the response includes a jobId and message for tracking extraction into atomic memories.

`search(request)`

Searches memories using hybrid retrieval. Use full natural-language questions for best results.

const results = await client.search({
  query: "What language does the user prefer?",
  limit: 5,
  threshold: 0.6,
});

Returns { found, memories }, where each memory includes content, category, scope, project, relevance, and createdAt as a Date.

`list(request?)`

Lists current non-deleted memories with pagination and filters.

const page = await client.list({
  limit: 20,
  offset: 0,
  category: "fact",
  search: "release notes",
});

Returns { memories, total, hasMore }.

`get(memoryId, options?)`

Fetches one memory by ID. Pass scope when retrieving scoped memories from a base client.

const memory = await client.get("memory-id", {
  scope: "user_123",
});

`update(memoryId, request, options?)`

Updates memory content, category, or project. Content updates may create relations or supersede related memories.

await client.update(
  "memory-id",
  { content: "User now prefers concise changelogs" },
  { scope: "user_123" },
);

`delete(memoryId, options?)`

Removes a memory from future search and list results.

await client.delete("memory-id", {
  scope: "user_123",
});

`forget(memoryId, options?)`

Endpoint-parity alias for delete(). Prefer delete() unless you specifically want the /forget response shape.

await client.forget("memory-id", {
  scope: "user_123",
});

`feedback(memoryId, request, options?)`

Records retrieval quality feedback. Feedback helps improve future ranking.

await client.feedback(
  "memory-id",
  {
    type: "helpful",
    context: "This memory answered the user's question directly.",
  },
  { scope: "user_123" },
);

Feedback type can be helpful, not_helpful, outdated, or wrong.

`history(memoryId, options?)`

Returns the current memory and previous versions in its version chain.

const history = await client.history("memory-id", {
  scope: "user_123",
});

`profile(options?)`

Returns pre-aggregated profile context split into stable and recent memory.

const profile = await client.profile({
  scope: "user_123",
  project: "memcontext",
});

Returns { static, dynamic }.

`graph(options?)`

Returns graph visualization data for memories in the selected scope.

const graph = await client.graph({
  scope: "user_123",
});

Returns { nodes, links, meta }.

`health(signal?)`

Checks API health.

const health = await client.health();

Workspace Methods

Context Vault uses workspaces for shared knowledge. These methods require an API key or dashboard session that belongs to the user.

`listWorkspaces()`

Lists workspaces the current user belongs to.

const { workspaces } = await client.listWorkspaces();

`createWorkspace(request)`

Creates a workspace and assigns the current user as owner.

const { workspace } = await client.createWorkspace({
  name: "Acme Support",
});

`inviteWorkspaceMember(workspaceId, request)`

Sends an email invitation for another workspace member. Roles can be admin, member, or viewer. The user is added only after accepting the invite.

const invite = await client.inviteWorkspaceMember(workspace.id, {
  email: "teammate@example.com",
  role: "member",
});

`listWorkspaceTeam(workspaceId)`

Lists current members and pending invitations.

const team = await client.listWorkspaceTeam(workspace.id);

`updateWorkspaceMember(workspaceId, memberId, request)`

Updates a member role. Owners cannot be changed through this method.

await client.updateWorkspaceMember(workspace.id, memberId, {
  role: "viewer",
});

`removeWorkspaceMember(workspaceId, memberId)`

Removes a non-owner member from the workspace.

await client.removeWorkspaceMember(workspace.id, memberId);

`revokeWorkspaceInvitation(workspaceId, invitationId)`

Revokes a pending invitation before it is accepted.

await client.revokeWorkspaceInvitation(workspace.id, invitationId);

`acceptWorkspaceInvitation(request)`

Accepts a workspace invitation token.

await client.acceptWorkspaceInvitation({
  token: "invitation-token",
});

Context Vault Methods

Context Vault methods let you add documents, list processing status, search workspace knowledge, and collect feedback from your app.

`ingestContextVaultDocument(request, options?)`

Adds extracted text, a public file URL, or a documentation URL to a workspace.

await client.ingestContextVaultDocument({
  workspaceId: workspace.id,
  title: "Product docs",
  uri: "https://docs.example.com",
  sourceType: "url",
  crawlSubpages: true,
  priorityPageLimit: 15,
  subpageTarget: ["api", "guides"],
});

For docs sites with llms.txt, MemContext uses the page map and ingests only the top-priority pages. priorityPageLimit defaults to 15 and is capped at 25. For public file URLs, pass the file type so the document can be parsed correctly:

await client.ingestContextVaultDocument({
  workspaceId: workspace.id,
  title: "Security report",
  uri: "https://example.com/security-report.pdf",
  sourceType: "pdf",
});

`uploadContextVaultDocument(request, options?)`

Uploads a local file and adds it to Context Vault.

await client.uploadContextVaultDocument({
  workspaceId: workspace.id,
  title: "Employee handbook",
  file,
  filename: "handbook.pdf",
  sourceType: "pdf",
});

`listContextVaultDocuments(workspaceId, options?)`

Lists workspace documents and their current status.

const docs = await client.listContextVaultDocuments(workspace.id);

`cancelContextVaultDocument(documentId, options?)`

Stops a pending, retrying, or active document job.

await client.cancelContextVaultDocument("document-id");

`deleteContextVaultDocument(documentId, options?)`

Deletes the document, chunks, citations, and any extracted memories that are only backed by that document.

await client.deleteContextVaultDocument("document-id");

`createContextVaultMemory(request, options?)`

Adds a curated company fact to a workspace. Use this for important company context that is not documented yet.

await client.createContextVaultMemory({
  workspaceId: workspace.id,
  content: "Refund discounts are not offered after the trial period ends.",
  scope: "billing",
  project: "pricing",
  category: "fact",
});

`deleteContextVaultMemory(workspaceId, memoryId, options?)`

Deletes a curated company fact from a workspace. Document-extracted memories are removed by deleting their source document when they are not backed by any other document.

await client.deleteContextVaultMemory(workspace.id, "memory-id");

`searchContextVault(request, options?)`

Searches workspace knowledge in documents, memories, or hybrid mode.

const results = await client.searchContextVault({
  workspaceId: workspace.id,
  query: "How do refunds work?",
  mode: "hybrid",
  limit: 8,
});

// Source passages from files/docs.
console.log(results.chunks);

// Extracted atomic facts and curated company facts.
console.log(results.memories);

Hybrid mode keeps chunks[] and memories[] separate. For answer generation, pass chunks[] as source document context and convert memories[] into a second memory-context document. Curated company facts use memoryType: "company" and may return with evidence: [].

`listContextVaultMemories(request, options?)`

Browses extracted workspace memories.

const page = await client.listContextVaultMemories({
  workspaceId: workspace.id,
  limit: 20,
  search: "refund",
});

`listContextVaultDocumentMemories(workspaceId, documentId, options?)`

Lists memories extracted from one document.

const extracted = await client.listContextVaultDocumentMemories(
  workspace.id,
  "document-id",
);

`submitContextVaultMemoryFeedback(memoryId, request, options?)`

Records feedback on an extracted workspace memory.

await client.submitContextVaultMemoryFeedback("memory-id", {
  workspaceId: workspace.id,
  type: "helpful",
});

`listContextVaultMemoryEvidence(workspaceId, memoryId, options?)`

Loads source chunks for an extracted memory.

const evidence = await client.listContextVaultMemoryEvidence(
  workspace.id,
  "memory-id",
);

`getContextVaultHierarchy(workspaceId, options?)`

Returns scope/project counts for workspace memories.

const hierarchy = await client.getContextVaultHierarchy(workspace.id);

Error Handling

Failed API responses throw MemContextApiError.

import { MemContextApiError } from "memcontext-sdk";

try {
  await client.get("missing-id");
} catch (error) {
  if (error instanceof MemContextApiError) {
    console.error(error.status, error.code, error.message);
  }
}

​Install

​Quickstart

​Client Setup

​Scope Helpers

​withScope(scope)

​withProject(project)

​Methods

​save(request, options?)

​search(request)

​list(request?)

​get(memoryId, options?)

​update(memoryId, request, options?)

​delete(memoryId, options?)

​forget(memoryId, options?)

​feedback(memoryId, request, options?)

​history(memoryId, options?)

​profile(options?)

​graph(options?)

​health(signal?)

​Workspace Methods

​listWorkspaces()

​createWorkspace(request)

​inviteWorkspaceMember(workspaceId, request)

​listWorkspaceTeam(workspaceId)

​updateWorkspaceMember(workspaceId, memberId, request)

​removeWorkspaceMember(workspaceId, memberId)

​revokeWorkspaceInvitation(workspaceId, invitationId)

​acceptWorkspaceInvitation(request)

​Context Vault Methods

​ingestContextVaultDocument(request, options?)

​uploadContextVaultDocument(request, options?)

​listContextVaultDocuments(workspaceId, options?)

​cancelContextVaultDocument(documentId, options?)

​deleteContextVaultDocument(documentId, options?)

​createContextVaultMemory(request, options?)

​deleteContextVaultMemory(workspaceId, memoryId, options?)

​searchContextVault(request, options?)

​listContextVaultMemories(request, options?)

​listContextVaultDocumentMemories(workspaceId, documentId, options?)

​submitContextVaultMemoryFeedback(memoryId, request, options?)

​listContextVaultMemoryEvidence(workspaceId, memoryId, options?)

​getContextVaultHierarchy(workspaceId, options?)

​Error Handling

​Links