@becomerpackage/sdk 0.1.0

package/README.md

@@ -0,0 +1,177 @@
+# becomer — JavaScript / Node.js SDK
+
+[![npm](https://img.shields.io/npm/v/becomer)](https://www.npmjs.com/package/becomer)
+[![LongMemEval](https://img.shields.io/badge/LongMemEval-94.4%25-brightgreen)](https://becomer.net/#benchmarks)
+
+**Persistent memory API for AI apps. Zero dependencies. Node 18+.**
+
+```js
+const { Client } = require('becomer');
+
+const mem = new Client('bcm_your-api-key');
+await mem.store('User prefers dark mode and speaks French');
+const memories = await mem.recall('user preferences');
+// → ['User prefers dark mode and speaks French']
+```
+
+→ [Get your free API key](https://becomer.net/signup.html) · [Docs](https://becomer.net/docs.html) · [Benchmarks](https://becomer.net/#benchmarks)
+
+---
+
+## Install
+
+```bash
+npm install @becomerpackage/sdk
+```
+
+Zero dependencies. Uses Node's built-in `fetch` (Node 18+).
+
+---
+
+## Quick start
+
+```js
+const { Client } = require('becomer');
+// ESM: import { Client } from 'becomer';
+
+const mem = new Client('bcm_your-api-key');
+
+await mem.store('User is Sarah, senior engineer at Stripe');
+await mem.store('User prefers TypeScript and dark mode');
+
+const context = await mem.recall('what do I know about the user?');
+// → ['User is Sarah, senior engineer at Stripe', ...]
+
+// Inject into your LLM call
+const system = 'You are a helpful assistant.\n\nContext:\n' + context.join('\n');
+```
+
+---
+
+## Multi-tenant (one key, many users)
+
+Pass `userId` to isolate memories per end-user under one master key.
+
+```js
+// Constructor-level (all calls scoped to alice)
+const memAlice = new Client('bcm_your-api-key', { userId: 'alice-123' });
+await memAlice.store('Alice prefers TypeScript');
+
+// Different user — completely isolated
+const memBob = new Client('bcm_your-api-key', { userId: 'bob-456' });
+await memBob.recall('preferences'); // → [] (cannot see Alice's memories)
+
+// Or override per-call
+const mem = new Client('bcm_your-api-key');
+await mem.store('Charlie loves Rust', { userId: 'charlie-789' });
+await mem.recall('languages', { userId: 'charlie-789' });
+```
+
+Billing counts against the master key. Browse per-user memories in your [dashboard](https://becomer.net/dashboard.html).
+
+---
+
+## OpenAI
+
+```js
+const OpenAI = require('openai');
+const { Client } = require('becomer');
+
+const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+const mem = new Client(process.env.BECOMER_API_KEY);
+
+async function chat(message, userId) {
+  const context = await mem.recall(message, { userId });
+  const system = context.length
+    ? 'You are helpful.\n\nContext:\n' + context.join('\n')
+    : 'You are helpful.';
+
+  const res = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [{ role: 'system', content: system }, { role: 'user', content: message }],
+  });
+  const reply = res.choices[0].message.content;
+
+  await mem.store(`User: ${message}`, { userId });
+  await mem.store(`Assistant: ${reply}`, { userId });
+  return reply;
+}
+```
+
+---
+
+## Anthropic
+
+```js
+const Anthropic = require('@anthropic-ai/sdk');
+const { Client } = require('becomer');
+
+const claude = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
+const mem = new Client(process.env.BECOMER_API_KEY);
+
+async function chat(message, userId) {
+  const context = await mem.recall(message, { userId });
+  const system = context.length
+    ? 'You are helpful.\n\nContext:\n' + context.join('\n')
+    : 'You are helpful.';
+
+  const res = await claude.messages.create({
+    model: 'claude-opus-4-8',
+    max_tokens: 1024,
+    system,
+    messages: [{ role: 'user', content: message }],
+  });
+  const reply = res.content[0].text;
+
+  await mem.store(`User: ${message}`, { userId });
+  await mem.store(`Assistant: ${reply}`, { userId });
+  return reply;
+}
+```
+
+---
+
+## API reference
+
+### `new Client(apiKey, options?)`
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `userId` | string | Default sub-user ID applied to all calls |
+| `baseUrl` | string | Override API base URL |
+
+### Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `store(content, opts?)` | `Promise<{ok}>` | Store a memory |
+| `recall(query, opts?)` | `Promise<string[]>` | Retrieve top-k relevant memories |
+| `forget(opts?)` | `Promise<{ok}>` | Delete all memories (or sub-user's) |
+| `sync(opts?)` | `Promise<{ok}>` | Consolidate working memory |
+
+All methods accept `opts.userId` to override the sub-user for that call.  
+`recall` also accepts `opts.topK` (default: 5).
+
+---
+
+## Examples
+
+| File | Framework |
+|------|-----------|
+| [quickstart.js](examples/quickstart.js) | Plain Node.js |
+| [openai.js](examples/openai.js) | OpenAI SDK |
+| [anthropic.js](examples/anthropic.js) | Anthropic SDK |
+| [langchain.js](examples/langchain.js) | LangChain.js |
+
+---
+
+## Requirements
+
+- Node.js 18+ (uses built-in `fetch`)
+- Zero npm dependencies
+
+---
+
+## Built by
+
+[Obsidex Pvt Limited](https://www.linkedin.com/company/115424394/) · [Aravind Balaji](https://www.linkedin.com/in/aravind-balaji-2k1/), Founder · [hello@becomer.net](mailto:hello@becomer.net)

package/examples/anthropic.js

@@ -0,0 +1,44 @@
+// Anthropic Claude + BECOMER — persistent memory across conversations
+// npm install @anthropic-ai/sdk becomer
+const Anthropic = require('@anthropic-ai/sdk');
+const { Client } = require('becomer');
+
+const claude = new Anthropic({ apiKey: 'sk-ant-your-key' });
+
+async function chat(message, mem) {
+  const context = await mem.recall(message);
+
+  let system = 'You are a helpful assistant.';
+  if (context.length) {
+    system += '\n\nWhat you remember about this user:\n' + context.map(m => `- ${m}`).join('\n');
+  }
+
+  const response = await claude.messages.create({
+    model: 'claude-opus-4-8',
+    max_tokens: 1024,
+    system,
+    messages: [{ role: 'user', content: message }],
+  });
+  const reply = response.content[0].text;
+
+  await mem.store(`User: ${message}`);
+  await mem.store(`Assistant: ${reply}`);
+
+  return reply;
+}
+
+async function main() {
+  // ── Single user ─────────────────────────────────────────────────────────────
+  const mem = new Client('bcm_your-api-key');
+  console.log(await chat("I'm Aravind, I'm building an AI memory product", mem));
+  console.log(await chat('What should I focus on for launch?', mem));
+
+  // ── Multi-tenant ────────────────────────────────────────────────────────────
+  const memAlice = new Client('bcm_your-api-key', { userId: 'alice-123' });
+  const memBob   = new Client('bcm_your-api-key', { userId: 'bob-456' });
+
+  console.log(await chat('I love Rust and systems programming', memAlice));
+  console.log(await chat("I'm a data scientist, I use Python daily", memBob));
+}
+
+main().catch(console.error);

package/examples/langchain.js

@@ -0,0 +1,58 @@
+// LangChain.js + BECOMER — persistent memory adapter
+// npm install langchain @langchain/openai becomer
+const { BaseMemory } = require('langchain/memory');
+const { ConversationChain } = require('langchain/chains');
+const { ChatOpenAI } = require('@langchain/openai');
+const { Client } = require('becomer');
+
+class BecomerMemory extends BaseMemory {
+  constructor(apiKey, options = {}) {
+    super();
+    this.mem = new Client(apiKey, { userId: options.userId });
+    this.memoryKey = options.memoryKey || 'history';
+  }
+
+  get memoryVariables() {
+    return [this.memoryKey];
+  }
+
+  async loadMemoryVariables(inputs) {
+    const query = inputs.input || '';
+    const memories = await this.mem.recall(query);
+    return { [this.memoryKey]: memories.join('\n') };
+  }
+
+  async saveContext(inputs, outputs) {
+    await this.mem.store(`User: ${inputs.input || ''}`);
+    await this.mem.store(`Assistant: ${outputs.response || outputs.output || ''}`);
+  }
+
+  async clear() {
+    await this.mem.forget();
+  }
+}
+
+async function main() {
+  // ── Single user ─────────────────────────────────────────────────────────────
+  const chain = new ConversationChain({
+    llm: new ChatOpenAI({ model: 'gpt-4o', apiKey: 'sk-your-openai-key' }),
+    memory: new BecomerMemory('bcm_your-api-key'),
+  });
+
+  console.log(await chain.call({ input: 'My name is Sarah and I work at Stripe' }));
+  console.log(await chain.call({ input: 'What do you know about me?' }));
+
+  // ── Multi-tenant: per-user isolated memory ──────────────────────────────────
+  const chainAlice = new ConversationChain({
+    llm: new ChatOpenAI({ model: 'gpt-4o', apiKey: 'sk-your-openai-key' }),
+    memory: new BecomerMemory('bcm_your-api-key', { userId: 'alice-123' }),
+  });
+  const chainBob = new ConversationChain({
+    llm: new ChatOpenAI({ model: 'gpt-4o', apiKey: 'sk-your-openai-key' }),
+    memory: new BecomerMemory('bcm_your-api-key', { userId: 'bob-456' }),
+  });
+  // Alice and Bob have completely separate memory stores.
+}
+
+module.exports = { BecomerMemory };
+main().catch(console.error);

package/examples/openai.js

@@ -0,0 +1,46 @@
+// OpenAI + BECOMER — persistent memory across conversations
+// npm install openai becomer
+const OpenAI = require('openai');
+const { Client } = require('becomer');
+
+const openai = new OpenAI({ apiKey: 'sk-your-openai-key' });
+
+async function chat(message, mem) {
+  const context = await mem.recall(message);
+
+  let system = 'You are a helpful assistant.';
+  if (context.length) {
+    system += '\n\nWhat you remember about this user:\n' + context.map(m => `- ${m}`).join('\n');
+  }
+
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4o',
+    messages: [
+      { role: 'system', content: system },
+      { role: 'user', content: message },
+    ],
+  });
+  const reply = response.choices[0].message.content;
+
+  await mem.store(`User: ${message}`);
+  await mem.store(`Assistant: ${reply}`);
+
+  return reply;
+}
+
+async function main() {
+  // ── Single user ─────────────────────────────────────────────────────────────
+  const mem = new Client('bcm_your-api-key');
+  console.log(await chat("My name is Sarah and I'm building a payments dashboard", mem));
+  console.log(await chat('What stack should I use?', mem));
+
+  // ── Multi-tenant ────────────────────────────────────────────────────────────
+  const memAlice = new Client('bcm_your-api-key', { userId: 'alice-123' });
+  const memBob   = new Client('bcm_your-api-key', { userId: 'bob-456' });
+
+  console.log(await chat('I prefer functional programming', memAlice));
+  console.log(await chat('I prefer OOP and Java', memBob));
+  // Alice and Bob have completely separate memory stores.
+}
+
+main().catch(console.error);

package/examples/quickstart.js

@@ -0,0 +1,32 @@
+// Quickstart — store and recall memories
+// Get your free API key at https://becomer.net
+const { Client } = require('becomer');
+
+async function main() {
+  // ── Single user ─────────────────────────────────────────────────────────────
+  const mem = new Client('bcm_your-api-key');
+
+  await mem.store('My name is Sarah and I work at Stripe');
+  await mem.store('I prefer concise answers and I use Node.js 20');
+
+  const results = await mem.recall('who is the user?');
+  console.log(results);
+  // → ['My name is Sarah and I work at Stripe', ...]
+
+  // ── Multi-tenant: one key, many users ───────────────────────────────────────
+  const memAlice = new Client('bcm_your-api-key', { userId: 'alice-123' });
+  const memBob   = new Client('bcm_your-api-key', { userId: 'bob-456' });
+
+  await memAlice.store('Alice prefers TypeScript');
+  await memBob.store('Bob prefers Python');
+
+  console.log(await memAlice.recall('language preference')); // → Alice's only
+  console.log(await memBob.recall('language preference'));   // → Bob's only
+
+  // Or override per-call:
+  const mem2 = new Client('bcm_your-api-key');
+  await mem2.store('Charlie loves Rust', { userId: 'charlie-789' });
+  console.log(await mem2.recall('languages', { userId: 'charlie-789' }));
+}
+
+main().catch(console.error);

package/index.d.ts

@@ -0,0 +1,36 @@
+export interface ClientOptions {
+  /** Default sub-user ID for multi-tenant apps. Applied to all calls unless overridden. */
+  userId?: string;
+  /** Override the API base URL. Defaults to https://becomer.net */
+  baseUrl?: string;
+}
+
+export interface CallOptions {
+  /** Sub-user ID for this call only. Overrides the constructor-level userId. */
+  userId?: string;
+}
+
+export interface RecallOptions extends CallOptions {
+  /** Number of memories to return. Default: 5 */
+  topK?: number;
+}
+
+export declare class BecomerError extends Error {
+  status?: number;
+}
+
+export declare class Client {
+  constructor(apiKey: string, options?: ClientOptions);
+
+  /** Store a memory. */
+  store(content: string, opts?: CallOptions): Promise<{ ok: boolean }>;
+
+  /** Recall relevant memories for a query. */
+  recall(query: string, opts?: RecallOptions): Promise<string[]>;
+
+  /** Delete all memories (or a sub-user's memories if userId is set). */
+  forget(opts?: CallOptions): Promise<{ ok: boolean }>;
+
+  /** Consolidate working memory into long-term storage. */
+  sync(opts?: CallOptions): Promise<{ ok: boolean }>;
+}

package/index.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const BASE_URL = 'https://becomer.net';
+
+class BecomerError extends Error {
+  constructor(message, status) {
+    super(message);
+    this.name = 'BecomerError';
+    this.status = status;
+  }
+}
+
+class Client {
+  /**
+   * @param {string} apiKey - Your BECOMER API key (starts with bcm_)
+   * @param {object} [options]
+   * @param {string} [options.userId] - Default sub-user ID for multi-tenant apps
+   * @param {string} [options.baseUrl] - Override API base URL
+   */
+  constructor(apiKey, options = {}) {
+    if (!apiKey) throw new BecomerError('apiKey is required');
+    this._key = apiKey;
+    this._userId = options.userId || null;
+    this._base = (options.baseUrl || BASE_URL).replace(/\/$/, '');
+  }
+
+  _body(base, opts = {}) {
+    const uid = opts.userId !== undefined ? opts.userId : this._userId;
+    if (uid) return { ...base, user_id: uid };
+    return base;
+  }
+
+  async _request(method, path, body) {
+    const url = this._base + path;
+    const res = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${this._key}`,
+        'Content-Type': 'application/json',
+      },
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      const text = await res.text().catch(() => '');
+      throw new BecomerError(`HTTP ${res.status}: ${text}`, res.status);
+    }
+    return res.json();
+  }
+
+  /**
+   * Store a memory.
+   * @param {string} content
+   * @param {object} [opts]
+   * @param {string} [opts.userId] - Override sub-user for this call
+   */
+  async store(content, opts = {}) {
+    return this._request('POST', '/v1/store', this._body({ content }, opts));
+  }
+
+  /**
+   * Recall relevant memories for a query.
+   * @param {string} query
+   * @param {object} [opts]
+   * @param {number} [opts.topK=5]
+   * @param {string} [opts.userId]
+   * @returns {Promise<string[]>}
+   */
+  async recall(query, opts = {}) {
+    const { topK = 5, userId } = opts;
+    const result = await this._request(
+      'POST', '/v1/recall',
+      this._body({ query, top_k: topK }, { userId })
+    );
+    return result.memories || [];
+  }
+
+  /**
+   * Delete all memories (or a sub-user's memories if userId is set).
+   * @param {object} [opts]
+   * @param {string} [opts.userId]
+   */
+  async forget(opts = {}) {
+    return this._request('POST', '/v1/forget', this._body({ forget_all: true }, opts));
+  }
+
+  /**
+   * Consolidate working memory into long-term storage.
+   * @param {object} [opts]
+   * @param {string} [opts.userId]
+   */
+  async sync(opts = {}) {
+    return this._request('POST', '/v1/sync', this._body({}, opts));
+  }
+}
+
+module.exports = { Client, BecomerError };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@becomerpackage/sdk",
+  "version": "0.1.0",
+  "description": "Persistent memory API for AI applications — 94.4% LongMemEval, zero tokens per recall",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./index.js",
+      "import": "./index.js",
+      "types": "./index.d.ts"
+    }
+  },
+  "scripts": {
+    "test": "node examples/quickstart.js"
+  },
+  "keywords": [
+    "memory", "llm", "ai", "mcp", "claude", "gpt", "openai", "anthropic",
+    "langchain", "persistent-memory", "vector-store", "rag"
+  ],
+  "author": "Obsidex Pvt Limited <hello@becomer.net>",
+  "license": "MIT",
+  "homepage": "https://becomer.net",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Aravind-Becomer-net/Becomer.net"
+  },
+  "bugs": {
+    "url": "https://github.com/Aravind-Becomer-net/Becomer.net/issues",
+    "email": "hello@becomer.net"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {}
+}