Memsy
Memsy

API Reference

Sub-resources

orgs, roles, teams, and memories — sub-resources on the Node MemsyClient.

MemsyClient exposes four sub-resources for the onboarding hierarchy and console memory browsing. They behave identically to the Python equivalents — same endpoints, same parameter shapes, with camelCased field names and Promise<T> returns.

import { MemsyClient } from '@memsy-io/memsy';

const client = new MemsyClient({
  baseUrl: process.env.MEMSY_BASE_URL!,
  apiKey: process.env.MEMSY_API_KEY!,
});

client.orgs;       // OrgsResource
client.roles;      // RolesResource
client.teams;      // TeamsResource
client.memories;   // MemoriesResource

Most onboarding mutation endpoints (create/update/regenerate/delete) are admin-gated. Non-admin keys raise MemsyAuthorizationError.

client.orgs

await client.orgs.list();                                              // Org[]
await client.orgs.create(orgId, name, focus);                          // Org
await client.orgs.get(orgId);                                          // Org
await client.orgs.update(orgId, { name, focus, promotionPrompt });     // Org
await client.orgs.regeneratePrompt(orgId);                             // Org
await client.orgs.delete(orgId);                                       // void
MethodSignature
list()Promise<Org[]>
create(orgId, name, focus)Promise<Org>
get(orgId)Promise<Org>
update(orgId, update)Promise<Org> — OrgUpdate
regeneratePrompt(orgId)Promise<Org>
delete(orgId)Promise<void>

OrgUpdate is { name?, focus?, promotionPrompt? }.

client.roles

Roles always require an orgId.

await client.roles.list(orgId, { limit, offset });                              // Role[]
await client.roles.create(orgId, name, focus);                                  // Role
await client.roles.get(roleId, orgId);                                          // Role
await client.roles.update(roleId, orgId, { name, focus, promotionPrompt });     // Role
await client.roles.regeneratePrompt(roleId, orgId);                             // Role
await client.roles.delete(roleId, orgId);                                       // void

client.teams

Same shape as roles — every method takes an orgId.

await client.teams.list(orgId, { limit, offset });                              // Team[]
await client.teams.create(orgId, name, focus);                                  // Team
await client.teams.get(teamId, orgId);                                          // Team
await client.teams.update(teamId, orgId, { name, focus, promotionPrompt });     // Team
await client.teams.regeneratePrompt(teamId, orgId);                             // Team
await client.teams.delete(teamId, orgId);                                       // void

client.memories

Read-only console memory browsing.

await client.memories.list({                                  // MemoryListResponse
  actorId: 'user_42',                                         // filter to a single actor
  kind: 'semantic',
  type: 'preference',
  status: 'active',
  sort: 'observed_at_desc',
  search: 'dark mode',
  limit: 50,
  offset: 0,
});
await client.memories.stats();                                // MemoryStatsResponse
await client.memories.get(memoryId);                          // MemoryItem

Pagination is stable across pages: the server always sorts with memory_id as a secondary tiebreaker, so walking offset won't return duplicates or skip records.

MethodSignature
list(options?)Promise<MemoryListResponse> — MemoryListOptions
stats()Promise<MemoryStatsResponse>
get(memoryId)Promise<MemoryItem>

MemoryListOptions is { kind?, type?, status?, sort?, search?, limit?, offset? }.

client.actors

Read-only listing of the actors that have memories in the org.

await client.actors.list(undefined, {                         // ActorListResponse
  sort: 'first_memory_desc',                                  // default
  q: 'slack',                                                 // substring on actorId
  limit: 100,
  offset: 0,
});
await client.actors.get('user_42');                           // Actor

Actors are derived by folding the org's memories on actor_id at read time, not stored — so there is no create/rename/delete. limit/offset page the deduped actor list, so total is the org's full distinct-actor count.

MethodSignature
list(orgId?, options?)Promise<ActorListResponse> — ActorListOptions
get(actorId, orgId?)Promise<Actor>

ActorListOptions is { limit?, offset?, sort?, q? }; sort is ActorSort — one of 'first_memory_desc', 'first_memory_asc', 'last_memory_desc', 'actor_id_asc'. Both orgId arguments default to the caller's org.

firstMemoryAt and lastMemoryAt are the min/max of the memories' created_at — named for the memories because that is what they measure. lastMemoryAt is not a "last used" signal; it only advances when a new memory is written.

Check page.truncated: when set, the server hit its row-scan cap, so the list may be incomplete and every memoryCount is an under-count. That is also why there is no sort by memory count.

See also