@knowzai/local-store 0.1.0

package/dist/sync-engine.js

@@ -0,0 +1,342 @@
+import { supportsOutbox } from './types.js';
+import { contentHash } from './hash.js';
+function emptyReport() {
+    return { pulled: 0, pushed: 0, conflicts: [], skipped: 0 };
+}
+export class SyncEngine {
+    store;
+    client;
+    encryptor;
+    constructor(store, client, opts = {}) {
+        this.store = store;
+        this.client = client;
+        this.encryptor = opts.encryptor;
+    }
+    /**
+     * Iterate EVERY page of `knowledge.list` for a vault, invoking `onSummary`
+     * per remote item. Stops when the cumulative count reaches `total` OR a page
+     * returns fewer than `pageSize` items (defensive against a 0/undefined total),
+     * so the full remote set is always covered without an infinite loop.
+     */
+    async forEachRemote(opts, onSummary) {
+        const pageSize = opts.pageSize;
+        let page = 1;
+        let fetched = 0;
+        for (;;) {
+            const result = await this.client.knowledge.list({ vaultId: opts.vaultId, page, pageSize });
+            const items = result.items ?? [];
+            for (const summary of items)
+                await onSummary(summary);
+            fetched += items.length;
+            const total = result.total;
+            const reachedTotal = typeof total === 'number' && total >= 0 && fetched >= total;
+            if (items.length < pageSize || reachedTotal)
+                break;
+            page++;
+        }
+    }
+    /** Cloud → local. Upserts remote items; flags conflicts; skips unchanged. */
+    async pull(opts = {}) {
+        const report = emptyReport();
+        await this.forEachRemote({ vaultId: opts.vaultId, pageSize: opts.pageSize ?? 100 }, async (summary) => {
+            const detail = await this.client.knowledge.get(summary.id);
+            // Model-3: decrypt ciphertext fetched from the cloud into local plaintext.
+            let content = detail.content;
+            if (content && this.encryptor?.isEncrypted(content))
+                content = this.encryptor.decrypt(content);
+            const hash = contentHash(content, detail.title, detail.tags ?? []);
+            const local = await this.store.getItem(detail.id);
+            if (local && local.contentHash === hash && local.syncState === 'synced') {
+                report.skipped++;
+                return;
+            }
+            if (local &&
+                local.syncState === 'dirty' &&
+                local.remoteVersion != null &&
+                detail.version > local.remoteVersion) {
+                await this.store.upsertItem({ ...local, syncState: 'conflict' });
+                report.conflicts.push(detail.id);
+                return;
+            }
+            await this.store.upsertItem({
+                id: detail.id,
+                vaultId: detail.vaultId,
+                title: detail.title,
+                type: detail.type,
+                contentHash: hash,
+                content,
+                tags: detail.tags ?? [],
+                updatedAt: detail.updatedAt,
+                syncState: 'synced',
+                remoteVersion: detail.version,
+            });
+            report.pulled++;
+        });
+        return report;
+    }
+    /** Local dirty/new → cloud. Clears dirty + records remoteVersion. */
+    async push(opts = {}) {
+        const report = emptyReport();
+        const pending = [
+            ...(await this.store.listItems({ syncState: 'new', vaultId: opts.vaultId })),
+            ...(await this.store.listItems({ syncState: 'dirty', vaultId: opts.vaultId })),
+        ];
+        for (const it of pending) {
+            // Model-3: encrypt before the content leaves the machine.
+            const wire = it.content != null && this.encryptor ? this.encryptor.encrypt(it.content) : it.content;
+            if (it.remoteVersion == null) {
+                const created = await this.client.knowledge.create({
+                    vaultId: it.vaultId,
+                    title: it.title,
+                    content: wire,
+                    type: it.type,
+                    tags: it.tags,
+                });
+                if (created.id !== it.id)
+                    await this.store.reassignItemId(it.id, created.id);
+                await this.store.upsertItem({
+                    ...it,
+                    id: created.id,
+                    syncState: 'synced',
+                    remoteVersion: created.version,
+                    // hash the LOCAL plaintext (server echoes ciphertext under CMEK).
+                    contentHash: contentHash(it.content, it.title, it.tags),
+                });
+            }
+            else {
+                // F26 — precondition guard. The API can't yet supply a monotonic
+                // version on create/update (create() returns 0, update() falls back to
+                // 0), so version-based conflict detection on pull/recover is effectively
+                // dead. Re-fetch the remote before overwriting: if it advanced past the
+                // version this local copy last saw, mark a conflict instead of silently
+                // clobbering the concurrent remote edit.
+                if (it.remoteVersion != null) {
+                    const current = await this.client.knowledge.get(it.id);
+                    if (current.version > it.remoteVersion) {
+                        await this.store.upsertItem({ ...it, syncState: 'conflict' });
+                        report.conflicts.push(it.id);
+                        continue;
+                    }
+                }
+                const updated = await this.client.knowledge.update(it.id, {
+                    title: it.title,
+                    content: wire,
+                    tags: it.tags,
+                    vaultId: it.vaultId,
+                });
+                await this.store.upsertItem({
+                    ...it,
+                    syncState: 'synced',
+                    remoteVersion: updated.version,
+                    contentHash: contentHash(it.content, it.title, it.tags),
+                });
+            }
+            report.pushed++;
+        }
+        return report;
+    }
+    async run(opts = {}) {
+        const a = await this.pull(opts);
+        const b = await this.push(opts);
+        return {
+            pulled: a.pulled,
+            pushed: b.pushed,
+            conflicts: [...a.conflicts, ...b.conflicts],
+            skipped: a.skipped + b.skipped,
+        };
+    }
+    async status() {
+        const all = await this.store.listItems();
+        const by = (s) => all.filter((i) => i.syncState === s).length;
+        return {
+            total: all.length,
+            new: by('new'),
+            dirty: by('dirty'),
+            synced: by('synced'),
+            conflict: by('conflict'),
+            deleted: by('deleted'),
+        };
+    }
+    /** Items currently in conflict (local + remote both changed). */
+    async listConflicts() {
+        return this.store.listItems({ syncState: 'conflict' });
+    }
+    /** Resolve one conflicted item by keeping the remote copy or the local copy. */
+    async resolveConflict(id, strategy) {
+        const local = await this.store.getItem(id);
+        if (!local)
+            return 'not-found';
+        if (strategy === 'remote') {
+            const detail = await this.client.knowledge.get(id);
+            let content = detail.content;
+            if (content && this.encryptor?.isEncrypted(content))
+                content = this.encryptor.decrypt(content);
+            await this.store.upsertItem({
+                id: detail.id,
+                vaultId: detail.vaultId,
+                title: detail.title,
+                type: detail.type,
+                contentHash: contentHash(content, detail.title, detail.tags ?? []),
+                content,
+                tags: detail.tags ?? [],
+                updatedAt: detail.updatedAt,
+                syncState: 'synced',
+                remoteVersion: detail.version,
+            });
+            return 'updated-from-remote';
+        }
+        // keep local → mark dirty so the next push overwrites the remote (last-writer)
+        await this.store.upsertItem({ ...local, syncState: 'dirty' });
+        return 'kept-local';
+    }
+    /**
+     * Recovery: re-pull authoritative cloud state to repair the local store
+     * (overwrites non-dirty items, preserves dirty-vs-advanced as conflicts) and
+     * report any local `synced` items no longer present remotely (orphans).
+     */
+    async recover(opts = {}) {
+        const report = { repaired: 0, conflicts: [], orphanedLocal: [] };
+        // F3 — repair + collect remoteIds across ALL pages BEFORE the orphan sweep,
+        // else a local synced item that only lives on page 2+ is wrongly reported
+        // as orphaned.
+        const remoteIds = new Set();
+        await this.forEachRemote({ vaultId: opts.vaultId, pageSize: opts.pageSize ?? 200 }, async (summary) => {
+            remoteIds.add(summary.id);
+            const detail = await this.client.knowledge.get(summary.id);
+            let content = detail.content;
+            if (content && this.encryptor?.isEncrypted(content))
+                content = this.encryptor.decrypt(content);
+            const local = await this.store.getItem(detail.id);
+            if (local?.syncState === 'dirty' && local.remoteVersion != null && detail.version > local.remoteVersion) {
+                await this.store.upsertItem({ ...local, syncState: 'conflict' });
+                report.conflicts.push(detail.id);
+                return;
+            }
+            await this.store.upsertItem({
+                id: detail.id,
+                vaultId: detail.vaultId,
+                title: detail.title,
+                type: detail.type,
+                contentHash: contentHash(content, detail.title, detail.tags ?? []),
+                content,
+                tags: detail.tags ?? [],
+                updatedAt: detail.updatedAt,
+                syncState: 'synced',
+                remoteVersion: detail.version,
+            });
+            report.repaired++;
+        });
+        // orphan sweep only after the FULL remote set is known
+        for (const it of await this.store.listItems({ syncState: 'synced' })) {
+            if (!remoteIds.has(it.id))
+                report.orphanedLocal.push(it.id);
+        }
+        return report;
+    }
+    /**
+     * Drain the capture outbox to the cloud (FEAT_AgentMemoryLocalOutbox).
+     *
+     * Each claimed entry's sealed content lives in `items`; we create it via the
+     * existing `knowledge.create` path (the batch endpoint is not yet shipped),
+     * stamping the idempotency key into item metadata for best-effort server-side
+     * dedup. Idempotency is enforced LOCALLY: a `done` entry is never reclaimed,
+     * and re-enqueue is a no-op on the idempotency-key PK. The only double-create
+     * window is "create succeeded but its ack was lost before we marked done" —
+     * acceptable until the content-hash-dedup batch endpoint lands.
+     *
+     * Resilience: claims `pending` (whose backoff elapsed) plus `inflight` whose
+     * lease expired (crash recovery). Transient failures back off exponentially;
+     * after `maxAttempts` an entry dead-letters (visible via `outboxStats`). This
+     * is what makes the orphaned-pending-captures leak structurally impossible —
+     * a capture is a committed row drained by an idempotent, retrying consumer.
+     */
+    async flushOutbox(opts = {}) {
+        if (!supportsOutbox(this.store)) {
+            throw new Error('flushOutbox requires a store that supports the capture outbox (use the default SQLite store).');
+        }
+        const store = this.store;
+        const nowFn = opts.now ?? (() => Date.now());
+        const limit = opts.limit ?? 100;
+        const leaseMs = opts.leaseMs ?? 60_000;
+        const maxAttempts = opts.maxAttempts ?? 5;
+        const baseBackoff = opts.baseBackoffMs ?? 1_000;
+        const maxBackoff = opts.maxBackoffMs ?? 5 * 60_000;
+        const report = { claimed: 0, sent: 0, failed: 0, dead: 0, conflicts: [] };
+        const nowMs = nowFn();
+        const nowIso = new Date(nowMs).toISOString();
+        const leaseIso = new Date(nowMs + leaseMs).toISOString();
+        const claimed = await store.claimOutbox({ now: nowIso, leaseUntil: leaseIso, limit });
+        report.claimed = claimed.length;
+        for (const entry of claimed) {
+            const item = await this.store.getItem(entry.itemId);
+            if (!item) {
+                await store.updateOutbox(entry.idempotencyKey, {
+                    state: 'dead',
+                    attempts: entry.attempts + 1,
+                    lastAttemptAt: nowIso,
+                    lastError: 'orphaned: sealed item not found',
+                });
+                report.dead++;
+                continue;
+            }
+            try {
+                const wire = item.content != null && this.encryptor ? this.encryptor.encrypt(item.content) : item.content;
+                const created = await this.client.knowledge.create({
+                    vaultId: item.vaultId,
+                    title: item.title,
+                    content: wire,
+                    type: item.type,
+                    tags: item.tags,
+                    metadata: {
+                        'knowz-agent-key': entry.idempotencyKey,
+                        'knowz-agent-session': entry.sessionId,
+                        ...(opts.source ? { 'knowz-agent-source': opts.source } : {}),
+                    },
+                });
+                if (created.id !== item.id)
+                    await this.store.reassignItemId(item.id, created.id);
+                await this.store.upsertItem({
+                    ...item,
+                    id: created.id,
+                    syncState: 'synced',
+                    remoteVersion: created.version,
+                    contentHash: contentHash(item.content, item.title, item.tags),
+                });
+                await store.updateOutbox(entry.idempotencyKey, {
+                    state: 'done',
+                    attempts: entry.attempts + 1,
+                    lastAttemptAt: nowIso,
+                    lastError: undefined,
+                    itemId: created.id,
+                });
+                report.sent++;
+            }
+            catch (err) {
+                const attempts = entry.attempts + 1;
+                const msg = err instanceof Error ? err.message : String(err);
+                if (attempts >= maxAttempts) {
+                    await store.updateOutbox(entry.idempotencyKey, {
+                        state: 'dead',
+                        attempts,
+                        lastAttemptAt: nowIso,
+                        lastError: msg,
+                    });
+                    report.dead++;
+                }
+                else {
+                    const backoff = Math.min(maxBackoff, baseBackoff * 2 ** (attempts - 1));
+                    await store.updateOutbox(entry.idempotencyKey, {
+                        state: 'pending',
+                        attempts,
+                        lastAttemptAt: nowIso,
+                        lastError: msg,
+                        leaseUntil: new Date(nowMs + backoff).toISOString(),
+                    });
+                    report.failed++;
+                }
+            }
+        }
+        return report;
+    }
+}
+//# sourceMappingURL=sync-engine.js.map

package/dist/sync-engine.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,150 @@
+export type SyncState = 'new' | 'synced' | 'dirty' | 'conflict' | 'deleted';
+export interface LocalItem {
+    id: string;
+    vaultId?: string;
+    title: string;
+    type: string;
+    contentHash: string;
+    content?: string;
+    tags: string[];
+    updatedAt: string;
+    syncState: SyncState;
+    remoteVersion?: number;
+}
+export interface Chunk {
+    id: string;
+    itemId: string;
+    ordinal: number;
+    text: string;
+    startByte?: number;
+    endByte?: number;
+    lang?: string;
+}
+export interface FileState {
+    path: string;
+    hash: string;
+    mtimeMs: number;
+    size: number;
+    itemId?: string;
+    lastIndexedAt?: string;
+}
+export interface KnnHit {
+    chunk: Chunk;
+    distance: number;
+}
+export interface LocalStore {
+    readonly driver: 'sqlite' | 'postgres';
+    init(): Promise<void>;
+    upsertItem(item: LocalItem): Promise<void>;
+    getItem(id: string): Promise<LocalItem | undefined>;
+    reassignItemId(oldId: string, newId: string): Promise<void>;
+    listItems(filter?: {
+        vaultId?: string;
+        syncState?: SyncState;
+    }): Promise<LocalItem[]>;
+    deleteItem(id: string): Promise<void>;
+    putChunks(itemId: string, chunks: Chunk[], vectors?: Float32Array[]): Promise<void>;
+    knnSearch(queryVec: Float32Array, k: number, filter?: {
+        vaultId?: string;
+    }): Promise<KnnHit[]>;
+    setFileState(s: FileState): Promise<void>;
+    getFileState(path: string): Promise<FileState | undefined>;
+    listFileStates(): Promise<FileState[]>;
+    meta(): Promise<{
+        schemaVersion: number;
+        dim: number;
+        itemCount: number;
+        chunkCount: number;
+    }>;
+    close(): Promise<void>;
+}
+export interface OpenStoreOptions {
+    driver?: 'sqlite' | 'postgres';
+    dbPath?: string;
+    dsn?: string;
+    dim?: number;
+}
+export declare const SCHEMA_VERSION = 2;
+export declare const DEFAULT_DIM = 384;
+/**
+ * Map an L2 distance between L2-normalized vectors to a 0..1 cosine-similarity
+ * "relevance". For unit vectors L2² = 2(1 − cos), so cos = 1 − d²/2. Identical
+ * vectors → 1; orthogonal (d=√2) → 0. Use this for any "% match" display.
+ */
+export declare function relevanceFromDistance(distance: number): number;
+/** Lifecycle of a capture_outbox entry. `done`/`dead` are terminal. */
+export type OutboxState = 'pending' | 'inflight' | 'done' | 'dead' | 'conflict';
+/** A raw, already-redacted observation of one tool-use / agent event. */
+export interface Observation {
+    id: string;
+    sessionId: string;
+    /** ISO timestamp. */
+    ts: string;
+    /** Event kind, e.g. 'tool', 'prompt', 'precompact'. */
+    kind: string;
+    toolName?: string;
+    /** One-line, redaction-safe summary. Never raw secret-bearing payload. */
+    summary: string;
+    /** True once the source payload passed through the redactor. */
+    redacted: boolean;
+    vaultId?: string;
+    /** Set once this observation has been rolled into a sealed `items` row. */
+    sealedIntoItemId?: string;
+}
+/** Durable delivery record for one sealed observation item bound for the cloud. */
+export interface OutboxEntry {
+    /** sha256(sessionId:seq:contentHash) — stable PK, dedupes re-enqueue. */
+    idempotencyKey: string;
+    /** FK → items.id (the sealed observation content). */
+    itemId: string;
+    sessionId: string;
+    createdAt: string;
+    attempts: number;
+    lastAttemptAt?: string;
+    state: OutboxState;
+    lastError?: string;
+    /** ISO not-before: claim ignores entries leased into the future. */
+    leaseUntil?: string;
+}
+export interface OutboxStats {
+    pending: number;
+    inflight: number;
+    done: number;
+    dead: number;
+    conflict: number;
+}
+/**
+ * Capture/outbox surface, implemented by SqliteStore (the default local store).
+ * Kept separate from LocalStore so the Postgres driver is unaffected for now
+ * (agent-memory capture targets the default SQLite store; pg outbox is a
+ * follow-up). Use `supportsOutbox(store)` to narrow a LocalStore safely.
+ */
+export interface ObservationOutboxStore {
+    recordObservation(o: Observation): Promise<void>;
+    listObservations(filter?: {
+        sessionId?: string;
+        sealed?: boolean;
+    }): Promise<Observation[]>;
+    markObservationsSealed(ids: string[], itemId: string): Promise<void>;
+    /** Insert-or-ignore on idempotencyKey, so a re-enqueue is a no-op. */
+    enqueueOutbox(e: OutboxEntry): Promise<void>;
+    /**
+     * Atomically claim up to `limit` deliverable entries — `pending` whose lease
+     * has elapsed plus `inflight` whose lease expired (crash recovery) — flipping
+     * each to `inflight` with a fresh lease. Returns the claimed entries.
+     */
+    claimOutbox(opts: {
+        now: string;
+        leaseUntil: string;
+        limit: number;
+    }): Promise<OutboxEntry[]>;
+    updateOutbox(key: string, patch: Partial<Omit<OutboxEntry, 'idempotencyKey'>>): Promise<void>;
+    getOutbox(key: string): Promise<OutboxEntry | undefined>;
+    listOutbox(filter?: {
+        state?: OutboxState;
+    }): Promise<OutboxEntry[]>;
+    outboxStats(): Promise<OutboxStats>;
+}
+/** Runtime narrow: does this LocalStore also expose the capture/outbox surface? */
+export declare function supportsOutbox(store: unknown): store is LocalStore & ObservationOutboxStore;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,21 @@
+export const SCHEMA_VERSION = 2;
+// Local store holds LOCALLY-computed embeddings only (the local hashing
+// embedder, dim 384). Cloud (1536-dim) vectors are never stored here — synced
+// content is re-embedded locally for KNN. Keep this aligned with the indexer's
+// DEFAULT_EMBED_DIM so every command opens the store at the same dim.
+export const DEFAULT_DIM = 384;
+/**
+ * Map an L2 distance between L2-normalized vectors to a 0..1 cosine-similarity
+ * "relevance". For unit vectors L2² = 2(1 − cos), so cos = 1 − d²/2. Identical
+ * vectors → 1; orthogonal (d=√2) → 0. Use this for any "% match" display.
+ */
+export function relevanceFromDistance(distance) {
+    return Math.max(0, Math.min(1, 1 - (distance * distance) / 2));
+}
+/** Runtime narrow: does this LocalStore also expose the capture/outbox surface? */
+export function supportsOutbox(store) {
+    return (!!store &&
+        typeof store.claimOutbox === 'function' &&
+        typeof store.enqueueOutbox === 'function');
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AA+DA,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC;AAChC,wEAAwE;AACxE,8EAA8E;AAC9E,+EAA+E;AAC/E,sEAAsE;AACtE,MAAM,CAAC,MAAM,WAAW,GAAG,GAAG,CAAC;AAE/B;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,QAAgB;IACpD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACjE,CAAC;AA+ED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,CACL,CAAC,CAAC,KAAK;QACP,OAAQ,KAAgC,CAAC,WAAW,KAAK,UAAU;QACnE,OAAQ,KAAgC,CAAC,aAAa,KAAK,UAAU,CACtE,CAAC;AACJ,CAAC"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@knowzai/local-store",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^11.7.0",
+    "sqlite-vec": "^0.1.6",
+    "@knowzai/types": "0.1.0",
+    "@knowzai/api-client": "0.1.0"
+  },
+  "optionalDependencies": {
+    "pg": "^8.13.1"
+  },
+  "license": "MIT",
+  "author": "Knowz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/knowz-io/knowz-platform.git",
+    "directory": "cli/local-store"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -b"
+  }
+}