@pyxmate/memory 0.0.1-beta

package/dist/dashboard.d.ts

@@ -0,0 +1,216 @@
+import { MemoryType, MemoryEntry, MemoryStats, GraphRelationship, GraphNode } from '@pyx-memory/shared';
+import { MemoryClient } from '@pyx-memory/client';
+
+interface RawHealthResponse {
+    status: string;
+    uptime: number;
+    memoryStatus: string;
+    embeddingProvider: string;
+    version: string;
+    stats?: {
+        totalEntries: number;
+        vectorCount: number;
+        storageUsedBytes: number;
+    };
+}
+interface HealthData {
+    status: 'ok' | 'degraded' | 'unreachable';
+    uptime: number;
+    uptimeFormatted: string;
+    storageMB: number;
+    isHealthy: boolean;
+    embeddingProvider: string;
+    stats?: {
+        totalEntries: number;
+        vectorCount: number;
+        storageUsedBytes: number;
+    };
+}
+interface TypeDistribution {
+    counts: Record<string, number>;
+    percentages: Record<string, number>;
+    total: number;
+    dominant: string;
+}
+interface EntryFilters {
+    page?: number;
+    limit?: number;
+    type?: MemoryType;
+    agentId?: string;
+    query?: string;
+}
+interface PaginatedEntries {
+    entries: MemoryEntry[];
+    page: number;
+    limit: number;
+    totalCount: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+}
+interface ConsolidationLogEntry {
+    id: number;
+    runAt: string;
+    entriesProcessed: number;
+    entriesMerged: number;
+    entriesArchived: number;
+    durationMs: number;
+}
+interface ConsolidationAnalytics {
+    entries: ConsolidationLogEntry[];
+    totalRuns: number;
+    avgDurationMs: number;
+    avgEntriesProcessed: number;
+    avgEntriesMerged: number;
+    avgEntriesArchived: number;
+    lastRunAt: string | null;
+    consolidationTrend: 'increasing' | 'decreasing' | 'stable' | 'insufficient_data';
+}
+interface MemoryMetrics {
+    totalEntries: number;
+    vectorCount: number;
+    storageUsedBytes: number;
+    storageMB: number;
+    avgImportance: number;
+    staleCandidates: number;
+    graphNodeCount: number;
+    graphEdgeCount: number;
+}
+interface GraphVizNode {
+    id: string;
+    label: string;
+    type: string;
+    memoryCount: number;
+    degree: number;
+    properties: Record<string, unknown>;
+}
+interface GraphVizEdge {
+    id: string;
+    source: string;
+    target: string;
+    label: string;
+    weight: number;
+}
+interface GraphVizData {
+    nodes: GraphVizNode[];
+    edges: GraphVizEdge[];
+    nodeCount: number;
+    edgeCount: number;
+    nodeTypes: Record<string, number>;
+    edgeTypes: Record<string, number>;
+}
+interface GraphologyNode {
+    key: string;
+    attributes: {
+        label: string;
+        type: string;
+        memoryCount: number;
+        degree: number;
+        [key: string]: unknown;
+    };
+}
+interface GraphologyEdge {
+    key: string;
+    source: string;
+    target: string;
+    attributes: {
+        label: string;
+        weight: number;
+    };
+}
+interface GraphologyData {
+    nodes: GraphologyNode[];
+    edges: GraphologyEdge[];
+}
+interface D3ForceNode {
+    id: string;
+    label: string;
+    type: string;
+    memoryCount: number;
+    degree: number;
+}
+interface D3ForceLink {
+    source: string;
+    target: string;
+    label: string;
+    weight: number;
+}
+interface D3ForceData {
+    nodes: D3ForceNode[];
+    links: D3ForceLink[];
+}
+interface PollerOptions {
+    intervalMs: number;
+    immediate?: boolean;
+}
+interface PollerState<T> {
+    data: T | null;
+    error: Error | null;
+    isLoading: boolean;
+    lastUpdated: Date | null;
+}
+interface HookResult<T> {
+    data: T | null;
+    error: Error | null;
+    isLoading: boolean;
+    lastUpdated: Date | null;
+    refetch: () => void;
+}
+
+declare function analyzeConsolidationLog(entries: ConsolidationLogEntry[]): ConsolidationAnalytics;
+
+declare function formatUptime(seconds: number): string;
+declare function formatBytes(bytes: number): string;
+declare function enrichHealth(raw: RawHealthResponse): HealthData;
+declare function unreachableHealth(_error?: Error): HealthData;
+
+declare function computeMetrics(stats: MemoryStats, entries: MemoryEntry[]): MemoryMetrics;
+
+declare function computeTypeDistribution(entries: MemoryEntry[]): TypeDistribution;
+
+declare class DashboardClient extends MemoryClient {
+    consolidationLog(limit?: number): Promise<ConsolidationLogEntry[]>;
+    listEntriesPaginated(filters?: EntryFilters): Promise<PaginatedEntries>;
+    graphRelationships(limit?: number): Promise<{
+        relationships: GraphRelationship[];
+        totalCount: number;
+    }>;
+    graphFull(limit?: number): Promise<{
+        nodes: GraphNode[];
+        relationships: GraphRelationship[];
+    }>;
+    fetchHealthRaw(): Promise<RawHealthResponse>;
+}
+
+interface TransformOptions {
+    minWeight?: number;
+    maxNodes?: number;
+}
+declare function transformGraphData(nodes: GraphNode[], relationships: GraphRelationship[], opts?: TransformOptions): GraphVizData;
+
+declare function toGraphologyFormat(data: GraphVizData): GraphologyData;
+declare function toD3ForceFormat(data: GraphVizData): D3ForceData;
+
+type Listener<T> = (state: PollerState<T>) => void;
+type ErrorListener = (error: Error) => void;
+declare class Poller<T> {
+    private fetcher;
+    private options;
+    private timer;
+    private state;
+    private updateListeners;
+    private errorListeners;
+    constructor(fetcher: () => Promise<T>, options: PollerOptions);
+    on(event: 'update', listener: Listener<T>): this;
+    on(event: 'error', listener: ErrorListener): this;
+    off(event: 'update', listener: Listener<T>): this;
+    off(event: 'error', listener: ErrorListener): this;
+    start(): Promise<void>;
+    stop(): void;
+    getState(): PollerState<T>;
+    isRunning(): boolean;
+    poll(): Promise<void>;
+    private emit;
+}
+
+export { type ConsolidationAnalytics, type ConsolidationLogEntry, type D3ForceData, type D3ForceLink, type D3ForceNode, DashboardClient, type EntryFilters, type GraphVizData, type GraphVizEdge, type GraphVizNode, type GraphologyData, type GraphologyEdge, type GraphologyNode, type HealthData, type HookResult, type MemoryMetrics, type PaginatedEntries, Poller, type PollerOptions, type PollerState, type RawHealthResponse, type TransformOptions, type TypeDistribution, analyzeConsolidationLog, computeMetrics, computeTypeDistribution, enrichHealth, formatBytes, formatUptime, toD3ForceFormat, toGraphologyFormat, transformGraphData, unreachableHealth };

package/dist/dashboard.mjs

@@ -0,0 +1,29 @@
+import {
+  DashboardClient,
+  Poller,
+  analyzeConsolidationLog,
+  computeMetrics,
+  computeTypeDistribution,
+  enrichHealth,
+  formatBytes,
+  formatUptime,
+  toD3ForceFormat,
+  toGraphologyFormat,
+  transformGraphData,
+  unreachableHealth
+} from "./chunk-EDIYGMT2.mjs";
+import "./chunk-Q4QIILKH.mjs";
+export {
+  DashboardClient,
+  Poller,
+  analyzeConsolidationLog,
+  computeMetrics,
+  computeTypeDistribution,
+  enrichHealth,
+  formatBytes,
+  formatUptime,
+  toD3ForceFormat,
+  toGraphologyFormat,
+  transformGraphData,
+  unreachableHealth
+};

package/dist/index.d.ts

@@ -0,0 +1,270 @@
+import { MemoryEntry as MemoryEntry$1, MemorySearchParams as MemorySearchParams$1, MemorySearchResult as MemorySearchResult$1, MemoryType as MemoryType$1, MemoryStats as MemoryStats$1, GraphNode as GraphNode$1, GraphTraversalResult as GraphTraversalResult$1 } from '@pyx-memory/shared';
+
+/** Parameters for paginated entry listing. */
+interface MemoryListParams {
+    /** 1-based page number. Default: 1 */
+    page?: number;
+    /** Entries per page (1–100). Default: 20 */
+    limit?: number;
+    /** Filter by memory type. */
+    type?: MemoryType$1;
+    /** Filter by agent ID. */
+    agentId?: string;
+}
+/** Result of a paginated entry listing. */
+interface MemoryListResult {
+    entries: MemoryEntry$1[];
+    totalCount: number;
+    page: number;
+    limit: number;
+}
+/** Abstract interface for memory systems (local or remote). */
+interface MemoryInterface {
+    initialize(): Promise<void>;
+    store(entry: Omit<MemoryEntry$1, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): Promise<MemoryEntry$1>;
+    search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
+    /** List entries with SQL LIMIT/OFFSET pagination. */
+    list(params?: MemoryListParams): Promise<MemoryListResult>;
+    get(id: string): Promise<MemoryEntry$1 | null>;
+    delete(id: string): Promise<boolean>;
+    clearSession(sessionId: string): Promise<number>;
+    stats(): Promise<MemoryStats$1>;
+    shutdown(): Promise<void>;
+}
+/** Consolidation run result. */
+interface ConsolidationRunResult {
+    entriesProcessed: number;
+    entriesMerged: number;
+    entriesArchived: number;
+    durationMs: number;
+}
+/** Extended interface with lifecycle operations. Non-breaking for existing consumers. */
+interface ExtendedMemoryInterface extends MemoryInterface {
+    /** Run consolidation: score, dedup, decay, and summarize memories. */
+    consolidate(): Promise<ConsolidationRunResult>;
+    /** Soft-delete a memory with a reason (marks as archived). */
+    forget(id: string, reason?: string): Promise<boolean>;
+    /** Summarize a session's memories into a long-term entry. */
+    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
+    /** Run decay on all entries, archiving those below threshold. */
+    runDecay(): Promise<number>;
+    /** Reindex the FTS5 full-text search index. */
+    reindex(): Promise<void>;
+    /** Delete all entries matching a source, cleaning up all stores. */
+    deleteBySource(source: string): Promise<number>;
+}
+
+interface IngestionResult {
+    filename: string;
+    chunks: number;
+    totalCharacters: number;
+}
+
+/** Error thrown by MemoryClient when the server returns a non-success response. */
+declare class MemoryServerError extends Error {
+    readonly status: number;
+    constructor(message: string, status: number);
+    /** True when the server returned HTTP 404 (not found). */
+    get isNotFound(): boolean;
+}
+declare class MemoryClient implements ExtendedMemoryInterface {
+    protected baseUrl: string;
+    constructor(memoryUrl: string);
+    /** Encode a path segment to prevent URL injection */
+    private encodePathSegment;
+    initialize(): Promise<void>;
+    store(entry: Omit<MemoryEntry$1, 'id' | 'createdAt'> & {
+        id?: string;
+        createdAt?: string;
+    }): Promise<MemoryEntry$1>;
+    search(params: MemorySearchParams$1): Promise<MemorySearchResult$1>;
+    get(id: string): Promise<MemoryEntry$1 | null>;
+    delete(id: string): Promise<boolean>;
+    clearSession(sessionId: string): Promise<number>;
+    stats(): Promise<MemoryStats$1>;
+    shutdown(): Promise<void>;
+    list(params?: MemoryListParams): Promise<MemoryListResult>;
+    ingestFile(file: File): Promise<IngestionResult>;
+    /** @deprecated Use {@link list} instead. Kept for backwards compatibility. */
+    listEntries(params?: {
+        page?: number;
+        limit?: number;
+    }): Promise<MemoryEntry$1[]>;
+    graphNodes(): Promise<GraphNode$1[]>;
+    graphEdges(): Promise<{
+        stats: {
+            nodeCount: number;
+            edgeCount: number;
+        };
+    }>;
+    graphQuery(query: {
+        nodeId: string;
+        depth?: number;
+    }): Promise<GraphTraversalResult$1>;
+    consolidate(): Promise<ConsolidationRunResult>;
+    forget(id: string, reason?: string): Promise<boolean>;
+    summarizeSession(sessionId: string): Promise<MemoryEntry$1 | null>;
+    runDecay(): Promise<number>;
+    reindex(): Promise<void>;
+    deleteBySource(source: string): Promise<number>;
+    protected fetchApi<T>(path: string, options?: RequestInit): Promise<T>;
+}
+
+declare const DEFAULTS: {
+    readonly DATA_DIR: "./data";
+    readonly VECTOR_PROVIDER: "lancedb";
+    readonly EMBEDDING_PROVIDER: "stub";
+    readonly MEMORY_SERVER_PORT: 7822;
+};
+
+interface ApiResponse<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+
+/** ISO 8601 timestamp string */
+type Timestamp = string;
+/** Unique agent identifier */
+type AgentId = string;
+
+declare const MemoryType: {
+    readonly SHORT_TERM: "short-term";
+    readonly LONG_TERM: "long-term";
+    readonly WORKING: "working";
+    readonly EPISODIC: "episodic";
+    readonly SUMMARY: "summary";
+};
+type MemoryType = (typeof MemoryType)[keyof typeof MemoryType];
+declare const RAGStrategy: {
+    readonly NAIVE: "naive";
+    readonly GRAPH: "graph";
+    readonly AGENTIC: "agentic";
+    readonly HYBRID: "hybrid";
+};
+type RAGStrategy = (typeof RAGStrategy)[keyof typeof RAGStrategy];
+declare const VectorProvider: {
+    readonly LANCEDB: "lancedb";
+    readonly QDRANT: "qdrant";
+};
+type VectorProvider = (typeof VectorProvider)[keyof typeof VectorProvider];
+declare const EmbeddingProviderName: {
+    readonly STUB: "stub";
+    readonly ANTHROPIC: "anthropic";
+    readonly OPENAI: "openai";
+    readonly LOCAL: "local";
+};
+type EmbeddingProviderName = (typeof EmbeddingProviderName)[keyof typeof EmbeddingProviderName];
+interface MemoryEntry {
+    id: string;
+    content: string;
+    type: MemoryType;
+    agentId?: AgentId;
+    sessionId?: string;
+    metadata: Record<string, unknown>;
+    embedding?: number[];
+    createdAt: Timestamp;
+    /** SHA-256 hash of content for deduplication. */
+    contentHash?: string;
+    /** Importance score (1-10). */
+    importance?: number;
+    /** Number of times this entry has been accessed via search. */
+    accessCount?: number;
+    /** ISO timestamp of last access via search. */
+    lastAccessed?: string;
+    /** Parent entry ID for hierarchical storage (e.g., doc → section → chunk). */
+    parentId?: string;
+    /** Source identifier (e.g., filename, URL, session). */
+    source?: string;
+    /** When the event described by this memory occurred. */
+    eventTime?: string;
+    /** When this entry was ingested into the system. */
+    ingestTime?: string;
+}
+interface SearchFilters {
+    /** Filter by source identifier. */
+    source?: string;
+    /** Minimum importance score. */
+    importanceMin?: number;
+    /** Event time range [start, end] as ISO timestamps. */
+    eventTimeRange?: [string, string];
+    /** Filter by parent entry ID. */
+    parentId?: string;
+    /** Filter by content type in metadata. */
+    contentType?: string;
+}
+interface MemorySearchParams {
+    query: string;
+    type?: MemoryType;
+    agentId?: AgentId;
+    limit?: number;
+    strategy?: RAGStrategy;
+    /** Extended filters for Phase 1+ features. */
+    filters?: SearchFilters;
+    /** Enable Hypothetical Document Embedding for query expansion. */
+    enableHyDE?: boolean;
+    /** Enable reranking of results. */
+    enableRerank?: boolean;
+}
+interface MemorySearchResult {
+    entries: MemoryEntry[];
+    totalCount: number;
+    strategy: RAGStrategy;
+    /** Optional scored entries with relevance scores for ranked results. */
+    scoredEntries?: Array<{
+        entry: MemoryEntry;
+        score: number;
+    }>;
+}
+interface MemoryIngestRequest {
+    content?: string;
+    type?: MemoryType;
+    fileType?: 'pdf' | 'csv' | 'txt';
+    metadata?: Record<string, unknown>;
+}
+interface MemoryStats {
+    totalEntries: number;
+    storageUsedBytes: number;
+    vectorCount: number;
+    recentAccessCount: number;
+    graphNodeCount?: number;
+    graphEdgeCount?: number;
+    /** Whether the memory service is connected. False when using DisabledMemory. */
+    connected?: boolean;
+}
+interface GraphEdge {
+    id: string;
+    sourceEntity: string;
+    targetEntity: string;
+    relation: string;
+    weight: number;
+    memoryEntryId: string;
+}
+interface GraphNode {
+    id: string;
+    name: string;
+    type: string;
+    properties: Record<string, unknown>;
+    memoryEntryIds: string[];
+}
+interface GraphRelationship {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    type: string;
+    properties: Record<string, unknown>;
+    memoryEntryId?: string;
+}
+interface GraphTraversalResult {
+    nodes: GraphNode[];
+    relationships: GraphRelationship[];
+    paths: Array<{
+        nodeIds: string[];
+        relationshipIds: string[];
+    }>;
+}
+
+export { type AgentId, type ApiResponse, type ConsolidationRunResult, DEFAULTS, EmbeddingProviderName, type ExtendedMemoryInterface, type GraphEdge, type GraphNode, type GraphRelationship, type GraphTraversalResult, type IngestionResult, MemoryClient, type MemoryEntry, type MemoryIngestRequest, type MemoryInterface, type MemoryListParams, type MemoryListResult, type MemorySearchParams, type MemorySearchResult, MemoryServerError, type MemoryStats, MemoryType, RAGStrategy, type SearchFilters, type Timestamp, VectorProvider };

package/dist/index.mjs

@@ -0,0 +1,46 @@
+import {
+  MemoryClient,
+  MemoryServerError
+} from "./chunk-Q4QIILKH.mjs";
+
+// ../shared/src/constants/defaults.ts
+var DEFAULTS = {
+  DATA_DIR: "./data",
+  VECTOR_PROVIDER: "lancedb",
+  EMBEDDING_PROVIDER: "stub",
+  MEMORY_SERVER_PORT: 7822
+};
+
+// ../shared/src/types/memory.ts
+var MemoryType = {
+  SHORT_TERM: "short-term",
+  LONG_TERM: "long-term",
+  WORKING: "working",
+  EPISODIC: "episodic",
+  SUMMARY: "summary"
+};
+var RAGStrategy = {
+  NAIVE: "naive",
+  GRAPH: "graph",
+  AGENTIC: "agentic",
+  HYBRID: "hybrid"
+};
+var VectorProvider = {
+  LANCEDB: "lancedb",
+  QDRANT: "qdrant"
+};
+var EmbeddingProviderName = {
+  STUB: "stub",
+  ANTHROPIC: "anthropic",
+  OPENAI: "openai",
+  LOCAL: "local"
+};
+export {
+  DEFAULTS,
+  EmbeddingProviderName,
+  MemoryClient,
+  MemoryServerError,
+  MemoryType,
+  RAGStrategy,
+  VectorProvider
+};

package/dist/react.d.ts

@@ -0,0 +1,28 @@
+import { HookResult, ConsolidationAnalytics, TransformOptions, GraphVizData, EntryFilters, PaginatedEntries, HealthData, TypeDistribution } from './dashboard.js';
+export { ConsolidationLogEntry, D3ForceData, D3ForceLink, D3ForceNode, DashboardClient, GraphVizEdge, GraphVizNode, GraphologyData, GraphologyEdge, GraphologyNode, MemoryMetrics, Poller, PollerOptions, PollerState, RawHealthResponse, analyzeConsolidationLog, computeMetrics, computeTypeDistribution, enrichHealth, formatBytes, formatUptime, toD3ForceFormat, toGraphologyFormat, transformGraphData, unreachableHealth } from './dashboard.js';
+import { MemoryStats } from '@pyx-memory/shared';
+import '@pyx-memory/client';
+
+declare function useConsolidationLog(serverUrl: string, limit?: number, intervalMs?: number): HookResult<ConsolidationAnalytics>;
+
+interface UseKnowledgeGraphOptions extends TransformOptions {
+    intervalMs?: number;
+    limit?: number;
+}
+declare function useKnowledgeGraph(serverUrl: string, opts?: UseKnowledgeGraphOptions): HookResult<GraphVizData>;
+
+declare function useMemoryEntries(serverUrl: string, filters?: EntryFilters, intervalMs?: number): HookResult<PaginatedEntries>;
+
+declare function useMemoryHealth(serverUrl: string, intervalMs?: number): HookResult<HealthData>;
+
+declare function useMemoryStats(serverUrl: string, intervalMs?: number): HookResult<MemoryStats>;
+
+interface UsePollingOptions {
+    intervalMs: number;
+    enabled?: boolean;
+}
+declare function usePolling<T>(fetcher: () => Promise<T>, options: UsePollingOptions): HookResult<T>;
+
+declare function useTypeDistribution(serverUrl: string, intervalMs?: number): HookResult<TypeDistribution>;
+
+export { ConsolidationAnalytics, EntryFilters, GraphVizData, HealthData, HookResult, PaginatedEntries, TransformOptions, TypeDistribution, type UseKnowledgeGraphOptions, type UsePollingOptions, useConsolidationLog, useKnowledgeGraph, useMemoryEntries, useMemoryHealth, useMemoryStats, usePolling, useTypeDistribution };