wontopos 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wontopos
+
+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.

package/README.md

@@ -0,0 +1,57 @@
+# Wontopos — long-term memory for AI agents
+
+```bash
+npm install wontopos
+```
+
+```ts
+import { Client } from "wontopos";
+
+const mem = new Client({ apiKey: "wos-..." });
+await mem.add("she prefers tea over coffee", "alice");
+
+// one call → short-term + long-term + context, ready for your LLM prompt
+const ctx = await mem.recall("what does alice drink?", "alice");
+```
+
+## Why
+
+- **Pure semantic retrieval** — no keyword/BM25. Identical recall in every language (한국어 · 日本語 · 中文 · English).
+- **No LLM in the loop** — `store` / `search` / `recall` never call a language model. You pay embeddings, not generation.
+- **Bounded retrieval** — `recall()` returns a small, fixed-size slice (~1,200 tokens) regardless of how much you've stored.
+
+## Methods
+
+`add` · `addTurn` · `addBulk` · `update` · `search` · `recall` · `history` · `stats` · `delete` · `deleteAll`
+
+All methods take `{ userId }`. Memories are isolated per user, then per account.
+
+## Errors
+
+```ts
+import { Client, WosError } from "wontopos";
+
+try {
+  await mem.search("...", "alice");
+} catch (e) {
+  if (e instanceof WosError) {
+    if (e.status === 401) console.error("API key invalid or revoked");
+    else if (e.status === 429) console.error("Rate limited");
+    else console.error(e.status, e.message);
+  }
+}
+```
+
+## Self-host
+
+```ts
+const mem = new Client({ apiKey: "...", baseUrl: "https://wos.your-host.com" });
+```
+
+## Links
+
+- Homepage: <https://wontopos.com>
+- API reference: <https://wontopos.com/why> (Developers tab)
+- Repo: <https://github.com/Irina1920/Wos_API>
+
+License: MIT.

package/dist/wontopos.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Wontopos — long-term memory for AI, in three lines.
+ *
+ *   npm install wontopos
+ *
+ *   import { Client } from "wontopos";
+ *   const mem = new Client({ apiKey: "wos-..." });
+ *   await mem.add("she prefers tea over coffee", "alice");
+ *   const hits = await mem.search("what does alice drink?", "alice");
+ *
+ * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
+ * language. Storing and searching call no LLM; you only pay for embeddings.
+ */
+export declare class WosError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export interface Memory {
+    id?: string;
+    content?: string;
+    score?: number;
+    [key: string]: unknown;
+}
+export interface RecallResult {
+    short_term: {
+        turns: unknown[];
+        count: number;
+    };
+    long_term: {
+        memories: Memory[];
+        count: number;
+    };
+    context: {
+        around_top_memory: unknown[];
+        count: number;
+    };
+    [key: string]: unknown;
+}
+export interface ClientOptions {
+    apiKey: string;
+    /** API base URL (defaults to the hosted service). */
+    baseUrl?: string;
+    /** Per-request timeout in ms (default 30000). */
+    timeoutMs?: number;
+}
+/** Wontopos memory client. Store and recall memories, isolated per `userId`. */
+export declare class Client {
+    private readonly base;
+    private readonly headers;
+    private readonly timeoutMs;
+    constructor(opts: ClientOptions);
+    /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }). */
+    add(content: string, userId: string, metadata?: Record<string, unknown>): Promise<any>;
+    /** Store a conversation turn (user + assistant) into short-term + long-term memory. */
+    addTurn(userId: string, userMsg: string, assistantMsg: string): Promise<any>;
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
+    addBulk(content: string, userId: string, category?: string, timestamp?: string): Promise<any>;
+    /** Supersede an old memory with new content (a fact that changed). */
+    update(userId: string, oldMemoryId: string, newContent: string): Promise<any>;
+    /** Semantic search over a user's memories. Returns memories, most relevant first. */
+    search(query: string, userId: string, limit?: number, opts?: Record<string, unknown>): Promise<Memory[]>;
+    /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
+    recall(query: string, userId: string): Promise<RecallResult>;
+    /** Recent conversation turns (short-term memory). */
+    history(userId: string): Promise<unknown[]>;
+    /** Memory counts for a user: { total_memories, short_term_turns }. */
+    stats(userId: string): Promise<any>;
+    /** Delete a single memory by id. */
+    delete(userId: string, memoryId: string): Promise<any>;
+    /** Delete ALL memories for a user (GDPR erase). */
+    deleteAll(userId: string): Promise<any>;
+    private post;
+}
+/** Back-compat alias: older code used `WME`. */
+export declare const WME: typeof Client;
+export default Client;

package/dist/wontopos.js

@@ -0,0 +1,127 @@
+/**
+ * Wontopos — long-term memory for AI, in three lines.
+ *
+ *   npm install wontopos
+ *
+ *   import { Client } from "wontopos";
+ *   const mem = new Client({ apiKey: "wos-..." });
+ *   await mem.add("she prefers tea over coffee", "alice");
+ *   const hits = await mem.search("what does alice drink?", "alice");
+ *
+ * Pure semantic retrieval — no keyword/BM25 matching, so it works the SAME in every
+ * language. Storing and searching call no LLM; you only pay for embeddings.
+ */
+const DEFAULT_BASE_URL = "https://api.wontopos.com";
+export class WosError extends Error {
+    status;
+    constructor(status, message) {
+        super(`[${status}] ${message}`);
+        this.name = "WosError";
+        this.status = status;
+    }
+}
+/** Wontopos memory client. Store and recall memories, isolated per `userId`. */
+export class Client {
+    base;
+    headers;
+    timeoutMs;
+    constructor(opts) {
+        if (!opts?.apiKey)
+            throw new Error("apiKey is required");
+        this.base = (opts.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+        this.headers = { "X-API-Key": opts.apiKey, "Content-Type": "application/json" };
+    }
+    // ----- write -----
+    /** Store one memory. `metadata` optional (e.g. { event_date: "2026-03-01" }). */
+    add(content, userId, metadata = {}) {
+        return this.post("/api/v1/memory/store", { user_id: userId, content, metadata });
+    }
+    /** Store a conversation turn (user + assistant) into short-term + long-term memory. */
+    addTurn(userId, userMsg, assistantMsg) {
+        return this.post("/api/v1/memory/store-turn", { user_id: userId, user_msg: userMsg, assistant_msg: assistantMsg });
+    }
+    /** Bulk-ingest a large blob of text (chunked + embedded server-side). For backfilling. */
+    addBulk(content, userId, category = "general", timestamp) {
+        const body = { user_id: userId, content, category };
+        if (timestamp)
+            body.timestamp = timestamp;
+        return this.post("/api/v1/memory/bulk-store", body);
+    }
+    /** Supersede an old memory with new content (a fact that changed). */
+    update(userId, oldMemoryId, newContent) {
+        return this.post("/api/v1/memory/supersede", { user_id: userId, old_memory_id: oldMemoryId, new_content: newContent });
+    }
+    // ----- read -----
+    /** Semantic search over a user's memories. Returns memories, most relevant first. */
+    async search(query, userId, limit = 10, opts = {}) {
+        const r = await this.post("/api/v1/memory/search", { user_id: userId, query, max_results: limit, ...opts });
+        return (r.memories ?? []);
+    }
+    /** One-call LLM context: short-term turns + long-term matches + surrounding context. */
+    recall(query, userId) {
+        return this.post("/api/v1/memory/recall", { user_id: userId, query });
+    }
+    /** Recent conversation turns (short-term memory). */
+    async history(userId) {
+        const r = await this.post("/api/v1/memory/history", { user_id: userId });
+        return (r.turns ?? []);
+    }
+    /** Memory counts for a user: { total_memories, short_term_turns }. */
+    stats(userId) {
+        return this.post("/api/v1/memory/stats", { user_id: userId });
+    }
+    // ----- delete -----
+    /** Delete a single memory by id. */
+    delete(userId, memoryId) {
+        return this.post("/api/v1/memory/forget", { user_id: userId, memory_id: memoryId });
+    }
+    /** Delete ALL memories for a user (GDPR erase). */
+    deleteAll(userId) {
+        return this.post("/api/v1/memory/forget", { user_id: userId });
+    }
+    // ----- internal -----
+    async post(path, body) {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await fetch(`${this.base}${path}`, {
+                method: "POST",
+                headers: this.headers,
+                body: JSON.stringify(body),
+                signal: ctrl.signal,
+            });
+        }
+        catch (e) {
+            throw new WosError(0, `network error: ${e.message}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!res.ok) {
+            // Server returns either Anthropic-style envelope
+            //   {"type":"error","error":{"type":...,"message":...,"request_id":...}}
+            // or simple {"error":"reason"}. Fall back to raw text.
+            let msg = await res.text();
+            try {
+                const data = JSON.parse(msg);
+                if (data && typeof data === "object") {
+                    const err = data.error;
+                    if (err && typeof err === "object")
+                        msg = err.message ?? err.type ?? msg;
+                    else if (typeof err === "string")
+                        msg = err;
+                    else if (typeof data.message === "string")
+                        msg = data.message;
+                }
+            }
+            catch { /* keep raw text */ }
+            throw new WosError(res.status, msg);
+        }
+        return res.json();
+    }
+}
+/** Back-compat alias: older code used `WME`. */
+export const WME = Client;
+export default Client;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "wontopos",
+  "version": "2.0.0",
+  "description": "Wontopos — long-term memory for AI agents. Pure semantic retrieval, identical recall in every language, ~100× lower LLM bill.",
+  "keywords": [
+    "memory",
+    "ai",
+    "agent",
+    "llm",
+    "vector",
+    "embedding",
+    "semantic",
+    "rag",
+    "context"
+  ],
+  "homepage": "https://wontopos.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Irina1920/Wos_API.git",
+    "directory": "sdk/typescript"
+  },
+  "bugs": {
+    "url": "https://github.com/Irina1920/Wos_API/issues"
+  },
+  "license": "MIT",
+  "author": "Wontopos",
+  "type": "module",
+  "main": "./dist/wontopos.js",
+  "module": "./dist/wontopos.js",
+  "types": "./dist/wontopos.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/wontopos.d.ts",
+      "import": "./dist/wontopos.js",
+      "default": "./dist/wontopos.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0"
+  }
+}