@claude-flow/cli 3.32.2 → 3.32.3

package/dist/src/memory/memory-bridge.d.ts

@@ -1,537 +0,0 @@
-/**
- * Memory Bridge — Routes CLI memory operations through ControllerRegistry + AgentDB v3
- *
- * Per ADR-053 Phases 1-6: Full controller activation pipeline.
- * CLI → ControllerRegistry → AgentDB v3 controllers.
- *
- * Phase 1: Core CRUD + embeddings + HNSW + controller access (complete)
- * Phase 2: BM25 hybrid search, TieredCache read/write, MutationGuard validation
- * Phase 3: ReasoningBank pattern store, recordFeedback, CausalMemoryGraph edges
- * Phase 4: SkillLibrary promotion, ExplainableRecall provenance, AttestationLog
- * Phase 5: ReflexionMemory session lifecycle, WitnessChain attestation
- * Phase 6: AgentDB MCP tools (separate file), COW branching
- *
- * Uses better-sqlite3 API (synchronous .all()/.get()/.run()) since that's
- * what AgentDB v3 uses internally.
- *
- * @module v3/cli/memory-bridge
- */
-/**
- * Store an entry via AgentDB v3.
- * Phase 2-5: Routes through MutationGuard → TieredCache → DB → AttestationLog.
- * Returns null to signal fallback to sql.js.
- */
-export declare function bridgeStoreEntry(options: {
-    key: string;
-    value: string;
-    namespace?: string;
-    generateEmbeddingFlag?: boolean;
-    tags?: string[];
-    ttl?: number;
-    dbPath?: string;
-    upsert?: boolean;
-}): Promise<{
-    success: boolean;
-    id: string;
-    embedding?: {
-        dimensions: number;
-        model: string;
-    };
-    rawEmbedding?: number[];
-    guarded?: boolean;
-    cached?: boolean;
-    attested?: boolean;
-    error?: string;
-} | null>;
-/**
- * Search entries via AgentDB v3.
- * Phase 2: BM25 hybrid scoring replaces naive String.includes() keyword fallback.
- * Combines cosine similarity (semantic) with BM25 (lexical) via reciprocal rank fusion.
- */
-export declare function bridgeSearchEntries(options: {
-    query: string;
-    namespace?: string;
-    limit?: number;
-    threshold?: number;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    results: {
-        id: string;
-        key: string;
-        content: string;
-        score: number;
-        namespace: string;
-        provenance?: string;
-    }[];
-    searchTime: number;
-    searchMethod?: string;
-    error?: string;
-} | null>;
-/**
- * List entries via AgentDB v3.
- */
-export declare function bridgeListEntries(options: {
-    namespace?: string;
-    limit?: number;
-    offset?: number;
-    dbPath?: string;
-    /** #2073: When true, include the entry's full `content` string in each result. */
-    includeContent?: boolean;
-}): Promise<{
-    success: boolean;
-    entries: {
-        id: string;
-        key: string;
-        namespace: string;
-        size: number;
-        accessCount: number;
-        createdAt: string;
-        updatedAt: string;
-        hasEmbedding: boolean;
-        /** #2073: Present when `includeContent: true` was requested. */
-        content?: string;
-    }[];
-    total: number;
-    error?: string;
-} | null>;
-/**
- * Get a specific entry via AgentDB v3.
- * Phase 2: TieredCache consulted before DB hit.
- */
-export declare function bridgeGetEntry(options: {
-    key: string;
-    namespace?: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    found: boolean;
-    entry?: {
-        id: string;
-        key: string;
-        namespace: string;
-        content: string;
-        accessCount: number;
-        createdAt: string;
-        updatedAt: string;
-        hasEmbedding: boolean;
-        tags: string[];
-    };
-    cacheHit?: boolean;
-    error?: string;
-} | null>;
-/**
- * Delete an entry via AgentDB v3.
- * Phase 5: MutationGuard validation, cache invalidation, attestation logging.
- */
-export declare function bridgeDeleteEntry(options: {
-    key: string;
-    namespace?: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    deleted: boolean;
-    key: string;
-    namespace: string;
-    remainingEntries: number;
-    guarded?: boolean;
-    error?: string;
-} | null>;
-export declare function bridgePurgeNamespace(options: {
-    namespace: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    deletedCount: number;
-    remainingEntries: number;
-    guarded?: boolean;
-    error?: string;
-} | null>;
-/**
- * Generate embedding via AgentDB v3's embedder.
- * Returns null if bridge unavailable — caller falls back to own ONNX/hash.
- */
-export declare function bridgeGenerateEmbedding(text: string, dbPath?: string): Promise<{
-    embedding: number[];
-    dimensions: number;
-    model: string;
-    backend?: 'onnx' | 'mock';
-} | null>;
-/**
- * Load embedding model via AgentDB v3 (it loads on init).
- * Returns null if unavailable.
- */
-export declare function bridgeLoadEmbeddingModel(dbPath?: string): Promise<{
-    success: boolean;
-    dimensions: number;
-    modelName: string;
-    loadTime?: number;
-} | null>;
-/**
- * Get HNSW status from AgentDB v3's vector backend or HNSW index.
- * Returns null if unavailable.
- */
-export declare function bridgeGetHNSWStatus(dbPath?: string): Promise<{
-    available: boolean;
-    initialized: boolean;
-    entryCount: number;
-    dimensions: number;
-} | null>;
-/**
- * Search using AgentDB v3's embedder + SQLite entries.
- * This is the HNSW-equivalent search through the bridge.
- * Returns null if unavailable.
- */
-export declare function bridgeSearchHNSW(queryEmbedding: number[], options?: {
-    k?: number;
-    namespace?: string;
-    threshold?: number;
-}, dbPath?: string): Promise<Array<{
-    id: string;
-    key: string;
-    content: string;
-    score: number;
-    namespace: string;
-}> | null>;
-/**
- * Add entry to the bridge's database with embedding.
- * Returns null if unavailable.
- */
-export declare function bridgeAddToHNSW(id: string, embedding: number[], entry: {
-    id: string;
-    key: string;
-    namespace: string;
-    content: string;
-}, dbPath?: string): Promise<boolean | null>;
-/**
- * Get a named controller from AgentDB v3 via ControllerRegistry.
- * Returns null if unavailable.
- */
-export declare function bridgeGetController(name: string, dbPath?: string): Promise<any | null>;
-/**
- * Check if a controller is available.
- */
-export declare function bridgeHasController(name: string, dbPath?: string): Promise<boolean>;
-/**
- * List all controllers and their status.
- */
-export declare function bridgeListControllers(dbPath?: string): Promise<Array<{
-    name: string;
-    enabled: boolean;
-    level: number;
-}> | null>;
-/**
- * Check if the AgentDB v3 bridge is available.
- */
-export declare function isBridgeAvailable(dbPath?: string): Promise<boolean>;
-/**
- * Get the ControllerRegistry instance (for advanced consumers).
- */
-export declare function getControllerRegistry(dbPath?: string): Promise<any | null>;
-/**
- * Shutdown the bridge and release resources.
- */
-export declare function shutdownBridge(): Promise<void>;
-/**
- * Store a pattern via ReasoningBank controller.
- * Falls back to raw SQL if ReasoningBank unavailable.
- */
-export declare function bridgeStorePattern(options: {
-    pattern: string;
-    type: string;
-    confidence: number;
-    metadata?: Record<string, unknown>;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    patternId: string;
-    controller: string;
-} | null>;
-/**
- * Search patterns via ReasoningBank controller.
- */
-export declare function bridgeSearchPatterns(options: {
-    query: string;
-    topK?: number;
-    minConfidence?: number;
-    dbPath?: string;
-}): Promise<{
-    results: Array<{
-        id: string;
-        content: string;
-        score: number;
-    }>;
-    controller: string;
-} | null>;
-/**
- * Record task feedback for learning via ReasoningBank or LearningSystem.
- * Wired into hooks_post-task handler.
- */
-export declare function bridgeRecordFeedback(options: {
-    taskId: string;
-    success: boolean;
-    quality: number;
-    agent?: string;
-    duration?: number;
-    patterns?: string[];
-    dbPath?: string;
-    parentAgentId?: string;
-    depth?: number;
-}): Promise<{
-    success: boolean;
-    controller: string;
-    updated: number;
-} | null>;
-/**
- * Record a causal edge between two entries (e.g., task → result).
- */
-export declare function bridgeRecordCausalEdge(options: {
-    sourceId: string;
-    targetId: string;
-    relation: string;
-    weight?: number;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    controller: string;
-} | null>;
-/**
- * Delete a hierarchical-memory entry by key (#1784).
- *
- * Reality check: agentdb's HierarchicalMemory class doesn't expose a public
- * delete API today, so the real-backend path falls back to direct SQL on
- * the underlying SQLite tables (status flip to 'deleted' + AttestationLog
- * audit). The bridge-fallback path that bridgeHierarchicalStore uses when
- * HierarchicalMemory isn't loaded writes plain memory_entries rows that
- * `bridgeDeleteEntry` already handles.
- *
- * Returns { controller: 'native-unsupported' } when the real HM is loaded
- * and the SQL fallback can't reach its private tables — surfacing the
- * limitation honestly instead of silently returning success.
- */
-export declare function bridgeDeleteHierarchical(options: {
-    key: string;
-    tier?: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    deleted: boolean;
-    key: string;
-    tier?: string;
-    controller: string;
-    guarded?: boolean;
-    error?: string;
-} | null>;
-/**
- * Delete a causal edge between two memory entries (#1784).
- *
- * The bridge stores fallback edges in namespace='causal-edges' with key
- * '{sourceId}→{targetId}'. Those CAN be soft-deleted. The native graph-node
- * backend has no delete API (createNode/createEdge/createHyperedge only),
- * so an edge that landed in graph-node native storage stays there. We
- * surface that explicitly via controller: 'native-unsupported'.
- */
-export declare function bridgeDeleteCausalEdge(options: {
-    sourceId: string;
-    targetId: string;
-    relation?: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    deleted: boolean;
-    sourceId: string;
-    targetId: string;
-    controller: string;
-    guarded?: boolean;
-    error?: string;
-} | null>;
-/**
- * Cascade-delete a causal node and all its incident edges (#1784).
- *
- * Same constraint as bridgeDeleteCausalEdge — native graph-node lacks a
- * delete API. SQL fallback path soft-deletes the node (if stored as a
- * memory_entries row) and every edge whose key contains the nodeId.
- */
-export declare function bridgeDeleteCausalNode(options: {
-    nodeId: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    deletedNode: boolean;
-    deletedEdges: number;
-    nodeId: string;
-    controller: string;
-    guarded?: boolean;
-    error?: string;
-} | null>;
-/**
- * Start a session with ReflexionMemory episodic replay.
- * Loads relevant past session patterns for the new session.
- */
-export declare function bridgeSessionStart(options: {
-    sessionId: string;
-    context?: string;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    controller: string;
-    restoredPatterns: number;
-    sessionId: string;
-} | null>;
-/**
- * End a session and persist episodic summary to ReflexionMemory.
- */
-export declare function bridgeSessionEnd(options: {
-    sessionId: string;
-    summary?: string;
-    tasksCompleted?: number;
-    patternsLearned?: number;
-    dbPath?: string;
-}): Promise<{
-    success: boolean;
-    controller: string;
-    persisted: boolean;
-} | null>;
-/**
- * Route a task via AgentDB's SemanticRouter.
- * Returns null to fall back to local ruvector router.
- */
-export declare function bridgeRouteTask(options: {
-    task: string;
-    context?: string;
-    dbPath?: string;
-}): Promise<{
-    route: string;
-    confidence: number;
-    agents: string[];
-    controller: string;
-} | null>;
-/**
- * Get comprehensive bridge health including all controller statuses.
- */
-export declare function bridgeHealthCheck(dbPath?: string): Promise<{
-    available: boolean;
-    controllers: Array<{
-        name: string;
-        enabled: boolean;
-        level: number;
-    }>;
-    attestationCount?: number;
-    cacheStats?: {
-        size: number;
-        hits: number;
-        misses: number;
-    };
-} | null>;
-/**
- * Store to hierarchical memory with tier.
- * Valid tiers: working, episodic, semantic
- *
- * Real HierarchicalMemory API (agentdb alpha.10+):
- *   store(content, importance?, tier?, options?) → Promise<string>
- * Fallback API (@claude-flow/memory TieredMemoryStore):
- *   store(key, value, tier, temporalOptions?) — synchronous, returns
- *   { id, key, tier, superseded? }
- *
- * Temporal validity (Zep/Graphiti-style, impl/memory-sota):
- * - validFrom / validUntil (ISO) travel with the entry.
- * - supersedes=<entryId|key> INVALIDATES the old entry (validUntil=now +
- *   supersededBy=newId) instead of deleting it. Natively supported by the
- *   TieredMemoryStore fallback; on the real agentdb HierarchicalMemory the
- *   temporal fields are stored in metadata, and supersede is reported as
- *   unsupported (no public update API) rather than silently dropped.
- */
-export declare function bridgeHierarchicalStore(params: {
-    key: string;
-    value: string;
-    tier?: string;
-    importance?: number;
-    validFrom?: string;
-    validUntil?: string;
-    supersedes?: string;
-}): Promise<any>;
-/**
- * Recall from hierarchical memory.
- *
- * Real HierarchicalMemory API (agentdb alpha.10+):
- *   recall(query: MemoryQuery) → Promise<MemoryItem[]>
- *   where MemoryQuery = { query, tier?, k?, threshold?, context?, includeDecayed? }
- * Stub API (fallback):
- *   recall(query: string, topK: number) → synchronous array
- */
-export declare function bridgeHierarchicalRecall(params: {
-    query: string;
-    tier?: string;
-    topK?: number;
-    includeExpired?: boolean;
-}): Promise<any>;
-/**
- * Run memory consolidation.
- *
- * Real MemoryConsolidation API (agentdb alpha.10+):
- *   consolidate() → Promise<ConsolidationReport>
- *   ConsolidationReport = { episodicProcessed, semanticCreated, memoriesForgotten, ... }
- * Stub API (fallback):
- *   consolidate() → { promoted, pruned, timestamp }
- */
-export declare function bridgeConsolidate(params: {
-    minAge?: number;
-    maxEntries?: number;
-}): Promise<any>;
-/**
- * Batch operations (insert, update, delete).
- * - insert: calls insertEpisodes(entries) where entries are {content, metadata?}
- * - delete: calls bulkDelete(table, conditions) on episodes table
- * - update: calls bulkUpdate(table, updates, conditions) on episodes table
- */
-export declare function bridgeBatchOperation(params: {
-    operation: string;
-    entries: any[];
-}): Promise<any>;
-/**
- * Synthesize context from memories.
- * ContextSynthesizer.synthesize is a static method that takes MemoryPattern[] (not a string).
- */
-export declare function bridgeContextSynthesize(params: {
-    query: string;
-    maxEntries?: number;
-}): Promise<any>;
-/**
- * Route via SemanticRouter.
- * Available since agentdb 3.0.0-alpha.10 — uses @ruvector/router for
- * semantic matching with keyword fallback.
- */
-export declare function bridgeSemanticRoute(params: {
-    input: string;
-}): Promise<any>;
-/**
- * Export all embeddings from the bridge's better-sqlite3 connection.
- * Used by RaBitQ to build its index from the same data that memory_store writes.
- * Returns null if bridge is unavailable (caller falls back to sql.js).
- */
-export declare function bridgeGetAllEmbeddings(options?: {
-    dimensions?: number;
-    limit?: number;
-    dbPath?: string;
-}): Promise<Array<{
-    id: string;
-    key: string;
-    namespace: string;
-    embedding: number[];
-}> | null>;
-/**
- * Public helper for the unified learning-stats aggregator: counts of entries
- * per namespace + the top-level total. Best-effort — if the bridge isn't
- * available it returns zeros so the aggregator can still report the other
- * stores honestly. (#2245 follow-up.)
- */
-export declare function getMemoryBridgeStats(options?: {
-    namespaces?: string[];
-    dbPath?: string;
-}): Promise<{
-    totalEntries: number;
-    perNamespace: Record<string, number>;
-    source: string;
-    reachable: boolean;
-}>;
-//# sourceMappingURL=memory-bridge.d.ts.map