@mporenta/mg 0.1.0

package/README.md

@@ -0,0 +1,29 @@
+# mg
+
+Agent-friendly CLI for the memory-graph-mcp FastAPI surface.
+
+```bash
+npm i -g @mporenta/mg
+export MEMORY_GRAPH_URL=http://localhost:8000
+mg config doctor
+```
+
+Data is written to stdout; diagnostics are written to stderr. JSON is emitted by default when stdout is not a TTY. Use `--format pretty` for human-readable output.
+
+## Search recipes
+
+All search subcommands require `--query` and return JSON-friendly results with `diagnostics` and `next_steps` hints.
+
+```bash
+# Discover candidate entities before narrowing context.
+mg search entities --query "memory graph" --limit 5
+
+# Recall repo-scoped codebase context with paths and observation IDs.
+mg search codebase --query "search diagnostics" --repo memory-graph-mcp --limit 5
+
+# Pass an embedding vector when a caller can produce one for hybrid ranking.
+mg search codebase --query "ranking" --repo memory-graph-mcp --query-embedding 0.1,0.2,0.3
+
+# Follow up on exact observations for a known entity.
+mg search memory --query "noise_floor" --entity "memory-graph-mcp" --limit 5
+```

package/dist/mg.js

@@ -0,0 +1,698 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// package.json
+var package_default = {
+  name: "@mporenta/mg",
+  version: "0.1.0",
+  description: "Agent-friendly CLI for memory-graph-mcp",
+  license: "MIT",
+  type: "module",
+  bin: {
+    mg: "dist/mg.js"
+  },
+  files: [
+    "dist",
+    "generated",
+    "README.md"
+  ],
+  engines: {
+    node: ">=18"
+  },
+  scripts: {
+    build: "esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --target=node18 --outfile=dist/mg.js --banner:js='#!/usr/bin/env node' && chmod +x dist/mg.js",
+    check: "tsc --noEmit",
+    test: "npm run build && node --test test/*.test.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    prepack: "npm run build",
+    "generate:types": "openapi-typescript ${MEMORY_GRAPH_OPENAPI_URL:-http://localhost:8000/openapi.json} -o generated/api.d.ts"
+  },
+  dependencies: {
+    commander: "^12.1.0",
+    "openapi-fetch": "^0.13.4"
+  },
+  devDependencies: {
+    "@types/node": "^22.10.1",
+    esbuild: "^0.24.0",
+    "openapi-typescript": "^7.4.4",
+    typescript: "^5.7.2"
+  }
+};
+
+// src/client.ts
+import createClient from "openapi-fetch";
+var EXIT_USER = 1;
+var EXIT_SERVER = 2;
+var EXIT_CONFIG = 3;
+var MgError = class extends Error {
+  exitCode;
+  detail;
+  constructor(message, exitCode, detail) {
+    super(message);
+    this.name = "MgError";
+    this.exitCode = exitCode;
+    this.detail = detail;
+  }
+};
+function readConfig() {
+  const baseUrl = (process.env.MEMORY_GRAPH_URL || "http://localhost:8000").replace(/\/+$/, "");
+  if (!baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
+    throw new MgError(
+      "MEMORY_GRAPH_URL must start with http:// or https://",
+      EXIT_CONFIG
+    );
+  }
+  return {
+    baseUrl,
+    token: process.env.MEMORY_GRAPH_TOKEN
+  };
+}
+async function postTool(tool, body) {
+  const config = readConfig();
+  const headers = {
+    "content-type": "application/json"
+  };
+  if (config.token) {
+    headers.authorization = `Bearer ${config.token}`;
+  }
+  let response;
+  try {
+    response = await fetch(`${config.baseUrl}/v1/${tool}`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body)
+    });
+  } catch (error) {
+    throw new MgError(
+      `Could not reach memory graph server at ${config.baseUrl}: ${stringifyError(error)}`,
+      EXIT_CONFIG,
+      { cause: stringifyError(error) }
+    );
+  }
+  return await parseResponse(response, tool);
+}
+async function getJson(path) {
+  const config = readConfig();
+  const headers = {};
+  if (config.token) {
+    headers.authorization = `Bearer ${config.token}`;
+  }
+  let response;
+  try {
+    response = await fetch(`${config.baseUrl}${path}`, { headers });
+  } catch (error) {
+    throw new MgError(
+      `Could not reach memory graph server at ${config.baseUrl}: ${stringifyError(error)}`,
+      EXIT_CONFIG,
+      { cause: stringifyError(error) }
+    );
+  }
+  return await parseResponse(response, path);
+}
+async function parseResponse(response, tool) {
+  const text = await response.text();
+  let payload;
+  if (text.length > 0) {
+    try {
+      payload = JSON.parse(text);
+    } catch {
+      payload = text;
+    }
+  }
+  if (response.ok) {
+    return payload;
+  }
+  const message = extractMessage(payload) || `${tool} failed with HTTP ${response.status}`;
+  const exitCode = response.status >= 500 ? EXIT_SERVER : EXIT_USER;
+  throw new MgError(message, exitCode, payload);
+}
+function extractMessage(payload) {
+  if (payload && typeof payload === "object" && "message" in payload) {
+    const value = payload.message;
+    if (typeof value === "string") return value;
+  }
+  if (payload && typeof payload === "object" && "detail" in payload) {
+    const value = payload.detail;
+    if (typeof value === "string") return value;
+  }
+  return void 0;
+}
+function render(data, format = defaultFormat()) {
+  if (format === "json") {
+    process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+    return;
+  }
+  process.stdout.write(`${pretty(data)}
+`);
+}
+function defaultFormat() {
+  return process.stdout.isTTY ? "pretty" : "json";
+}
+function parseFormat(value) {
+  if (value === void 0) return defaultFormat();
+  if (value === "json" || value === "pretty") return value;
+  throw new MgError("--format must be either 'json' or 'pretty'", EXIT_USER);
+}
+function compact(obj) {
+  return Object.fromEntries(
+    Object.entries(obj).filter(
+      ([, value]) => value !== void 0 && value !== ""
+    )
+  );
+}
+function parseCsv(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+function parseFloatCsv(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean).map((item) => Number.parseFloat(item));
+  if (items.some((item) => !Number.isFinite(item))) {
+    throw new MgError("Expected a comma-separated list of numbers", EXIT_USER);
+  }
+  return items.length > 0 ? items : void 0;
+}
+function parseJsonObject(value) {
+  if (!value) return void 0;
+  const parsed = JSON.parse(value);
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new MgError("Expected a JSON object", EXIT_USER);
+  }
+  return parsed;
+}
+function parseJsonObjectOrString(value) {
+  if (!value) return void 0;
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{")) {
+    return value;
+  }
+  return parseJsonObject(trimmed);
+}
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+async function readFileOrStdin(path) {
+  if (path === "-") {
+    return await readStdin();
+  }
+  const fs = await import("node:fs/promises");
+  return await fs.readFile(path, "utf8");
+}
+async function runAndRender(tool, body, opts, transform) {
+  const requestBody = compact(body);
+  const data = await postTool(tool, requestBody);
+  render(
+    transform ? transform(data, requestBody) : data,
+    parseFormat(opts.format)
+  );
+}
+function handleError(error) {
+  if (error instanceof MgError) {
+    process.stderr.write(`${error.message}
+`);
+    if (error.detail !== void 0 && process.env.MG_DEBUG) {
+      process.stderr.write(`${JSON.stringify(error.detail, null, 2)}
+`);
+    }
+    process.exit(error.exitCode);
+  }
+  process.stderr.write(`${stringifyError(error)}
+`);
+  process.exit(EXIT_SERVER);
+}
+function stringifyError(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}
+function pretty(data) {
+  if (data === void 0 || data === null) return "";
+  if (typeof data !== "object") return String(data);
+  return JSON.stringify(data, null, 2);
+}
+
+// src/commands/admin.ts
+function registerAdmin(program) {
+  const admin = program.command("admin").description("Administrative import, export, and consistency commands");
+  admin.command("consistency-check").description("Run graph consistency checks").action(async (_opts, cmd) => {
+    await runAndRender("run_consistency_check", {}, cmd.optsWithGlobals());
+  });
+  admin.command("export").description("Export graph JSON").option("--include-deleted", "include soft-deleted rows").option("--include-events", "include event audit rows").action(async (opts, cmd) => {
+    await runAndRender("export_graph_json", {
+      include_deleted: opts.includeDeleted,
+      include_events: opts.includeEvents
+    }, cmd.optsWithGlobals());
+  });
+  admin.command("import [path]").description("Import graph JSON from a file or stdin with path/-/--file -").option("--file <path>", "JSON file path or - for stdin").option("--merge-strategy <mode>", "skip or merge", "skip").action(async (path, opts, cmd) => {
+    const input = opts.file ?? path;
+    if (!input) throw new MgError("Provide a file path, --file <path>, or - for stdin", EXIT_USER);
+    const text = await readFileOrStdin(input);
+    await runAndRender("import_graph_json", {
+      payload: JSON.parse(text),
+      merge_strategy: opts.mergeStrategy
+    }, cmd.optsWithGlobals());
+  });
+  admin.command("import-legacy [path]").description("Import legacy @modelcontextprotocol/server-memory JSONL").option("--file <path>", "JSONL file path or - for stdin").action(async (path, opts, cmd) => {
+    const input = opts.file ?? path;
+    if (!input) throw new MgError("Provide a file path, --file <path>, or - for stdin", EXIT_USER);
+    await runAndRender("import_legacy_jsonl", {
+      jsonl: await readFileOrStdin(input)
+    }, cmd.optsWithGlobals());
+  });
+  admin.command("find-conflicts").description("List recorded memory conflicts").option("--entity <name>", "entity filter").option("--status <status>", "open, resolved, or ignored", "open").option("--limit <n>", "max conflicts", parseInt).action(async (opts, cmd) => {
+    await runAndRender("find_conflicts", {
+      entity: opts.entity,
+      status: opts.status,
+      limit: opts.limit
+    }, cmd.optsWithGlobals());
+  });
+}
+
+// src/commands/config.ts
+function redact(value) {
+  if (!value) return void 0;
+  return value.length <= 4 ? "****" : `${value.slice(0, 2)}\u2026${value.slice(-2)}`;
+}
+function registerConfig(program) {
+  const config = program.command("config").description("Inspect CLI and server configuration");
+  config.command("doctor").description("Validate MEMORY_GRAPH_* configuration and server readiness").action(async (_opts, cmd) => {
+    const cfg = readConfig();
+    let health;
+    let ok = false;
+    try {
+      health = await getJson("/healthz");
+      ok = Boolean(health && typeof health === "object" && health.ready === true);
+    } catch (error) {
+      const payload2 = {
+        ok: false,
+        client_version: package_default.version,
+        env: {
+          MEMORY_GRAPH_URL: cfg.baseUrl,
+          MEMORY_GRAPH_TOKEN: redact(cfg.token)
+        },
+        error: error instanceof Error ? error.message : String(error)
+      };
+      render(payload2, parseFormat(cmd.optsWithGlobals().format));
+      throw new MgError("memory graph configuration check failed", EXIT_CONFIG, payload2);
+    }
+    const payload = {
+      ok,
+      client_version: package_default.version,
+      env: {
+        MEMORY_GRAPH_URL: cfg.baseUrl,
+        MEMORY_GRAPH_TOKEN: redact(cfg.token)
+      },
+      health
+    };
+    render(payload, parseFormat(cmd.optsWithGlobals().format));
+    if (!ok) {
+      throw new MgError("memory graph server is reachable but not ready", EXIT_CONFIG, payload);
+    }
+  });
+}
+
+// src/commands/entity.ts
+function registerEntity(program) {
+  const entity = program.command("entity").description("Resolve, inspect, and merge entities");
+  entity.command("neighborhood").description("Fetch an entity neighborhood").requiredOption("--entity <name-or-id>", "entity name or id").option("--depth <n>", "depth 1-2", parseInt).option("--relation-types <csv>", "comma-separated relation types").option("--no-include-observations", "omit observations").option("--limit <n>", "max rows", parseInt).action(async (opts, cmd) => {
+    await runAndRender("get_entity_neighborhood", {
+      entity: opts.entity,
+      depth: opts.depth,
+      relation_types: opts.relationTypes ? String(opts.relationTypes).split(",").map((x) => x.trim()).filter(Boolean) : void 0,
+      include_observations: opts.includeObservations,
+      limit: opts.limit
+    }, cmd.optsWithGlobals());
+  });
+  entity.command("merge").description("Merge a duplicate entity into a target entity").requiredOption("--source <name-or-id>", "source duplicate entity").requiredOption("--target <name-or-id>", "target canonical entity").option("--reason <text>", "audit reason", "").action(async (opts, cmd) => {
+    await runAndRender("merge_entities", {
+      source_entity: opts.source,
+      target_entity: opts.target,
+      reason: opts.reason
+    }, cmd.optsWithGlobals());
+  });
+  entity.command("resolve").description("Resolve a free-form query to entity matches").requiredOption("--query <text>", "entity query").option("--limit <n>", "max matches", parseInt).action(async (opts, cmd) => {
+    await runAndRender("resolve_entity", {
+      query: opts.query,
+      limit: opts.limit
+    }, cmd.optsWithGlobals());
+  });
+}
+
+// src/commands/find.ts
+function addKindOptions(command) {
+  return command.option("--query <text>", "search query", "").option("--repo <repo>", "repo filter").option("--branch <branch>", "branch filter").option("--limit <n>", "max results", parseInt);
+}
+function registerFind(program) {
+  const find = program.command("find").description("Find codebase-shaped memory slices");
+  addKindOptions(find.command("decisions").description("Find Decision entities")).action(async (opts, cmd) => {
+    await runAndRender("find_decisions", { kind: "Decision", query: opts.query, repo: opts.repo, branch: opts.branch, limit: opts.limit }, cmd.optsWithGlobals());
+  });
+  addKindOptions(find.command("runbooks").description("Find Runbook entities")).action(async (opts, cmd) => {
+    await runAndRender("find_runbooks", { kind: "Runbook", query: opts.query, repo: opts.repo, branch: opts.branch, limit: opts.limit }, cmd.optsWithGlobals());
+  });
+  addKindOptions(find.command("incidents").description("Find Incident entities")).action(async (opts, cmd) => {
+    await runAndRender("find_incidents", { kind: "Incident", query: opts.query, repo: opts.repo, branch: opts.branch, limit: opts.limit }, cmd.optsWithGlobals());
+  });
+  find.command("by-path").description("Find entities and observations by path glob").requiredOption("--path-glob <glob>", "SQL glob pattern").option("--repo <repo>", "repo filter").option("--branch <branch>", "branch filter").option("--limit <n>", "max results", parseInt).option("--include-fixtures", "include fixture data").action(async (opts, cmd) => {
+    await runAndRender("find_by_path", {
+      repo: opts.repo,
+      path_glob: opts.pathGlob,
+      branch: opts.branch,
+      limit: opts.limit,
+      include_fixtures: opts.includeFixtures
+    }, cmd.optsWithGlobals());
+  });
+  addKindOptions(find.command("by-kind").description("Find entities by kind")).requiredOption("--kind <kind>", "entity type").action(async (opts, cmd) => {
+    await runAndRender("find_by_kind", { kind: opts.kind, query: opts.query, repo: opts.repo, branch: opts.branch, limit: opts.limit }, cmd.optsWithGlobals());
+  });
+}
+
+// src/commands/memory.ts
+function registerMemory(program) {
+  const memory = program.command("memory").description("Store, remove, and explain memories");
+  memory.command("remember").description("Store an observation about an entity").requiredOption("--entity-name <name>", "entity canonical name").option("--entity-type <type>", "entity type", "Person").requiredOption("--content <text>", "observation text").option("--confidence <number>", "confidence 0.0-1.0", parseFloat).option("--source <source>", "source ref or source object JSON").option("--sensitivity <level>", "normal, sensitive, or secret").option("--metadata <json>", "metadata JSON object").option("--repo <repo>", "repo metadata").option("--branch <branch>", "branch metadata").option("--path <path>", "path metadata").option("--is-fixture", "mark as fixture data").option("--memory-type <type>", "working, episodic, semantic, procedural, preference, or policy").option("--scope <scope>", "memory scope", "project").option("--quality-score <number>", "quality score 0.0-1.0", parseFloat).option("--evidence-count <n>", "number of supporting evidence items", parseInt).option("--verification-status <status>", "unverified, verified, failed, or partial").option("--last-verified-at <iso>", "last verification timestamp").option("--source-run-id <uuid>", "source memory_runs id").option("--subtask-type <type>", "coding subtask type").option("--success-score <number>", "success score 0.0-1.0", parseFloat).action(async (opts, cmd) => {
+    await runAndRender("remember_observation", compact({
+      entity_name: opts.entityName,
+      entity_type: opts.entityType,
+      content: opts.content,
+      confidence: opts.confidence,
+      source: parseJsonObjectOrString(opts.source),
+      sensitivity: opts.sensitivity,
+      metadata: parseJsonObject(opts.metadata),
+      repo: opts.repo,
+      branch: opts.branch,
+      path: opts.path,
+      is_fixture: opts.isFixture,
+      memory_type: opts.memoryType,
+      scope: opts.scope,
+      quality_score: opts.qualityScore,
+      evidence_count: opts.evidenceCount,
+      verification_status: opts.verificationStatus,
+      last_verified_at: opts.lastVerifiedAt,
+      source_run_id: opts.sourceRunId,
+      subtask_type: opts.subtaskType,
+      success_score: opts.successScore
+    }), cmd.optsWithGlobals());
+  });
+  memory.command("forget").description("Forget an observation or entity").option("--query <text>", "substring query for observation forget").option("--target-id <uuid>", "target observation/entity id").option("--mode <mode>", "soft, stale, supersede, or hard", "soft").option("--reason <text>", "audit reason").option("--target-type <type>", "observation or entity", "observation").option("--superseded-by-content <text>", "replacement content for supersede mode").option("--entity-name <name>", "entity name for scoped forget/explain").action(async (opts, cmd) => {
+    await runAndRender("forget_memory", {
+      query: opts.query ?? "",
+      target_id: opts.targetId,
+      mode: opts.mode,
+      reason: opts.reason ?? "",
+      target_type: opts.targetType,
+      superseded_by_content: opts.supersededByContent,
+      entity_name: opts.entityName
+    }, cmd.optsWithGlobals());
+  });
+  memory.command("explain").description("Explain an observation, entity, or relation").requiredOption("--target-type <type>", "observation, entity, or relation").option("--target-id <uuid>", "target id").option("--query <text>", "lookup query").option("--entity-name <name>", "entity name").action(async (opts, cmd) => {
+    await runAndRender("explain_memory", {
+      target_type: opts.targetType,
+      target_id: opts.targetId,
+      query: opts.query,
+      entity_name: opts.entityName
+    }, cmd.optsWithGlobals());
+  });
+}
+
+// src/commands/relation.ts
+function registerRelation(program) {
+  const relation = program.command("relation").description("Create and manage relationships");
+  relation.command("create").description("Create a relation between two entities").requiredOption("--from <name>", "source entity name").requiredOption("--to <name>", "target entity name").requiredOption("--type <type>", "relation type").option("--confidence <number>", "confidence 0.0-1.0", parseFloat).option("--source <source>", "source ref or source object JSON").option("--metadata <json>", "metadata JSON object").option("--repo <repo>", "repo metadata").option("--branch <branch>", "branch metadata").option("--path <path>", "path metadata").action(async (opts, cmd) => {
+    await runAndRender("create_relation_v2", compact({
+      from_entity: opts.from,
+      to_entity: opts.to,
+      relation_type: opts.type,
+      confidence: opts.confidence,
+      source: parseJsonObjectOrString(opts.source),
+      metadata: parseJsonObject(opts.metadata),
+      repo: opts.repo,
+      branch: opts.branch,
+      path: opts.path
+    }), cmd.optsWithGlobals());
+  });
+}
+
+// src/search_output.ts
+var SEARCH_TEXT_KEYS = ["content", "matched_text", "snippet"];
+var SCORE_THRESHOLD = 0.3;
+function transformSearchResult(tool, requestBody, data) {
+  if (!isRecord(data)) {
+    return data;
+  }
+  const augmented = addDisplayFields(data);
+  if (!isRecord(augmented)) {
+    return augmented;
+  }
+  const hits = Array.isArray(augmented.hits) ? augmented.hits.filter(isRecord) : [];
+  const topScore = topHitScore(hits);
+  const noiseFloor = typeof augmented.noise_floor === "boolean" ? augmented.noise_floor : hits.length === 0 || (topScore ?? 0) < SCORE_THRESHOLD;
+  return {
+    ...augmented,
+    noise_floor: noiseFloor,
+    diagnostics: {
+      hit_count: hits.length,
+      noise_floor: noiseFloor,
+      top_score: topScore
+    },
+    next_steps: nextSteps(tool, requestBody, hits, noiseFloor)
+  };
+}
+function addDisplayFields(value) {
+  if (Array.isArray(value)) {
+    return value.map((item) => addDisplayFields(item));
+  }
+  if (isRecord(value)) {
+    const augmented = Object.fromEntries(
+      Object.entries(value).map(([entryKey, entryValue]) => [
+        entryKey,
+        addDisplayFields(entryValue)
+      ])
+    );
+    for (const key of SEARCH_TEXT_KEYS) {
+      const raw = value[key];
+      if (typeof raw !== "string") continue;
+      const display = cleanSearchText(raw);
+      if (display !== raw) {
+        augmented[`${key}_display`] = display;
+      }
+    }
+    return augmented;
+  }
+  return value;
+}
+function cleanSearchText(value) {
+  return value.replace(/,?StartSel=/g, "").replace(/,?StopSel=/g, "").replace(/<\/?b>/g, "");
+}
+function topHitScore(hits) {
+  const scores = hits.map((hit) => hit.score).filter(
+    (score) => typeof score === "number" && Number.isFinite(score)
+  );
+  return scores.length > 0 ? Math.max(...scores) : null;
+}
+function nextSteps(tool, requestBody, hits, noiseFloor) {
+  const steps = [];
+  const query = typeof requestBody.query === "string" ? requestBody.query : "";
+  if (hits.length === 0 || noiseFloor) {
+    steps.push(
+      "Broaden the query or remove filters if these hits are not enough."
+    );
+  }
+  const firstHit = hits[0];
+  if (!firstHit) {
+    steps.push(
+      `Retry with fewer filters: mg search ${commandName(tool)} --query ${shellQuote(query)} --limit 5`
+    );
+    return steps;
+  }
+  if (tool === "search_memory") {
+    const observationId = stringValue(firstHit.observation_id);
+    if (observationId) {
+      steps.push(
+        `Inspect the top observation: mg memory explain --target-type observation --target-id ${shellQuote(observationId)}`
+      );
+    }
+  }
+  if (tool === "search_entities") {
+    const canonicalName = stringValue(firstHit.canonical_name);
+    if (canonicalName) {
+      steps.push(
+        `Search observations for the top entity: mg search memory --query ${shellQuote(query)} --entity ${shellQuote(canonicalName)} --limit 5`
+      );
+    }
+  }
+  if (tool === "search_codebase") {
+    const repo = stringValue(firstHit.repo) ?? stringValue(requestBody.repo);
+    const path = stringValue(firstHit.path);
+    if (repo && path) {
+      steps.push(
+        `Find related path entries: mg find by-path --repo ${shellQuote(repo)} --path-glob ${shellQuote(`%${path}%`)}`
+      );
+    }
+    const observationId = stringValue(firstHit.observation_id);
+    if (observationId) {
+      steps.push(
+        `Inspect the top observation: mg memory explain --target-type observation --target-id ${shellQuote(observationId)}`
+      );
+    }
+  }
+  return steps.slice(0, 3);
+}
+function commandName(tool) {
+  if (tool === "search_memory") return "memory";
+  if (tool === "search_entities") return "entities";
+  return "codebase";
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+// src/commands/search.ts
+function registerSearch(program) {
+  const search = program.command("search").description("Search memories, entities, and codebase context");
+  search.command("memory").description("Search observation text").requiredOption("--query <text>", "search query").option("--limit <n>", "max results", parseInt).option("--include-stale", "include stale memories").option("--entity <name>", "restrict to entity").option(
+    "--exclude-entity-types <csv>",
+    "comma-separated entity types to exclude"
+  ).option(
+    "--include-entity-types <csv>",
+    "comma-separated entity types to include"
+  ).option("--content-preview-chars <n>", "preview length", parseInt).option("--include-fixtures", "include fixture data").addHelpText(
+    "after",
+    `
+
+Examples:
+  $ mg search memory --query "airflow retries" --limit 5
+  $ mg search memory --query "schema migration" --entity "memory-graph-mcp" --content-preview-chars 80
+`
+  ).action(async (opts, cmd) => {
+    await runAndRender(
+      "search_memory",
+      {
+        query: opts.query,
+        limit: opts.limit,
+        include_stale: opts.includeStale,
+        entity: opts.entity,
+        exclude_entity_types: parseCsv(opts.excludeEntityTypes),
+        include_entity_types: parseCsv(opts.includeEntityTypes),
+        content_preview_chars: opts.contentPreviewChars,
+        include_fixtures: opts.includeFixtures
+      },
+      cmd.optsWithGlobals(),
+      (data, requestBody) => transformSearchResult("search_memory", requestBody, data)
+    );
+  });
+  search.command("codebase").description("Search codebase-scoped graph data").requiredOption("--query <text>", "search query").option("--repo <repo>", "repo filter").option("--branch <branch>", "branch filter").option("--entity-types <csv>", "comma-separated entity types").option(
+    "--exclude-entity-types <csv>",
+    "comma-separated entity types to exclude (empty/default excludes archives)"
+  ).option("--match-kinds <csv>", "comma-separated match kinds").option(
+    "--query-embedding <csv>",
+    "comma-separated embedding vector for optional hybrid search"
+  ).option("--limit <n>", "max results", parseInt).option("--include-stale", "include stale memories").option("--include-fixtures", "include fixture data").option("--content-preview-chars <n>", "preview length", parseInt).addHelpText(
+    "after",
+    `
+
+Examples:
+  $ mg search codebase --query "search diagnostics" --repo memory-graph-mcp --limit 5
+  $ mg search codebase --query "services.py" --repo memory-graph-mcp --match-kinds entity_path,observation_fts
+`
+  ).action(async (opts, cmd) => {
+    await runAndRender(
+      "search_codebase",
+      {
+        query: opts.query,
+        repo: opts.repo,
+        branch: opts.branch,
+        entity_types: parseCsv(opts.entityTypes),
+        exclude_entity_types: parseCsv(opts.excludeEntityTypes),
+        match_kinds: parseCsv(opts.matchKinds),
+        query_embedding: parseFloatCsv(opts.queryEmbedding),
+        limit: opts.limit,
+        include_stale: opts.includeStale,
+        include_fixtures: opts.includeFixtures,
+        content_preview_chars: opts.contentPreviewChars
+      },
+      cmd.optsWithGlobals(),
+      (data, requestBody) => transformSearchResult("search_codebase", requestBody, data)
+    );
+  });
+  search.command("entities").description("Search entity names, aliases, types, and observations").requiredOption("--query <text>", "search query").option("--limit <n>", "max results", parseInt).option(
+    "--exclude-entity-types <csv>",
+    "comma-separated entity types to exclude"
+  ).option(
+    "--include-entity-types <csv>",
+    "comma-separated entity types to include"
+  ).option("--include-fixtures", "include fixture data").addHelpText(
+    "after",
+    `
+
+Examples:
+  $ mg search entities --query "Mike" --limit 5
+  $ mg search entities --query "memory graph" --include-entity-types Repo,Decision
+`
+  ).action(async (opts, cmd) => {
+    await runAndRender(
+      "search_entities",
+      {
+        query: opts.query,
+        limit: opts.limit,
+        exclude_entity_types: parseCsv(opts.excludeEntityTypes),
+        include_entity_types: parseCsv(opts.includeEntityTypes),
+        include_fixtures: opts.includeFixtures
+      },
+      cmd.optsWithGlobals(),
+      (data, requestBody) => transformSearchResult("search_entities", requestBody, data)
+    );
+  });
+}
+
+// src/index.ts
+async function serverVersion() {
+  try {
+    const health = await getJson("/healthz");
+    if (health && typeof health === "object" && "version" in health) {
+      const value = health.version;
+      return typeof value === "string" ? value : void 0;
+    }
+  } catch {
+    return void 0;
+  }
+  return void 0;
+}
+async function main() {
+  const program = new Command();
+  program.name("mg").description("Agent-friendly CLI for memory-graph-mcp").option("--format <format>", "output format: json or pretty").option("--url <url>", "override MEMORY_GRAPH_URL for this invocation").helpOption("-h, --help", "display help").version(package_default.version, "-V, --version", "print mg client version").showHelpAfterError();
+  program.hook("preAction", (thisCommand) => {
+    const opts = thisCommand.opts();
+    if (opts.url) {
+      process.env.MEMORY_GRAPH_URL = opts.url;
+    }
+    parseFormat(opts.format);
+    readConfig();
+  });
+  program.command("version").description("Print client and server versions").action(async (_opts, cmd) => {
+    const server = await serverVersion();
+    render({ client: package_default.version, server: server ?? null }, parseFormat(cmd.optsWithGlobals().format));
+  });
+  registerMemory(program);
+  registerSearch(program);
+  registerFind(program);
+  registerRelation(program);
+  registerEntity(program);
+  registerAdmin(program);
+  registerConfig(program);
+  await program.parseAsync(process.argv);
+}
+main().catch(handleError);

package/generated/api.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Minimal checked-in OpenAPI type placeholder for the mg CLI.
+ * Regenerate against a running server with: npm run generate:types
+ */
+export interface paths {
+  [path: string]: {
+    post?: {
+      requestBody?: { content: { "application/json": unknown } };
+      responses?: { [statusCode: string]: { content: { "application/json": unknown } } };
+    };
+    get?: {
+      responses?: { [statusCode: string]: { content: { "application/json": unknown } } };
+    };
+  };
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@mporenta/mg",
+  "version": "0.1.0",
+  "description": "Agent-friendly CLI for memory-graph-mcp",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mg": "dist/mg.js"
+  },
+  "files": [
+    "dist",
+    "generated",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --packages=external --platform=node --format=esm --target=node18 --outfile=dist/mg.js --banner:js='#!/usr/bin/env node' && chmod +x dist/mg.js",
+    "check": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack:dry-run": "npm pack --dry-run",
+    "prepack": "npm run build",
+    "generate:types": "openapi-typescript ${MEMORY_GRAPH_OPENAPI_URL:-http://localhost:8000/openapi.json} -o generated/api.d.ts"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "openapi-fetch": "^0.13.4"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "esbuild": "^0.24.0",
+    "openapi-typescript": "^7.4.4",
+    "typescript": "^5.7.2"
+  }
+}