@openanonymity/nanomem 0.1.0

package/src/cli/commands.js

@@ -0,0 +1,411 @@
+/**
+ * CLI command implementations — thin wrappers around the library API.
+ */
+
+import { readFile, writeFile, readdir, stat } from 'node:fs/promises';
+import { resolve, join } from 'node:path';
+import { serialize, toZip } from '../utils/portability.js';
+import { safeDateIso } from '../bullets/normalize.js';
+import { extractSessionsFromOAFastchatExport } from '../imports/oaFastchat.js';
+import { isChatGptExport, parseChatGptExport } from '../imports/chatgpt.js';
+import { parseMarkdownFiles } from '../imports/markdown.js';
+import { loginInteractive } from './auth.js';
+import { writeConfigFile, CONFIG_PATH } from './config.js';
+import { createSpinner } from './spinner.js';
+import { printFileDiff } from './diff.js';
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf-8');
+}
+
+async function readMarkdownDir(dirPath) {
+    const entries = await readdir(dirPath, { recursive: true });
+    const files = [];
+    for (const entry of entries) {
+        if (!entry.endsWith('.md')) continue;
+        const fullPath = join(dirPath, entry);
+        const info = await stat(fullPath);
+        if (!info.isFile()) continue;
+        const content = await readFile(fullPath, 'utf-8');
+        files.push({ path: entry, content });
+    }
+    return files;
+}
+
+function buildExportPath(format) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const ext = format === 'zip' ? 'zip' : 'txt';
+    return resolve(process.cwd(), `memory-export-${stamp}.${ext}`);
+}
+
+/**
+ * Parse input into one or more conversations.
+ * Returns [{ title, messages }] to handle both single and multi-session inputs.
+ *
+ * Auto-detects:
+ *   1. OA Fastchat export  → { data: { chats: { sessions, messages } } }
+ *   2. ChatGPT export      → [{ mapping, current_node, title, ... }]
+ *   3. JSON messages array  → [{ role, content }]
+ *   4. Plain text           → User: / Assistant: line format
+ */
+function parseConversations(input, flags) {
+    const trimmed = input.trim();
+
+    // Try JSON
+    try {
+        const parsed = JSON.parse(trimmed);
+
+        // OA Fastchat export
+        if (parsed?.data?.chats?.sessions) {
+            const sessions = extractSessionsFromOAFastchatExport(parsed, {
+                sessionId: flags['session-id'],
+                sessionTitle: flags['session-title'],
+            });
+            return sessions.map(s => ({
+                title: s.session.title || s.session.id || 'untitled',
+                messages: s.conversation,
+                updatedAt: safeDateIso(s.session.updatedAt),
+            }));
+        }
+
+        // ChatGPT export (conversations.json)
+        if (isChatGptExport(parsed)) {
+            return parseChatGptExport(parsed);
+        }
+
+        // Plain messages array
+        if (Array.isArray(parsed)) {
+            return [{ title: null, messages: parsed }];
+        }
+    } catch { /* fall through to text parsing */ }
+
+    // Parse User: / Assistant: format
+    const messages = [];
+    const lines = trimmed.split('\n');
+    let current = null;
+    for (const line of lines) {
+        const userMatch = line.match(/^User:\s*(.*)/i);
+        const asstMatch = line.match(/^Assistant:\s*(.*)/i);
+        if (userMatch) {
+            if (current) messages.push(current);
+            current = { role: 'user', content: userMatch[1] };
+        } else if (asstMatch) {
+            if (current) messages.push(current);
+            current = { role: 'assistant', content: asstMatch[1] };
+        } else if (current) {
+            current.content += '\n' + line;
+        }
+    }
+    if (current) messages.push(current);
+
+    if (messages.length === 0) {
+        // Fallback: treat as plain markdown notes to extract facts from
+        return parseMarkdownFiles(trimmed);
+    }
+    return [{ title: null, messages }];
+}
+
+// ─── Commands ────────────────────────────────────────────────────
+
+export async function init(positionals, flags, mem, config) {
+    await mem.init();
+    return { status: 'initialized', storage: config.storage, path: config.storagePath };
+}
+
+export async function retrieve(positionals, flags, mem) {
+    const query = positionals[0];
+    if (!query) throw new Error('Usage: memory retrieve <query>');
+
+    await mem.init();
+
+    let conversationText = null;
+    if (flags.context) {
+        conversationText = await readFile(flags.context, 'utf-8');
+    }
+
+    const result = await mem.retrieve(query, conversationText);
+    if (!result || !result.assembledContext) {
+        return { assembledContext: null, message: 'No relevant context found.' };
+    }
+    return result;
+}
+
+export async function importCmd(positionals, flags, mem, config, { showProgress, spinnerHolder } = {}) {
+    const source = positionals[0];
+    let conversations;
+    let extractionMode = 'conversation';
+
+    if (source === '-' || (!source && !process.stdin.isTTY)) {
+        conversations = parseConversations(await readStdin(), flags);
+    } else if (source) {
+        const info = await stat(source);
+        if (info.isDirectory()) {
+            const files = await readMarkdownDir(source);
+            if (files.length === 0) throw new Error(`No .md files found in ${source}`);
+            conversations = parseMarkdownFiles(files);
+            extractionMode = 'document';
+        } else {
+            conversations = parseConversations(await readFile(source, 'utf-8'), flags);
+            if (flags.format === 'markdown') extractionMode = 'document';
+        }
+    } else {
+        throw new Error('Usage: memory import <file|dir|->');
+    }
+
+    return ingestConversations(conversations, extractionMode, mem, { showProgress, spinnerHolder, status: 'imported' });
+}
+
+export async function add(positionals, flags, mem, config, { showProgress, spinnerHolder } = {}) {
+    const input = positionals[0] ?? (!process.stdin.isTTY ? await readStdin() : null);
+    if (!input) throw new Error('Usage: memory add <text>');
+
+    const conversations = parseConversations(input, flags);
+    return ingestConversations(conversations, 'conversation', mem, { showProgress, spinnerHolder, status: 'added', showDiff: true });
+}
+
+async function ingestConversations(conversations, extractionMode, mem, { showProgress, spinnerHolder, status, showDiff = false }) {
+    await mem.init();
+
+    const total = conversations.length;
+    let totalWriteCalls = 0;
+    const results = [];
+
+    const isTTY = process.stderr.isTTY;
+    const c = isTTY ? { green: '\x1b[32m', yellow: '\x1b[33m', dim: '\x1b[2m', bold: '\x1b[1m', reset: '\x1b[0m', gray: '\x1b[90m' }
+                    : { green: '', yellow: '', dim: '', bold: '', reset: '', gray: '' };
+
+    for (let i = 0; i < total; i++) {
+        const conv = conversations[i];
+        const label = conv.title || `conversation ${i + 1}`;
+
+        if (showProgress) {
+            const counter = total > 1 ? `${c.gray}(${i + 1}/${total})${c.reset} ` : '';
+            process.stderr.write(`\n  ${counter}${c.bold}"${label}"${c.reset}\n`);
+        }
+
+        let spinner = null;
+        if (showProgress && isTTY) {
+            spinner = createSpinner('thinking…');
+            if (spinnerHolder) spinnerHolder.current = spinner;
+        }
+
+        const result = await mem.ingest(conv.messages, { updatedAt: conv.updatedAt, extractionMode });
+
+        if (spinnerHolder) spinnerHolder.current = null;
+        if (showProgress) {
+            if (result.status === 'error') {
+                spinner?.stop(`  ${c.yellow}⚠ ${result.error}${c.reset}`);
+            } else if (result.writeCalls > 0) {
+                spinner?.stop(`  ${c.green}✓ ${result.writeCalls} fact${result.writeCalls === 1 ? '' : 's'} saved${c.reset}`);
+            } else {
+                spinner?.stop(`  ${c.dim}– nothing to save${c.reset}`);
+            }
+            if (showDiff && result.writes?.length) {
+                for (const { path, before, after } of result.writes) {
+                    printFileDiff(path, before, after);
+                }
+            }
+        }
+
+        totalWriteCalls += result.writeCalls || 0;
+        results.push({ session: label, messages: conv.messages.length, writeCalls: result.writeCalls, error: result.error });
+    }
+
+    return { status, sessions: results.length, totalWriteCalls, details: results };
+}
+
+export async function compact(positionals, flags, mem) {
+    await mem.init();
+    const stats = await mem.compact();
+    return { status: 'compacted', filesChanged: stats?.filesChanged ?? 0, filesTotal: stats?.filesTotal ?? 0 };
+}
+
+export async function ls(positionals, flags, mem) {
+    await mem.init();
+    return mem.storage.ls(positionals[0] || '');
+}
+
+export async function read(positionals, flags, mem) {
+    const path = positionals[0];
+    if (!path) throw new Error('Usage: memory read <path>');
+
+    await mem.init();
+    const content = await mem.storage.read(path);
+    if (content == null) {
+        throw new Error(`File not found: ${path}`);
+    }
+    return { path, content };
+}
+
+export async function write(positionals, flags, mem) {
+    const path = positionals[0];
+    if (!path) throw new Error('Usage: memory write <path>');
+
+    let content;
+    if (flags.content != null) {
+        content = flags.content;
+    } else if (!process.stdin.isTTY) {
+        content = await readStdin();
+    } else {
+        throw new Error('Provide content via --content or stdin.');
+    }
+
+    await mem.init();
+    await mem.storage.write(path, content);
+    return { status: 'written', path };
+}
+
+export async function del(positionals, flags, mem) {
+    const path = positionals[0];
+    if (!path) throw new Error('Usage: memory delete <path>');
+
+    await mem.init();
+    await mem.storage.delete(path);
+    return { status: 'deleted', path };
+}
+
+export async function search(positionals, flags, mem) {
+    const query = positionals[0];
+    if (!query) throw new Error('Usage: memory search <query>');
+
+    await mem.init();
+    const results = await mem.storage.search(query);
+    results._query = query;
+    return results;
+}
+
+export async function exportCmd(positionals, flags, mem) {
+    const format = flags.format || 'txt';
+    await mem.init();
+    const all = await mem.storage.exportAll();
+    const files = all.filter(f => !f.path.endsWith('_tree.md'));
+    const exportPath = buildExportPath(format);
+
+    if (format === 'zip') {
+        const zip = toZip(all);
+        await writeFile(exportPath, zip);
+    } else {
+        await writeFile(exportPath, serialize(all), 'utf-8');
+    }
+
+    return { status: 'exported', files: files.length, format, path: exportPath };
+}
+
+
+
+export async function clear(positionals, flags, mem, config) {
+    await mem.init();
+    const all = await mem.storage.exportAll();
+    const files = all.filter(f => !f.path.endsWith('_tree.md'));
+
+    if (!flags.confirm) {
+        throw new Error(`This will delete ${files.length} file${files.length === 1 ? '' : 's'} in ${config.storagePath}. Run with --confirm to proceed.`);
+    }
+
+    await mem.storage.clear();
+    return { status: 'cleared', filesDeleted: files.length, path: config.storagePath };
+}
+
+export async function status(positionals, flags, mem, config) {
+    await mem.init();
+    const all = await mem.storage.exportAll();
+    const files = all.filter(f => !f.path.endsWith('_tree.md'));
+
+    const dirs = new Set();
+    for (const f of files) {
+        const slash = f.path.indexOf('/');
+        if (slash !== -1) dirs.add(f.path.slice(0, slash));
+    }
+
+    return {
+        provider: config.provider,
+        model: config.model,
+        baseUrl: config.baseUrl,
+        storage: config.storage,
+        storagePath: config.storagePath,
+        configFile: CONFIG_PATH,
+        files: files.length,
+        directories: [...dirs].sort(),
+    };
+}
+
+export async function tree(positionals, flags, mem, config) {
+    await mem.init();
+    const all = await mem.storage.exportAll();
+    const files = all
+        .filter(f => !f.path.endsWith('_tree.md'))
+        .sort((a, b) => a.path.localeCompare(b.path));
+
+    if (files.length === 0) {
+        return { treeLines: [] };
+    }
+
+    // Group by top-level directory
+    const grouped = new Map(); // dir → [file]
+    for (const f of files) {
+        const slash = f.path.indexOf('/');
+        const dir = slash !== -1 ? f.path.slice(0, slash) : '';
+        const name = slash !== -1 ? f.path.slice(slash + 1) : f.path;
+        if (!grouped.has(dir)) grouped.set(dir, []);
+        grouped.get(dir).push({ ...f, name });
+    }
+
+    const isTTY = process.stdout.isTTY;
+    const c = isTTY ? {
+        reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+        cyan: '\x1b[36m', green: '\x1b[32m', gray: '\x1b[90m', yellow: '\x1b[33m',
+    } : Object.fromEntries(['reset','bold','dim','cyan','green','gray','yellow'].map(k => [k, '']));
+
+    const lines = [];
+    lines.push('');
+    lines.push(`  ${c.bold}Memory${c.reset}  ${c.dim}${config.storagePath}${c.reset}`);
+    lines.push('');
+
+    const dirs = [...grouped.keys()].sort();
+    for (const dir of dirs) {
+        const entries = grouped.get(dir);
+
+        if (dir) {
+            lines.push(`  ${c.cyan}${dir}/${c.reset}`);
+        }
+
+        const prefix = dir ? '  ' : '';
+        for (let i = 0; i < entries.length; i++) {
+            const f = entries[i];
+            const isLast = i === entries.length - 1;
+            const branch = entries.length === 1 ? '──' : isLast ? '└─' : '├─';
+            const count = f.itemCount != null ? `${c.green}${String(f.itemCount).padStart(3)} facts${c.reset}` : '';
+            const hint  = f.oneLiner ? `  ${c.dim}${f.oneLiner.slice(0, 60)}${f.oneLiner.length > 60 ? '…' : ''}${c.reset}` : '';
+            const fname = f.name.replace(/\.md$/, '');
+            lines.push(`  ${prefix}${c.gray}${branch}${c.reset} ${c.bold}${fname}${c.reset}  ${count}${hint}`);
+        }
+        lines.push('');
+    }
+
+    const totalFacts = files.reduce((n, f) => n + (f.itemCount || 0), 0);
+    lines.push(`  ${c.dim}${files.length} file${files.length === 1 ? '' : 's'}  ·  ${totalFacts} facts total${c.reset}`);
+    lines.push('');
+
+    return { treeLines: lines };
+}
+
+export async function login(positionals, flags, mem, config) {
+    // Non-interactive mode: --api-key provided as a flag
+    if (flags['api-key']) {
+        const toSave = {
+            provider: flags.provider || config.provider,
+            apiKey: flags['api-key'],
+            storage: flags.storage || (flags.path ? 'filesystem' : null) || config.storage || 'filesystem',
+        };
+        if (flags.model) toSave.model = flags.model;
+        if (flags.path)  toSave.storagePath = flags.path;
+        await writeConfigFile(toSave);
+        return { status: 'logged_in', provider: toSave.provider, configFile: CONFIG_PATH };
+    }
+
+    return loginInteractive();
+}

package/src/cli/config.js

@@ -0,0 +1,120 @@
+/**
+ * CLI config resolution — flags + config file + env vars → createMemoryBank config.
+ *
+ * Config lives at ~/.config/nanomem/config.json (fixed location).
+ * Memory data lives at ~/nanomem by default (configurable via login or --path).
+ *
+ * Priority (highest wins):
+ *   CLI flags  >  config file  >  env vars  >  preset defaults
+ */
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { createMemoryBank } from '../index.js';
+
+// ─── Paths ──────────────────────────────────────────────────────
+
+export const CONFIG_DIR = join(homedir(), '.config', 'nanomem');
+export const CONFIG_PATH = join(CONFIG_DIR, 'config.json');
+export const DEFAULT_STORAGE_PATH = join(homedir(), 'nanomem');
+
+// ─── Config file ────────────────────────────────────────────────
+
+export async function readConfigFile() {
+    try {
+        const raw = await readFile(CONFIG_PATH, 'utf-8');
+        return JSON.parse(raw);
+    } catch {
+        return {};
+    }
+}
+
+export async function writeConfigFile(data) {
+    await mkdir(CONFIG_DIR, { recursive: true });
+    const existing = await readConfigFile();
+    const merged = { ...existing, ...data };
+    await writeFile(CONFIG_PATH, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+}
+
+// ─── Provider presets ───────────────────────────────────────────
+
+const PRESETS = {
+    tinfoil: { envKey: 'TINFOIL_API_KEY', baseUrl: 'https://inference.tinfoil.sh/v1', model: 'kimi-k2-5' },
+    openai: { envKey: 'OPENAI_API_KEY', baseUrl: 'https://api.openai.com/v1', model: 'gpt-5.4-mini' },
+    anthropic: { envKey: 'ANTHROPIC_API_KEY', baseUrl: 'https://api.anthropic.com', model: 'claude-sonnet-4-6', isAnthropic: true },
+    openrouter: {
+        envKey: 'OPENROUTER_API_KEY', baseUrl: 'https://openrouter.ai/api/v1', model: 'openai/gpt-4o',
+        headers: { 'HTTP-Referer': 'https://github.com/openanonymity/nanomem', 'X-Title': 'nanomem' }
+    },
+    custom: { envKey: null, baseUrl: null, model: null },
+};
+
+// ─── Resolve config ─────────────────────────────────────────────
+
+export async function resolveConfig(flags) {
+    const fileConfig = await readConfigFile();
+
+    // 1. Pick provider
+    let providerName = flags.provider || fileConfig.provider || process.env.LLM_PROVIDER || null;
+    let preset;
+    if (providerName) {
+        preset = PRESETS[providerName];
+        if (!preset) {
+            throw new Error(`Unknown provider: ${providerName}. Use: ${Object.keys(PRESETS).join(', ')}`);
+        }
+    } else {
+        const match = Object.entries(PRESETS).find(([, p]) => p.envKey && process.env[p.envKey]);
+        providerName = match ? match[0] : 'openai';
+        preset = match ? match[1] : PRESETS.openai;
+    }
+
+    // 2. Resolve fields — flags > config file > env vars > preset defaults
+    const apiKey = flags['api-key'] || fileConfig.apiKey || process.env.LLM_API_KEY || (preset.envKey && process.env[preset.envKey]) || null;
+    const baseUrl = flags['base-url'] || fileConfig.baseUrl || process.env.LLM_BASE_URL || preset.baseUrl;
+    const model = flags.model || fileConfig.model || process.env.LLM_MODEL || preset.model;
+    const headers = preset.headers || null;
+    const storage = flags.storage || (flags.path ? 'filesystem' : null) || fileConfig.storage || 'filesystem';
+    const rawPath = flags.path || fileConfig.storagePath || DEFAULT_STORAGE_PATH;
+    const storagePath = rawPath.startsWith('~/') ? join(homedir(), rawPath.slice(2)) : rawPath;
+
+    return { apiKey, baseUrl, model, headers, provider: providerName, isAnthropic: !!preset.isAnthropic, storage, storagePath };
+}
+
+// ─── Create a memory instance from resolved config ──────────────
+
+const LLM_COMMANDS = new Set(['retrieve', 'extract', 'compact', 'import', 'add']);
+
+export function createMemoryFromConfig(config, command, { onToolCall, onProgress, onCompactProgress } = {}) {
+    const needsLlm = LLM_COMMANDS.has(command);
+
+    if (needsLlm && !config.apiKey) {
+        throw new Error(
+            'No API key configured. Run `memory login` to get started.'
+        );
+    }
+
+    const opts = {
+        storage: config.storage,
+        storagePath: config.storagePath,
+    };
+
+    if (needsLlm) {
+        opts.llm = {
+            apiKey: config.apiKey,
+            baseUrl: config.baseUrl,
+            model: config.model,
+            provider: config.isAnthropic ? 'anthropic' : config.provider,
+            ...(config.headers ? { headers: config.headers } : {}),
+        };
+        if (onToolCall) opts.onToolCall = onToolCall;
+        if (onProgress) opts.onProgress = onProgress;
+        if (onCompactProgress) opts.onCompactProgress = onCompactProgress;
+    } else {
+        opts.llmClient = {
+            createChatCompletion() { throw new Error('This command requires an API key.'); },
+        };
+    }
+
+    return createMemoryBank(opts);
+}

package/src/cli/diff.js

@@ -0,0 +1,68 @@
+/**
+ * Terminal diff rendering using @pierre/diffs.
+ */
+
+import { parseDiffFromFile } from '@pierre/diffs';
+
+const R = '\x1b[0m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const RED = '\x1b[31m';
+const GRAY = '\x1b[90m';
+
+/**
+ * Render a file diff to stderr as ANSI-colored terminal output.
+ * Returns early and silently if not a TTY or nothing changed.
+ *
+ * @param {string} path
+ * @param {string} before
+ * @param {string} after
+ */
+export function printFileDiff(path, before, after) {
+    if (!process.stderr.isTTY) return;
+    if (before === after) return;
+
+    let fileMeta;
+    try {
+        fileMeta = parseDiffFromFile(
+            { name: path, contents: before },
+            { name: path, contents: after },
+            { context: 2 },
+        );
+    } catch {
+        return;
+    }
+
+    const { hunks, additionLines, deletionLines } = fileMeta;
+    if (!hunks?.length) return;
+
+    const isNew = !before;
+    const action = isNew ? 'new file' : 'modified';
+
+    process.stderr.write(`\n  ${BOLD}${CYAN}${path}${R}  ${DIM}${action}${R}\n`);
+
+    for (const hunk of hunks) {
+        const header = (hunk.hunkSpecs || '').trim();
+        process.stderr.write(`  ${GRAY}${header}${R}\n`);
+
+        for (const seg of hunk.hunkContent) {
+            if (seg.type === 'context') {
+                for (let i = 0; i < seg.lines; i++) {
+                    const line = (additionLines[seg.additionLineIndex + i] ?? '').replace(/\n$/, '');
+                    process.stderr.write(`  ${DIM}  ${line}${R}\n`);
+                }
+            } else {
+                for (let i = 0; i < seg.deletions; i++) {
+                    const line = (deletionLines[seg.deletionLineIndex + i] ?? '').replace(/\n$/, '');
+                    process.stderr.write(`  ${RED}- ${line}${R}\n`);
+                }
+                for (let i = 0; i < seg.additions; i++) {
+                    const line = (additionLines[seg.additionLineIndex + i] ?? '').replace(/\n$/, '');
+                    process.stderr.write(`  ${GREEN}+ ${line}${R}\n`);
+                }
+            }
+        }
+    }
+}

package/src/cli/help.js

@@ -0,0 +1,84 @@
+/**
+ * CLI help text.
+ */
+
+export const GLOBAL_HELP = `Usage: nanomem <command> [args] [flags]
+
+Commands:
+
+  Setup:
+    login                                   Configure provider, model, API key, and storage path
+    status                                  Show current config and storage stats
+
+  Memory:
+    add <text>                              Add raw text directly and extract facts
+    import <file|dir|->                     Import conversations or notes and extract facts
+    retrieve <query> [--context <file>]     Retrieve relevant context for a query
+    compact                                 Deduplicate and archive stale facts
+    export [--format txt|zip]               Export all memory to a file
+
+  Storage:
+    ls [path]                               List files and directories
+    read <path>                             Read a file
+    write <path> --content <text>           Write content to a file (or pipe stdin)
+    delete <path>                           Delete a file
+    search <query>                          Search files by keyword
+    clear --confirm                         Delete all memory files
+
+Flags:
+  --api-key <key>         LLM API key
+  --model <model>         Model ID
+  --provider <name>       Provider: openai | anthropic | tinfoil | custom
+  --base-url <url>        Custom API endpoint
+  --path <dir>            Storage directory (default: ~/nanomem)
+  --json                  Force JSON output
+  --render                Render markdown for terminal output
+  -h, --help              Show help
+  -v, --version           Show version
+
+Examples:
+  nanomem login
+  nanomem add "User: I moved to Seattle."
+  nanomem import conversations.json
+  nanomem import my-notes.md
+  nanomem import ./notes/
+  nanomem retrieve "what are my hobbies?"
+  nanomem status
+  nanomem export --format zip
+`;
+
+export const COMMAND_HELP = {
+    add: 'Usage: nanomem add <text>\n\nAdd raw text directly and extract facts into memory.\nAccepts quoted text or piped stdin.\nRequires an LLM API key.',
+    retrieve: 'Usage: nanomem retrieve <query> [--context <file>]\n\nRetrieve relevant memory context for a query.\nRequires an LLM API key.',
+    compact: 'Usage: nanomem compact\n\nDeduplicate and archive stale facts across all memory files.\nRequires an LLM API key.',
+    ls: 'Usage: nanomem ls [path]\n\nList files and directories in storage.',
+    read: 'Usage: nanomem read <path>\n\nRead a file from storage.\nUse --render to format markdown files for terminal display.',
+    write: 'Usage: nanomem write <path> [--content <text>]\n\nWrite content to a file. Reads from stdin if --content is not provided.',
+    delete: 'Usage: nanomem delete <path>\n\nDelete a file from storage.',
+    search: 'Usage: nanomem search <query>\n\nSearch files by keyword.',
+    export: 'Usage: nanomem export [--format txt|zip]\n\nExport all memory to a timestamped file in the current directory.\nDefault format is txt (line-delimited text). Use --format zip for a ZIP archive.',
+    import: `Usage: nanomem import <file|dir|->
+
+Import conversations or notes and extract facts into memory.
+
+Auto-detects format:
+  - ChatGPT export (conversations.json from "Export data")
+  - OA Fastchat export (JSON with data.chats.sessions)
+  - JSON messages array ([{role, content}, ...])
+  - Plain text (User:/Assistant: lines)
+  - Markdown notes (splits by top-level headings)
+  - Directory (imports all .md files recursively)
+
+For multi-session exports, use --session-id or --session-title to filter.
+Requires an LLM API key.`,
+    clear: 'Usage: nanomem clear --confirm\n\nDelete all memory files. Requires --confirm to prevent accidental data loss.',
+    status: 'Usage: nanomem status\n\nShow resolved config and storage statistics.',
+    login: `Usage: nanomem login
+
+Walks you through provider, model, API key, and storage path.
+Config is saved to ~/.nanomem/config.json.
+
+Non-interactive (for agents/scripts):
+  nanomem login --provider openai --api-key sk-... --model gpt-5.4-mini
+  nanomem login --provider anthropic --api-key sk-ant-... --path ~/project/memory`,
+};