@hasna/mementos 0.6.0 → 0.8.0

package/dist/types/hooks.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Hook system types for open-mementos lifecycle events.
+ *
+ * Blocking hooks: handler returns false → operation is cancelled.
+ * Non-blocking hooks: fire-and-forget, never delay the caller.
+ */
+import type { Memory, CreateMemoryInput, UpdateMemoryInput } from "./index.js";
+export type HookType = "PreMemorySave" | "PostMemorySave" | "PreMemoryUpdate" | "PostMemoryUpdate" | "PreMemoryDelete" | "PostMemoryDelete" | "PreEntityCreate" | "PostEntityCreate" | "PreRelationCreate" | "PostRelationCreate" | "OnSessionStart" | "OnSessionEnd" | "PreMemoryInject" | "PostMemoryInject";
+export interface BaseHookContext {
+    agentId?: string;
+    projectId?: string;
+    sessionId?: string;
+    timestamp: number;
+}
+export interface PreMemorySaveContext extends BaseHookContext {
+    input: CreateMemoryInput;
+}
+export interface PostMemorySaveContext extends BaseHookContext {
+    memory: Memory;
+    wasUpdated: boolean;
+}
+export interface PreMemoryUpdateContext extends BaseHookContext {
+    memoryId: string;
+    input: UpdateMemoryInput;
+    existing: Memory;
+}
+export interface PostMemoryUpdateContext extends BaseHookContext {
+    memory: Memory;
+    previousValue: string;
+}
+export interface PreMemoryDeleteContext extends BaseHookContext {
+    memoryId: string;
+    memory: Memory;
+}
+export interface PostMemoryDeleteContext extends BaseHookContext {
+    memoryId: string;
+}
+export interface PreEntityCreateContext extends BaseHookContext {
+    name: string;
+    entityType: string;
+}
+export interface PostEntityCreateContext extends BaseHookContext {
+    entityId: string;
+    name: string;
+    entityType: string;
+}
+export interface PreRelationCreateContext extends BaseHookContext {
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationType: string;
+}
+export interface PostRelationCreateContext extends BaseHookContext {
+    relationId: string;
+    sourceEntityId: string;
+    targetEntityId: string;
+    relationType: string;
+}
+export interface OnSessionStartContext extends BaseHookContext {
+    agentId: string;
+    projectId?: string;
+}
+export interface OnSessionEndContext extends BaseHookContext {
+    agentId: string;
+    projectId?: string;
+    /** Optional session summary for memory extraction */
+    summary?: string;
+}
+export interface PreMemoryInjectContext extends BaseHookContext {
+    /** Memories about to be injected — hook can mutate this array */
+    memories: Memory[];
+    format: string;
+}
+export interface PostMemoryInjectContext extends BaseHookContext {
+    memoriesCount: number;
+    format: string;
+    contextLength: number;
+}
+/** Union of all hook contexts keyed by type */
+export type HookContextMap = {
+    PreMemorySave: PreMemorySaveContext;
+    PostMemorySave: PostMemorySaveContext;
+    PreMemoryUpdate: PreMemoryUpdateContext;
+    PostMemoryUpdate: PostMemoryUpdateContext;
+    PreMemoryDelete: PreMemoryDeleteContext;
+    PostMemoryDelete: PostMemoryDeleteContext;
+    PreEntityCreate: PreEntityCreateContext;
+    PostEntityCreate: PostEntityCreateContext;
+    PreRelationCreate: PreRelationCreateContext;
+    PostRelationCreate: PostRelationCreateContext;
+    OnSessionStart: OnSessionStartContext;
+    OnSessionEnd: OnSessionEndContext;
+    PreMemoryInject: PreMemoryInjectContext;
+    PostMemoryInject: PostMemoryInjectContext;
+};
+/**
+ * Blocking hook: return false to cancel the operation.
+ * Non-blocking hook: return value is ignored.
+ */
+export type HookHandler<T extends HookType = HookType> = (context: HookContextMap[T]) => Promise<boolean | void>;
+export interface Hook<T extends HookType = HookType> {
+    id: string;
+    type: T;
+    handler: HookHandler<T>;
+    /** Lower number = runs first. Default: 50 */
+    priority: number;
+    /**
+     * If true: operation waits for handler result. Return false = cancel.
+     * If false: runs async in background, return value ignored.
+     */
+    blocking: boolean;
+    /** Scope: only fire for this agent (undefined = all agents) */
+    agentId?: string;
+    /** Scope: only fire for this project (undefined = all projects) */
+    projectId?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Whether this is a built-in system hook (can't be unregistered) */
+    builtin?: boolean;
+}
+export type HookRegistration<T extends HookType = HookType> = Omit<Hook<T>, "id">;
+export interface WebhookHook {
+    id: string;
+    type: HookType;
+    /** HTTP endpoint to POST the context to */
+    handlerUrl: string;
+    priority: number;
+    blocking: boolean;
+    agentId?: string;
+    projectId?: string;
+    description?: string;
+    enabled: boolean;
+    createdAt: string;
+    invocationCount: number;
+    failureCount: number;
+}
+//# sourceMappingURL=hooks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../../src/types/hooks.ts"],"names":[],"mappings":"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"}

package/package.json

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