@utaba/deep-memory 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -1,12 +1,14 @@
-import { G as GovernanceConfig, M as MemoryVocabulary, q as ResolvedVocabulary, C as CreateEntityInput, U as UpdateEntityInput, r as CreateRelationshipInput, s as EntityTypeDefinition, t as VocabularyProposal, u as VocabularyProposalResult, v as ProvenanceContext, w as Provenance, x as Entity, D as DetailLevel, y as EntitySummary, z as EntityBrief, F as FindEntitiesQuery, P as PaginatedResult, A as ReembedResult, H as Relationship, J as PropertyFilter, K as RelationshipSummary, L as GraphResult, N as ExploreOptions, O as Neighbourhood, Q as PathOptions, T as PathResult, W as ConceptSearchOptions, X as ScoredEntity, Y as TimelineOptions, Z as TimelineResult, d as RepositoryStats, _ as RepositoryConfig, R as RepositoryFilter, $ as RepositorySummary, c as RepositoryUpdate, a as StoredRepository, a0 as ExportArchive, a1 as ImportOptions, a2 as ImportResult, a3 as ExportStreamItem, a4 as ImportStreamHeader, I as ImportChunk, S as StorageRepositoryConfig, b as StoredRepositorySummary, e as PaginationOptions, V as VocabularyChangeRecord, f as StoredEntity, g as StoredEntityUpdate, h as StorageFindQuery, i as StoredRelationship, j as RelationshipQueryOptions, k as StorageExploreOptions, l as StorageNeighbourhood, m as StoragePathOptions, n as StoragePathResult, o as StorageTimelineOptions, p as StorageTimelineResult, E as ExportChunk, B as BulkImportResult, a5 as SearchOptions, a6 as SearchHit } from './portability-DdlNYXGX.cjs';
-export { a7 as EnrichedRelationship, a8 as EntityMap, a9 as EntityTypeInput, aa as ExportManifest, ab as GetEntitiesOptions, ac as GetEntityOptions, ad as GovernanceMode, ae as ImportWarning, af as NeighbourhoodCentre, ag as NeighbourhoodGroup, ah as NeighbourhoodLayer, ai as Path, aj as PropertySchema, ak as PropertyType, al as ProvenanceFilter, am as RelationshipDirection, an as RelationshipTypeDefinition, ao as RelationshipTypeInput, ap as RepositoryMetadata, aq as StorageNeighbourhoodGroup, ar as StorageNeighbourhoodLayer, as as StoragePath, at as StorageTimelineEvent, au as TimelineEntityRef, av as TimelineEvent, aw as TimelineRelationshipDetail, ax as VocabularyInput } from './portability-DdlNYXGX.cjs';
+import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, U as UpdateEntityInput, y as CreateRelationshipInput, z as EntityTypeDefinition, A as VocabularyProposal, F as VocabularyProposalResult, H as ProvenanceContext, J as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, K as FindEntitiesQuery, e as PaginatedResult, L as ReembedResult, N as Relationship, P as PropertyFilter, R as RelationshipSummary, O as GraphResult, Q as ExploreOptions, T as Neighbourhood, W as PathOptions, X as PathResult, Y as ConceptSearchOptions, Z as ScoredEntity, _ as TimelineOptions, $ as TimelineResult, i as RepositoryStats, a0 as RepositoryConfig, d as RepositoryFilter, a1 as RepositorySummary, g as RepositoryUpdate, c as StoredRepository, a2 as ExportOptions, a3 as ExportArchive, a4 as ImportOptions, a5 as ImportResult, a6 as ExportStreamItem, a7 as ImportStreamHeader, I as ImportChunk, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, k as StoredEntity, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighbourhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, a8 as SearchOptions, a9 as SearchHit } from './portability-1KBMVBGJ.cjs';
+export { aa as EnrichedRelationship, ab as EntityMap, ac as EntityTypeInput, ad as ExportLegalMetadata, ae as ExportManifest, af as ExportPipelineMetadata, ag as GetEntitiesOptions, ah as GetEntityOptions, ai as GovernanceMode, aj as ImportWarning, ak as NeighbourhoodCentre, al as NeighbourhoodGroup, am as NeighbourhoodLayer, an as Path, ao as PropertySchema, ap as PropertyType, aq as ProvenanceFilter, ar as RelationshipDirection, as as RelationshipTypeDefinition, at as RelationshipTypeInput, au as RepositoryMetadata, av as StorageNeighbourhoodGroup, aw as StorageNeighbourhoodLayer, ax as StoragePath, ay as StorageTimelineEvent, az as TimelineEntityRef, aA as TimelineEvent, aB as TimelineRelationshipDetail, aC as VocabularyInput } from './portability-1KBMVBGJ.cjs';
 import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload } from './types/index.cjs';
-import { S as StorageProvider } from './StorageProvider-CkFjdboX.cjs';
-import { EmbeddingProvider, SearchProvider, LockProvider, SearchableEntity } from './providers/index.cjs';
-export { LockHandle, LockOptions } from './providers/index.cjs';
+import { T as TraversalSpec, a as TraversalResult } from './traversal-DQynd-to.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-DQynd-to.cjs';
+import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-CSbaIY6X.cjs';
+import { EmbeddingProvider, SearchProvider, GraphTraversalProvider, LockProvider, SearchableEntity } from './providers/index.cjs';
+export { GraphTraversalCapabilities, LockHandle, LockOptions } from './providers/index.cjs';
 
 /** Error codes for all Deep Memory errors */
-type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR';
+type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT';
 /** Base error class for all Deep Memory errors */
 declare class DeepMemoryError extends Error {
     readonly code: DeepMemoryErrorCode;
@@ -96,6 +98,25 @@ declare class ExportError extends DeepMemoryError {
 declare class ProviderError extends DeepMemoryError {
     constructor(message: string, suggestion?: string);
 }
+/** Thrown when executeNativeQuery() is called but no GraphTraversalProvider is registered. */
+declare class GraphTraversalProviderRequiredError extends DeepMemoryError {
+    constructor();
+}
+/** Thrown when a TraversalSpec is structurally invalid. */
+declare class TraversalValidationError extends DeepMemoryError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** Thrown when a TraversalSpec references relationship/entity types not in the vocabulary. */
+declare class TraversalVocabularyError extends DeepMemoryError {
+    readonly unknownTypes: string[];
+    constructor(unknownTypes: string[]);
+}
+/** Thrown when a native query times out. */
+declare class TraversalTimeoutError extends DeepMemoryError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
 
 /** A single validation error with optional suggestion */
 interface ValidationError {
@@ -210,6 +231,7 @@ interface MemoryRepositoryConfig {
     storage: StorageProvider;
     search?: SearchProvider;
     embedding?: EmbeddingProvider;
+    graphTraversal?: GraphTraversalProvider;
     vocabularyEngine: VocabularyEngine;
     provenanceTracker: ProvenanceTracker;
     eventBus: EventBus;
@@ -230,7 +252,7 @@ declare class MemoryRepository {
     proposeVocabularyChange(proposal: VocabularyProposal): Promise<VocabularyProposalResult>;
     /** @deprecated Use proposeVocabularyChange instead */
     proposeVocabularyExtension(proposal: VocabularyProposal): Promise<VocabularyProposalResult>;
-    createEntity(input: CreateEntityInput): Promise<Entity>;
+    createEntities(inputs: CreateEntityInput[]): Promise<Entity[]>;
     updateEntity(entityId: string, updates: UpdateEntityInput): Promise<Entity>;
     getEntity(entityId: string, detailLevel?: DetailLevel): Promise<Entity | EntitySummary | EntityBrief | null>;
     getBySlug(slug: string, detailLevel?: DetailLevel): Promise<Entity | EntitySummary | EntityBrief | null>;
@@ -253,7 +275,7 @@ declare class MemoryRepository {
         /** Milliseconds to wait between batches for rate limiting (default 0) */
         delayBetweenBatchesMs?: number;
     }): Promise<ReembedResult>;
-    createRelationship(input: CreateRelationshipInput): Promise<Relationship>;
+    createRelationships(inputs: CreateRelationshipInput[]): Promise<Relationship[]>;
     removeRelationship(relationshipId: string): Promise<void>;
     getRelationships(entityId: string, options?: {
         relationshipTypes?: string[];
@@ -272,9 +294,21 @@ declare class MemoryRepository {
     }): Promise<GraphResult>;
     exploreNeighbourhood(entityId: string, options?: ExploreOptions): Promise<Neighbourhood>;
     findPaths(sourceId: string, targetId: string, options?: PathOptions): Promise<PathResult>;
+    traverse(spec: TraversalSpec): Promise<TraversalResult>;
+    executeNativeQuery(query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
     searchByConcept(query: string, options?: ConceptSearchOptions): Promise<PaginatedResult<ScoredEntity>>;
     getTimeline(entityId: string, options?: TimelineOptions): Promise<TimelineResult>;
     getStats(): Promise<RepositoryStats>;
+    /** Delete all entities and relationships in this repository, preserving the repository and vocabulary */
+    deleteAllContents(): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
+    /**
+     * Returns a static markdown guide describing the recommended query strategy
+     * for AI agents and other consumers of the repository.
+     */
+    getQueryGuide(): string;
     on<E extends DeepMemoryEventType>(event: E, handler: EventHandler<E>): Unsubscribe;
     onHook<E extends Extract<DeepMemoryEventType, 'entity:creating' | 'entity:updating' | 'entity:deleting' | 'relationship:creating' | 'relationship:removing'>>(event: E, handler: HookHandler<E>): Unsubscribe;
 }
@@ -293,6 +327,8 @@ interface DeepMemoryConfig {
     embedding?: EmbeddingProvider;
     /** Optional: lock provider for distributed locking */
     lock?: LockProvider;
+    /** Optional: graph traversal provider for native multi-hop queries */
+    graphTraversal?: GraphTraversalProvider;
     /** Required: provenance context identifying the actor */
     provenance: ProvenanceContext;
 }
@@ -302,14 +338,15 @@ declare class DeepMemory {
     private readonly embedding?;
     /** Reserved for future distributed locking support */
     readonly lock?: LockProvider;
+    private readonly graphTraversalProvider?;
     private readonly provenance;
     private readonly globalEventBus;
     private initialised;
     constructor(config: DeepMemoryConfig);
-    /** Initialise the storage provider (call once before use) */
+    /** Initialise the storage provider and optional providers (call once before use) */
     private ensureInitialised;
     /** Create or migrate the storage schema. Call once at deployment / startup, not per-request. */
-    ensureSchema(): Promise<void>;
+    ensureSchema(): Promise<EnsureSchemaResult>;
     private validateRepositoryId;
     /** Create a new memory repository */
     createRepository(config: RepositoryConfig): Promise<MemoryRepository>;
@@ -321,8 +358,13 @@ declare class DeepMemory {
     updateRepository(repositoryId: string, updates: RepositoryUpdate): Promise<StoredRepository>;
     /** Delete a repository */
     deleteRepository(repositoryId: string): Promise<void>;
+    /** Delete all entities and relationships in a repository, preserving the repository and vocabulary */
+    deleteAllContents(repositoryId: string): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
     /** Export a repository to a portable archive */
-    exportRepository(repositoryId: string): Promise<ExportArchive>;
+    exportRepository(repositoryId: string, options?: ExportOptions): Promise<ExportArchive>;
     /** Import a repository from a portable archive */
     importRepository(archive: ExportArchive, options: ImportOptions): Promise<ImportResult>;
     /**
@@ -330,7 +372,7 @@ declare class DeepMemory {
      * Yields: manifest → vocabulary → entity chunks → relationship chunks.
      * Use for large repositories to avoid loading everything into memory.
      */
-    exportRepositoryStream(repositoryId: string): AsyncGenerator<ExportStreamItem>;
+    exportRepositoryStream(repositoryId: string, options?: ExportOptions): AsyncGenerator<ExportStreamItem>;
     /**
      * Import a repository from a stream of chunks.
      * Use for large repositories to avoid loading everything into memory.
@@ -350,6 +392,31 @@ declare class DeepMemory {
  */
 declare function matchesPropertyFilters(properties: Record<string, unknown>, filters: PropertyFilter[]): boolean;
 
+interface TraversalCompiler {
+    /** The query language this compiler targets. */
+    readonly language: 'gremlin' | 'cypher' | 'sql';
+    /** Compile a validated TraversalSpec into a native query string. */
+    compile(spec: TraversalSpec, vocabulary: MemoryVocabulary): CompiledQuery;
+}
+interface CompiledQuery {
+    /** The native query string. */
+    query: string;
+    /** Parameter bindings (for parameterized queries). */
+    params: Record<string, unknown>;
+    /** Estimated cost heuristic (fan-out estimation). Provider may override. */
+    estimatedFanOut: number;
+}
+
+declare class GremlinCompiler implements TraversalCompiler {
+    readonly language: "gremlin";
+    compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
+}
+
+declare class CypherCompiler implements TraversalCompiler {
+    readonly language: "cypher";
+    compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
+}
+
 declare class InMemoryStorageProvider implements StorageProvider {
     private stores;
     private getStore;
@@ -359,7 +426,11 @@ declare class InMemoryStorageProvider implements StorageProvider {
     getRepository(repositoryId: string): Promise<StoredRepository | null>;
     listRepositories(filter?: RepositoryFilter): Promise<PaginatedResult<StoredRepositorySummary>>;
     updateRepository(repositoryId: string, updates: RepositoryUpdate): Promise<StoredRepository>;
-    deleteRepository(repositoryId: string): Promise<void>;
+    deleteRepository(repositoryId: string, _onProgress?: DeleteProgressCallback): Promise<void>;
+    deleteAllContents(repositoryId: string, _onProgress?: DeleteProgressCallback): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
     getRepositoryStats(repositoryId: string): Promise<RepositoryStats>;
     getVocabulary(repositoryId: string): Promise<MemoryVocabulary>;
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
@@ -386,7 +457,7 @@ declare class InMemoryStorageProvider implements StorageProvider {
     findPaths(repositoryId: string, sourceId: string, targetId: string, options: StoragePathOptions): Promise<StoragePathResult>;
     getTimeline(repositoryId: string, entityId: string, options: StorageTimelineOptions): Promise<StorageTimelineResult>;
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
-    importBulk(repositoryId: string, data: ImportChunk[]): Promise<BulkImportResult>;
+    importBulk(repositoryId: string, data: ImportChunk[], _options?: BulkImportOptions): Promise<BulkImportResult>;
 }
 
 declare class InMemorySearchProvider implements SearchProvider {
@@ -405,4 +476,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportResult, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderRequiredError, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighbourhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, StorageExploreOptions, StorageFindQuery, StorageNeighbourhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, Unsubscribe, UpdateEntityInput, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, 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, Neighbourhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, StorageExploreOptions, StorageFindQuery, StorageNeighbourhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters };

package/dist/index.d.ts

@@ -1,12 +1,14 @@
-import { G as GovernanceConfig, M as MemoryVocabulary, q as ResolvedVocabulary, C as CreateEntityInput, U as UpdateEntityInput, r as CreateRelationshipInput, s as EntityTypeDefinition, t as VocabularyProposal, u as VocabularyProposalResult, v as ProvenanceContext, w as Provenance, x as Entity, D as DetailLevel, y as EntitySummary, z as EntityBrief, F as FindEntitiesQuery, P as PaginatedResult, A as ReembedResult, H as Relationship, J as PropertyFilter, K as RelationshipSummary, L as GraphResult, N as ExploreOptions, O as Neighbourhood, Q as PathOptions, T as PathResult, W as ConceptSearchOptions, X as ScoredEntity, Y as TimelineOptions, Z as TimelineResult, d as RepositoryStats, _ as RepositoryConfig, R as RepositoryFilter, $ as RepositorySummary, c as RepositoryUpdate, a as StoredRepository, a0 as ExportArchive, a1 as ImportOptions, a2 as ImportResult, a3 as ExportStreamItem, a4 as ImportStreamHeader, I as ImportChunk, S as StorageRepositoryConfig, b as StoredRepositorySummary, e as PaginationOptions, V as VocabularyChangeRecord, f as StoredEntity, g as StoredEntityUpdate, h as StorageFindQuery, i as StoredRelationship, j as RelationshipQueryOptions, k as StorageExploreOptions, l as StorageNeighbourhood, m as StoragePathOptions, n as StoragePathResult, o as StorageTimelineOptions, p as StorageTimelineResult, E as ExportChunk, B as BulkImportResult, a5 as SearchOptions, a6 as SearchHit } from './portability-DdlNYXGX.js';
-export { a7 as EnrichedRelationship, a8 as EntityMap, a9 as EntityTypeInput, aa as ExportManifest, ab as GetEntitiesOptions, ac as GetEntityOptions, ad as GovernanceMode, ae as ImportWarning, af as NeighbourhoodCentre, ag as NeighbourhoodGroup, ah as NeighbourhoodLayer, ai as Path, aj as PropertySchema, ak as PropertyType, al as ProvenanceFilter, am as RelationshipDirection, an as RelationshipTypeDefinition, ao as RelationshipTypeInput, ap as RepositoryMetadata, aq as StorageNeighbourhoodGroup, ar as StorageNeighbourhoodLayer, as as StoragePath, at as StorageTimelineEvent, au as TimelineEntityRef, av as TimelineEvent, aw as TimelineRelationshipDetail, ax as VocabularyInput } from './portability-DdlNYXGX.js';
+import { G as GovernanceConfig, M as MemoryVocabulary, x as ResolvedVocabulary, C as CreateEntityInput, U as UpdateEntityInput, y as CreateRelationshipInput, z as EntityTypeDefinition, A as VocabularyProposal, F as VocabularyProposalResult, H as ProvenanceContext, J as Provenance, E as Entity, D as DetailLevel, a as EntitySummary, b as EntityBrief, K as FindEntitiesQuery, e as PaginatedResult, L as ReembedResult, N as Relationship, P as PropertyFilter, R as RelationshipSummary, O as GraphResult, Q as ExploreOptions, T as Neighbourhood, W as PathOptions, X as PathResult, Y as ConceptSearchOptions, Z as ScoredEntity, _ as TimelineOptions, $ as TimelineResult, i as RepositoryStats, a0 as RepositoryConfig, d as RepositoryFilter, a1 as RepositorySummary, g as RepositoryUpdate, c as StoredRepository, a2 as ExportOptions, a3 as ExportArchive, a4 as ImportOptions, a5 as ImportResult, a6 as ExportStreamItem, a7 as ImportStreamHeader, I as ImportChunk, S as StorageRepositoryConfig, f as StoredRepositorySummary, h as DeleteProgressCallback, j as PaginationOptions, V as VocabularyChangeRecord, k as StoredEntity, l as StoredEntityUpdate, m as StorageFindQuery, n as StoredRelationship, o as RelationshipQueryOptions, p as StorageExploreOptions, q as StorageNeighbourhood, r as StoragePathOptions, s as StoragePathResult, t as StorageTimelineOptions, u as StorageTimelineResult, v as ExportChunk, B as BulkImportOptions, w as BulkImportResult, a8 as SearchOptions, a9 as SearchHit } from './portability-1KBMVBGJ.js';
+export { aa as EnrichedRelationship, ab as EntityMap, ac as EntityTypeInput, ad as ExportLegalMetadata, ae as ExportManifest, af as ExportPipelineMetadata, ag as GetEntitiesOptions, ah as GetEntityOptions, ai as GovernanceMode, aj as ImportWarning, ak as NeighbourhoodCentre, al as NeighbourhoodGroup, am as NeighbourhoodLayer, an as Path, ao as PropertySchema, ap as PropertyType, aq as ProvenanceFilter, ar as RelationshipDirection, as as RelationshipTypeDefinition, at as RelationshipTypeInput, au as RepositoryMetadata, av as StorageNeighbourhoodGroup, aw as StorageNeighbourhoodLayer, ax as StoragePath, ay as StorageTimelineEvent, az as TimelineEntityRef, aA as TimelineEvent, aB as TimelineRelationshipDetail, aC as VocabularyInput } from './portability-1KBMVBGJ.js';
 import { DeepMemoryEventType, EventHandler, Unsubscribe, DeepMemoryEvent, HookResult, EventPayload } from './types/index.js';
-import { S as StorageProvider } from './StorageProvider-CJjz8uBY.js';
-import { EmbeddingProvider, SearchProvider, LockProvider, SearchableEntity } from './providers/index.js';
-export { LockHandle, LockOptions } from './providers/index.js';
+import { T as TraversalSpec, a as TraversalResult } from './traversal-B4SUysM-.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-B4SUysM-.js';
+import { S as StorageProvider, E as EnsureSchemaResult } from './StorageProvider-DqW-zpd0.js';
+import { EmbeddingProvider, SearchProvider, GraphTraversalProvider, LockProvider, SearchableEntity } from './providers/index.js';
+export { GraphTraversalCapabilities, LockHandle, LockOptions } from './providers/index.js';
 
 /** Error codes for all Deep Memory errors */
-type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR';
+type DeepMemoryErrorCode = 'INVALID_INPUT' | 'ENTITY_NOT_FOUND' | 'ENTITY_ALREADY_EXISTS' | 'RELATIONSHIP_NOT_FOUND' | 'RELATIONSHIP_ALREADY_EXISTS' | 'REPOSITORY_NOT_FOUND' | 'REPOSITORY_ALREADY_EXISTS' | 'VOCABULARY_VALIDATION_FAILED' | 'RELATIONSHIP_CONSTRAINT_FAILED' | 'GOVERNANCE_DENIED' | 'OPERATION_CANCELLED' | 'EMBEDDING_PROVIDER_REQUIRED' | 'IMPORT_ERROR' | 'EXPORT_ERROR' | 'PROVIDER_ERROR' | 'GRAPH_TRAVERSAL_PROVIDER_REQUIRED' | 'TRAVERSAL_VALIDATION_FAILED' | 'TRAVERSAL_VOCABULARY_ERROR' | 'TRAVERSAL_TIMEOUT';
 /** Base error class for all Deep Memory errors */
 declare class DeepMemoryError extends Error {
     readonly code: DeepMemoryErrorCode;
@@ -96,6 +98,25 @@ declare class ExportError extends DeepMemoryError {
 declare class ProviderError extends DeepMemoryError {
     constructor(message: string, suggestion?: string);
 }
+/** Thrown when executeNativeQuery() is called but no GraphTraversalProvider is registered. */
+declare class GraphTraversalProviderRequiredError extends DeepMemoryError {
+    constructor();
+}
+/** Thrown when a TraversalSpec is structurally invalid. */
+declare class TraversalValidationError extends DeepMemoryError {
+    readonly errors: string[];
+    constructor(errors: string[]);
+}
+/** Thrown when a TraversalSpec references relationship/entity types not in the vocabulary. */
+declare class TraversalVocabularyError extends DeepMemoryError {
+    readonly unknownTypes: string[];
+    constructor(unknownTypes: string[]);
+}
+/** Thrown when a native query times out. */
+declare class TraversalTimeoutError extends DeepMemoryError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
 
 /** A single validation error with optional suggestion */
 interface ValidationError {
@@ -210,6 +231,7 @@ interface MemoryRepositoryConfig {
     storage: StorageProvider;
     search?: SearchProvider;
     embedding?: EmbeddingProvider;
+    graphTraversal?: GraphTraversalProvider;
     vocabularyEngine: VocabularyEngine;
     provenanceTracker: ProvenanceTracker;
     eventBus: EventBus;
@@ -230,7 +252,7 @@ declare class MemoryRepository {
     proposeVocabularyChange(proposal: VocabularyProposal): Promise<VocabularyProposalResult>;
     /** @deprecated Use proposeVocabularyChange instead */
     proposeVocabularyExtension(proposal: VocabularyProposal): Promise<VocabularyProposalResult>;
-    createEntity(input: CreateEntityInput): Promise<Entity>;
+    createEntities(inputs: CreateEntityInput[]): Promise<Entity[]>;
     updateEntity(entityId: string, updates: UpdateEntityInput): Promise<Entity>;
     getEntity(entityId: string, detailLevel?: DetailLevel): Promise<Entity | EntitySummary | EntityBrief | null>;
     getBySlug(slug: string, detailLevel?: DetailLevel): Promise<Entity | EntitySummary | EntityBrief | null>;
@@ -253,7 +275,7 @@ declare class MemoryRepository {
         /** Milliseconds to wait between batches for rate limiting (default 0) */
         delayBetweenBatchesMs?: number;
     }): Promise<ReembedResult>;
-    createRelationship(input: CreateRelationshipInput): Promise<Relationship>;
+    createRelationships(inputs: CreateRelationshipInput[]): Promise<Relationship[]>;
     removeRelationship(relationshipId: string): Promise<void>;
     getRelationships(entityId: string, options?: {
         relationshipTypes?: string[];
@@ -272,9 +294,21 @@ declare class MemoryRepository {
     }): Promise<GraphResult>;
     exploreNeighbourhood(entityId: string, options?: ExploreOptions): Promise<Neighbourhood>;
     findPaths(sourceId: string, targetId: string, options?: PathOptions): Promise<PathResult>;
+    traverse(spec: TraversalSpec): Promise<TraversalResult>;
+    executeNativeQuery(query: string, params?: Record<string, unknown>): Promise<TraversalResult>;
     searchByConcept(query: string, options?: ConceptSearchOptions): Promise<PaginatedResult<ScoredEntity>>;
     getTimeline(entityId: string, options?: TimelineOptions): Promise<TimelineResult>;
     getStats(): Promise<RepositoryStats>;
+    /** Delete all entities and relationships in this repository, preserving the repository and vocabulary */
+    deleteAllContents(): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
+    /**
+     * Returns a static markdown guide describing the recommended query strategy
+     * for AI agents and other consumers of the repository.
+     */
+    getQueryGuide(): string;
     on<E extends DeepMemoryEventType>(event: E, handler: EventHandler<E>): Unsubscribe;
     onHook<E extends Extract<DeepMemoryEventType, 'entity:creating' | 'entity:updating' | 'entity:deleting' | 'relationship:creating' | 'relationship:removing'>>(event: E, handler: HookHandler<E>): Unsubscribe;
 }
@@ -293,6 +327,8 @@ interface DeepMemoryConfig {
     embedding?: EmbeddingProvider;
     /** Optional: lock provider for distributed locking */
     lock?: LockProvider;
+    /** Optional: graph traversal provider for native multi-hop queries */
+    graphTraversal?: GraphTraversalProvider;
     /** Required: provenance context identifying the actor */
     provenance: ProvenanceContext;
 }
@@ -302,14 +338,15 @@ declare class DeepMemory {
     private readonly embedding?;
     /** Reserved for future distributed locking support */
     readonly lock?: LockProvider;
+    private readonly graphTraversalProvider?;
     private readonly provenance;
     private readonly globalEventBus;
     private initialised;
     constructor(config: DeepMemoryConfig);
-    /** Initialise the storage provider (call once before use) */
+    /** Initialise the storage provider and optional providers (call once before use) */
     private ensureInitialised;
     /** Create or migrate the storage schema. Call once at deployment / startup, not per-request. */
-    ensureSchema(): Promise<void>;
+    ensureSchema(): Promise<EnsureSchemaResult>;
     private validateRepositoryId;
     /** Create a new memory repository */
     createRepository(config: RepositoryConfig): Promise<MemoryRepository>;
@@ -321,8 +358,13 @@ declare class DeepMemory {
     updateRepository(repositoryId: string, updates: RepositoryUpdate): Promise<StoredRepository>;
     /** Delete a repository */
     deleteRepository(repositoryId: string): Promise<void>;
+    /** Delete all entities and relationships in a repository, preserving the repository and vocabulary */
+    deleteAllContents(repositoryId: string): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
     /** Export a repository to a portable archive */
-    exportRepository(repositoryId: string): Promise<ExportArchive>;
+    exportRepository(repositoryId: string, options?: ExportOptions): Promise<ExportArchive>;
     /** Import a repository from a portable archive */
     importRepository(archive: ExportArchive, options: ImportOptions): Promise<ImportResult>;
     /**
@@ -330,7 +372,7 @@ declare class DeepMemory {
      * Yields: manifest → vocabulary → entity chunks → relationship chunks.
      * Use for large repositories to avoid loading everything into memory.
      */
-    exportRepositoryStream(repositoryId: string): AsyncGenerator<ExportStreamItem>;
+    exportRepositoryStream(repositoryId: string, options?: ExportOptions): AsyncGenerator<ExportStreamItem>;
     /**
      * Import a repository from a stream of chunks.
      * Use for large repositories to avoid loading everything into memory.
@@ -350,6 +392,31 @@ declare class DeepMemory {
  */
 declare function matchesPropertyFilters(properties: Record<string, unknown>, filters: PropertyFilter[]): boolean;
 
+interface TraversalCompiler {
+    /** The query language this compiler targets. */
+    readonly language: 'gremlin' | 'cypher' | 'sql';
+    /** Compile a validated TraversalSpec into a native query string. */
+    compile(spec: TraversalSpec, vocabulary: MemoryVocabulary): CompiledQuery;
+}
+interface CompiledQuery {
+    /** The native query string. */
+    query: string;
+    /** Parameter bindings (for parameterized queries). */
+    params: Record<string, unknown>;
+    /** Estimated cost heuristic (fan-out estimation). Provider may override. */
+    estimatedFanOut: number;
+}
+
+declare class GremlinCompiler implements TraversalCompiler {
+    readonly language: "gremlin";
+    compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
+}
+
+declare class CypherCompiler implements TraversalCompiler {
+    readonly language: "cypher";
+    compile(spec: TraversalSpec, _vocabulary: MemoryVocabulary): CompiledQuery;
+}
+
 declare class InMemoryStorageProvider implements StorageProvider {
     private stores;
     private getStore;
@@ -359,7 +426,11 @@ declare class InMemoryStorageProvider implements StorageProvider {
     getRepository(repositoryId: string): Promise<StoredRepository | null>;
     listRepositories(filter?: RepositoryFilter): Promise<PaginatedResult<StoredRepositorySummary>>;
     updateRepository(repositoryId: string, updates: RepositoryUpdate): Promise<StoredRepository>;
-    deleteRepository(repositoryId: string): Promise<void>;
+    deleteRepository(repositoryId: string, _onProgress?: DeleteProgressCallback): Promise<void>;
+    deleteAllContents(repositoryId: string, _onProgress?: DeleteProgressCallback): Promise<{
+        deletedEntities: number;
+        deletedRelationships: number;
+    }>;
     getRepositoryStats(repositoryId: string): Promise<RepositoryStats>;
     getVocabulary(repositoryId: string): Promise<MemoryVocabulary>;
     saveVocabulary(repositoryId: string, vocabulary: MemoryVocabulary): Promise<void>;
@@ -386,7 +457,7 @@ declare class InMemoryStorageProvider implements StorageProvider {
     findPaths(repositoryId: string, sourceId: string, targetId: string, options: StoragePathOptions): Promise<StoragePathResult>;
     getTimeline(repositoryId: string, entityId: string, options: StorageTimelineOptions): Promise<StorageTimelineResult>;
     exportAll(repositoryId: string): AsyncIterable<ExportChunk>;
-    importBulk(repositoryId: string, data: ImportChunk[]): Promise<BulkImportResult>;
+    importBulk(repositoryId: string, data: ImportChunk[], _options?: BulkImportOptions): Promise<BulkImportResult>;
 }
 
 declare class InMemorySearchProvider implements SearchProvider {
@@ -405,4 +476,4 @@ declare class NoOpEmbeddingProvider implements EmbeddingProvider {
     modelId(): string;
 }
 
-export { BulkImportResult, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderRequiredError, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, EventHandler, EventPayload, ExploreOptions, ExportArchive, ExportChunk, ExportError, ExportStreamItem, FindEntitiesQuery, GovernanceConfig, GovernanceDeniedError, GraphResult, HookResult, ImportChunk, ImportError, ImportOptions, ImportResult, ImportStreamHeader, InMemorySearchProvider, InMemoryStorageProvider, InvalidInputError, LockProvider, MemoryRepository, MemoryVocabulary, Neighbourhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, StorageExploreOptions, StorageFindQuery, StorageNeighbourhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, Unsubscribe, UpdateEntityInput, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters };
+export { BulkImportOptions, BulkImportResult, type CompiledQuery, ConceptSearchOptions, CreateEntityInput, CreateRelationshipInput, CypherCompiler, DeepMemory, type DeepMemoryConfig, DeepMemoryError, type DeepMemoryErrorCode, DeepMemoryEvent, DeepMemoryEventType, DeleteProgressCallback, DetailLevel, DuplicateEntityError, DuplicateRelationshipError, DuplicateRepositoryError, EmbeddingProvider, EmbeddingProviderRequiredError, EnsureSchemaResult, Entity, EntityBrief, EntityNotFoundError, EntitySummary, EntityTypeDefinition, 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, Neighbourhood, NoOpEmbeddingProvider, OperationCancelledError, PaginatedResult, PaginationOptions, PathOptions, PathResult, PropertyFilter, Provenance, ProvenanceContext, ProviderError, ReembedResult, Relationship, RelationshipConstraintError, RelationshipNotFoundError, RelationshipQueryOptions, RelationshipSummary, RepositoryConfig, RepositoryFilter, RepositoryNotFoundError, RepositoryStats, RepositorySummary, RepositoryUpdate, ResolvedVocabulary, ScoredEntity, SearchHit, SearchOptions, SearchProvider, SearchableEntity, StorageExploreOptions, StorageFindQuery, StorageNeighbourhood, StoragePathOptions, StoragePathResult, StorageProvider, StorageRepositoryConfig, StorageTimelineOptions, StorageTimelineResult, StoredEntity, StoredEntityUpdate, StoredRelationship, StoredRepository, StoredRepositorySummary, TimelineOptions, TimelineResult, type TraversalCompiler, TraversalResult, TraversalSpec, TraversalTimeoutError, TraversalValidationError, TraversalVocabularyError, Unsubscribe, UpdateEntityInput, VocabularyChangeRecord, VocabularyProposal, VocabularyProposalResult, VocabularyValidationError, generateId, isValidUuid, matchesPropertyFilters };