aismemory 0.7.4 → 0.8.0

package/dist/cli/pull-memory.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+/**
+ * `aismemory pull` — copy this agent's memories from the Agent Identity Service
+ * into a local JSON Lines backup file (CORBOT-31C43CBD).
+ *
+ * The counterpart of `aismemory sync`. Sync pushes local files up; this pulls
+ * the service's copy down, so memories written from anywhere — the Claude app,
+ * Codex, another machine — end up in the local backup too.
+ *
+ * Reads only the calling agent's own memories, over a route a scoped agent API
+ * key may already call. No server change, no widened key scope.
+ *
+ * Usage:
+ *   AIS_AGENT_ID=... AIS_API_KEY=... npx aismemory pull
+ *   npx aismemory pull --out ./backup.jsonl
+ *   npx aismemory pull --page-size 50 --quiet
+ *
+ * Exit codes:
+ *   0 — backup written
+ *   1 — configuration missing, or the service refused or failed the read
+ */
+import { realpathSync, mkdirSync, writeFileSync, renameSync, unlinkSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { pathToFileURL } from 'node:url';
+import { loadAgentApiKeyConfig, AgentApiKeyConfigError } from '../agent-key-mode.js';
+import { DEFAULT_AIS_URL } from '../ais-http.js';
+import { pullMemories, toJsonLines, describePullFailure, MAX_PAGE_SIZE, } from '../memory-pull.js';
+const USAGE = `aismemory pull — copy this agent's memories into a local JSON Lines backup
+
+Usage:
+  aismemory pull [options]
+
+Options:
+  --out <path>        Where to write the backup.
+                      Default: ~/.aismemory/backups/<agent id>.jsonl
+  --page-size <n>     Memories per request (1-${MAX_PAGE_SIZE}). Default: ${MAX_PAGE_SIZE}.
+  --quiet             Only report the final line.
+  --help, -h          Show this message.
+
+Environment:
+  AIS_AGENT_ID        The agent to pull (required).
+  AIS_API_KEY         That agent's scoped API key (required).
+  AIS_URL             Agent Identity Service base URL.
+                      Default: ${DEFAULT_AIS_URL}
+
+Only this agent's own memories are ever read.
+`;
+export function parseArgs(argv) {
+    const args = { quiet: false, help: false };
+    for (let i = 0; i < argv.length; i++) {
+        const flag = argv[i];
+        if (flag === '--out' && argv[i + 1]) {
+            args.out = argv[++i];
+        }
+        else if (flag === '--page-size' && argv[i + 1]) {
+            const raw = argv[++i];
+            const parsed = Number(raw);
+            if (!Number.isInteger(parsed) || parsed < 1 || parsed > MAX_PAGE_SIZE) {
+                throw new Error(`--page-size must be a whole number between 1 and ${MAX_PAGE_SIZE} (got "${raw}")`);
+            }
+            args.pageSize = parsed;
+        }
+        else if (flag === '--quiet') {
+            args.quiet = true;
+        }
+        else if (flag === '--help' || flag === '-h') {
+            args.help = true;
+        }
+        else {
+            throw new Error(`Unknown option: ${flag}. Run aismemory pull --help.`);
+        }
+    }
+    return args;
+}
+/** Default backup location for an agent. */
+export function defaultBackupPath(agentId, home = homedir()) {
+    return join(home, '.aismemory', 'backups', `${agentId}.jsonl`);
+}
+/**
+ * Write the backup atomically: a crash or a failed pull must never leave a
+ * half-written file where a complete earlier backup used to be.
+ */
+export function writeBackupFile(filePath, contents) {
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const tmp = `${filePath}.tmp`;
+    try {
+        writeFileSync(tmp, contents, { mode: 0o600 });
+        renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Nothing to clean up.
+        }
+        throw err;
+    }
+}
+export async function main(argv = process.argv.slice(2)) {
+    const args = parseArgs(argv);
+    if (args.help) {
+        process.stdout.write(USAGE);
+        return;
+    }
+    const config = loadAgentApiKeyConfig();
+    if (!config) {
+        throw new Error('AIS_API_KEY is not set. aismemory pull needs an agent API key and AIS_AGENT_ID ' +
+            'so it can read that agent\'s own memories.');
+    }
+    const aisUrl = (process.env['AIS_URL']?.trim() || DEFAULT_AIS_URL).replace(/\/+$/, '');
+    const outPath = args.out ? resolve(args.out) : defaultBackupPath(config.agentId);
+    const onProgress = args.quiet
+        ? undefined
+        : (progress) => {
+            const of = progress.totalCount === undefined ? '' : ` of ${progress.totalCount}`;
+            process.stderr.write(`[aismemory pull] page ${progress.page}: ${progress.total}${of} memories\n`);
+        };
+    const result = await pullMemories(onProgress === undefined
+        ? { aisUrl, agentId: config.agentId, apiKey: config.apiKey, pageSize: args.pageSize }
+        : { aisUrl, agentId: config.agentId, apiKey: config.apiKey, pageSize: args.pageSize, onProgress });
+    writeBackupFile(outPath, toJsonLines(result.memories));
+    process.stdout.write(`Wrote ${result.memories.length} memories to ${outPath}\n`);
+    if (result.truncated) {
+        process.stderr.write('[aismemory pull] Warning: stopped at the page limit; the backup may be incomplete.\n');
+    }
+    else if (result.totalCount !== undefined && result.totalCount !== result.memories.length) {
+        // Not an error: memories written or deleted mid-walk move the count.
+        process.stderr.write(`[aismemory pull] Note: the service reported ${result.totalCount} memories and ${result.memories.length} were pulled; ` +
+            'the corpus changed while the backup was running.\n');
+    }
+}
+if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+    main().catch((err) => {
+        const message = err instanceof AgentApiKeyConfigError ? err.message : describePullFailure(err);
+        process.stderr.write(`[aismemory pull] Failed: ${message}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=pull-memory.js.map

package/dist/cli/pull-memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-memory.js","sourceRoot":"","sources":["../../src/cli/pull-memory.ts"],"names":[],"mappings":"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"}