claude-code-workflow 6.3.26 → 6.3.28

package/ccw/scripts/README-memory-embedder.md

@@ -0,0 +1,157 @@
+# Memory Embedder
+
+Bridge CCW to CodexLens semantic search by generating and searching embeddings for memory chunks.
+
+## Features
+
+- **Generate embeddings** for memory chunks using CodexLens's jina-embeddings-v2-base-code (768 dim)
+- **Semantic search** across all memory types (core_memory, workflow, cli_history)
+- **Status tracking** to monitor embedding progress
+- **Batch processing** for efficient embedding generation
+- **Restore commands** included in search results
+
+## Requirements
+
+```bash
+pip install numpy codexlens[semantic]
+```
+
+## Usage
+
+### 1. Check Status
+
+```bash
+python scripts/memory_embedder.py status <db_path>
+```
+
+Example output:
+```json
+{
+  "total_chunks": 150,
+  "embedded_chunks": 100,
+  "pending_chunks": 50,
+  "by_type": {
+    "core_memory": {"total": 80, "embedded": 60, "pending": 20},
+    "workflow": {"total": 50, "embedded": 30, "pending": 20},
+    "cli_history": {"total": 20, "embedded": 10, "pending": 10}
+  }
+}
+```
+
+### 2. Generate Embeddings
+
+Embed all unembedded chunks:
+```bash
+python scripts/memory_embedder.py embed <db_path>
+```
+
+Embed specific source:
+```bash
+python scripts/memory_embedder.py embed <db_path> --source-id CMEM-20250101-120000
+```
+
+Re-embed all chunks (force):
+```bash
+python scripts/memory_embedder.py embed <db_path> --force
+```
+
+Adjust batch size (default 8):
+```bash
+python scripts/memory_embedder.py embed <db_path> --batch-size 16
+```
+
+Example output:
+```json
+{
+  "success": true,
+  "chunks_processed": 50,
+  "chunks_failed": 0,
+  "elapsed_time": 12.34
+}
+```
+
+### 3. Semantic Search
+
+Basic search:
+```bash
+python scripts/memory_embedder.py search <db_path> "authentication flow"
+```
+
+Advanced search:
+```bash
+python scripts/memory_embedder.py search <db_path> "rate limiting" \
+  --top-k 5 \
+  --min-score 0.5 \
+  --type workflow
+```
+
+Example output:
+```json
+{
+  "success": true,
+  "matches": [
+    {
+      "source_id": "WFS-20250101-auth",
+      "source_type": "workflow",
+      "chunk_index": 2,
+      "content": "Implemented JWT-based authentication...",
+      "score": 0.8542,
+      "restore_command": "ccw session resume WFS-20250101-auth"
+    }
+  ]
+}
+```
+
+## Database Path
+
+The database is located in CCW's storage directory:
+
+- **Windows**: `%USERPROFILE%\.ccw\projects\<project-id>\core-memory\core_memory.db`
+- **Linux/Mac**: `~/.ccw/projects/<project-id>/core-memory/core_memory.db`
+
+Find your project's database:
+```bash
+ccw memory list  # Shows project path
+# Then look in: ~/.ccw/projects/<hashed-path>/core-memory/core_memory.db
+```
+
+## Integration with CCW
+
+This script is designed to be called from CCW's TypeScript code:
+
+```typescript
+import { execSync } from 'child_process';
+
+// Embed chunks
+const result = execSync(
+  `python scripts/memory_embedder.py embed ${dbPath}`,
+  { encoding: 'utf-8' }
+);
+const { success, chunks_processed } = JSON.parse(result);
+
+// Search
+const searchResult = execSync(
+  `python scripts/memory_embedder.py search ${dbPath} "${query}" --top-k 10`,
+  { encoding: 'utf-8' }
+);
+const { matches } = JSON.parse(searchResult);
+```
+
+## Performance
+
+- **Embedding speed**: ~8 chunks/second (batch size 8)
+- **Search speed**: ~0.1-0.5 seconds for 1000 chunks
+- **Model loading**: ~0.8 seconds (cached after first use)
+
+## Source Types
+
+- `core_memory`: Strategic architectural context
+- `workflow`: Session-based development history
+- `cli_history`: Command execution logs
+
+## Restore Commands
+
+Search results include restore commands:
+
+- **core_memory/cli_history**: `ccw memory export <source_id>`
+- **workflow**: `ccw session resume <source_id>`

package/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);
+}