@xopcai/xopc 0.0.248 → 0.0.249

package/dist/src/knowledge/connected-knowledge-pipeline.js

@@ -1,40 +1,29 @@
 import { createLogger } from "../utils/logger/index.js";
 import { init_logger } from "../utils/logger.js";
-import { attachMemoryEvidence, claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, deleteMemoryEvidenceForRecord, listKnowledgeSourceItems, pruneBoundedKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
-import { deleteMemoryRecord, getMemoryRecord, upsertMemoryRecord } from "../storage/sqlite/memory-records-repository.js";
+import { claimKnowledgeSourceItems, completeKnowledgeSourceItemSynthesis, listKnowledgeSourceItems, pruneBoundedKnowledgeSourceItems } from "../storage/sqlite/knowledge-repository.js";
 import "../storage/sqlite/index.js";
-import { createHash, randomUUID } from "node:crypto";
+import { listKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem } from "../knowledge-memory/repository.js";
+import "../knowledge-memory/index.js";
+import { randomUUID } from "node:crypto";
 //#region src/knowledge/connected-knowledge-pipeline.ts
 init_logger();
 const log = createLogger("ConnectedKnowledge");
 const MAX_ITEM_CHARS = 8e3;
-const MAX_SUMMARY_CHARS = 6e3;
-const MAX_SUMMARY_ITEMS = 24;
 function providerId(item) {
 	const connectorId = item.metadata.connectorId;
-	if (typeof connectorId === "string" && connectorId.trim()) return connectorId.trim();
-	return item.sourceInstanceId.split(":")[0] || "connected-source";
+	return typeof connectorId === "string" && connectorId.trim() ? connectorId.trim() : item.sourceInstanceId.split(":")[0] || "connected-source";
 }
 function ownerAgentId(item, fallback) {
-	const agentId = item.metadata.agentId;
-	return typeof agentId === "string" && agentId.trim() ? agentId.trim() : fallback;
+	const value = item.metadata.agentId;
+	return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 function ownerWorkspaceId(item, fallback) {
-	const workspaceId = item.metadata.workspaceId;
-	return typeof workspaceId === "string" && workspaceId.trim() ? workspaceId.trim() : fallback;
-}
-function knowledgeRecordId(itemId) {
-	return `knowledge:${itemId}`;
+	const value = item.metadata.workspaceId;
+	return typeof value === "string" && value.trim() ? value.trim() : fallback;
 }
 function boundedText(item) {
-	const text = item.normalizedText?.trim() ?? "";
-	return text.length > MAX_ITEM_CHARS ? `${text.slice(0, MAX_ITEM_CHARS)}\n…` : text;
-}
-function dayFor(item) {
-	return (item.occurredAt ?? item.sourceUpdatedAt ?? item.updatedAt).slice(0, 10);
-}
-function summaryRecordId(sourceInstanceId, day) {
-	return `knowledge-summary:${createHash("sha256").update(`${sourceInstanceId}:${day}`).digest("hex").slice(0, 24)}`;
+	const value = item.normalizedText?.trim() ?? "";
+	return value.length > MAX_ITEM_CHARS ? `${value.slice(0, MAX_ITEM_CHARS)}\n…` : value;
 }
 var ConnectedKnowledgePipeline = class {
 	workerId;
@@ -58,51 +47,20 @@ var ConnectedKnowledgePipeline = class {
 			failed: 0,
 			recordIds: []
 		};
-		const summaryKeys = /* @__PURE__ */ new Set();
 		for (const item of claimed) try {
-			const recordId = knowledgeRecordId(item.id);
 			const content = boundedText(item);
+			const existing = listKnowledgeItems({
+				recordClass: "source_index",
+				limit: 2e3
+			}).find((entry) => entry.canonicalKey === `source-item:${item.sourceInstanceId}:${item.externalId}`);
 			if (item.deletedAt) {
-				const existing = getMemoryRecord(recordId);
-				if (existing) upsertMemoryRecord({
-					id: existing.id,
-					providerId: "connected-knowledge",
-					kind: existing.kind,
-					sourceAgentId: existing.provenance.sourceAgentId,
-					workspaceId: existing.scope.workspaceId,
-					content: existing.content,
-					source: existing.source,
-					confidence: existing.confidence,
-					tags: existing.tags,
-					status: "archived",
-					sensitivity: existing.sensitivity,
-					explicitness: existing.explicitness,
-					durability: existing.durability,
-					importance: existing.importance,
-					disclosurePolicy: existing.disclosurePolicy,
-					evidence: existing.evidence,
-					validFrom: existing.validFrom,
-					validTo: item.deletedAt,
-					reviewAfter: existing.reviewAfter,
-					expiresAt: existing.expiresAt,
-					canonicalKey: existing.canonicalKey,
-					supersedesRecordId: existing.supersedesRecordId,
-					conflictGroupId: existing.conflictGroupId,
-					originClass: existing.provenance.originClass,
-					sessionKind: existing.provenance.sessionKind,
-					observedAt: existing.provenance.observedAt,
-					sourceSessionId: existing.provenance.sourceSessionId,
-					sourceTurnId: existing.provenance.sourceTurnId,
-					supersedesKey: existing.provenance.supersedesKey,
-					derivedFromRecalledContext: existing.provenance.derivedFromRecalledContext
-				});
+				if (existing) setKnowledgeStatus(existing.id, "archived");
 				completeKnowledgeSourceItemSynthesis({
 					itemId: item.id,
 					workerId: this.workerId,
 					status: "ignored"
 				});
 				result.ignored += 1;
-				summaryKeys.add(`${item.sourceInstanceId}\u0000${dayFor(item)}`);
 				continue;
 			}
 			if (!content || item.sensitivity === "secret" || item.sensitivity === "regulated") {
@@ -114,53 +72,28 @@ var ConnectedKnowledgePipeline = class {
 				result.ignored += 1;
 				continue;
 			}
-			const sourceProvider = providerId(item);
-			const record = upsertMemoryRecord({
-				id: recordId,
-				providerId: "connected-knowledge",
+			const written = writeKnowledgeItem({
 				kind: "workspace_fact",
-				sourceAgentId: ownerAgentId(item, this.options.agentId),
-				workspaceId: ownerWorkspaceId(item, this.options.workspaceId),
+				scope: {
+					type: "workspace",
+					id: ownerWorkspaceId(item, this.options.workspaceId)
+				},
 				content,
 				canonicalKey: `source-item:${item.sourceInstanceId}:${item.externalId}`,
-				source: {
-					provider: sourceProvider,
-					sourceInstanceId: item.sourceInstanceId,
-					path: item.payloadRef
-				},
-				confidence: .78,
-				tags: [
-					"connected-source",
-					"external",
-					sourceProvider,
-					item.itemType
-				],
+				recordClass: "source_index",
 				status: "active",
-				sensitivity: item.sensitivity,
-				explicitness: "observed",
-				durability: item.retentionClass === "durable" ? "durable" : "recurring",
+				confidence: .78,
 				importance: .5,
-				disclosurePolicy: "referenceable",
-				evidence: [{
-					sourceItemId: item.id,
-					relation: "derived_from",
-					sourceText: content.slice(0, 1e3),
-					confidence: .78,
-					observedAt: item.occurredAt ?? item.sourceUpdatedAt
-				}],
-				validFrom: item.occurredAt ?? item.sourceUpdatedAt,
+				validFrom: Date.parse(item.occurredAt ?? item.sourceUpdatedAt ?? item.updatedAt),
 				originClass: "untrusted",
-				sessionKind: "background",
-				observedAt: item.occurredAt ?? item.sourceUpdatedAt ?? item.updatedAt,
-				derivedFromRecalledContext: false
-			});
-			attachMemoryEvidence({
-				recordId: record.id,
-				sourceItemId: item.id,
-				relation: "derived_from",
-				excerpt: content.slice(0, 1e3),
-				confidence: .78,
-				observedAt: item.occurredAt ?? item.sourceUpdatedAt
+				sourceAgentId: ownerAgentId(item, this.options.agentId),
+				source: {
+					provider: providerId(item),
+					sourceInstanceId: item.sourceInstanceId,
+					sourceItemId: item.id,
+					payloadRef: item.payloadRef
+				},
+				replaceExisting: true
 			});
 			completeKnowledgeSourceItemSynthesis({
 				itemId: item.id,
@@ -168,30 +101,24 @@ var ConnectedKnowledgePipeline = class {
 				status: "completed"
 			});
 			result.completed += 1;
-			result.recordIds.push(record.id);
-			summaryKeys.add(`${item.sourceInstanceId}\u0000${dayFor(item)}`);
-		} catch (err) {
-			const errorMessage = err instanceof Error ? err.message : String(err);
+			result.recordIds.push(written.item.id);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
 			completeKnowledgeSourceItemSynthesis({
 				itemId: item.id,
 				workerId: this.workerId,
 				status: "failed",
-				error: errorMessage.slice(0, 1e3)
+				error: message.slice(0, 1e3)
 			});
 			result.failed += 1;
 			log.warn({
-				err,
+				err: error,
 				itemId: item.id,
 				sourceInstanceId: item.sourceInstanceId
-			}, `Connected knowledge synthesis failed: ${errorMessage}`);
-		}
-		for (const key of summaryKeys) {
-			const [sourceInstanceId, day] = key.split("\0");
-			if (sourceInstanceId && day) this.rebuildDailySummary(sourceInstanceId, day);
+			}, `Connected knowledge synthesis failed: ${message}`);
 		}
 		return result;
 	}
-	/** Remove bounded raw items and every content-bearing memory derived only from them. */
 	pruneBoundedRetention(sourceInstanceId, olderThanMs) {
 		const expired = [];
 		for (let offset = 0;; offset += 500) {
@@ -206,117 +133,19 @@ var ConnectedKnowledgePipeline = class {
 			expired.push(...page);
 			if (page.length < 500) break;
 		}
-		if (!expired.length) return {
-			rawDeleted: 0,
-			derivedDeleted: 0
-		};
-		const affectedDays = new Set(expired.map(dayFor));
 		let derivedDeleted = 0;
-		for (const item of expired) if (deleteMemoryRecord(knowledgeRecordId(item.id))) derivedDeleted += 1;
-		const rawDeleted = pruneBoundedKnowledgeSourceItems(sourceInstanceId, olderThanMs);
-		for (const day of affectedDays) if (this.rebuildDailySummary(sourceInstanceId, day, true)) derivedDeleted += 1;
+		const expiredIds = new Set(expired.map((item) => item.id));
+		for (const item of listKnowledgeItems({
+			recordClass: "source_index",
+			limit: 2e3
+		})) if (typeof item.source.sourceItemId === "string" && expiredIds.has(item.source.sourceItemId)) {
+			if (setKnowledgeStatus(item.id, "archived")) derivedDeleted += 1;
+		}
 		return {
-			rawDeleted,
+			rawDeleted: pruneBoundedKnowledgeSourceItems(sourceInstanceId, olderThanMs),
 			derivedDeleted
 		};
 	}
-	rebuildDailySummary(sourceInstanceId, day, deleteWhenEmpty = false) {
-		const items = listKnowledgeSourceItems({
-			sourceInstanceId,
-			limit: 500
-		}).filter((item) => dayFor(item) === day && item.synthesisStatus === "completed").slice(0, MAX_SUMMARY_ITEMS);
-		if (items.length === 0) {
-			const existing = getMemoryRecord(summaryRecordId(sourceInstanceId, day));
-			if (existing && deleteWhenEmpty) return deleteMemoryRecord(existing.id);
-			if (existing) upsertMemoryRecord({
-				id: existing.id,
-				providerId: "connected-knowledge",
-				kind: existing.kind,
-				sourceAgentId: existing.provenance.sourceAgentId,
-				workspaceId: existing.scope.workspaceId,
-				content: existing.content,
-				source: existing.source,
-				confidence: existing.confidence,
-				tags: existing.tags,
-				status: "archived",
-				sensitivity: existing.sensitivity,
-				explicitness: existing.explicitness,
-				durability: existing.durability,
-				importance: existing.importance,
-				disclosurePolicy: existing.disclosurePolicy,
-				evidence: existing.evidence,
-				validFrom: existing.validFrom,
-				validTo: (/* @__PURE__ */ new Date()).toISOString(),
-				reviewAfter: existing.reviewAfter,
-				expiresAt: existing.expiresAt,
-				canonicalKey: existing.canonicalKey,
-				originClass: existing.provenance.originClass,
-				sessionKind: existing.provenance.sessionKind,
-				observedAt: existing.provenance.observedAt,
-				sourceSessionId: existing.provenance.sourceSessionId,
-				sourceTurnId: existing.provenance.sourceTurnId,
-				supersedesKey: existing.provenance.supersedesKey,
-				derivedFromRecalledContext: existing.provenance.derivedFromRecalledContext
-			});
-			return false;
-		}
-		const sourceProvider = providerId(items[0]);
-		const lines = [`# ${sourceProvider} updates for ${day}`, ""];
-		for (const item of items) {
-			const text = boundedText(item).replace(/\s+/g, " ").trim();
-			if (!text) continue;
-			lines.push(`- ${text.slice(0, 360)}`);
-			if (lines.join("\n").length >= MAX_SUMMARY_CHARS) break;
-		}
-		const content = lines.join("\n").slice(0, MAX_SUMMARY_CHARS);
-		const summary = upsertMemoryRecord({
-			id: summaryRecordId(sourceInstanceId, day),
-			providerId: "connected-knowledge",
-			kind: "daily_note",
-			sourceAgentId: ownerAgentId(items[0], this.options.agentId),
-			workspaceId: ownerWorkspaceId(items[0], this.options.workspaceId),
-			content,
-			canonicalKey: `source-day:${sourceInstanceId}:${day}`,
-			source: {
-				provider: sourceProvider,
-				sourceInstanceId
-			},
-			confidence: .72,
-			tags: [
-				"connected-source",
-				"source-day-summary",
-				sourceProvider
-			],
-			status: "active",
-			sensitivity: items.some((item) => item.sensitivity === "personal") ? "personal" : "normal",
-			explicitness: "observed",
-			durability: "recurring",
-			importance: .55,
-			disclosurePolicy: "referenceable",
-			evidence: items.map((item) => ({
-				sourceItemId: item.id,
-				relation: "derived_from",
-				sourceText: boundedText(item).slice(0, 500),
-				confidence: .72,
-				observedAt: item.occurredAt ?? item.sourceUpdatedAt
-			})),
-			validFrom: `${day}T00:00:00.000Z`,
-			originClass: "untrusted",
-			sessionKind: "background",
-			observedAt: items.map((item) => item.occurredAt ?? item.sourceUpdatedAt ?? item.updatedAt).sort().at(-1),
-			derivedFromRecalledContext: false
-		});
-		deleteMemoryEvidenceForRecord(summary.id, "derived_from");
-		for (const item of items) attachMemoryEvidence({
-			recordId: summary.id,
-			sourceItemId: item.id,
-			relation: "derived_from",
-			excerpt: boundedText(item).slice(0, 500),
-			confidence: .72,
-			observedAt: item.occurredAt ?? item.sourceUpdatedAt
-		});
-		return false;
-	}
 };
 //#endregion
 export { ConnectedKnowledgePipeline };

package/dist/src/knowledge-memory/domain.d.ts

@@ -0,0 +1,35 @@
+import type { UserModelScope } from '../user-model/domain.js';
+export type KnowledgeKind = 'project_fact' | 'workspace_fact' | 'decision' | 'task_lesson' | 'commitment' | 'open_question' | 'episode' | 'note';
+export type KnowledgeStatus = 'candidate' | 'active' | 'needs_review' | 'stale' | 'archived' | 'rejected';
+export type KnowledgeOriginClass = 'owner' | 'agent' | 'system' | 'untrusted';
+export type KnowledgeRecordClass = 'memory' | 'source_index';
+export interface KnowledgeItem {
+    id: string;
+    principalId: string;
+    kind: KnowledgeKind;
+    scope: UserModelScope;
+    content: string;
+    canonicalKey: string;
+    recordClass: KnowledgeRecordClass;
+    status: KnowledgeStatus;
+    confidence: number;
+    importance: number;
+    validFrom?: number;
+    validTo?: number;
+    expiresAt?: number;
+    reviewAt?: number;
+    originClass: KnowledgeOriginClass;
+    sourceAgentId?: string;
+    sourceSessionId?: string;
+    sourceTurnId?: string;
+    derivedFromRecalledContext: boolean;
+    source: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface KnowledgeVisibilityContext {
+    agentId: string;
+    workspaceId: string;
+    projectId?: string;
+    sessionId: string;
+}

package/dist/src/knowledge-memory/index.d.ts

@@ -0,0 +1,2 @@
+export * from './domain.js';
+export * from './repository.js';

package/dist/src/knowledge-memory/index.js

@@ -0,0 +1,2 @@
+import { getKnowledgeItem, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem } from "./repository.js";
+export { getKnowledgeItem, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem };

package/dist/src/knowledge-memory/repository.d.ts

@@ -0,0 +1,45 @@
+import { type UserModelScope } from '../user-model/domain.js';
+import type { KnowledgeItem, KnowledgeKind, KnowledgeOriginClass, KnowledgeRecordClass, KnowledgeStatus, KnowledgeVisibilityContext } from './domain.js';
+export interface WriteKnowledgeInput {
+    principalId?: string;
+    kind: KnowledgeKind;
+    scope: UserModelScope;
+    content: string;
+    canonicalKey: string;
+    recordClass?: KnowledgeRecordClass;
+    status?: KnowledgeStatus;
+    confidence: number;
+    importance: number;
+    validFrom?: number;
+    validTo?: number;
+    expiresAt?: number;
+    reviewAt?: number;
+    originClass: KnowledgeOriginClass;
+    sourceAgentId?: string;
+    sourceSessionId?: string;
+    sourceTurnId?: string;
+    derivedFromRecalledContext?: boolean;
+    source?: Record<string, unknown>;
+    replaceExisting?: boolean;
+    now?: number;
+}
+export declare function writeKnowledgeItem(input: WriteKnowledgeInput): {
+    item: KnowledgeItem;
+    created: boolean;
+};
+export declare function getKnowledgeItem(id: string): KnowledgeItem | undefined;
+export declare function listKnowledgeItems(input?: {
+    principalId?: string;
+    statuses?: KnowledgeStatus[];
+    recordClass?: KnowledgeRecordClass;
+    limit?: number;
+}): KnowledgeItem[];
+export declare function setKnowledgeStatus(id: string, status: KnowledgeStatus, now?: number): KnowledgeItem | undefined;
+export declare function searchKnowledgeItems(input: {
+    query: string;
+    context: KnowledgeVisibilityContext;
+    principalId?: string;
+    asOf?: number;
+    recordClass?: KnowledgeRecordClass;
+    limit?: number;
+}): KnowledgeItem[];

package/dist/src/knowledge-memory/repository.js

@@ -0,0 +1,154 @@
+import { getSqliteDatabase, runSqliteWriteTransaction } from "../storage/sqlite/transaction.js";
+import { validateScope } from "../user-model/domain.js";
+import { buildFts5SearchQuery } from "../storage/sqlite/fts.js";
+import { randomUUID } from "node:crypto";
+//#region src/knowledge-memory/repository.ts
+function fromRow(row) {
+	return {
+		id: row.knowledge_id,
+		principalId: row.principal_id,
+		kind: row.kind,
+		scope: {
+			type: row.scope_type,
+			...row.scope_id ? { id: row.scope_id } : {}
+		},
+		content: row.content,
+		canonicalKey: row.canonical_key,
+		recordClass: row.record_class,
+		status: row.status,
+		confidence: row.confidence,
+		importance: row.importance,
+		...row.valid_from === null ? {} : { validFrom: row.valid_from },
+		...row.valid_to === null ? {} : { validTo: row.valid_to },
+		...row.expires_at === null ? {} : { expiresAt: row.expires_at },
+		...row.review_at === null ? {} : { reviewAt: row.review_at },
+		originClass: row.origin_class,
+		...row.source_agent_id ? { sourceAgentId: row.source_agent_id } : {},
+		...row.source_session_id ? { sourceSessionId: row.source_session_id } : {},
+		...row.source_turn_id ? { sourceTurnId: row.source_turn_id } : {},
+		derivedFromRecalledContext: row.derived_from_recalled_context === 1,
+		source: JSON.parse(row.source_json),
+		createdAt: row.created_at,
+		updatedAt: row.updated_at
+	};
+}
+function bounded(value, field) {
+	if (!Number.isFinite(value) || value < 0 || value > 1) throw new Error(`${field} must be between 0 and 1.`);
+}
+function writeKnowledgeItem(input) {
+	validateScope(input.scope);
+	bounded(input.confidence, "confidence");
+	bounded(input.importance, "importance");
+	if (!input.content.trim()) throw new Error("Knowledge content is required.");
+	if (!input.canonicalKey.trim()) throw new Error("Knowledge canonical key is required.");
+	if (input.validFrom !== void 0 && input.validTo !== void 0 && input.validTo < input.validFrom) throw new Error("Knowledge validTo must be greater than or equal to validFrom.");
+	const principalId = input.principalId ?? "local-owner";
+	const now = input.now ?? Date.now();
+	return runSqliteWriteTransaction((db) => {
+		const existingStatuses = input.replaceExisting ? [
+			"candidate",
+			"active",
+			"needs_review",
+			"stale",
+			"archived"
+		] : [
+			"candidate",
+			"active",
+			"needs_review",
+			"stale"
+		];
+		const existing = db.prepare(`SELECT * FROM knowledge_items WHERE principal_id = ?
+      AND canonical_key = ? AND scope_type = ? AND COALESCE(scope_id, '') = COALESCE(?, '')
+      AND status IN (${existingStatuses.map(() => "?").join(", ")})`).get(principalId, input.canonicalKey.trim(), input.scope.type, input.scope.id ?? null, ...existingStatuses);
+		if (existing && !input.replaceExisting) return {
+			item: fromRow(existing),
+			created: false
+		};
+		if (existing) {
+			db.prepare(`UPDATE knowledge_items SET kind = ?, content = ?, record_class = ?, status = ?, confidence = ?,
+        importance = ?, valid_from = ?, valid_to = ?, expires_at = ?, review_at = ?,
+        origin_class = ?, source_agent_id = ?, source_session_id = ?, source_turn_id = ?,
+        derived_from_recalled_context = ?, source_json = ?, updated_at = ? WHERE knowledge_id = ?`).run(input.kind, input.content.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceSessionId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, existing.knowledge_id);
+			db.prepare("DELETE FROM knowledge_items_fts WHERE knowledge_id = ?").run(existing.knowledge_id);
+			db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), existing.knowledge_id);
+			return {
+				item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(existing.knowledge_id)),
+				created: false
+			};
+		}
+		const id = randomUUID();
+		db.prepare(`INSERT INTO knowledge_items (
+      knowledge_id, principal_id, kind, scope_type, scope_id, content, canonical_key, record_class,
+      status, confidence, importance, valid_from, valid_to, expires_at, review_at,
+      origin_class, source_agent_id, source_session_id, source_turn_id,
+      derived_from_recalled_context, source_json, created_at, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, principalId, input.kind, input.scope.type, input.scope.id ?? null, input.content.trim(), input.canonicalKey.trim(), input.recordClass ?? "memory", input.status ?? (input.originClass === "owner" ? "active" : "candidate"), input.confidence, input.importance, input.validFrom ?? null, input.validTo ?? null, input.expiresAt ?? null, input.reviewAt ?? null, input.originClass, input.sourceAgentId ?? null, input.sourceSessionId ?? null, input.sourceTurnId ?? null, input.derivedFromRecalledContext ? 1 : 0, JSON.stringify(input.source ?? {}), now, now);
+		db.prepare("INSERT INTO knowledge_items_fts(content, knowledge_id) VALUES (?, ?)").run(input.content.trim(), id);
+		return {
+			item: fromRow(db.prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(id)),
+			created: true
+		};
+	});
+}
+function getKnowledgeItem(id) {
+	const row = getSqliteDatabase().prepare("SELECT * FROM knowledge_items WHERE knowledge_id = ?").get(id);
+	return row ? fromRow(row) : void 0;
+}
+function listKnowledgeItems(input = {}) {
+	const statuses = input.statuses ?? [
+		"active",
+		"candidate",
+		"needs_review",
+		"stale"
+	];
+	if (!statuses.length) return [];
+	const placeholders = statuses.map(() => "?").join(", ");
+	return getSqliteDatabase().prepare(`SELECT * FROM knowledge_items
+    WHERE principal_id = ? AND status IN (${placeholders})
+      ${input.recordClass ? "AND record_class = ?" : ""}
+    ORDER BY importance DESC, updated_at DESC LIMIT ?`).all(input.principalId ?? "local-owner", ...statuses, ...input.recordClass ? [input.recordClass] : [], Math.max(1, Math.min(2e3, input.limit ?? 200))).map(fromRow);
+}
+function setKnowledgeStatus(id, status, now = Date.now()) {
+	return getSqliteDatabase().prepare(`UPDATE knowledge_items SET status = ?, updated_at = ?
+    WHERE knowledge_id = ?`).run(status, now, id).changes ? getKnowledgeItem(id) : void 0;
+}
+function visibilityClause(context) {
+	const parts = [
+		"k.scope_type = 'global'",
+		"(k.scope_type = 'agent' AND k.scope_id = ?)",
+		"(k.scope_type = 'workspace' AND k.scope_id = ?)",
+		"(k.scope_type = 'session' AND k.scope_id = ?)"
+	];
+	const values = [
+		context.agentId ?? "",
+		context.workspaceId ?? "",
+		context.sessionId ?? ""
+	];
+	if (context.projectId) {
+		parts.push("(k.scope_type = 'project' AND k.scope_id = ?)");
+		values.push(context.projectId);
+	}
+	return {
+		sql: `(${parts.join(" OR ")})`,
+		values
+	};
+}
+function searchKnowledgeItems(input) {
+	const principalId = input.principalId ?? "local-owner";
+	const asOf = input.asOf ?? Date.now();
+	const limit = Math.max(1, Math.min(100, input.limit ?? 12));
+	const visible = visibilityClause(input.context);
+	const fts = buildFts5SearchQuery(input.query);
+	if (!fts) return [];
+	return getSqliteDatabase().prepare(`SELECT k.*, bm25(knowledge_items_fts) AS rank
+    FROM knowledge_items_fts JOIN knowledge_items k ON k.knowledge_id = knowledge_items_fts.knowledge_id
+    WHERE knowledge_items_fts MATCH ? AND k.principal_id = ? AND k.status = 'active'
+      AND (k.valid_from IS NULL OR k.valid_from <= ?)
+      AND (k.valid_to IS NULL OR k.valid_to >= ?)
+      AND (k.expires_at IS NULL OR k.expires_at >= ?)
+      ${input.recordClass ? "AND k.record_class = ?" : ""}
+      AND ${visible.sql}
+    ORDER BY rank ASC, k.importance DESC, k.updated_at DESC LIMIT ?`).all(fts, principalId, asOf, asOf, asOf, ...input.recordClass ? [input.recordClass] : [], ...visible.values, limit).map(fromRow);
+}
+//#endregion
+export { getKnowledgeItem, listKnowledgeItems, searchKnowledgeItems, setKnowledgeStatus, writeKnowledgeItem };

package/dist/src/memory-maintenance/index.d.ts

@@ -0,0 +1,2 @@
+export * from './schedule.js';
+export * from './service.js';

package/dist/src/memory-maintenance/index.js

@@ -0,0 +1,3 @@
+import { MEMORY_MAINTENANCE_TOKEN, maintenanceInstruction, parseMaintenanceInstruction, resolveMemoryMaintenanceSchedules } from "./schedule.js";
+import { listMemoryMaintenanceRuns, runMemoryMaintenance } from "./service.js";
+export { MEMORY_MAINTENANCE_TOKEN, listMemoryMaintenanceRuns, maintenanceInstruction, parseMaintenanceInstruction, resolveMemoryMaintenanceSchedules, runMemoryMaintenance };

package/dist/src/memory-maintenance/schedule.d.ts

@@ -0,0 +1,13 @@
+import type { Config } from '../config/schema.js';
+import type { MemoryMaintenanceJob } from './service.js';
+export declare const MEMORY_MAINTENANCE_TOKEN = "__xopc_memory_maintenance__";
+export interface MemoryMaintenanceSchedule {
+    jobType: Exclude<MemoryMaintenanceJob, 'manual_repair'>;
+    automationId: string;
+    name: string;
+    cron: string;
+    timezone: string;
+}
+export declare function resolveMemoryMaintenanceSchedules(config: Config): MemoryMaintenanceSchedule[];
+export declare function maintenanceInstruction(jobType: MemoryMaintenanceSchedule['jobType']): string;
+export declare function parseMaintenanceInstruction(value: string): MemoryMaintenanceSchedule['jobType'] | undefined;

package/dist/src/memory-maintenance/schedule.js

@@ -0,0 +1,51 @@
+//#region src/memory-maintenance/schedule.ts
+const MEMORY_MAINTENANCE_TOKEN = "__xopc_memory_maintenance__";
+const WEEKDAY = {
+	sun: 0,
+	mon: 1,
+	tue: 2,
+	wed: 3,
+	thu: 4,
+	fri: 5,
+	sat: 6
+};
+function cronAt(time, weekday) {
+	const [hour, minute] = time.split(":").map(Number);
+	return `${minute} ${hour} * * ${weekday ?? "*"}`;
+}
+function resolveMemoryMaintenanceSchedules(config) {
+	const maintenance = config.userContext.userModel.maintenance;
+	if (!config.userContext.enabled || !config.userContext.userModel.enabled || !maintenance.enabled) return [];
+	const timezone = maintenance.timezone ?? Intl.DateTimeFormat().resolvedOptions().timeZone ?? "UTC";
+	return [
+		{
+			jobType: "temporal_sweep",
+			automationId: "system-memory-temporal-sweep",
+			name: "Memory temporal sweep",
+			cron: `*/${maintenance.temporalSweepMinutes} * * * *`,
+			timezone
+		},
+		{
+			jobType: "daily_reconciliation",
+			automationId: "system-memory-daily-reconciliation",
+			name: "Memory daily reconciliation",
+			cron: cronAt(maintenance.dailyTime),
+			timezone
+		},
+		{
+			jobType: "weekly_knowledge",
+			automationId: "system-memory-weekly-knowledge",
+			name: "Memory weekly knowledge maintenance",
+			cron: cronAt(maintenance.weeklyTime, WEEKDAY[maintenance.weeklyDay]),
+			timezone
+		}
+	];
+}
+function maintenanceInstruction(jobType) {
+	return `${MEMORY_MAINTENANCE_TOKEN}:${jobType}`;
+}
+function parseMaintenanceInstruction(value) {
+	return new RegExp(`${MEMORY_MAINTENANCE_TOKEN}:(temporal_sweep|daily_reconciliation|weekly_knowledge)`).exec(value)?.[1];
+}
+//#endregion
+export { MEMORY_MAINTENANCE_TOKEN, maintenanceInstruction, parseMaintenanceInstruction, resolveMemoryMaintenanceSchedules };