@monoes/memory 1.0.0

package/dist/query-builder.js

@@ -0,0 +1,134 @@
+/**
+ * Fluent builder for MemoryQuery objects.
+ *
+ * @example
+ * const q = query()
+ *   .semantic('authentication patterns')
+ *   .inNamespace('security')
+ *   .withTags(['critical'])
+ *   .threshold(0.8)
+ *   .limit(10)
+ *   .build();
+ */
+export class QueryBuilder {
+    _type = 'hybrid';
+    _content;
+    _namespace;
+    _tags;
+    _limit = 10;
+    _offset;
+    _threshold;
+    _sortField;
+    _sortDirection;
+    semantic(content) {
+        this._type = 'semantic';
+        this._content = content;
+        return this;
+    }
+    exact(key) {
+        this._type = 'exact';
+        this._content = key;
+        return this;
+    }
+    hybrid(content) {
+        this._type = 'hybrid';
+        this._content = content;
+        return this;
+    }
+    inNamespace(namespace) {
+        this._namespace = namespace;
+        return this;
+    }
+    withTags(tags) {
+        this._tags = tags;
+        return this;
+    }
+    limit(n) {
+        this._limit = n;
+        return this;
+    }
+    offset(n) {
+        this._offset = n;
+        return this;
+    }
+    threshold(t) {
+        this._threshold = t;
+        return this;
+    }
+    sortBy(field, direction = 'desc') {
+        this._sortField = field;
+        // Only store direction when it differs from the default ('desc')
+        this._sortDirection = direction === 'desc' ? undefined : direction;
+        return this;
+    }
+    newestFirst() { return this.sortBy('createdAt', 'desc'); }
+    oldestFirst() { return this.sortBy('createdAt', 'asc'); }
+    recentlyAccessed() { return this.sortBy('lastAccessedAt', 'desc'); }
+    mostAccessed() { return this.sortBy('accessCount', 'desc'); }
+    reset() {
+        this._type = 'hybrid';
+        this._content = undefined;
+        this._namespace = undefined;
+        this._tags = undefined;
+        this._limit = 10;
+        this._offset = undefined;
+        this._threshold = undefined;
+        this._sortField = undefined;
+        this._sortDirection = undefined;
+        return this;
+    }
+    clone() {
+        const b = new QueryBuilder();
+        b._type = this._type;
+        b._content = this._content;
+        b._namespace = this._namespace;
+        b._tags = this._tags ? [...this._tags] : undefined;
+        b._limit = this._limit;
+        b._offset = this._offset;
+        b._threshold = this._threshold;
+        b._sortField = this._sortField;
+        b._sortDirection = this._sortDirection;
+        return b;
+    }
+    build() {
+        const q = {
+            type: this._type,
+            limit: this._limit,
+        };
+        if (this._content !== undefined)
+            q.content = this._content;
+        if (this._namespace !== undefined)
+            q.namespace = this._namespace;
+        if (this._tags !== undefined)
+            q.tags = this._tags;
+        if (this._offset !== undefined)
+            q.offset = this._offset;
+        if (this._threshold !== undefined)
+            q.threshold = this._threshold;
+        if (this._sortField !== undefined)
+            q.sortField = this._sortField;
+        if (this._sortDirection !== undefined)
+            q.sortDirection = this._sortDirection;
+        return q;
+    }
+}
+/** Factory shorthand: `query().semantic('...').build()` */
+export function query() {
+    return new QueryBuilder();
+}
+/** Pre-built common query patterns */
+export const QueryTemplates = {
+    recentInNamespace(namespace, limit = 10) {
+        return query().hybrid('').inNamespace(namespace).limit(limit).newestFirst().build();
+    },
+    byTags(tags, limit = 10) {
+        return query().hybrid('').withTags(tags).limit(limit).build();
+    },
+    semanticSearch(content, limit = 10, threshold = 0.7) {
+        return query().semantic(content).limit(limit).threshold(threshold).build();
+    },
+    exactKey(namespace, key) {
+        return { type: 'exact', key, namespace, limit: 1 };
+    },
+};
+//# sourceMappingURL=query-builder.js.map

package/dist/query-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.js","sourceRoot":"","sources":["../src/query-builder.ts"],"names":[],"mappings":"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"}

package/dist/rvf-backend.d.ts

@@ -0,0 +1,51 @@
+import type { IMemoryBackend, MemoryEntry, MemoryEntryUpdate, MemoryQuery, SearchOptions, SearchResult, BackendStats, HealthCheckResult } from './types.js';
+export interface RvfBackendConfig {
+    databasePath: string;
+    dimensions?: number;
+    metric?: 'cosine' | 'euclidean' | 'dot';
+    quantization?: 'fp32' | 'fp16' | 'int8';
+    hnswM?: number;
+    hnswEfConstruction?: number;
+    maxElements?: number;
+    verbose?: boolean;
+    defaultNamespace?: string;
+    autoPersistInterval?: number;
+}
+export declare class RvfBackend implements IMemoryBackend {
+    private entries;
+    private keyIndex;
+    private hnswIndex;
+    private nativeDb;
+    private config;
+    private initialized;
+    private dirty;
+    private persisting;
+    private persistTimer;
+    private queryTimes;
+    private searchTimes;
+    constructor(config: RvfBackendConfig);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    store(entry: MemoryEntry): Promise<void>;
+    get(id: string): Promise<MemoryEntry | null>;
+    getByKey(namespace: string, key: string): Promise<MemoryEntry | null>;
+    update(id: string, updateData: MemoryEntryUpdate): Promise<MemoryEntry | null>;
+    delete(id: string): Promise<boolean>;
+    query(q: MemoryQuery): Promise<MemoryEntry[]>;
+    search(embedding: Float32Array, options: SearchOptions): Promise<SearchResult[]>;
+    bulkInsert(entries: MemoryEntry[]): Promise<void>;
+    bulkDelete(ids: string[]): Promise<number>;
+    count(namespace?: string): Promise<number>;
+    listNamespaces(): Promise<string[]>;
+    clearNamespace(namespace: string): Promise<number>;
+    getStats(): Promise<BackendStats>;
+    healthCheck(): Promise<HealthCheckResult>;
+    private tryNativeInit;
+    private compositeKey;
+    private bruteForceSearch;
+    private recordTiming;
+    private avg;
+    private loadFromDisk;
+    private persistToDisk;
+}
+//# sourceMappingURL=rvf-backend.d.ts.map

package/dist/rvf-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvf-backend.d.ts","sourceRoot":"","sources":["../src/rvf-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EACX,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,iBAAiB,EAElB,MAAM,YAAY,CAAC;AAWpB,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,QAAQ,GAAG,WAAW,GAAG,KAAK,CAAC;IACxC,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAqBD,qBAAa,UAAW,YAAW,cAAc;IAC/C,OAAO,CAAC,OAAO,CAAkC;IACjD,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,SAAS,CAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,UAAU,CAAgB;IAClC,OAAO,CAAC,WAAW,CAAgB;gBAEvB,MAAM,EAAE,gBAAgB;IAoB9B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IA4B3B,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAuBzB,KAAK,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAWxC,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAQ5C,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAMrE,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAe9E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAUpC,KAAK,CAAC,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAkD7C,MAAM,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAwBhF,UAAU,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IASjD,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAe1C,KAAK,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAS1C,cAAc,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAMnC,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAelD,QAAQ,IAAI,OAAO,CAAC,YAAY,CAAC;IA+BjC,WAAW,IAAI,OAAO,CAAC,iBAAiB,CAAC;YA2BjC,aAAa;IAyB3B,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,GAAG;YAIG,YAAY;YAiDZ,aAAa;CAyD5B"}