@hasna/mementos 0.1.1 → 0.2.0

package/dist/cli/index.js

@@ -4,6 +4,7 @@ var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __toESM = (mod, isNodeMode, target) => {
   target = mod != null ? __create(__getProtoOf(mod)) : {};
@@ -16,7 +17,31 @@ var __toESM = (mod, isNodeMode, target) => {
       });
   return to;
 };
+var __moduleCache = /* @__PURE__ */ new WeakMap;
+var __toCommonJS = (from) => {
+  var entry = __moduleCache.get(from), desc;
+  if (entry)
+    return entry;
+  entry = __defProp({}, "__esModule", { value: true });
+  if (from && typeof from === "object" || typeof from === "function")
+    __getOwnPropNames(from).map((key) => !__hasOwnProp.call(entry, key) && __defProp(entry, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    }));
+  __moduleCache.set(from, entry);
+  return entry;
+};
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: (newValue) => all[name] = () => newValue
+    });
+};
+var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = import.meta.require;
 
 // node_modules/commander/lib/error.js
@@ -2053,28 +2078,6 @@ var require_commander = __commonJS((exports) => {
   exports.InvalidOptionArgumentError = InvalidArgumentError;
 });
 
-// node_modules/commander/esm.mjs
-var import__ = __toESM(require_commander(), 1);
-var {
-  program,
-  createCommand,
-  createArgument,
-  createOption,
-  CommanderError,
-  InvalidArgumentError,
-  InvalidOptionArgumentError,
-  Command,
-  Argument,
-  Option,
-  Help
-} = import__.default;
-
-// src/cli/index.tsx
-import chalk from "chalk";
-import { readFileSync as readFileSync2 } from "fs";
-import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
-import { fileURLToPath } from "url";
-
 // src/db/database.ts
 import { Database } from "bun:sqlite";
 import { existsSync, mkdirSync } from "fs";
@@ -2132,8 +2135,59 @@ function ensureDir(filePath) {
     mkdirSync(dir, { recursive: true });
   }
 }
-var MIGRATIONS = [
-  `
+function getDatabase(dbPath) {
+  if (_db)
+    return _db;
+  const path = dbPath || getDbPath();
+  ensureDir(path);
+  _db = new Database(path, { create: true });
+  _db.run("PRAGMA journal_mode = WAL");
+  _db.run("PRAGMA busy_timeout = 5000");
+  _db.run("PRAGMA foreign_keys = ON");
+  runMigrations(_db);
+  return _db;
+}
+function runMigrations(db) {
+  try {
+    const result = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
+    const currentLevel = result?.max_id ?? 0;
+    for (let i = currentLevel;i < MIGRATIONS.length; i++) {
+      try {
+        db.exec(MIGRATIONS[i]);
+      } catch {}
+    }
+  } catch {
+    for (const migration of MIGRATIONS) {
+      try {
+        db.exec(migration);
+      } catch {}
+    }
+  }
+}
+function now() {
+  return new Date().toISOString();
+}
+function uuid() {
+  return crypto.randomUUID();
+}
+function shortUuid() {
+  return crypto.randomUUID().slice(0, 8);
+}
+function resolvePartialId(db, table, partialId) {
+  if (partialId.length >= 36) {
+    const row = db.query(`SELECT id FROM ${table} WHERE id = ?`).get(partialId);
+    return row?.id ?? null;
+  }
+  const rows = db.query(`SELECT id FROM ${table} WHERE id LIKE ?`).all(`${partialId}%`);
+  if (rows.length === 1) {
+    return rows[0].id;
+  }
+  return null;
+}
+var MIGRATIONS, _db = null;
+var init_database = __esm(() => {
+  MIGRATIONS = [
+    `
   CREATE TABLE IF NOT EXISTS projects (
     id TEXT PRIMARY KEY,
     name TEXT NOT NULL,
@@ -2220,75 +2274,29 @@ var MIGRATIONS = [
 
   INSERT OR IGNORE INTO _migrations (id) VALUES (1);
   `
-];
-var _db = null;
-function getDatabase(dbPath) {
-  if (_db)
-    return _db;
-  const path = dbPath || getDbPath();
-  ensureDir(path);
-  _db = new Database(path, { create: true });
-  _db.run("PRAGMA journal_mode = WAL");
-  _db.run("PRAGMA busy_timeout = 5000");
-  _db.run("PRAGMA foreign_keys = ON");
-  runMigrations(_db);
-  return _db;
-}
-function runMigrations(db) {
-  try {
-    const result = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
-    const currentLevel = result?.max_id ?? 0;
-    for (let i = currentLevel;i < MIGRATIONS.length; i++) {
-      try {
-        db.exec(MIGRATIONS[i]);
-      } catch {}
-    }
-  } catch {
-    for (const migration of MIGRATIONS) {
-      try {
-        db.exec(migration);
-      } catch {}
-    }
-  }
-}
-function now() {
-  return new Date().toISOString();
-}
-function uuid() {
-  return crypto.randomUUID();
-}
-function shortUuid() {
-  return crypto.randomUUID().slice(0, 8);
-}
-function resolvePartialId(db, table, partialId) {
-  if (partialId.length >= 36) {
-    const row = db.query(`SELECT id FROM ${table} WHERE id = ?`).get(partialId);
-    return row?.id ?? null;
-  }
-  const rows = db.query(`SELECT id FROM ${table} WHERE id LIKE ?`).all(`${partialId}%`);
-  if (rows.length === 1) {
-    return rows[0].id;
-  }
-  return null;
-}
+  ];
+});
 
 // src/types/index.ts
-class MemoryNotFoundError extends Error {
-  constructor(id) {
-    super(`Memory not found: ${id}`);
-    this.name = "MemoryNotFoundError";
-  }
-}
-class VersionConflictError extends Error {
-  expected;
-  actual;
-  constructor(id, expected, actual) {
-    super(`Version conflict for memory ${id}: expected ${expected}, got ${actual}`);
-    this.name = "VersionConflictError";
-    this.expected = expected;
-    this.actual = actual;
-  }
-}
+var MemoryNotFoundError, VersionConflictError;
+var init_types = __esm(() => {
+  MemoryNotFoundError = class MemoryNotFoundError extends Error {
+    constructor(id) {
+      super(`Memory not found: ${id}`);
+      this.name = "MemoryNotFoundError";
+    }
+  };
+  VersionConflictError = class VersionConflictError extends Error {
+    expected;
+    actual;
+    constructor(id, expected, actual) {
+      super(`Version conflict for memory ${id}: expected ${expected}, got ${actual}`);
+      this.name = "VersionConflictError";
+      this.expected = expected;
+      this.actual = actual;
+    }
+  };
+});
 
 // src/db/memories.ts
 function parseMemoryRow(row) {
@@ -2591,8 +2599,150 @@ function cleanExpiredMemories(db) {
   const result = d.run("DELETE FROM memories WHERE expires_at IS NOT NULL AND expires_at < ?", [timestamp]);
   return result.changes;
 }
+var init_memories = __esm(() => {
+  init_types();
+  init_database();
+});
+
+// src/lib/poll.ts
+var exports_poll = {};
+__export(exports_poll, {
+  startPolling: () => startPolling
+});
+function startPolling(opts) {
+  const interval = opts.interval_ms ?? 500;
+  const db = opts.db ?? getDatabase();
+  let stopped = false;
+  let inFlight = false;
+  let lastSeen = null;
+  const seedLastSeen = () => {
+    try {
+      const latest = listMemories({
+        scope: opts.scope,
+        category: opts.category,
+        agent_id: opts.agent_id,
+        project_id: opts.project_id,
+        limit: 1
+      }, db);
+      if (latest.length > 0 && latest[0]) {
+        lastSeen = latest[0].updated_at;
+      }
+    } catch (err) {
+      opts.on_error?.(err instanceof Error ? err : new Error(String(err)));
+    }
+  };
+  const poll = () => {
+    if (stopped || inFlight)
+      return;
+    inFlight = true;
+    try {
+      const conditions = ["status = 'active'"];
+      const params = [];
+      if (lastSeen) {
+        conditions.push("(updated_at > ? OR created_at > ?)");
+        params.push(lastSeen, lastSeen);
+      }
+      if (opts.scope) {
+        conditions.push("scope = ?");
+        params.push(opts.scope);
+      }
+      if (opts.category) {
+        conditions.push("category = ?");
+        params.push(opts.category);
+      }
+      if (opts.agent_id) {
+        conditions.push("agent_id = ?");
+        params.push(opts.agent_id);
+      }
+      if (opts.project_id) {
+        conditions.push("project_id = ?");
+        params.push(opts.project_id);
+      }
+      const sql = `SELECT * FROM memories WHERE ${conditions.join(" AND ")} ORDER BY updated_at ASC`;
+      const rows = db.query(sql).all(...params);
+      if (rows.length > 0) {
+        const memories = rows.map(parseMemoryRow3);
+        const lastRow = memories[memories.length - 1];
+        if (lastRow) {
+          lastSeen = lastRow.updated_at;
+        }
+        try {
+          opts.on_memories(memories);
+        } catch (err) {
+          opts.on_error?.(err instanceof Error ? err : new Error(String(err)));
+        }
+      }
+    } catch (err) {
+      opts.on_error?.(err instanceof Error ? err : new Error(String(err)));
+    } finally {
+      inFlight = false;
+    }
+  };
+  seedLastSeen();
+  const timer = setInterval(poll, interval);
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(timer);
+    }
+  };
+}
+function parseMemoryRow3(row) {
+  return {
+    id: row["id"],
+    key: row["key"],
+    value: row["value"],
+    category: row["category"],
+    scope: row["scope"],
+    summary: row["summary"] || null,
+    tags: JSON.parse(row["tags"] || "[]"),
+    importance: row["importance"],
+    source: row["source"],
+    status: row["status"],
+    pinned: !!row["pinned"],
+    agent_id: row["agent_id"] || null,
+    project_id: row["project_id"] || null,
+    session_id: row["session_id"] || null,
+    metadata: JSON.parse(row["metadata"] || "{}"),
+    access_count: row["access_count"],
+    version: row["version"],
+    expires_at: row["expires_at"] || null,
+    created_at: row["created_at"],
+    updated_at: row["updated_at"],
+    accessed_at: row["accessed_at"] || null
+  };
+}
+var init_poll = __esm(() => {
+  init_memories();
+  init_database();
+});
+
+// node_modules/commander/esm.mjs
+var import__ = __toESM(require_commander(), 1);
+var {
+  program,
+  createCommand,
+  createArgument,
+  createOption,
+  CommanderError,
+  InvalidArgumentError,
+  InvalidOptionArgumentError,
+  Command,
+  Argument,
+  Option,
+  Help
+} = import__.default;
+
+// src/cli/index.tsx
+init_database();
+init_memories();
+import chalk from "chalk";
+import { readFileSync as readFileSync2, existsSync as existsSync3, accessSync, constants as fsConstants } from "fs";
+import { dirname as dirname3, join as join3, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
 
 // src/db/agents.ts
+init_database();
 function parseAgentRow(row) {
   return {
     id: row["id"],
@@ -2650,8 +2800,34 @@ function listAgents(db) {
   const rows = d.query("SELECT * FROM agents ORDER BY last_seen_at DESC").all();
   return rows.map(parseAgentRow);
 }
+function updateAgent(id, updates, db) {
+  const d = db || getDatabase();
+  const agent = getAgent(id, d);
+  if (!agent)
+    return null;
+  const timestamp = now();
+  if (updates.name && updates.name !== agent.name) {
+    const existing = d.query("SELECT id FROM agents WHERE name = ? AND id != ?").get(updates.name, agent.id);
+    if (existing) {
+      throw new Error(`Agent name already taken: ${updates.name}`);
+    }
+    d.run("UPDATE agents SET name = ? WHERE id = ?", [updates.name, agent.id]);
+  }
+  if (updates.description !== undefined) {
+    d.run("UPDATE agents SET description = ? WHERE id = ?", [updates.description, agent.id]);
+  }
+  if (updates.role !== undefined) {
+    d.run("UPDATE agents SET role = ? WHERE id = ?", [updates.role, agent.id]);
+  }
+  if (updates.metadata !== undefined) {
+    d.run("UPDATE agents SET metadata = ? WHERE id = ?", [JSON.stringify(updates.metadata), agent.id]);
+  }
+  d.run("UPDATE agents SET last_seen_at = ? WHERE id = ?", [timestamp, agent.id]);
+  return getAgent(agent.id, d);
+}
 
 // src/db/projects.ts
+init_database();
 function parseProjectRow(row) {
   return {
     id: row["id"],
@@ -2696,6 +2872,7 @@ function listProjects(db) {
 }
 
 // src/lib/search.ts
+init_database();
 function parseMemoryRow2(row) {
   return {
     id: row["id"],
@@ -2929,6 +3106,8 @@ function loadConfig() {
 }
 
 // src/lib/retention.ts
+init_database();
+init_memories();
 function enforceQuotas(config, db) {
   const d = db || getDatabase();
   let totalEvicted = 0;
@@ -2971,6 +3150,94 @@ function runCleanup(config, db) {
   return { expired, evicted, archived };
 }
 
+// src/lib/injector.ts
+init_memories();
+class MemoryInjector {
+  config;
+  injectedIds = new Set;
+  constructor(config) {
+    this.config = config || loadConfig();
+  }
+  getInjectionContext(options = {}) {
+    const maxTokens = options.max_tokens || this.config.injection.max_tokens;
+    const minImportance = options.min_importance || this.config.injection.min_importance;
+    const categories = options.categories || this.config.injection.categories;
+    const db = options.db;
+    const allMemories = [];
+    const globalMems = listMemories({
+      scope: "global",
+      category: categories,
+      min_importance: minImportance,
+      status: "active",
+      limit: 100
+    }, db);
+    allMemories.push(...globalMems);
+    if (options.project_id) {
+      const sharedMems = listMemories({
+        scope: "shared",
+        category: categories,
+        min_importance: minImportance,
+        status: "active",
+        project_id: options.project_id,
+        limit: 100
+      }, db);
+      allMemories.push(...sharedMems);
+    }
+    if (options.agent_id) {
+      const privateMems = listMemories({
+        scope: "private",
+        category: categories,
+        min_importance: minImportance,
+        status: "active",
+        agent_id: options.agent_id,
+        limit: 100
+      }, db);
+      allMemories.push(...privateMems);
+    }
+    const seen = new Set;
+    const unique = allMemories.filter((m) => {
+      if (seen.has(m.id))
+        return false;
+      seen.add(m.id);
+      return true;
+    });
+    unique.sort((a, b) => {
+      if (a.pinned !== b.pinned)
+        return a.pinned ? -1 : 1;
+      if (b.importance !== a.importance)
+        return b.importance - a.importance;
+      return new Date(b.updated_at).getTime() - new Date(a.updated_at).getTime();
+    });
+    const charBudget = maxTokens * 4;
+    const lines = [];
+    let totalChars = 0;
+    for (const m of unique) {
+      if (this.injectedIds.has(m.id))
+        continue;
+      const line = `- [${m.scope}/${m.category}] ${m.key}: ${m.value}`;
+      if (totalChars + line.length > charBudget)
+        break;
+      lines.push(line);
+      totalChars += line.length;
+      this.injectedIds.add(m.id);
+      touchMemory(m.id, db);
+    }
+    if (lines.length === 0) {
+      return "";
+    }
+    return `<agent-memories>
+${lines.join(`
+`)}
+</agent-memories>`;
+  }
+  resetDedup() {
+    this.injectedIds.clear();
+  }
+  getInjectedCount() {
+    return this.injectedIds.size;
+  }
+}
+
 // src/cli/index.tsx
 function getPackageVersion() {
   try {
@@ -3075,16 +3342,53 @@ function resolveMemoryId(partialId) {
   return id;
 }
 program2.name("mementos").description("Universal memory system for AI agents").version(getPackageVersion()).option("--project <path>", "Project path for scoping").option("--json", "Output as JSON").option("--agent <name>", "Agent name or ID").option("--session <id>", "Session ID");
-program2.command("save <key> <value>").description("Save a memory (create or upsert)").option("-c, --category <cat>", "Category: preference, fact, knowledge, history").option("-s, --scope <scope>", "Scope: global, shared, private").option("--importance <n>", "Importance 1-10", parseInt).option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "Brief summary").option("--ttl <ms>", "Time-to-live in milliseconds", parseInt).option("--source <src>", "Source: user, agent, system, auto, imported").action((key, value, opts) => {
+program2.command("save <key> <value>").description("Save a memory (create or upsert)").option("-c, --category <cat>", "Category: preference, fact, knowledge, history").option("-s, --scope <scope>", "Scope: global, shared, private").option("--importance <n>", "Importance 1-10", parseInt).option("--tags <tags>", "Comma-separated tags").option("--summary <text>", "Brief summary").option("--ttl <ms>", "Time-to-live in milliseconds", parseInt).option("--source <src>", "Source: user, agent, system, auto, imported").option("--template <name>", "Apply a template: correction, preference, decision, learning").action((key, value, opts) => {
   try {
     const globalOpts = program2.opts();
+    const templates = {
+      correction: {
+        scope: "shared",
+        category: "knowledge",
+        importance: 9,
+        tags: ["correction"]
+      },
+      preference: {
+        scope: "global",
+        category: "preference",
+        importance: 8,
+        tags: []
+      },
+      decision: {
+        scope: "shared",
+        category: "fact",
+        importance: 8,
+        tags: ["decision"]
+      },
+      learning: {
+        scope: "shared",
+        category: "knowledge",
+        importance: 7,
+        tags: ["learning"]
+      }
+    };
+    let templateDefaults;
+    if (opts.template) {
+      const tpl = templates[opts.template];
+      if (!tpl) {
+        console.error(chalk.red(`Unknown template: ${opts.template}. Valid templates: ${Object.keys(templates).join(", ")}`));
+        process.exit(1);
+      }
+      templateDefaults = tpl;
+    }
+    const explicitTags = opts.tags ? opts.tags.split(",").map((t) => t.trim()) : undefined;
+    const mergedTags = explicitTags ? explicitTags : templateDefaults?.tags && templateDefaults.tags.length > 0 ? templateDefaults.tags : undefined;
     const input = {
       key,
       value,
-      category: opts.category,
-      scope: opts.scope,
-      importance: opts.importance,
-      tags: opts.tags ? opts.tags.split(",").map((t) => t.trim()) : undefined,
+      category: opts.category ?? templateDefaults?.category,
+      scope: opts.scope ?? templateDefaults?.scope,
+      importance: opts.importance ?? templateDefaults?.importance,
+      tags: mergedTags,
       summary: opts.summary,
       ttl_ms: opts.ttl,
       source: opts.source,
@@ -3119,20 +3423,38 @@ program2.command("recall <key>").description("Recall a memory by key").option("-
         projectId = project.id;
     }
     const memory = getMemoryByKey(key, opts.scope, agentId, projectId);
-    if (!memory) {
+    if (memory) {
+      touchMemory(memory.id);
       if (globalOpts.json) {
-        outputJson({ error: `No memory found for key: ${key}` });
+        outputJson(memory);
       } else {
-        console.error(chalk.yellow(`No memory found for key: ${key}`));
+        console.log(formatMemoryDetail(memory));
       }
-      process.exit(1);
+      return;
+    }
+    const results = searchMemories(key, {
+      scope: opts.scope,
+      agent_id: agentId,
+      project_id: projectId,
+      limit: 1
+    });
+    if (results.length > 0) {
+      const best = results[0];
+      touchMemory(best.memory.id);
+      if (globalOpts.json) {
+        outputJson({ fuzzy_match: true, score: best.score, match_type: best.match_type, memory: best.memory });
+      } else {
+        console.log(chalk.yellow(`No exact match, showing best result (score: ${best.score.toFixed(2)}, match: ${best.match_type}):`));
+        console.log(formatMemoryDetail(best.memory));
+      }
+      return;
     }
-    touchMemory(memory.id);
     if (globalOpts.json) {
-      outputJson(memory);
+      outputJson({ error: `No memory found for key: ${key}` });
     } else {
-      console.log(formatMemoryDetail(memory));
+      console.error(chalk.yellow(`No memory found for key: ${key}`));
     }
+    process.exit(1);
   } catch (e) {
     handleError(e);
   }
@@ -3363,10 +3685,18 @@ program2.command("export").description("Export memories as JSON").option("-s, --
     handleError(e);
   }
 });
-program2.command("import <file>").description("Import memories from a JSON file").option("--overwrite", "Overwrite existing memories (default: merge)").action((file, opts) => {
+program2.command("import [file]").description("Import memories from a JSON file or stdin (use '-' or pipe data)").option("--overwrite", "Overwrite existing memories (default: merge)").action(async (file, opts) => {
   try {
     const globalOpts = program2.opts();
-    const raw = readFileSync2(resolve3(file), "utf-8");
+    let raw;
+    if (file === "-" || !file && !process.stdin.isTTY) {
+      raw = await Bun.stdin.text();
+    } else if (file) {
+      raw = readFileSync2(resolve3(file), "utf-8");
+    } else {
+      console.error(chalk.red("No input: provide a file path, use '-' for stdin, or pipe data."));
+      process.exit(1);
+    }
     const memories = JSON.parse(raw);
     if (!Array.isArray(memories)) {
       throw new Error("JSON file must contain an array of memories");
@@ -3440,6 +3770,47 @@ program2.command("agents").description("List all registered agents").action(() =
     handleError(e);
   }
 });
+program2.command("agent-update <id>").description("Update an agent's name, description, or role").option("--name <name>", "New agent name").option("-d, --description <text>", "New description").option("-r, --role <role>", "New role").action((id, opts) => {
+  try {
+    const globalOpts = program2.opts();
+    const updates = {};
+    if (opts.name !== undefined)
+      updates.name = opts.name;
+    if (opts.description !== undefined)
+      updates.description = opts.description;
+    if (opts.role !== undefined)
+      updates.role = opts.role;
+    if (Object.keys(updates).length === 0) {
+      if (globalOpts.json) {
+        outputJson({ error: "No updates provided. Use --name, --description, or --role." });
+      } else {
+        console.error(chalk.red("No updates provided. Use --name, --description, or --role."));
+      }
+      process.exit(1);
+    }
+    const agent = updateAgent(id, updates);
+    if (!agent) {
+      if (globalOpts.json) {
+        outputJson({ error: `Agent not found: ${id}` });
+      } else {
+        console.error(chalk.red(`Agent not found: ${id}`));
+      }
+      process.exit(1);
+    }
+    if (globalOpts.json) {
+      outputJson(agent);
+    } else {
+      console.log(chalk.green("Agent updated:"));
+      console.log(`  ${chalk.bold("ID:")}          ${agent.id}`);
+      console.log(`  ${chalk.bold("Name:")}        ${agent.name}`);
+      console.log(`  ${chalk.bold("Description:")} ${agent.description || "-"}`);
+      console.log(`  ${chalk.bold("Role:")}        ${agent.role || "agent"}`);
+      console.log(`  ${chalk.bold("Last seen:")}   ${agent.last_seen_at}`);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
 program2.command("projects").description("Manage projects").option("--add", "Add a new project").option("--name <name>", "Project name").option("--path <path>", "Project path").option("--description <text>", "Project description").action((opts) => {
   try {
     const globalOpts = program2.opts();
@@ -3640,6 +4011,156 @@ program2.command("bulk <action> <ids...>").description("Batch operations: forget
     handleError(e);
   }
 });
+program2.command("doctor").description("Run health checks on the mementos database").action(() => {
+  const globalOpts = program2.opts();
+  const checks = [];
+  const dbPath = getDbPath();
+  if (existsSync3(dbPath)) {
+    try {
+      accessSync(dbPath, fsConstants.R_OK | fsConstants.W_OK);
+      checks.push({ name: "Database file", status: "ok", detail: dbPath });
+    } catch {
+      checks.push({ name: "Database file", status: "fail", detail: `Not readable/writable: ${dbPath}` });
+    }
+  } else {
+    checks.push({ name: "Database file", status: "fail", detail: `Not found: ${dbPath}` });
+  }
+  try {
+    const db = getDatabase();
+    const migRow = db.query("SELECT MAX(id) as max_id FROM _migrations").get();
+    const schemaVersion = migRow?.max_id ?? 0;
+    checks.push({ name: "Schema version", status: schemaVersion > 0 ? "ok" : "warn", detail: `v${schemaVersion}` });
+    const memCount = db.query("SELECT COUNT(*) as c FROM memories").get().c;
+    const agentCount = db.query("SELECT COUNT(*) as c FROM agents").get().c;
+    const projectCount = db.query("SELECT COUNT(*) as c FROM projects").get().c;
+    checks.push({ name: "Memories", status: "ok", detail: String(memCount) });
+    checks.push({ name: "Agents", status: "ok", detail: String(agentCount) });
+    checks.push({ name: "Projects", status: "ok", detail: String(projectCount) });
+    const orphanedTags = db.query("SELECT COUNT(*) as c FROM memory_tags WHERE memory_id NOT IN (SELECT id FROM memories)").get().c;
+    checks.push({
+      name: "Orphaned tags",
+      status: orphanedTags > 0 ? "warn" : "ok",
+      detail: orphanedTags > 0 ? `${orphanedTags} orphaned tag(s)` : "None"
+    });
+    const expiredCount = db.query("SELECT COUNT(*) as c FROM memories WHERE status != 'expired' AND expires_at IS NOT NULL AND expires_at < datetime('now')").get().c;
+    checks.push({
+      name: "Expired memories",
+      status: expiredCount > 0 ? "warn" : "ok",
+      detail: expiredCount > 0 ? `${expiredCount} expired but not cleaned up (run 'mementos clean')` : "None pending"
+    });
+  } catch (e) {
+    checks.push({ name: "Database connection", status: "fail", detail: e instanceof Error ? e.message : String(e) });
+  }
+  if (globalOpts.json) {
+    outputJson({ checks, healthy: checks.every((c) => c.status === "ok") });
+  } else {
+    console.log(chalk.bold(`
+Mementos Health Report
+`));
+    for (const check of checks) {
+      const icon = check.status === "ok" ? chalk.green("\u2713") : check.status === "warn" ? chalk.yellow("!") : chalk.red("\u2717");
+      console.log(`  ${icon} ${chalk.bold(check.name)}: ${check.detail}`);
+    }
+    const healthy = checks.every((c) => c.status === "ok");
+    const warnings = checks.filter((c) => c.status === "warn").length;
+    const failures = checks.filter((c) => c.status === "fail").length;
+    console.log("");
+    if (healthy) {
+      console.log(chalk.green("  All checks passed."));
+    } else {
+      if (failures > 0)
+        console.log(chalk.red(`  ${failures} check(s) failed.`));
+      if (warnings > 0)
+        console.log(chalk.yellow(`  ${warnings} warning(s).`));
+    }
+    console.log("");
+  }
+});
+program2.command("show <id>").description("Show full detail of a memory by ID (supports partial IDs)").action((id) => {
+  try {
+    const globalOpts = program2.opts();
+    const resolvedId = resolveMemoryId(id);
+    const memory = getMemory(resolvedId);
+    if (!memory) {
+      if (globalOpts.json) {
+        outputJson({ error: `Memory not found: ${id}` });
+      } else {
+        console.error(chalk.red(`Memory not found: ${id}`));
+      }
+      process.exit(1);
+    }
+    touchMemory(memory.id);
+    if (globalOpts.json) {
+      outputJson(memory);
+    } else {
+      console.log(formatMemoryDetail(memory));
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
+program2.command("history").description("List memories sorted by most recently accessed").option("--limit <n>", "Max results (default: 20)", parseInt).action((opts) => {
+  try {
+    const globalOpts = program2.opts();
+    const limit = opts.limit || 20;
+    const db = getDatabase();
+    const rows = db.query("SELECT * FROM memories WHERE status = 'active' AND accessed_at IS NOT NULL ORDER BY accessed_at DESC LIMIT ?").all(limit);
+    const memories = rows.map(parseMemoryRow);
+    if (globalOpts.json) {
+      outputJson(memories);
+      return;
+    }
+    if (memories.length === 0) {
+      console.log(chalk.yellow("No recently accessed memories."));
+      return;
+    }
+    console.log(chalk.bold(`${memories.length} recently accessed memor${memories.length === 1 ? "y" : "ies"}:`));
+    for (const m of memories) {
+      const id = chalk.dim(m.id.slice(0, 8));
+      const scope = colorScope(m.scope);
+      const cat = colorCategory(m.category);
+      const value = m.value.length > 60 ? m.value.slice(0, 60) + "..." : m.value;
+      const accessed = m.accessed_at ? chalk.dim(m.accessed_at) : chalk.dim("never");
+      console.log(`${id} [${scope}/${cat}] ${chalk.bold(m.key)} = ${value}  ${accessed}`);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
+program2.command("context").description("Output formatted injection context (for piping into agent prompts)").option("--agent <name>", "Agent ID for private memory scope").option("--project <path>", "Project path for shared memory scope").option("--max-tokens <n>", "Token budget for context", parseInt).option("--categories <cats>", "Comma-separated categories: preference, fact, knowledge, history").action((opts) => {
+  try {
+    const globalOpts = program2.opts();
+    const agentId = opts.agent || globalOpts.agent;
+    const projectPath = opts.project || globalOpts.project;
+    let projectId;
+    if (projectPath) {
+      const project = getProject(resolve3(projectPath));
+      if (project)
+        projectId = project.id;
+    }
+    const categories = opts.categories ? opts.categories.split(",").map((c) => c.trim()) : undefined;
+    const injector = new MemoryInjector;
+    const context = injector.getInjectionContext({
+      agent_id: agentId,
+      project_id: projectId,
+      max_tokens: opts.maxTokens,
+      categories
+    });
+    if (globalOpts.json) {
+      outputJson({
+        context,
+        injected_count: injector.getInjectedCount()
+      });
+    } else if (context) {
+      console.log(context);
+    } else {
+      console.error(chalk.yellow("No memories matched the injection criteria."));
+      process.exit(1);
+    }
+  } catch (e) {
+    handleError(e);
+  }
+});
 program2.command("mcp").description("Install mementos MCP server into Claude Code, Codex, or Gemini").option("--claude", "Install into Claude Code (~/.claude/.mcp.json)").option("--codex", "Install into Codex (~/.codex/config.toml)").option("--gemini", "Install into Gemini (~/.gemini/settings.json)").option("--all", "Install into all supported agents").option("--uninstall", "Remove mementos MCP from config").action((opts) => {
   const { readFileSync: readFileSync3, writeFileSync, existsSync: fileExists } = __require("fs");
   const { join: pathJoin } = __require("path");
@@ -3717,4 +4238,105 @@ args = []
     }
   }
 });
+program2.command("watch").description("Watch for new and changed memories in real-time").option("-s, --scope <scope>", "Scope filter: global, shared, private").option("-c, --category <cat>", "Category filter: preference, fact, knowledge, history").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").option("--interval <ms>", "Poll interval in milliseconds", parseInt).action((opts) => {
+  try {
+    const globalOpts = program2.opts();
+    const agentId = opts.agent || globalOpts.agent;
+    const projectPath = opts.project || globalOpts.project;
+    let projectId;
+    if (projectPath) {
+      const project = getProject(resolve3(projectPath));
+      if (project)
+        projectId = project.id;
+    }
+    const intervalMs = opts.interval || 500;
+    console.log(chalk.bold.cyan("Watching memories...") + chalk.dim(" (Ctrl+C to stop)"));
+    const filters = [];
+    if (opts.scope)
+      filters.push(`scope=${colorScope(opts.scope)}`);
+    if (opts.category)
+      filters.push(`category=${colorCategory(opts.category)}`);
+    if (agentId)
+      filters.push(`agent=${chalk.dim(agentId)}`);
+    if (projectId)
+      filters.push(`project=${chalk.dim(projectId)}`);
+    if (filters.length > 0) {
+      console.log(chalk.dim("Filters: ") + filters.join(chalk.dim(" | ")));
+    }
+    console.log(chalk.dim(`Poll interval: ${intervalMs}ms`));
+    console.log();
+    const filter = {
+      scope: opts.scope,
+      category: opts.category,
+      agent_id: agentId,
+      project_id: projectId,
+      limit: 20
+    };
+    const recent = listMemories(filter);
+    if (recent.length > 0) {
+      console.log(chalk.bold.dim(`Recent (${recent.length}):`));
+      for (const m of recent.reverse()) {
+        console.log(formatWatchLine(m));
+      }
+    } else {
+      console.log(chalk.dim("No recent memories."));
+    }
+    console.log(chalk.dim("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 Live \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+    console.log();
+    const { startPolling: startPolling2 } = (init_poll(), __toCommonJS(exports_poll));
+    const handle = startPolling2({
+      interval_ms: intervalMs,
+      scope: opts.scope,
+      category: opts.category,
+      agent_id: agentId,
+      project_id: projectId,
+      on_memories: (memories) => {
+        for (const m of memories) {
+          console.log(formatWatchLine(m));
+          sendNotification(m);
+        }
+      },
+      on_error: (err) => {
+        console.error(chalk.red(`Poll error: ${err.message}`));
+      }
+    });
+    const cleanup = () => {
+      handle.stop();
+      console.log();
+      console.log(chalk.dim("Stopped watching."));
+      process.exit(0);
+    };
+    process.on("SIGINT", cleanup);
+    process.on("SIGTERM", cleanup);
+  } catch (e) {
+    handleError(e);
+  }
+});
+function formatWatchLine(m) {
+  const scope = colorScope(m.scope);
+  const cat = colorCategory(m.category);
+  const imp = colorImportance(m.importance);
+  const value = m.value.length > 100 ? m.value.slice(0, 100) + "..." : m.value;
+  const main = `  [${scope}/${cat}] ${chalk.bold(m.key)} = ${value} ${chalk.dim(`(importance: ${imp})`)}`;
+  const parts = [];
+  if (m.tags.length > 0)
+    parts.push(`Tags: ${m.tags.join(", ")}`);
+  if (m.agent_id)
+    parts.push(`Agent: ${m.agent_id}`);
+  parts.push(`Updated: ${m.updated_at}`);
+  const detail = chalk.dim(`    ${parts.join("  |  ")}`);
+  return `${main}
+${detail}`;
+}
+function sendNotification(m) {
+  if (process.platform !== "darwin")
+    return;
+  try {
+    const title = "Mementos";
+    const msg = `[${m.scope}/${m.category}] ${m.key} = ${m.value.slice(0, 60)}`;
+    const escaped = msg.replace(/"/g, "\\\"");
+    const { execSync } = __require("child_process");
+    execSync(`osascript -e 'display notification "${escaped}" with title "${title}"'`, { stdio: "ignore", timeout: 2000 });
+  } catch {}
+}
 program2.parse(process.argv);