@memesh/sdk

Official TypeScript SDK for MeMesh Cloud.

MeMesh Cloud is a project workspace system: a tenant/account can own or join many workspaces, and each workspace is an independent project boundary for memory, agents, roadmap/progress, runs, approvals, and artifacts.

Status: Alpha. Create an account at memesh.ai/en/signup, then create an API key from your account settings (or run npx @memesh/cloud setup for the device-flow sign-in used by the MCP server).

Related packages: @memesh/cloud (the MeMesh Cloud MCP server, built on this SDK) and @pcircle/memesh (the local open-source MeMesh memory server — no cloud account required).

Installation

npm install @memesh/sdk

Usage

import { MeMesh } from "@memesh/sdk";

const client = new MeMesh({ apiKey: process.env.MEMESH_API_KEY });
const projectId = "00000000-0000-4000-8000-000000000123";

const remoteTarget = await client.agents.registerRemoteDispatchTarget({
  projectId,
  agentCardUrl: "https://remote-agent.example.com/.well-known/agent-card.json",
  category: "research",
  roleName: "Research target",
  capabilityTags: ["research", "summarize"],
});

const source = await client.projects.registerKnowledgeSource(projectId, {
  sourceType: "obsidian",
  displayName: "Story Vault",
  sourcePath: "Short Stories/Mara",
  readOnly: true,
});

const syncRequest = await client.projects.requestSourceSync(
  projectId,
  source.id,
  {
    reason: "Refresh story bible before planning the next chapter",
  },
);

const postingSchedule = await client.schedules.create({
  projectId,
  name: "Daily story update draft",
  cronExpression: "0 9 * * 1-5",
  taskDescription: "Draft the next project-scoped story update",
  agentType: "writer",
});

const queue = await client.projects.listClaimableSourceSyncRuns({
  projectId,
  sourceType: "obsidian",
  limit: 10,
});

const overview = await client.projects.getCoordinationOverview({ limit: 12 });
for (const project of overview.projects) {
  console.log(
    project.name,
    project.role,
    project.roadmap.progressPercent,
    project.runtime.pendingApprovalCount,
    project.sources.unhealthySourceCount,
  );
}

const claimedSync = await client.projects.claimSourceSyncRun(
  projectId,
  source.id,
  queue.syncRuns[0]?.id ?? syncRequest.id,
  {
    claimToken: "connector-generated-token",
    workerId: "obsidian-worker-1",
  },
);

await client.projects.importSourceDocuments(projectId, source.id, {
  syncRunId: claimedSync.id,
  claimToken: "connector-generated-token",
  documents: [
    {
      sourcePath: "Short Stories/Mara/character-bible.md",
      externalRevision: "mtime:2026-05-27T08:00:00Z",
      contentHash: "sha256:...",
      syncCursor: "cursor_abc",
      content: "Character bible: Mara never uses first-person narration.",
      tags: ["story-bible", "character"],
    },
  ],
  status: "completed",
  syncCursor: "cursor_abc",
});

Remote A2A registration uses the canonical project dispatch-target path. The SDK validates through the server's Agent Card and reachability flow, then binds the target to exactly one project workspace.

client.projects.getCoordinationOverview() is the SDK contract for multi-workspace command-center status. It returns owned and joined project workspaces with roadmap progress, task counts, assigned project agent role gaps, pending approvals, runtime artifact counts, project memory counts, and source health in one response.

client.projects.getOperationsReport(projectId) is the auditable selected-project operations report. Its agentRoleRoster entries preserve assigned project agent role binding truth, including provider connection id, provider label, provider status, explicit model, memory mode, capability tags, and verified-provider readiness. SDK callers should use those fields to inspect project role readiness instead of rebuilding provider/model state from agent catalogs or memory manifests.

Source registration, connector authorization readiness, sync requests, caller-provided source imports, worker claim/heartbeat, provenance, and sync-run health are shipped SDK/API contracts. Every ProjectSourceImportResult includes sourceBoundary so SDK consumers can verify the import stayed inside one project workspace, used read-only one-way import semantics, did not write back to the external source, did not propagate source deletions, and required an explicit project id. Use client.projects.updateKnowledgeSourceConnectorAuth() to link sources such as Google Drive to the current user's OAuth connection before sync requests or workers proceed; Google Drive links require the https://www.googleapis.com/auth/drive.readonly scope. A sync request is only queued when the source is not paused and connector authorization is not_required or linked, so clients do not create unclaimable source-sync runs. Repeated requests for a source with a queued or running sync return that in-flight run instead of creating duplicate queue entries. The hosted web setup flow creates that Google OAuth connection through the existing Auth.js Google callback (/api/auth/callback/google), not a separate backend callback. client.projects.processGoogleDriveSourceSyncRun() is the server-side read-only Drive worker path for nested folder listing, incremental cursor filtering, text-compatible export/download, and project-memory import while closing the same syncRunId as completed or failed. client.projects.processObsidianSourceSyncRun() is the local-vault snapshot path: a desktop/local connector submits changed markdown content, frontmatter, tags, and wikilinks while MeMesh Cloud enforces project memory scope and completed-or-failed sync-run closure. client.projects.processLocalMemeshSourceSyncRun() is the local MeMesh snapshot path: a local connector submits selected project memories with source paths, local memory ids, captured times, tags, and metadata for project-scoped import with completed-or-failed sync-run closure. Pass a queued request's syncRequest.id as syncRunId when importing or recording sync health to close that same request; once claimed, terminal writes must include the matching claimToken. MCP connector-processing tools expose terminal source health through runtime.status and expose documents_scanned / documents_imported from processor results or the closed sync-run truth. Bidirectional edits, deletion propagation, and packaged local connector distribution are still separate connector runtime work.

client.schedules.create(), client.schedules.list(), read, update, delete, pause, resume, and trigger calls require projectId so recurring work stays inside one project workspace. Update sends projectId as query scope and omits it from the update body, so the SDK does not move schedule ownership between projects.

client.lessons.create(), client.lessons.list(), read, update, and delete calls require projectId so learned project rules stay inside the selected project workspace. Project members can read lessons through the selected project boundary; update and delete still require ownership of the lesson record.

Module Format: ESM-only

This package is ESM-only ("type": "module" in package.json). It does not ship a CommonJS build.

Plain Node.js require("@memesh/sdk") from CommonJS will throw ERR_REQUIRE_ESM. Use one of:

• ESM import,
• dynamic import() from CommonJS,
• a bundler/transpiler that understands ESM.

Documentation & Support

• Documentation: memesh.ai/docs
• Support: [email protected]

License

MIT