memax-cli 0.0.1 → 0.1.0-alpha.10

package/src/index.ts

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join, dirname } from "node:path";
+import { pushCommand } from "./commands/push.js";
+import { recallCommand } from "./commands/recall.js";
+import { listCommand } from "./commands/list.js";
+import { showCommand } from "./commands/show.js";
+import { deleteCommand } from "./commands/delete.js";
+import { syncCommand, syncAgentMemoryCommand } from "./commands/sync.js";
+import { hookCommand } from "./commands/hook.js";
+import { configGetCommand, configSetCommand } from "./commands/config.js";
+import {
+  loginCommand,
+  logoutCommand,
+  whoamiCommand,
+} from "./commands/login.js";
+import {
+  createKeyCommand,
+  listKeysCommand,
+  revokeKeyCommand,
+} from "./commands/auth.js";
+import { registerMcpCommand } from "./commands/mcp.js";
+import { setupCommand, teardownCommand } from "./commands/setup.js";
+import { captureSessionCommand } from "./commands/capture.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(
+  readFileSync(join(__dirname, "..", "package.json"), "utf-8"),
+);
+
+const program = new Command();
+
+program
+  .name("memax")
+  .description("Universal context & memory hub for AI agents")
+  .version(pkg.version);
+
+// --- Core commands ---
+
+program
+  .command("push [content]")
+  .description("Save knowledge to your Memax workspace")
+  .option("-f, --file <path>", "File to push")
+  .option("-c, --category <category>", "Category (auto-detected if omitted)")
+  .option("-t, --tags <tags>", "Comma-separated tags")
+  .option("--title <title>", "Note title")
+  .option("--ttl <duration>", "Auto-archive after duration (e.g., 7d, 30d)")
+  .option("--stdin", "Read content from stdin")
+  .action(pushCommand);
+
+program
+  .command("recall [query]")
+  .description("Ask your knowledge a question")
+  .option("-c, --category <category>", "Filter by category")
+  .option("-t, --tags <tags>", "Filter by tags")
+  .option("-l, --limit <n>", "Max results", "5")
+  .option("--format <format>", "Output format: text, json", "text")
+  .option("--hook", "Output in agent-injectable format")
+  .option("--max-tokens <number>", "Maximum tokens to output (approximate)")
+  .option("--include-archived", "Include archived notes")
+  .action(recallCommand);
+
+program
+  .command("list")
+  .description("List your knowledge notes")
+  .option("-c, --category <category>", "Filter by category")
+  .option("--state <state>", "Filter by state: active, cooling, archived")
+  .option("-l, --limit <n>", "Max results", "20")
+  .action(listCommand);
+
+program
+  .command("show <id>")
+  .description("Show a specific note")
+  .action(showCommand);
+
+program
+  .command("delete <id>")
+  .description("Delete a note")
+  .option("-y, --yes", "Skip confirmation")
+  .action(deleteCommand);
+
+// Aliases
+program
+  .command("remember [content]")
+  .description("Alias for push — save knowledge to your Memax workspace")
+  .option("-f, --file <path>", "File to push")
+  .option("-c, --category <category>", "Category (auto-detected if omitted)")
+  .option("-t, --tags <tags>", "Comma-separated tags")
+  .option("--title <title>", "Note title")
+  .option("--stdin", "Read content from stdin")
+  .action(pushCommand);
+
+program
+  .command("forget <id>")
+  .description("Alias for delete — remove a note from your workspace")
+  .option("-y, --yes", "Skip confirmation")
+  .action(deleteCommand);
+
+// --- Sync ---
+
+const syncCmd = program
+  .command("sync [directory]")
+  .description("Sync a directory or agent memory to your Memax workspace")
+  .option("-w, --watch", "Watch for changes (coming soon)")
+  .option(
+    "-b, --boundary <level>",
+    "Visibility level: private, team, org",
+    "private",
+  )
+  .option(
+    "-c, --category <category>",
+    "Default category (auto-detected if omitted)",
+  )
+  .option("--ignore <patterns>", "Comma-separated directories to ignore")
+  .option(
+    "--agent-memory",
+    "Sync native AI agent memory files (Claude Code, Cursor, Codex)",
+  )
+  .option("-y, --yes", "Skip confirmation for large syncs")
+  .action(syncCommand);
+
+syncCmd
+  .command("agents")
+  .description("Sync native AI agent memory files to Memax")
+  .action(syncAgentMemoryCommand);
+
+// --- Session capture ---
+
+program
+  .command("capture-session")
+  .description("Capture an agent session — extract decisions and learnings")
+  .option("--summary <text>", "Session summary text (alternative to stdin)")
+  .option("--agent <name>", "Agent name (claude-code, gemini, etc.)")
+  .action(captureSessionCommand);
+
+// --- Agent integration setup ---
+
+program
+  .command("setup")
+  .description("Set up AI agent integrations (auto-detects installed agents)")
+  .option("--mcp", "Enable MCP server (agent tools)")
+  .option("--hooks", "Enable context injection hooks")
+  .option("--instructions", "Inject memax instructions into agent config files")
+  .option("--all", "Enable MCP + hooks + instructions")
+  .option("--local", "Use local stdio MCP instead of remote server")
+  .option("--print", "Print MCP config JSON to copy/paste (no changes made)")
+  .option("--only <agents>", "Only configure these agents (comma-separated)")
+  .option("--skip <agents>", "Skip these agents (comma-separated)")
+  .action(setupCommand);
+
+program
+  .command("teardown")
+  .description("Remove Memax integrations from agents")
+  .option("--only <agents>", "Only remove from these agents (comma-separated)")
+  .action(teardownCommand);
+
+program
+  .command("hook <action> <agent>")
+  .description("Manage agent hooks (install/uninstall claude-code)")
+  .action(hookCommand);
+
+// --- Auth ---
+
+program
+  .command("login")
+  .description("Log in to Memax via GitHub")
+  .action(loginCommand);
+
+program
+  .command("logout")
+  .description("Clear saved credentials")
+  .action(logoutCommand);
+
+program
+  .command("whoami")
+  .description("Show current user")
+  .action(whoamiCommand);
+
+// --- API Keys ---
+
+const authCmd = program
+  .command("auth")
+  .description("Manage authentication and API keys");
+
+authCmd
+  .command("create-key <name>")
+  .description("Create an API key for CI/CD or non-interactive use")
+  .option("--expires <days>", "Expire after N days (default: never)")
+  .action(createKeyCommand);
+
+authCmd
+  .command("list-keys")
+  .description("List your API keys")
+  .action(listKeysCommand);
+
+authCmd
+  .command("revoke-key <id>")
+  .description("Revoke an API key")
+  .action(revokeKeyCommand);
+
+// --- MCP Server ---
+
+registerMcpCommand(program);
+
+// --- Config ---
+
+const configCmd = program
+  .command("config")
+  .description("Manage Memax configuration");
+
+configCmd
+  .command("get [key]")
+  .description("Get config value (or all values)")
+  .action(configGetCommand);
+
+configCmd
+  .command("set <key> <value>")
+  .description("Set a config value")
+  .action(configSetCommand);
+
+program.parse();

package/src/lib/api.ts

@@ -0,0 +1,110 @@
+import { loadConfig } from "./config.js";
+import {
+  loadCredentials,
+  saveCredentials,
+  isTokenExpired,
+} from "./credentials.js";
+
+interface ApiEnvelope {
+  data?: unknown;
+  error?: { code: string; message: string };
+}
+
+function getApiUrl(): string {
+  return loadConfig().api_url;
+}
+
+async function authHeaders(): Promise<Record<string, string>> {
+  // 1. MEMAX_API_KEY env var takes priority (CI/CD, non-interactive)
+  const envKey = process.env.MEMAX_API_KEY;
+  if (envKey) {
+    return { Authorization: `Bearer ${envKey}` };
+  }
+
+  // 2. Stored credentials with auto-refresh
+  const creds = loadCredentials();
+  if (!creds?.access_token) return {};
+
+  if (isTokenExpired() && creds.refresh_token) {
+    // Attempt to refresh the access token
+    try {
+      const url = `${getApiUrl()}/v1/auth/refresh`;
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ refresh_token: creds.refresh_token }),
+      });
+      const json = (await res.json()) as ApiEnvelope;
+      if (json.data) {
+        const tokens = json.data as {
+          access_token: string;
+          refresh_token: string;
+          expires_in: number;
+        };
+        saveCredentials({
+          access_token: tokens.access_token,
+          refresh_token: tokens.refresh_token,
+          expires_at: Date.now() + tokens.expires_in * 1000,
+        });
+        return { Authorization: `Bearer ${tokens.access_token}` };
+      }
+    } catch {
+      // Refresh failed — fall through to use stale token (server will reject)
+    }
+  }
+
+  return { Authorization: `Bearer ${creds.access_token}` };
+}
+
+export async function apiPost<T>(path: string, body: unknown): Promise<T> {
+  const url = `${getApiUrl()}${path}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+      body: JSON.stringify(body),
+    });
+  } catch {
+    throw new Error(`Cannot reach API at ${url} — is the server running?`);
+  }
+  const json = (await res.json()) as ApiEnvelope;
+  if (json.error) {
+    throw new Error(json.error.message);
+  }
+  return json.data as T;
+}
+
+export async function apiGet<T>(path: string): Promise<T> {
+  const url = `${getApiUrl()}${path}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      headers: { ...(await authHeaders()) },
+    });
+  } catch {
+    throw new Error(`Cannot reach API at ${url} — is the server running?`);
+  }
+  const json = (await res.json()) as ApiEnvelope;
+  if (json.error) {
+    throw new Error(json.error.message);
+  }
+  return json.data as T;
+}
+
+export async function apiDelete(path: string): Promise<void> {
+  const url = `${getApiUrl()}${path}`;
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: "DELETE",
+      headers: { ...(await authHeaders()) },
+    });
+  } catch {
+    throw new Error(`Cannot reach API at ${url} — is the server running?`);
+  }
+  const json = (await res.json()) as ApiEnvelope;
+  if (json.error) {
+    throw new Error(json.error.message);
+  }
+}

package/src/lib/config.ts

@@ -0,0 +1,61 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+
+const CONFIG_DIR = join(homedir(), ".memax");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+export interface MemaxConfig {
+  api_url: string;
+  default_hub: string;
+  default_boundary: string;
+  auto_categorize: boolean;
+}
+
+const DEFAULT_CONFIG: MemaxConfig = {
+  api_url: "http://localhost:8080",
+  default_hub: "default",
+  default_boundary: "private",
+  auto_categorize: true,
+};
+
+export function getConfigDir(): string {
+  return CONFIG_DIR;
+}
+
+export function loadConfig(): MemaxConfig {
+  // Env var overrides everything
+  const envUrl = process.env.MEMAX_API_URL;
+
+  if (!existsSync(CONFIG_FILE)) {
+    return envUrl ? { ...DEFAULT_CONFIG, api_url: envUrl } : DEFAULT_CONFIG;
+  }
+
+  try {
+    const raw = readFileSync(CONFIG_FILE, "utf-8");
+    const config = { ...DEFAULT_CONFIG, ...JSON.parse(raw) };
+    if (envUrl) config.api_url = envUrl;
+    return config;
+  } catch {
+    return envUrl ? { ...DEFAULT_CONFIG, api_url: envUrl } : DEFAULT_CONFIG;
+  }
+}
+
+export function saveConfig(config: Partial<MemaxConfig>): void {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+
+  let existing = DEFAULT_CONFIG;
+  if (existsSync(CONFIG_FILE)) {
+    try {
+      existing = {
+        ...DEFAULT_CONFIG,
+        ...JSON.parse(readFileSync(CONFIG_FILE, "utf-8")),
+      };
+    } catch {
+      // ignore parse errors
+    }
+  }
+
+  const merged = { ...existing, ...config };
+  writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2) + "\n");
+}

package/src/lib/credentials.ts

@@ -0,0 +1,42 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getConfigDir } from "./config.js";
+
+const CRED_FILE = join(getConfigDir(), "credentials.json");
+
+interface Credentials {
+  access_token: string;
+  refresh_token: string;
+  expires_at?: number; // unix timestamp (ms)
+}
+
+export function loadCredentials(): Credentials | null {
+  if (!existsSync(CRED_FILE)) return null;
+  try {
+    const creds = JSON.parse(readFileSync(CRED_FILE, "utf-8")) as Credentials;
+    if (!creds.access_token) return null;
+    return creds;
+  } catch {
+    return null;
+  }
+}
+
+export function saveCredentials(creds: Credentials): void {
+  mkdirSync(getConfigDir(), { recursive: true });
+  writeFileSync(CRED_FILE, JSON.stringify(creds, null, 2) + "\n", {
+    mode: 0o600,
+  });
+}
+
+export function isTokenExpired(): boolean {
+  const creds = loadCredentials();
+  if (!creds?.expires_at) return false; // no expiry info → assume valid
+  // Treat as expired 5 minutes early to avoid edge cases
+  return Date.now() >= creds.expires_at - 5 * 60 * 1000;
+}
+
+export function clearCredentials(): void {
+  if (existsSync(CRED_FILE)) {
+    writeFileSync(CRED_FILE, "{}\n", { mode: 0o600 });
+  }
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "types": ["node"]
+  },
+  "include": ["src"]
+}

package/LICENSE

@@ -1,24 +0,0 @@
-This is free and unencumbered software released into the public domain.
-
-Anyone is free to copy, modify, publish, use, compile, sell, or
-distribute this software, either in source code form or as a compiled
-binary, for any purpose, commercial or non-commercial, and by any
-means.
-
-In jurisdictions that recognize copyright laws, the author or authors
-of this software dedicate any and all copyright interest in the
-software to the public domain. We make this dedication for the benefit
-of the public at large and to the detriment of our heirs and
-successors. We intend this dedication to be an overt act of
-relinquishment in perpetuity of all present and future rights to this
-software under copyright law.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
-IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
-OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
-ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
-OTHER DEALINGS IN THE SOFTWARE.
-
-For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,2 +0,0 @@
-# memax
-Memax NPM package

package/bin/memax.js

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-
-const message = [
-  "",
-  "  ===============================",
-  "             memax CLI",
-  "  ===============================",
-  "  We're polishing the experience.",
-  "  Stay tuned for the first release.",
-  ""
-].join("\n");
-
-console.log(message);