Onboarding Hierarchy

Memsy supports a three-level onboarding hierarchy — org → role → team — that controls how memories are scoped and how extraction prompts are customised. Setting this up is optional: the SDKs work fine without it, but adding hierarchy lets you tune extraction for different parts of your user base.

The CRUD operations on this page are exposed in both SDKs via client.orgs, client.roles, and client.teams. Most of these endpoints are admin-gated; non-admin keys will receive a typed AuthorizationError (Python) / MemsyAuthorizationError (Node).

Hierarchy overview

org
├── team   (e.g. "platform team", "enterprise sales")
└── role   (e.g. "frontend engineer", "sales rep")

Roles and teams are independent siblings under an org — a role does not belong to a team in the data model. An actor can be tagged with both a role_id and a team_id at the same time.

What connects them is the memory promotion chain: when memories are promoted up the hierarchy, the path is actor → role → team → org. Each level has its own promotion_prompt that biases extraction for what matters at that scope.

Events tagged with role_id or team_id in EventPayload are extracted with the customised prompt for that role/team.

Accessing the sub-resources

from memsy import MemsyClient

client = MemsyClient(base_url="...", api_key="msy_...")

client.orgs
client.roles
client.teams

Async equivalents are available on AsyncMemsyClient — same methods, all awaited.

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

const client = new MemsyClient({ baseUrl: '...', apiKey: 'msy_...' });

client.orgs;
client.roles;
client.teams;

Every method returns a Promise<T> — Node is async-only.

Orgs

# Create
org = client.orgs.create(
    org_id="my-org",
    name="Acme Inc",
    focus="B2B SaaS company building developer tools",
)
print(org.promotion_prompt)

# List / Get / Update
orgs = client.orgs.list()
org = client.orgs.get("my-org")
org = client.orgs.update("my-org", name="Acme Corp", focus="Updated focus")

# Re-generate the LLM prompt from current name + focus
org = client.orgs.regenerate_prompt("my-org")

# Delete
client.orgs.delete("my-org")

// Create
const org = await client.orgs.create(
  'my-org',
  'Acme Inc',
  'B2B SaaS company building developer tools',
);
console.log(org.promotionPrompt);

// List / Get / Update
const orgs = await client.orgs.list();
const fetched = await client.orgs.get('my-org');
const updated = await client.orgs.update('my-org', {
  name: 'Acme Corp',
  focus: 'Updated focus',
});

// Re-generate the LLM prompt from current name + focus
const regenerated = await client.orgs.regeneratePrompt('my-org');

// Delete
await client.orgs.delete('my-org');

Roles

Roles represent distinct personas or job functions within your org.

role = client.roles.create(
    org_id="my-org",
    name="Backend Engineer",
    focus="Python, distributed systems, Postgres",
)
# role.role_id is assigned by the server

roles = client.roles.list("my-org")
role = client.roles.get(role.role_id, "my-org")
role = client.roles.update(role.role_id, "my-org", focus="Updated focus")
role = client.roles.regenerate_prompt(role.role_id, "my-org")
client.roles.delete(role.role_id, "my-org")

const role = await client.roles.create(
  'my-org',
  'Backend Engineer',
  'Python, distributed systems, Postgres',
);
// role.roleId is assigned by the server

const roles = await client.roles.list('my-org');
const fetched = await client.roles.get(role.roleId, 'my-org');
const updated = await client.roles.update(role.roleId, 'my-org', {
  focus: 'Updated focus',
});
const regenerated = await client.roles.regeneratePrompt(role.roleId, 'my-org');
await client.roles.delete(role.roleId, 'my-org');

Teams

Teams represent groups of actors that share a context.

team = client.teams.create(
    org_id="my-org",
    name="Platform Team",
    focus="Infrastructure, CI/CD, reliability",
)
# team.team_id is assigned by the server

teams = client.teams.list("my-org")
team = client.teams.get(team.team_id, "my-org")
team = client.teams.update(team.team_id, "my-org", name="Platform & Infra")
team = client.teams.regenerate_prompt(team.team_id, "my-org")
client.teams.delete(team.team_id, "my-org")

const team = await client.teams.create(
  'my-org',
  'Platform Team',
  'Infrastructure, CI/CD, reliability',
);
// team.teamId is assigned by the server

const teams = await client.teams.list('my-org');
const fetched = await client.teams.get(team.teamId, 'my-org');
const updated = await client.teams.update(team.teamId, 'my-org', {
  name: 'Platform & Infra',
});
const regenerated = await client.teams.regeneratePrompt(team.teamId, 'my-org');
await client.teams.delete(team.teamId, 'my-org');

Tagging events with role/team

Once the hierarchy is set up, tag events at ingest time. This part works from any SDK or raw HTTP:

from memsy import EventPayload

client.ingest([
    EventPayload(
        actor_id="user_42",
        session_id="session_1",
        kind="user_message",
        content="I prefer to use Rust for performance-critical paths.",
        role_id="role_eng",
        team_id="team_platform",
    )
])

await client.ingest([
  {
    actorId: 'user_42',
    sessionId: 'session_1',
    kind: 'user_message',
    content: 'I prefer to use Rust for performance-critical paths.',
    roleId: 'role_eng',
    teamId: 'team_platform',
  },
]);

curl -X POST "$MEMSY_BASE_URL/ingest" \
  -H "Authorization: Bearer $MEMSY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "actor_id": "user_42",
        "session_id": "session_1",
        "kind": "user_message",
        "content": "I prefer to use Rust for performance-critical paths.",
        "role_id": "role_eng",
        "team_id": "team_platform"
      }
    ]
  }'

The memory extractor uses the role's/team's promotion_prompt to bias extraction toward relevant facts for that context.

Response model

All three sub-resources return shaped objects with the same fields (Python is snake_case, Node is camelCase):

Python	Node	Description
`org_id` / `role_id` / `team_id`	`orgId` / `roleId` / `teamId`	Stable resource ID.
`name`	`name`	Display name.
`focus`	`focus`	Description used to generate the promotion prompt.
`promotion_prompt`	`promotionPrompt`	Auto-generated extraction prompt for this scope.
`created_at` / `updated_at`	`createdAt` / `updatedAt`	ISO-8601 timestamps.
`prompt_meta`	`promptMeta`	Metadata about the prompt generation.

See Python models reference or Node models reference.