atlas-mcp 0.1.0

package/src/cli/commands/list.js

@@ -0,0 +1,53 @@
+import {
+  formatJson,
+  formatMemoriesTable,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas list [options]
+
+List recently stored memories, newest first.
+
+Options:
+  --limit <n>     Page size, 1-100. Default: 20
+  --offset <n>    Pagination offset. Default: 0
+  --source <s>    Filter by source: ui | mcp | cli
+  --json          Emit the raw memory array.
+`;
+
+export const meta = {
+  name: "list",
+  help: HELP,
+  options: ["limit", "offset", "source", "json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const limit = Number.isFinite(flags.limit) ? flags.limit : 20;
+  const offset = Number.isFinite(flags.offset) ? flags.offset : 0;
+  if (limit < 1 || limit > 100) {
+    printError("--limit must be between 1 and 100");
+    return { exitCode: 2 };
+  }
+  if (offset < 0) {
+    printError("--offset must be >= 0");
+    return { exitCode: 2 };
+  }
+
+  try {
+    const memories = deps.getMemories({
+      limit,
+      offset,
+      source: flags.source,
+    });
+    if (json) {
+      printJson(memories);
+    } else {
+      console.log(formatMemoriesTable(memories));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not list memories: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/related.js

@@ -0,0 +1,56 @@
+import {
+  formatJson,
+  formatRelatedList,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas related <id> [options]
+
+Find memories connected to <id> through shared entities, relationships,
+semantic similarity, and BM25 keyword matches.
+
+Options:
+  --limit <n>       Max results, 1-20. Default: 5
+  --threshold <f>   Minimum similarity score in -1..1. Default: 0.65
+  --json            Emit the raw result.
+`;
+
+export const meta = {
+  name: "related",
+  help: HELP,
+  options: ["limit", "threshold", "json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const [id] = positional;
+  if (!id) {
+    printError("related requires a memory ID.");
+    return { exitCode: 2 };
+  }
+  const limit = Number.isFinite(flags.limit) ? flags.limit : 5;
+  if (limit < 1 || limit > 20) {
+    printError("--limit must be between 1 and 20");
+    return { exitCode: 2 };
+  }
+  const scoreThreshold = Number.isFinite(flags.threshold)
+    ? flags.threshold
+    : 0.65;
+
+  try {
+    const result = await deps.getRelatedMemories(id, { limit, scoreThreshold });
+    if (!result) {
+      printError(`Memory not found: ${id}`);
+      return { exitCode: 1 };
+    }
+    if (json) {
+      printJson(result);
+    } else {
+      console.log(formatRelatedList(result));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not get related memories: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/search.js

@@ -0,0 +1,68 @@
+import {
+  formatJson,
+  formatMemoriesTable,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas search <query> [options]
+
+Find memories using hybrid search (semantic + keyword).
+
+Options:
+  --limit <n>          Max results, 1-100. Default: 20
+  --threshold <f>      Minimum similarity score in -1..1.
+  --strategy <name>    hybrid (default) | vector | bm25
+  --json               Emit the raw hits.
+`;
+
+export const meta = {
+  name: "search",
+  help: HELP,
+  options: ["limit", "threshold", "strategy", "json"],
+};
+
+const STRATEGIES = new Set(["hybrid", "vector", "bm25"]);
+
+export async function run({ positional, flags, deps, json }) {
+  const query = positional.join(" ").trim();
+  if (!query) {
+    printError("search requires a query. Try: atlas search \"coffee preference\"");
+    return { exitCode: 2 };
+  }
+  const limit = Number.isFinite(flags.limit) ? flags.limit : 20;
+  if (limit < 1 || limit > 100) {
+    printError("--limit must be between 1 and 100");
+    return { exitCode: 2 };
+  }
+  const strategy = flags.strategy || "hybrid";
+  if (!STRATEGIES.has(strategy)) {
+    printError(`--strategy must be one of: ${[...STRATEGIES].join(", ")}`);
+    return { exitCode: 2 };
+  }
+  const scoreThreshold = Number.isFinite(flags.threshold)
+    ? flags.threshold
+    : undefined;
+
+  try {
+    const hits = await deps.hybridSearchMemories(query, {
+      limit,
+      scoreThreshold,
+      strategy,
+    });
+    const memories = hits.flatMap(({ id, score }) => {
+      const memory = deps.serializeMemory(deps.getMemory(id));
+      return memory && memory.id ? [{ ...memory, rrfScore: score }] : [];
+    });
+    const payload = { query, strategy, memories };
+    if (json) {
+      printJson(payload);
+    } else {
+      console.log(formatMemoriesTable(memories));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not search memories: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/update.js

@@ -0,0 +1,58 @@
+import {
+  formatJson,
+  formatMemoryDetail,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas update <id> --summary <text>
+
+Replace the editable summary of an existing memory. The original raw text,
+type, and extraction graph are preserved. The vector embedding is reindexed
+after the update.
+
+Options:
+  --summary <str>   Replacement summary. Required.
+  --json            Emit the refreshed memory object.
+`;
+
+export const meta = {
+  name: "update",
+  help: HELP,
+  options: ["summary", "json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const [id] = positional;
+  if (!id) {
+    printError("update requires a memory ID.");
+    return { exitCode: 2 };
+  }
+  if (typeof flags.summary !== "string" || !flags.summary.trim()) {
+    printError("update requires --summary <text>.");
+    return { exitCode: 2 };
+  }
+
+  try {
+    if (!deps.getMemory(id)) {
+      printError(`Memory not found: ${id}`);
+      return { exitCode: 1 };
+    }
+    deps.updateMemorySummary(id, flags.summary);
+    try {
+      await deps.indexMemoryVector(deps.getMemory(id));
+    } catch (error) {
+      printError(`Could not reindex memory ${id}: ${error.message}`);
+    }
+    const memory = deps.serializeMemory(deps.getMemory(id));
+    if (json) {
+      printJson(memory);
+    } else {
+      console.log(formatMemoryDetail(memory));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not update memory: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/deps.js

@@ -0,0 +1,114 @@
+import {
+  closeDb,
+  deleteMemory,
+  findEntities,
+  getEntitiesForMemory,
+  getLatestExtraction,
+  getMemories,
+  getMemoriesForEntity,
+  getMemory,
+  getRegionActivations,
+  getRelationshipsForMemory,
+  getStructuralMemoryLinks,
+  searchMemoriesFts,
+  storeMemory,
+  updateMemoryGraph,
+  updateMemorySummary,
+  createMemorySource,
+  enqueueAnnotationJob,
+  enqueueVectorIndexJob,
+  getAnnotationStatus,
+  getMemorySource,
+  getSourceMemoryLinks,
+  getVectorIndexStatus,
+  linkSourceMemory,
+  updateMemorySourceStatus,
+  withTransaction,
+} from "../db.js";
+import {
+  deleteMemoryVector,
+  hybridSearchMemories,
+  indexMemoryVector,
+  searchMemoryVectors,
+} from "../vector-store.js";
+import { getRelatedMemories as deriveRelatedMemories } from "../related-memories.js";
+import { retrieveExtractionContext } from "../extraction-context.js";
+import { createIngestionService } from "../ingestion-service.js";
+
+function serializeMemory(memory) {
+  if (!memory) return null;
+  return {
+    ...memory,
+    extraction: getLatestExtraction(memory.id),
+    entities: getEntitiesForMemory(memory.id),
+    relationships: getRelationshipsForMemory(memory.id),
+    regions: getRegionActivations(memory.id),
+  };
+}
+
+export function defaultDependencies() {
+  const dependencies = {
+    closeDb,
+    decideMemoryWrite: async (...args) => {
+      const mod = await import("../llm.js");
+      return mod.decideMemoryWrite(...args);
+    },
+    deleteMemory,
+    deleteMemoryVector,
+    extractAtomicMemories: async (...args) => {
+      const mod = await import("../llm.js");
+      return mod.extractAtomicMemories(...args);
+    },
+    findEntities,
+    getEntitiesForMemory,
+    getLatestExtraction,
+    getMemories,
+    getMemoriesForEntity,
+    getMemory,
+    getRegionActivations,
+    getRelationshipsForMemory,
+    getStructuralMemoryLinks,
+    hybridSearchMemories,
+    indexMemoryVector,
+    model: undefined,
+    retrieveExtractionContext,
+    searchMemoryVectors,
+    serializeMemory,
+    storeMemory,
+    updateMemoryGraph,
+    updateMemorySummary,
+    createMemorySource,
+    updateMemorySourceStatus,
+    getMemorySource,
+    getSourceMemoryLinks,
+    linkSourceMemory,
+    enqueueAnnotationJob,
+    enqueueVectorIndexJob,
+    getAnnotationStatus,
+    getVectorIndexStatus,
+    withTransaction,
+  };
+
+  dependencies.getModel = async () => {
+    const mod = await import("../llm-config.js");
+    dependencies.model = mod.model;
+    return mod.model;
+  };
+
+  dependencies.getRelatedMemories = (id, options) =>
+    deriveRelatedMemories(
+      id,
+      {
+        getMemory,
+        getStructuralMemoryLinks,
+        searchMemoryVectors,
+        searchMemoriesFts,
+        serializeMemory,
+      },
+      options,
+    );
+
+  dependencies.ingestionService = createIngestionService(dependencies);
+
+  return dependencies;
+}

package/src/cli/env-file.js

@@ -0,0 +1,44 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+
+const LINE_RE = /^([A-Z_][A-Z0-9_]*)=(.*)$/;
+
+export function readEnvFile(filePath) {
+  if (!existsSync(filePath)) return {};
+  const content = readFileSync(filePath, "utf8");
+  const records = {};
+  for (const line of content.split("\n")) {
+    const m = line.match(LINE_RE);
+    if (m) {
+      records[m[1]] = m[2];
+    }
+  }
+  return records;
+}
+
+export function writeEnvFile(filePath, records) {
+  const lines = Object.entries(records).map(([k, v]) => `${k}=${v}`);
+  writeFileSync(filePath, lines.join("\n") + "\n", "utf8");
+}
+
+export function updateEnvValue(filePath, key, value) {
+  const records = readEnvFile(filePath);
+  if (value === "" || value === undefined || value === null) {
+    delete records[key];
+  } else {
+    records[key] = value;
+  }
+  writeEnvFile(filePath, records);
+  return records;
+}
+
+const SECRET_PATTERNS = [/KEY/i, /SECRET/i, /TOKEN/i, /PASSWORD/i];
+
+export function isSecretKey(key) {
+  return SECRET_PATTERNS.some((p) => p.test(key));
+}
+
+export function maskValue(val) {
+  if (!val) return "";
+  if (val.length <= 8) return "***";
+  return val.slice(0, 3) + "***" + val.slice(-4);
+}

package/src/cli/format.js

@@ -0,0 +1,246 @@
+const RESET = "\x1b[0m";
+const DIM = "\x1b[2m";
+const BOLD = "\x1b[1m";
+const CYAN = "\x1b[36m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const GREEN = "\x1b[32m";
+
+const useColor = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+
+function paint(color, text) {
+  return useColor ? `${color}${text}${RESET}` : text;
+}
+
+function pad(value, width) {
+  const str = String(value ?? "");
+  if (str.length >= width) return str;
+  return str + " ".repeat(width - str.length);
+}
+
+function truncate(str, max = 80) {
+  const s = String(str ?? "").replace(/\s+/g, " ").trim();
+  if (s.length <= max) return s;
+  return s.slice(0, Math.max(0, max - 1)) + "…";
+}
+
+function formatScore(score) {
+  if (score === undefined || score === null) return "-";
+  return score.toFixed(3);
+}
+
+function formatTimestamp(value) {
+  if (!value) return "-";
+  return String(value).replace("T", " ").replace(/\.\d+Z$/, "Z");
+}
+
+function formatMemoryRow(memory) {
+  const id = memory.id || memory.memory_id || "-";
+  const type = memory.type || "-";
+  const title = truncate(memory.title || memory.summary || memory.raw_text || "", 40);
+  const summary = truncate(memory.summary || memory.raw_text || "", 80);
+  const score = memory.rrfScore ?? memory.score;
+  const scoreStr = score !== undefined ? formatScore(score) : "-";
+  return { id, type, title, summary, scoreStr };
+}
+
+function formatMemoriesTable(memories) {
+  if (!memories || memories.length === 0) {
+    return paint(DIM, "(no memories)");
+  }
+  const rows = memories.map(formatMemoryRow);
+  const widths = {
+    id: Math.max(2, ...rows.map((r) => r.id.length)),
+    type: Math.max(4, ...rows.map((r) => r.type.length)),
+    score: Math.max(5, ...rows.map((r) => r.scoreStr.length)),
+    title: Math.max(5, ...rows.map((r) => r.title.length)),
+  };
+  const header = [
+    paint(BOLD, pad("ID", widths.id)),
+    paint(BOLD, pad("TYPE", widths.type)),
+    paint(BOLD, pad("SCORE", widths.score)),
+    paint(BOLD, pad("TITLE", widths.title)),
+    paint(BOLD, "SUMMARY"),
+  ].join("  ");
+  const lines = [header, paint(DIM, "─".repeat(Math.min(120, header.length)))];
+  for (const row of rows) {
+    lines.push(
+      [
+        paint(CYAN, pad(row.id, widths.id)),
+        paint(YELLOW, pad(row.type, widths.type)),
+        pad(row.scoreStr, widths.score),
+        pad(row.title, widths.title),
+        row.summary,
+      ].join("  "),
+    );
+  }
+  return lines.join("\n");
+}
+
+function formatMemoryDetail(memory) {
+  if (!memory) return paint(DIM, "(no memory)");
+  const lines = [];
+  lines.push(`${paint(BOLD, "ID")}        ${paint(CYAN, memory.id || "-")}`);
+  lines.push(`${paint(BOLD, "Type")}      ${memory.type || "-"}`);
+  lines.push(`${paint(BOLD, "Title")}     ${memory.title || "-"}`);
+  lines.push(`${paint(BOLD, "Summary")}   ${memory.summary || "-"}`);
+  lines.push(`${paint(BOLD, "Confidence")} ${memory.confidence ?? "-"}`);
+  if (memory.tags && memory.tags.length) {
+    lines.push(`${paint(BOLD, "Tags")}      ${memory.tags.join(", ")}`);
+  }
+  lines.push(
+    `${paint(BOLD, "Created")}   ${formatTimestamp(memory.created_at || memory.createdAt)}`,
+  );
+  lines.push(
+    `${paint(BOLD, "Updated")}   ${formatTimestamp(memory.updated_at || memory.updatedAt)}`,
+  );
+  lines.push("");
+  lines.push(paint(BOLD, "Raw text"));
+  lines.push(memory.raw_text || "-");
+
+  if (memory.extraction) {
+    lines.push("");
+    lines.push(paint(BOLD, "Extraction"));
+    if (memory.extraction.summary) {
+      lines.push(`  summary: ${memory.extraction.summary}`);
+    }
+    if (Array.isArray(memory.extraction.types) && memory.extraction.types.length) {
+      const ts = memory.extraction.types
+        .map((t) => `${t.type || t.name || "?"}:${t.weight ?? "?"}`)
+        .join(", ");
+      lines.push(`  types:   ${ts}`);
+    }
+    if (Array.isArray(memory.extraction.entities) && memory.extraction.entities.length) {
+      lines.push(`  entities (${memory.extraction.entities.length}):`);
+      for (const e of memory.extraction.entities.slice(0, 10)) {
+        lines.push(`    - ${e.name || e.canonical_name || e.text} (${e.kind || "?"})`);
+      }
+    }
+  }
+
+  if (Array.isArray(memory.entities) && memory.entities.length) {
+    lines.push("");
+    lines.push(paint(BOLD, `Entities (${memory.entities.length})`));
+    for (const e of memory.entities.slice(0, 10)) {
+      lines.push(`  - ${e.canonical_name || e.name} (${e.kind || "?"}) [${e.id}]`);
+    }
+  }
+
+  if (Array.isArray(memory.relationships) && memory.relationships.length) {
+    lines.push("");
+    lines.push(paint(BOLD, `Relationships (${memory.relationships.length})`));
+    for (const r of memory.relationships.slice(0, 10)) {
+      const source = r.source?.canonical_name || r.source_name || "?";
+      const target = r.target?.canonical_name || r.target_name || "?";
+      lines.push(`  - ${source} ${r.predicate || "?"} ${target}`);
+    }
+  }
+
+  if (Array.isArray(memory.regions) && memory.regions.length) {
+    lines.push("");
+    lines.push(paint(BOLD, `Regions (${memory.regions.length})`));
+    for (const r of memory.regions.slice(0, 10)) {
+      lines.push(`  - ${r.region}: ${r.weight ?? "?"}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function formatRelatedList(result) {
+  if (!result || !Array.isArray(result.links) || result.links.length === 0) {
+    return paint(DIM, "(no related memories)");
+  }
+  const lines = [`${paint(BOLD, `Related to ${result.memoryId}`)}`, ""];
+  result.links.forEach((link, index) => {
+    const id = link.memoryId || link.id || "?";
+    const score = link.score !== undefined ? formatScore(link.score) : "-";
+    const title = link.title || link.summary || link.rawText || "";
+    const reasons = Array.isArray(link.reasons) && link.reasons.length
+      ? ` (${link.reasons.join(", ")})`
+      : "";
+    lines.push(
+      `${paint(CYAN, `${index + 1}.`)} ${id}  ${paint(DIM, score)}${reasons}`,
+    );
+    if (title) lines.push(`   ${truncate(title, 100)}`);
+  });
+  return lines.join("\n");
+}
+
+function formatEntitiesTable(entities) {
+  if (!entities || entities.length === 0) {
+    return paint(DIM, "(no matching entities)");
+  }
+  const rows = entities.map((e) => ({
+    id: String(e.id ?? "?"),
+    name: e.canonical_name || e.name || "?",
+    kind: e.kind || "?",
+    aliases: Array.isArray(e.aliases) ? e.aliases.length : 0,
+  }));
+  const widths = {
+    id: Math.max(2, ...rows.map((r) => r.id.length)),
+    name: Math.max(4, ...rows.map((r) => r.name.length)),
+    kind: Math.max(4, ...rows.map((r) => r.kind.length)),
+    aliases: Math.max(7, ...rows.map((r) => String(r.aliases).length)),
+  };
+  const header = [
+    paint(BOLD, pad("ID", widths.id)),
+    paint(BOLD, pad("NAME", widths.name)),
+    paint(BOLD, pad("KIND", widths.kind)),
+    paint(BOLD, pad("ALIASES", widths.aliases)),
+  ].join("  ");
+  const lines = [header, paint(DIM, "─".repeat(header.length))];
+  for (const row of rows) {
+    lines.push(
+      [
+        paint(CYAN, pad(row.id, widths.id)),
+        pad(row.name, widths.name),
+        paint(YELLOW, pad(row.kind, widths.kind)),
+        pad(String(row.aliases), widths.aliases),
+      ].join("  "),
+    );
+  }
+  return lines.join("\n");
+}
+
+function formatAddSummary(results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    return paint(DIM, "(no memories)");
+  }
+  const lines = [];
+  for (const r of results) {
+    const id = r.memory?.id || r.matchedMemoryId || "?";
+    const color = r.action === "created"
+      ? GREEN
+      : r.action === "updated"
+        ? YELLOW
+        : DIM;
+    lines.push(
+      `${paint(color, r.action.padEnd(10))} ${paint(CYAN, id)}  ${truncate(r.reason || "", 80)}`,
+    );
+  }
+  return lines.join("\n");
+}
+
+function formatJson(data) {
+  return JSON.stringify(data, null, 2);
+}
+
+function printJson(data) {
+  console.log(formatJson(data));
+}
+
+function printError(message) {
+  console.error(paint(RED, `Error: ${message}`));
+}
+
+export {
+  formatAddSummary,
+  formatEntitiesTable,
+  formatJson,
+  formatMemoryDetail,
+  formatMemoriesTable,
+  formatRelatedList,
+  printError,
+  printJson,
+};