Claude-Mem企业级上下文记忆系统架构深度解析：生产环境高可用部署实战指南-CSDN博客

Claude-Mem企业级上下文记忆系统架构深度解析：生产环境高可用部署实战指南

【免费下载链接】claude-mem Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More 项目地址: https://gitcode.com/GitHub_Trending/cl/claude-mem

Claude-Mem是一款专为AI辅助编程设计的跨会话持久化上下文记忆系统，通过智能捕获、压缩和注入技术实现开发者在不同会话间的知识连续性。该系统采用模块化架构设计，结合SQLite数据库、FTS5全文搜索和实时SSE通信，为Claude Code、OpenClaw、Codex等AI开发工具提供企业级记忆管理解决方案。

系统架构核心组件与技术栈

Claude-Mem采用分层架构设计，各组件职责分明，确保系统的可扩展性和稳定性。以下是系统的核心架构组成：

插件钩子系统架构

插件系统作为Claude-Mem的入口点，通过生命周期钩子机制与各类AI开发工具深度集成。系统定义了六个关键生命周期事件，每个事件对应特定的处理逻辑：

// 钩子事件分发机制示例
const hookHandlers = {
  'SessionStart': 'context',
  'UserPromptSubmit': 'session-init', 
  'PreToolUse': 'file-context',
  'PostToolUse': 'observation',
  'Stop': 'summarize'
};

// 钩子执行流程
export async function executeHook(event: HookEvent) {
  const handler = hookHandlers[event.type];
  await workerService.dispatchHook(handler, event.data);
}

钩子系统通过bun-runner.js启动工作进程，确保钩子逻辑与主进程隔离，避免超时问题。Setup阶段的version-check.js执行速度控制在100毫秒以内，仅检查版本标记而不执行安装操作，保证了启动性能。

工作进程服务架构

工作进程服务采用Express.js构建，提供完整的HTTP API接口集。进程管理由ProcessManager类负责，实现自动化的生命周期管理：

// 进程管理器核心逻辑
class ProcessManager {
  private pidFile = '~/.claude-mem/worker.pid';
  
  async startWorker(): Promise<void> {
    const bunPath = await this.resolveBunRuntime();
    const workerProcess = Bun.spawn([bunPath, 'worker-service.cjs']);
    await this.writePidFile(workerProcess.pid);
    await this.healthCheckWithRetry();
  }
  
  async healthCheck(): Promise<boolean> {
    const response = await fetch(`http://127.0.0.1:${this.port}/health`);
    return response.status === 200;
  }
}

端口分配采用用户ID哈希算法：37700 + (uid % 100)，确保同一机器上不同用户的实例不会冲突。可通过CLAUDE_MEM_WORKER_PORT环境变量覆盖默认端口配置。

数据库层架构设计

SQLite 3数据库作为核心存储引擎，结合FTS5全文搜索功能，提供高效的数据检索能力。数据库架构采用多表关联设计：

-- 核心表结构设计
CREATE TABLE sdk_sessions (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  sdk_session_id TEXT UNIQUE NOT NULL,
  project TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'active',
  created_at_epoch INTEGER NOT NULL,
  completed_at_epoch INTEGER
);

CREATE TABLE observations (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  session_id TEXT NOT NULL,
  tool_name TEXT NOT NULL,
  title TEXT,
  narrative TEXT,
  type TEXT CHECK(type IN ('decision', 'bugfix', 'feature', 'refactor', 'discovery', 'change')),
  created_at_epoch INTEGER NOT NULL,
  FOREIGN KEY (session_id) REFERENCES sdk_sessions(sdk_session_id)
);

-- FTS5虚拟表实现全文搜索
CREATE VIRTUAL TABLE observations_fts USING fts5(
  title, subtitle, narrative, text, facts, concepts,
  content='observations',
  content_rowid='id'
);

数据库采用WAL（Write-Ahead Logging）模式支持并发读写，通过触发器机制自动同步FTS5索引，确保搜索性能与数据一致性。

实时数据流架构

系统采用Server-Sent Events（SSE）实现实时数据推送，支持观察者模式的数据更新通知：

// SSE流实现
app.get('/stream', (req, res) => {
  res.writeHead(200, {
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-cache',
    'Connection': 'keep-alive'
  });
  
  const clientId = generateClientId();
  sseClients.set(clientId, res);
  
  // 发送初始数据
  res.write(`data: ${JSON.stringify(initialData)}\n\n`);
  
  req.on('close', () => {
    sseClients.delete(clientId);
  });
});

// 事件广播机制
function broadcastEvent(eventType: string, data: any) {
  const message = `event: ${eventType}\ndata: ${JSON.stringify(data)}\n\n`;
  sseClients.forEach(client => {
    client.write(message);
  });
}

数据持久化与检索优化策略

分层存储架构

Claude-Mem采用三级存储架构，平衡性能与数据完整性：

mermaid

全文搜索优化策略

FTS5虚拟表提供高性能全文搜索能力，支持复杂的查询语法：

-- 复合查询示例
SELECT * FROM observations_fts 
WHERE observations_fts MATCH 'title:"authentication" AND (bug OR fix) NOT feature'
ORDER BY rank
LIMIT 20;

-- 分面搜索实现
SELECT type, COUNT(*) as count 
FROM observations 
WHERE created_at_epoch > :start_time
GROUP BY type
ORDER BY count DESC;

搜索API支持多种查询模式：

简单关键词搜索："error handling"
布尔逻辑搜索："bug" AND "fix" OR "issue"
字段限定搜索：title:"authentication" narrative:"security"
时间范围搜索：结合时间戳过滤

数据一致性保障机制

系统采用事务性写入和自动重试机制确保数据完整性：

// 事务性数据写入
async function saveObservationWithRetry(observation: ObservationData): Promise<void> {
  let attempts = 0;
  const maxAttempts = 3;
  
  while (attempts < maxAttempts) {
    try {
      await db.transaction(async (tx) => {
        await tx.insertInto('observations').values(observation).execute();
        await tx.insertInto('observations_fts').values({
          rowid: observation.id,
          title: observation.title,
          narrative: observation.narrative
        }).execute();
      });
      return; // 成功返回
    } catch (error) {
      attempts++;
      if (attempts === maxAttempts) {
        throw new Error(`Failed to save observation after ${maxAttempts} attempts`);
      }
      await delay(100 * Math.pow(2, attempts)); // 指数退避
    }
  }
}

高可用部署架构与故障恢复

进程健康监控体系

Claude-Mem实现多层次健康检查机制，确保服务持续可用：

// 健康检查实现
class HealthMonitor {
  private checks = [
    this.checkDatabaseConnection.bind(this),
    this.checkWorkerProcess.bind(this),
    this.checkDiskSpace.bind(this),
    this.checkMemoryUsage.bind(this)
  ];
  
  async performHealthCheck(): Promise<HealthStatus> {
    const results = await Promise.allSettled(
      this.checks.map(check => check())
    );
    
    const status: HealthStatus = {
      overall: 'healthy',
      components: {},
      timestamp: Date.now()
    };
    
    results.forEach((result, index) => {
      const component = this.checkNames[index];
      if (result.status === 'fulfilled') {
        status.components[component] = 'healthy';
      } else {
        status.components[component] = 'unhealthy';
        status.overall = 'degraded';
        status.errors = status.errors || [];
        status.errors.push(`${component}: ${result.reason}`);
      }
    });
    
    return status;
  }
}

自动故障恢复机制

系统实现智能故障检测与自动恢复策略：

# 故障检测脚本示例
#!/bin/bash
# check-worker-health.sh

MAX_RETRIES=3
RETRY_DELAY=5

check_worker() {
    curl -s -f http://localhost:${CLAUDE_MEM_WORKER_PORT}/health > /dev/null
    return $?
}

attempt_recovery() {
    echo "检测到工作进程异常，尝试恢复..."
    
    for i in $(seq 1 $MAX_RETRIES); do
        echo "恢复尝试 $i/$MAX_RETRIES"
        
        # 停止现有进程
        npm run worker:stop 2>/dev/null || true
        
        # 清理PID文件
        rm -f ~/.claude-mem/worker.pid
        
        # 启动新进程
        if npm run worker:start; then
            sleep 2
            if check_worker; then
                echo "恢复成功"
                return 0
            fi
        fi
        
        sleep $RETRY_DELAY
    done
    
    echo "恢复失败，请手动检查"
    return 1
}

# 主监控循环
while true; do
    if ! check_worker; then
        attempt_recovery
    fi
    sleep 30
done

数据库备份与恢复策略

生产环境部署需要完善的数据备份机制：

// 数据库备份服务
class DatabaseBackupService {
  private backupDir = '~/.claude-mem/backups';
  
  async createBackup(): Promise<string> {
    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
    const backupFile = `${this.backupDir}/claude-mem-${timestamp}.db`;
    
    // 创建备份目录
    await fs.mkdir(this.backupDir, { recursive: true });
    
    // 执行SQLite备份
    const db = new Database('~/.claude-mem/claude-mem.db');
    const backupDb = new Database(backupFile);
    
    db.backup(backupDb, {
      progress: (remaining, pageCount) => {
        const percent = ((pageCount - remaining) / pageCount * 100).toFixed(1);
        console.log(`备份进度: ${percent}%`);
      }
    });
    
    // 清理旧备份（保留最近7天）
    await this.cleanupOldBackups();
    
    return backupFile;
  }
  
  async restoreBackup(backupFile: string): Promise<void> {
    // 验证备份文件完整性
    await this.validateBackup(backupFile);
    
    // 停止工作进程
    await this.stopWorker();
    
    // 恢复数据库
    const backupDb = new Database(backupFile);
    const mainDb = new Database('~/.claude-mem/claude-mem.db');
    
    backupDb.backup(mainDb);
    
    // 重新启动工作进程
    await this.startWorker();
  }
}

性能优化与扩展性设计

内存管理优化

系统采用分层缓存策略优化内存使用：

// 多级缓存实现
class MemoryCacheManager {
  private l1Cache = new Map<string, CacheEntry>(); // 内存缓存
  private l2Cache = new SQLiteCache(); // SQLite缓存
  private maxMemoryItems = 1000;
  
  async get(key: string): Promise<any> {
    // L1缓存查找
    const l1Hit = this.l1Cache.get(key);
    if (l1Hit && !this.isExpired(l1Hit)) {
      return l1Hit.value;
    }
    
    // L2缓存查找
    const l2Hit = await this.l2Cache.get(key);
    if (l2Hit) {
      // 回填L1缓存
      this.l1Cache.set(key, {
        value: l2Hit,
        timestamp: Date.now(),
        ttl: 300000 // 5分钟
      });
      return l2Hit;
    }
    
    // 缓存未命中
    return null;
  }
  
  private cleanupL1Cache() {
    if (this.l1Cache.size > this.maxMemoryItems) {
      // LRU淘汰策略
      const entries = Array.from(this.l1Cache.entries());
      entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
      
      const toRemove = entries.slice(0, Math.floor(this.maxMemoryItems * 0.2));
      toRemove.forEach(([key]) => this.l1Cache.delete(key));
    }
  }
}

并发处理优化

针对高并发场景，系统实现请求队列和批处理机制：

// 批处理队列实现
class BatchProcessingQueue {
  private queue: Array<{data: any, resolve: Function, reject: Function}> = [];
  private batchSize = 50;
  private processing = false;
  private flushTimer: Timer | null = null;
  
  async enqueue(item: any): Promise<any> {
    return new Promise((resolve, reject) => {
      this.queue.push({ data: item, resolve, reject });
      
      // 触发批量处理
      if (this.queue.length >= this.batchSize) {
        this.flush();
      } else if (!this.flushTimer) {
        this.flushTimer = setTimeout(() => this.flush(), 100); // 100ms延迟
      }
    });
  }
  
  private async flush() {
    if (this.processing || this.queue.length === 0) return;
    
    this.processing = true;
    if (this.flushTimer) {
      clearTimeout(this.flushTimer);
      this.flushTimer = null;
    }
    
    const batch = this.queue.splice(0, this.batchSize);
    
    try {
      const results = await this.processBatch(batch.map(b => b.data));
      
      // 分发结果
      batch.forEach((item, index) => {
        item.resolve(results[index]);
      });
    } catch (error) {
      // 批量失败，回退到单条处理
      for (const item of batch) {
        try {
          const result = await this.processSingle(item.data);
          item.resolve(result);
        } catch (singleError) {
          item.reject(singleError);
        }
      }
    } finally {
      this.processing = false;
      
      // 如果队列中还有数据，继续处理
      if (this.queue.length > 0) {
        setTimeout(() => this.flush(), 0);
      }
    }
  }
}

安全架构与数据保护

输入验证与消毒

所有API端点实现严格输入验证：

// 输入验证中间件
const validationMiddleware = {
  observationInput: (req, res, next) => {
    const { tool_name, tool_input, correlation_id } = req.body;
    
    // 工具名称验证
    const validTools = ['Read', 'Write', 'Execute', 'Search'];
    if (!validTools.includes(tool_name)) {
      return res.status(400).json({ 
        error: `无效的工具名称: ${tool_name}` 
      });
    }
    
    // 输入数据消毒
    if (tool_input) {
      req.body.tool_input = sanitizeInput(tool_input);
    }
    
    // 关联ID格式验证
    if (correlation_id && !isValidUUID(correlation_id)) {
      return res.status(400).json({ 
        error: '无效的关联ID格式' 
      });
    }
    
    next();
  },
  
  searchQuery: (req, res, next) => {
    const { query, limit = 20, offset = 0 } = req.query;
    
    // 查询参数消毒
    if (query) {
      req.query.query = escapeFTS5Query(query);
    }
    
    // 分页参数验证
    const parsedLimit = parseInt(limit);
    const parsedOffset = parseInt(offset);
    
    if (isNaN(parsedLimit) || parsedLimit < 1 || parsedLimit > 100) {
      return res.status(400).json({ 
        error: 'limit参数必须在1-100之间' 
      });
    }
    
    if (isNaN(parsedOffset) || parsedOffset < 0) {
      return res.status(400).json({ 
        error: 'offset参数必须是非负整数' 
      });
    }
    
    next();
  }
};

// FTS5查询转义
function escapeFTS5Query(query: string): string {
  // 转义特殊字符
  return query
    .replace(/"/g, '""')  // 转义双引号
    .replace(/\[/g, '\\[') // 转义方括号
    .replace(/\]/g, '\\]')
    .replace(/\*/g, '\\*') // 转义通配符
    .replace(/\?/g, '\\?');
}

数据加密与访问控制

敏感数据采用加密存储，实现基于角色的访问控制：

// 数据加密服务
class DataEncryptionService {
  private algorithm = 'aes-256-gcm';
  private key: Buffer;
  
  constructor() {
    // 从安全存储加载密钥
    this.key = this.loadEncryptionKey();
  }
  
  async encrypt(data: string): Promise<EncryptedData> {
    const iv = crypto.randomBytes(12);
    const cipher = crypto.createCipheriv(this.algorithm, this.key, iv);
    
    let encrypted = cipher.update(data, 'utf8', 'hex');
    encrypted += cipher.final('hex');
    
    const authTag = cipher.getAuthTag();
    
    return {
      encrypted,
      iv: iv.toString('hex'),
      authTag: authTag.toString('hex'),
      algorithm: this.algorithm
    };
  }
  
  async storeSensitiveObservation(observation: ObservationData): Promise<void> {
    // 加密敏感字段
    const encryptedNarrative = await this.encrypt(observation.narrative);
    const encryptedFacts = await this.encrypt(JSON.stringify(observation.facts));
    
    // 存储加密数据
    await db.insertInto('encrypted_observations').values({
      observation_id: observation.id,
      narrative_encrypted: encryptedNarrative.encrypted,
      narrative_iv: encryptedNarrative.iv,
      narrative_auth_tag: encryptedNarrative.authTag,
      facts_encrypted: encryptedFacts.encrypted,
      facts_iv: encryptedFacts.iv,
      facts_auth_tag: encryptedFacts.authTag
    }).execute();
    
    // 存储明文索引（不含敏感信息）
    await db.insertInto('observations').values({
      id: observation.id,
      title: observation.title,
      type: observation.type,
      created_at_epoch: observation.created_at_epoch
    }).execute();
  }
}

监控与日志系统

结构化日志记录

系统实现分级的结构化日志记录：

// 结构化日志记录器
class StructuredLogger {
  private levels = ['error', 'warn', 'info', 'debug', 'trace'];
  private currentLevel = process.env.LOG_LEVEL || 'info';
  
  log(level: string, message: string, meta: any = {}) {
    if (this.levels.indexOf(level) > this.levels.indexOf(this.currentLevel)) {
      return;
    }
    
    const logEntry = {
      timestamp: new Date().toISOString(),
      level,
      message,
      pid: process.pid,
      ...meta,
      // 添加上下文信息
      session_id: meta.session_id || 'global',
      correlation_id: meta.correlation_id,
      duration_ms: meta.duration_ms
    };
    
    // 输出到控制台（开发环境）
    if (process.env.NODE_ENV === 'development') {
      console.log(JSON.stringify(logEntry));
    }
    
    // 写入文件（生产环境）
    if (process.env.NODE_ENV === 'production') {
      this.writeToFile(logEntry);
    }
    
    // 发送到监控系统
    if (this.monitoringEnabled) {
      this.sendToMonitoring(logEntry);
    }
  }
  
  // 性能监控装饰器
  measure<T>(name: string, fn: () => Promise<T>): Promise<T> {
    const startTime = performance.now();
    
    return fn().then(result => {
      const duration = performance.now() - startTime;
      this.log('debug', `操作 ${name} 完成`, {
        operation: name,
        duration_ms: Math.round(duration)
      });
      
      // 慢操作告警
      if (duration > 1000) {
        this.log('warn', `慢操作检测: ${name}`, {
          operation: name,
          duration_ms: Math.round(duration),
          threshold_ms: 1000
        });
      }
      
      return result;
    }).catch(error => {
      const duration = performance.now() - startTime;
      this.log('error', `操作 ${name} 失败`, {
        operation: name,
        duration_ms: Math.round(duration),
        error: error.message,
        stack: error.stack
      });
      throw error;
    });
  }
}

性能指标收集

系统收集关键性能指标用于容量规划和故障预测：

// 性能指标收集器
class PerformanceMetricsCollector {
  private metrics = new Map<string, MetricSeries>();
  
  recordMetric(name: string, value: number, tags: Record<string, string> = {}) {
    const key = this.getMetricKey(name, tags);
    const series = this.metrics.get(key) || {
      name,
      tags,
      values: [],
      timestamps: []
    };
    
    series.values.push(value);
    series.timestamps.push(Date.now());
    
    // 保留最近1000个数据点
    if (series.values.length > 1000) {
      series.values.shift();
      series.timestamps.shift();
    }
    
    this.metrics.set(key, series);
  }
  
  getMetricsSummary(): MetricsSummary {
    const summary: MetricsSummary = {
      timestamp: Date.now(),
      metrics: {}
    };
    
    for (const [key, series] of this.metrics) {
      if (series.values.length === 0) continue;
      
      const values = series.values;
      summary.metrics[key] = {
        count: values.length,
        min: Math.min(...values),
        max: Math.max(...values),
        avg: values.reduce((a, b) => a + b, 0) / values.length,
        p95: this.calculatePercentile(values, 95),
        p99: this.calculatePercentile(values, 99),
        last: values[values.length - 1]
      };
    }
    
    return summary;
  }
  
  // API端点暴露指标
  setupMetricsEndpoint(app: Express) {
    app.get('/metrics', (req, res) => {
      const summary = this.getMetricsSummary();
      res.json(summary);
    });
    
    // Prometheus格式指标
    app.get('/metrics/prometheus', (req, res) => {
      const prometheusLines: string[] = [];
      
      for (const [key, series] of this.metrics) {
        const metricName = series.name.replace(/[^a-zA-Z0-9_]/g, '_');
        const tags = Object.entries(series.tags)
          .map(([k, v]) => `${k}="${v}"`)
          .join(',');
        
        const labelStr = tags ? `{${tags}}` : '';
        
        // 当前值
        if (series.values.length > 0) {
          const lastValue = series.values[series.values.length - 1];
          prometheusLines.push(`${metricName}_last${labelStr} ${lastValue}`);
        }
        
        // 统计信息
        if (series.values.length >= 10) {
          const avg = series.values.reduce((a, b) => a + b, 0) / series.values.length;
          prometheusLines.push(`${metricName}_avg${labelStr} ${avg}`);
        }
      }
      
      res.set('Content-Type', 'text/plain');
      res.send(prometheusLines.join('\n') + '\n');
    });
  }
}

部署与运维最佳实践

容器化部署配置

提供Docker容器化部署方案，支持Kubernetes编排：

# Dockerfile
FROM oven/bun:1.0-alpine AS builder

WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile --production

COPY . .
RUN bun run build

FROM oven/bun:1.0-alpine

WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./
COPY --from=builder /app/node_modules ./node_modules

# 创建非root用户
RUN addgroup -g 1001 -S claudemem && \
    adduser -u 1001 -S claudemem -G claudemem

# 设置数据目录权限
RUN mkdir -p /data && chown -R claudemem:claudemem /data

USER claudemem

# 环境变量配置
ENV NODE_ENV=production \
    CLAUDE_MEM_DATA_DIR=/data \
    CLAUDE_MEM_WORKER_PORT=37777 \
    CLAUDE_MEM_MODEL=claude-haiku-4-5-20251001

# 健康检查
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD curl -f http://localhost:37777/health || exit 1

EXPOSE 37777
CMD ["bun", "dist/worker-service.cjs"]

# kubernetes-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-mem-worker
spec:
  replicas: 2
  selector:
    matchLabels:
      app: claude-mem-worker
  template:
    metadata:
      labels:
        app: claude-mem-worker
    spec:
      containers:
      - name: worker
        image: claude-mem/worker:latest
        ports:
        - containerPort: 37777
        env:
        - name: CLAUDE_MEM_DATA_DIR
          value: /data
        - name: CLAUDE_MEM_WORKER_PORT
          value: "37777"
        - name: CLAUDE_MEM_MODEL
          value: "claude-haiku-4-5-20251001"
        volumeMounts:
        - name: data
          mountPath: /data
        resources:
          requests:
            memory: "256Mi"
            cpu: "100m"
          limits:
            memory: "512Mi"
            cpu: "500m"
        livenessProbe:
          httpGet:
            path: /health
            port: 37777
          initialDelaySeconds: 10
          periodSeconds: 30
        readinessProbe:
          httpGet:
            path: /health
            port: 37777
          initialDelaySeconds: 5
          periodSeconds: 10
      volumes:
      - name: data
        persistentVolumeClaim:
          claimName: claude-mem-data

自动化运维脚本

提供完整的运维脚本集合：

#!/bin/bash
# deploy-claude-mem.sh

set -e

# 配置参数
DEPLOY_ENV=${1:-"production"}
WORKER_COUNT=${2:-2}
DATA_VOLUME_SIZE=${3:-"10Gi"}

echo "开始部署Claude-Mem到 ${DEPLOY_ENV} 环境..."

# 检查依赖
check_dependencies() {
    local deps=("kubectl" "helm" "docker")
    for dep in "${deps[@]}"; do
        if ! command -v $dep &> /dev/null; then
            echo "错误: 缺少依赖 $dep"
            exit 1
        fi
    done
}

# 构建镜像
build_image() {
    echo "构建Docker镜像..."
    docker build -t claude-mem/worker:latest -f Dockerfile .
    
    if [ "$DEPLOY_ENV" = "production" ]; then
        docker tag claude-mem/worker:latest registry.example.com/claude-mem/worker:$(git rev-parse --short HEAD)
        docker push registry.example.com/claude-mem/worker:$(git rev-parse --short HEAD)
    fi
}

# 部署到Kubernetes
deploy_kubernetes() {
    echo "部署到Kubernetes..."
    
    # 创建命名空间
    kubectl create namespace claude-mem --dry-run=client -o yaml | kubectl apply -f -
    
    # 创建配置
    cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: ConfigMap
metadata:
  name: claude-mem-config
  namespace: claude-mem
data:
  worker-port: "37777"
  model: "claude-haiku-4-5-20251001"
  log-level: "info"
EOF

    # 创建持久化存储
    cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: claude-mem-data
  namespace: claude-mem
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: ${DATA_VOLUME_SIZE}
EOF

    # 部署工作负载
    kubectl apply -f kubernetes-deployment.yaml -n claude-mem
    
    # 创建服务
    cat <<EOF | kubectl apply -f -
apiVersion: v1
kind: Service
metadata:
  name: claude-mem-service
  namespace: claude-mem
spec:
  selector:
    app: claude-mem-worker
  ports:
    - protocol: TCP
      port: 37777
      targetPort: 37777
  type: ClusterIP
EOF

    echo "部署完成!"
    echo "服务端点: claude-mem-service.claude-mem.svc.cluster.local:37777"
}

# 执行部署
main() {
    check_dependencies
    build_image
    deploy_kubernetes
    
    # 等待部署完成
    echo "等待Pod就绪..."
    kubectl wait --for=condition=ready pod -l app=claude-mem-worker -n claude-mem --timeout=300s
    
    # 验证部署
    echo "验证部署..."
    kubectl get pods -n claude-mem
    kubectl get svc -n claude-mem
}

main "$@"

故障排查与性能调优

系统诊断工具集

提供完整的诊断工具链：

// 系统诊断工具
class SystemDiagnostics {
  async runComprehensiveCheck(): Promise<DiagnosticReport> {
    const checks = [
      this.checkDatabaseHealth(),
      this.checkWorkerProcess(),
      this.checkDiskSpace(),
      this.checkMemoryUsage(),
      this.checkNetworkConnectivity(),
      this.checkAPIEndpoints(),
      this.checkSearchPerformance(),
      this.checkDataConsistency()
    ];
    
    const results = await Promise.allSettled(checks);
    
    const report: DiagnosticReport = {
      timestamp: new Date().toISOString(),
      overallStatus: 'healthy',
      components: {},
      recommendations: []
    };
    
    results.forEach((result, index) => {
      const checkName = this.checkNames[index];
      
      if (result.status === 'fulfilled') {
        report.components[checkName] = {
          status: 'healthy',
          details: result.value
        };
      } else {
        report.components[checkName] = {
          status: 'unhealthy',
          error: result.reason.message,
          details: result.reason.stack
        };
        report.overallStatus = 'degraded';
        
        // 添加修复建议
        const recommendation = this.generateRecommendation(checkName, result.reason);
        if (recommendation) {
          report.recommendations.push(recommendation);
        }
      }
    });
    
    return report;
  }
  
  async checkDatabaseHealth(): Promise<DatabaseHealth> {
    const db = new Database('~/.claude-mem/claude-mem.db');
    
    try {
      // 检查数据库完整性
      const integrityCheck = await db.prepare('PRAGMA integrity_check').get();
      
      // 检查表状态
      const tableStats = await db.prepare(`
        SELECT 
          name,
          (SELECT COUNT(*) FROM sqlite_master WHERE type='table') as table_count,
          (SELECT COUNT(*) FROM sqlite_master WHERE type='index') as index_count,
          (SELECT page_count * page_size FROM pragma_page_count, pragma_page_size) as db_size
      `).get();
      
      // 检查FTS5索引
      const fts5Status = await db.prepare(`
        SELECT 
          COUNT(*) as observation_count,
          COUNT(DISTINCT session_id) as session_count,
          MIN(created_at_epoch) as oldest_record,
          MAX(created_at_epoch) as newest_record
        FROM observations
      `).get();
      
      return {
        integrity: integrityCheck.status === 'ok',
        tableCount: tableStats.table_count,
        indexCount: tableStats.index_count,
        databaseSize: tableStats.db_size,
        ...fts5Status
      };
    } finally {
      db.close();
    }
  }
  
  async checkSearchPerformance(): Promise<SearchPerformance> {
    const testQueries = [
      'SELECT COUNT(*) FROM observations',
      'SELECT * FROM observations_fts WHERE observations_fts MATCH "bug" LIMIT 10',
      'SELECT type, COUNT(*) FROM observations GROUP BY type'
    ];
    
    const results: SearchPerformance = {
      queryTimes: {},
      averageResponseTime: 0,
      slowQueries: []
    };
    
    for (const query of testQueries) {
      const startTime = performance.now();
      await db.prepare(query).all();
      const duration = performance.now() - startTime;
      
      results.queryTimes[query] = duration;
      
      if (duration > 100) { // 超过100ms视为慢查询
        results.slowQueries.push({
          query,
          duration,
          suggestion: this.getQueryOptimizationSuggestion(query)
        });
      }
    }
    
    const times = Object.values(results.queryTimes);
    results.averageResponseTime = times.reduce((a, b) => a + b, 0) / times.length;
    
    return results;
  }
}

性能监控仪表板

提供实时性能监控界面：

// 性能监控仪表板
class PerformanceDashboard {
  private metrics: PerformanceMetrics = {
    requestsPerSecond: 0,
    averageResponseTime: 0,
    errorRate: 0,
    memoryUsage: 0,
    activeConnections: 0,
    queueLength: 0
  };
  
  updateDashboard() {
    // 更新实时指标
    setInterval(async () => {
      const health = await fetch('/api/health').then(r => r.json());
      const stats = await fetch('/api/stats').then(r => r.json());
      const queue = await fetch('/api/pending-queue').then(r => r.json());
      
      this.metrics = {
        requestsPerSecond: this.calculateRPS(),
        averageResponseTime: this.calculateAvgResponseTime(),
        errorRate: this.calculateErrorRate(),
        memoryUsage: process.memoryUsage().heapUsed / 1024 / 1024, // MB
        activeConnections: this.getActiveConnections(),
        queueLength: queue.queue?.totalPending || 0,
        databaseSize: stats.total?.observations || 0
      };
      
      this.renderDashboard();
    }, 5000); // 每5秒更新一次
  }
  
  renderDashboard() {
    console.clear();
    console.log(`
╔══════════════════════════════════════════════════════════════╗
║                    Claude-Mem 性能监控仪表板                   ║
╠══════════════════════════════════════════════════════════════╣
║ 请求速率: ${this.metrics.requestsPerSecond.toFixed(1)}/s        
║ 平均响应时间: ${this.metrics.averageResponseTime.toFixed(1)}ms  
║ 错误率: ${(this.metrics.errorRate * 100).toFixed(1)}%          
║ 内存使用: ${this.metrics.memoryUsage.toFixed(1)} MB           
║ 活动连接: ${this.metrics.activeConnections}                   
║ 待处理队列: ${this.metrics.queueLength}                        
║ 数据库记录: ${this.metrics.databaseSize}                      
╚══════════════════════════════════════════════════════════════╝
    `);
    
    // 显示性能建议
    this.displayRecommendations();
  }
  
  displayRecommendations() {
    const recommendations = [];
    
    if (this.metrics.memoryUsage > 500) {
      recommendations.push('⚠️  内存使用过高，考虑增加内存限制或优化缓存策略');
    }
    
    if (this.metrics.queueLength > 100) {
      recommendations.push('⚠️  处理队列过长，考虑增加工作进程或优化处理逻辑');
    }
    
    if (this.metrics.errorRate > 0.05) {
      recommendations.push('⚠️  错误率过高，检查日志以识别问题');
    }
    
    if (this.metrics.averageResponseTime > 1000) {
      recommendations.push('⚠️  响应时间过长，考虑数据库索引优化或查询优化');
    }
    
    if (recommendations.length > 0) {
      console.log('\n📋 性能建议:');
      recommendations.forEach(rec => console.log(`  • ${rec}`));
    }
  }
}

通过以上系统化的架构设计、性能优化策略和运维实践，Claude-Mem能够为企业级AI开发环境提供稳定、高效、可扩展的上下文记忆服务。系统采用模块化设计，支持灵活部署和扩展，同时提供完善的监控和故障恢复机制，确保生产环境的高可用性。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考