@pyxmate/memory 0.19.1 → 0.20.5

package/bin/init.mjs

@@ -1,43 +1,312 @@
 #!/usr/bin/env node
 
-import { cpSync, existsSync, mkdirSync, readdirSync } from 'node:fs';
-import { dirname, join, resolve } from 'node:path';
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
+const DEFAULT_ENDPOINT = 'https://memory.api.pyxmate.com';
 
-const command = process.argv[2];
+// ---------- Argument parsing ----------
 
-if (command !== 'init') {
-  console.log(`Usage: pyxmate-memory init
+/**
+ * Minimal long-flag parser. Supports `--key=value`, `--key value`, boolean `--flag`,
+ * `--` terminator, and positional rest. Unknown subcommand-specific flags surface
+ * as keys in `flags`; the dispatcher decides if any are unsupported.
+ */
+function parseArgs(argv) {
+  const flags = Object.create(null);
+  const positional = [];
+  let i = 0;
+  while (i < argv.length) {
+    const a = argv[i];
+    if (a === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq >= 0) {
+        const key = a.slice(2, eq);
+        flags[key] = a.slice(eq + 1);
+        i += 1;
+        continue;
+      }
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+        i += 1;
+      } else {
+        flags[key] = next;
+        i += 2;
+      }
+      continue;
+    }
+    positional.push(a);
+    i += 1;
+  }
+  return { flags, positional };
+}
 
-Commands:
-  init    Copy pyx-memory skill files into .claude/skills/ for Claude Code auto-discovery`);
-  process.exit(command ? 1 : 0);
+// ---------- Errors ----------
+
+class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
 }
 
-const source = resolve(__dirname, '..', 'skills', 'pyx-memory');
-const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory');
+// ---------- Shared helpers ----------
 
-if (!existsSync(source)) {
-  console.error('Error: Skills directory not found in package. Please reinstall @pyxmate/memory.');
-  process.exit(1);
+function resolveAuth(flags) {
+  const endpointRaw = flags.endpoint ?? process.env.PYXMATE_ENDPOINT ?? DEFAULT_ENDPOINT;
+  if (typeof endpointRaw !== 'string') {
+    throw new CliError('--endpoint requires a value (got bare flag)', 2);
+  }
+  const endpoint = endpointRaw.replace(/\/+$/, '');
+  const apiKey = flags['api-key'] ?? process.env.PYXMATE_API_KEY;
+  if (!apiKey || typeof apiKey !== 'string') {
+    throw new CliError('missing API key: set PYXMATE_API_KEY or pass --api-key <key>', 2);
+  }
+  return { apiKey, endpoint };
+}
+
+function buildHeaders(flags, { apiKey, json = false, includeSensitivity = false } = {}) {
+  const headers = { Authorization: `Bearer ${apiKey}` };
+  if (json) headers['Content-Type'] = 'application/json';
+  // Bare `--tenant-id`/`--user-id`/`--team-id` (no value) becomes `true` via parseArgs;
+  // `String(true)` would silently scope the request to a tenant literally named "true".
+  // Type-guard mirrors resolveAuth's `--endpoint` shape.
+  for (const [flag, header] of [
+    ['tenant-id', 'X-Tenant-Id'],
+    ['user-id', 'X-User-Id'],
+    ['team-id', 'X-Team-Id'],
+  ]) {
+    if (flags[flag] !== undefined) {
+      if (typeof flags[flag] !== 'string') {
+        throw new CliError(`--${flag} requires a value (got bare flag)`, 2);
+      }
+      headers[header] = flags[flag];
+    }
+  }
+  if (includeSensitivity && flags.sensitivity) {
+    const level = String(flags.sensitivity);
+    if (!['public', 'internal', 'secret'].includes(level)) {
+      throw new CliError(
+        `--sensitivity must be one of: public, internal, secret (got '${level}')`,
+        2,
+      );
+    }
+    headers['X-Caller-Access-Level'] = level;
+  }
+  return headers;
 }
 
-// Ensure target parent exists
-mkdirSync(dirname(target), { recursive: true });
+function loadJsonArg(value, flagName) {
+  if (value === undefined || value === null || value === true) {
+    throw new CliError(`--${flagName} requires a value`, 2);
+  }
+  const raw = String(value);
+  let source;
+  let payload;
+  try {
+    if (raw === '-') {
+      source = 'stdin';
+      // Synchronous stdin read for ergonomics; only invoked when caller explicitly passes '-'.
+      payload = readFileSync(0, 'utf8');
+    } else if (raw.startsWith('@')) {
+      source = `file ${raw.slice(1)}`;
+      payload = readFileSync(raw.slice(1), 'utf8');
+    } else {
+      source = 'inline';
+      payload = raw;
+    }
+  } catch (err) {
+    throw new CliError(`--${flagName}: failed to read ${source}: ${err.message}`, 2);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(payload);
+  } catch (err) {
+    throw new CliError(`--${flagName}: invalid JSON from ${source}: ${err.message}`, 2);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new CliError(`--${flagName}: expected JSON array, got ${typeof parsed}`, 2);
+  }
+  return parsed;
+}
 
-// Copy skills (overwrites existing files for idempotency)
-cpSync(source, target, { recursive: true });
+async function request(method, url, { headers = {}, body = undefined } = {}) {
+  let response;
+  try {
+    response = await fetch(url, { method, headers, body });
+  } catch (err) {
+    throw new CliError(`network error: ${err.message}`, 1);
+  }
+  const text = await response.text();
+  let parsed;
+  if (text.length === 0) {
+    parsed = null;
+  } else {
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      // Server returned non-JSON; surface raw text so the failure is visible.
+      if (!response.ok) {
+        throw new CliError(`HTTP ${response.status}: ${text.slice(0, 500)}`, 1);
+      }
+      throw new CliError(`expected JSON response from ${url}; got: ${text.slice(0, 200)}`, 1);
+    }
+  }
+  if (!response.ok) {
+    const msg =
+      parsed && (parsed.error || parsed.message)
+        ? parsed.error || parsed.message
+        : `HTTP ${response.status}`;
+    throw new CliError(`server error (${response.status}): ${msg}`, 1);
+  }
+  // Surface `{ success: false }` envelope errors.
+  if (parsed && parsed.success === false) {
+    const msg = parsed.error || parsed.message || 'unknown error';
+    throw new CliError(`server error: ${msg}`, 1);
+  }
+  return parsed;
+}
+
+function emit(result, flags, humanFn) {
+  if (flags.json) {
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    return;
+  }
+  const human = humanFn ? humanFn(result) : JSON.stringify(result);
+  if (human !== undefined && human !== null && human !== '') {
+    process.stdout.write(`${human}\n`);
+  }
+}
+
+// ---------- Help text ----------
+
+const TOP_HELP = `pyxmate-memory — CLI for the pyx-memory HTTP API
+
+Usage:
+  pyxmate-memory <command> [flags]
+
+Commands:
+  init                          Copy pyx-memory skill files into ./.claude/skills/
+  store                         Store a memory entry (POST /api/memory/ingest)
+  search                        Search memory (GET /api/memory/search)
+  get <id>                      Fetch a single entry (GET /api/memory/:id)
+  delete <id>                   Delete an entry (DELETE /api/memory/:id)
+  log                           List recent entries (GET /api/memory/log)
+  summarize-entity <name>       Summarize an entity (POST /api/memory/summarize-entity)
+  ingest-file <path>            Upload a file (POST /api/memory/ingest/file, multipart NDJSON)
+
+Auth (operation commands):
+  PYXMATE_API_KEY=<key>         API key (or --api-key <key>)
+  PYXMATE_ENDPOINT=<url>        Endpoint (or --endpoint <url>, default ${DEFAULT_ENDPOINT})
+
+Global flags (operation commands):
+  --tenant-id <id>              Forward X-Tenant-Id header
+  --user-id <id>                Forward X-User-Id header
+  --team-id <id>                Forward X-Team-Id header
+  --json                        Emit raw upstream JSON to stdout
+  --help                        Print help for the command
+
+Run \`pyxmate-memory <command> --help\` for command-specific flags.`;
+
+const SUB_HELP = {
+  init: `Usage: pyxmate-memory init
+
+  Copies skill files into ./.claude/skills/pyx-memory/ for Claude Code auto-discovery.
+  Requires no API key; idempotent overwrite.`,
+  store: `Usage: pyxmate-memory store --content <text> [flags]
+
+  --content <text>              Memory content (required)
+  --type <type>                 Memory type (default: long-term)
+  --topic <topic>               Topic (metadata.topic)
+  --project <name>              Project (metadata.project)
+  --importance <1-10>           Importance score (metadata.importance)
+  --source <source>             Source (metadata.source)
+  --event-time <iso>            Event time (metadata.eventTime)
+  --entities <json|@path|->     JSON array of entities (inline, @file, or - for stdin)
+  --relationships <json|@path|-> JSON array of relationships (inline, @file, or - for stdin)
+  --quiet                       Print only the new entry id`,
+  search: `Usage: pyxmate-memory search --query <text> [flags]
+
+  --query <text>                Search query (required; also accepts --q)
+  --limit <n>                   Max results (default 5)
+  --strategy <s>                hybrid | vector | keyword | graph
+  --type <t>                    Filter by memory type
+  --agent-id <id>               Filter by agentId
+  --abstention-threshold <0-1>  Enable confidence scoring
+  --sensitivity <level>         X-Caller-Access-Level (public|internal|secret)`,
+  get: `Usage: pyxmate-memory get <id> [flags]`,
+  delete: `Usage: pyxmate-memory delete <id> [flags]`,
+  log: `Usage: pyxmate-memory log [flags]
+
+  --since <iso>                 Only entries created at or after this ISO timestamp
+  --limit <n>                   Max entries
+  --type <t>                    Filter by memory type
+  --agent-id <id>               Filter by agentId
+  --source <s>                  Filter by source`,
+  'summarize-entity': `Usage: pyxmate-memory summarize-entity <name> [flags]`,
+  'ingest-file': `Usage: pyxmate-memory ingest-file <path> [flags]
+
+  --description <text>          Required for images; describes the file contents
+  --namespace-id <id>           Namespace for the entry`,
+};
+
+const GLOBAL_FLAGS_FOOTER = `
+Global flags:
+  --api-key <key>               API key (or PYXMATE_API_KEY)
+  --endpoint <url>              Endpoint URL (or PYXMATE_ENDPOINT)
+  --tenant-id <id>              Forward X-Tenant-Id header
+  --user-id <id>                Forward X-User-Id header
+  --team-id <id>                Forward X-Team-Id header
+  --json                        Emit raw upstream JSON to stdout`;
+
+function printHelp(subcommand) {
+  if (subcommand && SUB_HELP[subcommand]) {
+    const footer = subcommand === 'init' ? '' : `\n${GLOBAL_FLAGS_FOOTER}`;
+    process.stdout.write(`${SUB_HELP[subcommand]}${footer}\n`);
+    return;
+  }
+  process.stdout.write(`${TOP_HELP}\n`);
+}
+
+// ---------- init (existing behavior) ----------
+
+function runInit() {
+  const source = resolve(__dirname, '..', 'skills', 'pyx-memory');
+  const target = resolve(process.cwd(), '.claude', 'skills', 'pyx-memory');
+
+  if (!existsSync(source)) {
+    throw new CliError(
+      'Skills directory not found in package. Please reinstall @pyxmate/memory.',
+      1,
+    );
+  }
+
+  mkdirSync(dirname(target), { recursive: true });
+  cpSync(source, target, { recursive: true });
+
+  const fileCount = countFiles(target);
+  const fileList = listFiles(target);
+
+  process.stdout.write(`Copied ${fileCount} skill files to .claude/skills/pyx-memory/\n\n`);
+  process.stdout.write(`${fileList.join('\n')}\n`);
+  process.stdout.write('\nClaude Code will now auto-discover pyx-memory integration patterns.\n');
+}
 
-// Count copied files
 function countFiles(dir) {
   let count = 0;
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       count += countFiles(join(dir, entry.name));
     } else {
-      count++;
+      count += 1;
     }
   }
   return count;
@@ -55,9 +324,349 @@ function listFiles(dir, prefix = '') {
   return lines;
 }
 
-const fileCount = countFiles(target);
-const fileList = listFiles(target);
+// ---------- Operation subcommands ----------
+
+async function runStore(flags) {
+  if (!flags.content || flags.content === true) {
+    throw new CliError('--content is required', 2);
+  }
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey, json: true });
+
+  const metadata = {};
+  if (flags.topic) metadata.topic = String(flags.topic);
+  if (flags.project) metadata.project = String(flags.project);
+
+  const body = {
+    content: String(flags.content),
+    type: flags.type ? String(flags.type) : 'long-term',
+  };
+  if (Object.keys(metadata).length > 0) body.metadata = metadata;
+  if (flags.source) body.source = String(flags.source);
+  if (flags.importance !== undefined) {
+    const n = Number(flags.importance);
+    if (!Number.isInteger(n) || n < 1 || n > 10) {
+      throw new CliError(
+        `--importance must be an integer in [1,10] (got '${flags.importance}')`,
+        2,
+      );
+    }
+    body.importance = n;
+  }
+  if (flags['event-time']) {
+    const iso = String(flags['event-time']);
+    if (
+      !/^\d{4}-\d{2}-\d{2}T/.test(iso) ||
+      !/(Z|[+-]\d{2}:?\d{2})$/.test(iso) ||
+      !Number.isFinite(new Date(iso).getTime())
+    ) {
+      throw new CliError(
+        `--event-time must be ISO 8601 (e.g. 2026-04-15T10:00:00Z); got '${iso}'`,
+        2,
+      );
+    }
+    body.eventTime = iso;
+  }
+  if (flags.entities !== undefined) body.entities = loadJsonArg(flags.entities, 'entities');
+  if (flags.relationships !== undefined)
+    body.relationships = loadJsonArg(flags.relationships, 'relationships');
+
+  const result = await request('POST', `${endpoint}/api/memory/ingest`, {
+    headers,
+    body: JSON.stringify(body),
+  });
+
+  if (flags.quiet) {
+    const id = (result && result.data && result.data.id) || (result && result.id);
+    if (!id) throw new CliError('--quiet: server response did not contain an id', 1);
+    process.stdout.write(`${id}\n`);
+    return;
+  }
+  emit(result, flags, (r) => {
+    const id = (r && r.data && r.data.id) || (r && r.id) || '<no id>';
+    return `stored ${id}`;
+  });
+}
+
+async function runSearch(flags) {
+  const query = flags.query ?? flags.q;
+  if (!query || query === true) throw new CliError('--query is required', 2);
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey, includeSensitivity: true });
+
+  const params = new URLSearchParams();
+  // Cloud reads `q`; self-hosted reads `query`. Send both for runtime compat.
+  params.set('query', String(query));
+  params.set('q', String(query));
+  if (flags.limit !== undefined) params.set('limit', String(flags.limit));
+  if (flags.strategy) params.set('strategy', String(flags.strategy));
+  if (flags.type) params.set('type', String(flags.type));
+  if (flags['agent-id']) params.set('agentId', String(flags['agent-id']));
+  if (flags['abstention-threshold'] !== undefined) {
+    params.set('abstentionThreshold', String(flags['abstention-threshold']));
+  }
+
+  const result = await request('GET', `${endpoint}/api/memory/search?${params.toString()}`, {
+    headers,
+  });
+
+  emit(result, flags, (r) => {
+    const results = (r && r.data && r.data.results) || (r && r.results) || [];
+    if (!Array.isArray(results) || results.length === 0) return 'no results';
+    return results
+      .map((m, idx) => {
+        const id = m.id ?? '<no id>';
+        const content = (m.content ?? '').slice(0, 100);
+        const score = typeof m.score === 'number' ? ` [score=${m.score.toFixed(3)}]` : '';
+        return `${idx + 1}. ${id}${score}  ${content}`;
+      })
+      .join('\n');
+  });
+}
+
+async function runGet(flags, positional) {
+  const id = positional[0];
+  if (!id) throw new CliError('get: <id> argument is required', 2);
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey });
+  const result = await request('GET', `${endpoint}/api/memory/entries/${encodeURIComponent(id)}`, {
+    headers,
+  });
+  emit(result, flags, (r) => JSON.stringify(r, null, 2));
+}
+
+async function runDelete(flags, positional) {
+  const id = positional[0];
+  if (!id) throw new CliError('delete: <id> argument is required', 2);
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey });
+  const result = await request(
+    'DELETE',
+    `${endpoint}/api/memory/entries/${encodeURIComponent(id)}`,
+    { headers },
+  );
+  emit(result, flags, () => `deleted ${id}`);
+}
+
+async function runLog(flags) {
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey });
+  const params = new URLSearchParams();
+  if (flags.since) params.set('since', String(flags.since));
+  if (flags.limit !== undefined) params.set('limit', String(flags.limit));
+  if (flags.type) params.set('type', String(flags.type));
+  if (flags['agent-id']) params.set('agentId', String(flags['agent-id']));
+  if (flags.source) params.set('source', String(flags.source));
+  const qs = params.toString();
+  const url = `${endpoint}/api/memory/log${qs ? `?${qs}` : ''}`;
+  const result = await request('GET', url, { headers });
+  emit(result, flags, (r) => {
+    const entries = (r && r.data && r.data.entries) || (r && r.entries) || [];
+    if (!Array.isArray(entries) || entries.length === 0) return 'no entries';
+    return entries
+      .map((e) => `${e.createdAt ?? ''}  ${e.id ?? ''}  ${(e.content ?? '').slice(0, 80)}`)
+      .join('\n');
+  });
+}
+
+async function runSummarizeEntity(flags, positional) {
+  const name = positional[0];
+  if (!name) throw new CliError('summarize-entity: <name> argument is required', 2);
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey, json: true });
+  const result = await request('POST', `${endpoint}/api/memory/synthesis/entity`, {
+    headers,
+    body: JSON.stringify({ name }),
+  });
+  emit(result, flags, (r) => {
+    const summary = (r && r.data && r.data.summary) || (r && r.summary);
+    return summary ? `${name}: ${summary}` : JSON.stringify(r);
+  });
+}
+
+async function runIngestFile(flags, positional) {
+  const filePath = positional[0];
+  if (!filePath) throw new CliError('ingest-file: <path> argument is required', 2);
+  const absPath = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
+  let fileStat;
+  try {
+    fileStat = statSync(absPath);
+  } catch (err) {
+    throw new CliError(`ingest-file: cannot stat '${filePath}': ${err.message}`, 2);
+  }
+  if (!fileStat.isFile()) throw new CliError(`ingest-file: '${filePath}' is not a regular file`, 2);
+
+  const { apiKey, endpoint } = resolveAuth(flags);
+  const headers = buildHeaders(flags, { apiKey });
+
+  const buf = readFileSync(absPath);
+  const blob = new Blob([buf]);
+  const form = new FormData();
+  form.append('file', blob, basename(absPath));
+  if (flags.description) form.append('description', String(flags.description));
+  if (flags['namespace-id']) form.append('namespaceId', String(flags['namespace-id']));
+
+  let response;
+  try {
+    response = await fetch(`${endpoint}/api/memory/ingest/file`, {
+      method: 'POST',
+      headers,
+      body: form,
+    });
+  } catch (err) {
+    throw new CliError(`network error: ${err.message}`, 1);
+  }
+
+  // Parse NDJSON stream line-by-line.
+  if (!response.body) {
+    const text = await response.text();
+    throw new CliError(
+      `ingest-file: server returned empty body (HTTP ${response.status}): ${text.slice(0, 200)}`,
+      1,
+    );
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let buffer = '';
+  let terminalEvent = null;
+  let terminalError = null;
 
-console.log(`Copied ${fileCount} skill files to .claude/skills/pyx-memory/\n`);
-console.log(fileList.join('\n'));
-console.log('\nClaude Code will now auto-discover pyx-memory integration patterns.');
+  while (true) {
+    const { value, done } = await reader.read();
+    if (value) buffer += decoder.decode(value, { stream: true });
+    if (done) {
+      buffer += decoder.decode();
+      break;
+    }
+    let nl = buffer.indexOf('\n');
+    while (nl >= 0) {
+      const line = buffer.slice(0, nl).trim();
+      buffer = buffer.slice(nl + 1);
+      if (line) {
+        const event = parseNdjsonLine(line, response.status);
+        const handled = handleEvent(event, flags);
+        if (handled.terminal) {
+          if (event.type === 'error') terminalError = event;
+          else terminalEvent = event;
+        }
+      }
+      nl = buffer.indexOf('\n');
+    }
+  }
+  const tail = buffer.trim();
+  if (tail) {
+    const event = parseNdjsonLine(tail, response.status);
+    const handled = handleEvent(event, flags);
+    if (handled.terminal) {
+      if (event.type === 'error') terminalError = event;
+      else terminalEvent = event;
+    }
+  }
+
+  if (terminalError) {
+    const msg = terminalError.message || terminalError.error || `HTTP ${response.status}`;
+    throw new CliError(`ingest-file error: ${msg}`, 1);
+  }
+  if (!terminalEvent) {
+    throw new CliError(
+      `ingest-file: stream ended without a terminal result (HTTP ${response.status})`,
+      1,
+    );
+  }
+  if (!response.ok) {
+    throw new CliError(`ingest-file: HTTP ${response.status} despite terminal event`, 1);
+  }
+
+  emit(terminalEvent, flags, (r) => {
+    const chunks = r.chunks ?? '?';
+    const fname = r.filename ?? '<file>';
+    return `ingested ${fname}: ${chunks} chunks`;
+  });
+}
+
+function parseNdjsonLine(line, status) {
+  try {
+    return JSON.parse(line);
+  } catch (err) {
+    throw new CliError(`ingest-file: malformed NDJSON line (HTTP ${status}): ${err.message}`, 1);
+  }
+}
+
+function handleEvent(event, flags) {
+  const type = event && event.type;
+  if (type === 'progress' || type === 'heartbeat') {
+    if (!flags.json) {
+      const stage = event.stage ?? '?';
+      const msg = event.message ?? '';
+      process.stderr.write(`[${type}:${stage}] ${msg}\n`);
+    }
+    return { terminal: false };
+  }
+  if (type === 'result' || type === 'error') {
+    return { terminal: true };
+  }
+  // Unknown event type — surface but don't terminate.
+  if (!flags.json) {
+    process.stderr.write(`[event] ${JSON.stringify(event)}\n`);
+  }
+  return { terminal: false };
+}
+
+// ---------- Dispatcher ----------
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const { flags, positional } = parseArgs(argv);
+  const command = positional.shift();
+
+  if (!command || command === '--help' || command === 'help' || (flags.help === true && !command)) {
+    printHelp();
+    return;
+  }
+
+  if (flags.help === true) {
+    printHelp(command);
+    return;
+  }
+
+  switch (command) {
+    case 'init':
+      runInit();
+      return;
+    case 'store':
+      await runStore(flags);
+      return;
+    case 'search':
+      await runSearch(flags);
+      return;
+    case 'get':
+      await runGet(flags, positional);
+      return;
+    case 'delete':
+      await runDelete(flags, positional);
+      return;
+    case 'log':
+      await runLog(flags);
+      return;
+    case 'summarize-entity':
+      await runSummarizeEntity(flags, positional);
+      return;
+    case 'ingest-file':
+      await runIngestFile(flags, positional);
+      return;
+    default:
+      process.stderr.write(`error: unknown command '${command}'\n`);
+      printHelp();
+      process.exit(2);
+  }
+}
+
+main().catch((err) => {
+  if (err instanceof CliError) {
+    process.stderr.write(`error: ${err.message}\n`);
+    process.exit(err.exitCode);
+  }
+  process.stderr.write(`error: ${err && err.stack ? err.stack : String(err)}\n`);
+  process.exit(1);
+});

package/dist/index.d.ts

@@ -356,11 +356,14 @@ declare const VectorProvider: {
 type VectorProvider = (typeof VectorProvider)[keyof typeof VectorProvider];
 declare const EmbeddingProviderName: {
     readonly STUB: "stub";
-    /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
+    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
     readonly ANTHROPIC: "anthropic";
-    /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
+    /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
     readonly OPENAI: "openai";
+    /** In-process ONNX model (default: EmbeddingGemma-300M). */
     readonly LOCAL: "local";
+    /** Remote OpenAI-compatible embedding service (pyx-cloud shared, custom, etc.). */
+    readonly HTTP: "http";
 };
 type EmbeddingProviderName = (typeof EmbeddingProviderName)[keyof typeof EmbeddingProviderName];
 interface MemoryEntry {

package/dist/index.mjs

@@ -40,11 +40,14 @@ var VectorProvider = {
 };
 var EmbeddingProviderName = {
   STUB: "stub",
-  /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
+  /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
   ANTHROPIC: "anthropic",
-  /** @deprecated Vestigial — pyx-memory uses internal BGE-M3 embeddings. */
+  /** @deprecated Vestigial — pyx-memory uses internal EmbeddingGemma embeddings. */
   OPENAI: "openai",
-  LOCAL: "local"
+  /** In-process ONNX model (default: EmbeddingGemma-300M). */
+  LOCAL: "local",
+  /** Remote OpenAI-compatible embedding service (pyx-cloud shared, custom, etc.). */
+  HTTP: "http"
 };
 var StoreTarget = {
   SQLITE: "sqlite",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pyxmate/memory",
-  "version": "0.19.1",
+  "version": "0.20.5",
   "type": "module",
   "description": "SDK for pyx-memory — Memory as a Service for AI agents",
   "license": "MIT",

package/skills/pyx-memory/SKILL.md

@@ -37,6 +37,9 @@ Your endpoint and API key are in the project's CLAUDE.md or agent config. Look f
 
 If no credentials are configured, skip to [SDK Integration](#sdk-integration) below.
 
+Operations below use the `pyxmate-memory` CLI (ships with `@pyxmate/memory`).
+Set `PYXMATE_API_KEY` and `PYXMATE_ENDPOINT` once; for multi-tenant servers add `--tenant-id <id>`.
+
 ## Store: after important events
 
 Immediately after any of these events, store a memory before continuing:
@@ -50,23 +53,11 @@ Immediately after any of these events, store a memory before continuing:
 - **The user explicitly says "remember this"** → store immediately
 
 ```bash
-curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -H "Content-Type: application/json" \
-  -d '{"content":"WHAT_HAPPENED","type":"long-term","metadata":{"source":"agent","topic":"TOPIC","project":"PROJECT_NAME"}}'
-```
-
-**Multi-tenant mode**: When the server uses `TENANT_MODE=multi`, include `X-Tenant-Id` on all requests:
-
-```bash
-curl -s -X POST {{ENDPOINT}}/api/memory/ingest \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -H "Content-Type: application/json" \
-  -H "X-Tenant-Id: {{TENANT_ID}}" \
-  -d '{"content":"WHAT_HAPPENED","type":"long-term","metadata":{"source":"agent","topic":"TOPIC","project":"PROJECT_NAME"}}'
+pyxmate-memory store \
+  --content "WHAT_HAPPENED" --topic TOPIC --project PROJECT_NAME --source agent
 ```
 
-When the memory mentions specific people, tools, organizations, or other named subjects, also include `entities` and `relationships` to populate the knowledge graph. See [reference/http-api.md](reference/http-api.md) for entity types, relationship types, and examples.
+When the memory mentions named people, tools, or organizations, pass `--entities '<json>'` and `--relationships '<json>'` (or `@path.json` / `-` for stdin) to populate the knowledge graph. See [reference/http-api.md](reference/http-api.md) for entity and relationship types.
 
 ## Search: before making assumptions
 
@@ -78,12 +69,9 @@ Search for relevant context in these situations:
 - **Investigating a bug** → search if it was seen before
 
 ```bash
-curl -s "{{ENDPOINT}}/api/memory/search?q=QUERY&limit=5" \
-  -H "Authorization: Bearer {{API_KEY}}"
+pyxmate-memory search --query "QUERY" --limit 5
 ```
 
-**Multi-tenant mode**: Add `-H "X-Tenant-Id: {{TENANT_ID}}"` to scope search results to the tenant.
-
 ## Ingest files & images: when a file is worth remembering
 
 Upload files directly when the content is worth persisting — diagrams, screenshots, documents, data files.
@@ -93,10 +81,7 @@ Upload files directly when the content is worth persisting — diagrams, screens
 - **A document contains reference material** (spec, config, report) → ingest it
 
 ```bash
-curl -s -X POST {{ENDPOINT}}/api/memory/ingest/file \
-  -H "Authorization: Bearer {{API_KEY}}" \
-  -F "file=@path/to/file" \
-  -F "description=What this file contains or shows"
+pyxmate-memory ingest-file path/to/file --description "What this file contains or shows"
 ```
 
 Supported formats: txt, md, csv, tsv, log, pdf, docx, xlsx, pptx, json, jsonl, html, htm, png, jpg, jpeg, webp, gif, bmp, tiff, svg (100MB limit).