@hasna/mementos 0.6.0 → 0.7.0

package/dist/index.js

@@ -346,6 +346,25 @@ var MIGRATIONS = [
   ALTER TABLE memories ADD COLUMN recall_count INTEGER NOT NULL DEFAULT 0;
   CREATE INDEX IF NOT EXISTS idx_memories_recall_count ON memories(recall_count DESC);
   INSERT OR IGNORE INTO _migrations (id) VALUES (9);
+  `,
+  `
+  CREATE TABLE IF NOT EXISTS webhook_hooks (
+    id TEXT PRIMARY KEY,
+    type TEXT NOT NULL,
+    handler_url TEXT NOT NULL,
+    priority INTEGER NOT NULL DEFAULT 50,
+    blocking INTEGER NOT NULL DEFAULT 0,
+    agent_id TEXT,
+    project_id TEXT,
+    description TEXT,
+    enabled INTEGER NOT NULL DEFAULT 1,
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    invocation_count INTEGER NOT NULL DEFAULT 0,
+    failure_count INTEGER NOT NULL DEFAULT 0
+  );
+  CREATE INDEX IF NOT EXISTS idx_webhook_hooks_type ON webhook_hooks(type);
+  CREATE INDEX IF NOT EXISTS idx_webhook_hooks_enabled ON webhook_hooks(enabled);
+  INSERT OR IGNORE INTO _migrations (id) VALUES (10);
   `
 ];
 var _db = null;
@@ -443,6 +462,87 @@ function containsSecrets(text) {
   return false;
 }
 
+// src/lib/hooks.ts
+var _idCounter = 0;
+function generateHookId() {
+  return `hook_${++_idCounter}_${Date.now().toString(36)}`;
+}
+
+class HookRegistry {
+  hooks = new Map;
+  register(reg) {
+    const id = generateHookId();
+    const hook = {
+      ...reg,
+      id,
+      priority: reg.priority ?? 50
+    };
+    this.hooks.set(id, hook);
+    return id;
+  }
+  unregister(hookId) {
+    const hook = this.hooks.get(hookId);
+    if (!hook)
+      return false;
+    if (hook.builtin)
+      return false;
+    this.hooks.delete(hookId);
+    return true;
+  }
+  list(type) {
+    const all = [...this.hooks.values()];
+    if (!type)
+      return all;
+    return all.filter((h) => h.type === type);
+  }
+  async runHooks(type, context) {
+    const matching = this.getMatchingHooks(type, context);
+    if (matching.length === 0)
+      return true;
+    matching.sort((a, b) => a.priority - b.priority);
+    for (const hook of matching) {
+      if (hook.blocking) {
+        try {
+          const result = await hook.handler(context);
+          if (result === false)
+            return false;
+        } catch (err) {
+          console.error(`[hooks] blocking hook ${hook.id} (${type}) threw:`, err);
+        }
+      } else {
+        Promise.resolve().then(() => hook.handler(context)).catch((err) => console.error(`[hooks] non-blocking hook ${hook.id} (${type}) threw:`, err));
+      }
+    }
+    return true;
+  }
+  getMatchingHooks(type, context) {
+    const ctx = context;
+    return [...this.hooks.values()].filter((hook) => {
+      if (hook.type !== type)
+        return false;
+      if (hook.agentId && hook.agentId !== ctx.agentId)
+        return false;
+      if (hook.projectId && hook.projectId !== ctx.projectId)
+        return false;
+      return true;
+    });
+  }
+  stats() {
+    const all = [...this.hooks.values()];
+    const byType = {};
+    for (const hook of all) {
+      byType[hook.type] = (byType[hook.type] ?? 0) + 1;
+    }
+    return {
+      total: all.length,
+      byType,
+      blocking: all.filter((h) => h.blocking).length,
+      nonBlocking: all.filter((h) => !h.blocking).length
+    };
+  }
+}
+var hookRegistry = new HookRegistry;
+
 // src/db/entity-memories.ts
 function parseEntityRow(row) {
   return {
@@ -628,9 +728,15 @@ function createMemory(input, dedupeMode = "merge", db) {
     insertTag.run(id, tag);
   }
   const memory = getMemory(id, d);
-  try {
-    runEntityExtraction(memory, input.project_id, d);
-  } catch {}
+  runEntityExtraction(memory, input.project_id, d);
+  hookRegistry.runHooks("PostMemorySave", {
+    memory,
+    wasUpdated: false,
+    agentId: input.agent_id,
+    projectId: input.project_id,
+    sessionId: input.session_id,
+    timestamp: Date.now()
+  });
   return memory;
 }
 function getMemory(id, db) {
@@ -854,20 +960,33 @@ function updateMemory(id, input, db) {
   params.push(id);
   d.run(`UPDATE memories SET ${sets.join(", ")} WHERE id = ?`, params);
   const updated = getMemory(id, d);
-  try {
-    if (input.value !== undefined) {
+  if (input.value !== undefined) {
+    try {
       const oldLinks = getEntityMemoryLinks(undefined, updated.id, d);
       for (const link of oldLinks) {
         unlinkEntityFromMemory(link.entity_id, updated.id, d);
       }
-      runEntityExtraction(updated, existing.project_id || undefined, d);
-    }
-  } catch {}
+    } catch {}
+  }
+  hookRegistry.runHooks("PostMemoryUpdate", {
+    memory: updated,
+    previousValue: existing.value,
+    agentId: existing.agent_id ?? undefined,
+    projectId: existing.project_id ?? undefined,
+    sessionId: existing.session_id ?? undefined,
+    timestamp: Date.now()
+  });
   return updated;
 }
 function deleteMemory(id, db) {
   const d = db || getDatabase();
   const result = d.run("DELETE FROM memories WHERE id = ?", [id]);
+  if (result.changes > 0) {
+    hookRegistry.runHooks("PostMemoryDelete", {
+      memoryId: id,
+      timestamp: Date.now()
+    });
+  }
   return result.changes > 0;
 }
 function bulkDeleteMemories(ids, db) {
@@ -1182,8 +1301,25 @@ class MemoryLockConflictError extends Error {
 // src/lib/focus.ts
 var sessionFocus = new Map;
 function setFocus(agentId, projectId) {
+  const previous = getFocusCached(agentId);
   sessionFocus.set(agentId, projectId);
   updateAgent(agentId, { active_project_id: projectId });
+  if (projectId && projectId !== previous) {
+    hookRegistry.runHooks("OnSessionStart", {
+      agentId,
+      projectId,
+      timestamp: Date.now()
+    });
+  } else if (!projectId && previous) {
+    hookRegistry.runHooks("OnSessionEnd", {
+      agentId,
+      projectId: previous,
+      timestamp: Date.now()
+    });
+  }
+}
+function getFocusCached(agentId) {
+  return sessionFocus.get(agentId) ?? null;
 }
 function getFocus(agentId) {
   if (sessionFocus.has(agentId)) {
@@ -1319,6 +1455,13 @@ function createEntity(input, db) {
     timestamp,
     timestamp
   ]);
+  hookRegistry.runHooks("PostEntityCreate", {
+    entityId: id,
+    name: input.name,
+    entityType: input.type,
+    projectId: input.project_id,
+    timestamp: Date.now()
+  });
   return getEntity(id, d);
 }
 function getEntity(id, db) {
@@ -2491,7 +2634,15 @@ function createRelation(input, db) {
      DO UPDATE SET weight = excluded.weight, metadata = excluded.metadata`, [id, input.source_entity_id, input.target_entity_id, input.relation_type, weight, metadata, timestamp]);
   const row = d.query(`SELECT * FROM relations
        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);
+  const relation = parseRelationRow(row);
+  hookRegistry.runHooks("PostRelationCreate", {
+    relationId: relation.id,
+    sourceEntityId: relation.source_entity_id,
+    targetEntityId: relation.target_entity_id,
+    relationType: relation.relation_type,
+    timestamp: Date.now()
+  });
+  return relation;
 }
 function getRelation(id, db) {
   const d = db || getDatabase();

package/dist/lib/built-in-hooks.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in hooks — registered at server/MCP startup.
+ * These are system-level hooks that power the auto-memory pipeline.
+ *
+ * Built-in hooks cannot be unregistered (builtin: true).
+ * They are always non-blocking so they never delay the calling operation.
+ */
+import type { HookType } from "../types/hooks.js";
+export declare function loadWebhooksFromDb(): void;
+export declare function reloadWebhooks(): void;
+export type { HookType };
+//# sourceMappingURL=built-in-hooks.d.ts.map

package/dist/lib/built-in-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-hooks.d.ts","sourceRoot":"","sources":["../../src/lib/built-in-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AA2ElD,wBAAgB,kBAAkB,IAAI,IAAI,CAyBzC;AAuBD,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAGD,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/lib/focus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../src/lib/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIxE;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAClC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAC3C,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAClC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC5C,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACvC,gBAAgB,GAAG,IAAI,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAKnC"}
+{"version":3,"file":"focus.d.ts","sourceRoot":"","sources":["../../src/lib/focus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAqBxE;AAOD;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAWvD;AAED;;GAEG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAClC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAC3C,MAAM,GAAG,IAAI,CAUf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAClC,iBAAiB,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAC5C,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GACvC,gBAAgB,GAAG,IAAI,CAazB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GAChB;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAKnC"}

package/dist/lib/hooks.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Hook registry — the central nervous system connecting all memory operations.
+ *
+ * Blocking hooks: await handler, return false = cancel the operation.
+ * Non-blocking hooks: fire-and-forget in background, never delay caller.
+ *
+ * Hooks run in priority order (ascending — lower number first).
+ * Per-agent and per-project scoping supported.
+ */
+import type { Hook, HookType, HookHandler, HookRegistration, HookContextMap } from "../types/hooks.js";
+declare class HookRegistry {
+    private hooks;
+    /**
+     * Register a hook. Returns the assigned hookId.
+     * Built-in hooks (builtin: true) cannot be unregistered.
+     */
+    register<T extends HookType>(reg: HookRegistration<T>): string;
+    /**
+     * Unregister a hook by ID.
+     * Returns false if hook not found or is a built-in.
+     */
+    unregister(hookId: string): boolean;
+    /** List all hooks, optionally filtered by type */
+    list(type?: HookType): Hook[];
+    /**
+     * Run all hooks of a given type for a given context.
+     *
+     * Returns true if the operation should proceed.
+     * Returns false if any blocking hook cancelled it.
+     *
+     * Non-blocking hooks are fired async and never delay the return.
+     */
+    runHooks<T extends HookType>(type: T, context: HookContextMap[T]): Promise<boolean>;
+    /**
+     * Get hooks matching type + agent/project scope.
+     * A hook with no agentId/projectId matches everything.
+     */
+    private getMatchingHooks;
+    /** Get stats about registered hooks */
+    stats(): {
+        total: number;
+        byType: Record<string, number>;
+        blocking: number;
+        nonBlocking: number;
+    };
+}
+/** Singleton — shared across the whole process */
+export declare const hookRegistry: HookRegistry;
+export type { Hook, HookType, HookHandler, HookRegistration };
+//# sourceMappingURL=hooks.d.ts.map

package/dist/lib/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/lib/hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EACV,IAAI,EACJ,QAAQ,EACR,WAAW,EACX,gBAAgB,EAChB,cAAc,EACf,MAAM,mBAAmB,CAAC;AAO3B,cAAM,YAAY;IAChB,OAAO,CAAC,KAAK,CAA2B;IAExC;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAAE,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM;IAW9D;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAQnC,kDAAkD;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,GAAG,IAAI,EAAE;IAM7B;;;;;;;OAOG;IACG,QAAQ,CAAC,CAAC,SAAS,QAAQ,EAC/B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,OAAO,CAAC;IA8BnB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;IAaxB,uCAAuC;IACvC,KAAK,IAAI;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE;CAalG;AAED,kDAAkD;AAClD,eAAO,MAAM,YAAY,cAAqB,CAAC;AAG/C,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,CAAC"}