@mastra/mongodb 1.25.0-alpha.0 → 1.26.0-alpha.0

package/dist/_types/@internal_core/dist/knowledge-compat/index.d.ts

@@ -0,0 +1,338 @@
+export declare const KNOWLEDGE_STORAGE_CONTRACT_VERSION: 4;
+export declare const KNOWLEDGE_STORAGE_SCHEMA_VERSION: 4;
+export declare const TABLE_KNOWLEDGE_NODE_SCOPES = "mastra_knowledge_node_scopes";
+export declare const TABLE_KNOWLEDGE_RECORD_SCOPES = "mastra_knowledge_record_scopes";
+export declare const TABLE_KNOWLEDGE_SCOPE_GRANTS = "mastra_knowledge_scope_grants";
+export declare const TABLE_KNOWLEDGE_ACCESS_STATE = "mastra_knowledge_access_state";
+export declare const TABLE_KNOWLEDGE_SCOPE_ADDRESSES = "mastra_knowledge_scope_addresses";
+export declare const TABLE_KNOWLEDGE_NODE_ADDRESSES = "mastra_knowledge_node_addresses";
+export declare const TABLE_KNOWLEDGE_IMPORT_STATE = "mastra_knowledge_import_state";
+export declare const TABLE_KNOWLEDGE_IMPORT_RUNS = "mastra_knowledge_import_runs";
+export declare const TABLE_KNOWLEDGE_PROPOSALS = "mastra_knowledge_proposals";
+export declare const KNOWLEDGE_TABLE_NAMES: readonly ["mastra_knowledge_nodes", "mastra_knowledge_records", "mastra_knowledge_mentions", "mastra_knowledge_activity", "mastra_knowledge_semantic_outbox", "mastra_knowledge_node_scopes", "mastra_knowledge_record_scopes", "mastra_knowledge_scope_grants", "mastra_knowledge_access_state", "mastra_knowledge_scope_addresses", "mastra_knowledge_node_addresses", "mastra_knowledge_import_state", "mastra_knowledge_import_runs", "mastra_knowledge_proposals"];
+/** Knowledge v1 tables with no v2 equivalent; an explicit schema reset drops them. */
+export declare const RETIRED_KNOWLEDGE_TABLE_NAMES: readonly ['mastra_knowledge_cursors'];
+export declare const KNOWLEDGE_PAGES_CORE_FEATURE = "knowledge-pages";
+export declare const KNOWLEDGE_PAGES_SCHEMA_VERSION: 4;
+export declare const TABLE_KNOWLEDGE_PAGES = "mastra_knowledge_pages";
+export declare const TABLE_KNOWLEDGE_NOTES = "mastra_knowledge_notes";
+export declare const TABLE_KNOWLEDGE_NOTE_STAMPS = "mastra_knowledge_note_stamps";
+/** Same name as the schema-2 table; schema 4 re-keys it to note → page. */
+export declare const TABLE_KNOWLEDGE_PAGE_MENTIONS = "mastra_knowledge_mentions";
+export declare const TABLE_KNOWLEDGE_PINS = "mastra_knowledge_pins";
+/** Same name as schema 2; schema 4 re-keys it to scope/page/note. */
+export declare const TABLE_KNOWLEDGE_PAGE_ACTIVITY = "mastra_knowledge_activity";
+/** Holds `{ id: 'knowledge', schemaVersion: 4 }`, written when the schema-4 tables are created. */
+export declare const TABLE_KNOWLEDGE_PAGES_STATE = "mastra_knowledge_access_state";
+export declare const KNOWLEDGE_PAGES_TABLE_NAMES: readonly ["mastra_knowledge_pages", "mastra_knowledge_notes", "mastra_knowledge_note_stamps", "mastra_knowledge_mentions", "mastra_knowledge_pins", "mastra_knowledge_activity", "mastra_knowledge_access_state"];
+/** Every Knowledge table any schema version created. Reset drops these and nothing else. */
+export declare const KNOWLEDGE_RESETTABLE_TABLE_NAMES: readonly string[];
+/** Schema-1/2 tables whose presence means the store needs a reset before schema 4 can run. */
+export declare const LEGACY_KNOWLEDGE_TABLE_NAMES: ReadonlySet<string>;
+/** Pages and scope pages. `scopeId` equals `id` on scope pages; `address`/`declaration` only on scope pages. */
+export declare const KNOWLEDGE_PAGES_SCHEMA: {
+  readonly id: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly primaryKey: true;
+  };
+  readonly scopeId: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly parentId: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly isScope: {
+    readonly type: 'boolean';
+    readonly nullable: false;
+  };
+  readonly address: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly declaration: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly key: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly position: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly name: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly canonicalName: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly description: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly body: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly version: {
+    readonly type: 'integer';
+    readonly nullable: false;
+  };
+  readonly mergedInto: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly createdBy: {
+    readonly type: 'jsonb';
+    readonly nullable: false;
+  };
+  readonly updatedBy: {
+    readonly type: 'jsonb';
+    readonly nullable: false;
+  };
+  readonly createdAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+  readonly updatedAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+  readonly deletedAt: {
+    readonly type: 'timestamp';
+    readonly nullable: true;
+  };
+  readonly deletedBy: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+};
+export declare const KNOWLEDGE_NOTES_SCHEMA: {
+  readonly id: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly primaryKey: true;
+  };
+  readonly pageId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_pages";
+      readonly column: 'id';
+    };
+  };
+  readonly text: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly when: {
+    readonly type: 'timestamp';
+    readonly nullable: true;
+  };
+  readonly provenance: {
+    readonly type: 'jsonb';
+    readonly nullable: false;
+  };
+  readonly version: {
+    readonly type: 'integer';
+    readonly nullable: false;
+  };
+  readonly createdAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+  readonly updatedAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+  readonly deletedAt: {
+    readonly type: 'timestamp';
+    readonly nullable: true;
+  };
+  readonly deletedBy: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+};
+/** One row per (note, stamp scope). Primary key is the pair. */
+export declare const KNOWLEDGE_NOTE_STAMPS_SCHEMA: {
+  readonly noteId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_notes";
+      readonly column: 'id';
+    };
+  };
+  readonly scopeId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_pages";
+      readonly column: 'id';
+    };
+  };
+};
+/** One row per (note, mentioned page). Primary key is the pair. */
+export declare const KNOWLEDGE_PAGE_MENTIONS_SCHEMA: {
+  readonly noteId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_notes";
+      readonly column: 'id';
+    };
+  };
+  readonly pageId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_pages";
+      readonly column: 'id';
+    };
+  };
+};
+/** `audience` is a JSON array of scope addresses (PG may store it as `text[]`, Mongo as an array). */
+export declare const KNOWLEDGE_PINS_SCHEMA: {
+  readonly id: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly primaryKey: true;
+  };
+  readonly pageId: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly references: {
+      readonly table: "mastra_knowledge_pages";
+      readonly column: 'id';
+    };
+  };
+  readonly audience: {
+    readonly type: 'jsonb';
+    readonly nullable: false;
+  };
+  readonly createdBy: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly createdAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+  readonly updatedAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+};
+export declare const KNOWLEDGE_PAGE_ACTIVITY_SCHEMA: {
+  readonly id: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly primaryKey: true;
+  };
+  readonly action: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly scopeId: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly pageId: {
+    readonly type: 'text';
+    readonly nullable: false;
+  };
+  readonly noteId: {
+    readonly type: 'text';
+    readonly nullable: true;
+  };
+  readonly provenance: {
+    readonly type: 'jsonb';
+    readonly nullable: false;
+  };
+  readonly createdAt: {
+    readonly type: 'timestamp';
+    readonly nullable: false;
+  };
+};
+export declare const KNOWLEDGE_PAGES_STATE_SCHEMA: {
+  readonly id: {
+    readonly type: 'text';
+    readonly nullable: false;
+    readonly primaryKey: true;
+  };
+  readonly schemaVersion: {
+    readonly type: 'integer';
+    readonly nullable: false;
+  };
+};
+export type KnowledgePagesSchemaInspection = {
+  status: 'compatible';
+  schemaVersion: typeof KNOWLEDGE_PAGES_SCHEMA_VERSION;
+} | {
+  status: 'uninitialized';
+  schemaVersion: null;
+} | {
+  status: 'incompatible-reset-required';
+  schemaVersion: number | null;
+  reason: string;
+};
+/**
+ * Classifies what an adapter found before creating schema-4 tables. `tableNames` is every
+ * `mastra_knowledge_*` table present; `schemaVersion` is the state row's version, if any.
+ */
+export declare function inspectKnowledgePagesSchema(snapshot: {
+  tableNames: readonly string[];
+  schemaVersion?: number;
+}): KnowledgePagesSchemaInspection;
+/**
+ * The old Knowledge tables an adapter drops on init, rows included: Knowledge before schema 4 was an
+ * experimental store with no migration. Every schema-1/2-only table present is dropped. The table
+ * names schema 4 reuses (mentions, activity, the state table) are dropped too, but only when an old
+ * table is present and no schema-4 state row exists, so they are old-shaped. Schema-4-only tables
+ * are never listed. On a schema-4 store this lists only tables an older process recreated during a
+ * rolling deploy. Drop order is safe for adapters that enforce references.
+ */
+export declare function legacyKnowledgeTablesToDrop(snapshot: {
+  tableNames: readonly string[];
+  schemaVersion?: number;
+}): string[];
+/** Message for the error an adapter throws on `incompatible-reset-required`. */
+export declare function knowledgePagesResetMessage(reason: string): string;
+/**
+ * The page-store runtime pieces adapters take from `@mastra/core/storage`. They are loaded through
+ * `createKnowledgePagesCoreLoader` instead of static imports so adapters keep loading on cores
+ * older than the `knowledge-pages` feature without raising their `@mastra/core` peer floor.
+ */
+export interface KnowledgePagesCore {
+  assertKnowledgePageDescriptionWithinBound(description: string | undefined): void;
+  assertKnowledgeNoteTextWithinBound(text: string): void;
+  canonicalKnowledgeName(name: string): string;
+  knowledgePositionBetween(before?: string, after?: string): string;
+  MAX_KNOWLEDGE_MOVE_PAGES: number;
+  MAX_KNOWLEDGE_PAGE_DEPTH: number;
+  MAX_KNOWLEDGE_PAGE_LIST_LIMIT: number;
+  KnowledgeMoveTooLargeError: new (pageId: string, pages: number) => Error;
+  KnowledgePageDepthError: new (pageId: string) => Error;
+  KnowledgePageHasChildrenError: new (pageId: string) => Error;
+  KnowledgePageKeyConflictError: new (key: string, parentId: string) => Error;
+}
+/** Loads core's page-store runtime once, after checking core advertises `knowledge-pages`. */
+export declare function createKnowledgePagesCoreLoader(features: ReadonlySet<string>, loadStorageModule: () => Promise<unknown>): () => Promise<KnowledgePagesCore>;
+/**
+ * Keyword-search words: the query split on whitespace, lowercased, deduplicated. Every word must
+ * appear (as a case-insensitive substring) in a hit; an empty list means the search returns nothing.
+ */
+export declare function knowledgeSearchWords(query: string): string[];
+/**
+ * Why `key` can't be a Knowledge page key, or undefined when it can. Keys are one path segment:
+ * non-empty, with no `/` (path separator), `#` (scope/path separator) or `%` (escape character).
+ */
+export declare function knowledgePageKeyProblem(key: string): string | undefined;
+//# sourceMappingURL=index.d.ts.map

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-mongodb
 description: Documentation for @mastra/mongodb. Use when working with @mastra/mongodb APIs, configuration, or implementation.
 metadata:
   package: "@mastra/mongodb"
-  version: "1.25.0-alpha.0"
+  version: "1.26.0-alpha.0"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.25.0-alpha.0",
+  "version": "1.26.0-alpha.0",
   "package": "@mastra/mongodb",
   "exports": {},
   "modules": {}

package/dist/docs/references/docs-memory-semantic-recall.md

@@ -435,6 +435,8 @@ When using PostgreSQL as your vector store, you can optimize semantic recall per
 
 PostgreSQL supports both IVFFlat and HNSW indexes. By default, Mastra creates an IVFFlat index, but HNSW indexes typically provide better performance, especially with OpenAI embeddings which use inner product distance.
 
+Semantic recall always filters by thread or resource. PgVector uses the vector index for these searches only with HNSW on pgvector 0.8.0 or newer. With IVFFlat, each search compares the query against every message in the thread or resource.
+
 ```typescript
 import { Memory } from '@mastra/memory'
 import { PostgresStore, PgVector } from '@mastra/pg'

package/dist/docs/references/reference-rag-retrieval.md

@@ -251,7 +251,11 @@ const results = await pgVector.query({
 })
 ```
 
-Postgres vector indexes (HNSW and IVFFlat) can't restrict that search to rows matching a condition. When a filter is present, pgVector instead compares the query vector against every matching row and returns the closest `topK`. Results are exact, but the work grows with the number of rows the filter matches. Indexing the metadata column speeds up row retrieval. The distance comparisons still happen per row.
+With an HNSW index on pgvector 0.8.0 or newer, PostgreSQL searches the index and skips rows that don't match the filter. When the index search can't fill `topK`, pgVector reruns the query as an exact search.
+
+With IVFFlat, or HNSW on older pgvector versions, pgVector compares the query vector against every matching row. Results are exact, but the work grows with the number of matching rows.
+
+Indexing the metadata fields you filter on speeds up both cases and gives PostgreSQL the row counts it needs to choose between them.
 
 ### Vector Query Tool