@utaba/deep-memory 0.8.1 → 0.9.1

package/dist/index.d.cts

@@ -1,6 +1,7 @@
 import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, y as ValidationResult, U as UpdateEntityInput, z as CreateRelationshipInput, A as EntityTypeDefinition, F as VocabularyProposal, H as VocabularyProposalResult, J as ProvenanceContext, K as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, L as FindEntitiesQuery, e as PaginatedResult, N as DeleteEntitiesResult, O as ReembedResult, Q as Relationship, T as RemoveRelationshipsResult, P as PropertyFilter, R as RelationshipSummary, W as GraphResult, X as ExploreOptions, Y as Neighborhood, Z as PathOptions, _ as PathResult, $ as ConceptSearchOptions, a0 as ScoredEntity, a1 as TimelineOptions, a2 as TimelineResult, i as RepositoryStats, a3 as ValidateEntitiesOptions, a4 as EntityValidationPage, a5 as ValidateRelationshipsOptions, a6 as RelationshipValidationPage, a7 as RepositoryConfig, c as StoredRepository, d as RepositoryFilter, a8 as RepositorySummary, g as RepositoryUpdate, a9 as ExportOptions, aa as ExportArchive, ab as ImportOptions, ac as ImportResult, ad as ExportStreamItem, ae as ImportStreamHeader, I as ImportChunk, k as StoredEntity, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, af as SearchOptions, ag as SearchHit } from './portability-dhIuWJbJ.cjs';
 export { ah as EnrichedRelationship, ai as EntityMap, aj as EntityTypeInput, ak as EntityValidationIssue, al as ExportLegalMetadata, am as ExportManifest, an as ExportPipelineMetadata, ao as GetEntitiesOptions, ap as GetEntityOptions, aq as GovernanceMode, ar as ImportWarning, as as NeighborhoodCenter, at as NeighborhoodGroup, au as NeighborhoodLayer, av as Path, aw as PropertySchema, ax as PropertyType, ay as ProvenanceFilter, az as RelationshipDirection, aA as RelationshipTypeDefinition, aB as RelationshipTypeInput, aC as RelationshipValidationIssue, aD as RepositoryMetadata, aE as StorageNeighborhoodGroup, aF as StorageNeighborhoodLayer, aG as StoragePath, aH as StorageTimelineEvent, aI as TimelineEntityRef, aJ as TimelineEvent, aK as TimelineRelationshipDetail, aL as VocabularyInput } from './portability-dhIuWJbJ.cjs';
-import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload } from './types/index.cjs';
+import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload, UsageSink } from './types/index.cjs';
+export { OperationUsage } from './types/index.cjs';
 import { T as TraversalSpec, a as TraversalResult } from './traversal-Bmv4we_g.cjs';
 export { Q as QueryMetadata, b as TraversalAggregation, c as TraversalPath, d as TraversalProjection, e as TraversalRelationship, f as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-Bmv4we_g.cjs';
 import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-DmKddrEg.cjs';
@@ -446,6 +447,17 @@ declare function matchesPropertyFilters(properties: Record<string, unknown>, fil
 /** Project a stored entity to the requested detail level */
 declare function projectEntity(stored: StoredEntity, level: DetailLevel): Entity | EntitySummary | EntityBrief;
 
+/**
+ * Wrap a sink with try/catch so a throwing caller sink never aborts the
+ * underlying operation. Errors from the caller's sink are silently swallowed;
+ * if the caller cares about internal failures they can catch in their own
+ * implementation.
+ *
+ * Returns `undefined` if the input sink is `undefined`, letting providers
+ * cheaply skip sink machinery when nobody is listening.
+ */
+declare function createSafeSink(sink: UsageSink | undefined): UsageSink | undefined;
+
 interface TraversalCompiler {
     /** The query language this compiler targets. */
     readonly language: 'gremlin' | 'cypher' | 'sql';
@@ -538,4 +550,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters, projectEntity };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, y as ValidationResult, U as UpdateEntityInput, z as CreateRelationshipInput, A as EntityTypeDefinition, F as VocabularyProposal, H as VocabularyProposalResult, J as ProvenanceContext, K as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, L as FindEntitiesQuery, e as PaginatedResult, N as DeleteEntitiesResult, O as ReembedResult, Q as Relationship, T as RemoveRelationshipsResult, P as PropertyFilter, R as RelationshipSummary, W as GraphResult, X as ExploreOptions, Y as Neighborhood, Z as PathOptions, _ as PathResult, $ as ConceptSearchOptions, a0 as ScoredEntity, a1 as TimelineOptions, a2 as TimelineResult, i as RepositoryStats, a3 as ValidateEntitiesOptions, a4 as EntityValidationPage, a5 as ValidateRelationshipsOptions, a6 as RelationshipValidationPage, a7 as RepositoryConfig, c as StoredRepository, d as RepositoryFilter, a8 as RepositorySummary, g as RepositoryUpdate, a9 as ExportOptions, aa as ExportArchive, ab as ImportOptions, ac as ImportResult, ad as ExportStreamItem, ae as ImportStreamHeader, I as ImportChunk, k as StoredEntity, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighborhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, af as SearchOptions, ag as SearchHit } from './portability-dhIuWJbJ.js';
 export { ah as EnrichedRelationship, ai as EntityMap, aj as EntityTypeInput, ak as EntityValidationIssue, al as ExportLegalMetadata, am as ExportManifest, an as ExportPipelineMetadata, ao as GetEntitiesOptions, ap as GetEntityOptions, aq as GovernanceMode, ar as ImportWarning, as as NeighborhoodCenter, at as NeighborhoodGroup, au as NeighborhoodLayer, av as Path, aw as PropertySchema, ax as PropertyType, ay as ProvenanceFilter, az as RelationshipDirection, aA as RelationshipTypeDefinition, aB as RelationshipTypeInput, aC as RelationshipValidationIssue, aD as RepositoryMetadata, aE as StorageNeighborhoodGroup, aF as StorageNeighborhoodLayer, aG as StoragePath, aH as StorageTimelineEvent, aI as TimelineEntityRef, aJ as TimelineEvent, aK as TimelineRelationshipDetail, aL as VocabularyInput } from './portability-dhIuWJbJ.js';
-import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload } from './types/index.js';
+import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload, UsageSink } from './types/index.js';
+export { OperationUsage } from './types/index.js';
 import { T as TraversalSpec, a as TraversalResult } from './traversal-D8SGKq0z.js';
 export { Q as QueryMetadata, b as TraversalAggregation, c as TraversalPath, d as TraversalProjection, e as TraversalRelationship, f as TraversalReturnMode, g as TraversalStart, h as TraversalStep } from './traversal-D8SGKq0z.js';
 import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-CRenWERy.js';
@@ -446,6 +447,17 @@ declare function matchesPropertyFilters(properties: Record<string, unknown>, fil
 /** Project a stored entity to the requested detail level */
 declare function projectEntity(stored: StoredEntity, level: DetailLevel): Entity | EntitySummary | EntityBrief;
 
+/**
+ * Wrap a sink with try/catch so a throwing caller sink never aborts the
+ * underlying operation. Errors from the caller's sink are silently swallowed;
+ * if the caller cares about internal failures they can catch in their own
+ * implementation.
+ *
+ * Returns `undefined` if the input sink is `undefined`, letting providers
+ * cheaply skip sink machinery when nobody is listening.
+ */
+declare function createSafeSink(sink: UsageSink | undefined): UsageSink | undefined;
+
 interface TraversalCompiler {
     /** The query language this compiler targets. */
     readonly language: 'gremlin' | 'cypher' | 'sql';
@@ -538,4 +550,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters, projectEntity };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteEntitiesResult, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderFactory, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EntityValidationPage, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportOptions, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, GraphTraversalProvider, GraphTraversalProviderRequiredError, GremlinCompiler, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighborhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RelationshipValidationPage, RemoveRelationshipsResult, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, RepositoryValidator, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, SelfReferentialRelationshipError, StorageExploreOptions, StorageFindQuery, StorageNeighborhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, UsageSink, ValidateEntitiesOptions, ValidateRelationshipsOptions, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, createSafeSink, generateId, isValidUuid, matchesPropertyFilters, projectEntity };

package/dist/index.js

@@ -2553,7 +2553,7 @@ var MemoryRepository = class {
 ### Step 1 \u2014 Discover before you traverse
 
 Before following relationships from an entity, check that it actually has relationships.
-\`memory_query_graph\` includes \`relationshipSummary\` on every returned entity by default
+Graph queries include \`relationshipSummary\` on every returned entity by default
 (outbound and inbound counts by type). Inspect this before traversing \u2014 entities with
 zero outbound counts for the relationship type you need have no connections to follow.
 To skip summaries and reduce response size, set \`includeRelationshipSummary: false\`.
@@ -2561,7 +2561,7 @@ To skip summaries and reduce response size, set \`includeRelationshipSummary: fa
 ### Step 2 \u2014 Use projection for aggregation
 
 To understand what data exists (e.g. all distinct values of a property, or counts by
-category), use \`memory_query_graph\` with \`projection\` instead of fetching full entities:
+category), use a graph query with \`projection\` instead of fetching full entities:
 \`{ start: { entityType: "..." }, projection: { properties: ["propName"], distinct: true }, limit: 200 }\`
 
 This returns only the aggregated values \u2014 no entity objects \u2014 keeping responses lightweight.
@@ -2570,23 +2570,23 @@ This returns only the aggregated values \u2014 no entity objects \u2014 keeping
 
 - **Omit relationshipTypes** in a traversal step to follow all relationship types at once,
   rather than making separate calls per type.
-- **Use multi-step traversals** for multi-hop patterns. A two-step query
+- **Use multi-step traversals** for multi-hop patterns. A two-step traverse operation
   (e.g. Equipment \u2192 Component \u2192 MaintenanceProcedure) is one call, not two sequential calls.
 - **Use returnMode "all"** when you need intermediate entities along the path, not just
   the terminal nodes.
 
 ### Step 4 \u2014 Use semantic search for known-unknowns
 
-\`memory_search_by_concept\` is best for finding specific entities when you know roughly
+Semantic/concept search is best for finding specific entities when you know roughly
 what you're looking for but not the exact label or type. It is not efficient for broad
-discovery \u2014 use projection or find_entities for that.
+discovery \u2014 use projection or entity finding for that.
 
 ### Common anti-patterns to avoid
 
 - **Don't traverse from entities with zero relationship counts.** The \`relationshipSummary\` on each entity tells you what is connected before you traverse.
-- **Don't split queries by relationship type.** One step with no type filter is better
+- **Don't split queries by relationship type.** One traverse step with no type filter is better
   than three separate single-type calls.
-- **Don't use sequential single-hop traversals** when a multi-step query achieves the
+- **Don't use sequential single-hop traversals** when a multi-step traverse operation achieves the
   same result in one call.
 - **Don't fetch full entities when you only need property values.** Use projection.`;
   }
@@ -3431,7 +3431,7 @@ var EventBus = class {
 };
 
 // src/portability/RepositoryExporter.ts
-var LIBRARY_VERSION = true ? "0.8.1" : "0.1.0";
+var LIBRARY_VERSION = true ? "0.9.1" : "0.1.0";
 var RepositoryExporter = class {
   storage;
   provenance;
@@ -4486,6 +4486,17 @@ var DeepMemory = class {
   }
 };
 
+// src/usage/safeSink.ts
+function createSafeSink(sink) {
+  if (!sink) return void 0;
+  return (usage) => {
+    try {
+      sink(usage);
+    } catch {
+    }
+  };
+}
+
 // src/relationships/compilers/GremlinCompiler.ts
 var DEFAULT_ESTIMATED_FANOUT_PER_HOP = 10;
 var GremlinCompiler = class {
@@ -5560,6 +5571,7 @@ export {
   TraversalValidationError,
   TraversalVocabularyError,
   VocabularyValidationError,
+  createSafeSink,
   generateId,
   isValidUuid,
   matchesPropertyFilters,