@xopcai/xopc 0.0.136 → 0.0.138

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

@@ -31,13 +31,13 @@ function resolveBuiltinMemoryStoreConfig(workspaceDir, config) {
 * Whether to prefix the user message with prefetched external memory this turn.
 * `first-turn` only injects on turn 1. `contextCadence` N injects on turns 1, N+1, 2N+1, …
 */
-function shouldInjectMemoryPrefetchThisTurn(config, turnNumber) {
+function shouldPlanUserContextThisTurn(_config, turnNumber) {
 	return turnNumber >= 1;
 }
 function shouldRegisterCuratedMemoryTool(config) {
 	return isCuratedMemoryInPrompt(config);
 }
 //#endregion
-export { isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, shouldInjectMemoryPrefetchThisTurn, shouldRegisterCuratedMemoryTool };
+export { isCuratedMemoryInPrompt, isMemorySubsystemEnabled, resolveBuiltinMemoryStoreConfig, shouldPlanUserContextThisTurn, shouldRegisterCuratedMemoryTool };
 
 //# sourceMappingURL=memory-config.js.map

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 { 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"}
+{"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 shouldPlanUserContextThisTurn(\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,8BACd,SACA,YACS;AACT,QAAO,cAAc;;AAGvB,SAAgB,gCAAgC,QAAqC;AACnF,QAAO,wBAAwB,OAAO"}

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

@@ -3,6 +3,7 @@ import type { MemoryCapabilities, MemoryDeleteRequest, MemoryListRequest, Memory
 export interface MemoryProviderInitOptions {
     workspace?: string;
     agentWorkspace?: string;
+    agentId?: string;
     sessionId?: string;
     config?: Record<string, unknown>;
     [key: string]: unknown;
@@ -16,9 +17,6 @@ export interface MemoryProvider {
     initialize(sessionId: string, options?: MemoryProviderInitOptions): Promise<void> | void;
     /** Static text merged into the system prompt. */
     systemPromptBlock?(): string;
-    prefetch?(query: string, options?: {
-        sessionId?: string;
-    }): Promise<string>;
     queuePrefetch?(query: string, options?: {
         sessionId?: string;
     }): void;

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

@@ -21,7 +21,6 @@ export declare class StubMemoryProvider implements MemoryProvider {
     isAvailable(): boolean;
     initialize(_sessionId: string, _options?: MemoryProviderInitOptions): Promise<void>;
     systemPromptBlock(): string;
-    prefetch(query: string): Promise<string>;
     queuePrefetch(): void;
     sync(): void;
     getToolSchemas(): any[];

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

@@ -25,11 +25,6 @@ var StubMemoryProvider = class {
 	systemPromptBlock() {
 		return "External memory provider: stub (wiring only; no cloud backend).";
 	}
-	async prefetch(query) {
-		const q = query.trim();
-		if (!q) return "";
-		return `[stub prefetch] query length=${q.length}`;
-	}
 	queuePrefetch() {}
 	sync() {}
 	getToolSchemas() {

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 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"}
+{"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  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,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,5 +1,5 @@
 /**
- * Built-in curated memory:
+ * Curated Markdown compatibility store:
  * - agent notes: `~/.xopc/agents/<id>/memories/MEMORY.md`
  * - user memory: `~/.xopc/user/MEMORY.md`
  */
@@ -21,14 +21,23 @@ 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 MemoryKind = 'user_profile' | 'preference' | 'boundary' | 'relationship' | 'project_context' | 'commitment' | 'routine' | 'personal_logistics' | 'open_question' | 'milestone' | 'current_state' | '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 type MemoryExplicitness = 'explicit' | 'observed' | 'inferred';
+export type MemoryDurability = 'ephemeral' | 'durable' | 'recurring';
+export type MemoryDisclosurePolicy = 'silent' | 'referenceable' | 'ask_before_reference';
+export type MemoryEvidenceRelation = 'supports' | 'contradicts' | 'supersedes' | 'derived_from';
 export interface MemoryEvidence {
+    evidenceId?: string;
+    sourceItemId?: string;
+    relation?: MemoryEvidenceRelation;
     sessionKey?: string;
     turnId?: string;
     toolCallId?: string;
     sourceText?: string;
+    observedAt?: string;
+    confidence?: number;
 }
 export interface MemoryScope {
     agentId: string;
@@ -50,6 +59,7 @@ export interface MemoryRecord {
     id: string;
     kind: MemoryKind;
     status?: MemoryStatus;
+    canonicalKey?: string;
     scope: MemoryScope;
     content: string;
     source: {
@@ -61,9 +71,17 @@ export interface MemoryRecord {
     };
     confidence?: number;
     sensitivity?: MemorySensitivity;
+    explicitness: MemoryExplicitness;
+    durability: MemoryDurability;
+    importance: number;
+    disclosurePolicy: MemoryDisclosurePolicy;
     evidence?: MemoryEvidence[];
+    validFrom?: string;
+    validTo?: string;
     reviewAfter?: string;
     expiresAt?: string;
+    supersedesRecordId?: string;
+    conflictGroupId?: string;
     createdAt: string;
     updatedAt: string;
     tags?: string[];
@@ -97,12 +115,15 @@ export interface MemoryReadResult {
 }
 export interface MemoryListRequest {
     kind?: MemoryKind;
+    status?: MemoryStatus;
+    canonicalKey?: string;
     target?: 'memory' | 'user';
     scope?: Partial<MemoryScope>;
 }
 export interface MemoryWriteRequest {
     kind: MemoryKind;
     content: string;
+    canonicalKey?: string;
     scope?: Partial<MemoryScope>;
     target?: 'memory' | 'user';
     tags?: string[];
@@ -110,9 +131,17 @@ export interface MemoryWriteRequest {
     confidence?: number;
     status?: MemoryStatus;
     sensitivity?: MemorySensitivity;
+    explicitness?: MemoryExplicitness;
+    durability?: MemoryDurability;
+    importance?: number;
+    disclosurePolicy?: MemoryDisclosurePolicy;
     evidence?: MemoryEvidence[];
+    validFrom?: string;
+    validTo?: string;
     reviewAfter?: string;
     expiresAt?: string;
+    supersedesRecordId?: string;
+    conflictGroupId?: string;
     approved?: boolean;
 }
 export interface MemoryUpdateRequest {

package/dist/src/agent/memory/understanding/correction.d.ts

@@ -0,0 +1,3 @@
+export declare function isExplicitUnderstandingCorrection(text: string): boolean;
+/** Returns only a concrete replacement statement; pure denials intentionally return null. */
+export declare function extractExplicitUnderstandingCorrectionContent(text: string): string | null;

package/dist/src/agent/memory/understanding/correction.js

@@ -0,0 +1,41 @@
+//#region src/agent/memory/understanding/correction.ts
+const UNDERSTANDING_CORRECTION_PATTERNS = [
+	/(?:你|您)(?:记错|理解错|搞错)(?:了)?(?:我|我的)/,
+	/(?:这|那)(?:不是|并非)我的(?:偏好|习惯|情况|信息|边界)/,
+	/我(?:没有|从没|从未)(?:说过|表示过|要求过)(?:这|那|这个|那个)/,
+	/(?:不要|别再)(?:认为|假设|记成)(?:我|我的)/,
+	/you (?:remembered|understood|got) (?:me|my .+?) wrong\b/i,
+	/that(?:'s| is) not my (?:preference|habit|situation|information|boundary)\b/i,
+	/i (?:never|did not|didn't) (?:say|said|tell you|told you|ask for|asked for) that\b/i,
+	/do not assume that about me\b/i
+];
+const UNDERSTANDING_CORRECTION_CONTENT_PATTERNS = [
+	/(?:你|您)(?:记错|理解错|搞错)(?:了)?(?:我|我的)(?:偏好|习惯|情况|信息|边界|工作方式)?[，,:：；;。]\s*(?:其实|实际上|正确的是)?\s*(.+)$/,
+	/(?:这|那)(?:不是|并非)我的(?:偏好|习惯|情况|信息|边界)[，,:：；;。]\s*(.+)$/,
+	/you (?:remembered|understood|got) (?:me|my .+?) wrong\b[,:;.]?\s*(?:actually[,:]?\s*)?(.+)$/i,
+	/that(?:'s| is) not my (?:preference|habit|situation|information|boundary)\b[,:;.]?\s*(.+)$/i
+];
+function normalizeCorrectionContent(content) {
+	const normalized = content.replace(/^[“”‘’"'\s]+|[“”‘’"'\s]+$/g, "").replace(/\s+/g, " ").trim();
+	return normalized.length >= 4 ? normalized.slice(0, 600) : null;
+}
+function isExplicitUnderstandingCorrection(text) {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	return normalized.length > 0 && UNDERSTANDING_CORRECTION_PATTERNS.some((pattern) => pattern.test(normalized));
+}
+/** Returns only a concrete replacement statement; pure denials intentionally return null. */
+function extractExplicitUnderstandingCorrectionContent(text) {
+	const normalized = text.replace(/\s+/g, " ").trim();
+	if (!isExplicitUnderstandingCorrection(normalized)) return null;
+	for (const pattern of UNDERSTANDING_CORRECTION_CONTENT_PATTERNS) {
+		const match = pattern.exec(normalized);
+		if (!match?.[1]) continue;
+		const content = normalizeCorrectionContent(match[1]);
+		if (content) return content;
+	}
+	return null;
+}
+//#endregion
+export { extractExplicitUnderstandingCorrectionContent, isExplicitUnderstandingCorrection };
+
+//# sourceMappingURL=correction.js.map

package/dist/src/agent/memory/understanding/correction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"correction.js","names":[],"sources":["../../../../../src/agent/memory/understanding/correction.ts"],"sourcesContent":["const UNDERSTANDING_CORRECTION_PATTERNS: RegExp[] = [\n  /(?:你|您)(?:记错|理解错|搞错)(?:了)?(?:我|我的)/,\n  /(?:这|那)(?:不是|并非)我的(?:偏好|习惯|情况|信息|边界)/,\n  /我(?:没有|从没|从未)(?:说过|表示过|要求过)(?:这|那|这个|那个)/,\n  /(?:不要|别再)(?:认为|假设|记成)(?:我|我的)/,\n  /you (?:remembered|understood|got) (?:me|my .+?) wrong\\b/i,\n  /that(?:'s| is) not my (?:preference|habit|situation|information|boundary)\\b/i,\n  /i (?:never|did not|didn't) (?:say|said|tell you|told you|ask for|asked for) that\\b/i,\n  /do not assume that about me\\b/i,\n];\n\nconst UNDERSTANDING_CORRECTION_CONTENT_PATTERNS: RegExp[] = [\n  /(?:你|您)(?:记错|理解错|搞错)(?:了)?(?:我|我的)(?:偏好|习惯|情况|信息|边界|工作方式)?[，,:：；;。]\\s*(?:其实|实际上|正确的是)?\\s*(.+)$/,\n  /(?:这|那)(?:不是|并非)我的(?:偏好|习惯|情况|信息|边界)[，,:：；;。]\\s*(.+)$/,\n  /you (?:remembered|understood|got) (?:me|my .+?) wrong\\b[,:;.]?\\s*(?:actually[,:]?\\s*)?(.+)$/i,\n  /that(?:'s| is) not my (?:preference|habit|situation|information|boundary)\\b[,:;.]?\\s*(.+)$/i,\n];\n\nfunction normalizeCorrectionContent(content: string): string | null {\n  const normalized = content\n    .replace(/^[“”‘’\"'\\s]+|[“”‘’\"'\\s]+$/g, '')\n    .replace(/\\s+/g, ' ')\n    .trim();\n  return normalized.length >= 4 ? normalized.slice(0, 600) : null;\n}\n\nexport function isExplicitUnderstandingCorrection(text: string): boolean {\n  const normalized = text.replace(/\\s+/g, ' ').trim();\n  return normalized.length > 0\n    && UNDERSTANDING_CORRECTION_PATTERNS.some((pattern) => pattern.test(normalized));\n}\n\n/** Returns only a concrete replacement statement; pure denials intentionally return null. */\nexport function extractExplicitUnderstandingCorrectionContent(text: string): string | null {\n  const normalized = text.replace(/\\s+/g, ' ').trim();\n  if (!isExplicitUnderstandingCorrection(normalized)) return null;\n  for (const pattern of UNDERSTANDING_CORRECTION_CONTENT_PATTERNS) {\n    const match = pattern.exec(normalized);\n    if (!match?.[1]) continue;\n    const content = normalizeCorrectionContent(match[1]);\n    if (content) return content;\n  }\n  return null;\n}\n"],"mappings":";AAAA,MAAM,oCAA8C;CAClD;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD;AAED,MAAM,4CAAsD;CAC1D;CACA;CACA;CACA;CACD;AAED,SAAS,2BAA2B,SAAgC;CAClE,MAAM,aAAa,QAChB,QAAQ,8BAA8B,GAAG,CACzC,QAAQ,QAAQ,IAAI,CACpB,MAAM;AACT,QAAO,WAAW,UAAU,IAAI,WAAW,MAAM,GAAG,IAAI,GAAG;;AAG7D,SAAgB,kCAAkC,MAAuB;CACvE,MAAM,aAAa,KAAK,QAAQ,QAAQ,IAAI,CAAC,MAAM;AACnD,QAAO,WAAW,SAAS,KACtB,kCAAkC,MAAM,YAAY,QAAQ,KAAK,WAAW,CAAC;;;AAIpF,SAAgB,8CAA8C,MAA6B;CACzF,MAAM,aAAa,KAAK,QAAQ,QAAQ,IAAI,CAAC,MAAM;AACnD,KAAI,CAAC,kCAAkC,WAAW,CAAE,QAAO;AAC3D,MAAK,MAAM,WAAW,2CAA2C;EAC/D,MAAM,QAAQ,QAAQ,KAAK,WAAW;AACtC,MAAI,CAAC,QAAQ,GAAI;EACjB,MAAM,UAAU,2BAA2B,MAAM,GAAG;AACpD,MAAI,QAAS,QAAO;;AAEtB,QAAO"}

package/dist/src/agent/memory/understanding/quality.d.ts

@@ -0,0 +1,8 @@
+import type { UserUnderstandingQualityMetrics } from '../../../storage/sqlite/index.js';
+export interface UnderstandingCadenceDecision {
+    baseIntervalTurns: number;
+    effectiveIntervalTurns: number;
+    slowed: boolean;
+    reasons: Array<'candidate_backlog' | 'low_acceptance' | 'low_recall_quality'>;
+}
+export declare function resolveAdaptiveUnderstandingCadence(baseIntervalTurns: number, metrics: UserUnderstandingQualityMetrics, enabled?: boolean): UnderstandingCadenceDecision;

package/dist/src/agent/memory/understanding/quality.js

@@ -0,0 +1,20 @@
+//#region src/agent/memory/understanding/quality.ts
+function resolveAdaptiveUnderstandingCadence(baseIntervalTurns, metrics, enabled = true) {
+	const base = Math.max(1, Math.min(1e3, Math.floor(baseIntervalTurns)));
+	const reasons = [];
+	if (enabled) {
+		if (metrics.records.candidate >= 20 || metrics.records.agingCandidates >= 10) reasons.push("candidate_backlog");
+		if (metrics.decisions.total >= 10 && metrics.decisions.acceptanceRate != null && metrics.decisions.acceptanceRate < .25) reasons.push("low_acceptance");
+		if (metrics.recall.total >= 10 && metrics.recall.helpfulRate != null && metrics.recall.helpfulRate < .4) reasons.push("low_recall_quality");
+	}
+	return {
+		baseIntervalTurns: base,
+		effectiveIntervalTurns: reasons.length > 0 ? Math.min(1e3, base * 2) : base,
+		slowed: reasons.length > 0,
+		reasons
+	};
+}
+//#endregion
+export { resolveAdaptiveUnderstandingCadence };
+
+//# sourceMappingURL=quality.js.map

package/dist/src/agent/memory/understanding/quality.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"quality.js","names":[],"sources":["../../../../../src/agent/memory/understanding/quality.ts"],"sourcesContent":["import type { UserUnderstandingQualityMetrics } from '../../../storage/sqlite/index.js';\n\nexport interface UnderstandingCadenceDecision {\n  baseIntervalTurns: number;\n  effectiveIntervalTurns: number;\n  slowed: boolean;\n  reasons: Array<'candidate_backlog' | 'low_acceptance' | 'low_recall_quality'>;\n}\n\nexport function resolveAdaptiveUnderstandingCadence(\n  baseIntervalTurns: number,\n  metrics: UserUnderstandingQualityMetrics,\n  enabled = true,\n): UnderstandingCadenceDecision {\n  const base = Math.max(1, Math.min(1_000, Math.floor(baseIntervalTurns)));\n  const reasons: UnderstandingCadenceDecision['reasons'] = [];\n  if (enabled) {\n    if (metrics.records.candidate >= 20 || metrics.records.agingCandidates >= 10) {\n      reasons.push('candidate_backlog');\n    }\n    if (\n      metrics.decisions.total >= 10\n      && metrics.decisions.acceptanceRate != null\n      && metrics.decisions.acceptanceRate < 0.25\n    ) {\n      reasons.push('low_acceptance');\n    }\n    if (\n      metrics.recall.total >= 10\n      && metrics.recall.helpfulRate != null\n      && metrics.recall.helpfulRate < 0.4\n    ) {\n      reasons.push('low_recall_quality');\n    }\n  }\n  return {\n    baseIntervalTurns: base,\n    effectiveIntervalTurns: reasons.length > 0 ? Math.min(1_000, base * 2) : base,\n    slowed: reasons.length > 0,\n    reasons,\n  };\n}\n"],"mappings":";AASA,SAAgB,oCACd,mBACA,SACA,UAAU,MACoB;CAC9B,MAAM,OAAO,KAAK,IAAI,GAAG,KAAK,IAAI,KAAO,KAAK,MAAM,kBAAkB,CAAC,CAAC;CACxE,MAAM,UAAmD,EAAE;AAC3D,KAAI,SAAS;AACX,MAAI,QAAQ,QAAQ,aAAa,MAAM,QAAQ,QAAQ,mBAAmB,GACxE,SAAQ,KAAK,oBAAoB;AAEnC,MACE,QAAQ,UAAU,SAAS,MACxB,QAAQ,UAAU,kBAAkB,QACpC,QAAQ,UAAU,iBAAiB,IAEtC,SAAQ,KAAK,iBAAiB;AAEhC,MACE,QAAQ,OAAO,SAAS,MACrB,QAAQ,OAAO,eAAe,QAC9B,QAAQ,OAAO,cAAc,GAEhC,SAAQ,KAAK,qBAAqB;;AAGtC,QAAO;EACL,mBAAmB;EACnB,wBAAwB,QAAQ,SAAS,IAAI,KAAK,IAAI,KAAO,OAAO,EAAE,GAAG;EACzE,QAAQ,QAAQ,SAAS;EACzB;EACD"}

package/dist/src/agent/memory/understanding/service.d.ts

@@ -0,0 +1,26 @@
+import type { MemoryRecord, MemoryWriteRequest, MemoryWriteResult } from '../types.js';
+import type { UnderstandingCandidate, UnderstandingReviewResult } from './types.js';
+export declare function extractExplicitUnderstandingCandidates(userContent: string): UnderstandingCandidate[];
+export interface UserUnderstandingServiceOptions {
+    write: (request: MemoryWriteRequest) => Promise<MemoryWriteResult>;
+    list: (canonicalKey: string) => Promise<MemoryRecord[]>;
+}
+export declare class UserUnderstandingService {
+    private readonly options;
+    constructor(options: UserUnderstandingServiceOptions);
+    reviewTurn(params: {
+        agentId?: string;
+        userContent: string;
+        assistantContent: string;
+        sessionKey?: string;
+        correctionTargetRecordIds?: string[];
+    }): Promise<UnderstandingReviewResult>;
+    applyCandidates(candidates: UnderstandingCandidate[], context: {
+        agentId?: string;
+        sessionKey?: string;
+        sourceItemId?: string;
+        sourceText?: string;
+        reviewSource?: 'turn' | 'background';
+        supersedesRecordIds?: string[];
+    }): Promise<Omit<UnderstandingReviewResult, 'sourceItemId'>>;
+}

package/dist/src/agent/memory/understanding/service.js

@@ -0,0 +1,233 @@
+import { createLogger } from "../../../utils/logger/index.js";
+import { init_logger } from "../../../utils/logger.js";
+import { appendMemoryTraceEvent } from "../../../storage/sqlite/memory-records-repository.js";
+import { attachMemoryEvidence, upsertKnowledgeSourceItems } from "../../../storage/sqlite/knowledge-repository.js";
+import "../../../storage/sqlite/index.js";
+import { extractExplicitUnderstandingCorrectionContent } from "./correction.js";
+import { createHash } from "node:crypto";
+//#region src/agent/memory/understanding/service.ts
+init_logger();
+const log = createLogger("UserUnderstanding");
+const MAX_CANDIDATE_CHARS = 600;
+const EXPLICIT_PATTERNS = [
+	/\b(?:please\s+)?remember(?:\s+that)?\s+(.+)/i,
+	/\bkeep\s+in\s+mind(?:\s+that)?\s+(.+)/i,
+	/(?:请)?记住[：:\s]*(.+)/,
+	/以后(?:都)?(?:请)?[：:\s]*(.+)/,
+	/下次(?:请)?[：:\s]*(.+)/
+];
+function normalizeContent(raw) {
+	return raw.replace(/^["'“”‘’\s]+|["'“”‘’\s]+$/g, "").replace(/\s+/g, " ").trim().slice(0, MAX_CANDIDATE_CHARS);
+}
+function inferKind(content) {
+	if (/\b(don't|do not|never|avoid)\b/i.test(content) || /不要|别再|禁止|底线/.test(content)) return "boundary";
+	if (/\b(prefer|preference|like)\b/i.test(content) || /喜欢|偏好|习惯/.test(content)) return "preference";
+	if (/\b(tool|command|pnpm|npm|git|ripgrep|rg)\b/i.test(content) || /工具|命令/.test(content)) return "tool_preference";
+	if (/\b(project|repo|codebase|workspace)\b/i.test(content) || /项目|仓库|代码库/.test(content)) return "project_context";
+	if (/\b(goal|plan|commit|deadline)\b/i.test(content) || /目标|计划|承诺|截止/.test(content)) return "commitment";
+	if (/\b(next time|lesson|failed|error)\b/i.test(content) || /下次|教训|失败|错误/.test(content)) return "task_lesson";
+	return "agent_note";
+}
+function inferSensitivity(content) {
+	if (/\b(api[_-]?key|access[_-]?key|token|password|secret|credential|private[_-]?key|bearer)\b/i.test(content) || /密钥|密码|令牌|私钥/.test(content) || /\b(?:sk|gh[opsu]|xox[abprs])-[a-z0-9_-]{8,}\b/i.test(content) || /\bAKIA[A-Z0-9]{12,}\b/.test(content) || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)) return "secret";
+	if (/\b(ssn|social security|bank account|credit card|medical record)\b/i.test(content) || /身份证|银行卡|信用卡|医疗记录/.test(content)) return "regulated";
+	return /家庭|住址|生日|健康|关系|family|address|birthday|health/i.test(content) ? "personal" : "normal";
+}
+function redactSensitiveText(content) {
+	return content.replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED PRIVATE KEY]").replace(/\b(api[_-]?key|access[_-]?key|token|password|secret|credential|private[_-]?key|bearer)\b\s*[:=]?\s*[^\s,;]+/gi, "$1=[REDACTED]").replace(/(密钥|密码|令牌|私钥)\s*[：:=]?\s*[^\s，；]+/g, "$1=[REDACTED]").replace(/\b(?:sk|gh[opsu]|xox[abprs])-[a-z0-9_-]{8,}\b/gi, "[REDACTED TOKEN]").replace(/\bAKIA[A-Z0-9]{12,}\b/g, "[REDACTED ACCESS KEY]");
+}
+const SENSITIVITY_RANK = {
+	normal: 0,
+	personal: 1,
+	regulated: 2,
+	secret: 3
+};
+function stricterSensitivity(content, declared) {
+	const inferred = inferSensitivity(content);
+	return SENSITIVITY_RANK[inferred] > SENSITIVITY_RANK[declared] ? inferred : declared;
+}
+function canonicalKey(kind, content) {
+	const normalized = content.toLocaleLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+	return `${kind}:${createHash("sha256").update(normalized).digest("hex").slice(0, 20)}`;
+}
+function extractExplicitUnderstandingCandidates(userContent) {
+	const correction = extractExplicitUnderstandingCorrectionContent(userContent);
+	if (correction) {
+		const kind = inferKind(correction);
+		return [{
+			kind,
+			content: correction,
+			canonicalKey: canonicalKey(kind, correction),
+			confidence: .95,
+			importance: kind === "boundary" ? .9 : .8,
+			explicitness: "explicit",
+			durability: "durable",
+			sensitivity: inferSensitivity(correction),
+			disclosurePolicy: kind === "boundary" ? "silent" : "referenceable",
+			tags: ["user-understanding", "explicit-user-correction"]
+		}];
+	}
+	const lines = userContent.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+	for (const line of lines.length > 0 ? lines : [userContent.trim()]) for (const pattern of EXPLICIT_PATTERNS) {
+		const content = normalizeContent(pattern.exec(line)?.[1] ?? "");
+		if (content.length < 8) continue;
+		const kind = inferKind(content);
+		return [{
+			kind,
+			content,
+			canonicalKey: canonicalKey(kind, content),
+			confidence: .92,
+			importance: kind === "boundary" ? .9 : .75,
+			explicitness: "explicit",
+			durability: "durable",
+			sensitivity: inferSensitivity(content),
+			disclosurePolicy: kind === "boundary" ? "silent" : "referenceable",
+			tags: ["user-understanding", "explicit-user-request"]
+		}];
+	}
+	return [];
+}
+var UserUnderstandingService = class {
+	constructor(options) {
+		this.options = options;
+	}
+	async reviewTurn(params) {
+		const candidates = extractExplicitUnderstandingCandidates(params.userContent);
+		const sourceText = `User:\n${params.userContent.trim()}\n\nAssistant:\n${params.assistantContent.trim()}`;
+		const normalizedText = redactSensitiveText(sourceText);
+		const contentHash = createHash("sha256").update(sourceText).digest("hex");
+		const sourceItemId = upsertKnowledgeSourceItems([{
+			sourceInstanceId: params.sessionKey ? `session:${params.sessionKey}` : "session:unknown",
+			externalId: contentHash,
+			itemType: "conversation_turn",
+			authorRole: "user",
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString(),
+			contentHash,
+			normalizedText,
+			metadata: params.sessionKey ? { sessionKey: params.sessionKey } : {},
+			sensitivity: "personal",
+			retentionClass: "bounded",
+			synthesisStatus: "pending"
+		}]).items[0]?.id;
+		return {
+			...await this.applyCandidates(candidates, {
+				agentId: params.agentId,
+				sessionKey: params.sessionKey,
+				sourceItemId,
+				sourceText: params.userContent,
+				reviewSource: "turn",
+				supersedesRecordIds: params.correctionTargetRecordIds
+			}),
+			sourceItemId
+		};
+	}
+	async applyCandidates(candidates, context) {
+		const startedAt = Date.now();
+		let created = 0;
+		let deduplicated = 0;
+		let rejected = 0;
+		const recordIds = [];
+		for (const candidate of candidates.slice(0, 10)) {
+			const content = normalizeContent(candidate.content);
+			const sensitivity = stricterSensitivity(content, candidate.sensitivity);
+			if (content.length < 4 || candidate.confidence < .55 || sensitivity === "secret" || sensitivity === "regulated") {
+				rejected += 1;
+				continue;
+			}
+			const evidenceText = context.sourceText ? redactSensitiveText(context.sourceText).slice(0, MAX_CANDIDATE_CHARS) : void 0;
+			const key = candidate.canonicalKey ?? canonicalKey(candidate.kind, content);
+			const supersedesRecordId = context.supersedesRecordIds && [...new Set(context.supersedesRecordIds)].length === 1 ? context.supersedesRecordIds[0] : void 0;
+			const existing = await this.options.list(key);
+			const evidence = {
+				...context.sourceItemId ? { sourceItemId: context.sourceItemId } : {},
+				relation: "supports",
+				...context.sessionKey ? { sessionKey: context.sessionKey } : {},
+				...evidenceText ? { sourceText: evidenceText } : {},
+				observedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				confidence: candidate.confidence
+			};
+			if (existing[0]) {
+				deduplicated += 1;
+				recordIds.push(existing[0].id);
+				if (context.sourceItemId) attachMemoryEvidence({
+					recordId: existing[0].id,
+					sourceItemId: context.sourceItemId,
+					relation: "supports",
+					excerpt: evidenceText,
+					confidence: candidate.confidence
+				});
+				continue;
+			}
+			const write = await this.options.write({
+				kind: candidate.kind,
+				content,
+				canonicalKey: key,
+				scope: context.sessionKey ? { sessionKey: context.sessionKey } : void 0,
+				target: candidate.kind === "preference" ? "user" : "memory",
+				tags: [...new Set(["user-understanding", ...candidate.tags ?? []])],
+				source: { provider: "user-understanding" },
+				confidence: candidate.confidence,
+				status: "candidate",
+				sensitivity,
+				explicitness: candidate.explicitness,
+				durability: candidate.durability,
+				importance: candidate.importance,
+				disclosurePolicy: candidate.disclosurePolicy,
+				evidence: [evidence],
+				validFrom: candidate.validFrom,
+				validTo: candidate.validTo,
+				supersedesRecordId
+			});
+			if (write.success) {
+				created += 1;
+				if (write.record) recordIds.push(write.record.id);
+				if (write.record && context.sourceItemId) attachMemoryEvidence({
+					recordId: write.record.id,
+					sourceItemId: context.sourceItemId,
+					relation: "supports",
+					excerpt: evidenceText,
+					confidence: candidate.confidence
+				});
+			} else {
+				rejected += 1;
+				log.debug({
+					errorMessage: write.error,
+					canonicalKey: key
+				}, "Understanding candidate was not stored");
+			}
+		}
+		try {
+			appendMemoryTraceEvent({
+				sessionKey: context.sessionKey,
+				phase: "understanding",
+				providerId: "user-understanding",
+				request: {
+					...context.agentId ? { agentId: context.agentId } : {},
+					source: context.reviewSource ?? "turn",
+					proposed: candidates.length,
+					created,
+					deduplicated,
+					rejected
+				},
+				resultCount: created,
+				selectedRecordIds: recordIds,
+				durationMs: Date.now() - startedAt
+			});
+		} catch (err) {
+			log.debug({
+				err,
+				sessionKey: context.sessionKey
+			}, "Understanding quality trace append failed");
+		}
+		return {
+			proposed: candidates.length,
+			created,
+			deduplicated,
+			rejected
+		};
+	}
+};
+//#endregion
+export { UserUnderstandingService, extractExplicitUnderstandingCandidates };
+
+//# sourceMappingURL=service.js.map

package/dist/src/agent/memory/understanding/service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.js","names":[],"sources":["../../../../../src/agent/memory/understanding/service.ts"],"sourcesContent":["import { createHash } from 'node:crypto';\n\nimport {\n  appendMemoryTraceEvent,\n  attachMemoryEvidence,\n  upsertKnowledgeSourceItems,\n} from '../../../storage/sqlite/index.js';\nimport { createLogger } from '../../../utils/logger.js';\nimport type {\n  MemoryEvidence,\n  MemoryKind,\n  MemoryRecord,\n  MemorySensitivity,\n  MemoryWriteRequest,\n  MemoryWriteResult,\n} from '../types.js';\nimport { extractExplicitUnderstandingCorrectionContent } from './correction.js';\nimport type { UnderstandingCandidate, UnderstandingReviewResult } from './types.js';\n\nconst log = createLogger('UserUnderstanding');\nconst MAX_CANDIDATE_CHARS = 600;\n\nconst EXPLICIT_PATTERNS: RegExp[] = [\n  /\\b(?:please\\s+)?remember(?:\\s+that)?\\s+(.+)/i,\n  /\\bkeep\\s+in\\s+mind(?:\\s+that)?\\s+(.+)/i,\n  /(?:请)?记住[：:\\s]*(.+)/,\n  /以后(?:都)?(?:请)?[：:\\s]*(.+)/,\n  /下次(?:请)?[：:\\s]*(.+)/,\n];\n\nfunction normalizeContent(raw: string): string {\n  return raw\n    .replace(/^[\"'“”‘’\\s]+|[\"'“”‘’\\s]+$/g, '')\n    .replace(/\\s+/g, ' ')\n    .trim()\n    .slice(0, MAX_CANDIDATE_CHARS);\n}\n\nfunction inferKind(content: string): MemoryKind {\n  if (/\\b(don't|do not|never|avoid)\\b/i.test(content) || /不要|别再|禁止|底线/.test(content)) {\n    return 'boundary';\n  }\n  if (/\\b(prefer|preference|like)\\b/i.test(content) || /喜欢|偏好|习惯/.test(content)) {\n    return 'preference';\n  }\n  if (/\\b(tool|command|pnpm|npm|git|ripgrep|rg)\\b/i.test(content) || /工具|命令/.test(content)) {\n    return 'tool_preference';\n  }\n  if (/\\b(project|repo|codebase|workspace)\\b/i.test(content) || /项目|仓库|代码库/.test(content)) {\n    return 'project_context';\n  }\n  if (/\\b(goal|plan|commit|deadline)\\b/i.test(content) || /目标|计划|承诺|截止/.test(content)) {\n    return 'commitment';\n  }\n  if (/\\b(next time|lesson|failed|error)\\b/i.test(content) || /下次|教训|失败|错误/.test(content)) {\n    return 'task_lesson';\n  }\n  return 'agent_note';\n}\n\nfunction inferSensitivity(content: string): UnderstandingCandidate['sensitivity'] {\n  if (\n    /\\b(api[_-]?key|access[_-]?key|token|password|secret|credential|private[_-]?key|bearer)\\b/i.test(content)\n    || /密钥|密码|令牌|私钥/.test(content)\n    || /\\b(?:sk|gh[opsu]|xox[abprs])-[a-z0-9_-]{8,}\\b/i.test(content)\n    || /\\bAKIA[A-Z0-9]{12,}\\b/.test(content)\n    || /-----BEGIN [A-Z ]*PRIVATE KEY-----/.test(content)\n  ) {\n    return 'secret';\n  }\n  if (\n    /\\b(ssn|social security|bank account|credit card|medical record)\\b/i.test(content)\n    || /身份证|银行卡|信用卡|医疗记录/.test(content)\n  ) {\n    return 'regulated';\n  }\n  return /家庭|住址|生日|健康|关系|family|address|birthday|health/i.test(content)\n    ? 'personal'\n    : 'normal';\n}\n\nfunction redactSensitiveText(content: string): string {\n  return content\n    .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\\s\\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, '[REDACTED PRIVATE KEY]')\n    .replace(/\\b(api[_-]?key|access[_-]?key|token|password|secret|credential|private[_-]?key|bearer)\\b\\s*[:=]?\\s*[^\\s,;]+/gi, '$1=[REDACTED]')\n    .replace(/(密钥|密码|令牌|私钥)\\s*[：:=]?\\s*[^\\s，；]+/g, '$1=[REDACTED]')\n    .replace(/\\b(?:sk|gh[opsu]|xox[abprs])-[a-z0-9_-]{8,}\\b/gi, '[REDACTED TOKEN]')\n    .replace(/\\bAKIA[A-Z0-9]{12,}\\b/g, '[REDACTED ACCESS KEY]');\n}\n\nconst SENSITIVITY_RANK: Record<MemorySensitivity, number> = {\n  normal: 0,\n  personal: 1,\n  regulated: 2,\n  secret: 3,\n};\n\nfunction stricterSensitivity(content: string, declared: MemorySensitivity): MemorySensitivity {\n  const inferred = inferSensitivity(content);\n  return SENSITIVITY_RANK[inferred] > SENSITIVITY_RANK[declared] ? inferred : declared;\n}\n\nfunction canonicalKey(kind: MemoryKind, content: string): string {\n  const normalized = content\n    .toLocaleLowerCase()\n    .replace(/[^\\p{L}\\p{N}]+/gu, ' ')\n    .trim();\n  return `${kind}:${createHash('sha256').update(normalized).digest('hex').slice(0, 20)}`;\n}\n\nexport function extractExplicitUnderstandingCandidates(userContent: string): UnderstandingCandidate[] {\n  const correction = extractExplicitUnderstandingCorrectionContent(userContent);\n  if (correction) {\n    const kind = inferKind(correction);\n    return [{\n      kind,\n      content: correction,\n      canonicalKey: canonicalKey(kind, correction),\n      confidence: 0.95,\n      importance: kind === 'boundary' ? 0.9 : 0.8,\n      explicitness: 'explicit',\n      durability: 'durable',\n      sensitivity: inferSensitivity(correction),\n      disclosurePolicy: kind === 'boundary' ? 'silent' : 'referenceable',\n      tags: ['user-understanding', 'explicit-user-correction'],\n    }];\n  }\n  const lines = userContent.split(/\\r?\\n/).map((line) => line.trim()).filter(Boolean);\n  for (const line of lines.length > 0 ? lines : [userContent.trim()]) {\n    for (const pattern of EXPLICIT_PATTERNS) {\n      const content = normalizeContent(pattern.exec(line)?.[1] ?? '');\n      if (content.length < 8) continue;\n      const kind = inferKind(content);\n      return [{\n        kind,\n        content,\n        canonicalKey: canonicalKey(kind, content),\n        confidence: 0.92,\n        importance: kind === 'boundary' ? 0.9 : 0.75,\n        explicitness: 'explicit',\n        durability: 'durable',\n        sensitivity: inferSensitivity(content),\n        disclosurePolicy: kind === 'boundary' ? 'silent' : 'referenceable',\n        tags: ['user-understanding', 'explicit-user-request'],\n      }];\n    }\n  }\n  return [];\n}\n\nexport interface UserUnderstandingServiceOptions {\n  write: (request: MemoryWriteRequest) => Promise<MemoryWriteResult>;\n  list: (canonicalKey: string) => Promise<MemoryRecord[]>;\n}\n\nexport class UserUnderstandingService {\n  constructor(private readonly options: UserUnderstandingServiceOptions) {}\n\n  async reviewTurn(params: {\n    agentId?: string;\n    userContent: string;\n    assistantContent: string;\n    sessionKey?: string;\n    correctionTargetRecordIds?: string[];\n  }): Promise<UnderstandingReviewResult> {\n    const candidates = extractExplicitUnderstandingCandidates(params.userContent);\n    const sourceText = `User:\\n${params.userContent.trim()}\\n\\nAssistant:\\n${params.assistantContent.trim()}`;\n    const normalizedText = redactSensitiveText(sourceText);\n    const contentHash = createHash('sha256').update(sourceText).digest('hex');\n    const stored = upsertKnowledgeSourceItems([{\n      sourceInstanceId: params.sessionKey ? `session:${params.sessionKey}` : 'session:unknown',\n      externalId: contentHash,\n      itemType: 'conversation_turn',\n      authorRole: 'user',\n      occurredAt: new Date().toISOString(),\n      contentHash,\n      normalizedText,\n      metadata: params.sessionKey ? { sessionKey: params.sessionKey } : {},\n      sensitivity: 'personal',\n      retentionClass: 'bounded',\n      synthesisStatus: 'pending',\n    }]);\n    const sourceItemId = stored.items[0]?.id;\n    const result = await this.applyCandidates(candidates, {\n      agentId: params.agentId,\n      sessionKey: params.sessionKey,\n      sourceItemId,\n      sourceText: params.userContent,\n      reviewSource: 'turn',\n      supersedesRecordIds: params.correctionTargetRecordIds,\n    });\n    return { ...result, sourceItemId };\n  }\n\n  async applyCandidates(\n    candidates: UnderstandingCandidate[],\n    context: {\n      agentId?: string;\n      sessionKey?: string;\n      sourceItemId?: string;\n      sourceText?: string;\n      reviewSource?: 'turn' | 'background';\n      supersedesRecordIds?: string[];\n    },\n  ): Promise<Omit<UnderstandingReviewResult, 'sourceItemId'>> {\n    const startedAt = Date.now();\n    let created = 0;\n    let deduplicated = 0;\n    let rejected = 0;\n    const recordIds: string[] = [];\n    for (const candidate of candidates.slice(0, 10)) {\n      const content = normalizeContent(candidate.content);\n      const sensitivity = stricterSensitivity(content, candidate.sensitivity);\n      if (\n        content.length < 4\n        || candidate.confidence < 0.55\n        || sensitivity === 'secret'\n        || sensitivity === 'regulated'\n      ) {\n        rejected += 1;\n        continue;\n      }\n      const evidenceText = context.sourceText\n        ? redactSensitiveText(context.sourceText).slice(0, MAX_CANDIDATE_CHARS)\n        : undefined;\n      const key = candidate.canonicalKey ?? canonicalKey(candidate.kind, content);\n      const supersedesRecordId = context.supersedesRecordIds\n        && [...new Set(context.supersedesRecordIds)].length === 1\n        ? context.supersedesRecordIds[0]\n        : undefined;\n      const existing = await this.options.list(key);\n      const evidence: MemoryEvidence = {\n        ...(context.sourceItemId ? { sourceItemId: context.sourceItemId } : {}),\n        relation: 'supports',\n        ...(context.sessionKey ? { sessionKey: context.sessionKey } : {}),\n        ...(evidenceText ? { sourceText: evidenceText } : {}),\n        observedAt: new Date().toISOString(),\n        confidence: candidate.confidence,\n      };\n      if (existing[0]) {\n        deduplicated += 1;\n        recordIds.push(existing[0].id);\n        if (context.sourceItemId) {\n          attachMemoryEvidence({\n            recordId: existing[0].id,\n            sourceItemId: context.sourceItemId,\n            relation: 'supports',\n            excerpt: evidenceText,\n            confidence: candidate.confidence,\n          });\n        }\n        continue;\n      }\n      const write = await this.options.write({\n        kind: candidate.kind,\n        content,\n        canonicalKey: key,\n        scope: context.sessionKey ? { sessionKey: context.sessionKey } : undefined,\n        target: candidate.kind === 'preference' ? 'user' : 'memory',\n        tags: [...new Set(['user-understanding', ...(candidate.tags ?? [])])],\n        source: { provider: 'user-understanding' },\n        confidence: candidate.confidence,\n        status: 'candidate',\n        sensitivity,\n        explicitness: candidate.explicitness,\n        durability: candidate.durability,\n        importance: candidate.importance,\n        disclosurePolicy: candidate.disclosurePolicy,\n        evidence: [evidence],\n        validFrom: candidate.validFrom,\n        validTo: candidate.validTo,\n        supersedesRecordId,\n      });\n      if (write.success) {\n        created += 1;\n        if (write.record) recordIds.push(write.record.id);\n        if (write.record && context.sourceItemId) {\n          attachMemoryEvidence({\n            recordId: write.record.id,\n            sourceItemId: context.sourceItemId,\n            relation: 'supports',\n            excerpt: evidenceText,\n            confidence: candidate.confidence,\n          });\n        }\n      } else {\n        rejected += 1;\n        log.debug({ errorMessage: write.error, canonicalKey: key }, 'Understanding candidate was not stored');\n      }\n    }\n    try {\n      appendMemoryTraceEvent({\n        sessionKey: context.sessionKey,\n        phase: 'understanding',\n        providerId: 'user-understanding',\n        request: {\n          ...(context.agentId ? { agentId: context.agentId } : {}),\n          source: context.reviewSource ?? 'turn',\n          proposed: candidates.length,\n          created,\n          deduplicated,\n          rejected,\n        },\n        resultCount: created,\n        selectedRecordIds: recordIds,\n        durationMs: Date.now() - startedAt,\n      });\n    } catch (err) {\n      log.debug({ err, sessionKey: context.sessionKey }, 'Understanding quality trace append failed');\n    }\n    return { proposed: candidates.length, created, deduplicated, rejected };\n  }\n}\n"],"mappings":"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"}

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

@@ -0,0 +1,22 @@
+import type { MemoryDisclosurePolicy, MemoryDurability, MemoryExplicitness, MemoryKind, MemorySensitivity } from '../types.js';
+export interface UnderstandingCandidate {
+    kind: MemoryKind;
+    content: string;
+    canonicalKey?: string;
+    confidence: number;
+    importance: number;
+    explicitness: MemoryExplicitness;
+    durability: MemoryDurability;
+    sensitivity: MemorySensitivity;
+    disclosurePolicy: MemoryDisclosurePolicy;
+    tags?: string[];
+    validFrom?: string;
+    validTo?: string;
+}
+export interface UnderstandingReviewResult {
+    sourceItemId?: string;
+    proposed: number;
+    created: number;
+    deduplicated: number;
+    rejected: number;
+}

package/dist/src/agent/memory/understanding/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/agent/memory/user-context-coordinator.d.ts

@@ -0,0 +1,21 @@
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Config } from '../../config/schema.js';
+import type { UserContextPlan } from './context/types.js';
+import type { MemoryManager } from './manager.js';
+export interface UserContextCoordinatorOptions {
+    getConfig: () => Config | undefined;
+    isEnabledForSession: (sessionKey: string) => boolean;
+    getMemoryManagerForSession: (sessionKey: string) => MemoryManager;
+    getLastAssistantContent: (sessionKey: string) => string | null;
+}
+export declare class UserContextCoordinator {
+    private readonly options;
+    private readonly userTurn;
+    private readonly correctionTargets;
+    private readonly planner;
+    constructor(options: UserContextCoordinatorOptions);
+    forgetSession(sessionKey: string): void;
+    clear(): void;
+    prepare(userMessage: AgentMessage, sessionKey: string): Promise<UserContextPlan>;
+    afterTurn(sessionKey: string, userPlainText: string): Promise<void>;
+}