@aeriondyseti/vector-memory-mcp 2.2.2 → 2.2.6-dev.1

package/server/core/migrations.ts

@@ -0,0 +1,263 @@
+import type { Database } from "bun:sqlite";
+import type { EmbeddingsService } from "./embeddings.service.js";
+import { serializeVector } from "./sqlite-utils.js";
+
+/**
+ * Pre-migration step: remove vec0 virtual table entries from sqlite_master
+ * and drop their shadow tables using the sqlite3 CLI.
+ *
+ * Must run BEFORE bun:sqlite opens the database because:
+ *  - bun:sqlite cannot modify sqlite_master (no writable_schema support)
+ *  - DROP TABLE on a virtual table requires the extension module to be loaded
+ *  - SQLite 3.51+ has defensive mode on by default, requiring .dbconfig override
+ *
+ * Safe to call on any database — it's a no-op if there are no vec0 tables.
+ */
+export function removeVec0Tables(dbPath: string): void {
+  const result = Bun.spawnSync({
+    cmd: ["sqlite3", dbPath],
+    stdin: new TextEncoder().encode(
+      [
+        ".dbconfig defensive off",
+        ".dbconfig writable_schema on",
+        // Drop shadow tables (regular tables, no extension needed)
+        "DROP TABLE IF EXISTS memories_vec_rowids;",
+        "DROP TABLE IF EXISTS memories_vec_chunks;",
+        "DROP TABLE IF EXISTS memories_vec_info;",
+        "DROP TABLE IF EXISTS memories_vec_vector_chunks00;",
+        "DROP TABLE IF EXISTS memories_vec_migration_tmp;",
+        "DROP TABLE IF EXISTS conversation_history_vec_rowids;",
+        "DROP TABLE IF EXISTS conversation_history_vec_chunks;",
+        "DROP TABLE IF EXISTS conversation_history_vec_info;",
+        "DROP TABLE IF EXISTS conversation_history_vec_vector_chunks00;",
+        "DROP TABLE IF EXISTS conversation_history_vec_migration_tmp;",
+        // Remove orphaned vec0 virtual table entries from schema
+        "DELETE FROM sqlite_master WHERE sql LIKE '%vec0%';",
+      ].join("\n"),
+    ),
+  });
+  if (result.exitCode !== 0) {
+    const stderr = result.stderr.toString().trim();
+    if (!stderr.includes("unable to open database")) {
+      throw new Error(`vec0 cleanup failed: ${stderr}`);
+    }
+  }
+}
+
+/**
+ * Run all schema migrations. Safe to call on every startup (uses IF NOT EXISTS).
+ *
+ * IMPORTANT: Call removeVec0Tables(dbPath) before opening the database
+ * with bun:sqlite if the database may contain vec0 virtual tables.
+ */
+export function runMigrations(db: Database): void {
+  // -- Memories --
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id            TEXT PRIMARY KEY,
+      content       TEXT NOT NULL,
+      metadata      TEXT NOT NULL DEFAULT '{}',
+      created_at    INTEGER NOT NULL,
+      updated_at    INTEGER NOT NULL,
+      superseded_by TEXT,
+      usefulness    REAL NOT NULL DEFAULT 0.0,
+      access_count  INTEGER NOT NULL DEFAULT 0,
+      last_accessed INTEGER
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS memories_vec (
+      id     TEXT PRIMARY KEY,
+      vector BLOB NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+      id UNINDEXED,
+      content
+    )
+  `);
+
+  // -- Conversation History --
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_history (
+      id                  TEXT PRIMARY KEY,
+      content             TEXT NOT NULL,
+      metadata            TEXT NOT NULL DEFAULT '{}',
+      created_at          INTEGER NOT NULL,
+      session_id          TEXT NOT NULL,
+      role                TEXT NOT NULL,
+      message_index_start INTEGER NOT NULL,
+      message_index_end   INTEGER NOT NULL,
+      project             TEXT NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS conversation_history_vec (
+      id     TEXT PRIMARY KEY,
+      vector BLOB NOT NULL
+    )
+  `);
+
+  db.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS conversation_history_fts USING fts5(
+      id UNINDEXED,
+      content
+    )
+  `);
+
+  // -- Indexes --
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_session_id ON conversation_history(session_id)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_project ON conversation_history(project)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_role ON conversation_history(role)`);
+  db.exec(`CREATE INDEX IF NOT EXISTS idx_conversation_created_at ON conversation_history(created_at)`);
+}
+
+/**
+ * Backfill missing vectors in memories_vec and conversation_history_vec.
+ *
+ * After the vec0-to-BLOB migration, existing rows may lack vector embeddings.
+ * This re-embeds their content and inserts into the _vec tables.
+ * Idempotent: skips rows that already have vectors. Fast no-op when fully backfilled.
+ */
+export async function backfillVectors(
+  db: Database,
+  embeddings: EmbeddingsService,
+): Promise<void> {
+  // Fast sentinel check: skip the LEFT JOIN queries entirely when backfill is done
+  const sentinel = db
+    .prepare("SELECT 1 FROM memories_vec LIMIT 1")
+    .get();
+  const memoriesExist = db.prepare("SELECT 1 FROM memories LIMIT 1").get();
+  const convosExist = db.prepare("SELECT 1 FROM conversation_history LIMIT 1").get();
+
+  // If vec tables have data and source tables have data, backfill is likely complete.
+  // Only run the expensive LEFT JOIN when there's reason to suspect gaps.
+  const convoSentinel = db
+    .prepare("SELECT 1 FROM conversation_history_vec LIMIT 1")
+    .get();
+  const mayNeedMemoryBackfill = memoriesExist && !sentinel;
+  const mayNeedConvoBackfill = convosExist && !convoSentinel;
+
+  // If both vec tables are populated, do a quick count check to confirm
+  if (!mayNeedMemoryBackfill && !mayNeedConvoBackfill) {
+    if (memoriesExist) {
+      const gap = db.prepare(
+        `SELECT 1 FROM memories m LEFT JOIN memories_vec v ON m.id = v.id
+         WHERE v.id IS NULL OR length(v.vector) = 0 LIMIT 1`,
+      ).get();
+      if (!gap && convosExist) {
+        const convoGap = db.prepare(
+          `SELECT 1 FROM conversation_history c LEFT JOIN conversation_history_vec v ON c.id = v.id
+           WHERE v.id IS NULL OR length(v.vector) = 0 LIMIT 1`,
+        ).get();
+        if (!convoGap) return;
+      } else if (!gap && !convosExist) {
+        return;
+      }
+    } else {
+      return; // No data at all
+    }
+  }
+
+  // ── Memories ──────────────────────────────────────────────────────
+  const missingMemories = db
+    .prepare(
+      `SELECT m.id, m.content, json_extract(m.metadata, '$.type') AS type
+       FROM memories m
+       LEFT JOIN memories_vec v ON m.id = v.id
+       WHERE v.id IS NULL OR length(v.vector) = 0`,
+    )
+    .all() as Array<{ id: string; content: string; type: string | null }>;
+
+  if (missingMemories.length > 0) {
+    console.error(
+      `[vector-memory-mcp] Backfilling vectors for ${missingMemories.length} memories...`,
+    );
+
+    const insertVec = db.prepare(
+      "INSERT OR REPLACE INTO memories_vec (id, vector) VALUES (?, ?)",
+    );
+
+    const zeroVector = serializeVector(
+      new Array(embeddings.dimension).fill(0),
+    );
+
+    // Separate waypoints from content that needs embedding
+    const toEmbed = missingMemories.filter((r) => r.type !== "waypoint");
+    const waypoints = missingMemories.filter((r) => r.type === "waypoint");
+
+    // Batch embed all non-waypoint content
+    const vectors = toEmbed.length > 0
+      ? await embeddings.embedBatch(toEmbed.map((r) => r.content))
+      : [];
+
+    db.exec("BEGIN");
+    try {
+      for (const row of waypoints) {
+        insertVec.run(row.id, zeroVector);
+      }
+      for (let i = 0; i < toEmbed.length; i++) {
+        insertVec.run(toEmbed[i].id, serializeVector(vectors[i]));
+      }
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+
+    console.error(
+      `[vector-memory-mcp] Backfilled ${missingMemories.length} memory vectors`,
+    );
+  }
+
+  // ── Conversation history ──────────────────────────────────────────
+  const missingConvos = db
+    .prepare(
+      `SELECT c.id, c.content
+       FROM conversation_history c
+       LEFT JOIN conversation_history_vec v ON c.id = v.id
+       WHERE v.id IS NULL OR length(v.vector) = 0`,
+    )
+    .all() as Array<{ id: string; content: string }>;
+
+  if (missingConvos.length > 0) {
+    console.error(
+      `[vector-memory-mcp] Backfilling vectors for ${missingConvos.length} conversation chunks...`,
+    );
+
+    const insertConvoVec = db.prepare(
+      "INSERT OR REPLACE INTO conversation_history_vec (id, vector) VALUES (?, ?)",
+    );
+
+    // Batch embed in chunks of 32
+    const BATCH_SIZE = 32;
+    db.exec("BEGIN");
+    try {
+      for (let i = 0; i < missingConvos.length; i += BATCH_SIZE) {
+        const batch = missingConvos.slice(i, i + BATCH_SIZE);
+        const vecs = await embeddings.embedBatch(batch.map((r) => r.content));
+        for (let j = 0; j < batch.length; j++) {
+          insertConvoVec.run(batch[j].id, serializeVector(vecs[j]));
+        }
+
+        if ((i + BATCH_SIZE) % 100 < BATCH_SIZE) {
+          console.error(
+            `[vector-memory-mcp]   ...${Math.min(i + BATCH_SIZE, missingConvos.length)}/${missingConvos.length} conversation chunks`,
+          );
+        }
+      }
+      db.exec("COMMIT");
+    } catch (e) {
+      db.exec("ROLLBACK");
+      throw e;
+    }
+
+    console.error(
+      `[vector-memory-mcp] Backfilled ${missingConvos.length} conversation vectors`,
+    );
+  }
+}

package/{src/services → server/core}/parsers/claude-code.parser.ts

@@ -1,6 +1,6 @@
 import { readFile, readdir, stat } from "fs/promises";
 import { basename, dirname, join } from "path";
-import type { ParsedMessage, SessionFileInfo } from "../../types/conversation.js";
+import type { ParsedMessage, SessionFileInfo } from "../conversation.js";
 import type { SessionLogParser } from "./types.js";
 
 // UUID pattern for session IDs

package/{src/services → server/core}/parsers/types.ts

@@ -1,4 +1,4 @@
-import type { ParsedMessage, SessionFileInfo } from "../../types/conversation.js";
+import type { ParsedMessage, SessionFileInfo } from "../conversation.js";
 
 /** Interface for parsing session log files into structured messages */
 export interface SessionLogParser {

package/{src → server}/index.ts

@@ -1,34 +1,15 @@
 #!/usr/bin/env bun
 
 import { loadConfig, parseCliArgs } from "./config/index.js";
-import { connectToDatabase } from "./db/connection.js";
-import { MemoryRepository } from "./db/memory.repository.js";
-import { ConversationRepository } from "./db/conversation.repository.js";
-import { EmbeddingsService } from "./services/embeddings.service.js";
-import { MemoryService } from "./services/memory.service.js";
-import { ConversationHistoryService } from "./services/conversation.service.js";
-import { startServer } from "./mcp/server.js";
-import { startHttpServer, removeLockfile } from "./http/server.js";
-import { isLanceDbDirectory, migrate, formatMigrationSummary } from "./migration.js";
-
-async function runMigrate(args: string[]): Promise<void> {
-  const overrides = parseCliArgs(args.slice(1)); // skip "migrate"
-  const config = loadConfig(overrides);
-
-  const source = config.dbPath;
-  const target = source.endsWith(".sqlite") ? source.replace(/\.sqlite$/, "-migrated.sqlite") : source + ".sqlite";
-
-  if (!isLanceDbDirectory(source)) {
-    console.error(
-      `[vector-memory-mcp] No LanceDB data found at ${source}\n` +
-      `  Nothing to migrate. The server will create a fresh SQLite database on startup.`
-    );
-    return;
-  }
-
-  const result = await migrate({ source, target });
-  console.error(formatMigrationSummary(source, target, result));
-}
+import { connectToDatabase } from "./core/connection.js";
+import { backfillVectors } from "./core/migrations.js";
+import { MemoryRepository } from "./core/memory.repository.js";
+import { ConversationRepository } from "./core/conversation.repository.js";
+import { EmbeddingsService } from "./core/embeddings.service.js";
+import { MemoryService } from "./core/memory.service.js";
+import { ConversationHistoryService } from "./core/conversation.service.js";
+import { startServer } from "./transports/mcp/server.js";
+import { startHttpServer } from "./transports/http/server.js";
 
 async function main(): Promise<void> {
   const args = process.argv.slice(2);
@@ -40,35 +21,23 @@ async function main(): Promise<void> {
     return;
   }
 
-  // Check for migrate command
-  if (args[0] === "migrate") {
-    await runMigrate(args);
-    return;
-  }
-
   // Parse CLI args and load config
   const overrides = parseCliArgs(args);
   const config = loadConfig(overrides);
 
-  // Detect legacy LanceDB data and warn
-  if (isLanceDbDirectory(config.dbPath)) {
-    console.error(
-      `[vector-memory-mcp] ⚠️  Legacy LanceDB data detected at ${config.dbPath}\n` +
-      `  Your data must be migrated to the new SQLite format.\n` +
-      `  Run: vector-memory-mcp migrate\n` +
-      `  Or:  bun run src/index.ts migrate\n`
-    );
-    process.exit(1);
-  }
-
-  // Initialize database
+  // Initialize database and backfill any missing vectors before services start
   const db = connectToDatabase(config.dbPath);
+  const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
+  await backfillVectors(db, embeddings);
 
   // Initialize layers
   const repository = new MemoryRepository(db);
-  const embeddings = new EmbeddingsService(config.embeddingModel, config.embeddingDimension);
   const memoryService = new MemoryService(repository, embeddings);
 
+  if (config.pluginMode) {
+    console.error("[vector-memory-mcp] Running in plugin mode");
+  }
+
   // Conditionally initialize conversation history indexing
   if (config.conversationHistory.enabled) {
     const conversationRepository = new ConversationRepository(db);
@@ -88,7 +57,6 @@ async function main(): Promise<void> {
   // Graceful shutdown handler
   const shutdown = () => {
     console.error("[vector-memory-mcp] Shutting down...");
-    removeLockfile();
     if (httpStop) httpStop();
     db.close();
     process.exit(0);

package/{src → server/transports}/http/mcp-transport.ts

@@ -24,8 +24,8 @@ import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { tools } from "../mcp/tools.js";
 import { handleToolCall } from "../mcp/handlers.js";
 import { SERVER_INSTRUCTIONS } from "../mcp/server.js";
-import { VERSION } from "../config/index.js";
-import type { MemoryService } from "../services/memory.service.js";
+import { VERSION } from "../../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
 
 interface Session {
   server: Server;

package/{src → server/transports}/http/server.ts

@@ -3,11 +3,12 @@ import { cors } from "hono/cors";
 import { createServer } from "net";
 import { writeFileSync, mkdirSync, unlinkSync } from "fs";
 import { join } from "path";
-import type { MemoryService } from "../services/memory.service.js";
-import type { Config } from "../config/index.js";
-import { isDeleted } from "../types/memory.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import type { Config } from "../../config/index.js";
+import { isDeleted } from "../../core/memory.js";
 import { createMcpRoutes } from "./mcp-transport.js";
-import type { Memory, SearchIntent } from "../types/memory.js";
+import type { Memory, SearchIntent } from "../../core/memory.js";
+
 
 /**
  * Check if a port is available by attempting to bind to it
@@ -109,6 +110,7 @@ export function createHttpApp(memoryService: MemoryService, config: Config): Hon
         embeddingModel: config.embeddingModel,
         embeddingDimension: config.embeddingDimension,
         historyEnabled: config.conversationHistory.enabled,
+        pluginMode: config.pluginMode,
       },
     });
   });

package/{src → server/transports}/mcp/handlers.ts

@@ -1,9 +1,9 @@
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import type { MemoryService } from "../services/memory.service.js";
-import type { ConversationHistoryService } from "../services/conversation.service.js";
-import type { SearchIntent } from "../types/memory.js";
-import type { HistoryFilters, SearchResult } from "../types/conversation.js";
-import { DEBUG } from "../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import type { ConversationHistoryService } from "../../core/conversation.service.js";
+import type { SearchIntent } from "../../core/memory.js";
+import type { HistoryFilters, SearchResult } from "../../core/conversation.js";
+import { DEBUG } from "../../config/index.js";
 
 /**
  * Safely coerce a tool argument to an array. Handles the case where the MCP

package/server/transports/mcp/resources.ts

@@ -0,0 +1,20 @@
+export const resources: Array<{
+  uri: string;
+  name: string;
+  description: string;
+  mimeType: string;
+}> = [];
+
+const RESOURCE_CONTENT: Record<string, string> = {};
+
+export function readResource(uri: string): {
+  contents: Array<{ uri: string; mimeType: string; text: string }>;
+} {
+  const text = RESOURCE_CONTENT[uri];
+  if (!text) {
+    throw new Error(`Resource not found: ${uri}`);
+  }
+  return {
+    contents: [{ uri, mimeType: "text/markdown", text }],
+  };
+}

package/{src → server/transports}/mcp/server.ts

@@ -3,12 +3,15 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import {
   CallToolRequestSchema,
   ListToolsRequestSchema,
+  ListResourcesRequestSchema,
+  ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
+import { resources, readResource } from "./resources.js";
 
 import { tools } from "./tools.js";
 import { handleToolCall } from "./handlers.js";
-import type { MemoryService } from "../services/memory.service.js";
-import { VERSION } from "../config/index.js";
+import type { MemoryService } from "../../core/memory.service.js";
+import { VERSION } from "../../config/index.js";
 
 export const SERVER_INSTRUCTIONS = `This server is the user's canonical memory system. It provides persistent, semantic vector memory that survives across conversations and sessions.
 
@@ -20,7 +23,7 @@ export function createServer(memoryService: MemoryService): Server {
   const server = new Server(
     { name: "vector-memory-mcp", version: VERSION },
     {
-      capabilities: { tools: {} },
+      capabilities: { tools: {}, resources: {} },
       instructions: SERVER_INSTRUCTIONS,
     }
   );
@@ -34,6 +37,14 @@ export function createServer(memoryService: MemoryService): Server {
     return handleToolCall(name, args, memoryService);
   });
 
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return { resources };
+  });
+
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    return readResource(request.params.uri);
+  });
+
   return server;
 }
 

package/server/utils/formatting.ts

@@ -0,0 +1,143 @@
+/**
+ * Shared text formatting utilities.
+ *
+ * Provides ANSI styling, Nerd Font icons, horizontal rules, structured
+ * message builders, debug logging, and time formatting. Used by both the
+ * MCP server and the Claude Code plugin hooks.
+ */
+
+// ── ANSI escape codes ───────────────────────────────────────────────
+
+export const ansi = {
+  reset: "\x1b[0m",
+  bold: "\x1b[1m",
+  dim: "\x1b[2m",
+  italic: "\x1b[3m",
+  underline: "\x1b[4m",
+
+  // Foreground colors
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+} as const;
+
+// ── Nerd Font glyphs (single-width) ────────────────────────────────
+
+export const icon = {
+  check: "\uf00c", // nf-fa-check
+  cross: "\uf00d", // nf-fa-close
+  book: "\uf02d", // nf-fa-book
+  branch: "\ue0a0", // Powerline branch
+  clock: "\uf017", // nf-fa-clock_o
+  warning: "\uf071", // nf-fa-warning
+  bolt: "\uf0e7", // nf-fa-bolt
+  brain: "\uf5dc", // nf-mdi-brain
+  search: "\uf002", // nf-fa-search
+  gear: "\uf013", // nf-fa-gear
+  database: "\uf1c0", // nf-fa-database
+  arrow: "\uf061", // nf-fa-arrow_right
+  dot: "\u00b7", // middle dot (standard unicode)
+} as const;
+
+// ── Rule line ───────────────────────────────────────────────────────
+
+const RULE_WIDTH = 42;
+
+/**
+ * Create a horizontal rule with an optional inline title.
+ * e.g. "── Vector Memory ──────────────────────"
+ */
+export function rule(title?: string): string {
+  if (!title) {
+    return `${ansi.cyan}${"─".repeat(RULE_WIDTH)}${ansi.reset}`;
+  }
+  const label = ` ${ansi.bold}${title}${ansi.reset} `;
+  // "── " prefix = 3 visual chars
+  const prefix = `${ansi.cyan}── ${ansi.reset}`;
+  // Calculate remaining dashes (account for title visual length)
+  const remaining = RULE_WIDTH - 3 - title.length - 2; // 2 for spaces around title
+  const suffix = `${ansi.cyan}${"─".repeat(Math.max(1, remaining))}${ansi.reset}`;
+  return `${prefix}${label}${suffix}`;
+}
+
+// ── System message builder ──────────────────────────────────────────
+
+export interface MessageLine {
+  icon?: string;
+  iconColor?: string;
+  text: string;
+}
+
+/**
+ * Build a user-facing systemMessage with horizontal rules and content lines.
+ *
+ * Output format:
+ *   ── Title ──────────────────────────────
+ *     icon text
+ *     icon text
+ *   ──────────────────────────────────────
+ *
+ * Prepends an empty line so the content starts below the hook label prefix.
+ */
+export function buildSystemMessage(
+  title: string,
+  lines: MessageLine[]
+): string {
+  const parts = [
+    "", // push below "HookName says:" prefix
+    rule(title),
+  ];
+
+  for (const line of lines) {
+    if (line.icon) {
+      const color = line.iconColor ?? "";
+      const reset = line.iconColor ? ansi.reset : "";
+      parts.push(`  ${color}${line.icon}${reset} ${line.text}`);
+    } else {
+      parts.push(`  ${line.text}`);
+    }
+  }
+
+  parts.push(rule());
+  return parts.join("\n");
+}
+
+// ── Diagnostic logging ──────────────────────────────────────────────
+
+/**
+ * Log a diagnostic message to stderr when VECTOR_MEMORY_DEBUG=1.
+ */
+export function debug(label: string, message: string): void {
+  if (process.env.VECTOR_MEMORY_DEBUG !== "1") return;
+  console.error(
+    `${ansi.gray}[${label}]${ansi.reset} ${ansi.dim}${message}${ansi.reset}`
+  );
+}
+
+// ── Time formatting ─────────────────────────────────────────────────
+
+export function timeAgo(iso: string): string {
+  const now = Date.now();
+  const then = new Date(iso).getTime();
+  if (Number.isNaN(then)) {
+    debug("timeAgo", `invalid ISO string: ${iso}`);
+    return "unknown";
+  }
+  const seconds = Math.floor((now - then) / 1000);
+  if (seconds < 0) {
+    debug("timeAgo", `negative delta (${seconds}s) — clock skew or future timestamp`);
+    return "just now";
+  }
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}