@dakera-ai/dakera 0.8.6 → 0.9.2

package/dist/index.d.mts

@@ -1260,6 +1260,213 @@ interface BatchForgetRequest {
 interface BatchForgetResponse {
     deleted_count: number;
 }
+/**
+ * Edge type for memory knowledge graph relationships (CE-5).
+ *
+ * - `related_to`: Cosine similarity ≥ 0.85 between two memories.
+ * - `shares_entity`: Both memories reference the same named entity (CE-4).
+ * - `precedes`: Temporal ordering — source was created before target.
+ * - `linked_by`: Explicit user/agent-created link.
+ */
+type EdgeType = 'related_to' | 'shares_entity' | 'precedes' | 'linked_by';
+/** A directed edge in the memory knowledge graph. */
+interface GraphEdge {
+    /** Unique edge identifier. */
+    id: string;
+    /** Source memory ID. */
+    source_id: string;
+    /** Target memory ID. */
+    target_id: string;
+    /** Relationship type between the two memories. */
+    edge_type: EdgeType;
+    /** Edge weight (0.0–1.0). For `related_to` this is the cosine similarity score. */
+    weight: number;
+    /** Unix timestamp of edge creation. */
+    created_at: number;
+}
+/** A node (memory) in the knowledge graph traversal result. */
+interface GraphNode {
+    /** Memory identifier. */
+    memory_id: string;
+    /** First 200 characters of memory content. */
+    content_preview: string;
+    /** Memory importance score. */
+    importance: number;
+    /** Traversal depth from the root node (root = 0). */
+    depth: number;
+}
+/** Graph traversal result from `GET /v1/memories/{id}/graph`. */
+interface MemoryGraph {
+    /** The root memory ID from which traversal started. */
+    root_id: string;
+    /** Maximum traversal depth used. */
+    depth: number;
+    /** All memory nodes reachable within the requested depth. */
+    nodes: GraphNode[];
+    /** All edges connecting the returned nodes. */
+    edges: GraphEdge[];
+}
+/** Shortest path result from `GET /v1/memories/{id}/path`. */
+interface GraphPath {
+    /** Starting memory ID. */
+    source_id: string;
+    /** Destination memory ID. */
+    target_id: string;
+    /** Ordered list of memory IDs from source to target (inclusive). */
+    path: string[];
+    /** Number of edges traversed (`path.length - 1`). -1 if no path exists. */
+    hops: number;
+    /** Edges along the path, in traversal order. */
+    edges: GraphEdge[];
+}
+/** Response from `POST /v1/memories/{id}/links`. */
+interface GraphLinkResponse {
+    /** The newly created edge. */
+    edge: GraphEdge;
+}
+/** Agent graph export from `GET /v1/agents/{id}/graph/export`. */
+interface GraphExport {
+    /** Agent whose graph was exported. */
+    agent_id: string;
+    /** Export format: `json`, `graphml`, or `csv`. */
+    format: 'json' | 'graphml' | 'csv';
+    /** Serialised graph in the requested format. */
+    data: string;
+    /** Total number of memory nodes in the export. */
+    node_count: number;
+    /** Total number of edges in the export. */
+    edge_count: number;
+}
+/** Options for `client.memories.graph()`. */
+interface MemoryGraphOptions {
+    /** Maximum traversal depth (default: 1, max: 3). */
+    depth?: number;
+    /** Filter by edge types. `undefined` returns all types. */
+    types?: EdgeType[];
+}
+/** Configuration for namespace-level entity extraction (CE-4). */
+interface NamespaceNerConfig {
+    extract_entities: boolean;
+    entity_types?: string[];
+}
+/** A single extracted entity from GLiNER or rule-based pipeline. */
+interface ExtractedEntity {
+    entity_type: string;
+    value: string;
+    score: number;
+}
+/** Response from POST /v1/memories/extract */
+interface EntityExtractionResponse {
+    entities: ExtractedEntity[];
+}
+/** Response from GET /v1/memory/entities/:id */
+interface MemoryEntitiesResponse {
+    memory_id: string;
+    entities: ExtractedEntity[];
+}
+/**
+ * Feedback signal for memory active learning (INT-1).
+ *
+ * - `upvote`: Boost importance ×1.15, capped at 1.0.
+ * - `downvote`: Penalise importance ×0.85, floor 0.0.
+ * - `flag`: Mark as irrelevant — sets `decay_flag=true`, no immediate importance change.
+ * - `positive`: Backward-compatible alias for `upvote`.
+ * - `negative`: Backward-compatible alias for `downvote`.
+ */
+type FeedbackSignal = 'upvote' | 'downvote' | 'flag' | 'positive' | 'negative';
+/** A single recorded feedback event stored in memory metadata (INT-1). */
+interface FeedbackHistoryEntry {
+    /** Feedback signal that was applied. */
+    signal: FeedbackSignal;
+    /** Unix timestamp (seconds) when feedback was submitted. */
+    timestamp: number;
+    /** Memory importance before this feedback was applied. */
+    old_importance: number;
+    /** Memory importance after this feedback was applied. */
+    new_importance: number;
+}
+/** Request body for POST /v1/memories/:id/feedback (INT-1). */
+interface MemoryFeedbackBodyRequest {
+    agent_id: string;
+    signal: FeedbackSignal;
+}
+/** Request body for PATCH /v1/memories/:id/importance (INT-1). */
+interface MemoryImportancePatchRequest {
+    agent_id: string;
+    importance: number;
+}
+/** Response from POST /v1/memories/:id/feedback and PATCH /v1/memories/:id/importance (INT-1). */
+interface FeedbackResponse {
+    /** ID of the memory that was updated. */
+    memory_id: string;
+    /** New importance score after the feedback was applied (0.0–1.0). */
+    new_importance: number;
+    /** The feedback signal that was recorded. */
+    signal: FeedbackSignal;
+}
+/** Response from GET /v1/memories/:id/feedback (INT-1). */
+interface FeedbackHistoryResponse {
+    memory_id: string;
+    /** Ordered list of feedback events (oldest first, capped at 100). */
+    entries: FeedbackHistoryEntry[];
+}
+/** Response from GET /v1/agents/:id/feedback/summary (INT-1). */
+interface AgentFeedbackSummary {
+    agent_id: string;
+    upvotes: number;
+    downvotes: number;
+    flags: number;
+    total_feedback: number;
+    /** Weighted-average importance across all non-expired memories (0.0–1.0). */
+    health_score: number;
+}
+/** Response from GET /v1/feedback/health (INT-1). */
+interface FeedbackHealthResponse {
+    agent_id: string;
+    /** Mean importance of all non-expired memories (0.0–1.0). Higher = healthier. */
+    health_score: number;
+    memory_count: number;
+    avg_importance: number;
+}
+/** Namespace-scoped API key metadata (no secret). Returned by listNamespaceKeys (SEC-1). */
+interface NamespaceKeyInfo {
+    key_id: string;
+    name: string;
+    namespace: string;
+    created_at: number;
+    active: boolean;
+    expires_at?: number;
+}
+/**
+ * Response from POST /v1/namespaces/:namespace/keys (SEC-1).
+ * The `key` field is shown **only once** — store it securely.
+ */
+interface CreateNamespaceKeyResponse {
+    key_id: string;
+    /** The raw API key. Shown only on creation — cannot be retrieved again. */
+    key: string;
+    name: string;
+    namespace: string;
+    created_at: number;
+    expires_at?: number;
+    warning: string;
+}
+/** Response from GET /v1/namespaces/:namespace/keys (SEC-1). */
+interface ListNamespaceKeysResponse {
+    namespace: string;
+    keys: NamespaceKeyInfo[];
+    total: number;
+}
+/** Response from GET /v1/namespaces/:namespace/keys/:key_id/usage (SEC-1). */
+interface NamespaceKeyUsageResponse {
+    key_id: string;
+    namespace: string;
+    total_requests: number;
+    successful_requests: number;
+    failed_requests: number;
+    bytes_transferred: number;
+    avg_latency_ms: number;
+}
 
 /**
  * Dakera Client
@@ -1836,6 +2043,117 @@ declare class DakeraClient {
     consolidate(agentId: string, request?: ConsolidateRequest): Promise<ConsolidateResponse>;
     /** Submit feedback on a memory recall */
     memoryFeedback(agentId: string, request: MemoryFeedbackRequest): Promise<MemoryFeedbackResponse>;
+    /**
+     * Submit upvote/downvote/flag feedback on a memory (INT-1).
+     *
+     * - `upvote`: boosts importance ×1.15 (capped at 1.0).
+     * - `downvote`: penalises importance ×0.85 (floor 0.0).
+     * - `flag`: marks as irrelevant — accelerates decay on next cycle.
+     *
+     * @param memoryId  The memory to give feedback on.
+     * @param agentId   The agent that owns the memory.
+     * @param signal    Feedback signal.
+     */
+    feedbackMemory(memoryId: string, agentId: string, signal: FeedbackSignal): Promise<FeedbackResponse>;
+    /**
+     * Get the full feedback history for a memory (INT-1).
+     *
+     * @param memoryId  The memory whose feedback history to retrieve.
+     */
+    getMemoryFeedbackHistory(memoryId: string): Promise<FeedbackHistoryResponse>;
+    /**
+     * Get aggregate feedback counts and health score for an agent (INT-1).
+     *
+     * @param agentId  The agent to summarise feedback for.
+     */
+    getAgentFeedbackSummary(agentId: string): Promise<AgentFeedbackSummary>;
+    /**
+     * Directly override a memory's importance score (INT-1).
+     *
+     * @param memoryId    The memory to update.
+     * @param agentId     The agent that owns the memory.
+     * @param importance  New importance value (0.0–1.0).
+     */
+    patchMemoryImportance(memoryId: string, agentId: string, importance: number): Promise<FeedbackResponse>;
+    /**
+     * Get overall feedback health score for an agent (INT-1).
+     *
+     * The health score is the mean importance of all non-expired memories (0.0–1.0).
+     * A higher score indicates a healthier, more relevant memory store.
+     *
+     * @param agentId  The agent to get health score for.
+     */
+    getFeedbackHealth(agentId: string): Promise<FeedbackHealthResponse>;
+    /**
+     * Traverse the knowledge graph from a memory node.
+     *
+     * Requires CE-5 (Memory Knowledge Graph) on the server.
+     *
+     * @param memoryId  Root memory ID to start traversal from.
+     * @param options   `depth` (default 1, max 3) and optional `types` filter.
+     *
+     * @example
+     * const graph = await client.memories.graph(memoryId, { depth: 2 });
+     * console.log(`${graph.nodes.length} nodes, ${graph.edges.length} edges`);
+     */
+    memoryGraph(memoryId: string, options?: MemoryGraphOptions): Promise<MemoryGraph>;
+    /**
+     * Find the shortest path between two memories in the knowledge graph.
+     *
+     * Requires CE-5 (Memory Knowledge Graph) on the server.
+     *
+     * @param sourceId  Starting memory ID.
+     * @param targetId  Destination memory ID.
+     */
+    memoryPath(sourceId: string, targetId: string): Promise<GraphPath>;
+    /**
+     * Create an explicit edge between two memories.
+     *
+     * Requires CE-5 (Memory Knowledge Graph) on the server.
+     *
+     * @param sourceId  Source memory ID.
+     * @param targetId  Target memory ID.
+     * @param edgeType  Edge type — must be `"linked_by"` for explicit links.
+     */
+    memoryLink(sourceId: string, targetId: string, edgeType?: EdgeType): Promise<GraphLinkResponse>;
+    /**
+     * Export the full knowledge graph for an agent.
+     *
+     * Requires CE-5 (Memory Knowledge Graph) on the server.
+     *
+     * @param agentId  Agent whose graph to export.
+     * @param format   Export format — `"json"` (default), `"graphml"`, or `"csv"`.
+     */
+    agentGraphExport(agentId: string, format?: 'json' | 'graphml' | 'csv'): Promise<GraphExport>;
+    /**
+     * Configure entity extraction for a namespace.
+     *
+     * @param namespace - Target namespace
+     * @param config - NER configuration (extract_entities flag + entity_types)
+     * @returns Updated namespace config
+     *
+     * @note Requires CE-4 (GLiNER) on the server.
+     */
+    configureNamespaceNer(namespace: string, config: NamespaceNerConfig): Promise<Record<string, unknown>>;
+    /**
+     * Extract entities from arbitrary text without storing a memory.
+     *
+     * @param text - Text to extract entities from
+     * @param entityTypes - Entity types to extract (defaults to server defaults)
+     * @returns EntityExtractionResponse with extracted entities
+     *
+     * @note Requires CE-4 (GLiNER) on the server.
+     */
+    extractEntities(text: string, entityTypes?: string[]): Promise<EntityExtractionResponse>;
+    /**
+     * Get entity tags attached to a stored memory.
+     *
+     * @param memoryId - Memory ID to fetch entities for
+     * @returns MemoryEntitiesResponse with entity list
+     *
+     * @note Requires CE-4 (GLiNER) on the server.
+     */
+    memoryEntities(memoryId: string): Promise<MemoryEntitiesResponse>;
     /** Start a new session */
     startSession(agentId: string, metadata?: Record<string, unknown>): Promise<Session>;
     /** End a session */
@@ -2030,6 +2348,34 @@ declare class DakeraClient {
      * ```
      */
     streamMemoryEvents(): AsyncGenerator<MemoryEvent>;
+    /**
+     * Subscribe to real-time memory lifecycle events for a specific agent.
+     *
+     * Wraps `GET /v1/events/stream`, filtering events by `agentId` and
+     * optional `tags`.  Reconnects automatically on connection drop when
+     * `reconnect` is `true`.
+     *
+     * Requires a Read-scoped API key.
+     *
+     * @param agentId - Agent whose events to receive.
+     * @param options.tags - Optional tag filter: only events whose tags overlap
+     *   this array are yielded.
+     * @param options.reconnect - Auto-reconnect on connection drop. Default `true`.
+     * @param options.reconnectDelay - Milliseconds to wait between reconnection
+     *   attempts. Default `1000`.
+     *
+     * @example
+     * ```ts
+     * for await (const event of client.subscribeAgentMemories('my-bot', { tags: ['important'] })) {
+     *   console.log(event.event_type, event.memory_id);
+     * }
+     * ```
+     */
+    subscribeAgentMemories(agentId: string, options?: {
+        tags?: string[];
+        reconnect?: boolean;
+        reconnectDelay?: number;
+    }): AsyncGenerator<MemoryEvent>;
     /**
      * Return a URL with `?api_key=<key>` appended for use with browser-native
      * `EventSource`, which cannot send custom request headers.
@@ -2054,6 +2400,39 @@ declare class DakeraClient {
     private _streamSseMemory;
     /** Parse a single SSE event block into a {@link MemoryEvent}. */
     private _parseSseMemoryBlock;
+    /**
+     * Create a namespace-scoped API key (SEC-1).
+     *
+     * The `key` field in the response is shown **only once** — store it securely.
+     *
+     * @param namespace     The namespace to scope this key to.
+     * @param name          Human-readable label for the key.
+     * @param expiresInDays Optional expiry in days from now.
+     */
+    createNamespaceKey(namespace: string, name: string, expiresInDays?: number): Promise<CreateNamespaceKeyResponse>;
+    /**
+     * List all API keys scoped to a namespace (SEC-1).
+     *
+     * @param namespace  The namespace whose keys to list.
+     */
+    listNamespaceKeys(namespace: string): Promise<ListNamespaceKeysResponse>;
+    /**
+     * Revoke a namespace-scoped API key (SEC-1).
+     *
+     * @param namespace  The namespace the key belongs to.
+     * @param keyId      The key to revoke.
+     */
+    deleteNamespaceKey(namespace: string, keyId: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    /**
+     * Get usage statistics for a namespace-scoped API key (SEC-1).
+     *
+     * @param namespace  The namespace the key belongs to.
+     * @param keyId      The key whose usage to retrieve.
+     */
+    getNamespaceKeyUsage(namespace: string, keyId: string): Promise<NamespaceKeyUsageResponse>;
 }
 
 /**
@@ -2118,4 +2497,4 @@ declare class TimeoutError extends DakeraError {
     constructor(message: string);
 }
 
-export { type AccessPatternHint, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type AutoPilotConfig, type AutoPilotConfigRequest, type AutoPilotConfigResponse, type AutoPilotConsolidationResult, type AutoPilotDedupResult, type AutoPilotStatusResponse, type AutoPilotTriggerAction, type AutoPilotTriggerResponse, type BackupInfo, type BatchForgetRequest, type BatchForgetResponse, type BatchMemoryFilter, type BatchQuerySpec, type BatchRecallRequest, type BatchRecallResponse, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type ConsolidationResultSnapshot, type CreateKeyRequest, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DecayConfigResponse, type DecayConfigUpdateRequest, type DecayConfigUpdateResponse, type DecayStatsResponse, type DedupResultSnapshot, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EmbeddingModel, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LastDecayCycleStats, type LatencyAnalytics, type ListSessionsOptions, type Memory, type MemoryEvent, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryId, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, NotFoundError, type OpStatus, type OperationProgressEvent, type OpsStats, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type RateLimitHeaders, type ReadConsistency, type RecallRequest, type RecalledMemory, type RetryConfig, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };
+export { type AccessPatternHint, type AgentFeedbackSummary, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type AutoPilotConfig, type AutoPilotConfigRequest, type AutoPilotConfigResponse, type AutoPilotConsolidationResult, type AutoPilotDedupResult, type AutoPilotStatusResponse, type AutoPilotTriggerAction, type AutoPilotTriggerResponse, type BackupInfo, type BatchForgetRequest, type BatchForgetResponse, type BatchMemoryFilter, type BatchQuerySpec, type BatchRecallRequest, type BatchRecallResponse, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type ConsolidationResultSnapshot, type CreateKeyRequest, type CreateNamespaceKeyResponse, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DecayConfigResponse, type DecayConfigUpdateRequest, type DecayConfigUpdateResponse, type DecayStatsResponse, type DedupResultSnapshot, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EdgeType, type EmbeddingModel, type EntityExtractionResponse, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type ExtractedEntity, type FeedbackHealthResponse, type FeedbackHistoryEntry, type FeedbackHistoryResponse, type FeedbackResponse, type FeedbackSignal, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type GraphEdge, type GraphExport, type GraphLinkResponse, type GraphNode, type GraphPath, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LastDecayCycleStats, type LatencyAnalytics, type ListNamespaceKeysResponse, type ListSessionsOptions, type Memory, type MemoryEntitiesResponse, type MemoryEvent, type MemoryFeedbackBodyRequest, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryGraph, type MemoryGraphOptions, type MemoryId, type MemoryImportancePatchRequest, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, type NamespaceKeyInfo, type NamespaceKeyUsageResponse, type NamespaceNerConfig, NotFoundError, type OpStatus, type OperationProgressEvent, type OpsStats, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type RateLimitHeaders, type ReadConsistency, type RecallRequest, type RecalledMemory, type RetryConfig, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };