@xopcai/xopc 0.0.116 → 0.0.118

package/dist/src/agent/memory/memory-config.js

@@ -1,26 +1,30 @@
 import { init_agent_scope, resolveAgentHomeDir, resolveAgentIdForWorkspacePath } from "../agent-scope.js";
+import { resolveEffectiveAgentManifestForAgent } from "../../config/agent-profile.js";
+import { init_paths, resolveUserMemoryPath } from "../../config/paths.js";
 import { join } from "node:path";
 //#region src/agent/memory/memory-config.ts
+init_paths();
 init_agent_scope();
 /** When false, curated `memories/` (under agent home) + external memory providers are off. */
 function isMemorySubsystemEnabled(config) {
-	return config?.agents?.defaults?.memory?.enabled !== false;
+	if (!config) return true;
+	return config.agents.list.some((agent) => agent.enabled !== false && agent.memory.mode !== "off");
 }
 /** Curated memory tool + agent-home `memories/` store (not injected into system prompt). */
 function isCuratedMemoryInPrompt(config) {
-	const m = config?.agents?.defaults?.memory;
-	if (m?.enabled === false) return false;
-	if (m?.useEnhancedSystem === false) return false;
-	return true;
+	if (!config) return true;
+	return config.agents.list.some((agent) => agent.enabled !== false && agent.memory.sources.includes("curated"));
 }
 function resolveBuiltinMemoryStoreConfig(workspaceDir, config) {
-	const m = config?.agents?.defaults?.memory;
+	const agentId = config != null ? resolveAgentIdForWorkspacePath(config, workspaceDir) : void 0;
+	const manifest = config && agentId ? resolveEffectiveAgentManifestForAgent(config, agentId) : void 0;
 	return {
 		workspaceDir,
-		memoriesDir: config != null ? join(resolveAgentHomeDir(config, resolveAgentIdForWorkspacePath(config, workspaceDir)), "memories") : join(workspaceDir, "memories"),
-		memoryCharLimit: m?.memoryCharLimit ?? 2200,
-		userCharLimit: m?.userCharLimit ?? 1375,
-		userProfileEnabled: m?.userProfileEnabled !== false
+		memoriesDir: config != null ? join(resolveAgentHomeDir(config, agentId ?? "main"), "memories") : join(workspaceDir, "memories"),
+		userMemoryPath: config != null ? resolveUserMemoryPath() : join(workspaceDir, "user", "MEMORY.md"),
+		memoryCharLimit: manifest?.memory.retention?.maxItems ?? 2200,
+		userCharLimit: 1375,
+		userProfileEnabled: manifest?.memory.sources.includes("userProfile") ?? true
 	};
 }
 /**
@@ -28,11 +32,7 @@ function resolveBuiltinMemoryStoreConfig(workspaceDir, config) {
 * `first-turn` only injects on turn 1. `contextCadence` N injects on turns 1, N+1, 2N+1, …
 */
 function shouldInjectMemoryPrefetchThisTurn(config, turnNumber) {
-	const m = config?.agents?.defaults?.memory;
-	if ((m?.injectionFrequency ?? "every-turn") === "first-turn") return turnNumber === 1;
-	const cadence = m?.contextCadence ?? 1;
-	if (cadence <= 1) return true;
-	return (turnNumber - 1) % cadence === 0;
+	return turnNumber >= 1;
 }
 function shouldRegisterCuratedMemoryTool(config) {
 	return isCuratedMemoryInPrompt(config);

package/dist/src/agent/memory/memory-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-config.js","names":[],"sources":["../../../../src/agent/memory/memory-config.ts"],"sourcesContent":["import { join } from 'node:path';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveAgentHomeDir, resolveAgentIdForWorkspacePath } from '../agent-scope.js';\n\nimport type { MemoryStoreConfig } from './types.js';\n\n/** When false, curated `memories/` (under agent home) + external memory providers are off. */\nexport function isMemorySubsystemEnabled(config: Config | undefined): boolean {\n  return config?.agents?.defaults?.memory?.enabled !== false;\n}\n\n/** Curated memory tool + agent-home `memories/` store (not injected into system prompt). */\nexport function isCuratedMemoryInPrompt(config: Config | undefined): boolean {\n  const m = config?.agents?.defaults?.memory;\n  if (m?.enabled === false) {\n    return false;\n  }\n  if (m?.useEnhancedSystem === false) {\n    return false;\n  }\n  return true;\n}\n\nexport function resolveBuiltinMemoryStoreConfig(\n  workspaceDir: string,\n  config: Config | undefined,\n): MemoryStoreConfig {\n  const m = config?.agents?.defaults?.memory;\n  const memoriesDir =\n    config != null\n      ? join(\n          resolveAgentHomeDir(config, resolveAgentIdForWorkspacePath(config, workspaceDir)),\n          'memories',\n        )\n      : join(workspaceDir, 'memories');\n  return {\n    workspaceDir,\n    memoriesDir,\n    memoryCharLimit: m?.memoryCharLimit ?? 2200,\n    userCharLimit: m?.userCharLimit ?? 1375,\n    userProfileEnabled: m?.userProfileEnabled !== false,\n  };\n}\n\n/**\n * Whether to prefix the user message with prefetched external memory this turn.\n * `first-turn` only injects on turn 1. `contextCadence` N injects on turns 1, N+1, 2N+1, …\n */\nexport function shouldInjectMemoryPrefetchThisTurn(\n  config: Config | undefined,\n  turnNumber: number,\n): boolean {\n  const m = config?.agents?.defaults?.memory;\n  const freq = m?.injectionFrequency ?? 'every-turn';\n  if (freq === 'first-turn') {\n    return turnNumber === 1;\n  }\n  const cadence = m?.contextCadence ?? 1;\n  if (cadence <= 1) {\n    return true;\n  }\n  return (turnNumber - 1) % cadence === 0;\n}\n\nexport function shouldRegisterCuratedMemoryTool(config: Config | undefined): boolean {\n  return isCuratedMemoryInPrompt(config);\n}\n"],"mappings":";;;kBAGwF;;AAKxF,SAAgB,yBAAyB,QAAqC;AAC5E,QAAO,QAAQ,QAAQ,UAAU,QAAQ,YAAY;;;AAIvD,SAAgB,wBAAwB,QAAqC;CAC3E,MAAM,IAAI,QAAQ,QAAQ,UAAU;AACpC,KAAI,GAAG,YAAY,MACjB,QAAO;AAET,KAAI,GAAG,sBAAsB,MAC3B,QAAO;AAET,QAAO;;AAGT,SAAgB,gCACd,cACA,QACmB;CACnB,MAAM,IAAI,QAAQ,QAAQ,UAAU;AAQpC,QAAO;EACL;EACA,aARA,UAAU,OACN,KACE,oBAAoB,QAAQ,+BAA+B,QAAQ,aAAa,CAAC,EACjF,WACD,GACD,KAAK,cAAc,WAAW;EAIlC,iBAAiB,GAAG,mBAAmB;EACvC,eAAe,GAAG,iBAAiB;EACnC,oBAAoB,GAAG,uBAAuB;EAC/C;;;;;;AAOH,SAAgB,mCACd,QACA,YACS;CACT,MAAM,IAAI,QAAQ,QAAQ,UAAU;AAEpC,MADa,GAAG,sBAAsB,kBACzB,aACX,QAAO,eAAe;CAExB,MAAM,UAAU,GAAG,kBAAkB;AACrC,KAAI,WAAW,EACb,QAAO;AAET,SAAQ,aAAa,KAAK,YAAY;;AAGxC,SAAgB,gCAAgC,QAAqC;AACnF,QAAO,wBAAwB,OAAO"}
+{"version":3,"file":"memory-config.js","names":[],"sources":["../../../../src/agent/memory/memory-config.ts"],"sourcesContent":["import { join } from 'node:path';\n\nimport type { Config } from '../../config/schema.js';\nimport { resolveUserMemoryPath } from '../../config/paths.js';\nimport { resolveEffectiveAgentManifestForAgent } from '../../config/agent-profile.js';\nimport { resolveAgentHomeDir, resolveAgentIdForWorkspacePath } from '../agent-scope.js';\n\nimport type { MemoryStoreConfig } from './types.js';\n\n/** When false, curated `memories/` (under agent home) + external memory providers are off. */\nexport function isMemorySubsystemEnabled(config: Config | undefined): boolean {\n  if (!config) return true;\n  return config.agents.list.some((agent) => agent.enabled !== false && agent.memory.mode !== 'off');\n}\n\n/** Curated memory tool + agent-home `memories/` store (not injected into system prompt). */\nexport function isCuratedMemoryInPrompt(config: Config | undefined): boolean {\n  if (!config) return true;\n  return config.agents.list.some((agent) => agent.enabled !== false && agent.memory.sources.includes('curated'));\n}\n\nexport function resolveBuiltinMemoryStoreConfig(\n  workspaceDir: string,\n  config: Config | undefined,\n): MemoryStoreConfig {\n  const agentId = config != null ? resolveAgentIdForWorkspacePath(config, workspaceDir) : undefined;\n  const manifest = config && agentId ? resolveEffectiveAgentManifestForAgent(config, agentId) : undefined;\n  const memoriesDir =\n    config != null\n      ? join(\n          resolveAgentHomeDir(config, agentId ?? 'main'),\n          'memories',\n        )\n      : join(workspaceDir, 'memories');\n  return {\n    workspaceDir,\n    memoriesDir,\n    userMemoryPath: config != null ? resolveUserMemoryPath() : join(workspaceDir, 'user', 'MEMORY.md'),\n    memoryCharLimit: manifest?.memory.retention?.maxItems ?? 2200,\n    userCharLimit: 1375,\n    userProfileEnabled: manifest?.memory.sources.includes('userProfile') ?? true,\n  };\n}\n\n/**\n * Whether to prefix the user message with prefetched external memory this turn.\n * `first-turn` only injects on turn 1. `contextCadence` N injects on turns 1, N+1, 2N+1, …\n */\nexport function shouldInjectMemoryPrefetchThisTurn(\n  config: Config | undefined,\n  turnNumber: number,\n): boolean {\n  return turnNumber >= 1;\n}\n\nexport function shouldRegisterCuratedMemoryTool(config: Config | undefined): boolean {\n  return isCuratedMemoryInPrompt(config);\n}\n"],"mappings":";;;;;YAG8D;kBAE0B;;AAKxF,SAAgB,yBAAyB,QAAqC;AAC5E,KAAI,CAAC,OAAQ,QAAO;AACpB,QAAO,OAAO,OAAO,KAAK,MAAM,UAAU,MAAM,YAAY,SAAS,MAAM,OAAO,SAAS,MAAM;;;AAInG,SAAgB,wBAAwB,QAAqC;AAC3E,KAAI,CAAC,OAAQ,QAAO;AACpB,QAAO,OAAO,OAAO,KAAK,MAAM,UAAU,MAAM,YAAY,SAAS,MAAM,OAAO,QAAQ,SAAS,UAAU,CAAC;;AAGhH,SAAgB,gCACd,cACA,QACmB;CACnB,MAAM,UAAU,UAAU,OAAO,+BAA+B,QAAQ,aAAa,GAAG,KAAA;CACxF,MAAM,WAAW,UAAU,UAAU,sCAAsC,QAAQ,QAAQ,GAAG,KAAA;AAQ9F,QAAO;EACL;EACA,aARA,UAAU,OACN,KACE,oBAAoB,QAAQ,WAAW,OAAO,EAC9C,WACD,GACD,KAAK,cAAc,WAAW;EAIlC,gBAAgB,UAAU,OAAO,uBAAuB,GAAG,KAAK,cAAc,QAAQ,YAAY;EAClG,iBAAiB,UAAU,OAAO,WAAW,YAAY;EACzD,eAAe;EACf,oBAAoB,UAAU,OAAO,QAAQ,SAAS,cAAc,IAAI;EACzE;;;;;;AAOH,SAAgB,mCACd,QACA,YACS;AACT,QAAO,cAAc;;AAGvB,SAAgB,gCAAgC,QAAqC;AACnF,QAAO,wBAAwB,OAAO"}

package/dist/src/agent/memory/memory-flush.js

@@ -1,8 +1,8 @@
 import { createLogger } from "../../utils/logger/index.js";
 import { init_logger } from "../../utils/logger.js";
+import { join } from "node:path";
 import { existsSync } from "node:fs";
 import { appendFile, mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 //#region src/agent/memory/memory-flush.ts
 init_logger();
 const log = createLogger("MemoryFlush");

package/dist/src/agent/memory/plugin-discovery.d.ts

@@ -1,10 +1,24 @@
-/**
- * Discover optional `plugins/memory/<name>/` packages (extension point).
- * Compiled layout: `dist/src/plugins/memory/...` relative to this module.
- */
+import type { Config } from '../../config/schema.js';
+import type { DiscoveredExtension } from '../../extensions/types/loader.js';
+import type { MemoryProvider } from './provider.js';
+import type { MemoryProviderManifest } from './types.js';
 export interface MemoryPluginMetadata {
     name: string;
     description: string;
     available: boolean;
+    manifest?: MemoryProviderManifest;
 }
-export declare function discoverMemoryPlugins(): Promise<MemoryPluginMetadata[]>;
+export interface MemoryPluginProviderContext {
+    config?: Config;
+    manifest?: MemoryProviderManifest;
+    extension?: {
+        id: string;
+        path: string;
+        source: DiscoveredExtension['source'];
+        config?: Record<string, unknown>;
+    };
+}
+export declare function discoverMemoryPlugins(config?: Config): Promise<MemoryPluginMetadata[]>;
+export declare function loadMemoryPluginProviders(params?: {
+    config?: Config;
+}): Promise<MemoryProvider[]>;

package/dist/src/agent/memory/plugin-discovery.js

@@ -1,39 +1,105 @@
-import { readdir, stat } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { discoverExtensionsFromDisk, init_discover_extensions } from "../../extensions/discover-extensions.js";
+import { isAbsolute, join } from "node:path";
+import { stat } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
 //#region src/agent/memory/plugin-discovery.ts
-async function discoverMemoryPlugins() {
-	const pluginsDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "plugins", "memory");
-	try {
-		const entries = await readdir(pluginsDir);
-		const plugins = [];
-		for (const entry of entries) {
-			const fullPath = join(pluginsDir, entry);
-			if (!(await stat(fullPath)).isDirectory() || entry.startsWith("_") || entry.startsWith(".")) continue;
-			const initPath = join(fullPath, "index.js");
-			try {
-				await stat(initPath);
-				const mod = await import(initPath);
-				const available = mod.isAvailable?.() ?? true;
-				plugins.push({
-					name: entry,
-					description: mod.description ?? `${entry} memory plugin`,
-					available
-				});
-			} catch {
-				plugins.push({
-					name: entry,
-					description: `${entry} memory plugin`,
-					available: false
-				});
-			}
+init_discover_extensions();
+async function discoverMemoryPlugins(config) {
+	const plugins = [];
+	for (const extension of discoverMemoryProviderExtensions(config)) for (const providerId of extension.manifest.contracts?.memoryProviders ?? []) plugins.push({
+		name: providerId,
+		description: extension.manifest.description ?? `${extension.manifest.name} memory provider`,
+		available: true,
+		manifest: {
+			type: "memory-provider",
+			id: providerId,
+			displayName: extension.manifest.name || providerId,
+			entry: extension.manifest.main,
+			capabilities: {}
 		}
-		return plugins.sort((a, b) => a.name.localeCompare(b.name));
+	});
+	return plugins.sort((a, b) => a.name.localeCompare(b.name));
+}
+async function loadMemoryPluginProviders(params = {}) {
+	const providers = [];
+	for (const extension of discoverMemoryProviderExtensions(params.config)) {
+		const module = await loadMemoryProviderModule(extension);
+		if (!module?.createMemoryProvider) continue;
+		if (module.isAvailable?.() === false) continue;
+		const fallbackId = (extension.manifest.contracts?.memoryProviders ?? [])[0] ?? extension.id;
+		const manifest = normalizeMemoryProviderManifest(fallbackId, module.manifest) ?? {
+			type: "memory-provider",
+			id: fallbackId,
+			displayName: extension.manifest.name || fallbackId,
+			entry: extension.manifest.main,
+			capabilities: {}
+		};
+		const provider = await module.createMemoryProvider({
+			config: params.config,
+			manifest,
+			extension: {
+				id: extension.id,
+				path: extension.path,
+				source: extension.source,
+				config: extensionConfig(params.config, extension.id)
+			}
+		});
+		providers.push(provider);
+	}
+	return providers;
+}
+function discoverMemoryProviderExtensions(config) {
+	if (areExtensionsDisabled(config)) return [];
+	const disabled = new Set(extensionIds(config?.extensions?.disabled));
+	const enabled = config?.extensions?.enabled;
+	const enabledSet = Array.isArray(enabled) ? new Set(extensionIds(enabled)) : null;
+	return discoverExtensionsFromDisk({}, config).filter((extension) => (extension.manifest.contracts?.memoryProviders?.length ?? 0) > 0).filter((extension) => !disabled.has(extension.id)).filter((extension) => extension.manifest.enabledByDefault === true || enabledSet?.has(extension.id));
+}
+async function loadMemoryProviderModule(extension) {
+	if (!extension.manifest.main) return null;
+	const resolved = await resolveModuleEntry(isAbsolute(extension.manifest.main) ? extension.manifest.main : join(extension.path, extension.manifest.main));
+	try {
+		const mod = await import(pathToFileURL(resolved).href);
+		return "default" in mod && mod.default ? mod.default : mod;
 	} catch {
-		return [];
+		return null;
 	}
 }
+async function resolveModuleEntry(entryPath) {
+	for (const candidate of entryCandidates(entryPath)) try {
+		await stat(candidate);
+		return candidate;
+	} catch {}
+	return entryPath;
+}
+function entryCandidates(entryPath) {
+	const candidates = [entryPath];
+	if (entryPath.endsWith(".js")) candidates.push(`${entryPath.slice(0, -3)}.ts`);
+	return candidates;
+}
+function extensionIds(value) {
+	return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function areExtensionsDisabled(config) {
+	return config?.extensions?.enabled === false;
+}
+function extensionConfig(config, extensionId) {
+	const raw = config?.extensions?.[extensionId];
+	return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : void 0;
+}
+function normalizeMemoryProviderManifest(fallbackId, manifest) {
+	if (!manifest || manifest.type !== "memory-provider") return void 0;
+	const id = typeof manifest.id === "string" && manifest.id.trim() ? manifest.id.trim() : fallbackId;
+	return {
+		type: "memory-provider",
+		id,
+		displayName: typeof manifest.displayName === "string" && manifest.displayName.trim() ? manifest.displayName.trim() : id,
+		...manifest.entry ? { entry: manifest.entry } : {},
+		capabilities: manifest.capabilities ?? {},
+		...manifest.configSchema ? { configSchema: manifest.configSchema } : {}
+	};
+}
 //#endregion
-export { discoverMemoryPlugins };
+export { discoverMemoryPlugins, loadMemoryPluginProviders };
 
 //# sourceMappingURL=plugin-discovery.js.map

package/dist/src/agent/memory/plugin-discovery.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-discovery.js","names":[],"sources":["../../../../src/agent/memory/plugin-discovery.ts"],"sourcesContent":["import { readdir, stat } from 'node:fs/promises';\nimport { dirname, join } from 'node:path';\nimport { fileURLToPath } from 'node:url';\n\n/**\n * Discover optional `plugins/memory/<name>/` packages (extension point).\n * Compiled layout: `dist/src/plugins/memory/...` relative to this module.\n */\nexport interface MemoryPluginMetadata {\n  name: string;\n  description: string;\n  available: boolean;\n}\n\nexport async function discoverMemoryPlugins(): Promise<MemoryPluginMetadata[]> {\n  const here = dirname(fileURLToPath(import.meta.url));\n  const pluginsDir = join(here, '..', '..', 'plugins', 'memory');\n\n  try {\n    const entries = await readdir(pluginsDir);\n    const plugins: MemoryPluginMetadata[] = [];\n\n    for (const entry of entries) {\n      const fullPath = join(pluginsDir, entry);\n      const stats = await stat(fullPath);\n      if (!stats.isDirectory() || entry.startsWith('_') || entry.startsWith('.')) {\n        continue;\n      }\n\n      const initPath = join(fullPath, 'index.js');\n      try {\n        await stat(initPath);\n        const mod = (await import(initPath)) as {\n          isAvailable?: () => boolean;\n          description?: string;\n        };\n        const available = mod.isAvailable?.() ?? true;\n        plugins.push({\n          name: entry,\n          description: mod.description ?? `${entry} memory plugin`,\n          available,\n        });\n      } catch {\n        plugins.push({\n          name: entry,\n          description: `${entry} memory plugin`,\n          available: false,\n        });\n      }\n    }\n\n    return plugins.sort((a, b) => a.name.localeCompare(b.name));\n  } catch {\n    return [];\n  }\n}\n"],"mappings":";;;;AAcA,eAAsB,wBAAyD;CAE7E,MAAM,aAAa,KADN,QAAQ,cAAc,OAAO,KAAK,IAAI,CACvB,EAAE,MAAM,MAAM,WAAW,SAAS;AAE9D,KAAI;EACF,MAAM,UAAU,MAAM,QAAQ,WAAW;EACzC,MAAM,UAAkC,EAAE;AAE1C,OAAK,MAAM,SAAS,SAAS;GAC3B,MAAM,WAAW,KAAK,YAAY,MAAM;AAExC,OAAI,EAAC,MADe,KAAK,SAAS,EACvB,aAAa,IAAI,MAAM,WAAW,IAAI,IAAI,MAAM,WAAW,IAAI,CACxE;GAGF,MAAM,WAAW,KAAK,UAAU,WAAW;AAC3C,OAAI;AACF,UAAM,KAAK,SAAS;IACpB,MAAM,MAAO,MAAM,OAAO;IAI1B,MAAM,YAAY,IAAI,eAAe,IAAI;AACzC,YAAQ,KAAK;KACX,MAAM;KACN,aAAa,IAAI,eAAe,GAAG,MAAM;KACzC;KACD,CAAC;WACI;AACN,YAAQ,KAAK;KACX,MAAM;KACN,aAAa,GAAG,MAAM;KACtB,WAAW;KACZ,CAAC;;;AAIN,SAAO,QAAQ,MAAM,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,KAAK,CAAC;SACrD;AACN,SAAO,EAAE"}
+{"version":3,"file":"plugin-discovery.js","names":[],"sources":["../../../../src/agent/memory/plugin-discovery.ts"],"sourcesContent":["import { stat } from 'node:fs/promises';\nimport { isAbsolute, join } from 'node:path';\nimport { pathToFileURL } from 'node:url';\n\nimport type { Config } from '../../config/schema.js';\nimport { discoverExtensionsFromDisk } from '../../extensions/discover-extensions.js';\nimport type { DiscoveredExtension } from '../../extensions/types/loader.js';\nimport type { MemoryProvider } from './provider.js';\nimport type { MemoryProviderManifest } from './types.js';\n\nexport interface MemoryPluginMetadata {\n  name: string;\n  description: string;\n  available: boolean;\n  manifest?: MemoryProviderManifest;\n}\n\nexport interface MemoryPluginProviderContext {\n  config?: Config;\n  manifest?: MemoryProviderManifest;\n  extension?: {\n    id: string;\n    path: string;\n    source: DiscoveredExtension['source'];\n    config?: Record<string, unknown>;\n  };\n}\n\ntype MemoryPluginModule = {\n  isAvailable?: () => boolean;\n  description?: string;\n  manifest?: MemoryProviderManifest;\n  createMemoryProvider?: (\n    context: MemoryPluginProviderContext,\n  ) => MemoryProvider | Promise<MemoryProvider>;\n};\n\nexport async function discoverMemoryPlugins(config?: Config): Promise<MemoryPluginMetadata[]> {\n  const plugins: MemoryPluginMetadata[] = [];\n  for (const extension of discoverMemoryProviderExtensions(config)) {\n    for (const providerId of extension.manifest.contracts?.memoryProviders ?? []) {\n      plugins.push({\n        name: providerId,\n        description: extension.manifest.description ?? `${extension.manifest.name} memory provider`,\n        available: true,\n        manifest: {\n          type: 'memory-provider',\n          id: providerId,\n          displayName: extension.manifest.name || providerId,\n          entry: extension.manifest.main,\n          capabilities: {},\n        },\n      });\n    }\n  }\n  return plugins.sort((a, b) => a.name.localeCompare(b.name));\n}\n\nexport async function loadMemoryPluginProviders(params: {\n  config?: Config;\n} = {}): Promise<MemoryProvider[]> {\n  const providers: MemoryProvider[] = [];\n  for (const extension of discoverMemoryProviderExtensions(params.config)) {\n    const module = await loadMemoryProviderModule(extension);\n    if (!module?.createMemoryProvider) continue;\n    if (module.isAvailable?.() === false) continue;\n\n    const declaredProviderIds = extension.manifest.contracts?.memoryProviders ?? [];\n    const fallbackId = declaredProviderIds[0] ?? extension.id;\n    const manifest = normalizeMemoryProviderManifest(fallbackId, module.manifest) ?? {\n      type: 'memory-provider',\n      id: fallbackId,\n      displayName: extension.manifest.name || fallbackId,\n      entry: extension.manifest.main,\n      capabilities: {},\n    };\n\n    const provider = await module.createMemoryProvider({\n      config: params.config,\n      manifest,\n      extension: {\n        id: extension.id,\n        path: extension.path,\n        source: extension.source,\n        config: extensionConfig(params.config, extension.id),\n      },\n    });\n    providers.push(provider);\n  }\n  return providers;\n}\n\nfunction discoverMemoryProviderExtensions(config?: Config): DiscoveredExtension[] {\n  if (areExtensionsDisabled(config)) return [];\n  const disabled = new Set(extensionIds(config?.extensions?.disabled));\n  const enabled = config?.extensions?.enabled;\n  const enabledSet = Array.isArray(enabled) ? new Set(extensionIds(enabled)) : null;\n  return discoverExtensionsFromDisk({}, config as unknown as Record<string, unknown> | undefined)\n    .filter((extension) => (extension.manifest.contracts?.memoryProviders?.length ?? 0) > 0)\n    .filter((extension) => !disabled.has(extension.id))\n    .filter((extension) => extension.manifest.enabledByDefault === true || enabledSet?.has(extension.id));\n}\n\nasync function loadMemoryProviderModule(extension: DiscoveredExtension): Promise<MemoryPluginModule | null> {\n  if (!extension.manifest.main) return null;\n  const entryPath = isAbsolute(extension.manifest.main)\n    ? extension.manifest.main\n    : join(extension.path, extension.manifest.main);\n  const resolved = await resolveModuleEntry(entryPath);\n  try {\n    const mod = (await import(pathToFileURL(resolved).href)) as MemoryPluginModule | { default?: MemoryPluginModule };\n    return 'default' in mod && mod.default ? mod.default : (mod as MemoryPluginModule);\n  } catch {\n    return null;\n  }\n}\n\nasync function resolveModuleEntry(entryPath: string): Promise<string> {\n  for (const candidate of entryCandidates(entryPath)) {\n    try {\n      await stat(candidate);\n      return candidate;\n    } catch {\n      // Try the next candidate; source tests use .ts, builds use .js.\n    }\n  }\n  return entryPath;\n}\n\nfunction entryCandidates(entryPath: string): string[] {\n  const candidates = [entryPath];\n  if (entryPath.endsWith('.js')) {\n    candidates.push(`${entryPath.slice(0, -3)}.ts`);\n  }\n  return candidates;\n}\n\nfunction extensionIds(value: unknown): string[] {\n  return Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string') : [];\n}\n\nfunction areExtensionsDisabled(config?: Config): boolean {\n  return config?.extensions?.enabled === false;\n}\n\nfunction extensionConfig(config: Config | undefined, extensionId: string): Record<string, unknown> | undefined {\n  const raw = config?.extensions?.[extensionId as keyof Config['extensions']];\n  return raw && typeof raw === 'object' && !Array.isArray(raw) ? (raw as Record<string, unknown>) : undefined;\n}\n\nfunction normalizeMemoryProviderManifest(\n  fallbackId: string,\n  manifest: MemoryProviderManifest | undefined,\n): MemoryProviderManifest | undefined {\n  if (!manifest || manifest.type !== 'memory-provider') return undefined;\n  const id = typeof manifest.id === 'string' && manifest.id.trim() ? manifest.id.trim() : fallbackId;\n  const displayName =\n    typeof manifest.displayName === 'string' && manifest.displayName.trim()\n      ? manifest.displayName.trim()\n      : id;\n  return {\n    type: 'memory-provider',\n    id,\n    displayName,\n    ...(manifest.entry ? { entry: manifest.entry } : {}),\n    capabilities: manifest.capabilities ?? {},\n    ...(manifest.configSchema ? { configSchema: manifest.configSchema } : {}),\n  };\n}\n"],"mappings":"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"}

package/dist/src/agent/memory/prefetch-coordinator.js.map

@@ -1 +1 @@
-{"version":3,"file":"prefetch-coordinator.js","names":[],"sources":["../../../../src/agent/memory/prefetch-coordinator.ts"],"sourcesContent":["/**\n * MemoryPrefetchCoordinator — owns the per-session memory prefetch cadence and\n * the post-turn sync hand-off to external memory providers.\n *\n * Previously these lived as two methods + a private `Map<sessionKey, turn>` on\n * `AgentManager`. Moving them out makes the memory layer a stand-alone concern\n * with a single owner that handles both \"what to prefix on the user turn\" and\n * \"what to sync after the turn ends\".\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport type { MemoryManager } from './manager.js';\nimport { extractAgentUserPlainText } from './user-message-text.js';\nimport { injectPrefetchIntoUserMessage } from './inject-prefetch.js';\nimport {\n  isMemorySubsystemEnabled,\n  shouldInjectMemoryPrefetchThisTurn,\n} from './memory-config.js';\n\nexport interface MemoryPrefetchCoordinatorOptions {\n  /** Effective config snapshot accessor; tested against `isMemorySubsystemEnabled`. */\n  getConfig: () => Config | undefined;\n  /** Resolve the per-session memory manager (workspace runtime lookup lives in AgentManager). */\n  getMemoryManagerForSession: (sessionKey: string) => MemoryManager;\n  /** Return the last assistant text for a session — fed into external `syncAll`. */\n  getLastAssistantContent: (sessionKey: string) => string | null;\n}\n\nexport class MemoryPrefetchCoordinator {\n  private readonly opts: MemoryPrefetchCoordinatorOptions;\n  /** Per-session user-message index, incremented before each `applyPrefetch` call. */\n  private readonly prefetchUserTurn = new Map<string, number>();\n\n  constructor(opts: MemoryPrefetchCoordinatorOptions) {\n    this.opts = opts;\n  }\n\n  /** Forget a session entirely (called when AgentManager removes the agent). */\n  forgetSession(sessionKey: string): void {\n    this.prefetchUserTurn.delete(sessionKey);\n  }\n\n  /** Tear down all per-session state (process stop / hot reload). */\n  clear(): void {\n    this.prefetchUserTurn.clear();\n  }\n\n  /**\n   * Prepend the prefetched memory fence to the user turn when the cadence\n   * config says we should. Returns the original message untouched otherwise.\n   */\n  async applyToUserMessage(\n    userMessage: AgentMessage,\n    sessionKey: string,\n  ): Promise<AgentMessage> {\n    const cfg = this.opts.getConfig();\n    if (!isMemorySubsystemEnabled(cfg)) {\n      return userMessage;\n    }\n    const plain = extractAgentUserPlainText(userMessage);\n    const turn = (this.prefetchUserTurn.get(sessionKey) ?? 0) + 1;\n    this.prefetchUserTurn.set(sessionKey, turn);\n    if (!shouldInjectMemoryPrefetchThisTurn(cfg, turn)) {\n      return userMessage;\n    }\n    return injectPrefetchIntoUserMessage(\n      this.opts.getMemoryManagerForSession(sessionKey),\n      sessionKey,\n      userMessage,\n      plain,\n    );\n  }\n\n  /** Post-turn: push the latest exchange to external providers + warm next prefetch. */\n  afterTurn(sessionKey: string, userPlainText: string): void {\n    const cfg = this.opts.getConfig();\n    if (!isMemorySubsystemEnabled(cfg)) {\n      return;\n    }\n    const assistant = this.opts.getLastAssistantContent(sessionKey) ?? '';\n    const mm = this.opts.getMemoryManagerForSession(sessionKey);\n    mm.syncAll(userPlainText, assistant, { sessionId: sessionKey });\n    mm.queuePrefetchAll(userPlainText, { sessionId: sessionKey });\n  }\n}\n"],"mappings":";;;;AA8BA,IAAa,4BAAb,MAAuC;CACrC;;CAEA,mCAAoC,IAAI,KAAqB;CAE7D,YAAY,MAAwC;AAClD,OAAK,OAAO;;;CAId,cAAc,YAA0B;AACtC,OAAK,iBAAiB,OAAO,WAAW;;;CAI1C,QAAc;AACZ,OAAK,iBAAiB,OAAO;;;;;;CAO/B,MAAM,mBACJ,aACA,YACuB;EACvB,MAAM,MAAM,KAAK,KAAK,WAAW;AACjC,MAAI,CAAC,yBAAyB,IAAI,CAChC,QAAO;EAET,MAAM,QAAQ,0BAA0B,YAAY;EACpD,MAAM,QAAQ,KAAK,iBAAiB,IAAI,WAAW,IAAI,KAAK;AAC5D,OAAK,iBAAiB,IAAI,YAAY,KAAK;AAC3C,MAAI,CAAC,mCAAmC,KAAK,KAAK,CAChD,QAAO;AAET,SAAO,8BACL,KAAK,KAAK,2BAA2B,WAAW,EAChD,YACA,aACA,MACD;;;CAIH,UAAU,YAAoB,eAA6B;AAEzD,MAAI,CAAC,yBADO,KAAK,KAAK,WACW,CAAC,CAChC;EAEF,MAAM,YAAY,KAAK,KAAK,wBAAwB,WAAW,IAAI;EACnE,MAAM,KAAK,KAAK,KAAK,2BAA2B,WAAW;AAC3D,KAAG,QAAQ,eAAe,WAAW,EAAE,WAAW,YAAY,CAAC;AAC/D,KAAG,iBAAiB,eAAe,EAAE,WAAW,YAAY,CAAC"}
+{"version":3,"file":"prefetch-coordinator.js","names":[],"sources":["../../../../src/agent/memory/prefetch-coordinator.ts"],"sourcesContent":["/**\n * MemoryPrefetchCoordinator — owns the per-session memory prefetch cadence and\n * the post-turn sync hand-off to external memory providers.\n *\n * Previously these lived as two methods + a private `Map<sessionKey, turn>` on\n * `AgentManager`. Moving them out makes the memory layer a stand-alone concern\n * with a single owner that handles both \"what to prefix on the user turn\" and\n * \"what to sync after the turn ends\".\n */\n\nimport type { AgentMessage } from '@earendil-works/pi-agent-core';\n\nimport type { Config } from '../../config/schema.js';\nimport type { MemoryManager } from './manager.js';\nimport { extractAgentUserPlainText } from './user-message-text.js';\nimport { injectPrefetchIntoUserMessage } from './inject-prefetch.js';\nimport {\n  isMemorySubsystemEnabled,\n  shouldInjectMemoryPrefetchThisTurn,\n} from './memory-config.js';\n\nexport interface MemoryPrefetchCoordinatorOptions {\n  /** Effective config snapshot accessor; tested against `isMemorySubsystemEnabled`. */\n  getConfig: () => Config | undefined;\n  /** Resolve the per-session memory manager (workspace runtime lookup lives in AgentManager). */\n  getMemoryManagerForSession: (sessionKey: string) => MemoryManager;\n  /** Return the last assistant text for a session — fed into external `syncAll`. */\n  getLastAssistantContent: (sessionKey: string) => string | null;\n}\n\nexport class MemoryPrefetchCoordinator {\n  private readonly opts: MemoryPrefetchCoordinatorOptions;\n  /** Per-session user-message index, incremented before each `applyPrefetch` call. */\n  private readonly prefetchUserTurn = new Map<string, number>();\n\n  constructor(opts: MemoryPrefetchCoordinatorOptions) {\n    this.opts = opts;\n  }\n\n  /** Forget a session entirely (called when AgentManager removes the agent). */\n  forgetSession(sessionKey: string): void {\n    this.prefetchUserTurn.delete(sessionKey);\n  }\n\n  /** Tear down all per-session state (process stop / hot reload). */\n  clear(): void {\n    this.prefetchUserTurn.clear();\n  }\n\n  /**\n   * Prepend the prefetched memory fence to the user turn when the cadence\n   * config says we should. Returns the original message untouched otherwise.\n   */\n  async applyToUserMessage(\n    userMessage: AgentMessage,\n    sessionKey: string,\n  ): Promise<AgentMessage> {\n    const cfg = this.opts.getConfig();\n    if (!isMemorySubsystemEnabled(cfg)) {\n      return userMessage;\n    }\n    const plain = extractAgentUserPlainText(userMessage);\n    const turn = (this.prefetchUserTurn.get(sessionKey) ?? 0) + 1;\n    this.prefetchUserTurn.set(sessionKey, turn);\n    if (!shouldInjectMemoryPrefetchThisTurn(cfg, turn)) {\n      return userMessage;\n    }\n    return injectPrefetchIntoUserMessage(\n      this.opts.getMemoryManagerForSession(sessionKey),\n      sessionKey,\n      userMessage,\n      plain,\n    );\n  }\n\n  /** Post-turn: push the latest exchange to external providers + warm next prefetch. */\n  afterTurn(sessionKey: string, userPlainText: string): void {\n    const cfg = this.opts.getConfig();\n    if (!isMemorySubsystemEnabled(cfg)) {\n      return;\n    }\n    const assistant = this.opts.getLastAssistantContent(sessionKey) ?? '';\n    const mm = this.opts.getMemoryManagerForSession(sessionKey);\n    void mm.syncAll(userPlainText, assistant, { sessionId: sessionKey });\n    mm.queuePrefetchAll(userPlainText, { sessionId: sessionKey });\n  }\n}\n"],"mappings":";;;;AA8BA,IAAa,4BAAb,MAAuC;CACrC;;CAEA,mCAAoC,IAAI,KAAqB;CAE7D,YAAY,MAAwC;AAClD,OAAK,OAAO;;;CAId,cAAc,YAA0B;AACtC,OAAK,iBAAiB,OAAO,WAAW;;;CAI1C,QAAc;AACZ,OAAK,iBAAiB,OAAO;;;;;;CAO/B,MAAM,mBACJ,aACA,YACuB;EACvB,MAAM,MAAM,KAAK,KAAK,WAAW;AACjC,MAAI,CAAC,yBAAyB,IAAI,CAChC,QAAO;EAET,MAAM,QAAQ,0BAA0B,YAAY;EACpD,MAAM,QAAQ,KAAK,iBAAiB,IAAI,WAAW,IAAI,KAAK;AAC5D,OAAK,iBAAiB,IAAI,YAAY,KAAK;AAC3C,MAAI,CAAC,mCAAmC,KAAK,KAAK,CAChD,QAAO;AAET,SAAO,8BACL,KAAK,KAAK,2BAA2B,WAAW,EAChD,YACA,aACA,MACD;;;CAIH,UAAU,YAAoB,eAA6B;AAEzD,MAAI,CAAC,yBADO,KAAK,KAAK,WACW,CAAC,CAChC;EAEF,MAAM,YAAY,KAAK,KAAK,wBAAwB,WAAW,IAAI;EACnE,MAAM,KAAK,KAAK,KAAK,2BAA2B,WAAW;AACtD,KAAG,QAAQ,eAAe,WAAW,EAAE,WAAW,YAAY,CAAC;AACpE,KAAG,iBAAiB,eAAe,EAAE,WAAW,YAAY,CAAC"}

package/dist/src/agent/memory/provider.d.ts

@@ -1,35 +1,40 @@
-/**
- * Pluggable memory provider. Builtin curated files use `BuiltinMemoryStore` + `curated_memory`;
- * external providers add instructions, prefetch/sync, and optional tools.
- */
 import type { AgentTool } from '@earendil-works/pi-agent-core';
+import type { MemoryCapabilities, MemoryDeleteRequest, MemoryListRequest, MemoryProviderManifest, MemoryReadRequest, MemoryReadResult, MemorySearchRequest, MemorySearchResult, MemorySyncEvent, MemoryUpdateRequest, MemoryWriteRequest, MemoryWriteResult, MemoryRecord } from './types.js';
 export interface MemoryProviderInitOptions {
     workspace?: string;
     agentWorkspace?: string;
     sessionId?: string;
+    config?: Record<string, unknown>;
     [key: string]: unknown;
 }
 export interface MemoryProvider {
-    readonly name: string;
+    readonly id: string;
+    readonly displayName?: string;
+    readonly manifest?: MemoryProviderManifest;
+    readonly capabilities: MemoryCapabilities;
     isAvailable(): boolean;
     initialize(sessionId: string, options?: MemoryProviderInitOptions): Promise<void> | void;
-    /** Static text merged into system prompt (external providers only; builtin uses curated snapshot separately). */
-    systemPromptBlock(): string;
-    prefetch(query: string, options?: {
+    /** Static text merged into the system prompt. */
+    systemPromptBlock?(): string;
+    prefetch?(query: string, options?: {
         sessionId?: string;
     }): Promise<string>;
-    queuePrefetch(query: string, options?: {
+    queuePrefetch?(query: string, options?: {
         sessionId?: string;
     }): void;
-    syncTurn(userContent: string, assistantContent: string, options?: {
-        sessionId?: string;
-    }): void;
-    getToolSchemas(): AgentTool[];
+    sync?(event: MemorySyncEvent): Promise<void> | void;
+    search?(request: MemorySearchRequest): Promise<MemorySearchResult[]>;
+    read?(request: MemoryReadRequest): Promise<MemoryReadResult | null>;
+    get?(id: string): Promise<MemoryRecord | null>;
+    list?(request: MemoryListRequest): Promise<MemoryRecord[]>;
+    write?(request: MemoryWriteRequest): Promise<MemoryWriteResult>;
+    update?(request: MemoryUpdateRequest): Promise<MemoryWriteResult>;
+    delete?(request: MemoryDeleteRequest): Promise<MemoryWriteResult>;
+    getToolSchemas?(): AgentTool[];
     /** JSON string result for tool calls routed by name (when not using inline AgentTool.execute only). */
-    handleToolCall(toolName: string, args: Record<string, unknown>): Promise<string>;
+    handleToolCall?(toolName: string, args: Record<string, unknown>): Promise<string>;
     shutdown(): Promise<void> | void;
     onTurnStart?(turnNumber: number, message: string, metadata?: Record<string, unknown>): void;
     onSessionEnd?(messages: unknown[]): void;
     onPreCompress?(messages: unknown[]): string;
-    onMemoryWrite?(action: 'add' | 'replace' | 'remove', target: 'memory' | 'user', content: string): void;
 }

package/dist/src/agent/memory/stub-memory-provider.d.ts

@@ -3,14 +3,29 @@ import type { MemoryProvider, MemoryProviderInitOptions } from './provider.js';
  * Placeholder external provider — enables wiring tests without cloud deps.
  */
 export declare class StubMemoryProvider implements MemoryProvider {
-    readonly name = "stub";
+    readonly id = "stub";
+    readonly displayName = "Stub Memory Provider";
+    readonly capabilities: {
+        search: boolean;
+        read: boolean;
+        write: boolean;
+        update: boolean;
+        delete: boolean;
+        keywordSearch: boolean;
+        semanticSearch: boolean;
+        hybridSearch: boolean;
+        citations: boolean;
+        sync: boolean;
+        local: boolean;
+    };
     isAvailable(): boolean;
     initialize(_sessionId: string, _options?: MemoryProviderInitOptions): Promise<void>;
     systemPromptBlock(): string;
     prefetch(query: string): Promise<string>;
     queuePrefetch(): void;
-    syncTurn(_user: string, _assistant: string): void;
+    sync(): void;
     getToolSchemas(): any[];
     handleToolCall(toolName: string): Promise<string>;
+    search(): Promise<[]>;
     shutdown(): Promise<void>;
 }

package/dist/src/agent/memory/stub-memory-provider.js

@@ -3,13 +3,27 @@
 * Placeholder external provider — enables wiring tests without cloud deps.
 */
 var StubMemoryProvider = class {
-	name = "stub";
+	id = "stub";
+	displayName = "Stub Memory Provider";
+	capabilities = {
+		search: true,
+		read: false,
+		write: false,
+		update: false,
+		delete: false,
+		keywordSearch: false,
+		semanticSearch: false,
+		hybridSearch: false,
+		citations: false,
+		sync: true,
+		local: false
+	};
 	isAvailable() {
 		return true;
 	}
 	async initialize(_sessionId, _options) {}
 	systemPromptBlock() {
-		return "External memory provider: stub (wiring only; no cloud backend). Set `agents.defaults.memory.provider` to `none` to hide.";
+		return "External memory provider: stub (wiring only; no cloud backend).";
 	}
 	async prefetch(query) {
 		const q = query.trim();
@@ -17,13 +31,16 @@ var StubMemoryProvider = class {
 		return `[stub prefetch] query length=${q.length}`;
 	}
 	queuePrefetch() {}
-	syncTurn(_user, _assistant) {}
+	sync() {}
 	getToolSchemas() {
 		return [];
 	}
 	async handleToolCall(toolName) {
 		return JSON.stringify({ error: `stub provider has no tools (${toolName})` });
 	}
+	async search() {
+		return [];
+	}
 	async shutdown() {}
 };
 //#endregion

package/dist/src/agent/memory/stub-memory-provider.js.map

@@ -1 +1 @@
-{"version":3,"file":"stub-memory-provider.js","names":[],"sources":["../../../../src/agent/memory/stub-memory-provider.ts"],"sourcesContent":["import type { MemoryProvider, MemoryProviderInitOptions } from './provider.js';\n\n/**\n * Placeholder external provider — enables wiring tests without cloud deps.\n */\nexport class StubMemoryProvider implements MemoryProvider {\n  readonly name = 'stub';\n\n  isAvailable(): boolean {\n    return true;\n  }\n\n  async initialize(_sessionId: string, _options?: MemoryProviderInitOptions): Promise<void> {}\n\n  systemPromptBlock(): string {\n    return 'External memory provider: stub (wiring only; no cloud backend). Set `agents.defaults.memory.provider` to `none` to hide.';\n  }\n\n  async prefetch(query: string): Promise<string> {\n    const q = query.trim();\n    if (!q) {\n      return '';\n    }\n    return `[stub prefetch] query length=${q.length}`;\n  }\n\n  queuePrefetch(): void {}\n\n  syncTurn(_user: string, _assistant: string): void {}\n\n  getToolSchemas() {\n    return [];\n  }\n\n  async handleToolCall(toolName: string): Promise<string> {\n    return JSON.stringify({ error: `stub provider has no tools (${toolName})` });\n  }\n\n  async shutdown(): Promise<void> {}\n}\n"],"mappings":";;;;AAKA,IAAa,qBAAb,MAA0D;CACxD,OAAgB;CAEhB,cAAuB;AACrB,SAAO;;CAGT,MAAM,WAAW,YAAoB,UAAqD;CAE1F,oBAA4B;AAC1B,SAAO;;CAGT,MAAM,SAAS,OAAgC;EAC7C,MAAM,IAAI,MAAM,MAAM;AACtB,MAAI,CAAC,EACH,QAAO;AAET,SAAO,gCAAgC,EAAE;;CAG3C,gBAAsB;CAEtB,SAAS,OAAe,YAA0B;CAElD,iBAAiB;AACf,SAAO,EAAE;;CAGX,MAAM,eAAe,UAAmC;AACtD,SAAO,KAAK,UAAU,EAAE,OAAO,+BAA+B,SAAS,IAAI,CAAC;;CAG9E,MAAM,WAA0B"}
+{"version":3,"file":"stub-memory-provider.js","names":[],"sources":["../../../../src/agent/memory/stub-memory-provider.ts"],"sourcesContent":["import type { MemoryProvider, MemoryProviderInitOptions } from './provider.js';\n\n/**\n * Placeholder external provider — enables wiring tests without cloud deps.\n */\nexport class StubMemoryProvider implements MemoryProvider {\n  readonly id = 'stub';\n  readonly displayName = 'Stub Memory Provider';\n  readonly capabilities = {\n    search: true,\n    read: false,\n    write: false,\n    update: false,\n    delete: false,\n    keywordSearch: false,\n    semanticSearch: false,\n    hybridSearch: false,\n    citations: false,\n    sync: true,\n    local: false,\n  };\n\n  isAvailable(): boolean {\n    return true;\n  }\n\n  async initialize(_sessionId: string, _options?: MemoryProviderInitOptions): Promise<void> {}\n\n  systemPromptBlock(): string {\n    return 'External memory provider: stub (wiring only; no cloud backend).';\n  }\n\n  async prefetch(query: string): Promise<string> {\n    const q = query.trim();\n    if (!q) {\n      return '';\n    }\n    return `[stub prefetch] query length=${q.length}`;\n  }\n\n  queuePrefetch(): void {}\n\n  sync(): void {}\n\n  getToolSchemas() {\n    return [];\n  }\n\n  async handleToolCall(toolName: string): Promise<string> {\n    return JSON.stringify({ error: `stub provider has no tools (${toolName})` });\n  }\n\n  async search(): Promise<[]> {\n    return [];\n  }\n\n  async shutdown(): Promise<void> {}\n}\n"],"mappings":";;;;AAKA,IAAa,qBAAb,MAA0D;CACxD,KAAc;CACd,cAAuB;CACvB,eAAwB;EACtB,QAAQ;EACR,MAAM;EACN,OAAO;EACP,QAAQ;EACR,QAAQ;EACR,eAAe;EACf,gBAAgB;EAChB,cAAc;EACd,WAAW;EACX,MAAM;EACN,OAAO;EACR;CAED,cAAuB;AACrB,SAAO;;CAGT,MAAM,WAAW,YAAoB,UAAqD;CAE1F,oBAA4B;AAC1B,SAAO;;CAGT,MAAM,SAAS,OAAgC;EAC7C,MAAM,IAAI,MAAM,MAAM;AACtB,MAAI,CAAC,EACH,QAAO;AAET,SAAO,gCAAgC,EAAE;;CAG3C,gBAAsB;CAEtB,OAAa;CAEb,iBAAiB;AACf,SAAO,EAAE;;CAGX,MAAM,eAAe,UAAmC;AACtD,SAAO,KAAK,UAAU,EAAE,OAAO,+BAA+B,SAAS,IAAI,CAAC;;CAG9E,MAAM,SAAsB;AAC1B,SAAO,EAAE;;CAGX,MAAM,WAA0B"}

package/dist/src/agent/memory/types.d.ts

@@ -1,15 +1,19 @@
 /**
- * Built-in curated memory (MEMORY.md + USER.md under the agent home `memories/` dir).
+ * Built-in curated memory:
+ * - agent notes: `~/.xopc/agents/<id>/memories/MEMORY.md`
+ * - user memory: `~/.xopc/user/MEMORY.md`
  */
 export interface MemoryStoreConfig {
     workspaceDir: string;
     /** Absolute path to `…/agents/<id>/memories/` (not under markdown workspace). */
     memoriesDir: string;
+    /** Absolute path to global user memory (`~/.xopc/user/MEMORY.md`). */
+    userMemoryPath: string;
     /** Max chars for MEMORY.md entries (excluding delimiter overhead in limit check uses joined body). */
     memoryCharLimit: number;
-    /** Max chars for USER.md entries. */
+    /** Max chars for global user memory entries. */
     userCharLimit: number;
-    /** When false, USER.md is not loaded into the snapshot or shown in the system prompt. */
+    /** When false, global user memory is not loaded into the snapshot or shown in the system prompt. */
     userProfileEnabled?: boolean;
 }
 /** Frozen at session start; not updated when tools mutate disk mid-session. */
@@ -17,3 +21,158 @@ export interface MemorySnapshot {
     memory: string;
     user: string;
 }
+export type MemoryKind = 'user_profile' | 'agent_note' | 'workspace_fact' | 'daily_note' | 'session_summary' | 'derived_insight' | 'task_lesson' | 'tool_preference' | 'long_term_goal';
+export type MemoryStatus = 'candidate' | 'active' | 'needs_review' | 'stale' | 'archived' | 'rejected';
+export type MemorySensitivity = 'normal' | 'personal' | 'secret' | 'regulated';
+export interface MemoryEvidence {
+    sessionKey?: string;
+    turnId?: string;
+    toolCallId?: string;
+    sourceText?: string;
+}
+export interface MemoryScope {
+    agentId: string;
+    workspaceId?: string;
+    sessionKey?: string;
+}
+export interface MemoryCitation {
+    providerId: string;
+    recordId: string;
+    title?: string;
+    uri?: string;
+    path?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    createdAt?: string;
+}
+export interface MemoryRecord {
+    id: string;
+    kind: MemoryKind;
+    status?: MemoryStatus;
+    scope: MemoryScope;
+    content: string;
+    source: {
+        path?: string;
+        lineStart?: number;
+        lineEnd?: number;
+        sessionEntryId?: string;
+        provider?: string;
+    };
+    confidence?: number;
+    sensitivity?: MemorySensitivity;
+    evidence?: MemoryEvidence[];
+    reviewAfter?: string;
+    expiresAt?: string;
+    createdAt: string;
+    updatedAt: string;
+    tags?: string[];
+}
+export interface MemorySearchRequest {
+    query: string;
+    scope?: Partial<MemoryScope>;
+    kinds?: MemoryKind[];
+    maxResults?: number;
+    minScore?: number;
+}
+export interface MemorySearchResult {
+    record: MemoryRecord;
+    score: number;
+    snippet: string;
+    citation: MemoryCitation;
+}
+export interface MemoryReadRequest {
+    id?: string;
+    path?: string;
+    from?: number;
+    lines?: number;
+    scope?: Partial<MemoryScope>;
+}
+export interface MemoryReadResult {
+    record: MemoryRecord;
+    lineNumbers?: {
+        start: number;
+        end: number;
+    };
+}
+export interface MemoryListRequest {
+    kind?: MemoryKind;
+    target?: 'memory' | 'user';
+    scope?: Partial<MemoryScope>;
+}
+export interface MemoryWriteRequest {
+    kind: MemoryKind;
+    content: string;
+    scope?: Partial<MemoryScope>;
+    target?: 'memory' | 'user';
+    tags?: string[];
+    source?: MemoryRecord['source'];
+    confidence?: number;
+    status?: MemoryStatus;
+    sensitivity?: MemorySensitivity;
+    evidence?: MemoryEvidence[];
+    reviewAfter?: string;
+    expiresAt?: string;
+    approved?: boolean;
+}
+export interface MemoryUpdateRequest {
+    id?: string;
+    matchText?: string;
+    content: string;
+    scope?: Partial<MemoryScope>;
+    target?: 'memory' | 'user';
+    approved?: boolean;
+}
+export interface MemoryDeleteRequest {
+    id?: string;
+    matchText?: string;
+    scope?: Partial<MemoryScope>;
+    target?: 'memory' | 'user';
+}
+export interface MemoryWriteResult {
+    success: boolean;
+    message?: string;
+    error?: string;
+    record?: MemoryRecord;
+}
+export interface MemoryCapabilities {
+    search: boolean;
+    read: boolean;
+    write: boolean;
+    update: boolean;
+    delete: boolean;
+    keywordSearch?: boolean;
+    semanticSearch?: boolean;
+    hybridSearch?: boolean;
+    citations?: boolean;
+    sync?: boolean;
+    local?: boolean;
+}
+export interface MemoryProviderManifest {
+    type: 'memory-provider';
+    id: string;
+    displayName: string;
+    entry?: string;
+    capabilities: Partial<MemoryCapabilities>;
+    configSchema?: string;
+}
+export type MemorySyncEvent = {
+    type: 'turn';
+    userContent: string;
+    assistantContent: string;
+    sessionId?: string;
+} | {
+    type: 'write';
+    action: 'add' | 'replace' | 'remove';
+    target?: 'memory' | 'user';
+    content: string;
+} | {
+    type: 'signal';
+    signal: MemorySignal;
+};
+export interface MemorySignal {
+    source: 'search_recall' | 'session_summary' | 'explicit_remember' | 'background_review' | 'dreaming';
+    recordId?: string;
+    score?: number;
+    content?: string;
+    metadata?: Record<string, unknown>;
+}