atlas-mcp 0.1.0

package/scripts/sync-memory-vectors.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import "dotenv/config";
+import { closeDb, getMemories } from "../src/db.js";
+import {
+  QDRANT_COLLECTION,
+  createMemoryVectorStore,
+  createQdrantCloudClient,
+} from "../src/vector-store.js";
+
+const PAGE_SIZE = 100;
+
+async function syncMemoryVectors() {
+  const store = createMemoryVectorStore({
+    client: createQdrantCloudClient(),
+  });
+  let offset = 0;
+  let synced = 0;
+
+  while (true) {
+    const memories = getMemories({ limit: PAGE_SIZE, offset });
+    if (!memories.length) break;
+
+    for (const memory of memories) {
+      await store.indexMemory(memory);
+      synced += 1;
+      console.log(`Indexed ${synced}: ${memory.id}`);
+    }
+
+    offset += memories.length;
+    if (memories.length < PAGE_SIZE) break;
+  }
+
+  console.log(
+    `Synced ${synced} memories to Qdrant Cloud collection "${QDRANT_COLLECTION}".`,
+  );
+}
+
+syncMemoryVectors()
+  .catch((error) => {
+    console.error(`Qdrant Cloud sync failed: ${error.message}`);
+    process.exitCode = 1;
+  })
+  .finally(() => {
+    closeDb();
+  });

package/src/audit.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+import "dotenv/config";
+import { auditMemoryIntegrity, closeDb } from "./db.js";
+
+try {
+  console.log(JSON.stringify(auditMemoryIntegrity(), null, 2));
+} finally {
+  closeDb();
+}

package/src/cli/args.js

@@ -0,0 +1,87 @@
+// Handwritten argv parser. Returns { positional, flags } where flags is a plain
+// object (booleans for `--name`/`--no-name`, strings for `--name value` or
+// `--name=value`, comma-split arrays for repeatable flags via repeat()). Stops
+// parsing flags after `--`. Reserved globals (`--json`, `--help`, `--version`)
+// are not consumed here — the entry point reads them before delegating.
+
+const REPEATABLE = new Set(["tag", "tags"]);
+
+function isFlag(token) {
+  return token.startsWith("--") && token.length > 2;
+}
+
+function splitFlag(token) {
+  const eq = token.indexOf("=");
+  if (eq === -1) return { name: token.slice(2), value: undefined };
+  return { name: token.slice(2, eq), value: token.slice(eq + 1) };
+}
+
+function camelize(name) {
+  return name.replace(/-([a-z])/g, (_, ch) => ch.toUpperCase());
+}
+
+function coerceScalar(value) {
+  if (value === "true") return true;
+  if (value === "false") return false;
+  if (/^-?\d+$/.test(value)) return Number(value);
+  if (/^-?\d+\.\d+$/.test(value)) return Number(value);
+  return value;
+}
+
+function assignFlag(flags, name, rawValue) {
+  if (name.startsWith("no-") && rawValue === undefined) {
+    flags[camelize(name.slice(3))] = false;
+    return;
+  }
+  const value = rawValue === undefined ? true : coerceScalar(rawValue);
+  if (REPEATABLE.has(name) && value !== true && value !== false) {
+    const list = String(value)
+      .split(",")
+      .map((v) => v.trim())
+      .filter(Boolean);
+    const key = camelize(name);
+    flags[key] = Array.isArray(flags[key]) ? [...flags[key], ...list] : list;
+    return;
+  }
+  flags[camelize(name)] = value;
+}
+
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  let i = 0;
+  let stopFlags = false;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (stopFlags) {
+      positional.push(token);
+      i += 1;
+      continue;
+    }
+    if (token === "--") {
+      stopFlags = true;
+      i += 1;
+      continue;
+    }
+    if (isFlag(token)) {
+      const { name, value } = splitFlag(token);
+      if (value !== undefined) {
+        assignFlag(flags, name, value);
+        i += 1;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next !== undefined && !isFlag(next)) {
+        assignFlag(flags, name, next);
+        i += 2;
+        continue;
+      }
+      assignFlag(flags, name, undefined);
+      i += 1;
+      continue;
+    }
+    positional.push(token);
+    i += 1;
+  }
+  return { positional, flags };
+}

package/src/cli/commands/add.js

@@ -0,0 +1,103 @@
+import { z } from "zod";
+import {
+  formatAddSummary,
+  printError,
+  printJson,
+} from "../format.js";
+
+const TYPE_VALUES = [
+  "relationship",
+  "preference",
+  "fact",
+  "decision",
+  "learning",
+  "event",
+  "instruction",
+  "observation",
+  "error",
+];
+
+const AddInputSchema = z.object({
+  text: z
+    .string()
+    .min(1, "text is required")
+    .max(2000, "text must be 2000 characters or fewer"),
+  type: z.enum(TYPE_VALUES).optional(),
+  title: z
+    .string()
+    .min(1, "title must not be empty")
+    .max(50, "title must be 50 characters or fewer")
+    .optional(),
+  confidence: z.number().min(0).max(1).optional(),
+  tags: z.array(z.string().min(1)).optional(),
+});
+
+const HELP = `Usage: atlas add <text...> [options]
+
+Save a NEW personal memory. The text is split into atomic memories, each
+matched against existing memories, and either created, updated, or left
+unchanged based on similarity. The LLM infers a per-atom type from the
+extraction; --type is an optional caller-level fallback.
+
+Options:
+  --type <enum>        Optional fallback: relationship | preference | fact |
+                       decision | learning | event | instruction | observation |
+                       error
+  --title <str>        Optional short title (max 50 chars).
+  --confidence <0-1>   Optional confidence in the memory. Default: 0.6
+  --tags a,b,c         Comma-separated tags. Repeat to add more.
+  --json               Emit the raw result object instead of a summary.
+`;
+
+export const meta = {
+  name: "add",
+  help: HELP,
+  options: ["type", "title", "confidence", "tags", "json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const text = positional.join(" ").trim();
+  if (!text) {
+    printError("add requires text. Try: atlas add \"I prefer dark roast coffee\"");
+    return { exitCode: 2 };
+  }
+
+  const parsed = AddInputSchema.safeParse({
+    text,
+    type: flags.type,
+    title: flags.title,
+    confidence: flags.confidence,
+    tags: flags.tags,
+  });
+  if (!parsed.success) {
+    const issue = parsed.error.issues[0];
+    printError(`${issue.path.join(".") || "input"}: ${issue.message}`);
+    return { exitCode: 2 };
+  }
+
+  const { type, title, confidence, tags } = parsed.data;
+  const metadata = {};
+  if (type !== undefined) metadata.type = type;
+  if (title !== undefined) metadata.title = title;
+  if (confidence !== undefined) metadata.confidence = confidence;
+  if (tags !== undefined) metadata.tags = tags;
+
+  try {
+    await deps.getModel();
+    const result = await deps.ingestionService.ingest({
+      text: parsed.data.text,
+      source: "cli",
+      metadata,
+    });
+
+    if (json) {
+      printJson(result);
+    } else {
+      console.log(formatAddSummary(result.memories));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not add memory: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/config.js

@@ -0,0 +1,228 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  printError,
+  printJson,
+} from "../format.js";
+import {
+  readEnvFile,
+  updateEnvValue,
+  maskValue,
+  isSecretKey,
+} from "../env-file.js";
+
+const KNOWN_PROVIDERS = ["tokenrouter", "openrouter"];
+
+const CONFIG_KEYS = [
+  { key: "LLM_PROVIDER", description: "LLM backend", default: "tokenrouter" },
+  { key: "LLM_MODEL", description: "Model override", default: "(provider default)" },
+  { key: "TOKENROUTER_API_KEY", description: "TokenRouter API key" },
+  { key: "OPENROUTER_API_KEY", description: "OpenRouter API key" },
+  { key: "PORT", description: "HTTP server port", default: "3001" },
+  { key: "LOG_LEVEL", description: "Log level", default: "info" },
+  { key: "ENGRAM_DB_PATH", description: "SQLite database path", default: "./engram.db" },
+  { key: "EMBEDDING_MODEL", description: "Embedding model", default: "Xenova/all-MiniLM-L6-v2" },
+  { key: "EMBEDDING_DIMENSIONS", description: "Embedding dimensions", default: "384" },
+  { key: "EMBEDDING_DTYPE", description: "Embedding quantization", default: "q8" },
+  { key: "ATLAS_MODE", description: "Runtime mode", default: "local" },
+  { key: "AUTH_ENABLED", description: "Auth enabled", default: "false" },
+  { key: "SUPABASE_URL", description: "Supabase project URL" },
+  { key: "SUPABASE_PUBLISHABLE_KEY", description: "Supabase anon key" },
+];
+
+const HELP = `Usage: atlas config [subcommand] [args]
+
+View and edit Atlas configuration (.env file).
+
+Subcommands:
+  (none)               Show all current config values
+  get <KEY>            Get a single config value
+  set <KEY> <VALUE>    Set a config value in .env
+  provider [name]      Show or switch LLM provider (tokenrouter|openrouter)
+  model [name]         Show or set model override (LLM_MODEL)
+  apikey <provider> <key>  Set API key for a provider
+
+Examples:
+  atlas config                    Show all config
+  atlas config get LLM_PROVIDER   Get one value
+  atlas config set PORT 4000      Change port
+  atlas config provider openrouter Switch provider
+  atlas config model gpt-4o       Override model
+  atlas config apikey openrouter sk-or-v1-...  Set API key
+`;
+
+export const meta = {
+  name: "config",
+  help: HELP,
+  options: ["json"],
+};
+
+function resolveEnvPath() {
+  return resolve(process.cwd(), ".env");
+}
+
+function envPath() {
+  const p = resolveEnvPath();
+  return existsSync(p) ? p : null;
+}
+
+function showConfig(json) {
+  const filePath = envPath();
+  const fileRecords = filePath ? readEnvFile(filePath) : {};
+  const rows = [];
+
+  for (const def of CONFIG_KEYS) {
+    const fileVal = fileRecords[def.key];
+    const envVal = process.env[def.key];
+    const raw = envVal || fileVal || "";
+    const source = envVal ? "env" : fileVal ? ".env" : "default";
+    const display = raw || def.default || "";
+    const masked = isSecretKey(def.key) && raw ? maskValue(raw) : display;
+    rows.push({ key: def.key, value: masked, raw, source, description: def.description });
+  }
+
+  if (json) {
+    const out = {};
+    for (const r of rows) {
+      if (r.raw) out[r.key] = r.raw;
+    }
+    printJson(out);
+    return;
+  }
+
+  if (!filePath) {
+    console.log("No .env file found. Run 'atlas config set <KEY> <VALUE>' to create one.\n");
+  }
+
+  const keyW = Math.max(4, ...rows.map((r) => r.key.length));
+  const valW = Math.max(5, ...rows.map((r) => r.value.length));
+
+  const header = [
+    "KEY".padEnd(keyW),
+    "VALUE".padEnd(valW),
+    "SOURCE",
+  ].join("  ");
+  console.log(header);
+  console.log("─".repeat(header.length));
+
+  for (const r of rows) {
+    const display = isSecretKey(r.key) && r.raw
+      ? `\x1b[2m${r.value}\x1b[0m`
+      : r.value;
+    const visibleLen = r.value.length;
+    const padded = visibleLen < valW ? display + " ".repeat(valW - visibleLen) : display;
+    console.log(`${r.key.padEnd(keyW)}  ${padded}  ${r.source}`);
+  }
+}
+
+function getConfig(key, json) {
+  const filePath = envPath();
+  const fileRecords = filePath ? readEnvFile(filePath) : {};
+  const value = process.env[key] || fileRecords[key] || "";
+  if (json) {
+    printJson({ key, value });
+  } else if (value) {
+    const display = isSecretKey(key) ? maskValue(value) : value;
+    console.log(`${key}=${display}`);
+  } else {
+    console.log(`${key} (not set)`);
+  }
+}
+
+function setConfig(key, value) {
+  const filePath = envPath() || resolve(process.cwd(), ".env");
+  updateEnvValue(filePath, key, value);
+  if (value) {
+    const display = isSecretKey(key) ? maskValue(value) : value;
+    console.log(`Set ${key}=${display} in .env`);
+  } else {
+    console.log(`Removed ${key} from .env`);
+  }
+}
+
+function switchProvider(name) {
+  if (!name) {
+    const current = process.env.LLM_PROVIDER || "tokenrouter";
+    console.log(current);
+    return;
+  }
+  if (!KNOWN_PROVIDERS.includes(name)) {
+    printError(`Unknown provider "${name}". Valid: ${KNOWN_PROVIDERS.join(", ")}`);
+    return;
+  }
+  setConfig("LLM_PROVIDER", name);
+  console.log(`Restart the server to apply.`);
+}
+
+function setModel(name) {
+  if (!name) {
+    const current = process.env.LLM_MODEL || "(provider default)";
+    console.log(current);
+    return;
+  }
+  setConfig("LLM_MODEL", name);
+  console.log(`Restart the server to apply.`);
+}
+
+function setApiKey(provider, key) {
+  if (!provider || !key) {
+    printError("Usage: atlas config apikey <provider> <key>");
+    return;
+  }
+  if (!KNOWN_PROVIDERS.includes(provider)) {
+    printError(`Unknown provider "${provider}". Valid: ${KNOWN_PROVIDERS.join(", ")}`);
+    return;
+  }
+  const envKey = provider === "tokenrouter"
+    ? "TOKENROUTER_API_KEY"
+    : "OPENROUTER_API_KEY";
+  setConfig(envKey, key);
+}
+
+export async function run({ positional, flags, json }) {
+  const [sub, ...rest] = positional;
+
+  if (!sub || sub === "show") {
+    showConfig(json);
+    return { exitCode: 0 };
+  }
+
+  if (sub === "get") {
+    const key = rest[0];
+    if (!key) {
+      printError("Usage: atlas config get <KEY>");
+      return { exitCode: 2 };
+    }
+    getConfig(key, json);
+    return { exitCode: 0 };
+  }
+
+  if (sub === "set") {
+    const key = rest[0];
+    const value = rest[1];
+    if (!key || value === undefined) {
+      printError("Usage: atlas config set <KEY> <VALUE>");
+      return { exitCode: 2 };
+    }
+    setConfig(key, value);
+    return { exitCode: 0 };
+  }
+
+  if (sub === "provider") {
+    switchProvider(rest[0]);
+    return { exitCode: 0 };
+  }
+
+  if (sub === "model") {
+    setModel(rest[0]);
+    return { exitCode: 0 };
+  }
+
+  if (sub === "apikey") {
+    setApiKey(rest[0], rest[1]);
+    return { exitCode: 0 };
+  }
+
+  printError(`Unknown subcommand "${sub}". Run 'atlas config --help' for usage.`);
+  return { exitCode: 2 };
+}

package/src/cli/commands/delete.js

@@ -0,0 +1,75 @@
+import {
+  formatJson,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas delete <id> [--yes]
+
+Permanently delete a memory and its vector. Prompts for confirmation on a
+TTY; use --yes to skip the prompt (recommended for scripts).
+`;
+
+export const meta = {
+  name: "delete",
+  help: HELP,
+  options: ["yes"],
+};
+
+async function confirm(id) {
+  if (!process.stdout.isTTY) return false;
+  process.stdout.write(`Delete memory ${id}? [y/N] `);
+  return new Promise((resolve) => {
+    let buffer = "";
+    const onData = (chunk) => {
+      buffer += chunk.toString();
+      if (buffer.includes("\n")) {
+        process.stdin.removeListener("data", onData);
+        process.stdin.pause();
+        const answer = buffer.trim().toLowerCase();
+        resolve(answer === "y" || answer === "yes");
+      }
+    };
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", onData);
+  });
+}
+
+export async function run({ positional, flags, deps, json }) {
+  const [id] = positional;
+  if (!id) {
+    printError("delete requires a memory ID.");
+    return { exitCode: 2 };
+  }
+
+  try {
+    if (!deps.getMemory(id)) {
+      printError(`Memory not found: ${id}`);
+      return { exitCode: 1 };
+    }
+    if (!flags.yes) {
+      const ok = await confirm(id);
+      if (!ok) {
+        console.log("Aborted.");
+        return { exitCode: 0 };
+      }
+    }
+    deps.deleteMemory(id);
+    try {
+      await deps.deleteMemoryVector(id);
+    } catch (error) {
+      printError(`Could not delete vector for ${id}: ${error.message}`);
+    }
+    const result = { ok: true, deletedMemoryId: id };
+    if (json) {
+      printJson(result);
+    } else {
+      console.log(`Deleted ${id}.`);
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not delete memory: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/entities.js

@@ -0,0 +1,39 @@
+import {
+  formatEntitiesTable,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas entities <query>
+
+Look up canonical entities (people, places, objects, concepts, organizations)
+by partial name. Use the returned numeric ID with \`atlas entity <id>\` to
+list every memory linked to it.
+`;
+
+export const meta = {
+  name: "entities",
+  help: HELP,
+  options: ["json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const query = positional.join(" ").trim();
+  if (!query) {
+    printError("entities requires a query. Try: atlas entities Maya");
+    return { exitCode: 2 };
+  }
+
+  try {
+    const entities = deps.findEntities(query);
+    if (json) {
+      printJson({ entities });
+    } else {
+      console.log(formatEntitiesTable(entities));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not find entities: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/entity.js

@@ -0,0 +1,47 @@
+import {
+  formatJson,
+  formatMemoriesTable,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas entity <id>
+
+List every memory linked to a specific entity. Pass the numeric entity ID
+returned by \`atlas entities <query>\`.
+
+Options:
+  --json    Emit the raw memory array.
+`;
+
+export const meta = {
+  name: "entity",
+  help: HELP,
+  options: ["json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const [raw] = positional;
+  if (!raw) {
+    printError("entity requires a numeric entity ID.");
+    return { exitCode: 2 };
+  }
+  const entityId = Number.parseInt(raw, 10);
+  if (!Number.isInteger(entityId) || entityId <= 0) {
+    printError(`entity ID must be a positive integer, got: ${raw}`);
+    return { exitCode: 2 };
+  }
+
+  try {
+    const memories = deps.getMemoriesForEntity(entityId);
+    if (json) {
+      printJson({ entityId, memories });
+    } else {
+      console.log(formatMemoriesTable(memories));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not get entity memories: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli/commands/get.js

@@ -0,0 +1,46 @@
+import {
+  formatJson,
+  formatMemoryDetail,
+  printError,
+  printJson,
+} from "../format.js";
+
+const HELP = `Usage: atlas get <id> [options]
+
+Fetch one memory by ID with its full extraction (entities, relationships,
+regions).
+
+Options:
+  --json    Emit the raw memory object.
+`;
+
+export const meta = {
+  name: "get",
+  help: HELP,
+  options: ["json"],
+};
+
+export async function run({ positional, flags, deps, json }) {
+  const [id] = positional;
+  if (!id) {
+    printError("get requires a memory ID. Try: atlas get mem_12ab34cd");
+    return { exitCode: 2 };
+  }
+
+  try {
+    const memory = deps.serializeMemory(deps.getMemory(id));
+    if (!memory || !memory.id) {
+      printError(`Memory not found: ${id}`);
+      return { exitCode: 1 };
+    }
+    if (json) {
+      printJson(memory);
+    } else {
+      console.log(formatMemoryDetail(memory));
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    printError(`Could not get memory: ${error.message}`);
+    return { exitCode: 1 };
+  }
+}