@cilow/sdk 0.2.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,201 @@
-MIT License
-
-Copyright (c) 2024 Cilow AI
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Generalized Labs
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,322 +1,152 @@
-# @cilow/sdk
+# @cilow/sdk — TypeScript
 
-TypeScript/JavaScript SDK for the Cilow AI Agent Platform - Production-ready memory system for AI agents with unlimited context.
+The TypeScript client for **Cilow**, the verifiable context layer for AI agents. Point it at
+a running [`cilow-serve`](../../docs/user_guide/mcp_server.md) and call **four core verbs** —
+`ingest`, `contextPack`, `forget`, `explain` — the same four the MCP core profile advertises.
+The headline feature is **calibrated deferral**: every read tells you when the engine
+*doesn't know* instead of fabricating an answer.
 
-## Features
+## Install
 
-- **Semantic Memory Storage** - Store and retrieve memories using vector embeddings
-- **Multi-tier Storage** - Hot/Warm/Cold tiers with automatic optimization
-- **Tag-based Organization** - Organize memories with flexible tagging
-- **Full-text + Semantic Search** - Hybrid search combining BM25 and embeddings
-- **Knowledge Graph** - Entity extraction and relationship mapping
-- **Multi-tenant Support** - User isolation for secure multi-user apps
-- **TypeScript First** - Full type safety with comprehensive types
-
-## Installation
-
-```bash
-npm install @cilow/sdk
-# or
-yarn add @cilow/sdk
-# or
-pnpm add @cilow/sdk
-```
-
-## Quick Start
-
-```typescript
-import { CilowClient } from '@cilow/sdk';
-
-// Initialize with API key
-const client = new CilowClient({
-  apiKey: 'cilow_your_api_key',
-  baseUrl: 'https://api.cilow.ai', // or your self-hosted URL
-});
-
-// Add a memory
-const { memoryId } = await client.addMemory({
-  content: 'User prefers TypeScript over JavaScript for backend development',
-  tags: ['preference', 'programming', 'backend'],
-});
-
-// Search memories semantically
-const results = await client.searchMemories({
-  query: 'What programming languages does the user prefer?',
-  limit: 5,
-});
-
-console.log(results);
-// [
-//   {
-//     memoryId: 'mem_xxx',
-//     content: 'User prefers TypeScript over JavaScript...',
-//     similarity: 0.92,
-//     score: 0.18,
-//     tags: ['preference', 'programming', 'backend']
-//   }
-// ]
+```sh
+# From this repo (no registry publish yet):
+cd sdk/typescript && npm install && npm run build
+# In your app, depend on the built package or vendor `dist/`.
 ```
 
-## Authentication
+Node 18+ (uses the global `fetch`). Zero runtime dependencies.
 
-### API Key Authentication (Recommended for backends)
+## Point it at a server
 
-```typescript
-const client = new CilowClient({
-  apiKey: 'cilow_your_api_key',
-});
+```sh
+cargo build --profile fast --features serve --bin cilow-serve
+CILOW_DB=/tmp/cilow.log CILOW_TOKENS="demo:1:1" ./target/fast/cilow-serve
+# listening on http://0.0.0.0:8080  ·  bearer token "demo"
 ```
 
-### JWT Authentication (For frontend apps)
+The token maps to a tenant scope that the server **stamps** onto every request — a client can
+never read another tenant's memory, and a client-supplied `scope` is ignored over HTTP.
 
-```typescript
-const client = new CilowClient({
-  baseUrl: 'https://api.cilow.ai',
-});
+## Five lines
 
-// Login to get access token
-const auth = await client.login('user@example.com', 'password');
-console.log(`Logged in as: ${auth.user.email}`);
+```ts
+import { CilowClient, isGrounded } from "@cilow/sdk";
 
-// Token is automatically set for subsequent requests
+const cilow = new CilowClient({ baseUrl: "http://localhost:8080", token: "demo" });
+await cilow.ingest({ facts: [{ subject: "Maya", predicate: "employer", object: "Acme" }] });
+const r = await cilow.contextPack("where does Maya work", { anchor: "Maya", attribute: "employer" });
+console.log(r.abstained ? `don't know: ${r.reason}` : r.pack); // the injectible pack; citations on r.citations
+console.log(isGrounded(await cilow.explain(r.trace_id!)));     // why it surfaced, vs the tenant threshold
 ```
 
-## Memory Operations
-
-### Add Memory
-
-```typescript
-const { memoryId } = await client.addMemory({
-  content: 'Meeting notes: Q4 planning discussed roadmap priorities',
-  tags: ['meeting', 'planning', 'q4'],
-  metadata: {
-    source: 'meeting-notes',
-    date: '2024-01-15',
-  },
-});
-```
-
-### Search Memories
-
-```typescript
-// Semantic search
-const results = await client.searchMemories({
-  query: 'What were the Q4 priorities?',
-  limit: 10,
-  minScore: 0.5,
-});
-
-// Search with tag filtering
-const taggedResults = await client.searchMemories({
-  query: 'planning discussions',
-  tags: ['meeting', 'planning'],
-  tagMode: 'all', // 'all' = AND, 'any' = OR
-});
-```
-
-### Update Memory
-
-```typescript
-await client.updateMemory(memoryId, {
-  content: 'Updated content with new information',
-  tags: ['updated', 'important'],
-});
-```
-
-### Delete Memory
-
-```typescript
-await client.deleteMemory(memoryId);
-```
-
-### List Memories
-
-```typescript
-// List all memories
-const memories = await client.listMemories();
-
-// Filter by tier
-const hotMemories = await client.listMemories({
-  tier: 'hot',
-  limit: 50,
-  offset: 0,
-});
-```
-
-### Get Statistics
-
-```typescript
-const stats = await client.getMemoryStats();
-console.log(stats);
-// {
-//   totalMemories: 1500,
-//   hotTier: 200,
-//   warmTier: 800,
-//   coldTier: 500,
-//   totalTokens: 45000,
-//   avgSalience: 0.65
-// }
-```
+## The four core verbs
 
-## Tag Management
+| Verb | Signature | Returns | What it does |
+|------|-----------|---------|--------------|
+| `ingest` | `ingest({ facts } \| { text } \| { url } \| { contentBase64, mime? }, opts?)` | `IngestResponse` | The **one write door**. Never rejects: known kinds extract, unknown kinds are retained and recallable. A new value for an exclusive attribute *supersedes* the old one (history stays queryable). |
+| `contextPack` | `contextPack(query: string, opts?)` | `ContextPackResponse` | The **product read**: a ready-to-inject `pack`, structured `citations` / `claims` with `is_current`, and the faithfulness fields `abstained` / `reason_code` / `grounding` / `pack_sufficient` / `as_of` / `trace_id`. No free-form synthesis. |
+| `forget` | `forget(entity: string, opts?)` | `ForgetResponse` | **Withdraw**, not erase history: recall stops returning it; as-of-T reads before `at` still see it. `{ erase: true }` (or `erase()`) is the destructive right-to-be-forgotten path. |
+| `explain` | `explain(traceId: number, opts?)` | `ExplainResponse` | **Why** a pack/recall surfaced what it surfaced: the cited claims (labels resolved, inclusion probability each), `best_nonconformity` vs the tenant threshold `q_hat`, and `isGrounded(r)`. `found: false` + `error` is in-band. |
 
-```typescript
-// Add tags to a memory
-await client.addTags(memoryId, ['important', 'follow-up']);
+Plus `health()` (liveness probe, no auth).
 
-// Remove tags
-await client.removeTags(memoryId, ['follow-up']);
+### Options
 
-// Replace all tags
-await client.setTags(memoryId, ['new-tag-set']);
+- `ingest`: `{ scope?, sourceId?, observedAt?, source?, rawContext?, branch?, subjectHint?, metadata? }` —
+  `source` / `rawContext` / `branch` apply to the facts form; `subjectHint` / `metadata` to text / url / bytes.
+- `contextPack`: `{ scope?, now?, asOf?, anchor?, attribute? }`
+- `forget`: `{ scope?, attribute?, value?, erase?, at? }`
+- `explain`: `{ scope? }`
 
-// Filter memories by tags
-const tagged = await client.filterByTags(['important'], 'any');
+`ingest` takes **exactly one** content form. `sourceId` (the idempotency key the wire requires)
+defaults to a **content hash** — `ingestSourceId(content)` — so re-sending the same payload is a
+no-op; the key actually sent is echoed on `source_id`. `kind` tells you which server path ran
+(`"facts"` → the `remember` receipt on `remember`; `"content"` → the raw-durable receipt on
+`content` with `blob_id` / `detected` / `reader_error`).
 
-// List all tags with counts
-const allTags = await client.listAllTags();
+`anchor` (an entity surface form like `"Maya"`) + `attribute` (a predicate like `"employer"`)
+take the exact-key **fast path**. Omit them for free-text semantic reads — same response shape.
 
-// Get tag statistics
-const tagStats = await client.getTagStats();
-```
+### Full profile / legacy aliases
 
-## Agent Operations
+The engine's full tool profile (`CILOW_MCP_PROFILE=full`) also advertises the older verbs, and
+the client keeps them as aliases with their original receipts:
 
-```typescript
-// Create an agent
-const agentId = await client.createAgent({
-  name: 'research-assistant',
-  model: 'gpt-4',
-  systemPrompt: 'You are a helpful research assistant.',
-});
+| Alias | Signature | Returns |
+|-------|-----------|---------|
+| `remember` | `remember(facts: Fact[], { scope?, source?, sourceId?, observedAt?, rawContext?, branch? })` | `RememberResponse` (write receipt) |
+| `recall` | `recall(query: string, { scope?, asOf?, now?, anchor?, attribute?, branch? })` | `RecallResponse` (`abstained`, `claims`, `receipt`) |
+| `answer` | `answer(query: string, { scope?, now?, anchor?, attribute?, branch? })` | `AnswerResponse` (`abstained`, `text`, `citations`) |
+| `timeline` | `timeline(entity: string, { scope?, at?, from?, to? })` | `TimelineEntry[]` (bitemporal history) |
+| `trackEntity` | `trackEntity(name: string, { scope?, at? })` | `TrackEntityResponse` (canonical id + alias class) |
 
-// Execute a task
-const result = await client.executeTask(agentId, {
-  task: 'Summarize the key points from recent meetings',
-  context: 'User is preparing for Q1 planning',
-});
+Also available: `rememberText`, `ingestImage` / `ingestAudio` / `ingestPdf` / `ingestStructured`,
+`save` / `ingestAny`, `feedback`, `consolidate`, `fork` / `branchList`, `blobGet` / `blobMeta` /
+`blobList`, and the `cilow.memories.*` id-based REST surface (also exposed to frameworks via
+`@cilow/sdk/adapters`).
 
-// Get agent status
-const agent = await client.getAgent(agentId);
+### Time is in microseconds
 
-// List all agents
-const agents = await client.listAgents();
+Every time field (`observedAt`, `asOf`, `now`, `at`, `from`, `to`, and the `valid_from` /
+`valid_until` on timeline entries) is **epoch microseconds (µs)**, matching the engine. They all
+default to "now" (`Date.now() * 1000`). Use the exported `nowMicros()` helper if you need it:
 
-// Delete agent
-await client.deleteAgent(agentId);
+```ts
+import { nowMicros } from "@cilow/sdk";
+const t = nowMicros();
+await cilow.remember(facts, { observedAt: t });
+const past = await cilow.recall("...", { asOf: t - 86_400_000_000, now: t }); // a day ago
 ```
 
-## API Key Management
-
-```typescript
-// Create a new API key
-const apiKey = await client.createApiKey({
-  name: 'Production API Key',
-  expiresAt: new Date('2025-01-01'),
-});
+## The deferral contract
 
-// List API keys
-const keys = await client.listApiKeys();
+`contextPack` (and the `recall` / `answer` aliases) **never throw** for a deferral — they return
+a normal response with a boolean flag. When `abstained` is `true`, the pack / claims / citations
+are empty and `reason_code` says why: `below_threshold` / `no_candidates` are a *calibrated*
+abstain (memory genuinely lacks grounded context — do not fabricate past it), while
+`provider_unavailable` is an *infrastructure* abstain (retry when the provider recovers). Branch
+with `isCalibratedAbstain(r)` / `isInfrastructureAbstain(r)` rather than matching strings.
 
-// Revoke an API key
-await client.revokeApiKey(keyId);
+On `answer` / `contextPack` an abstain also names **which layer stopped it** — `r.terminal_layer`
+(`structural` | `gate` | `provider` | `reader` | `verifier`; `stoppedAt(r)` is the same thing gated on
+`abstained`). Only `provider` is retryable. Both surfaces also carry `r.evidence`: the claim, span,
+and verbatim lanes collapsed into one list ordered by fused cross-lane rank (`Evidence.origins`
+says which lanes agreed; `Evidence.structure` is present when a typed claim backs the unit). It is
+present on abstains too — the raw lanes have no standing at the gate, but you may still read them.
 
-// Delete an API key
-await client.deleteApiKey(keyId);
+```ts
+const r = await cilow.contextPack("what is Maya's salary", { anchor: "Maya", attribute: "salary" });
+if (r.abstained) {
+  // r.pack is empty; r.reason explains the configured gate decision.
+  return `I don't have that in memory (${r.reason}).`;
+}
+return r.pack;
 ```
 
-## Session Management
+Every read carries a `trace_id`. Hand it to `explain` for the audit trail — the cited claims,
+the tenant's conformal threshold `q_hat`, the best candidate's `best_nonconformity` (grounded iff
+`n ≤ q̂`, see `isGrounded`) — or to `feedback` so memory learns from the outcome. This is the
+difference between "I don't know" and a confident wrong answer.
 
-```typescript
-// List active sessions
-const sessions = await client.listSessions();
+## Errors
 
-// Revoke a specific session
-await client.revokeSession(sessionId);
-
-// Revoke all other sessions
-await client.revokeOtherSessions();
-
-// Revoke all sessions (logout everywhere)
-await client.revokeAllSessions();
-```
-
-## Error Handling
-
-```typescript
-import {
-  CilowError,
-  AuthenticationError,
-  NotFoundError,
-  RateLimitError
-} from '@cilow/sdk';
+`CilowError` is thrown for genuine failures — auth (`401` / JSON-RPC `-32001`), bad params,
+transport errors, malformed responses. A deferral is not an error.
 
+```ts
+import { CilowError } from "@cilow/sdk";
 try {
-  await client.searchMemories({ query: 'test' });
-} catch (error) {
-  if (error instanceof AuthenticationError) {
-    console.error('Invalid API key');
-  } else if (error instanceof NotFoundError) {
-    console.error('Resource not found');
-  } else if (error instanceof RateLimitError) {
-    console.error('Rate limited, retry later');
-  } else if (error instanceof CilowError) {
-    console.error(`API error: ${error.message}`);
-  }
+  await cilow.recall("...");
+} catch (e) {
+  if (e instanceof CilowError && e.isUnauthorized) { /* bad/expired token */ }
 }
 ```
 
-## Configuration Options
-
-```typescript
-const client = new CilowClient({
-  // API base URL (default: http://localhost:8080)
-  baseUrl: 'https://api.cilow.ai',
-
-  // API key for authentication
-  apiKey: 'cilow_your_api_key',
-
-  // JWT access token (alternative to API key)
-  accessToken: 'eyJhbGc...',
+## Develop
 
-  // Request timeout in milliseconds (default: 30000)
-  timeout: 60000,
-});
+```sh
+npm install
+npm run build     # tsc → dist/
+npm test          # node:test — client + adapters suites, mocks the HTTP layer (no server needed)
+npm run example   # runs examples/quickstart.ts against a live server
 ```
-
-## Types
-
-All types are fully exported for TypeScript users:
-
-```typescript
-import type {
-  Memory,
-  MemoryStats,
-  SearchResult,
-  Agent,
-  User,
-  ApiKey,
-  AddMemoryOptions,
-  SearchMemoriesOptions,
-} from '@cilow/sdk';
-```
-
-## Self-Hosting
-
-Cilow can be self-hosted. Point the SDK to your instance:
-
-```typescript
-const client = new CilowClient({
-  baseUrl: 'http://localhost:8080',
-  apiKey: 'your-local-api-key',
-});
-```
-
-## Requirements
-
-- Node.js >= 18.0.0
-- ES2020+ or modern browser with fetch support
-
-## License
-
-MIT