{"_id":"@aivm-brain/sdk","_rev":"2-dc4c3e598da25505fae190c35913e9e4","name":"@aivm-brain/sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@aivm-brain/sdk","version":"0.1.0","keywords":["aivm","brain","memory","sdk","ai"],"author":{"name":"AIVM Network"},"license":"MIT","_id":"@aivm-brain/sdk@0.1.0","maintainers":[{"name":"ashircgpt","email":"ali.ashir@chaingpt.tech"}],"homepage":"https://github.com/AIVMNetwork/aivm-sdk-workspace/tree/main/typescript#readme","bugs":{"url":"https://github.com/AIVMNetwork/aivm-sdk-workspace/issues"},"dist":{"shasum":"70e29648ff360c0fc9ab8e94e6ebf50d651b3b94","tarball":"https://registry.npmjs.org/@aivm-brain/sdk/-/sdk-0.1.0.tgz","fileCount":9,"integrity":"sha512-CT8EEnatOnJsNV6p8WZQmjFuvU5kR3WT/VFzTLh5lNlr9UJMAgj53nFFSCaRak7WzxRRmt8huTE5SwlJ73XKAw==","signatures":[{"sig":"MEUCICwA7115LJk9LrsTZkwTCkWN9sHbI095By8+ECS1iKgtAiEA+ZX3gJX5lVsZ3XCEtcq96Pj9k5v0tT3kC9B1z3T0FIc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":130831},"main":"./dist/index.js","type":"commonjs","types":"./dist/index.d.ts","module":"./dist/index.mjs","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"./package.json":"./package.json"},"gitHead":"a471617e60e5a2847fc9abf96722d0af2d4fd2c8","scripts":{"test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"_npmUser":{"name":"ashircgpt","email":"ali.ashir@chaingpt.tech"},"repository":{"url":"git+https://github.com/AIVMNetwork/aivm-sdk-workspace.git","type":"git","directory":"typescript"},"_npmVersion":"10.9.8","description":"Official TypeScript SDK for the AIVM Brain memory API (add, get, list, update, delete, search memories + ask).","directories":{},"sideEffects":false,"_nodeVersion":"22.22.3","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"msw":"^2.6.0","tsup":"^8.3.0","vitest":"^2.1.0","typescript":"^5.6.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/sdk_0.1.0_1785478116522_0.6227687889339006","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@aivm-brain/sdk","version":"0.1.1","description":"Official TypeScript SDK for the AIVM Brain memory API (add, get, list, update, delete, search memories + ask).","license":"MIT","author":{"name":"AIVM Network"},"homepage":"https://github.com/AIVMNetwork/aivm-sdk-workspace/tree/main/typescript#readme","repository":{"type":"git","url":"git+https://github.com/AIVMNetwork/aivm-sdk-workspace.git","directory":"typescript"},"bugs":{"url":"https://github.com/AIVMNetwork/aivm-sdk-workspace/issues"},"type":"commonjs","sideEffects":false,"engines":{"node":">=18"},"keywords":["aivm","brain","memory","sdk","ai"],"main":"./dist/index.js","module":"./dist/index.mjs","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.mts","default":"./dist/index.mjs"},"require":{"types":"./dist/index.d.ts","default":"./dist/index.js"}},"./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"devDependencies":{"@types/node":"^20.14.0","msw":"^2.6.0","tsup":"^8.3.0","typescript":"^5.6.0","vitest":"^2.1.0"},"_id":"@aivm-brain/sdk@0.1.1","gitHead":"a471617e60e5a2847fc9abf96722d0af2d4fd2c8","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-7FV4qw/bttF5mkzPIvvRwP64qPTiA5ePO4zW3nKtKwDIEzJg+b+EAMG6/i7PzUYVBeJRnQT7i32zEsgH+WOBmQ==","shasum":"644ad42c6f2889d2ad390241bf8d737317cbc213","tarball":"https://registry.npmjs.org/@aivm-brain/sdk/-/sdk-0.1.1.tgz","fileCount":9,"unpackedSize":142447,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCsmQfalPnxspKFsn7QQFlPs2QDbFBz0R6faHZkwPpuswIhAK8Vz+WV/RwjtBnuhpq/+Vr5c0rswIswdO8rB1HRc4M0"}]},"_npmUser":{"name":"ashircgpt","email":"ali.ashir@chaingpt.tech"},"directories":{},"maintainers":[{"name":"ashircgpt","email":"ali.ashir@chaingpt.tech"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.1_1785488165060_0.21588995778999998"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-31T06:08:36.360Z","modified":"2026-07-31T08:56:05.393Z","0.1.0":"2026-07-31T06:08:36.667Z","0.1.1":"2026-07-31T08:56:05.201Z"},"bugs":{"url":"https://github.com/AIVMNetwork/aivm-sdk-workspace/issues"},"author":{"name":"AIVM Network"},"license":"MIT","homepage":"https://github.com/AIVMNetwork/aivm-sdk-workspace/tree/main/typescript#readme","keywords":["aivm","brain","memory","sdk","ai"],"repository":{"type":"git","url":"git+https://github.com/AIVMNetwork/aivm-sdk-workspace.git","directory":"typescript"},"description":"Official TypeScript SDK for the AIVM Brain memory API (add, get, list, update, delete, search memories + ask).","maintainers":[{"name":"ashircgpt","email":"ali.ashir@chaingpt.tech"}],"readme":"# @aivm-brain/sdk\n\nOfficial **TypeScript SDK** for the [AIVM Brain](https://aivm.io) memory API — add, get, list,\nupdate, delete, and search memories (plus `ask`) with simple typed methods instead of hand-written\nHTTP. Zero runtime dependencies; ships dual **ESM + CommonJS** with type declarations.\n\n> **Server-side only.** An `ak_live_…` agent key grants full access to your memories. Never embed it\n> in a browser or mobile app — use the SDK from a server, function, or job.\n\n## Install\n\n```bash\nnpm install @aivm-brain/sdk\n```\n\nRequires **Node.js ≥ 18** (uses the built-in global `fetch`).\n\n## Authentication\n\nCreate an `ak_live_` agent key in the AIVM dashboard and provide it either explicitly or via the\n`AIVM_API_KEY` environment variable (preferred — keys should not be hard-coded):\n\n```ts\nimport { AivmBrain } from \"@aivm-brain/sdk\";\n\n// Reads AIVM_API_KEY (and optionally AIVM_BASE_URL) from the environment.\nconst brain = new AivmBrain();\n\n// …or pass it explicitly.\nconst brain2 = new AivmBrain({ apiKey: process.env.AIVM_API_KEY });\n```\n\nIf no key can be resolved, the constructor throws a `ConfigurationError`.\n\n### Client options\n\n| Option       | Default                                             | Description                                             |\n| ------------ | --------------------------------------------------- | ------------------------------------------------------ |\n| `apiKey`     | `process.env.AIVM_API_KEY`                          | Agent API key (`ak_live_…`).                           |\n| `tenantId`   | –                                                   | Workspace id for tenant-scoped keys (`x-tenant-id`).   |\n| `baseUrl`    | `process.env.AIVM_BASE_URL` → `https://brain-be.dev.aivm.io` | API base URL. Override for a self-hosted brain. |\n| `timeout`    | `30000`                                             | Timeout in ms for CRUD calls (add/get/list/update/delete). |\n| `retrievalTimeout` | `120000`                                      | Timeout in ms for `search` and `ask` — see below.      |\n| `maxRetries` | `2`                                                 | Retry attempts for idempotent GETs.                    |\n| `fetch`      | global `fetch`                                      | Custom fetch implementation (testing / proxies).       |\n\n### Why `search` and `ask` get their own timeout\n\nThey are not lookups. Both run retrieval **plus answer synthesis** server-side — the brain embeds\nyour question, retrieves, and has a model write the answer — and the backend allows itself ~120s to\ndo it. Putting them on the 30s CRUD timeout made the SDK hang up on requests the server was still\nworking on, which surfaced as:\n\n```json\n{ \"type\": \"APITimeoutError\", \"code\": \"timeout\", \"status\": null }\n```\n\n`status: null` is the tell — no HTTP response ever arrived, because the client aborted first. If\nyour brain is slower still, raise `retrievalTimeout`; CRUD stays fast either way.\n\n## Quickstart\n\n```ts\nimport { AivmBrain } from \"@aivm-brain/sdk\";\n\nconst brain = new AivmBrain({ apiKey: process.env.AIVM_API_KEY });\n\n// Create (or topic-upsert) a memory.\nconst memory = await brain.memories.add({\n  title: \"Q3 Budget\",\n  body: \"The Q3 engineering budget is two million dollars.\",\n  domain: \"finance\",\n});\n\n// Semantic search.\nconst { items, answer } = await brain.memories.search({ query: \"budget\", topK: 5 });\n\n// Fetch, update, delete.\nconst one = await brain.memories.get(memory.id);\nawait brain.memories.update(memory.id, { body: \"Updated body.\" });\nawait brain.memories.delete(memory.id);\n\n// Grounded question answering.\nconst result = await brain.ask({ question: \"What is the engineering budget?\" });\nconsole.log(result.answer);\n```\n\n### Methods\n\n| Method                                              | HTTP                       | Returns                             |\n| --------------------------------------------------- | -------------------------- | ----------------------------------- |\n| `memories.add({ title, body, domain?, topic? })`    | `POST /v1/memories`        | `Memory`                            |\n| `memories.get(id)`                                  | `GET /v1/memories/{id}`    | `Memory`                            |\n| `memories.list({ limit?, cursor?, domain? })`       | `GET /v1/memories`         | `Page<Memory>` = `{ items, nextCursor }` |\n| `memories.listAll({ domain? })`                     | iterates `list`            | `AsyncIterableIterator<Memory>`     |\n| `memories.update(id, { title?, body?, domain? })`   | `PATCH /v1/memories/{id}`  | `Memory`                            |\n| `memories.delete(id)`                               | `DELETE /v1/memories/{id}` | `{ id }`                            |\n| `memories.search({ query, topK? })`                 | `POST /v1/memories/search` | `{ items: SearchHit[], answer }`    |\n| `ask({ question, sessionId? })`                     | `POST /v1/ask`             | `AskResponse`                       |\n\nReusing a `topic` on `add` performs an idempotent **upsert** of that memory instead of creating a new\none.\n\n## Pagination\n\n`list` returns one page. `nextCursor` is an opaque string, or `null` on the last page. Pass it back as\n`cursor` to page manually, or let `listAll` follow it for you:\n\n```ts\n// Manual paging.\nlet cursor: string | undefined;\ndo {\n  const page = await brain.memories.list({ cursor, limit: 50 });\n  for (const m of page.items) process(m);\n  cursor = page.nextCursor ?? undefined;\n} while (cursor);\n\n// Or iterate everything transparently.\nfor await (const memory of brain.memories.listAll()) {\n  process(memory);\n}\n```\n\n## Error handling\n\nEvery failure is an `AivmError` (or subclass) carrying `.status` (number | null), `.code` (string),\n`.requestId` (string | null), and a `.message`.\n\n```ts\nimport {\n  AivmError,\n  AuthenticationError,\n  NotFoundError,\n  RateLimitError,\n  ValidationError,\n} from \"@aivm-brain/sdk\";\n\ntry {\n  await brain.memories.get(\"does-not-exist\");\n} catch (err) {\n  if (err instanceof NotFoundError) {\n    // 404\n  } else if (err instanceof AuthenticationError) {\n    // 401 — bad/missing key\n  } else if (err instanceof AivmError) {\n    console.error(err.code, err.status, err.requestId, err.message);\n  }\n}\n```\n\n| Status        | `code`              | Class                    |\n| ------------- | ------------------- | ------------------------ |\n| 400, 422      | `invalid_request`   | `ValidationError`        |\n| 401           | `unauthorized`      | `AuthenticationError`    |\n| 402           | `payment_required`  | `PaymentRequiredError`   |\n| 403           | `forbidden`         | `PermissionError`        |\n| 404           | `not_found`         | `NotFoundError`          |\n| 409           | `conflict`          | `ConflictError`          |\n| 413           | `payload_too_large` | `PayloadTooLargeError`   |\n| 429           | `rate_limited`      | `RateLimitError`         |\n| 5xx           | `server_error`      | `ServerError`            |\n| — (network)   | `unreachable`       | `APIConnectionError`     |\n| — (timeout)   | `timeout`           | `APITimeoutError`        |\n| — (no key)    | `configuration`     | `ConfigurationError`     |\n\nWhen the server returns a validation error with multiple messages, they are joined with `\"; \"`.\n\n### Retries & timeout\n\nOnly **idempotent reads** (`memories.get`, `memories.list`) are auto-retried, on `429` / `5xx` /\nnetwork / timeout, with jittered exponential backoff (base ~0.5s, `maxRetries` = 2 by default). A\n`Retry-After` header on a `429` is honored. Writes (`add` / `update` / `delete` / `search` / `ask`)\nare **never** auto-retried, so a transient failure can't double-write. Each request times out after\n`timeout` ms (default 30s).\n\n## Tenancy\n\nFor a tenant-scoped key, pass the workspace id — it is sent as the `x-tenant-id` header and verified\nagainst the key server-side. Omit it for personal keys.\n\n```ts\nconst brain = new AivmBrain({ apiKey: process.env.AIVM_API_KEY, tenantId: \"ws_123\" });\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}