@wrongstack/vector-memory 0.308.0 → 0.308.1

package/README.md

@@ -12,6 +12,69 @@ stores cannot contend on the same file lock. A built-in `syncFromSage`
 bridge indexes active SAGE memories into the vector store, giving
 semantic search over your existing knowledge.
 
+## Parallel operation with SAGE
+
+`wrapMemoryPortWithVectorRecall(port, { store })` returns a new
+`MemoryPort` whose `searchSage` calls automatically fuse lexical and
+semantic recall via Reciprocal Rank Fusion. Hosts that opt in get
+**vector-augmented retrieval without changing any caller code** — the
+tool-call middleware, the turn middleware, and the surface/retrieval
+capabilities all see the same `searchSage(query, options)` shape.
+
+```ts
+import {
+  VectorMemoryStore,
+  TransformersEmbeddingProvider,
+  wrapMemoryPortWithVectorRecall,
+} from '@wrongstack/vector-memory';
+
+const vectorStore = new VectorMemoryStore({
+  provider: new TransformersEmbeddingProvider({ cacheDir }),
+  projectRoot,
+});
+
+const augmentedPort = wrapMemoryPortWithVectorRecall(sagePort, {
+  store: vectorStore,
+  weight: 0.3, // default; mirrors SAGE's hybridRerankMemories baseline
+});
+
+// Every downstream searchSage(query, options) now does
+//   lexical candidates + vector hits → RRF → fused result list
+const hits = await augmentedPort
+  .getCapability(SAGE_RETRIEVAL_CAPABILITY)!
+  .searchSage('quantum entanglement', { limit: 10 });
+```
+
+The wrapper is fail-open: a thrown error from the vector backend
+(offline model, missing dependency) falls back to the lexical list
+unchanged. The vector channel only **re-orders and boosts** — it does
+not inject foreign memories, because vector hits that map to SAGE
+memories not present in the lexical list are dropped (no Sage object to
+materialize).
+
+## Embedding result cache
+
+A provider-level cache keyed by `(content_hash, provider_id, dimensions)`
+skips the ONNX forward pass for repeated text. Both `remember()` and
+`search()` use the same cache, so the second embedding of an identical
+text costs only a SQLite lookup. Hosts that want to bound cache growth
+can call `store.evictCache(keepMostRecent)` for an LRU sweep.
+
+```ts
+const stats = store.cacheStats();
+// { entries: 142, providers: 1, totalUseCount: 1834, oldestLastUsedAt: '...' }
+```
+
+## Cross-process safety
+
+Mutating operations (`remember`, `forget`, `reindexAll`, `syncFromSage`,
+`evictCache`) are wrapped in a host-OS file lock. Two processes pointing
+at the same `.wrongstack/vector-memory/vector-memory.db` cannot interleave
+a read-modify-write. `remember()` is also idempotent on `content_hash`:
+calling it twice with the same text returns the existing entry instead of
+inserting a duplicate (the `UNIQUE` index on `entries.content_hash` is
+the second line of defense).
+
 ## Installation
 
 `@huggingface/transformers` is listed as an **optional** dependency so

package/dist/index.d.ts

@@ -2,9 +2,15 @@
  * @wrongstack/vector-memory — public exports.
  */
 export { DEFAULT_VECTOR_DIMENSIONS, DEFAULT_VECTOR_DTYPE, DEFAULT_VECTOR_MODEL_ID, TransformersEmbeddingProvider, type TransformersEmbeddingProviderOptions, } from './transformers-provider.js';
-export { VECTOR_DIMENSIONS_KEY, VECTOR_PROVIDER_KEY, VECTOR_SCHEMA_VERSION, decodeVector, encodeVector, initVectorSchema, } from './schema.js';
+export { VECTOR_DIMENSIONS_KEY, VECTOR_PROVIDER_KEY, VECTOR_SCHEMA_VERSION, decodeVector, encodeVector, initVectorSchema, lookupEmbeddingCache, upsertEmbeddingCache, } from './schema.js';
 export { VectorMemoryStore, fallbackHashingProvider, type SageSyncSource, } from './store.js';
+export { createSageSurfaceSyncSource, type SageSurfaceSyncOptions, } from './sage-sync-source.js';
+export { SAGE_SYNC_MARKER_FILENAME, decideWhetherToSync, startFirstBootSageSync, type FirstBootSageSyncOptions, type FirstBootSageSyncResult, type SageSyncMarker, } from './sage-sync.js';
 export { createVectorMemoryTools } from './tools.js';
+export { asVectorRecallProvider, fuseWithVectorMemory, type SageFusionHit, type SageFusionOptions, } from './sage-fusion.js';
+export { wrapMemoryPortWithVectorRecall, type VectorPortWrappingOptions, } from './sage-port-wrapper.js';
+export { forgetStaleSageMirrors, subscribeVectorMemoryToSage, type VectorMemoryMirrorHandle, type VectorMemoryMirrorOptions, } from './sage-event-mirror.js';
+export { runSearchRace, type SearchRaceChannelHit, type SearchRaceOptions, type SearchRaceResult, } from './search-race.js';
 export type { SageSyncReport, VectorEntry, VectorEntryInput, VectorEntryWithVector, VectorKind, VectorMemoryStoreOptions, VectorScope, VectorSearchHit, VectorSearchOptions, VectorStoreStats, } from './types.js';
 export { VectorMemoryError, VectorMemoryProviderUnavailableError, } from './errors.js';
 //# sourceMappingURL=index.d.ts.map