@hasna/mementos 0.4.23 → 0.4.25

package/dist/cli/index.js

@@ -5110,6 +5110,90 @@ program2.command("stats").description("Show memory statistics").option("--format
     handleError(e);
   }
 });
+program2.command("report").description("Rich summary of memory activity and top memories").option("--days <n>", "Activity window in days (default: 7)", "7").option("--project <path>", "Filter by project path").option("--markdown", "Output as Markdown (for PRs, docs, etc.)").option("--json", "Output as JSON").action((opts) => {
+  try {
+    const globalOpts = program2.opts();
+    const days = parseInt(opts.days, 10) || 7;
+    const projectPath = opts.project || globalOpts.project;
+    let projectId;
+    if (projectPath) {
+      const project = getProject(resolve3(projectPath));
+      if (project)
+        projectId = project.id;
+    }
+    const db = getDatabase();
+    const conditions = projectId ? "AND project_id = ?" : "";
+    const params = projectId ? [projectId] : [];
+    const total = db.query(`SELECT COUNT(*) as c FROM memories WHERE status = 'active' ${conditions}`).get(...params).c;
+    const pinned = db.query(`SELECT COUNT(*) as c FROM memories WHERE status = 'active' AND pinned = 1 ${conditions}`).get(...params).c;
+    const activityRows = db.query(`
+        SELECT date(created_at) AS d, COUNT(*) AS cnt
+        FROM memories WHERE status = 'active' AND date(created_at) >= date('now', '-${days} days') ${conditions}
+        GROUP BY d ORDER BY d ASC
+      `).all(...params);
+    const recentTotal = activityRows.reduce((s, r) => s + r.cnt, 0);
+    const avgPerDay = activityRows.length > 0 ? (recentTotal / activityRows.length).toFixed(1) : "0";
+    const byScopeRows = db.query(`SELECT scope, COUNT(*) as c FROM memories WHERE status = 'active' ${conditions} GROUP BY scope`).all(...params);
+    const byScope = Object.fromEntries(byScopeRows.map((r) => [r.scope, r.c]));
+    const byCatRows = db.query(`SELECT category, COUNT(*) as c FROM memories WHERE status = 'active' ${conditions} GROUP BY category`).all(...params);
+    const byCat = Object.fromEntries(byCatRows.map((r) => [r.category, r.c]));
+    const topMems = db.query(`SELECT key, value, importance, scope, category FROM memories WHERE status = 'active' ${conditions} ORDER BY importance DESC, access_count DESC LIMIT 5`).all(...params);
+    const topAgents = db.query(`SELECT agent_id, COUNT(*) as c FROM memories WHERE status = 'active' AND agent_id IS NOT NULL ${conditions} GROUP BY agent_id ORDER BY c DESC LIMIT 5`).all(...params);
+    if (opts.json) {
+      console.log(JSON.stringify({ total, pinned, recent: { days, total: recentTotal, avg_per_day: parseFloat(avgPerDay) }, by_scope: byScope, by_category: byCat, top_memories: topMems, top_agents: topAgents }, null, 2));
+      return;
+    }
+    if (opts.markdown) {
+      const lines = [
+        `## Mementos Report (last ${days} days)`,
+        "",
+        `- **Total memories:** ${total} (${pinned} pinned)`,
+        `- **Recent activity:** ${recentTotal} new in ${days} days (~${avgPerDay}/day)`,
+        `- **Scopes:** global=${byScope["global"] || 0} shared=${byScope["shared"] || 0} private=${byScope["private"] || 0}`,
+        `- **Categories:** knowledge=${byCat["knowledge"] || 0} fact=${byCat["fact"] || 0} preference=${byCat["preference"] || 0} history=${byCat["history"] || 0}`,
+        "",
+        "### Top Memories",
+        ...topMems.map((m) => `- **${m.key}** (${m.scope}/${m.category}, imp:${m.importance}): ${m.value.slice(0, 80)}${m.value.length > 80 ? "..." : ""}`)
+      ];
+      if (topAgents.length > 0) {
+        lines.push("", "### Top Agents", ...topAgents.map((a) => `- ${a.agent_id}: ${a.c} memories`));
+      }
+      console.log(lines.join(`
+`));
+      return;
+    }
+    const sparkline = activityRows.map((r) => {
+      const bars = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+      const maxC = Math.max(...activityRows.map((x) => x.cnt), 1);
+      return bars[Math.round(r.cnt / maxC * 7)] || "\u2581";
+    }).join("");
+    console.log(chalk.bold(`
+mementos report \u2014 last ${days} days
+`));
+    console.log(`  ${chalk.cyan("Total:")}     ${total} memories (${chalk.yellow(String(pinned))} pinned)`);
+    console.log(`  ${chalk.cyan("Recent:")}    ${recentTotal} new \xB7 ${chalk.dim(`~${avgPerDay}/day`)}`);
+    console.log(`  ${chalk.cyan("Activity:")}  ${sparkline || chalk.dim("no activity")}`);
+    console.log(`  ${chalk.cyan("Scopes:")}    global=${byScope["global"] || 0} shared=${byScope["shared"] || 0} private=${byScope["private"] || 0}`);
+    console.log(`  ${chalk.cyan("Categories:")} knowledge=${byCat["knowledge"] || 0} fact=${byCat["fact"] || 0} preference=${byCat["preference"] || 0} history=${byCat["history"] || 0}`);
+    if (topMems.length > 0) {
+      console.log(`
+  ${chalk.bold("Top memories by importance:")}`);
+      topMems.forEach((m) => {
+        console.log(`    ${chalk.green(`[${m.importance}]`)} ${chalk.bold(m.key)} ${chalk.dim(`(${m.scope}/${m.category})`)}`);
+        console.log(`       ${m.value.slice(0, 90)}${m.value.length > 90 ? "..." : ""}`);
+      });
+    }
+    if (topAgents.length > 0) {
+      console.log(`
+  ${chalk.bold("Top agents:")}`);
+      topAgents.forEach((a) => console.log(`    ${a.agent_id}: ${a.c} memories`));
+    }
+    console.log("");
+  } catch (e) {
+    console.error(chalk.red(`report failed: ${e instanceof Error ? e.message : String(e)}`));
+    process.exit(1);
+  }
+});
 program2.command("export").description("Export memories as JSON").option("-s, --scope <scope>", "Scope filter").option("-c, --category <cat>", "Category filter").option("--agent <name>", "Agent filter").option("--project <path>", "Project filter").action((opts) => {
   try {
     const globalOpts = program2.opts();

package/dist/mcp/index.js

@@ -4728,6 +4728,33 @@ function listEntities(filter = {}, db) {
   const rows = d.query(sql).all(...params);
   return rows.map(parseEntityRow);
 }
+function updateEntity(id, input, db) {
+  const d = db || getDatabase();
+  const existing = d.query("SELECT id FROM entities WHERE id = ?").get(id);
+  if (!existing)
+    throw new EntityNotFoundError(id);
+  const sets = ["updated_at = ?"];
+  const params = [now()];
+  if (input.name !== undefined) {
+    sets.push("name = ?");
+    params.push(input.name);
+  }
+  if (input.type !== undefined) {
+    sets.push("type = ?");
+    params.push(input.type);
+  }
+  if (input.description !== undefined) {
+    sets.push("description = ?");
+    params.push(input.description);
+  }
+  if (input.metadata !== undefined) {
+    sets.push("metadata = ?");
+    params.push(JSON.stringify(input.metadata));
+  }
+  params.push(id);
+  d.run(`UPDATE entities SET ${sets.join(", ")} WHERE id = ?`, params);
+  return getEntity(id, d);
+}
 function deleteEntity(id, db) {
   const d = db || getDatabase();
   const result = d.run("DELETE FROM entities WHERE id = ?", [id]);
@@ -4839,6 +4866,13 @@ function createRelation(input, db) {
        WHERE source_entity_id = ? AND target_entity_id = ? AND relation_type = ?`).get(input.source_entity_id, input.target_entity_id, input.relation_type);
   return parseRelationRow(row);
 }
+function getRelation(id, db) {
+  const d = db || getDatabase();
+  const row = d.query("SELECT * FROM relations WHERE id = ?").get(id);
+  if (!row)
+    throw new Error(`Relation not found: ${id}`);
+  return parseRelationRow(row);
+}
 function listRelations(filter, db) {
   const d = db || getDatabase();
   const conditions = [];
@@ -6454,6 +6488,44 @@ ${lines.join(`
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+server.tool("memory_report", "Get a rich summary report: totals, activity trend, top memories, scope/category breakdown.", {
+  days: exports_external.coerce.number().optional(),
+  project_id: exports_external.string().optional(),
+  agent_id: exports_external.string().optional()
+}, async (args) => {
+  try {
+    const days = Math.min(args.days || 7, 365);
+    const db = getDatabase();
+    const cond = [args.project_id ? "AND project_id = ?" : "", args.agent_id ? "AND agent_id = ?" : ""].filter(Boolean).join(" ");
+    const params = [...args.project_id ? [args.project_id] : [], ...args.agent_id ? [args.agent_id] : []];
+    const total = db.query(`SELECT COUNT(*) as c FROM memories WHERE status = 'active' ${cond}`).get(...params).c;
+    const pinned = db.query(`SELECT COUNT(*) as c FROM memories WHERE status = 'active' AND pinned = 1 ${cond}`).get(...params).c;
+    const actRows = db.query(`SELECT date(created_at) AS d, COUNT(*) AS cnt FROM memories WHERE status = 'active' AND date(created_at) >= date('now', '-${days} days') ${cond} GROUP BY d ORDER BY d`).all(...params);
+    const recentTotal = actRows.reduce((s, r) => s + r.cnt, 0);
+    const sparkline = actRows.length > 0 ? actRows.map((r) => {
+      const bars = "\u2581\u2582\u2583\u2584\u2585\u2586\u2587\u2588";
+      const max = Math.max(...actRows.map((x) => x.cnt), 1);
+      return bars[Math.round(r.cnt / max * 7)] || "\u2581";
+    }).join("") : "\u2014";
+    const byScopeRows = db.query(`SELECT scope, COUNT(*) as c FROM memories WHERE status = 'active' ${cond} GROUP BY scope`).all(...params);
+    const byCatRows = db.query(`SELECT category, COUNT(*) as c FROM memories WHERE status = 'active' ${cond} GROUP BY category`).all(...params);
+    const topMems = db.query(`SELECT key, value, importance FROM memories WHERE status = 'active' ${cond} ORDER BY importance DESC, access_count DESC LIMIT 5`).all(...params);
+    const lines = [
+      `Memory Report (last ${days} days)`,
+      `Total: ${total} (${pinned} pinned) | Recent: +${recentTotal} | Activity: ${sparkline}`,
+      `Scopes: ${byScopeRows.map((r) => `${r.scope}=${r.c}`).join(" ")}`,
+      `Categories: ${byCatRows.map((r) => `${r.category}=${r.c}`).join(" ")}`,
+      topMems.length > 0 ? `
+Top memories:
+${topMems.map((m) => `  [${m.importance}] ${m.key}: ${m.value.slice(0, 80)}${m.value.length > 80 ? "..." : ""}`).join(`
+`)}` : ""
+    ].filter(Boolean);
+    return { content: [{ type: "text", text: lines.join(`
+`) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
 server.tool("memory_export", "Export memories as JSON", {
   scope: exports_external.enum(["global", "shared", "private"]).optional(),
   category: exports_external.enum(["preference", "fact", "knowledge", "history"]).optional(),
@@ -6991,6 +7063,46 @@ server.tool("entity_link", "Link an entity to a memory with a role (subject, obj
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+server.tool("entity_update", "Update an entity's name, description, or metadata.", {
+  entity_name_or_id: exports_external.string(),
+  name: exports_external.string().optional(),
+  description: exports_external.string().nullable().optional(),
+  metadata: exports_external.record(exports_external.unknown()).optional()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.entity_name_or_id);
+    const { entity_name_or_id: _id, ...updates } = args;
+    const updated = updateEntity(entity.id, updates);
+    return { content: [{ type: "text", text: `Updated entity: ${updated.name} (${updated.id.slice(0, 8)})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("entity_unlink", "Unlink a memory from an entity.", {
+  entity_name_or_id: exports_external.string(),
+  memory_id: exports_external.string()
+}, async (args) => {
+  try {
+    const entity = resolveEntityParam(args.entity_name_or_id);
+    const memoryId = resolveId(args.memory_id);
+    unlinkEntityFromMemory(entity.id, memoryId);
+    return { content: [{ type: "text", text: `Unlinked: ${entity.name} \u219B memory ${memoryId.slice(0, 8)}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
+server.tool("relation_get", "Get a relation by ID.", {
+  id: exports_external.string()
+}, async (args) => {
+  try {
+    const relation = getRelation(args.id);
+    if (!relation)
+      return { content: [{ type: "text", text: `Relation not found: ${args.id}` }] };
+    return { content: [{ type: "text", text: `Relation ${relation.id.slice(0, 8)}: ${relation.source_entity_id.slice(0, 8)} \u2014[${relation.relation_type}]\u2192 ${relation.target_entity_id.slice(0, 8)} (weight: ${relation.weight})` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
 server.tool("relation_create", "Create a relation between two entities (uses, knows, depends_on, created_by, related_to, contradicts, part_of, implements).", {
   source_entity: exports_external.string(),
   target_entity: exports_external.string(),
@@ -7427,6 +7539,44 @@ var FULL_SCHEMAS = {
     params: {},
     example: "{}"
   },
+  memory_report: {
+    description: "Rich summary: total/pinned counts, sparkline activity, scope/category breakdown, top 5 memories by importance.",
+    category: "memory",
+    params: {
+      days: { type: "number", description: "Activity window in days (default 7)" },
+      project_id: { type: "string", description: "Filter by project" },
+      agent_id: { type: "string", description: "Filter by agent" }
+    },
+    example: '{"days":7,"project_id":"proj-uuid"}'
+  },
+  entity_update: {
+    description: "Update an entity's name, description, or metadata.",
+    category: "graph",
+    params: {
+      entity_name_or_id: { type: "string", description: "Entity name or ID", required: true },
+      name: { type: "string", description: "New name" },
+      description: { type: "string", description: "New description (null to clear)" },
+      metadata: { type: "object", description: "New metadata" }
+    },
+    example: '{"entity_name_or_id":"TypeScript","description":"Typed superset of JavaScript by Microsoft"}'
+  },
+  entity_unlink: {
+    description: "Remove the link between an entity and a memory.",
+    category: "graph",
+    params: {
+      entity_name_or_id: { type: "string", description: "Entity name or ID", required: true },
+      memory_id: { type: "string", description: "Memory ID (partial OK)", required: true }
+    },
+    example: '{"entity_name_or_id":"TypeScript","memory_id":"abc12345"}'
+  },
+  relation_get: {
+    description: "Get a specific relation by ID.",
+    category: "graph",
+    params: {
+      id: { type: "string", description: "Relation ID", required: true }
+    },
+    example: '{"id":"rel-uuid"}'
+  },
   entity_create: {
     description: "Create a knowledge graph entity.",
     category: "graph",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",