@romiluz/clawmongo 2026.3.27 → 2026.3.28

package/dist/{mongodb-procedures-DNPmmW5r.js → mongodb-procedures-DI-_Dakz.js}

@@ -1,7 +1,7 @@
 import { t as createSubsystemLogger } from "./subsystem-VzQeL-96.js";
-import { v as procedureRevisionsCollection, y as proceduresCollection } from "./mongodb-schema-BI4Ze_ZV.js";
+import { b as proceduresCollection, y as procedureRevisionsCollection } from "./mongodb-schema-Dt6jxcPL.js";
 import { t as resolveScopeRef } from "./mongodb-scope-0bwP6Q3D.js";
-import { n as buildVectorSearchStage, s as summarizeExplain, t as MONGODB_MAX_NUM_CANDIDATES } from "./mongodb-search-VFKd72IZ.js";
+import { c as summarizeExplain, n as buildVectorSearchStage, t as MONGODB_MAX_NUM_CANDIDATES } from "./mongodb-search-DMsUyfpa.js";
 //#region src/memory/mongodb-procedures.ts
 const log = createSubsystemLogger("memory:mongodb:procedures");
 function arraysEqual(left, right) {
@@ -99,7 +99,11 @@ async function writeProcedure(params) {
 				},
 				$setOnInsert: {
 					createdAt: now,
-					openedCount: 0
+					openedCount: 0,
+					version: 1,
+					successCount: 0,
+					failCount: 0,
+					evolutionHistory: []
 				}
 			}, {
 				upsert: true,

package/dist/{mongodb-procedures-D3M2Ph8E.js → mongodb-procedures-tjhGdBV7.js}

@@ -5,7 +5,7 @@ import "./theme-CdOoMzRk.js";
 import "./globals-41sdSaKv.js";
 import "./subsystem-VzQeL-96.js";
 import "./ansi-BEJF8NKS.js";
-import "./mongodb-schema-BI4Ze_ZV.js";
-import "./mongodb-search-VFKd72IZ.js";
-import { n as writeProcedure } from "./mongodb-procedures-DNPmmW5r.js";
+import "./mongodb-schema-Dt6jxcPL.js";
+import "./mongodb-search-DMsUyfpa.js";
+import { n as writeProcedure } from "./mongodb-procedures-DI-_Dakz.js";
 export { writeProcedure };

package/dist/{mongodb-schema-JpDXcAUV.js → mongodb-schema-DN3aspLa.js}

@@ -5,5 +5,5 @@ import "./theme-CdOoMzRk.js";
 import "./globals-41sdSaKv.js";
 import "./subsystem-VzQeL-96.js";
 import "./ansi-BEJF8NKS.js";
-import { a as ensureCollections, c as ensureStandardIndexes, h as kbChunksCollection, r as detectCapabilities } from "./mongodb-schema-BI4Ze_ZV.js";
+import { a as ensureCollections, c as ensureStandardIndexes, h as kbChunksCollection, r as detectCapabilities } from "./mongodb-schema-Dt6jxcPL.js";
 export { detectCapabilities, ensureCollections, ensureStandardIndexes, kbChunksCollection };

package/dist/{mongodb-schema-BI4Ze_ZV.js → mongodb-schema-Dt6jxcPL.js}

@@ -64,6 +64,15 @@ function ingestRunsCollection(db, prefix) {
 function projectionRunsCollection(db, prefix) {
 	return col(db, prefix, "projection_runs");
 }
+function queryCacheCollection(db, prefix) {
+	return col(db, prefix, "query_cache");
+}
+function telemetryCollection(db, prefix) {
+	return col(db, prefix, "memory_telemetry");
+}
+function mutationsCollection(db, prefix) {
+	return col(db, prefix, "memory_mutations");
+}
 const KB_SCHEMA = { $jsonSchema: {
 	bsonType: "object",
 	required: [
@@ -416,6 +425,34 @@ const PROCEDURES_SCHEMA = { $jsonSchema: {
 			minimum: 0
 		},
 		lastUsedAt: { bsonType: "date" },
+		version: {
+			bsonType: "number",
+			minimum: 1,
+			description: "Current version number"
+		},
+		successCount: {
+			bsonType: "number",
+			minimum: 0
+		},
+		failCount: {
+			bsonType: "number",
+			minimum: 0
+		},
+		lastSuccessAt: { bsonType: "date" },
+		lastFailureAt: { bsonType: "date" },
+		evolutionHistory: {
+			bsonType: "array",
+			items: {
+				bsonType: "object",
+				properties: {
+					version: { bsonType: "number" },
+					changeType: { bsonType: "string" },
+					changeDescription: { bsonType: "string" },
+					timestamp: { bsonType: "date" }
+				}
+			},
+			description: "Capped at 20 entries via $push + $slice: -20"
+		},
 		createdAt: { bsonType: "date" },
 		updatedAt: { bsonType: "date" }
 	}
@@ -510,7 +547,15 @@ const CHUNKS_SCHEMA = { $jsonSchema: {
 		endLine: { bsonType: "number" },
 		embedding: { bsonType: "array" },
 		model: { bsonType: "string" },
-		updatedAt: { bsonType: "date" }
+		updatedAt: { bsonType: "date" },
+		status: {
+			enum: [
+				"active",
+				"archived",
+				"deleted"
+			],
+			description: "Lifecycle status (default: active)"
+		}
 	}
 } };
 const RELEVANCE_RUNS_SCHEMA = { $jsonSchema: {
@@ -729,6 +774,14 @@ const VALIDATED_COLLECTIONS = {
 				bsonType: "number",
 				minimum: 0,
 				maximum: 1
+			},
+			extractedAt: {
+				bsonType: "date",
+				description: "When this entity was extracted"
+			},
+			sourceRole: {
+				enum: ["user", "assistant"],
+				description: "Role of the event that produced this entity"
 			}
 		}
 	} },
@@ -859,6 +912,14 @@ const VALIDATED_COLLECTIONS = {
 			tags: {
 				bsonType: "array",
 				items: { bsonType: "string" }
+			},
+			status: {
+				enum: [
+					"active",
+					"archived",
+					"deleted"
+				],
+				description: "Lifecycle status (default: active)"
 			}
 		}
 	} },
@@ -923,6 +984,123 @@ const VALIDATED_COLLECTIONS = {
 			durationMs: { bsonType: "number" },
 			ts: { bsonType: "date" }
 		}
+	} },
+	query_cache: { $jsonSchema: {
+		bsonType: "object",
+		required: [
+			"queryHash",
+			"queryNorm",
+			"agentId",
+			"scope",
+			"scopeRef",
+			"results",
+			"pathUsed",
+			"sourceScope",
+			"createdAt",
+			"expiresAt",
+			"hitCount",
+			"lastHitAt"
+		],
+		properties: {
+			queryHash: {
+				bsonType: "string",
+				description: "SHA-256 of normalized query"
+			},
+			queryNorm: {
+				bsonType: "string",
+				description: "Normalized query text (autoEmbed source)"
+			},
+			agentId: {
+				bsonType: "string",
+				description: "Agent that generated this cache entry"
+			},
+			scope: {
+				enum: SCOPE_ENUM,
+				description: "Memory scope"
+			},
+			scopeRef: {
+				bsonType: "string",
+				description: "Resolved scope namespace"
+			},
+			results: {
+				bsonType: "array",
+				description: "Cached MemorySearchResult[]"
+			},
+			pathUsed: {
+				bsonType: "string",
+				description: "Retrieval path that produced results"
+			},
+			sourceScope: {
+				bsonType: "string",
+				description: "Source scope for cache partitioning"
+			},
+			createdAt: { bsonType: "date" },
+			expiresAt: {
+				bsonType: "date",
+				description: "Per-document TTL expiry"
+			},
+			hitCount: {
+				bsonType: "number",
+				minimum: 0
+			},
+			lastHitAt: { bsonType: "date" }
+		}
+	} },
+	memory_mutations: { $jsonSchema: {
+		bsonType: "object",
+		required: [
+			"mutationId",
+			"collectionName",
+			"documentId",
+			"operation",
+			"agentId",
+			"timestamp"
+		],
+		properties: {
+			mutationId: {
+				bsonType: "string",
+				description: "Unique mutation identifier"
+			},
+			collectionName: {
+				bsonType: "string",
+				description: "Target collection (structured_mem, entities, relations, procedures)"
+			},
+			documentId: {
+				bsonType: "string",
+				description: "_id or entityId of the modified document"
+			},
+			operation: {
+				enum: [
+					"create",
+					"update",
+					"delete"
+				],
+				description: "Mutation operation type"
+			},
+			agentId: {
+				bsonType: "string",
+				description: "Agent that performed the mutation"
+			},
+			oldValue: { description: "Document state before mutation (null for creates)" },
+			newValue: { description: "Document state after mutation (null for deletes)" },
+			changedFields: {
+				bsonType: "array",
+				items: { bsonType: "string" },
+				description: "Field names that changed (for updates)"
+			},
+			timestamp: {
+				bsonType: "date",
+				description: "When the mutation occurred"
+			},
+			actorRole: {
+				enum: [
+					"user",
+					"assistant",
+					"system"
+				],
+				description: "Role of the actor that triggered the mutation"
+			}
+		}
 	} }
 };
 async function ensureCollections(db, prefix) {
@@ -947,7 +1125,9 @@ async function ensureCollections(db, prefix) {
 		"entity_links",
 		"episodes",
 		"ingest_runs",
-		"projection_runs"
+		"projection_runs",
+		"query_cache",
+		"memory_mutations"
 	].map((n) => `${prefix}${n}`);
 	for (const name of needed) if (!existing.has(name)) {
 		const validator = VALIDATED_COLLECTIONS[name.slice(prefix.length)];
@@ -959,6 +1139,21 @@ async function ensureCollections(db, prefix) {
 		else await db.createCollection(name);
 		log.info(`created collection ${name}`);
 	}
+	const telemetryName = `${prefix}memory_telemetry`;
+	if (!existing.has(telemetryName)) try {
+		await db.createCollection(telemetryName, {
+			timeseries: {
+				timeField: "ts",
+				metaField: "meta",
+				granularity: "seconds"
+			},
+			expireAfterSeconds: 604800
+		});
+		log.info(`created time series collection ${telemetryName}`);
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (!msg.includes("already exists") && !msg.includes("Collection already exists")) log.warn(`time series collection creation failed: ${msg}`);
+	}
 	await ensureSchemaValidation(db, prefix);
 }
 /**
@@ -1265,6 +1460,13 @@ async function ensureStandardIndexes(db, prefix, ttlOpts) {
 		scopeRef: 1
 	}, { name: "idx_relations_agent_scope_scoperef" });
 	applied++;
+	await relations.createIndex({
+		toEntityId: 1,
+		agentId: 1,
+		scope: 1,
+		scopeRef: 1
+	}, { name: "idx_relations_to_entity_scope" });
+	applied++;
 	const entityLinks = entityLinksCollection(db, prefix);
 	await entityLinks.createIndex({
 		agentId: 1,
@@ -1372,6 +1574,61 @@ async function ensureStandardIndexes(db, prefix, ttlOpts) {
 		revision: -1
 	}, { name: "idx_procedure_revisions_identity_revision" });
 	applied++;
+	const queryCache = queryCacheCollection(db, prefix);
+	await queryCache.createIndex({
+		queryHash: 1,
+		agentId: 1,
+		scope: 1,
+		scopeRef: 1
+	}, {
+		name: "uq_query_cache_hash_agent_scope_scoperef",
+		unique: true
+	});
+	applied++;
+	await queryCache.createIndex({ expiresAt: 1 }, {
+		name: "idx_query_cache_ttl",
+		expireAfterSeconds: 0
+	});
+	applied++;
+	await queryCache.createIndex({
+		agentId: 1,
+		hitCount: -1
+	}, { name: "idx_query_cache_agent_hitcount" });
+	applied++;
+	const telemetry = telemetryCollection(db, prefix);
+	try {
+		await telemetry.createIndex({
+			"meta.agentId": 1,
+			ts: -1
+		}, { name: "idx_telemetry_agent_ts" });
+		applied++;
+		await telemetry.createIndex({
+			"meta.operation": 1,
+			ts: -1
+		}, { name: "idx_telemetry_op_ts" });
+		applied++;
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		log.warn(`telemetry index creation skipped: ${msg}`);
+	}
+	const mutations = mutationsCollection(db, prefix);
+	await mutations.createIndex({
+		agentId: 1,
+		collectionName: 1,
+		timestamp: -1
+	}, { name: "idx_mutations_agent_collection_ts" });
+	applied++;
+	await mutations.createIndex({ timestamp: 1 }, {
+		name: "idx_mutations_ttl",
+		expireAfterSeconds: 7776e3
+	});
+	applied++;
+	await mutations.createIndex({
+		documentId: 1,
+		collectionName: 1,
+		timestamp: -1
+	}, { name: "idx_mutations_doc_collection_ts" });
+	applied++;
 	log.info(`ensured ${applied} standard indexes`);
 	return applied;
 }
@@ -1386,7 +1643,7 @@ function hasServerVersionAtLeast(versionArray, minimumMajor, minimumMinor) {
 	return major > minimumMajor || major === minimumMajor && minor >= minimumMinor;
 }
 async function ensureSearchIndexes(db, prefix, profile, embeddingMode, quantization = "none", numDimensions = 1024) {
-	const budget = assertIndexBudget(profile, 8);
+	const budget = assertIndexBudget(profile, 9);
 	const reducedBudget = !budget.withinBudget && typeof budget.budget === "number" && budget.budget >= 2;
 	if (!budget.withinBudget && !reducedBudget) {
 		log.warn(`search index budget exceeded: planned=${budget.plannedSearchIndexes} budget=${budget.budget} profile=${profile}`);
@@ -1711,6 +1968,43 @@ async function ensureSearchIndexes(db, prefix, profile, embeddingMode, quantizat
 		}
 		if (!msg.includes("already exists") && !msg.includes("duplicate")) log.warn(`procedures vector search index creation failed: ${msg}`);
 	}
+	const queryCache = queryCacheCollection(db, prefix);
+	try {
+		await queryCache.createSearchIndex({
+			name: `${prefix}query_cache_vector`,
+			type: "vectorSearch",
+			definition: { fields: [
+				{
+					type: "autoEmbed",
+					modality: "text",
+					path: "queryNorm",
+					model: "voyage-4-large"
+				},
+				{
+					type: "filter",
+					path: "agentId"
+				},
+				{
+					type: "filter",
+					path: "scope"
+				},
+				{
+					type: "filter",
+					path: "scopeRef"
+				}
+			] }
+		});
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		if (isSearchIndexManagementUnavailable(msg)) {
+			log.warn(`search index management unavailable: ${msg}`);
+			return {
+				text: textCreated,
+				vector: vectorCreated
+			};
+		}
+		if (!msg.includes("already exists") && !msg.includes("duplicate")) log.warn(`query_cache vector search index creation failed: ${msg}`);
+	}
 	return {
 		text: textCreated,
 		vector: vectorCreated
@@ -1780,4 +2074,4 @@ async function detectCapabilities(db, probeCollectionName) {
 	return result;
 }
 //#endregion
-export { relevanceRegressionsCollection as C, structuredMemRevisionsCollection as E, relevanceArtifactsCollection as S, structuredMemCollection as T, metaCollection as _, ensureCollections as a, projectionRunsCollection as b, ensureStandardIndexes as c, episodesCollection as d, eventsCollection as f, kbCollection as g, kbChunksCollection as h, embeddingCacheCollection as i, entitiesCollection as l, ingestRunsCollection as m, chunksCollection as n, ensureSchemaValidation as o, filesCollection as p, detectCapabilities as r, ensureSearchIndexes as s, assertIndexBudget as t, entityLinksCollection as u, procedureRevisionsCollection as v, relevanceRunsCollection as w, relationsCollection as x, proceduresCollection as y };
+export { relationsCollection as C, structuredMemCollection as D, relevanceRunsCollection as E, structuredMemRevisionsCollection as O, queryCacheCollection as S, relevanceRegressionsCollection as T, metaCollection as _, ensureCollections as a, proceduresCollection as b, ensureStandardIndexes as c, episodesCollection as d, eventsCollection as f, kbCollection as g, kbChunksCollection as h, embeddingCacheCollection as i, telemetryCollection as k, entitiesCollection as l, ingestRunsCollection as m, chunksCollection as n, ensureSchemaValidation as o, filesCollection as p, detectCapabilities as r, ensureSearchIndexes as s, assertIndexBudget as t, entityLinksCollection as u, mutationsCollection as v, relevanceArtifactsCollection as w, projectionRunsCollection as x, procedureRevisionsCollection as y };

package/dist/{mongodb-search-VFKd72IZ.js → mongodb-search-DMsUyfpa.js}

@@ -1,5 +1,5 @@
 import { t as createSubsystemLogger } from "./subsystem-VzQeL-96.js";
-import { C as relevanceRegressionsCollection, S as relevanceArtifactsCollection, w as relevanceRunsCollection } from "./mongodb-schema-BI4Ze_ZV.js";
+import { E as relevanceRunsCollection, T as relevanceRegressionsCollection, w as relevanceArtifactsCollection } from "./mongodb-schema-Dt6jxcPL.js";
 import { readFile } from "node:fs/promises";
 import { createHash, randomUUID } from "node:crypto";
 //#region src/memory/mongodb-relevance.ts
@@ -971,4 +971,4 @@ async function mongoSearch(collection, query, queryVector, opts) {
 	}
 }
 //#endregion
-export { normalizeSearchResults as a, splitAtlasSearchFilter as i, buildVectorSearchStage as n, MongoDBRelevanceRuntime as o, mongoSearch as r, summarizeExplain as s, MONGODB_MAX_NUM_CANDIDATES as t };
+export { normalizeSearchResults as a, summarizeExplain as c, splitAtlasSearchFilter as i, buildVectorSearchStage as n, rrfScore as o, mongoSearch as r, MongoDBRelevanceRuntime as s, MONGODB_MAX_NUM_CANDIDATES as t };

package/dist/{mongodb-structured-memory-DnwUJ6SA.js → mongodb-structured-memory-D-3SEfTu.js}

@@ -1,9 +1,45 @@
 import { t as createSubsystemLogger } from "./subsystem-VzQeL-96.js";
-import { E as structuredMemRevisionsCollection, T as structuredMemCollection } from "./mongodb-schema-BI4Ze_ZV.js";
+import { D as structuredMemCollection, O as structuredMemRevisionsCollection, v as mutationsCollection } from "./mongodb-schema-Dt6jxcPL.js";
 import { t as resolveScopeRef } from "./mongodb-scope-0bwP6Q3D.js";
-import { n as buildVectorSearchStage, s as summarizeExplain, t as MONGODB_MAX_NUM_CANDIDATES } from "./mongodb-search-VFKd72IZ.js";
+import { c as summarizeExplain, n as buildVectorSearchStage, t as MONGODB_MAX_NUM_CANDIDATES } from "./mongodb-search-DMsUyfpa.js";
+import { randomUUID } from "node:crypto";
+//#region src/memory/mongodb-mutations.ts
+const log$1 = createSubsystemLogger("memory:mongodb:mutations");
+/**
+* Insert an audit record into the memory_mutations collection.
+* Fire-and-forget safe: callers can use Promise.allSettled to avoid blocking.
+*/
+async function recordMutation(params) {
+	const { db, prefix, mutation } = params;
+	const mutationId = randomUUID();
+	const doc = {
+		...mutation,
+		mutationId,
+		timestamp: /* @__PURE__ */ new Date()
+	};
+	try {
+		await mutationsCollection(db, prefix).insertOne(doc);
+		return { mutationId };
+	} catch (err) {
+		log$1.warn("recordMutation failed", {
+			mutationId,
+			error: err
+		});
+		throw err;
+	}
+}
+//#endregion
 //#region src/memory/mongodb-structured-memory.ts
 const log = createSubsystemLogger("memory:mongodb:structured");
+function computeChangedFields(oldDoc, newDoc) {
+	const fields = /* @__PURE__ */ new Set();
+	const allKeys = new Set([...Object.keys(oldDoc), ...Object.keys(newDoc)]);
+	for (const key of allKeys) {
+		if (key === "_id" || key === "updatedAt" || key === "createdAt") continue;
+		if (JSON.stringify(oldDoc[key] ?? null) !== JSON.stringify(newDoc[key] ?? null)) fields.add(key);
+	}
+	return Array.from(fields);
+}
 function arraysEqual(left, right) {
 	const a = left ?? [];
 	const b = right ?? [];
@@ -149,8 +185,10 @@ async function writeStructuredMemory(params) {
 		type: entry.type,
 		key: entry.key
 	};
+	let existingBeforeWrite = null;
 	const persist = async (session) => {
 		const existing = await collection.findOne(identityFilter, session ? { session } : void 0);
+		existingBeforeWrite = existing;
 		if (!existing) {
 			const result = await collection.updateOne(identityFilter, {
 				$set: {
@@ -248,6 +286,24 @@ async function writeStructuredMemory(params) {
 		}
 	})() : await persist();
 	log.info(`structured memory ${outcome.upserted ? "created" : "updated"}: type=${entry.type} key=${entry.key} revision=${outcome.revision}`);
+	const oldSnapshot = existingBeforeWrite;
+	const changedFields = oldSnapshot != null ? computeChangedFields(oldSnapshot, setDoc) : void 0;
+	Promise.allSettled([recordMutation({
+		db,
+		prefix,
+		mutation: {
+			collectionName: "structured_mem",
+			documentId: entry.key,
+			operation: oldSnapshot == null ? "create" : "update",
+			agentId: entry.agentId,
+			oldValue: oldSnapshot ?? null,
+			newValue: setDoc,
+			changedFields,
+			actorRole: "system"
+		}
+	})]).catch((err) => {
+		log.warn(`structured memory audit failed: ${err instanceof Error ? err.message : String(err)}`);
+	});
 	return {
 		upserted: outcome.upserted,
 		id: outcome.id

package/dist/{mongodb-structured-memory-BySGexcm.js → mongodb-structured-memory-lpyyW0kn.js}

@@ -5,7 +5,7 @@ import "./theme-CdOoMzRk.js";
 import "./globals-41sdSaKv.js";
 import "./subsystem-VzQeL-96.js";
 import "./ansi-BEJF8NKS.js";
-import "./mongodb-schema-BI4Ze_ZV.js";
-import "./mongodb-search-VFKd72IZ.js";
-import { n as writeStructuredMemory } from "./mongodb-structured-memory-DnwUJ6SA.js";
+import "./mongodb-schema-Dt6jxcPL.js";
+import { n as writeStructuredMemory } from "./mongodb-structured-memory-D-3SEfTu.js";
+import "./mongodb-search-DMsUyfpa.js";
 export { writeStructuredMemory };