@melandlabs/memory-store 0.3.0 → 1.0.0

package/dist/{config-2Q092MUz.d.ts → config-CnbqSek5.d.ts}

@@ -1,3 +1,38 @@
+import * as _melandlabs_memory_consolidation from '@melandlabs/memory-consolidation';
+import * as _melandlabs_contracts_peer from '@melandlabs/contracts/peer';
+import { Peer } from '@melandlabs/contracts/peer';
+import { FactType } from '@melandlabs/contracts';
+
+/**
+ * Reranker adapter contract.
+ *
+ * A `Reranker` is an optional plug-in applied to the unified-search output
+ * after per-source merge but before the final `slice(0, limit)`. It lets a
+ * host swap in a cross-encoder, a learned ranker, or any other deterministic
+ * ordering without changing the retrieval pipeline.
+ *
+ * Implementations MUST be deterministic for the same `(query, candidates)`
+ * pair — non-deterministic orderings would defeat the existing
+ * `rrfScore`/`similarity` tie-break tests.
+ */
+interface RerankerCandidate {
+    id: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface RerankerInput {
+    query: string;
+    candidates: RerankerCandidate[];
+    topK?: number;
+}
+interface RerankerScore {
+    id: string;
+    score: number;
+}
+interface Reranker {
+    rerank(input: RerankerInput): Promise<RerankerScore[]>;
+}
+
 /**
  * Pure helpers used by the unified memory search pipeline.
  *
@@ -5,6 +40,7 @@
  * and the HTTP daemon without pulling in any of the heavier
  * storage/search implementations.
  */
+
 type UnifiedMemorySearchSource = "memory" | "insights" | "knowledge";
 type UnifiedMemoryReasoningStrategy = "none" | "rewrite" | "iterative";
 interface UnifiedMemorySearchWarning {
@@ -81,12 +117,28 @@ interface UnifiedMemorySearchInput {
      * lists fed via the (internal) `rankedLists` option.
      */
     mergeStrategy?: UnifiedMemoryMergeStrategy;
+    /**
+     * Optional additive scope-narrowing filter expressed as structured
+     * peers. Coexists with `userId`/`botIds`. When supplied, the host's
+     * `UnifiedSearchDeps.peerScopeCheck` is consulted; peers that fall
+     * outside `userId` are dropped with a `peer_filter_outside_user_scope`
+     * warning rather than broadening the scope.
+     */
+    peerFilter?: ReadonlyArray<Peer>;
     /**
      * Optional reasoning strategy. `"rewrite"` rewrites the query before
      * embedding; `"iterative"` runs an LLM planner that searches, notes
      * evidence, and searches again. Defaults to `"none"`.
      */
     reasoningStrategy?: UnifiedMemoryReasoningStrategy;
+    /**
+     * Optional `FactType` read-side filter. When supplied, the memory
+     * source narrows candidates to rows whose `factType` is in this set.
+     * Only affects the `memory` source; `insights` and `knowledge` are
+     * not filtered by this. Empty array is treated as "no filter" so
+     * callers can pass `searchInput.factTypes ?? []` without surprises.
+     */
+    factTypes?: FactType[];
 }
 type UnifiedMemoryMergeStrategy = "similarity" | "rrf";
 /**
@@ -95,7 +147,9 @@ type UnifiedMemoryMergeStrategy = "similarity" | "rrf";
  * flattening them into a single similarity score first.
  */
 interface UnifiedMemoryRankedList {
-    name: "memory-bm25" | "memory-semantic" | "insights" | "knowledge";
+    /** Label for the source list (e.g. a tier or channel). Free-form; the
+     * RRF fusion only reads `hits`, so `name` is purely diagnostic. */
+    name: string;
     hits: UnifiedMemorySearchResult[];
 }
 interface UnifiedMemorySearchResult {
@@ -118,6 +172,83 @@ interface UnifiedMemorySearchOutput {
      */
     reasoning?: UnifiedMemoryReasoningInfo;
 }
+/**
+ * Cross-source retrieval surface for the unified search. Mirrors
+ * `UnifiedMemorySearchSource` but is exposed under a more discoverable
+ * name.
+ */
+type SearchSource = UnifiedMemorySearchSource;
+/**
+ * Per-tier evidence bucket consulted by `reflect`-style synthesis.
+ * Includes the `summary` tier that the read-only sources do not surface.
+ */
+type SearchTier = "summary" | "raw" | "insight" | "knowledge";
+interface SearchInput {
+    userId: string;
+    query: string;
+    /** Cross-source retrieval surface (defaults to all three sources). */
+    sources?: ReadonlyArray<SearchSource>;
+    /**
+     * Per-tier subset — when omitted, defaults to all four tiers.
+     * Forwarded to the gather step so the read pipeline can scope the
+     * evidence. Most callers pass nothing; `synthesize` callers can
+     * narrow to `["raw"]` or `["summary", "raw"]` for cheaper synthesis.
+     */
+    tiers?: ReadonlyArray<SearchTier>;
+    /**
+     * Opt-in LLM synthesis. When `true`, runs `reasoning.complete` after
+     * gathering evidence and returns `answer` in the output. When
+     * omitted / `false`, no LLM call is made (matches today's
+     * `searchUnifiedMemory`). The `responseSchema` form lets the LLM
+     * return JSON; the SDK extracts `{ answer: string }` from the
+     * payload and surfaces the rest via warnings.
+     */
+    synthesize?: boolean | {
+        responseSchema?: Record<string, unknown>;
+    };
+    limit?: number;
+    threshold?: number;
+    botIds?: string[];
+    documentIds?: string[];
+    dateFrom?: string;
+    dateTo?: string;
+    asOf?: string;
+    peerFilter?: ReadonlyArray<Peer>;
+    authToken?: string;
+    factTypes?: FactType[];
+    mergeStrategy?: UnifiedMemoryMergeStrategy;
+    reasoningStrategy?: UnifiedMemoryReasoningStrategy;
+    /**
+     * Backward-compat pass-through for callers that previously passed
+     * `responseSchema` at the top level. When set, it overrides
+     * `synthesize.responseSchema`.
+     */
+    responseSchema?: Record<string, unknown>;
+    /**
+     * Backward-compat pass-through for callers that previously passed
+     * `includeArchivedInsights` to the read-only search.
+     */
+    includeArchivedInsights?: boolean;
+}
+interface SearchEvidence {
+    id: string;
+    source: SearchSource | SearchTier;
+    snippet: string;
+    score: number;
+    timestamp?: number;
+}
+interface SearchOutput {
+    query: string;
+    sources: ReadonlyArray<SearchSource>;
+    results: UnifiedMemorySearchResult[];
+    /** Same hits as `results`, with the source labelled for synthesis callers. */
+    evidence: SearchEvidence[];
+    count: number;
+    warnings: UnifiedMemorySearchWarning[];
+    reasoning?: UnifiedMemoryReasoningInfo;
+    /** Only present when `synthesize` was truthy. */
+    answer?: string;
+}
 declare function normalizeUnifiedMemorySearchSources(sources: unknown): UnifiedMemorySearchSource[];
 declare function clampUnifiedMemorySearchLimit(limit: unknown): number;
 declare function clampUnifiedMemorySearchThreshold(threshold: unknown): number;
@@ -372,6 +503,16 @@ interface UnifiedSearchInsightsResult {
     metadata: Record<string, unknown>;
 }
 interface UnifiedSearchReasoningDeps {
+    /**
+     * LLM single-turn synthesis callback. Wired into
+     * `search({ synthesize: true })` so a host that wants synthesis
+     * responses only has to drop in one callable. When omitted, the
+     * synthesis path returns the gathered evidence with a
+     * `synthesize_llm_not_configured` warning instead of throwing.
+     */
+    complete?: (prompt: string) => Promise<string>;
+    /** Default merge strategy used by `searchUnifiedMemory` when the caller does not specify one. @default "rrf" */
+    defaultMergeStrategy?: UnifiedMemoryMergeStrategy;
     /** Optional query rewriter. When present, "rewrite" strategy is available. */
     queryRewriter?: QueryRewriter;
     /** Optional iterative recall planner. When present, "iterative" strategy is available. */
@@ -379,6 +520,14 @@ interface UnifiedSearchReasoningDeps {
     /** Default reasoning strategy when callers do not specify one. @default "none" */
     defaultStrategy?: UnifiedMemoryReasoningStrategy;
 }
+interface MemorySummaryHit {
+    summaryId: string;
+    summaryText: string;
+    summaryTier?: "L1" | "L2" | "L3";
+    keywords?: string[];
+    startTimestamp?: number;
+    endTimestamp?: number;
+}
 interface UnifiedSearchDeps {
     /** Embed a query string using the active user's provider. */
     embedQuery?: EmbedQueryFn;
@@ -394,6 +543,10 @@ interface UnifiedSearchDeps {
         limit: number;
         threshold: number;
         botId?: string;
+        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
+        peers?: ReadonlyArray<Peer>;
+        /** Optional `FactType` filter resolved from `UnifiedMemorySearchInput.factTypes`. */
+        factTypes?: FactType[];
     }) => Promise<Array<{
         id: string;
         content: string;
@@ -410,6 +563,8 @@ interface UnifiedSearchDeps {
             documentIds?: string[];
         };
         authToken?: string;
+        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
+        peers?: ReadonlyArray<Peer>;
     }) => Promise<UnifiedSearchKnowledgeResult[]>;
     /** Semantic search over extracted insights. */
     searchInsights?: (input: {
@@ -420,6 +575,8 @@ interface UnifiedSearchDeps {
         botIds?: string[];
         includeArchived?: boolean;
         authToken?: string;
+        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
+        peers?: ReadonlyArray<Peer>;
     }) => Promise<UnifiedSearchInsightsResult[]>;
     /**
      * Optional BM25 (lexical) sub-query for the memory source. Mirrors the
@@ -432,14 +589,58 @@ interface UnifiedSearchDeps {
         keywords: string[];
         limit: number;
         botId?: string;
+        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
+        peers?: ReadonlyArray<Peer>;
+        /** Optional `FactType` filter resolved from `UnifiedMemorySearchInput.factTypes`. */
+        factTypes?: FactType[];
     }) => Promise<Array<{
         id: string;
         content: string;
         similarity: number;
         metadata: Record<string, unknown>;
     }>>;
+    /**
+     * Optional summary-tier search. When wired in, `reflect()` consults the
+     * summary tier alongside raw messages and emits a
+     * `reflect_summaries_unavailable` warning if the call fails.
+     */
+    searchSummaries?: (input: {
+        userId: string;
+        query: string;
+        keywords: string[];
+        limit: number;
+        threshold: number;
+        dateFrom?: string;
+        dateTo?: string;
+        authToken?: string;
+        /** Optional peer scope resolved from `UnifiedMemorySearchInput.peerFilter`. */
+        peers?: ReadonlyArray<Peer>;
+    }) => Promise<MemorySummaryHit[]>;
+    /**
+     * Optional host-side check that validates whether a `peerFilter` peer is
+     * actually reachable from this `userId`. Used by
+     * `resolveScopePeer` to drop out-of-scope peers with a warning
+     * rather than broadening the search. May be omitted for hosts that
+     * have no peer-permission model.
+     */
+    peerScopeCheck?: (input: {
+        userId: string;
+        peers: ReadonlyArray<_melandlabs_contracts_peer.Peer>;
+    }) => Promise<boolean> | boolean;
     /** Optional reasoning providers. */
     reasoning?: UnifiedSearchReasoningDeps;
+    /**
+     * Optional reranker applied after per-source merge and before the
+     * final limit. Defaults to an identity pass-through so the merge order
+     * is preserved.
+     */
+    reranker?: Reranker;
+    /**
+     * Optional logger. When set (e.g. via `MemoryStoreConfig.logger`),
+     * `reflect` / `consolidate` log through it instead of `console`.
+     * Falls back to `console` when omitted.
+     */
+    logger?: Pick<Console, "log" | "warn" | "error">;
 }
 interface MemoryStoreConfig {
     /**
@@ -463,8 +664,20 @@ interface MemoryStoreConfig {
     vector?: MemoryStoreVectorConfig;
     /** Optional cross-source search providers. */
     unified?: UnifiedSearchDeps;
+    /**
+     * Optional write-back graph store. When set, `createMemoryStore` wires
+     * it into `store.graphStore` and forwards it to `consolidate`. Hosts
+     * that prefer post-construction wiring can use `attachMemoryGraphStore`.
+     */
+    graphStore?: _melandlabs_memory_consolidation.MemoryGraphStoreWithOperationHistory;
+    /**
+     * Optional storage adapter carrying `deprecateRecords`. Forwarded into
+     * `consolidate` for callers that want deprecation writes without
+     * attaching a full graph store.
+     */
+    storage?: _melandlabs_memory_consolidation.MemoryStorageAdapterLike;
     /** Optional logger. Defaults to console. */
     logger?: Pick<Console, "log" | "warn" | "error">;
 }
 
-export { isRawMemorySemanticResult as A, mergeUnifiedMemorySearchResults as B, normalizeUnifiedMemoryReasoningStrategy as C, normalizeUnifiedMemorySearchSources as D, type EmbedQueryFn as E, toKnowledgeResult as F, toMemoryResult as G, type UnifiedSearchDeps as H, type IterativeRecallCandidate as I, type UnifiedMemoryMergeStrategy as J, type UnifiedMemoryRankedList as K, mergeUnifiedMemorySearchResultsRrf as L, type MemoryStoreConfig as M, normalizeUnifiedMemoryMergeStrategy as N, type QueryRewriter as Q, type UnifiedMemoryReasoningInfo as U, type VectorBackend as V, type IterativeRecallExecutor as a, type IterativeRecallPlanner as b, type IterativeRecallPlannerOptions as c, type IterativeRecallResult as d, type IterativeRecallSearchRequest as e, type IterativeRecallSearchResult as f, type IterativeRecallStats as g, type MemoryStoreDb as h, type MemoryStoreEnv as i, type QueryRewriterInput as j, type QueryRewriterOptions as k, type UnifiedMemoryReasoningStrategy as l, type UnifiedMemorySearchInput as m, type UnifiedMemorySearchOutput as n, type UnifiedMemorySearchResult as o, type UnifiedMemorySearchSource as p, type UnifiedMemorySearchWarning as q, type UnifiedSearchInsightsResult as r, type UnifiedSearchKnowledgeResult as s, type UnifiedSearchReasoningDeps as t, clampUnifiedMemorySearchLimit as u, clampUnifiedMemorySearchThreshold as v, createIdentityIterativePlanner as w, createIdentityRewriter as x, createIterativeRecallPlanner as y, createUserVoiceRewriter as z };
+export { type IterativeRecallResult as A, type IterativeRecallSearchRequest as B, type IterativeRecallSearchResult as C, type IterativeRecallStats as D, type EmbedQueryFn as E, type MemoryStoreDb as F, type QueryRewriterInput as G, type QueryRewriterOptions as H, type IterativeRecallCandidate as I, type UnifiedMemoryReasoningInfo as J, type UnifiedSearchInsightsResult as K, type UnifiedSearchKnowledgeResult as L, type MemoryStoreConfig as M, type UnifiedSearchReasoningDeps as N, createIdentityIterativePlanner as O, createIdentityRewriter as P, type QueryRewriter as Q, createIterativeRecallPlanner as R, type SearchTier as S, createUserVoiceRewriter as T, type UnifiedSearchDeps as U, type VectorBackend as V, type MemoryStoreEnv as a, type UnifiedMemorySearchWarning as b, type SearchEvidence as c, type SearchInput as d, type SearchOutput as e, type UnifiedMemorySearchInput as f, type UnifiedMemorySearchOutput as g, type UnifiedMemorySearchResult as h, type SearchSource as i, type UnifiedMemoryMergeStrategy as j, type UnifiedMemoryRankedList as k, type UnifiedMemoryReasoningStrategy as l, type UnifiedMemorySearchSource as m, clampUnifiedMemorySearchLimit as n, clampUnifiedMemorySearchThreshold as o, isRawMemorySemanticResult as p, mergeUnifiedMemorySearchResults as q, mergeUnifiedMemorySearchResultsRrf as r, normalizeUnifiedMemoryMergeStrategy as s, normalizeUnifiedMemoryReasoningStrategy as t, normalizeUnifiedMemorySearchSources as u, toKnowledgeResult as v, toMemoryResult as w, type IterativeRecallExecutor as x, type IterativeRecallPlanner as y, type IterativeRecallPlannerOptions as z };

package/dist/contracts.d.ts

@@ -1,4 +1,5 @@
 import { MemoryRecord } from '@melandlabs/ai/memory';
+export { StoreVsaFactInput, StoreVsaFactOutput, VsaFact, VsaFactStorage, VsaFactSummary, VsaForgetInput, VsaForgetOutput, VsaListInput, VsaRecallInput, VsaRecallOutput, VsaRecallScore, VsaVocabularyEntry, vsaAssertSameDim, vsaNormalizeVector } from '@melandlabs/contracts';
 
 /**
  * Memory-store contracts — types and constants that were originally re-exported

package/dist/contracts.js

@@ -1,3 +1,5 @@
+export { vsaAssertSameDim, vsaNormalizeVector } from '@melandlabs/contracts';
+
 // src/contracts.ts
 var CHAT_MEMORY_EVIDENCE_ID_PREFIX = "opencontext-chat:";
 function normalizeTimestampToMs(value) {

package/dist/http.d.ts

@@ -1,4 +1,7 @@
-import { M as MemoryStoreConfig } from './config-2Q092MUz.js';
+import { M as MemoryStoreConfig } from './config-CnbqSek5.js';
+import '@melandlabs/memory-consolidation';
+import '@melandlabs/contracts/peer';
+import '@melandlabs/contracts';
 
 /**
  * @melandlabs/memory-store/http — HTTP server entry.
@@ -11,10 +14,16 @@ import { M as MemoryStoreConfig } from './config-2Q092MUz.js';
  *   });
  *
  * Endpoints (all POST, JSON in/out):
- *   GET  /health            → { ok: true }
- *   POST /v1/search         → UnifiedMemorySearchOutput
- *   POST /v1/raw-messages   → upsert raw messages (returns count)
- *   GET  /v1/raw-messages/:id  → single raw message
+ *   GET  /health              → { ok: true }
+ *   POST /v1/search           → SearchOutput (set `synthesize: true` for
+ *                                LLM synthesis)
+ *   POST /v1/raw-messages     → upsert raw messages (returns count)
+ *   GET  /v1/raw-messages/:id → single raw message
+ *   POST /v1/consolidate:apply → ApplyConsolidateOutput (agentic write-back)
+ *   POST /v1/vsa/store        → StoreVsaFactOutput
+ *   POST /v1/vsa/recall       → VsaRecallOutput
+ *   POST /v1/vsa/list         → VsaFactSummary[]
+ *   POST /v1/vsa/forget       → VsaForgetOutput
  *
  * `POST /v1/raw-messages` supports two body keys beyond `userId` /
  * `messages[]`:
@@ -29,6 +38,13 @@ import { M as MemoryStoreConfig } from './config-2Q092MUz.js';
  *      and the messages persist without an embedding (so ANN search
  *      won't return them).
  *
+ * `POST /v1/consolidate:apply` runs the same evidence pipeline as
+ * `POST /v1/search` with `synthesize: true`, then builds a
+ * memory-consolidation plan, optionally asks the LLM to veto unsafe
+ * entries, and persists via the attached graph store (when the host
+ * wired one into `options.graphStore`) + soft-deprecates superseded
+ * records via the storage adapter.
+ *
  * The HTTP server speaks only to the raw-message + vector layers; it does
  * not expose RAG/insights cross-source search (callers wire those up
  * server-side or use the MCP server with a fully-wired store).