feat: Upgrade to version 6.2.0 with major enhancements

- Updated COMMAND_SPEC.md to reflect new version and features including native CodexLens and CLI refactor. - Revised GETTING_STARTED.md and GETTING_STARTED_CN.md for improved onboarding experience with new features. - Enhanced INSTALL_CN.md to highlight the new CodexLens and Dashboard capabilities. - Updated README.md and README_CN.md to showcase version 6.2.0 features and breaking changes. - Introduced memory embedder scripts with comprehensive documentation and quick reference. - Added test suite for memory embedder functionality to ensure reliability and correctness. - Implemented TypeScript integration examples for memory embedder usage.
2026-02-10 02:24:35 +08:00 · 2025-12-20 13:16:09 +08:00
parent 6b62b5b5a9
commit 4458af83d8
16 changed files with 1245 additions and 33 deletions
--- a/ccw/scripts/memory-embedder-example.ts
+++ b/ccw/scripts/memory-embedder-example.ts
@@ -0,0 +1,184 @@
+/**
+ * Example: Using Memory Embedder from TypeScript
+ *
+ * This shows how to integrate the Python memory embedder script
+ * into CCW's TypeScript codebase.
+ */
+
+import { execSync } from 'child_process';
+import { join } from 'path';
+
+interface EmbedResult {
+  success: boolean;
+  chunks_processed: number;
+  chunks_failed: number;
+  elapsed_time: number;
+}
+
+interface SearchMatch {
+  source_id: string;
+  source_type: 'core_memory' | 'workflow' | 'cli_history';
+  chunk_index: number;
+  content: string;
+  score: number;
+  restore_command: string;
+}
+
+interface SearchResult {
+  success: boolean;
+  matches: SearchMatch[];
+  error?: string;
+}
+
+interface StatusResult {
+  total_chunks: number;
+  embedded_chunks: number;
+  pending_chunks: number;
+  by_type: Record<string, { total: number; embedded: number; pending: number }>;
+}
+
+/**
+ * Get path to memory embedder script
+ */
+function getEmbedderScript(): string {
+  return join(__dirname, 'memory_embedder.py');
+}
+
+/**
+ * Execute memory embedder command
+ */
+function execEmbedder(args: string[]): string {
+  const script = getEmbedderScript();
+  const command = `python "${script}" ${args.join(' ')}`;
+
+  try {
+    return execSync(command, {
+      encoding: 'utf-8',
+      maxBuffer: 10 * 1024 * 1024 // 10MB buffer
+    });
+  } catch (error: any) {
+    // Try to parse error output as JSON
+    if (error.stdout) {
+      return error.stdout;
+    }
+    throw new Error(`Embedder failed: ${error.message}`);
+  }
+}
+
+/**
+ * Generate embeddings for memory chunks
+ */
+export function embedChunks(
+  dbPath: string,
+  options: {
+    sourceId?: string;
+    batchSize?: number;
+    force?: boolean;
+  } = {}
+): EmbedResult {
+  const args = ['embed', `"${dbPath}"`];
+
+  if (options.sourceId) {
+    args.push('--source-id', options.sourceId);
+  }
+  if (options.batchSize) {
+    args.push('--batch-size', String(options.batchSize));
+  }
+  if (options.force) {
+    args.push('--force');
+  }
+
+  const output = execEmbedder(args);
+  return JSON.parse(output);
+}
+
+/**
+ * Search memory chunks semantically
+ */
+export function searchMemory(
+  dbPath: string,
+  query: string,
+  options: {
+    topK?: number;
+    minScore?: number;
+    sourceType?: 'core_memory' | 'workflow' | 'cli_history';
+  } = {}
+): SearchResult {
+  const args = ['search', `"${dbPath}"`, `"${query}"`];
+
+  if (options.topK) {
+    args.push('--top-k', String(options.topK));
+  }
+  if (options.minScore !== undefined) {
+    args.push('--min-score', String(options.minScore));
+  }
+  if (options.sourceType) {
+    args.push('--type', options.sourceType);
+  }
+
+  const output = execEmbedder(args);
+  return JSON.parse(output);
+}
+
+/**
+ * Get embedding status
+ */
+export function getEmbeddingStatus(dbPath: string): StatusResult {
+  const args = ['status', `"${dbPath}"`];
+  const output = execEmbedder(args);
+  return JSON.parse(output);
+}
+
+// ============================================================================
+// Example Usage
+// ============================================================================
+
+async function exampleUsage() {
+  const dbPath = join(process.env.HOME || '', '.ccw/projects/myproject/core-memory/core_memory.db');
+
+  // 1. Check status
+  console.log('Checking embedding status...');
+  const status = getEmbeddingStatus(dbPath);
+  console.log(`Total chunks: ${status.total_chunks}`);
+  console.log(`Embedded: ${status.embedded_chunks}`);
+  console.log(`Pending: ${status.pending_chunks}`);
+
+  // 2. Generate embeddings if needed
+  if (status.pending_chunks > 0) {
+    console.log('\nGenerating embeddings...');
+    const embedResult = embedChunks(dbPath, { batchSize: 16 });
+    console.log(`Processed: ${embedResult.chunks_processed}`);
+    console.log(`Time: ${embedResult.elapsed_time}s`);
+  }
+
+  // 3. Search for relevant memories
+  console.log('\nSearching for authentication-related memories...');
+  const searchResult = searchMemory(dbPath, 'authentication flow', {
+    topK: 5,
+    minScore: 0.5
+  });
+
+  if (searchResult.success) {
+    console.log(`Found ${searchResult.matches.length} matches:`);
+    for (const match of searchResult.matches) {
+      console.log(`\n- ${match.source_id} (score: ${match.score})`);
+      console.log(`  Type: ${match.source_type}`);
+      console.log(`  Restore: ${match.restore_command}`);
+      console.log(`  Content: ${match.content.substring(0, 100)}...`);
+    }
+  }
+
+  // 4. Search specific source type
+  console.log('\nSearching workflows only...');
+  const workflowSearch = searchMemory(dbPath, 'API implementation', {
+    sourceType: 'workflow',
+    topK: 3
+  });
+
+  console.log(`Found ${workflowSearch.matches.length} workflow matches`);
+}
+
+// Run example if executed directly
+if (require.main === module) {
+  exampleUsage().catch(console.error);
+}