@localmem/memory 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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/NOTICE

@@ -0,0 +1,5 @@
+localmem Memory API SDK
+Copyright 2026 Vijay Yadav, doing business as localmem.org.
+
+Licensed under the Apache License, Version 2.0 (LICENSE). "localmem" is a
+name of localmem.org; the licence grants no right to use it (section 6).

package/README.md

@@ -1,3 +1,20 @@
-# Temporary Holding Version
+# @localmem/memory
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The localmem Memory API from TypeScript: memory of each of your customers,
+with the source and date of every fact. Server-side only.
+
+```sh
+npx @localmem/memory login     # pair this terminal: approve the code in the browser
+npm install @localmem/memory
+```
+
+```ts
+import { Memory } from "@localmem/memory";
+
+const lm = new Memory(); // reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID, LOCALMEM_KEY_SECRET
+const { tenant } = await lm.customers.create("cust-42");
+await lm.documents.send(tenant, { text: "Ada Byron joined Acme on 3 March." });
+console.log((await lm.recall(tenant, { entity: "Ada Byron" })).facts);
+```
+
+Docs: https://localmem.org/docs/memory-api/sdks · Support: support@localmem.org

package/dist/bin.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+// The `npx @localmem/memory` entry point (specs/037 R53).
+import { main } from "./cli.js";
+main().catch((e) => {
+    console.error(e instanceof Error ? e.message : e);
+    process.exit(1);
+});

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+export interface Args {
+    command: string | undefined;
+    envFile: string;
+    device: string;
+    api: string;
+    browser: boolean;
+}
+export declare function parse(argv: string[]): Args;
+/** `text` with each of `vars` set: an existing line replaced, a new one appended. */
+export declare function withVars(text: string, vars: Record<string, string>): string;
+/**
+ * Keeps `file` out of git: nothing when git already ignores it, else its
+ * name added to the .gitignore beside it. Answers what it did.
+ */
+export declare function keepOutOfGit(file: string): string;
+export interface Io {
+    log: (line: string) => void;
+    fetch: typeof fetch;
+    sleep: (ms: number) => Promise<void>;
+    open: (url: string) => void;
+}
+/** The login flow; the exit code. */
+export declare function login(a: Args, io: Io): Promise<number>;
+/** The command line: `login`, or this help. */
+export declare function main(): Promise<void>;

package/dist/cli.js

@@ -0,0 +1,186 @@
+/**
+ * `npx @localmem/memory login` (specs/037 R53): pairs this terminal with a
+ * project. It asks for a pairing, prints the code, opens the approval page,
+ * and polls with its device secret until the key is handed to it once; then
+ * writes the three variables into .env (or --env-file) and keeps that file
+ * out of git. The secret is never printed.
+ */
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, appendFileSync, chmodSync } from "node:fs";
+import { hostname } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+import { DEFAULT_API } from "./index.js";
+const HELP = `Usage: npx @localmem/memory login [--env-file .env] [--device NAME] [--api URL] [--no-browser]
+
+Pairs this terminal with a localmem project: approve the code it prints in
+the browser, and a test key is written to your .env file.`;
+export function parse(argv) {
+    const a = {
+        command: undefined,
+        envFile: ".env",
+        device: hostname().slice(0, 60) || "a terminal",
+        api: (process.env.LOCALMEM_API_URL ?? DEFAULT_API).replace(/\/+$/, ""),
+        browser: true,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const v = argv[i];
+        const next = () => {
+            const n = argv[++i];
+            if (n === undefined)
+                throw new Error(`${v} needs a value`);
+            return n;
+        };
+        if (v === "--env-file")
+            a.envFile = next();
+        else if (v === "--device")
+            a.device = next();
+        else if (v === "--api")
+            a.api = next().replace(/\/+$/, "");
+        else if (v === "--no-browser")
+            a.browser = false;
+        else if (v === "-h" || v === "--help")
+            a.command = "help";
+        else if (!a.command)
+            a.command = v;
+        else
+            throw new Error(`unknown argument ${v}`);
+    }
+    return a;
+}
+/** `text` with each of `vars` set: an existing line replaced, a new one appended. */
+export function withVars(text, vars) {
+    const lines = text.length ? text.replace(/\n$/, "").split("\n") : [];
+    for (const [k, v] of Object.entries(vars)) {
+        const at = lines.findIndex((l) => new RegExp(`^\\s*(export\\s+)?${k}\\s*=`).test(l));
+        if (at >= 0)
+            lines[at] = `${k}=${v}`;
+        else
+            lines.push(`${k}=${v}`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * Keeps `file` out of git: nothing when git already ignores it, else its
+ * name added to the .gitignore beside it. Answers what it did.
+ */
+export function keepOutOfGit(file) {
+    const dir = dirname(file);
+    const name = basename(file);
+    const checked = spawnSync("git", ["check-ignore", "-q", name], { cwd: dir });
+    if (checked.status === 0)
+        return `${name} is already ignored by git.`;
+    const ignore = resolve(dir, ".gitignore");
+    const have = existsSync(ignore) ? readFileSync(ignore, "utf8") : "";
+    if (checked.status !== 1 && have.split("\n").some((l) => l.trim() === name || l.trim() === `/${name}`)) {
+        return `${name} is already in .gitignore.`;
+    }
+    appendFileSync(ignore, `${have && !have.endsWith("\n") ? "\n" : ""}${name}\n`);
+    return `Added ${name} to .gitignore, so the secret is never committed.`;
+}
+function open(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        spawn(cmd, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
+    }
+    catch {
+        // The link is printed; opening it is a courtesy.
+    }
+}
+async function post(url, body, f) {
+    const res = await f(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30_000),
+    });
+    const text = await res.text();
+    let parsed = {};
+    try {
+        parsed = text ? JSON.parse(text) : {};
+    }
+    catch {
+        parsed = { message: text.slice(0, 200) };
+    }
+    return { status: res.status, body: parsed };
+}
+/** The login flow; the exit code. */
+export async function login(a, io) {
+    const opened = await post(`${a.api}/v1/pair`, { device: a.device }, io.fetch);
+    if (opened.status !== 201) {
+        io.log(`Could not start pairing: ${opened.body.message ?? `localmem answered ${opened.status}`}`);
+        return 1;
+    }
+    const { pairing, device_secret, code, url } = opened.body;
+    const interval = Number(opened.body.interval ?? 3) * 1000;
+    const until = Date.now() + Number(opened.body.expires_in ?? 600) * 1000;
+    io.log(`Your code: ${code}`);
+    io.log(`Approve it at ${url}`);
+    if (a.browser)
+        io.open(url);
+    io.log("Waiting for approval…");
+    for (;;) {
+        await io.sleep(interval);
+        if (Date.now() > until) {
+            io.log("The code expired before it was approved. Run `npx @localmem/memory login` again.");
+            return 1;
+        }
+        let said;
+        try {
+            said = await post(`${a.api}/v1/pair/${encodeURIComponent(pairing)}/token`, { device_secret }, io.fetch);
+        }
+        catch {
+            continue;
+        }
+        if (said.status === 202)
+            continue;
+        if (said.status === 429 || said.status >= 500)
+            continue;
+        if (said.status !== 200) {
+            io.log(String(said.body.message ?? "This pairing has ended. Run `npx @localmem/memory login` again."));
+            return 1;
+        }
+        const { project, key_id, secret } = said.body;
+        const file = resolve(a.envFile);
+        const vars = {
+            LOCALMEM_PROJECT: project,
+            LOCALMEM_KEY_ID: key_id,
+            LOCALMEM_KEY_SECRET: secret,
+        };
+        if (a.api !== DEFAULT_API)
+            vars.LOCALMEM_API_URL = a.api;
+        const existed = existsSync(file);
+        writeFileSync(file, withVars(existed ? readFileSync(file, "utf8") : "", vars));
+        if (!existed)
+            chmodSync(file, 0o600);
+        io.log(`Paired with project ${project}: a test key, ${key_id}.`);
+        io.log(`Wrote ${Object.keys(vars).join(", ")} to ${a.envFile}. The secret is not shown here.`);
+        io.log(keepOutOfGit(file));
+        return 0;
+    }
+}
+/** The command line: `login`, or this help. */
+export async function main() {
+    let a;
+    try {
+        a = parse(process.argv.slice(2));
+    }
+    catch (e) {
+        console.error(`${e.message}\n\n${HELP}`);
+        process.exit(2);
+    }
+    if (a.command !== "login") {
+        console.log(HELP);
+        process.exit(a.command === "help" || a.command === undefined ? 0 : 2);
+    }
+    const code = await login(a, {
+        log: (l) => console.log(l),
+        fetch,
+        sleep: (ms) => new Promise((r) => setTimeout(r, ms)),
+        open,
+    });
+    process.exit(code);
+}

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+export declare const DEFAULT_API = "https://api.localmem.org";
+/** The longest Retry-After waited for; past it the error is raised at once. */
+export declare const MAX_WAIT_MS = 60000;
+export interface Options {
+    project?: string;
+    keyId?: string;
+    secret?: string;
+    /** Default LOCALMEM_API_URL, else https://api.localmem.org. */
+    baseUrl?: string;
+    /** Per attempt. Default 120 s: an inline document may take 90 s. */
+    timeoutMs?: number;
+    /** Retries after the first attempt. Default 3. */
+    maxRetries?: number;
+    fetch?: typeof fetch;
+    /** For tests: how a retry waits. */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** An answer that is not a success: the gateway's code and its words. */
+export declare class LocalmemError extends Error {
+    readonly status: number;
+    /** The gateway's code to act on, e.g. `monthly_limit`, `no_tenant`. */
+    readonly error: string;
+    readonly requestId: string | null;
+    /** Seconds, when the gateway said when to try again. */
+    readonly retryAfter: number | null;
+    /** The whole answer, with fields such as `resets_at`. */
+    readonly body: Record<string, unknown>;
+    constructor(status: number, body: Record<string, unknown>, requestId: string | null, retryAfter: number | null);
+}
+type Json = Record<string, unknown>;
+export interface Customer {
+    tenant: string;
+    external_ref: string;
+    phi: boolean;
+    status: string;
+    created_at: string;
+    [k: string]: unknown;
+}
+export interface DocumentIn {
+    text: string;
+    title?: string;
+    /** RFC 3339: when the document was true. */
+    as_of?: string;
+    tags?: Record<string, string>;
+    external_ref?: string;
+}
+/** The hex HMAC-SHA256 the gateway checks: `timestamp.METHOD.path.body`, the path without its query. */
+export declare function sign(secret: string, timestamp: string, method: string, path: string, body: string): string;
+export declare class Memory {
+    #private;
+    readonly project: string;
+    readonly keyId: string;
+    readonly baseUrl: string;
+    constructor(options?: Options);
+    /** Your customers: each its own memory (033 Part A). */
+    readonly customers: {
+        /** Made once per `external_ref`: the same one again answers the same customer. */
+        create: (externalRef: string, options?: {
+            phi?: boolean;
+        }) => Promise<Customer>;
+        list: () => Promise<{
+            tenants: Customer[];
+        }>;
+        get: (tenant: string) => Promise<Customer>;
+        /** Access stops at once; see the data contract for what follows. */
+        delete: (tenant: string) => Promise<Json>;
+    };
+    /** Documents, read by a model into facts (033 R15). */
+    readonly documents: {
+        /**
+         * Sends a document, with an Idempotency-Key (yours, or one made here)
+         * so a retry never reads it twice. Answers the written facts, or
+         * `{ status, follow }` when it is read in the background: pass that to
+         * `documents.wait`.
+         */
+        send: (tenant: string, doc: DocumentIn, options?: {
+            idempotencyKey?: string;
+        }) => Promise<Json>;
+        get: (tenant: string, documentId: string) => Promise<Json>;
+        /** Polls a background document until it is written or failed. */
+        wait: (tenant: string, documentId: string, options?: {
+            timeoutMs?: number;
+            everyMs?: number;
+        }) => Promise<Json>;
+    };
+    /** Facts you extracted yourself: nothing goes to a model. */
+    facts(tenant: string, body: Json): Promise<Json>;
+    write(tenant: string, body: {
+        content: string;
+        [k: string]: unknown;
+    }): Promise<Json>;
+    search(tenant: string, body: {
+        query: string;
+        k?: number;
+        at_time?: string;
+        [k: string]: unknown;
+    }): Promise<Json>;
+    /** What is known about `entity`, now or at `at_time`. */
+    recall(tenant: string, body: {
+        entity: string;
+        at_time?: string;
+        [k: string]: unknown;
+    }): Promise<Json>;
+    get(tenant: string, body: {
+        event_id: string;
+    }): Promise<Json>;
+    profile(tenant: string, body?: {
+        scope?: string;
+        tags?: Record<string, string>;
+    }): Promise<Json>;
+    /** Hides it from answers from now on; it does not destroy it. */
+    forget(tenant: string, body: {
+        target_id: string;
+    }): Promise<Json>;
+    /** One entry per customer and day, both dates included (YYYY-MM-DD). */
+    usage(range?: {
+        from?: string;
+        to?: string;
+    }): Promise<{
+        from: string;
+        to: string;
+        usage: Json[];
+    }>;
+}
+export {};

package/dist/index.js

@@ -0,0 +1,213 @@
+/**
+ * @localmem/memory: the localmem Memory API from TypeScript (specs/037 R55).
+ *
+ * Reads LOCALMEM_PROJECT, LOCALMEM_KEY_ID and LOCALMEM_KEY_SECRET (written by
+ * `npx @localmem/memory login`), signs every request as the gateway checks
+ * it (033 R2), sends an Idempotency-Key with every document and retries it
+ * on a timeout or a 5xx, honours Retry-After, and raises LocalmemError with
+ * the gateway's { error, message }. It covers the Memory API and nothing
+ * else. Server-side only: the secret must never reach a browser.
+ */
+import { createHmac, randomUUID } from "node:crypto";
+export const DEFAULT_API = "https://api.localmem.org";
+/** The longest Retry-After waited for; past it the error is raised at once. */
+export const MAX_WAIT_MS = 60_000;
+/** An answer that is not a success: the gateway's code and its words. */
+export class LocalmemError extends Error {
+    status;
+    /** The gateway's code to act on, e.g. `monthly_limit`, `no_tenant`. */
+    error;
+    requestId;
+    /** Seconds, when the gateway said when to try again. */
+    retryAfter;
+    /** The whole answer, with fields such as `resets_at`. */
+    body;
+    constructor(status, body, requestId, retryAfter) {
+        const code = typeof body.error === "string" ? body.error : `http_${status}`;
+        super(typeof body.message === "string" ? body.message : `localmem answered ${status}`);
+        this.name = "LocalmemError";
+        this.status = status;
+        this.error = code;
+        this.requestId = requestId;
+        this.retryAfter = retryAfter;
+        this.body = body;
+    }
+}
+/** The hex HMAC-SHA256 the gateway checks: `timestamp.METHOD.path.body`, the path without its query. */
+export function sign(secret, timestamp, method, path, body) {
+    const bare = path.split("?")[0];
+    return createHmac("sha256", secret).update(`${timestamp}.${method}.${bare}.${body}`).digest("hex");
+}
+function env(name) {
+    const v = typeof process !== "undefined" ? process.env[name] : undefined;
+    return v && v.trim() ? v.trim() : undefined;
+}
+const wait = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Memory {
+    project;
+    keyId;
+    baseUrl;
+    #secret;
+    #timeoutMs;
+    #maxRetries;
+    #fetch;
+    #sleep;
+    constructor(options = {}) {
+        const project = options.project ?? env("LOCALMEM_PROJECT");
+        const keyId = options.keyId ?? env("LOCALMEM_KEY_ID");
+        const secret = options.secret ?? env("LOCALMEM_KEY_SECRET");
+        const missing = [
+            !project && "LOCALMEM_PROJECT",
+            !keyId && "LOCALMEM_KEY_ID",
+            !secret && "LOCALMEM_KEY_SECRET",
+        ].filter(Boolean);
+        if (missing.length) {
+            throw new Error(`Set ${missing.join(", ")}: run \`npx @localmem/memory login\`, or pass them to new Memory().`);
+        }
+        this.project = project;
+        this.keyId = keyId;
+        this.#secret = secret;
+        this.baseUrl = (options.baseUrl ?? env("LOCALMEM_API_URL") ?? DEFAULT_API).replace(/\/+$/, "");
+        this.#timeoutMs = options.timeoutMs ?? 120_000;
+        this.#maxRetries = options.maxRetries ?? 3;
+        this.#fetch = options.fetch ?? fetch;
+        this.#sleep = options.sleep ?? wait;
+    }
+    /** Your customers: each its own memory (033 Part A). */
+    customers = {
+        /** Made once per `external_ref`: the same one again answers the same customer. */
+        create: (externalRef, options = {}) => this.#call("POST", "/v1/partner/tenants", { body: { external_ref: externalRef, ...options } }),
+        list: () => this.#call("GET", "/v1/partner/tenants"),
+        get: (tenant) => this.#call("GET", `/v1/partner/tenants/${encodeURIComponent(tenant)}`),
+        /** Access stops at once; see the data contract for what follows. */
+        delete: (tenant) => this.#call("DELETE", `/v1/partner/tenants/${encodeURIComponent(tenant)}`),
+    };
+    /** Documents, read by a model into facts (033 R15). */
+    documents = {
+        /**
+         * Sends a document, with an Idempotency-Key (yours, or one made here)
+         * so a retry never reads it twice. Answers the written facts, or
+         * `{ status, follow }` when it is read in the background: pass that to
+         * `documents.wait`.
+         */
+        send: (tenant, doc, options = {}) => this.#call("POST", "/v1/memory/documents", {
+            body: { ...doc },
+            tenant,
+            headers: { "Idempotency-Key": options.idempotencyKey ?? randomUUID() },
+            repeatable: true,
+        }),
+        get: (tenant, documentId) => this.#call("GET", `/v1/memory/documents/${encodeURIComponent(documentId)}`, { tenant, repeatable: true }),
+        /** Polls a background document until it is written or failed. */
+        wait: async (tenant, documentId, options = {}) => {
+            const until = Date.now() + (options.timeoutMs ?? 600_000);
+            for (;;) {
+                const d = await this.documents.get(tenant, documentId);
+                if (d.status === "written" || d.status === "failed" || Date.now() > until)
+                    return d;
+                await this.#sleep(options.everyMs ?? 5_000);
+            }
+        },
+    };
+    /** Facts you extracted yourself: nothing goes to a model. */
+    facts(tenant, body) {
+        return this.#memory("facts", tenant, body);
+    }
+    write(tenant, body) {
+        return this.#memory("write", tenant, body);
+    }
+    search(tenant, body) {
+        return this.#memory("search", tenant, body);
+    }
+    /** What is known about `entity`, now or at `at_time`. */
+    recall(tenant, body) {
+        return this.#memory("recall", tenant, body);
+    }
+    get(tenant, body) {
+        return this.#memory("get", tenant, body);
+    }
+    profile(tenant, body = {}) {
+        return this.#memory("profile", tenant, body);
+    }
+    /** Hides it from answers from now on; it does not destroy it. */
+    forget(tenant, body) {
+        return this.#memory("forget", tenant, body);
+    }
+    /** One entry per customer and day, both dates included (YYYY-MM-DD). */
+    usage(range = {}) {
+        const q = new URLSearchParams(Object.entries(range).filter(([, v]) => v)).toString();
+        return this.#call("GET", `/v1/partner/usage${q ? `?${q}` : ""}`, {
+            repeatable: true,
+        });
+    }
+    #memory(route, tenant, body) {
+        return this.#call("POST", `/v1/memory/${route}`, { body, tenant });
+    }
+    async #call(method, path, call = {}) {
+        const raw = call.body === undefined ? "" : JSON.stringify(call.body);
+        const repeatable = call.repeatable ?? method === "GET";
+        for (let attempt = 0;; attempt++) {
+            const ts = String(Math.floor(Date.now() / 1000));
+            const headers = {
+                "x-partner-id": this.project,
+                "x-localmem-key": this.keyId,
+                "x-localmem-timestamp": ts,
+                "x-localmem-signature": sign(this.#secret, ts, method, path, raw),
+                ...(raw ? { "content-type": "application/json" } : {}),
+                ...(call.tenant ? { "x-tenant-id": call.tenant } : {}),
+                ...call.headers,
+            };
+            let res;
+            try {
+                res = await this.#fetch(`${this.baseUrl}${path}`, {
+                    method,
+                    headers,
+                    body: raw || undefined,
+                    signal: AbortSignal.timeout(this.#timeoutMs),
+                });
+            }
+            catch (e) {
+                // No answer: sent again only when that cannot do it twice.
+                if (repeatable && attempt < this.#maxRetries) {
+                    await this.#sleep(backoff(attempt));
+                    continue;
+                }
+                throw e;
+            }
+            const text = await res.text();
+            let body = {};
+            try {
+                body = text ? JSON.parse(text) : {};
+            }
+            catch {
+                body = { error: "not_json", message: text.slice(0, 200) };
+            }
+            if (res.ok)
+                return body;
+            const after = res.headers.get("retry-after");
+            const retryAfter = after !== null && /^\d+$/.test(after) ? Number(after) : null;
+            const err = new LocalmemError(res.status, body, res.headers.get("x-request-id"), retryAfter);
+            if (attempt < this.#maxRetries) {
+                // A 429, and a 503 server_busy, were refused before any work, so any
+                // request may go again when the wait is short; a monthly limit's wait
+                // is days, so it is raised. Any other 503 (a timeout) may have done
+                // the work, so only a repeatable request goes again.
+                const notDone = res.status === 429 || (res.status === 503 && body.error === "server_busy");
+                if ((notDone || (res.status === 503 && repeatable)) && (retryAfter ?? 1) * 1000 <= MAX_WAIT_MS) {
+                    await this.#sleep(retryAfter !== null ? retryAfter * 1000 : backoff(attempt));
+                    continue;
+                }
+                // A document whose first send is still being read: its answer comes
+                // to the same Idempotency-Key shortly.
+                if ((res.status >= 500 || (res.status === 409 && body.error === "idempotency_key_in_use")) && repeatable) {
+                    await this.#sleep(backoff(attempt));
+                    continue;
+                }
+            }
+            throw err;
+        }
+    }
+}
+/** 0.5 s, 1 s, 2 s … with jitter, at most 8 s. */
+function backoff(attempt) {
+    return Math.min(8_000, 500 * 2 ** attempt) * (0.5 + Math.random() / 2);
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@localmem/memory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The localmem Memory API: memory of each of your customers, with the source and date of every fact. Server-side TypeScript, and `npx @localmem/memory login` to pair a terminal with a project.",
+  "license": "Apache-2.0",
+  "homepage": "https://localmem.org/docs/memory-api/sdks",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "memory": "./dist/bin.js"
+  },
+  "files": [
+    "dist/index.js",
+    "dist/index.d.ts",
+    "dist/cli.js",
+    "dist/cli.d.ts",
+    "dist/bin.js",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test test/*.test.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.2",
+    "typescript": "5.9.3"
+  }
+}