@melandlabs/memory-store 0.3.0 → 1.0.0

package/dist/index.d.ts

@@ -1,35 +1,250 @@
-import { M as MemoryStoreConfig } from './config-2Q092MUz.js';
-export { E as EmbedQueryFn, I as IterativeRecallCandidate, a as IterativeRecallExecutor, b as IterativeRecallPlanner, c as IterativeRecallPlannerOptions, d as IterativeRecallResult, e as IterativeRecallSearchRequest, f as IterativeRecallSearchResult, g as IterativeRecallStats, h as MemoryStoreDb, i as MemoryStoreEnv, Q as QueryRewriter, j as QueryRewriterInput, k as QueryRewriterOptions, U as UnifiedMemoryReasoningInfo, l as UnifiedMemoryReasoningStrategy, m as UnifiedMemorySearchInput, n as UnifiedMemorySearchOutput, o as UnifiedMemorySearchResult, p as UnifiedMemorySearchSource, q as UnifiedMemorySearchWarning, r as UnifiedSearchInsightsResult, s as UnifiedSearchKnowledgeResult, t as UnifiedSearchReasoningDeps, V as VectorBackend, u as clampUnifiedMemorySearchLimit, v as clampUnifiedMemorySearchThreshold, w as createIdentityIterativePlanner, x as createIdentityRewriter, y as createIterativeRecallPlanner, z as createUserVoiceRewriter, A as isRawMemorySemanticResult, B as mergeUnifiedMemorySearchResults, C as normalizeUnifiedMemoryReasoningStrategy, D as normalizeUnifiedMemorySearchSources, F as toKnowledgeResult, G as toMemoryResult } from './config-2Q092MUz.js';
-import { UnifiedSearch } from './search/unified-search.js';
-export { createUnifiedSearch } from './search/unified-search.js';
+import * as _melandlabs_memory_consolidation from '@melandlabs/memory-consolidation';
+import { OwnerScope } from '@melandlabs/memory-consolidation';
+import { d as SearchInput, e as SearchOutput, M as MemoryStoreConfig } from './config-CnbqSek5.js';
+export { E as EmbedQueryFn, I as IterativeRecallCandidate, x as IterativeRecallExecutor, y as IterativeRecallPlanner, z as IterativeRecallPlannerOptions, A as IterativeRecallResult, B as IterativeRecallSearchRequest, C as IterativeRecallSearchResult, D as IterativeRecallStats, F as MemoryStoreDb, a as MemoryStoreEnv, Q as QueryRewriter, G as QueryRewriterInput, H as QueryRewriterOptions, c as SearchEvidence, i as SearchSource, S as SearchTier, j as UnifiedMemoryMergeStrategy, k as UnifiedMemoryRankedList, J as UnifiedMemoryReasoningInfo, l as UnifiedMemoryReasoningStrategy, f as UnifiedMemorySearchInput, g as UnifiedMemorySearchOutput, h as UnifiedMemorySearchResult, m as UnifiedMemorySearchSource, b as UnifiedMemorySearchWarning, K as UnifiedSearchInsightsResult, L as UnifiedSearchKnowledgeResult, N as UnifiedSearchReasoningDeps, V as VectorBackend, n as clampUnifiedMemorySearchLimit, o as clampUnifiedMemorySearchThreshold, O as createIdentityIterativePlanner, P as createIdentityRewriter, R as createIterativeRecallPlanner, T as createUserVoiceRewriter, p as isRawMemorySemanticResult, q as mergeUnifiedMemorySearchResults, r as mergeUnifiedMemorySearchResultsRrf, t as normalizeUnifiedMemoryReasoningStrategy, u as normalizeUnifiedMemorySearchSources, v as toKnowledgeResult, w as toMemoryResult } from './config-CnbqSek5.js';
+import { U as UnifiedSearch, A as ApplyConsolidateInput, a as ApplyConsolidateOutput } from './unified-search-Bft57TRH.js';
+export { b as applyReflectedPlan, c as createUnifiedSearch } from './unified-search-Bft57TRH.js';
+import { StoreVsaFactInput, StoreVsaFactOutput, VsaRecallInput, VsaRecallOutput, VsaListInput, VsaFactSummary, VsaForgetInput, VsaForgetOutput, VsaFactStorage } from '@melandlabs/contracts';
+export { StoreVsaFactInput, StoreVsaFactOutput, VsaFact, VsaFactStorage, VsaFactSummary, VsaForgetInput, VsaForgetOutput, VsaListInput, VsaRecallInput, VsaRecallOutput, VsaRecallScore, VsaVocabularyEntry } from '@melandlabs/contracts';
 import { RawMessageStore, getRawMessageManager } from './storage/raw-message-store.js';
 export { RawMessageStorageBackend, RawMessageStorageManagerWithSearch, closeRawMessageStore, createRawMessageStore, getRawMessageStorageBackend, isRawMessageStorageAvailable } from './storage/raw-message-store.js';
 export { PostgresFactoryFn, PostgresRawMessageManagerLike, clearPostgresFactory, hasPostgresFactory, registerPostgresFactory, resolvePostgresFactory } from './storage/postgres-raw-message-factory.js';
+import { RawMessageGraphEvolutionStorage } from '@melandlabs/indexeddb';
+import { Peer } from '@melandlabs/contracts/peer';
+export { SQLiteVsaStore, SQLiteVsaStoreOptions, closeSQLiteVsaStore, getSQLiteVsaStore } from '@melandlabs/sqlite';
 export { RawMessage } from './contracts.js';
-import '@melandlabs/indexeddb/storage';
 import '@melandlabs/ai/memory';
 
 /**
- * @melandlabs/memory-store — SDK entry point.
+ * `@melandlabs/memory-store` — VSA (Vector Symbolic Architecture) facade.
  *
- * Wires up a top-level `MemoryStore` facade combining the raw message
- * manager, the unified search facade, and vector index helpers. Hosts
- * that want a non-web backend (CLI daemon, custom server) can use
- * this as the only entry point.
+ * Four verbs on top of any `VsaFactStorage` backend:
+ *
+ *   - `storeFact(input)` — persist a (role, filler) binding.
+ *   - `recall(input)`    — rebuild the memory vector from the user's
+ *                          facts, unbind by the requested role, and pick
+ *                          the best vocabulary entry.
+ *   - `listFacts(input)` — read-side projection of stored facts (no vectors).
+ *   - `forget(input)`    — soft-delete facts by id (idempotent).
+ *
+ * The facade intentionally does NOT route through `unified-search`. VSA
+ * recall semantics differ: a single best-match from a vocabulary, not
+ * top-K nearest neighbours. Folding both into one result set would require
+ * a confusing union type and a fake "similarity" field that doesn't mean
+ * the same thing across sources.
+ *
+ * Persistence shapes live in `@melandlabs/contracts/vsa-fact`. The HRR
+ * algebra (`bind` / `unbind` / `superpose` / `cleanup` / `cosineSimilarity`)
+ * is imported from `@melandlabs/vsa` — a leaf package with no runtime deps.
+ */
+
+interface VsaRecallFacade {
+    storeFact(input: StoreVsaFactInput): Promise<StoreVsaFactOutput>;
+    recall(input: VsaRecallInput): Promise<VsaRecallOutput>;
+    listFacts(input: VsaListInput): Promise<VsaFactSummary[]>;
+    forget(input: VsaForgetInput): Promise<VsaForgetOutput>;
+}
+declare function createVsaRecall(storage: VsaFactStorage): VsaRecallFacade;
+
+/**
+ * `attachMemoryGraphStore` — opt-in helper for hosts that want to wire
+ * a memory graph store onto an existing `MemoryStore` without going
+ * through `createMemoryStore({ graphStore })`.
+ *
+ * Usage:
+ * ```ts
+ * const store = await createMemoryStore();
+ * attachMemoryGraphStore(store, {
+ *   storage: indexedDbStorage,
+ *   ownerScope: { userId: "u-42" },
+ * });
+ * ```
+ *
+ * Returns the same `MemoryStore` reference for chaining. When
+ * `storage.compareAndSwapGraphLedger` is missing, no graph store is
+ * attached and a warning is emitted via the supplied logger — callers
+ * may still run `consolidate`, but it will skip `persistPlan` and
+ * emit a `reflect_apply_graph_store_not_configured` warning. The
+ * deprecation path through `storage.deprecateRecords` continues to
+ * work as long as a `MemoryStorageAdapter` is wired elsewhere.
  */
 
+interface AttachMemoryGraphStoreInput {
+    storage: RawMessageGraphEvolutionStorage;
+    ownerScope: OwnerScope;
+    botId?: string;
+    now?: () => number;
+    /**
+     * Optional logger; falls back to `console`. The helper does not log on
+     * the happy path; it only warns when `compareAndSwapGraphLedger` is
+     * missing on the storage.
+     */
+    logger?: Pick<Console, "warn">;
+}
+declare function attachMemoryGraphStore(store: MemoryStore, input: AttachMemoryGraphStoreInput): MemoryStore;
+
+/**
+ * Peer-centric profile + relationship facade.
+ *
+ * A higher-level pattern over `UnifiedSearch` that turns the underlying
+ * `search()` primitives into two question-shaped entry points a chat
+ * assistant can answer on demand:
+ *
+ *   - `getProfile(peer)`     — synthesises a peer profile from the
+ *     raw message tier (and any other tier the host enables).
+ *   - `getRelationships(peer)` — discovers other peers co-mentioned
+ *     with the target, confirms each via a pair-scoped
+ *     `search()` call, and ranks by co-mention count.
+ *
+ * The facade is purely additive: it composes existing primitives and
+ * never modifies `UnifiedSearch`. It assumes the host has already
+ * wired `UnifiedSearchDeps` (raw messages, summaries, insights,
+ * knowledge, peer-scope check, optional reranker, optional LLM).
+ *
+ * Host responsibilities:
+ *   - provide a `listKnownPeers()` callback so the facade can resolve
+ *     peer IDs to `Peer` records;
+ *   - optionally provide a `listPeerMentions()` callback so the
+ *     facade can enumerate co-mention candidates without scanning
+ *     every message.
+ */
+
+interface PeerPosting {
+    /** Stable identifier of the source posting (message ID, episode ID, ...). */
+    id: string;
+    /** ID of the peer who authored the posting. */
+    authorId: string;
+    /** IDs of peers mentioned in this posting (excludes the author). */
+    mentionedIds?: ReadonlyArray<string>;
+    /**
+     * Structured mentions (preferred over `mentionedIds`). Letting hosts pass
+     * full `Peer` records preserves `kind` (user vs agent) instead of
+     * collapsing every mention to a bare id that the resolver must guess at.
+     * Falls back to `mentionedIds` when omitted.
+     */
+    mentionedPeers?: ReadonlyArray<Peer>;
+}
+interface PeerProfileDeps {
+    /** Underlying unified-search facade (provides `search`; legacy `searchUnifiedMemory` is a deprecated alias). */
+    search: UnifiedSearch;
+    /** Workspace / tenant namespace used for all underlying searches. */
+    userId: string;
+    /**
+     * Resolve a peer ID to the canonical `Peer` record. The facade
+     * uses this to convert string IDs from `PeerPosting` into the
+     * `Peer` instances passed to `peerFilter`. May be omitted if the
+     * host already returns `Peer` from `listKnownPeers` and prefers
+     * the facade to derive IDs from `peer.id`.
+     */
+    resolvePeer?: (peerId: string) => Peer | undefined;
+    /**
+     * All known peers the facade can answer queries about. Required.
+     */
+    listKnownPeers: () => ReadonlyArray<Peer>;
+    /**
+     * Enumerate every peer→peer co-mention edge observed in the
+     * corpus. The facade uses these to discover relationship
+     * candidates before confirming each one via
+     * `search()`. May return an async iterable for
+     * large corpora.
+     */
+    listPeerMentions?: () => Promise<ReadonlyArray<PeerPosting>> | ReadonlyArray<PeerPosting>;
+    /**
+     * Minimum similarity for the profile synthesis search. Defaults to
+     * `DEFAULT_PROFILE_THRESHOLD`. `0` widens recall (noisy); raise it to
+     * drop weakly-matching raw messages from the LLM context.
+     */
+    profileThreshold?: number;
+    /**
+     * Minimum similarity for the relationship confirmation search. Defaults
+     * to `DEFAULT_RELATIONSHIP_THRESHOLD`.
+     */
+    relationshipThreshold?: number;
+}
+interface PeerProfile {
+    peer: Peer;
+    /** LLM-synthesised answer (empty string when no LLM is configured or synthesis fails). */
+    answer: string;
+    /** Stable IDs of the evidence items the LLM saw. */
+    evidenceIds: string[];
+    /** Warning codes from the reflect pipeline (e.g. `reflect_llm_failed`). */
+    warnings: string[];
+}
+interface PeerRelationship {
+    from: Peer;
+    to: Peer;
+    summary: string;
+    evidenceIds: string[];
+    /** Number of co-mention observations between `from` and `to`. */
+    strength: number;
+}
+interface PeerProfileFacade {
+    /** Synthesise a profile for `peerId` via `search({ synthesize: true })`. */
+    getProfile(peerId: string): Promise<PeerProfile>;
+    /** Discover and rank relationships `peerId` has with other peers. */
+    getRelationships(peerId: string): Promise<PeerRelationship[]>;
+    /** All peers the facade knows about. */
+    getKnownPeers(): ReadonlyArray<Peer>;
+}
+declare function createPeerProfile(deps: PeerProfileDeps): PeerProfileFacade;
+
 interface MemoryStore {
     /** Underlying raw-message store (sqlite vs postgres). */
     raw: RawMessageStore;
-    /** Unified semantic search facade (memory + insights + knowledge). */
-    search: UnifiedSearch;
+    /**
+     * Unified read entry point. Cross-source retrieval (memory +
+     * insights + knowledge + summaries) with RRF merge, reasoning
+     * strategies (`rewrite` / `iterative`), date filtering, and
+     * lexical fallback. Set `synthesize: true` to opt into the LLM
+     * synthesis path (formerly `reflect()`).
+     *
+     * Use `store.consolidate()` for the agentic write-back loop.
+     */
+    search(input: SearchInput): Promise<SearchOutput>;
     /** Resolve the active raw-message manager. */
     getRawMessageManager: typeof getRawMessageManager;
-    /** Run `searchUnifiedMemory` against the wired-up unified search. */
+    /**
+     * @deprecated Use `store.search(input)` instead. Forwarding shim
+     * kept for one release window.
+     */
     searchUnifiedMemory: UnifiedSearch["searchUnifiedMemory"];
-    /** Convenience: semantic search over raw messages only. */
+    /**
+     * @deprecated Use `store.search({ ...input, sources: ["memory"] })`
+     * and read `.results` instead.
+     */
     searchRawMemorySemantically: UnifiedSearch["searchRawMemorySemantically"];
+    /**
+     * Agentic write-back: gathers evidence, vets a consolidation plan
+     * with the LLM, persists via the attached graph store +
+     * soft-deprecates via the storage adapter. The `graphStore` and
+     * `storage` fields are forwarded from this `MemoryStore` instance
+     * when the caller omits them on the input.
+     */
+    consolidate(input: ApplyConsolidateInput): Promise<ApplyConsolidateOutput>;
+    /**
+     * Optional write-back graph store. Set via `attachMemoryGraphStore`;
+     * consumers can read it for diagnostic / replay tooling. Absent when
+     * the host has not wired one in.
+     */
+    graphStore?: _melandlabs_memory_consolidation.MemoryGraphStoreWithOperationHistory;
+    /**
+     * Optional storage adapter carrying `deprecateRecords`. Forwarded into
+     * `consolidate` when callers want deprecation writes without
+     * attaching a full graph store.
+     */
+    storage?: _melandlabs_memory_consolidation.MemoryStorageAdapterLike;
+    /**
+     * Vector Symbolic Architecture facade. Always available — backed by
+     * the same SQLite DB the raw-message manager uses. Routes through its
+     * own `vsa_facts` table; never mixed into the unified search.
+     *
+     *   - `vsaStoreFact(input)` — persist a (role, filler) binding.
+     *   - `vsaRecall(input)`    — rebuild memory vector + best-match cleanup.
+     *   - `vsaListFacts(input)` — read-side projection (no vectors).
+     *   - `vsaForget(input)`    — soft-delete by id.
+     */
+    vsa: VsaRecallFacade;
 }
 declare function createMemoryStore(config?: MemoryStoreConfig): Promise<MemoryStore>;
 
-export { type MemoryStore, MemoryStoreConfig, UnifiedSearch, createMemoryStore, getRawMessageManager };
+export { ApplyConsolidateInput, ApplyConsolidateOutput, type AttachMemoryGraphStoreInput, type MemoryStore, MemoryStoreConfig, type PeerPosting, type PeerProfile, type PeerProfileDeps, type PeerProfileFacade, type PeerRelationship, SearchInput, SearchOutput, UnifiedSearch, type VsaRecallFacade, attachMemoryGraphStore, createMemoryStore, createPeerProfile, createVsaRecall, getRawMessageManager };