{"name":"@withmemory/sdk","version":"0.1.0","baseUrl":"https://api.withmemory.dev","install":"npm install @withmemory/sdk","repository":"https://github.com/withmemory-dev/withmemory","docs":{"skill":"https://withmemory.dev/SKILL.md","agents":"https://withmemory.dev/agents","llms":"https://withmemory.dev/llms.txt","readme":"https://github.com/withmemory-dev/withmemory/blob/main/packages/sdk/README.md","apiReference":"https://github.com/withmemory-dev/withmemory/blob/main/packages/sdk/API.md"},"scope":{"description":"Arbitrary stable string that partitions memories into an isolated namespace.","constraints":{"minLength":1,"maxLength":255,"encoding":"UTF-8"},"patterns":[{"pattern":"user-{id}","useCase":"per-user memory (the classic)"},{"pattern":"project-{slug}","useCase":"facts about a project or codebase"},{"pattern":"research-{session-id}","useCase":"facts gathered during a research task"},{"pattern":"ticket-{id}","useCase":"context for a specific support / issue thread"},{"pattern":"self","useCase":"the agent's own persistent state"}]},"preAuth":[{"method":"memory.requestCode","signature":"({ email }) => Promise<{ result: { sent: boolean } }>","description":"Send a 6-digit verification code to an email. Pre-auth — no configure() required."},{"method":"memory.verifyCode","signature":"({ email, code, issuedTo? }) => Promise<{ result: { apiKey, accountId, isNewAccount } }>","description":"Exchange the 6-digit code for an API key. `issuedTo` labels the key (shown via whoami). Pre-auth."},{"method":"memory.cache.create","signature":"({ ttlSeconds? }) => Promise<CacheInstance>","description":"Create a temporary key-value cache with no account. 24-hour TTL. Rate-limited 3/IP/24h. Pre-auth."}],"core":[{"method":"memory.add","signature":"({ scope, key, value, importance? }) => Promise<AddResponse>","description":"Store a fact directly under a known key. importance in [0, 1] biases ranking (default 0.5). Explicit path — no LLM extraction.","requires":["memory:write"]},{"method":"memory.add","signature":"({ scope, value }) => Promise<AddResponse>","description":"Extract and store durable facts from free-form text. LLM picks out what's worth remembering. Extraction path — no `key`.","requires":["memory:write"]},{"method":"memory.recall","signature":"({ scope, query, threshold?, maxItems?, maxTokens?, defaults? }) => Promise<RecallResponse>","description":"Return a prompt-ready `context` string ranked by relevance. threshold: strict | balanced | permissive (default balanced).","requires":["memory:read"],"returns":"{ context: string; memories: Memory[]; ranking: { strategy, reason? } }"},{"method":"memory.get","signature":"({ scope, key }) => Promise<{ memory: Memory | null }>","description":"Retrieve a single memory by scope and key.","requires":["memory:read"]},{"method":"memory.list","signature":"({ scope?, source?, search?, ...pagination }) => Promise<ListResponse>","description":"Enumerate memories under a scope or the entire account. Supports cursor pagination, source filter, date ranges.","requires":["memory:read"]},{"method":"memory.remove","signature":"({ scope, key }) => Promise<{ result: { deleted: boolean } }>","description":"Delete a memory by (scope, key).","requires":["memory:write"]},{"method":"memory.delete","signature":"(memoryId) => Promise<{ result: { deleted: boolean } }>","description":"Delete a memory by ID.","requires":["memory:write"]},{"method":"memory.whoami","signature":"() => Promise<WhoamiResponse>","description":"Return account metadata and key scopes. Useful for self-checking what you can do.","requires":["memory:read"]},{"method":"memory.usage","signature":"() => Promise<UsageResponse>","description":"Current quota usage — memory count, memory limit, container count, container limit.","requires":["memory:read"]},{"method":"memory.health","signature":"() => Promise<HealthResponse>","description":"Service status check (authenticated).","requires":["memory:read"]},{"method":"memory.register","signature":"(defaults) => void","description":"Client-side defaults injected into recall context for unknown scopes (fallback facts when no memories exist)."}],"extractionPrompt":[{"method":"memory.setExtractionPrompt","signature":"(prompt: string) => Promise<ExtractionPromptResponse>","description":"Override the LLM extraction prompt for your account. Applies to all extraction-path add() calls.","requires":["account:admin","plan:pro+"]},{"method":"memory.getExtractionPrompt","signature":"() => Promise<ExtractionPromptResponse>","description":"Read the current extraction prompt (default or custom).","requires":["memory:read"]},{"method":"memory.resetExtractionPrompt","signature":"() => Promise<{ result: { reset: true } }>","description":"Reset the extraction prompt to the server default.","requires":["account:admin","plan:pro+"]}],"containers":[{"method":"memory.containers.create","signature":"({ name, metadata? }) => Promise<CreateContainerResponse>","description":"Provision an isolated memory namespace with its own quota and audit trail.","requires":["account:admin","plan:pro+"]},{"method":"memory.containers.createKey","signature":"({ containerId, issuedTo, scopes?, expiresIn? }) => Promise<CreateContainerKeyResponse>","description":"Mint a scoped credential for a container. `issuedTo` is a required audit label. `scopes` defaults to `memory:read,memory:write`.","requires":["account:admin","plan:pro+"]},{"method":"memory.containers.list","signature":"() => Promise<ListContainersResponse>","description":"List all containers under the authenticated account.","requires":["account:admin","plan:pro+"]},{"method":"memory.containers.get","signature":"({ containerId }) => Promise<GetContainerResponse>","description":"Get container details.","requires":["account:admin","plan:pro+"]},{"method":"memory.containers.revokeKey","signature":"({ containerId, keyId }) => Promise<RevokeContainerKeyResponse>","description":"Revoke a container key (soft revocation).","requires":["account:admin","plan:pro+"]},{"method":"memory.containers.delete","signature":"({ containerId, confirm: true }) => Promise<DeleteContainerResponse>","description":"Delete a container and all memories inside.","requires":["account:admin","plan:pro+"]}],"cache":[{"method":"cache.set","signature":"({ key, value }) => Promise<CacheSetResponse>","description":"Store a key/value entry inside a cache. Up to 50 entries per cache."},{"method":"cache.get","signature":"({ key }) => Promise<{ entry: CacheEntry | null }>","description":"Read a single entry."},{"method":"cache.delete","signature":"({ key }) => Promise<{ result: { deleted: boolean } }>","description":"Remove one entry."},{"method":"cache.list","signature":"() => Promise<CacheListResponse>","description":"Enumerate the cache's keys."},{"method":"memory.cache.claim","signature":"({ claimToken }) => Promise<CacheClaimResponse>","description":"Promote a cache into persistent memory under a new container. Response returns `scope` and `containerKey` (read-only, shown once). All plan tiers.","requires":["account:admin"]}],"requestOptions":{"timeout":{"type":"number","unit":"milliseconds","default":60000},"maxRetries":{"type":"number","default":3},"signal":{"type":"AbortSignal","description":"Cancel an in-flight request."},"idempotencyKey":{"type":"string","description":"Sets the Idempotency-Key header. Use on add() retries to prevent duplicate extraction."}},"errors":[{"code":"unauthorized","status":401,"description":"Missing or invalid API key, or account-hierarchy violation."},{"code":"key_expired","status":401,"description":"API key is past its expiresAt."},{"code":"insufficient_scope","status":403,"description":"Key is valid but lacks the scope required by the route. `details.required` and `details.granted` list the specifics.","recovery":["Mint a key with the required scopes via memory.containers.createKey (Pro+).","Re-run verifyCode with a different issuedTo to get a new full-scope key on the parent account."]},{"code":"invalid_request","status":400,"description":"Request body failed validation. `details` contains the Zod issue tree."},{"code":"not_found","status":404,"description":"Resource does not exist or is not visible to this key."},{"code":"quota_exceeded","status":403,"description":"Account memory limit reached (sums parent + all sub-accounts).","recovery":["memory.list() + memory.remove() to prune stale memories.","Re-add duplicates with the same (scope, key) to supersede them.","Upgrade the plan — URL in details.recovery_options."]},{"code":"plan_required","status":403,"description":"Endpoint requires a plan tier the account does not have (most common: account:admin ops require Pro+).","recovery":["Upgrade to Pro or above — URL in details.recovery_options."]},{"code":"container_limit_exceeded","status":403,"description":"Account has reached its plan's container cap.","recovery":["memory.containers.delete existing containers.","Upgrade plan — URL in details.recovery_options."]},{"code":"container_name_exists","status":409,"description":"A container with this name already exists under the parent account."},{"code":"rate_limited","status":429,"description":"Hit a per-IP or per-endpoint rate cap. Retry-After header indicates when to retry."},{"code":"cache_entry_limit","status":403,"description":"Cache has reached its 50-entry cap."},{"code":"cache_expired","status":410,"description":"Cache TTL elapsed — entries are gone."},{"code":"already_claimed","status":409,"description":"Cache has already been claimed. The containerKey was returned in the original claim response and cannot be re-issued. Use POST /v1/containers/{containerId}/keys (Pro+) to mint a new key."},{"code":"extraction_failed","status":500,"description":"LLM extraction pipeline failed (upstream model error)."},{"code":"timeout","status":0,"description":"Client-side: request exceeded the configured timeout. No HTTP round trip."},{"code":"network_error","status":0,"description":"Client-side: fetch failed or response was non-JSON. No HTTP round trip."}],"plans":[{"name":"free","price":"$0 / month","memoryLimit":1000,"monthlyApiCalls":10000,"containers":0,"customExtractionPrompt":false},{"name":"basic","price":"$9 / month","memoryLimit":10000,"monthlyApiCalls":100000,"containers":0,"customExtractionPrompt":false},{"name":"pro","price":"$29 / month","memoryLimit":100000,"monthlyApiCalls":1000000,"containers":10,"customExtractionPrompt":true}],"httpHeaders":{"authorization":"Bearer <api-key>","content-type":"application/json","x-withmemory-client":"Optional. Format `agent-name/version`. Helps the team track reliability by client.","idempotency-key":"Optional. Use on retry-safe writes to prevent duplicates."}}