@memcell/sdk

@memcell/sdk

Official TypeScript and Node.js SDK for MemCell.
Persistent, adaptive memory substrate for AI agents, workflows, and LLM pipelines.

npm install @memcell/sdk

import { MemCell } from "@memcell/sdk";

const memory = new MemCell({
  apiKey: process.env.MEMCELL_API_KEY!,
});

// 1. Recall relevant memories before an agent acts:
const { promptContext } = await memory.recall({
  namespace: "acme/support",
  query: "refund verification and escalation thresholds",
});

console.log(promptContext);
// [directive] Require explicit customer confirmation before applying refunds over $500 (confidence: 0.94)

Core Primitives

1. recall — Query Memory Before Acting

Query verified directives, facts, preferences, and observations using natural language.

const recall = await memory.recall({
  namespace: "acme/support",
  query: "refund verification and escalation thresholds",
});

// promptContext is formatted and ready to drop directly into agent system or user prompts:
console.log(recall.promptContext);

2. remember — Save Memories

Save a verified directive, fact, preference, or observation so future agents inherit it immediately:

await memory.remember({
  namespace: "acme/support",
  title:
    "Require explicit customer confirmation before applying refunds over $500",
  type: "directive",
});

3. report — Close the Feedback Loop

Memory adapts when told what happened. When an agent succeeds or fails after applying memory, report the outcome:

await memory.report({
  namespace: "acme/support",
  memoryId: "mem_019a4b2c",
  outcome: "worked", // "worked" | "failed" | "avoided"
  reason: "Customer verified and refund issued within guidelines",
});

Closed-Loop Execution (wrapExecution)

With wrapExecution, you can wrap any agent action or tool invocation in a self-healing, closed-loop memory:

import { MemCell } from "@memcell/sdk";

const memory = new MemCell({ apiKey: process.env.MEMCELL_API_KEY! });

// Scope memory to your workspace:
const support = memory.scope("acme/support");

async function handleRefund(ticketId: string, amount: number) {
  return await support.wrapExecution(
    {
      action: "process_refund",
      query: "refund verification requirements",
    },
    async (ctx) => {
      // 1. ctx.promptContext automatically contains active memories:
      //    e.g. "[directive] Require explicit customer confirmation before applying refunds over $500"

      // 2. Execute operation with verified context:
      const res = await processRefund(ticketId, amount);

      // 3. Automatically reports "worked" on success (or "failed" on error) and updates confidence scores.
      return res;
    },
  );
}

Resource Namespaces

The SDK provides direct, typed access to all MemCell platform resources:

Memories (memory.memories)

• list(namespace, params): Paginated query with filtering by type, status, scope, q, sort.
• get(namespace, id): Retrieve an individual memory.
• create(namespace, params): Create a memory (directive, fact, preference, observation).
• update(namespace, id, params): Update memory content, status, confidence, or metadata.
• delete(namespace, id): Delete a memory.
• star(namespace, id, starred): Star or unstar a memory.
• history(namespace, id): Retrieve complete version and mutation history.
• adopt(namespace, id, { targetWorkspaceIds }): Adopt a memory into other workspaces.
• promote(namespace, id, { toScope, reason }): Promote a provisional memory to active.

Workspaces (memory.workspaces)

• list(params): List caller's accessible workspaces.
• listForOwner(owner, params): List workspaces belonging to an owner.
• get(namespace): Retrieve workspace details.
• create(params): Create a new workspace.
• update(namespace, params): Update workspace properties.
• delete(namespace): Delete a workspace.
• transfer(namespace, { targetOwner }): Transfer workspace ownership.

Agents (memory.agents)

• list(namespace, params): List agents registered in a workspace.
• get(namespace, agentId): Retrieve agent details.
• create(namespace, params): Register an agent.
• update(namespace, agentId, params): Update agent configuration.
• delete(namespace, agentId): Deregister an agent.
• createKey(namespace, agentId, params): Generate a scoped agent API key.
• revokeKey(namespace, agentId, keyId): Revoke an agent key.

Collaborators (memory.collaborators)

• list(namespace, params): List workspace collaborators and pending invitations.
• invite(namespace, { identifier, role }): Invite a user or email to collaborate.
• updateRole(namespace, userId, role): Update a collaborator's role.
• remove(namespace, userId): Remove a collaborator.
• revokeInvitation(namespace, invitationId): Revoke an invitation.

Organizations (memory.organizations)

• list(params), get(orgSlug), create(params), update(orgSlug, params), delete(orgSlug)
• listMembers(orgSlug, params), updateMemberRole(orgSlug, userId, role), removeMember(orgSlug, userId)
• listInvitations(orgSlug), inviteMember(orgSlug, params), revokeInvitation(orgSlug, invitationId)

Usage & Quotas (memory.usage)

• get(owner, { timeframe }): Retrieve memory type breakdown and API quotas.

Account (memory.account)

• get(), updateProfile(params)
• tokens.list(), tokens.create(params), tokens.revoke(tokenId)

Scoped Handle (memory.scope(namespace))

Provides convenient namespace-bound access:

• scoped.memories.*, scoped.agents.*, scoped.collaborators.*, scoped.scopes.list()

Machine-to-Machine (M2M) OAuth 2.0

For enterprise and backend microservices, authenticate using client credentials. Tokens are automatically exchanged and refreshed 60 seconds before expiration:

const memory = new MemCell({
  auth: {
    clientId: process.env.MEMCELL_CLIENT_ID!,
    clientSecret: process.env.MEMCELL_CLIENT_SECRET!,
    scope: "memory:read:acme/* memory:write:acme/backend",
  },
});

Built-in 429 Resilience

MemCell automatically handles HTTP 429 rate limits with randomized jittered exponential backoff respecting the server's Retry-After header:

const memory = new MemCell({
  apiKey: process.env.MEMCELL_API_KEY!,
  maxRetries: 3, // default: 3
  onRateLimitWarning: (warning) => {
    // Dual-threshold warning (80-99% capacity) without interrupting execution
    console.warn("Approaching rate limit:", warning.limit);
  },
});

Links

• Documentation: https://memcell.ai/docs
• Developer CLI: npm install -g memcell
• GitHub Repository: https://github.com/memcell-ai/devkit

Apache License 2.0 · © 2026 Memcell, Inc.