cloudflare-mcp-smart-proxy 1.5.4 → 1.5.6

package/README.md

@@ -106,6 +106,21 @@ npx -y -p cloudflare-mcp-smart-proxy cloudmcp-connector activate codex \
 - [CLOUDMCP_A2_EXTERNAL_CONNECTOR_CONTRACT_STANDARD_2026-03-30.md](/home/coder/project/CLOUDMCP/docs/CLOUDMCP_A2_EXTERNAL_CONNECTOR_CONTRACT_STANDARD_2026-03-30.md)
 - [CLOUDMCP_A3_OFFICIAL_REFERENCE_CONNECTOR_STANDARD_2026-03-30.md](/home/coder/project/CLOUDMCP/docs/CLOUDMCP_A3_OFFICIAL_REFERENCE_CONNECTOR_STANDARD_2026-03-30.md)
 
+## 本地记忆目标
+
+原有 `cloudflare-mcp-smart-proxy` 包同时提供以下本地工具：
+
+- `configure_local_memory_target`：显式配置一个本地 JSON 记忆目录，并从当前连接器获授权的云端 scope 初始化有效条目。
+- `get_local_memory_target`：读取当前连接器工作空间的本机目标契约。
+- `verify_local_memory_target`：回读验证目标契约或一个精确条目。
+- `capture_memory`：以同一事务写入受治理的 CloudMCP memory plane 和已配置本地目标，双端回读一致后才返回成功。
+- `invalidate_memory`：以 revision、原因和证据软失效一个精确条目，并把同一 canonical JSON 提交到本地与云端。
+- `close_session`：把简洁交接转换为 `working + handoff`，复用与 `capture_memory` 相同的双端事务。
+
+`capture_memory / invalidate_memory / close_session` 只有在当前连接器通过云端鉴权、对应工具能力授权及精确 `memory_scope` 资源授权后才会被本地协调器暴露。它们仍复用原代理的 API Key、设备签名和 CloudMCP 请求路由，不存在匿名云端写入口。`search_memory / get_memory_entry / load_context` 保持受治理云端只读工具，由同一授权链提供。
+
+本地目录不是硬编码的。以 SoloMap 为目标时，用户或 Agent 可把其记忆根目录显式传给配置工具；未安装 CloudMCP 的 SoloMap 用户继续使用原有 Markdown 机制，公共 SoloMap 插件不会默认依赖这些工具。
+
 ## 常用命令
 
 ### Dry-run 渲染配置
@@ -137,6 +152,7 @@ node connector-cli.js reload codex
 node --test /home/coder/project/CLOUDMCP/tests/reference-connector-a3.test.js \
   /home/coder/project/CLOUDMCP/tests/codex-app-server-reload.test.js \
   /home/coder/project/CLOUDMCP/tests/local-proxy-device-identity.test.js \
+  /home/coder/project/CLOUDMCP/tests/local-proxy-memory.test.js \
   /home/coder/project/CLOUDMCP/tests/local-proxy-tool-discovery.test.js
 ```
 

package/index.js

@@ -16,6 +16,7 @@ import {
 import { sanitizeProxyError, SmartRouter } from './src/router.js';
 import { LocalToolExecutor } from './src/local-tools.js';
 import { ConnectorBridge } from './src/connector-bridge.js';
+import { LocalMemoryCoordinator } from './src/local-memory-coordinator.js';
 import fs from 'fs';
 
 // 从环境变量读取配置
@@ -68,8 +69,16 @@ const connectorBridge = new ConnectorBridge({
   workspaceId: WORKSPACE_ID,
   deviceIdentityPath: DEVICE_IDENTITY_PATH
 });
-const localTools = new LocalToolExecutor(WORKSPACE_ROOT, connectorBridge);
+const memoryCoordinator = new LocalMemoryCoordinator({
+  workspaceRoot: WORKSPACE_ROOT,
+  cloudUrl: CLOUD_URL,
+  clientProfileId: CLIENT_PROFILE_ID,
+  workspaceId: WORKSPACE_ID,
+  connectorId: CONNECTOR_ID
+});
+const localTools = new LocalToolExecutor(WORKSPACE_ROOT, connectorBridge, memoryCoordinator);
 const router = new SmartRouter(CLOUD_URL, CLOUD_API_KEY, localTools, WORKSPACE_ROOT, connectorBridge.deviceIdentity);
+localTools.setCloudToolCaller((tool, params) => router.callCloudTool(tool, params));
 
 // 创建 MCP 服务器
 const server = new Server(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cloudflare-mcp-smart-proxy",
-  "version": "1.5.4",
+  "version": "1.5.6",
   "description": "Smart proxy for Cloudflare MCP - routes tools to cloud or local execution",
   "repository": {
     "type": "git",

package/src/local-memory-coordinator.js

@@ -0,0 +1,392 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import {
+  assertMemoryEntryIntegrity,
+  canonicalMemoryJson,
+  validateMemoryCaptureInput,
+  validateMemoryIdentifier
+} from './memory-schema.js';
+
+function writeJsonAtomically(filePath, value, mode = 0o600) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temporaryPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(temporaryPath, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', flag: 'wx', mode });
+    fs.renameSync(temporaryPath, filePath);
+    if (process.platform !== 'win32') fs.chmodSync(filePath, mode);
+  } catch (error) {
+    if (fs.existsSync(temporaryPath)) fs.unlinkSync(temporaryPath);
+    throw error;
+  }
+}
+
+function readJson(filePath) {
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function fingerprint(parts) {
+  return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 24);
+}
+
+function resolveConfiguredDirectory(directory, workspaceRoot) {
+  const raw = typeof directory === 'string' ? directory.trim() : '';
+  if (!raw) throw new Error('directory is required');
+  if (/[*?\[\]{}]/.test(raw) || /\$\{|%[A-Za-z_][A-Za-z0-9_]*%/.test(raw) || raw.startsWith('~')) {
+    throw new Error('directory must be an explicit path without globs or unresolved variables');
+  }
+  const resolved = path.resolve(workspaceRoot, raw);
+  const filesystemRoot = path.parse(resolved).root;
+  if (resolved === filesystemRoot || resolved === os.homedir()) {
+    throw new Error('directory must not be a filesystem root or the home directory');
+  }
+  fs.mkdirSync(resolved, { recursive: true });
+  return fs.realpathSync(resolved);
+}
+
+function currentGitCommit(workspaceRoot) {
+  try {
+    return execFileSync('git', ['rev-parse', 'HEAD'], {
+      cwd: workspaceRoot,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+
+export class LocalMemoryCoordinator {
+  constructor(options = {}) {
+    this.workspaceRoot = path.resolve(options.workspaceRoot || process.cwd());
+    this.cloudUrl = String(options.cloudUrl || '').replace(/\/$/, '');
+    this.clientProfileId = options.clientProfileId || '';
+    this.workspaceId = options.workspaceId || '';
+    this.connectorId = options.connectorId || '';
+    this.homeDir = options.homeDir || os.homedir();
+    this.cloudToolCaller = options.cloudToolCaller || null;
+    const bindingFingerprint = fingerprint([
+      this.cloudUrl,
+      this.clientProfileId,
+      this.workspaceId,
+      this.connectorId,
+      this.workspaceRoot
+    ]);
+    this.privateRoot = path.join(this.homeDir, '.cloudmcp', 'memory-targets', bindingFingerprint);
+    this.contractPath = path.join(this.privateRoot, 'contract.json');
+    this.transactionsRoot = path.join(this.privateRoot, 'transactions');
+  }
+
+  setCloudToolCaller(caller) {
+    this.cloudToolCaller = caller;
+  }
+
+  async callCloud(tool, params) {
+    if (!this.cloudToolCaller) throw new Error('Cloud memory transport is not configured');
+    return await this.cloudToolCaller(tool, params);
+  }
+
+  getContract() {
+    if (!fs.existsSync(this.contractPath)) return null;
+    return readJson(this.contractPath);
+  }
+
+  async configure(params = {}) {
+    if (params.adapter !== 'solomap') throw new Error('Only the solomap memory adapter is currently supported');
+    const schemaVersion = Number(params.schema_version || params.schemaVersion || 1);
+    if (schemaVersion !== 1) throw new Error(`Unsupported local memory schema version: ${schemaVersion}`);
+    const directory = resolveConfiguredDirectory(params.directory, this.workspaceRoot);
+    const existing = this.getContract();
+    if (existing && existing.directory !== directory) {
+      throw new Error('A different local memory target is already active for this connector workspace');
+    }
+    const entriesRoot = path.join(directory, 'entries');
+    fs.mkdirSync(entriesRoot, { recursive: true });
+    const probePath = path.join(directory, `.cloudmcp-write-probe-${process.pid}.json`);
+    writeJsonAtomically(probePath, { ok: true });
+    const probe = readJson(probePath);
+    fs.unlinkSync(probePath);
+    if (probe.ok !== true) throw new Error('Local memory target write verification failed');
+
+    const scopesResult = await this.callCloud('list_memory_scopes', {});
+    const scopes = Array.isArray(scopesResult?.memory_scopes) ? scopesResult.memory_scopes : [];
+    if (scopes.length === 0) throw new Error('No governed CloudMCP memory scope is available');
+    const cloudScopeIds = scopes.map((scope) => scope.id).filter(Boolean);
+    const targetId = existing?.targetId || `memory_target_${randomUUID().replace(/-/g, '')}`;
+    const preparingContract = {
+      schemaVersion: 1,
+      targetId,
+      adapter: 'solomap',
+      format: 'cloudmcp-memory-json-v1',
+      workspaceId: this.workspaceId,
+      connectorId: this.connectorId,
+      cloudScopeIds,
+      status: 'preparing'
+    };
+    writeJsonAtomically(path.join(directory, 'contract.json'), preparingContract);
+    writeJsonAtomically(this.contractPath, { ...preparingContract, directory });
+
+    let hydratedEntries = 0;
+    for (const scopeId of cloudScopeIds) {
+      let offset = 0;
+      while (true) {
+        const loaded = await this.callCloud('load_context', {
+          memory_scope_id: scopeId,
+          include_layers: ['stable', 'working', 'candidate'],
+          limit: 50,
+          offset
+        });
+        const entries = Array.isArray(loaded?.entries) ? loaded.entries : [];
+        for (const entry of entries) {
+          assertMemoryEntryIntegrity(entry);
+          const entryPath = path.join(entriesRoot, `${entry.id}.json`);
+          if (fs.existsSync(entryPath)) {
+            const current = assertMemoryEntryIntegrity(readJson(entryPath));
+            if (current.canonicalHash !== entry.canonicalHash) {
+              throw new Error(`Local memory entry differs from CloudMCP: ${entry.id}`);
+            }
+          } else {
+            writeJsonAtomically(entryPath, entry);
+          }
+          hydratedEntries += 1;
+        }
+        if (!loaded?.pagination?.hasMore) break;
+        offset += entries.length;
+        if (entries.length === 0) break;
+      }
+    }
+    const publicContract = { ...preparingContract, status: 'active' };
+    writeJsonAtomically(path.join(directory, 'contract.json'), publicContract);
+    writeJsonAtomically(this.contractPath, { ...publicContract, directory });
+    return { configured: true, verified: true, contract: publicContract, hydratedEntries };
+  }
+
+  verify(params = {}) {
+    const contract = this.getContract();
+    if (!contract) throw new Error('Local memory target is not configured');
+    const marker = readJson(path.join(contract.directory, 'contract.json'));
+    if (marker.targetId !== contract.targetId || marker.schemaVersion !== 1 || marker.status !== 'active') {
+      throw new Error('Local memory target contract verification failed');
+    }
+    if (params.memory_id) {
+      const memoryId = validateMemoryIdentifier(params.memory_id, 'memory_id');
+      assertMemoryEntryIntegrity(readJson(path.join(contract.directory, 'entries', `${memoryId}.json`)));
+    }
+    return {
+      configured: true,
+      verified: true,
+      contract: { ...marker, directory: contract.directory },
+      memoryId: params.memory_id || null
+    };
+  }
+
+  async capture(params = {}) {
+    const contract = this.getContract();
+    if (!contract || contract.status !== 'active') throw new Error('Local memory target is not configured');
+    const input = validateMemoryCaptureInput(params);
+    const requestedScope = params.memory_scope_id || params.memoryScopeId || '';
+    if (requestedScope && !contract.cloudScopeIds.includes(requestedScope)) {
+      throw new Error(`Memory scope is not authorized by the local target contract: ${requestedScope}`);
+    }
+    const requestedTransactionId = params.transaction_id || params.transactionId;
+    const transactionId = requestedTransactionId
+      ? validateMemoryIdentifier(requestedTransactionId, 'transaction_id')
+      : `memory_txn_${randomUUID().replace(/-/g, '')}`;
+    const transactionPath = path.join(this.transactionsRoot, `${transactionId}.json`);
+    const existingTransaction = fs.existsSync(transactionPath) ? readJson(transactionPath) : null;
+    const requestedMemoryId = existingTransaction?.memoryId || params.memory_id || params.memoryId;
+    const memoryId = requestedMemoryId
+      ? validateMemoryIdentifier(requestedMemoryId, 'memory_id')
+      : `mem_${randomUUID().replace(/-/g, '')}`;
+    const semanticFingerprint = createHash('sha256').update(JSON.stringify(input)).digest('hex');
+    if (existingTransaction && existingTransaction.semanticFingerprint !== semanticFingerprint) {
+      throw new Error(`Memory transaction input changed: ${transactionId}`);
+    }
+    const gitCommit = existingTransaction?.gitCommit || currentGitCommit(this.workspaceRoot);
+    writeJsonAtomically(transactionPath, {
+      schemaVersion: 1,
+      transactionId,
+      memoryId,
+      gitCommit,
+      semanticFingerprint,
+      status: 'preparing',
+      createdAt: existingTransaction?.createdAt || new Date().toISOString(),
+      updatedAt: new Date().toISOString()
+    });
+
+    let stage = 'cloud_write';
+    try {
+      const cloudResult = await this.callCloud('capture_memory', {
+        memory_scope_id: requestedScope || undefined,
+        layer: input.layer,
+        kind: input.kind,
+        title: input.title,
+        content: input.content,
+        tags: input.tags,
+        evidence_refs: input.evidenceRefs,
+        verified_at: input.verifiedAt || undefined,
+        valid_from: input.validFrom || undefined,
+        valid_until: input.validUntil || undefined,
+        supersedes: input.supersedes,
+        memory_id: memoryId,
+        transaction_id: transactionId,
+        expected_revision: params.expected_revision || params.expectedRevision,
+        git_commit: gitCommit || undefined
+      });
+      if (cloudResult?.verified !== true) throw new Error(`Cloud memory did not confirm readback: ${memoryId}`);
+      const entry = assertMemoryEntryIntegrity(cloudResult.entry);
+      if (!contract.cloudScopeIds.includes(entry.scopeId)) {
+        throw new Error(`CloudMCP returned an unauthorized memory scope: ${entry.scopeId}`);
+      }
+      const supersededEntries = Array.isArray(cloudResult.superseded_entries)
+        ? cloudResult.superseded_entries.map((item) => assertMemoryEntryIntegrity(item))
+        : [];
+      if (supersededEntries.some((item) => item.scopeId !== entry.scopeId || item.status !== 'superseded')) {
+        throw new Error('CloudMCP returned an invalid superseded memory entry set');
+      }
+      stage = 'local_write';
+      const entryPath = path.join(contract.directory, 'entries', `${entry.id}.json`);
+      writeJsonAtomically(entryPath, entry);
+      for (const supersededEntry of supersededEntries) {
+        writeJsonAtomically(
+          path.join(contract.directory, 'entries', `${supersededEntry.id}.json`),
+          supersededEntry
+        );
+      }
+      stage = 'local_readback';
+      const localEntry = assertMemoryEntryIntegrity(readJson(entryPath));
+      if (canonicalMemoryJson(localEntry) !== canonicalMemoryJson(entry)) {
+        throw new Error(`Local memory readback verification failed for ${entry.id}`);
+      }
+      for (const supersededEntry of supersededEntries) {
+        const localSupersededEntry = assertMemoryEntryIntegrity(readJson(
+          path.join(contract.directory, 'entries', `${supersededEntry.id}.json`)
+        ));
+        if (canonicalMemoryJson(localSupersededEntry) !== canonicalMemoryJson(supersededEntry)) {
+          throw new Error(`Local memory readback verification failed for ${supersededEntry.id}`);
+        }
+      }
+      writeJsonAtomically(transactionPath, {
+        schemaVersion: 1,
+        transactionId,
+        memoryId,
+        semanticFingerprint,
+        gitCommit,
+        status: 'verified',
+        canonicalHash: entry.canonicalHash,
+        revision: entry.revision,
+        createdAt: existingTransaction?.createdAt || new Date().toISOString(),
+        updatedAt: new Date().toISOString()
+      });
+      return {
+        success: true,
+        memoryId: entry.id,
+        transactionId,
+        revision: entry.revision,
+        canonicalHash: entry.canonicalHash,
+        local: { persisted: true, verified: true },
+        cloud: { persisted: true, verified: true },
+        supersededMemoryIds: supersededEntries.map((item) => item.id),
+        entry
+      };
+    } catch (error) {
+      const cloudStatus = stage === 'cloud_write' ? 'unknown' : 'verified';
+      const localStatus = stage === 'cloud_write'
+        ? 'not_started'
+        : (stage === 'local_write' ? 'failed' : 'persisted_unverified');
+      try {
+        writeJsonAtomically(transactionPath, {
+          schemaVersion: 1,
+          transactionId,
+          memoryId,
+          semanticFingerprint,
+          gitCommit,
+          status: 'failed',
+          failedStage: stage,
+          cloudStatus,
+          localStatus,
+          createdAt: existingTransaction?.createdAt || new Date().toISOString(),
+          updatedAt: new Date().toISOString()
+        });
+      } catch {}
+      throw new Error(
+        `Memory transaction ${transactionId} failed at ${stage} `
+        + `(cloud=${cloudStatus}, local=${localStatus}): ${error?.message || 'unknown error'}`
+      );
+    }
+  }
+
+  async invalidate(params = {}) {
+    const contract = this.getContract();
+    if (!contract || contract.status !== 'active') throw new Error('Local memory target is not configured');
+    const memoryId = validateMemoryIdentifier(params.memory_id || params.memoryId, 'memory_id');
+    const requestedScope = params.memory_scope_id || params.memoryScopeId || '';
+    if (requestedScope && !contract.cloudScopeIds.includes(requestedScope)) {
+      throw new Error(`Memory scope is not authorized by the local target contract: ${requestedScope}`);
+    }
+    let stage = 'cloud_write';
+    try {
+      const result = await this.callCloud('invalidate_memory', {
+        memory_scope_id: requestedScope || undefined,
+        memory_id: memoryId,
+        expected_revision: params.expected_revision || params.expectedRevision,
+        reason: params.reason,
+        evidence_refs: params.evidence_refs || params.evidenceRefs
+      });
+      if (result?.verified !== true) throw new Error(`Cloud memory did not confirm invalidation readback: ${memoryId}`);
+      const entry = assertMemoryEntryIntegrity(result.entry);
+      if (!contract.cloudScopeIds.includes(entry.scopeId) || entry.status !== 'invalidated') {
+        throw new Error(`CloudMCP returned an invalid memory invalidation: ${memoryId}`);
+      }
+      stage = 'local_write';
+      const entryPath = path.join(contract.directory, 'entries', `${entry.id}.json`);
+      writeJsonAtomically(entryPath, entry);
+      stage = 'local_readback';
+      const localEntry = assertMemoryEntryIntegrity(readJson(entryPath));
+      if (canonicalMemoryJson(localEntry) !== canonicalMemoryJson(entry)) {
+        throw new Error(`Local memory invalidation readback failed for ${entry.id}`);
+      }
+      return {
+        success: true,
+        memoryId: entry.id,
+        revision: entry.revision,
+        canonicalHash: entry.canonicalHash,
+        idempotent: result.idempotent === true,
+        local: { persisted: true, verified: true },
+        cloud: { persisted: true, verified: true },
+        entry
+      };
+    } catch (error) {
+      const cloudStatus = stage === 'cloud_write' ? 'unknown' : 'verified';
+      const localStatus = stage === 'cloud_write' ? 'not_started' : (stage === 'local_write' ? 'failed' : 'persisted_unverified');
+      throw new Error(
+        `Memory invalidation ${memoryId} failed at ${stage} `
+        + `(cloud=${cloudStatus}, local=${localStatus}): ${error?.message || 'unknown error'}`
+      );
+    }
+  }
+
+  async closeSession(params = {}) {
+    const summary = typeof params.summary === 'string' ? params.summary.trim() : '';
+    if (!summary) throw new Error('summary is required');
+    const nextSteps = (Array.isArray(params.next_steps) ? params.next_steps : [])
+      .map((step) => String(step).trim())
+      .filter(Boolean);
+    const content = nextSteps.length
+      ? `${summary}\n\nNext steps:\n${nextSteps.map((step) => `- ${String(step).trim()}`).join('\n')}`
+      : summary;
+    const captured = await this.capture({
+      memory_scope_id: params.memory_scope_id || params.memoryScopeId,
+      layer: 'working',
+      kind: 'handoff',
+      title: params.title || 'Session handoff',
+      content,
+      tags: params.tags,
+      transaction_id: params.transaction_id || params.transactionId
+    });
+    return { ...captured, closed: true };
+  }
+}

package/src/local-tools.js

@@ -10,9 +10,14 @@ import { SymbolTools } from './tools/symbol-tools.js';
 import { Diagnostics } from './tools/diagnostics.js';
 
 export class LocalToolExecutor {
-  constructor(workspaceRoot, connectorBridge = null) {
+  constructor(workspaceRoot, connectorBridge = null, memoryCoordinator = null) {
     this.workspaceRoot = workspaceRoot;
     this.connectorBridge = connectorBridge;
+    this.memoryCoordinator = memoryCoordinator;
+  }
+
+  setCloudToolCaller(caller) {
+    this.memoryCoordinator?.setCloudToolCaller(caller);
   }
 
   /**
@@ -76,6 +81,30 @@ export class LocalToolExecutor {
       case 'connector_report_project_probe':
         if (!this.connectorBridge) throw new Error('Connector bridge is not configured');
         return await this.connectorBridge.reportProjectProbe(params || {});
+
+      case 'configure_local_memory_target':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return await this.memoryCoordinator.configure(params || {});
+
+      case 'get_local_memory_target':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return this.memoryCoordinator.getContract() || { configured: false };
+
+      case 'verify_local_memory_target':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return this.memoryCoordinator.verify(params || {});
+
+      case 'capture_memory':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return await this.memoryCoordinator.capture(params || {});
+
+      case 'invalidate_memory':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return await this.memoryCoordinator.invalidate(params || {});
+
+      case 'close_session':
+        if (!this.memoryCoordinator) throw new Error('Local memory coordinator is not configured');
+        return await this.memoryCoordinator.closeSession(params || {});
       
       default:
         throw new Error(`Unknown local tool: ${toolName}`);
@@ -87,6 +116,87 @@ export class LocalToolExecutor {
    */
   listTools() {
     return [
+      {
+        name: 'configure_local_memory_target',
+        description: 'Configure and verify the exact local directory used for governed JSON memory writes.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            adapter: { type: 'string', enum: ['solomap'] },
+            directory: { type: 'string' },
+            schema_version: { type: 'number', enum: [1] }
+          },
+          required: ['adapter', 'directory']
+        }
+      },
+      {
+        name: 'get_local_memory_target',
+        description: 'Read the active local memory target contract for this connector workspace.',
+        inputSchema: { type: 'object', properties: {} }
+      },
+      {
+        name: 'verify_local_memory_target',
+        description: 'Verify the active local memory target contract and optionally one exact memory entry.',
+        inputSchema: {
+          type: 'object',
+          properties: { memory_id: { type: 'string' } }
+        }
+      },
+      {
+        name: 'capture_memory',
+        description: 'Validate one governed memory and commit the same canonical JSON entry to the configured local target and CloudMCP scope.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            memory_scope_id: { type: 'string' },
+            layer: { type: 'string', enum: ['stable', 'working', 'candidate'] },
+            kind: { type: 'string', enum: ['preference', 'rule', 'project_fact', 'decision', 'pattern', 'domain', 'handoff', 'observation'] },
+            title: { type: 'string' },
+            content: { type: 'string' },
+            tags: { type: 'array', items: { type: 'string' } },
+            evidence_refs: { type: 'array', items: { type: 'string' } },
+            verified_at: { type: 'string' },
+            valid_from: { type: 'string' },
+            valid_until: { type: 'string' },
+            supersedes: { type: 'array', items: { type: 'string' } },
+            memory_id: { type: 'string' },
+            transaction_id: { type: 'string' },
+            expected_revision: { type: 'number' }
+          },
+          required: ['content']
+        }
+      },
+      {
+        name: 'invalidate_memory',
+        description: 'Soft-invalidate one governed memory and verify the same canonical result in CloudMCP and the configured local target.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            memory_scope_id: { type: 'string' },
+            memory_id: { type: 'string' },
+            expected_revision: { type: 'number' },
+            reason: { type: 'string' },
+            evidence_refs: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['memory_id', 'expected_revision', 'reason', 'evidence_refs']
+        }
+      },
+      {
+        name: 'close_session',
+        description: 'Persist a working handoff through the same verified local-and-cloud memory transaction.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            memory_scope_id: { type: 'string' },
+            title: { type: 'string' },
+            summary: { type: 'string' },
+            next_steps: { type: 'array', items: { type: 'string' } },
+            tags: { type: 'array', items: { type: 'string' } },
+            transaction_id: { type: 'string' }
+          },
+          required: ['summary']
+        }
+      },
       {
         name: 'read_file',
         description: 'Read a file from local filesystem',

package/src/memory-schema.js

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+
+const MEMORY_LAYERS = new Set(['stable', 'working', 'candidate']);
+const MEMORY_KINDS = new Set([
+  'preference', 'rule', 'project_fact', 'decision', 'pattern', 'domain', 'handoff', 'observation'
+]);
+const MEMORY_IDENTIFIER_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const MEMORY_KIND_LAYERS = new Map([
+  ['preference', 'stable'], ['rule', 'stable'], ['project_fact', 'stable'],
+  ['decision', 'stable'], ['pattern', 'stable'], ['domain', 'stable'],
+  ['handoff', 'working'], ['observation', 'candidate']
+]);
+const SENSITIVE_MEMORY_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----/i,
+  /\bCLOUDMCP_APPROVAL_CODE\s*=/i,
+  /\b(?:api[_ -]?key|access[_ -]?token|client[_ -]?secret|private[_ -]?key)\s*[:=]\s*\S{12,}/i,
+  /\bmcp_[A-Za-z0-9]{16,}\b/
+];
+
+function normalizeString(value, fallback = null) {
+  const normalized = typeof value === 'string' ? value.trim() : '';
+  return normalized || fallback;
+}
+
+export function validateMemoryIdentifier(value, label = 'memory_id') {
+  const normalized = normalizeString(value);
+  if (!normalized || !MEMORY_IDENTIFIER_PATTERN.test(normalized)) {
+    throw new Error(`${label} must be a portable identifier of 1-128 letters, digits, dots, underscores, or hyphens`);
+  }
+  return normalized;
+}
+
+function normalizeStringArray(value, limit = 32) {
+  return Array.from(new Set(
+    (Array.isArray(value) ? value : [])
+      .map((item) => normalizeString(item))
+      .filter(Boolean)
+      .slice(0, limit)
+  ));
+}
+
+export function assertNoSensitiveMemory(input = {}) {
+  const text = [input.title, input.content, ...(input.evidenceRefs || input.evidence_refs || [])]
+    .filter(Boolean).join('\n');
+  if (SENSITIVE_MEMORY_PATTERNS.some((pattern) => pattern.test(text))) {
+    throw new Error('Memory content appears to contain a secret or approval credential');
+  }
+}
+
+function sortValue(value) {
+  if (Array.isArray(value)) return value.map(sortValue);
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sortValue(value[key])]));
+}
+
+export function canonicalMemoryJson(entry) {
+  const { canonicalHash: _canonicalHash, ...withoutHash } = entry || {};
+  return JSON.stringify(sortValue(withoutHash));
+}
+
+export function hashMemoryEntry(entry) {
+  return `sha256:${createHash('sha256').update(canonicalMemoryJson(entry)).digest('hex')}`;
+}
+
+function normalizeIsoDate(value) {
+  const normalized = normalizeString(value);
+  if (!normalized) return null;
+  const date = new Date(normalized);
+  if (!Number.isFinite(date.getTime())) throw new Error(`Invalid memory timestamp: ${normalized}`);
+  return date.toISOString();
+}
+
+export function validateMemoryCaptureInput(payload = {}) {
+  const title = normalizeString(payload.title);
+  const content = normalizeString(payload.content);
+  if (!content) throw new Error('Memory content is required');
+  if (content.length > 12000) throw new Error('Memory content exceeds 12000 characters');
+  if (title && title.length > 240) throw new Error('Memory title exceeds 240 characters');
+  const layer = normalizeString(payload.layer, 'candidate');
+  if (layer === 'stable' && !normalizeString(payload.kind)) throw new Error('Stable memory requires an explicit kind');
+  const kind = normalizeString(payload.kind, layer === 'working' ? 'handoff' : 'observation');
+  if (!MEMORY_LAYERS.has(layer)) throw new Error(`Unsupported memory layer: ${layer}`);
+  if (!MEMORY_KINDS.has(kind)) throw new Error(`Unsupported memory kind: ${kind}`);
+  const requiredLayer = MEMORY_KIND_LAYERS.get(kind);
+  if (requiredLayer !== layer) throw new Error(`Memory kind ${kind} must use the ${requiredLayer} layer`);
+  const evidenceRefs = normalizeStringArray(payload.evidence_refs || payload.evidenceRefs, 20);
+  const verifiedAt = normalizeIsoDate(payload.verified_at || payload.verifiedAt);
+  if (layer === 'stable' && evidenceRefs.length === 0) {
+    throw new Error('Stable memory requires at least one evidence_ref');
+  }
+  const normalized = {
+    title: title || 'Untitled memory',
+    content,
+    layer,
+    kind,
+    tags: normalizeStringArray(payload.tags, 24),
+    evidenceRefs,
+    verifiedAt,
+    validFrom: normalizeIsoDate(payload.valid_from || payload.validFrom),
+    validUntil: normalizeIsoDate(payload.valid_until || payload.validUntil),
+    supersedes: normalizeStringArray(payload.supersedes, 20)
+      .map((id) => validateMemoryIdentifier(id, 'supersedes entry id'))
+  };
+  assertNoSensitiveMemory(normalized);
+  return normalized;
+}
+
+export function assertMemoryEntryIntegrity(entry) {
+  if (!entry || entry.schemaVersion !== 1 || !entry.id || !entry.scopeId) {
+    throw new Error('CloudMCP returned an invalid memory entry');
+  }
+  validateMemoryIdentifier(entry.id, 'memory entry id');
+  const expectedHash = hashMemoryEntry(entry);
+  if (entry.canonicalHash !== expectedHash) {
+    throw new Error(`Memory canonical hash mismatch for ${entry.id}`);
+  }
+  return entry;
+}

package/src/router.js

@@ -68,7 +68,13 @@ export class SmartRouter {
         'connector_sync_profile',
         'connector_report_status',
         'connector_discover_project_probe',
-        'connector_report_project_probe'
+        'connector_report_project_probe',
+        'configure_local_memory_target',
+        'get_local_memory_target',
+        'verify_local_memory_target',
+        'capture_memory',
+        'invalidate_memory',
+        'close_session'
       ],
       
       // 云端工具（需要网络或云端资源）
@@ -289,9 +295,15 @@ export class SmartRouter {
       throw new Error('CloudMCP returned no governed cloud tools');
     }
 
+    const cloudNames = new Set(cloudTools.map((tool) => tool.name));
+    const governedLocalMemoryTools = new Set(['capture_memory', 'invalidate_memory', 'close_session']);
+    const eligibleLocalTools = localTools.filter((tool) => (
+      !governedLocalMemoryTools.has(tool.name) || cloudNames.has(tool.name)
+    ));
+    const localNames = new Set(eligibleLocalTools.map((tool) => tool.name));
     return [
-      ...cloudTools.map(t => ({ ...t, source: 'cloud' })),
-      ...localTools.map(t => ({ ...t, source: 'local' }))
+      ...cloudTools.filter((tool) => !localNames.has(tool.name)).map((tool) => ({ ...tool, source: 'cloud' })),
+      ...eligibleLocalTools.map((tool) => ({ ...tool, source: 'local' }))
     ];
   }