@hasna/conversations 0.2.5 → 0.2.7

package/bin/hook.js

@@ -252,6 +252,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`

package/bin/index.js

@@ -2117,6 +2117,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -2330,6 +2344,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -2371,6 +2391,10 @@ function readMessages(opts = {}) {
   if (opts.threads_only) {
     conditions.push("reply_to IS NULL");
   }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
@@ -2622,6 +2646,14 @@ function searchMessages(opts) {
       extraWhere += " AND m.to_agent = ?";
       ftsParams.push(opts.to);
     }
+    if (opts.since) {
+      extraWhere += " AND m.created_at >= ?";
+      ftsParams.push(opts.since);
+    }
+    if (opts.until) {
+      extraWhere += " AND m.created_at <= ?";
+      ftsParams.push(opts.until);
+    }
     const orderClause = sortByRelevance ? "ORDER BY rank" : "ORDER BY m.created_at DESC, m.id DESC";
     const rows2 = db2.prepare(`SELECT m.*, rank,
         snippet(messages_fts, 0, '**', '**', '...', 20) as snippet
@@ -2654,6 +2686,14 @@ function searchMessages(opts) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.since) {
+    conditions.push("created_at >= ?");
+    params.push(opts.since);
+  }
+  if (opts.until) {
+    conditions.push("created_at <= ?");
+    params.push(opts.until);
+  }
   const where = `WHERE ${conditions.join(" AND ")}`;
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at DESC, id DESC LIMIT ${limit}`).all(...params);
   return rows.map((row) => {
@@ -2694,6 +2734,73 @@ function listUnreadCounts(agent) {
   `).all();
   return rows;
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
+function listUnreadCountsWithMentions(agent) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+      (SELECT COUNT(*) FROM message_mentions mm WHERE mm.space = m.space AND mm.mentioned_agent = ? AND mm.notified_at IS NULL) AS mention_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages m
+    WHERE space IN (
+      SELECT DISTINCT space FROM space_members WHERE agent = ?
+      UNION
+      SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+    )
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY mention_count DESC, unread_count DESC, latest_message_at DESC
+  `).all(agent, agent, agent, agent);
+  return rows;
+}
+function getMessagesForAgent(agent, opts) {
+  const db2 = getDb();
+  const conditions = ["mm.mentioned_agent = ?"];
+  const params = [agent.toLowerCase()];
+  if (opts?.space) {
+    conditions.push("m.space = ?");
+    params.push(opts.space);
+  }
+  if (opts?.unread_only) {
+    conditions.push("mm.notified_at IS NULL");
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db2.prepare(`SELECT m.*, mm.id AS mention_id FROM messages m
+     JOIN message_mentions mm ON mm.message_id = m.id
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY m.created_at DESC LIMIT ${limit}`).all(...params);
+  return rows.map(({ mention_id, ...row }) => ({ message: parseMessage(row), mention_id }));
+}
+function markMentionsRead(agent, space) {
+  const db2 = getDb();
+  if (space) {
+    const result2 = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND space = ? AND notified_at IS NULL").run(agent, space);
+    return result2.changes;
+  }
+  const result = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND notified_at IS NULL").run(agent);
+  return result.changes;
+}
 var init_messages = __esm(() => {
   init_db();
   init_webhooks();
@@ -4333,7 +4440,7 @@ var init_poll = __esm(() => {
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@hasna/conversations",
-    version: "0.2.5",
+    version: "0.2.7",
     description: "Real-time CLI messaging for AI agents",
     type: "module",
     bin: {
@@ -33588,7 +33695,8 @@ var init_mcp2 = __esm(() => {
       mark_read: exports_external.coerce.boolean().optional(),
       max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
       threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (reply_to IS NULL) \u2014 hides thread replies"),
-      include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)")
+      include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)"),
+      mentions_only: exports_external.string().optional().describe("Only return messages that @mention this agent")
     }
   }, async (args) => {
     const agent = resolveIdentity(args.from);
@@ -33671,19 +33779,26 @@ var init_mcp2 = __esm(() => {
     };
   });
   server.registerTool("search_messages", {
-    description: "Full-text search across messages.",
+    description: "Full-text search across messages. Uses FTS5 with BM25 ranking if available, falls back to LIKE. Returns messages with snippet and relevance_score.",
     inputSchema: {
-      query: exports_external.string(),
-      space: exports_external.string().optional(),
-      from: exports_external.string().optional(),
-      to: exports_external.string().optional(),
-      limit: exports_external.coerce.number().optional()
+      query: exports_external.string().describe(`Search query. Wrap in quotes for exact phrase: '"BUG-005"'`),
+      space: exports_external.string().optional().describe("Limit to a specific space"),
+      from: exports_external.string().optional().describe("Filter by sender"),
+      to: exports_external.string().optional().describe("Filter by recipient"),
+      since: exports_external.string().optional().describe("ISO 8601 date \u2014 only messages after this"),
+      until: exports_external.string().optional().describe("ISO 8601 date \u2014 only messages before this"),
+      sort: exports_external.enum(["relevance", "recent"]).optional().describe("Sort order (default: relevance)"),
+      limit: exports_external.coerce.number().optional().describe("Max results (default: 20)")
     }
   }, async (args) => {
-    const { query, space, from, to, limit } = args;
-    const messages = searchMessages({ query, space, from, to, limit });
+    const { query, space, from, to, since, until, sort, limit } = args;
+    const results = searchMessages({ query, space, from, to, since, until, sort, limit });
     return {
-      content: [{ type: "text", text: JSON.stringify(messages) }]
+      content: [{ type: "text", text: JSON.stringify({
+        results,
+        count: results.length,
+        query
+      }) }]
     };
   });
   server.registerTool("export_messages", {
@@ -33760,13 +33875,42 @@ var init_mcp2 = __esm(() => {
   server.registerTool("list_unread_counts", {
     description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
     inputSchema: {
-      agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+      agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts."),
+      include_mentions: exports_external.coerce.boolean().optional().describe("Include mention_count per space (requires agent)")
     }
   }, async (args) => {
+    if (args.agent && args.include_mentions) {
+      const counts2 = listUnreadCountsWithMentions(args.agent);
+      return { content: [{ type: "text", text: JSON.stringify(counts2) }] };
+    }
     const counts = listUnreadCounts(args.agent);
-    return {
-      content: [{ type: "text", text: JSON.stringify(counts) }]
-    };
+    return { content: [{ type: "text", text: JSON.stringify(counts) }] };
+  });
+  server.registerTool("get_mentions", {
+    description: "Get messages that @mention a specific agent. Useful for catching up on missed pings.",
+    inputSchema: {
+      agent: exports_external.string().describe("Agent name to find mentions for"),
+      space: exports_external.string().optional().describe("Filter to a specific space"),
+      unread_only: exports_external.coerce.boolean().optional().describe("Only unread (not yet notified) mentions (default: true)"),
+      limit: exports_external.coerce.number().optional().describe("Max results (default: 50)")
+    }
+  }, async (args) => {
+    const results = getMessagesForAgent(args.agent, {
+      space: args.space,
+      unread_only: args.unread_only ?? true,
+      limit: args.limit
+    });
+    return { content: [{ type: "text", text: JSON.stringify({ mentions: results, count: results.length }) }] };
+  });
+  server.registerTool("mark_mentions_read", {
+    description: "Mark @mentions as seen for an agent. Clears unread mention counts.",
+    inputSchema: {
+      agent: exports_external.string().describe("Agent name"),
+      space: exports_external.string().optional().describe("Clear only mentions in this space")
+    }
+  }, async (args) => {
+    const cleared = markMentionsRead(args.agent, args.space);
+    return { content: [{ type: "text", text: JSON.stringify({ cleared }) }] };
   });
   server.registerTool("send_to_space", {
     description: "Post a message to a space.",

package/bin/mcp.js

@@ -6749,6 +6749,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -28839,6 +28853,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -28880,6 +28900,10 @@ function readMessages(opts = {}) {
   if (opts.threads_only) {
     conditions.push("reply_to IS NULL");
   }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
@@ -29119,6 +29143,14 @@ function searchMessages(opts) {
       extraWhere += " AND m.to_agent = ?";
       ftsParams.push(opts.to);
     }
+    if (opts.since) {
+      extraWhere += " AND m.created_at >= ?";
+      ftsParams.push(opts.since);
+    }
+    if (opts.until) {
+      extraWhere += " AND m.created_at <= ?";
+      ftsParams.push(opts.until);
+    }
     const orderClause = sortByRelevance ? "ORDER BY rank" : "ORDER BY m.created_at DESC, m.id DESC";
     const rows2 = db2.prepare(`SELECT m.*, rank,
         snippet(messages_fts, 0, '**', '**', '...', 20) as snippet
@@ -29151,6 +29183,14 @@ function searchMessages(opts) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.since) {
+    conditions.push("created_at >= ?");
+    params.push(opts.since);
+  }
+  if (opts.until) {
+    conditions.push("created_at <= ?");
+    params.push(opts.until);
+  }
   const where = `WHERE ${conditions.join(" AND ")}`;
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at DESC, id DESC LIMIT ${limit}`).all(...params);
   return rows.map((row) => {
@@ -29191,6 +29231,73 @@ function listUnreadCounts(agent) {
   `).all();
   return rows;
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
+function listUnreadCountsWithMentions(agent) {
+  const db2 = getDb();
+  const rows = db2.prepare(`
+    SELECT
+      space,
+      COUNT(CASE WHEN read_at IS NULL AND (to_agent = ? OR to_agent IS NULL OR to_agent = '') THEN 1 END) AS unread_count,
+      (SELECT COUNT(*) FROM message_mentions mm WHERE mm.space = m.space AND mm.mentioned_agent = ? AND mm.notified_at IS NULL) AS mention_count,
+      MAX(created_at) AS latest_message_at
+    FROM messages m
+    WHERE space IN (
+      SELECT DISTINCT space FROM space_members WHERE agent = ?
+      UNION
+      SELECT DISTINCT space FROM messages WHERE to_agent = ? AND space IS NOT NULL
+    )
+    GROUP BY space
+    HAVING COUNT(*) > 0
+    ORDER BY mention_count DESC, unread_count DESC, latest_message_at DESC
+  `).all(agent, agent, agent, agent);
+  return rows;
+}
+function getMessagesForAgent(agent, opts) {
+  const db2 = getDb();
+  const conditions = ["mm.mentioned_agent = ?"];
+  const params = [agent.toLowerCase()];
+  if (opts?.space) {
+    conditions.push("m.space = ?");
+    params.push(opts.space);
+  }
+  if (opts?.unread_only) {
+    conditions.push("mm.notified_at IS NULL");
+  }
+  const limit = opts?.limit ?? 50;
+  const rows = db2.prepare(`SELECT m.*, mm.id AS mention_id FROM messages m
+     JOIN message_mentions mm ON mm.message_id = m.id
+     WHERE ${conditions.join(" AND ")}
+     ORDER BY m.created_at DESC LIMIT ${limit}`).all(...params);
+  return rows.map(({ mention_id, ...row }) => ({ message: parseMessage(row), mention_id }));
+}
+function markMentionsRead(agent, space) {
+  const db2 = getDb();
+  if (space) {
+    const result2 = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND space = ? AND notified_at IS NULL").run(agent, space);
+    return result2.changes;
+  }
+  const result = db2.prepare("UPDATE message_mentions SET notified_at = strftime('%Y-%m-%dT%H:%M:%f', 'now') WHERE mentioned_agent = ? AND notified_at IS NULL").run(agent);
+  return result.changes;
+}
 
 // src/lib/sessions.ts
 init_db();
@@ -30817,7 +30924,7 @@ function getGraphStats() {
 // package.json
 var package_default = {
   name: "@hasna/conversations",
-  version: "0.2.5",
+  version: "0.2.7",
   description: "Real-time CLI messaging for AI agents",
   type: "module",
   bin: {
@@ -30951,7 +31058,8 @@ server.registerTool("read_messages", {
     mark_read: exports_external.coerce.boolean().optional(),
     max_content_length: exports_external.coerce.number().optional().describe("Truncate each message content to N chars (adds truncated:true flag)"),
     threads_only: exports_external.coerce.boolean().optional().describe("Only return root messages (reply_to IS NULL) \u2014 hides thread replies"),
-    include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)")
+    include_reply_counts: exports_external.coerce.boolean().optional().describe("Include reply_count on each message (adds one extra query)"),
+    mentions_only: exports_external.string().optional().describe("Only return messages that @mention this agent")
   }
 }, async (args) => {
   const agent = resolveIdentity(args.from);
@@ -31034,19 +31142,26 @@ server.registerTool("mark_read", {
   };
 });
 server.registerTool("search_messages", {
-  description: "Full-text search across messages.",
+  description: "Full-text search across messages. Uses FTS5 with BM25 ranking if available, falls back to LIKE. Returns messages with snippet and relevance_score.",
   inputSchema: {
-    query: exports_external.string(),
-    space: exports_external.string().optional(),
-    from: exports_external.string().optional(),
-    to: exports_external.string().optional(),
-    limit: exports_external.coerce.number().optional()
+    query: exports_external.string().describe(`Search query. Wrap in quotes for exact phrase: '"BUG-005"'`),
+    space: exports_external.string().optional().describe("Limit to a specific space"),
+    from: exports_external.string().optional().describe("Filter by sender"),
+    to: exports_external.string().optional().describe("Filter by recipient"),
+    since: exports_external.string().optional().describe("ISO 8601 date \u2014 only messages after this"),
+    until: exports_external.string().optional().describe("ISO 8601 date \u2014 only messages before this"),
+    sort: exports_external.enum(["relevance", "recent"]).optional().describe("Sort order (default: relevance)"),
+    limit: exports_external.coerce.number().optional().describe("Max results (default: 20)")
   }
 }, async (args) => {
-  const { query, space, from, to, limit } = args;
-  const messages = searchMessages({ query, space, from, to, limit });
+  const { query, space, from, to, since, until, sort, limit } = args;
+  const results = searchMessages({ query, space, from, to, since, until, sort, limit });
   return {
-    content: [{ type: "text", text: JSON.stringify(messages) }]
+    content: [{ type: "text", text: JSON.stringify({
+      results,
+      count: results.length,
+      query
+    }) }]
   };
 });
 server.registerTool("export_messages", {
@@ -31123,13 +31238,42 @@ server.registerTool("list_spaces", {
 server.registerTool("list_unread_counts", {
   description: "Get unread message counts per space without fetching message content. Use this at session start to triage which spaces need attention before calling read_messages.",
   inputSchema: {
-    agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts.")
+    agent: exports_external.string().optional().describe("Filter to spaces the agent is a member of or has received messages in. Omit for global unread counts."),
+    include_mentions: exports_external.coerce.boolean().optional().describe("Include mention_count per space (requires agent)")
   }
 }, async (args) => {
+  if (args.agent && args.include_mentions) {
+    const counts2 = listUnreadCountsWithMentions(args.agent);
+    return { content: [{ type: "text", text: JSON.stringify(counts2) }] };
+  }
   const counts = listUnreadCounts(args.agent);
-  return {
-    content: [{ type: "text", text: JSON.stringify(counts) }]
-  };
+  return { content: [{ type: "text", text: JSON.stringify(counts) }] };
+});
+server.registerTool("get_mentions", {
+  description: "Get messages that @mention a specific agent. Useful for catching up on missed pings.",
+  inputSchema: {
+    agent: exports_external.string().describe("Agent name to find mentions for"),
+    space: exports_external.string().optional().describe("Filter to a specific space"),
+    unread_only: exports_external.coerce.boolean().optional().describe("Only unread (not yet notified) mentions (default: true)"),
+    limit: exports_external.coerce.number().optional().describe("Max results (default: 50)")
+  }
+}, async (args) => {
+  const results = getMessagesForAgent(args.agent, {
+    space: args.space,
+    unread_only: args.unread_only ?? true,
+    limit: args.limit
+  });
+  return { content: [{ type: "text", text: JSON.stringify({ mentions: results, count: results.length }) }] };
+});
+server.registerTool("mark_mentions_read", {
+  description: "Mark @mentions as seen for an agent. Clears unread mention counts.",
+  inputSchema: {
+    agent: exports_external.string().describe("Agent name"),
+    space: exports_external.string().optional().describe("Clear only mentions in this space")
+  }
+}, async (args) => {
+  const cleared = markMentionsRead(args.agent, args.space);
+  return { content: [{ type: "text", text: JSON.stringify({ cleared }) }] };
 });
 server.registerTool("send_to_space", {
   description: "Post a message to a space.",

package/dist/index.js

@@ -276,6 +276,20 @@ function getDb() {
   if (!presenceColNames.includes("project_id")) {
     db.exec("ALTER TABLE agent_presence ADD COLUMN project_id TEXT");
   }
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS message_mentions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      message_id INTEGER NOT NULL REFERENCES messages(id) ON DELETE CASCADE,
+      mentioned_agent TEXT NOT NULL,
+      from_agent TEXT NOT NULL,
+      space TEXT,
+      notified_at TEXT,
+      created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%f', 'now'))
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_agent ON message_mentions(mentioned_agent)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_message ON message_mentions(message_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS idx_mentions_notified ON message_mentions(notified_at)");
   const ftsExists = db.prepare("SELECT name FROM sqlite_master WHERE type='table' AND name='messages_fts'").get();
   if (!ftsExists) {
     db.exec(`
@@ -2304,6 +2318,12 @@ function sendMessage(opts) {
     db2.prepare("UPDATE messages SET attachments = ? WHERE id = ?").run(attachmentsJson, message.id);
     message.attachments = attachmentInfos;
   }
+  if (opts.space) {
+    const mentions = parseMentions(opts.content);
+    if (mentions.length > 0) {
+      processMentions(message.id, opts.from, opts.space, mentions, db2);
+    }
+  }
   fireWebhooks(message);
   return message;
 }
@@ -2345,6 +2365,10 @@ function readMessages(opts = {}) {
   if (opts.threads_only) {
     conditions.push("reply_to IS NULL");
   }
+  if (opts.mentions_only) {
+    conditions.push(`id IN (SELECT message_id FROM message_mentions WHERE mentioned_agent = ?)`);
+    params.push(opts.mentions_only.toLowerCase());
+  }
   const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
   const resolvedLimit = Number.isFinite(opts.limit) && opts.limit > 0 ? Math.floor(opts.limit) : 20;
   const order = opts.order?.toLowerCase() === "desc" ? "DESC" : "ASC";
@@ -2544,6 +2568,14 @@ function searchMessages(opts) {
       extraWhere += " AND m.to_agent = ?";
       ftsParams.push(opts.to);
     }
+    if (opts.since) {
+      extraWhere += " AND m.created_at >= ?";
+      ftsParams.push(opts.since);
+    }
+    if (opts.until) {
+      extraWhere += " AND m.created_at <= ?";
+      ftsParams.push(opts.until);
+    }
     const orderClause = sortByRelevance ? "ORDER BY rank" : "ORDER BY m.created_at DESC, m.id DESC";
     const rows2 = db2.prepare(`SELECT m.*, rank,
         snippet(messages_fts, 0, '**', '**', '...', 20) as snippet
@@ -2576,6 +2608,14 @@ function searchMessages(opts) {
     conditions.push("to_agent = ?");
     params.push(opts.to);
   }
+  if (opts.since) {
+    conditions.push("created_at >= ?");
+    params.push(opts.since);
+  }
+  if (opts.until) {
+    conditions.push("created_at <= ?");
+    params.push(opts.until);
+  }
   const where = `WHERE ${conditions.join(" AND ")}`;
   const rows = db2.prepare(`SELECT * FROM messages ${where} ORDER BY created_at DESC, id DESC LIMIT ${limit}`).all(...params);
   return rows.map((row) => {
@@ -2583,6 +2623,26 @@ function searchMessages(opts) {
     return { ...msg, snippet: null, relevance_score: 0 };
   });
 }
+function parseMentions(content) {
+  const matches = content.match(/@([a-zA-Z0-9_-]+)/g) ?? [];
+  return [...new Set(matches.map((m) => m.slice(1).toLowerCase()))];
+}
+async function processMentions(messageId, fromAgent, space, mentionedAgents, db2) {
+  const stmt = db2.prepare("INSERT INTO message_mentions (message_id, mentioned_agent, from_agent, space) VALUES (?, ?, ?, ?)");
+  for (const agent of mentionedAgents) {
+    try {
+      stmt.run(messageId, agent, fromAgent, space);
+      if (agent !== fromAgent.toLowerCase()) {
+        sendMessage({
+          from: fromAgent,
+          to: agent,
+          content: `You were mentioned in #${space} by ${fromAgent} (message #${messageId})`,
+          metadata: { type: "mention_notification", source_message_id: messageId, space }
+        });
+      }
+    } catch {}
+  }
+}
 // src/lib/sessions.ts
 init_db();
 function listSessions(agent) {

package/dist/lib/messages.d.ts

@@ -67,3 +67,24 @@ export interface UnreadCount {
  * If agent is omitted, returns counts for all spaces.
  */
 export declare function listUnreadCounts(agent?: string): UnreadCount[];
+/** Extract @agentname mentions from message content. Returns unique agent names (lowercase). */
+export declare function parseMentions(content: string): string[];
+export interface MentionCount {
+    space: string;
+    unread_count: number;
+    mention_count: number;
+    latest_message_at: string | null;
+}
+/** Get unread counts AND mention counts per space for an agent. */
+export declare function listUnreadCountsWithMentions(agent: string): MentionCount[];
+/** Get messages that mention a specific agent. */
+export declare function getMessagesForAgent(agent: string, opts?: {
+    space?: string;
+    unread_only?: boolean;
+    limit?: number;
+}): Array<{
+    message: Message;
+    mention_id: number;
+}>;
+/** Mark mentions as notified (agent has seen them). */
+export declare function markMentionsRead(agent: string, space?: string): number;

package/dist/types.d.ts

@@ -111,14 +111,18 @@ export interface ReadMessagesOptions {
     max_content_length?: number;
     threads_only?: boolean;
     include_reply_counts?: boolean;
+    mentions_only?: string;
 }
 export interface SearchMessagesOptions {
     query: string;
     space?: string;
     from?: string;
     to?: string;
+    since?: string;
+    until?: string;
     limit?: number;
     sort?: "relevance" | "recent";
+    snippet_length?: number;
 }
 export interface SearchResult extends Message {
     snippet: string | null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/conversations",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Real-time CLI messaging for AI agents",
   "type": "module",
   "bin": {