Memsy
Memsy

API Reference

MemsyClient

Synchronous HTTP client — constructor, methods, parameters, exceptions.

Synchronous HTTP client for the Memsy API.

from memsy import MemsyClient

Constructor

MemsyClient(
    base_url: str,
    api_key: str,
    timeout: float = 30.0,
    max_retries: int = 3,
    retry_backoff: float = 1.0,
)
ParameterTypeDefaultDescription
base_urlstr—Memsy API base URL, e.g. "https://api.memsy.io/v1". Trailing slashes are trimmed.
api_keystr—API key of the form msy_.... Sent as Authorization: Bearer <key>.
timeoutfloat30.0Request timeout in seconds. Covers connect + read + write.
max_retriesint3Max automatic retries on HTTP 429.
retry_backofffloat1.0Base exponential backoff in seconds between 429 retries.

Context manager

with MemsyClient(base_url="...", api_key="***") as client:
    client.health()

Methods

ingest(events)

Ingest a batch of events.

ingest(events: list[EventPayload]) -> IngestResponse
ParameterTypeDescription
eventslist[EventPayload]Events to ingest. Same order is preserved in the response.

Returns: IngestResponse with event_ids, plus optional usage / rate_limit.

Raises: AuthenticationError, AuthorizationError, FeatureNotAvailable, RateLimitExceeded, UsageLimitExceeded, MemsyConnectionError, MemsyAPIError.

search(query, *, actor_id, limit, threshold, include_source_events)

Retrieve memories via semantic search.

search(
    query: str,
    *,
    actor_id: str | None = None,
    limit: int = 10,
    threshold: float = 0.0,
    include_source_events: bool = False,
) -> SearchResponse
ParameterTypeDefaultDescription
querystr—Natural-language query.
actor_idstr | NoneNoneFilter results to a single actor.
limitint10Maximum number of results.
thresholdfloat0.0Minimum similarity score. 0.0 = no filter. See Threshold guidance.
include_source_eventsboolFalseInclude source events in each result.

Returns: SearchResponse with results: list[SearchResult], plus optional usage / rate_limit.

status(event_ids)

status(event_ids: list[str]) -> StatusResponse
ParameterTypeDescription
event_idslist[str]Event IDs returned from a prior ingest() call.

Returns: StatusResponse with completed_ids, failed_ids, pending_ids, total.

health()

health() -> HealthResponse

Returns: HealthResponse with status, version, and optionally billing_enabled and components.

clear(container_tag)

clear(container_tag: str) -> ClearResponse
ParameterTypeDescription
container_tagstrContainer/conversation tag to clear.

Warning

Currently a stub. The server returns 501 Not Implemented until a real actor-scoped delete is wired up; calling clear() will raise MemsyAPIError. Avoid calling it in production paths. Track the SDK CHANGELOG for the implementation announcement.

Returns (when implemented): ClearResponse with deleted (count of cleared items).

close()

Close the underlying HTTP connection pool. Called automatically by the context manager.

close() -> None

Sub-resource accessors

MemsyClient exposes three onboarding sub-resources and a console-memory sub-resource. Each is a thin accessor that delegates to the same underlying HTTP client.

client.orgs

CRUD for org customization records. See Onboarding.

client.orgs.list() -> list[OrgResource]
client.orgs.create(org_id, name, focus) -> OrgResource
client.orgs.get(org_id) -> OrgResource
client.orgs.update(org_id, *, name=None, focus=None, promotion_prompt=None) -> OrgResource
client.orgs.regenerate_prompt(org_id) -> OrgResource
client.orgs.delete(org_id) -> None

client.roles

CRUD for role customization records within an org. The server assigns role_id — it is returned in the response, not supplied at creation.

client.roles.list(org_id) -> list[RoleResource]
client.roles.create(org_id, name, focus) -> RoleResource
client.roles.get(role_id, org_id) -> RoleResource
client.roles.update(role_id, org_id, *, name=None, focus=None, promotion_prompt=None) -> RoleResource
client.roles.regenerate_prompt(role_id, org_id) -> RoleResource
client.roles.delete(role_id, org_id) -> None

client.teams

CRUD for team customization records within an org. The server assigns team_id — it is returned in the response, not supplied at creation.

client.teams.list(org_id) -> list[TeamResource]
client.teams.create(org_id, name, focus) -> TeamResource
client.teams.get(team_id, org_id) -> TeamResource
client.teams.update(team_id, org_id, *, name=None, focus=None, promotion_prompt=None) -> TeamResource
client.teams.regenerate_prompt(team_id, org_id) -> TeamResource
client.teams.delete(team_id, org_id) -> None

client.memories

Browse and inspect stored memories. See Console Memories.

client.memories.list(
    *,
    actor_id: str | None = None,  # filter to a single actor's memories
    kind: str | None = None,
    type: str | None = None,
    status: str | None = None,
    sort: str = "observed_at_desc",
    search: str | None = None,
    limit: int = 50,
    offset: int = 0,
) -> MemoryListResponse

client.memories.get(memory_id: str) -> MemoryItemResource
client.memories.stats() -> MemoryStatsResponse

Pagination is stable across pages: every sort includes memory_id as a secondary tiebreaker, so walking offset won't return duplicates or skip records.

Thread safety

A MemsyClient wraps an httpx.Client, which is safe to share across threads for HTTP calls. Create one client per process and reuse it.

See also