🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
Checkpoint: File edits
rUv569fb4792e4d
diff --git a/agents/architect.yaml b/agents/architect.yamlindex 057ae5debe..8015208de0 100644--- a/agents/architect.yaml+++ b/agents/architect.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- context-caching- memory-persistence-createdAt: "2026-01-07T03:55:13.825Z"+createdAt: "2026-01-07T04:31:43.920Z"diff --git a/agents/coder.yaml b/agents/coder.yamlindex 2f40eca45b..92b0840c83 100644--- a/agents/coder.yaml+++ b/agents/coder.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- flash-attention- token-reduction-createdAt: "2026-01-07T03:55:13.825Z"+createdAt: "2026-01-07T04:31:43.920Z"diff --git a/agents/reviewer.yaml b/agents/reviewer.yamlindex bf6e71c786..f83bf424f9 100644--- a/agents/reviewer.yaml+++ b/agents/reviewer.yaml@@ -7,4 +7,4 @@ capabilities:- best-practicesoptimizations:- incremental-analysis-createdAt: "2026-01-07T03:55:13.825Z"+createdAt: "2026-01-07T04:31:43.921Z"diff --git a/agents/security-architect.yaml b/agents/security-architect.yamlindex ad23593606..6e26b26428 100644--- a/agents/security-architect.yaml+++ b/agents/security-architect.yaml@@ -7,4 +7,4 @@ capabilities:- security-reviewoptimizations:- pattern-matching-createdAt: "2026-01-07T03:55:13.825Z"+createdAt: "2026-01-07T04:31:43.921Z"diff --git a/agents/tester.yaml b/agents/tester.yamlindex 49ce839c0b..f82884eec4 100644--- a/agents/tester.yaml+++ b/agents/tester.yaml@@ -7,4 +7,4 @@ capabilities:- coverageoptimizations:- parallel-execution-createdAt: "2026-01-07T03:55:13.825Z"+createdAt: "2026-01-07T04:31:43.920Z"diff --git a/v3/@claude-flow/cli/src/commands/completions.ts b/v3/@claude-flow/cli/src/commands/completions.tsnew file mode 100644index 0000000000..470bf498f4--- /dev/null+++ b/v3/@claude-flow/cli/src/commands/completions.ts@@ -0,0 +1,558 @@+/**+ * V3 CLI Completions Command+ * Shell completions for bash, zsh, fish, powershell+ *+ * Created with ruv.io+ */++import type { Command, CommandContext, CommandResult } from '../types.js';+import { output } from '../output.js';++// Get all top-level commands for completions+const TOP_LEVEL_COMMANDS = [+ 'swarm', 'agent', 'task', 'session', 'config', 'memory', 'workflow',+ 'hive-mind', 'hooks', 'daemon', 'neural', 'security', 'performance',+ 'providers', 'plugins', 'deployment', 'claims', 'embeddings',+ 'doctor', 'completions', 'help', 'version'+];++// Swarm subcommands+const SWARM_SUBCOMMANDS = ['init', 'status', 'scale', 'destroy', 'monitor', 'optimize'];++// Agent subcommands+const AGENT_SUBCOMMANDS = ['spawn', 'terminate', 'status', 'list', 'pool', 'health', 'update'];++// Task subcommands+const TASK_SUBCOMMANDS = ['create', 'status', 'list', 'complete', 'cancel'];++// Memory subcommands+const MEMORY_SUBCOMMANDS = ['store', 'retrieve', 'search', 'list', 'delete', 'stats', 'configure', 'cleanup', 'compress', 'export', 'import'];++// Hive-mind subcommands+const HIVE_MIND_SUBCOMMANDS = ['init', 'spawn', 'status', 'task', 'join', 'leave', 'consensus', 'broadcast', 'memory', 'optimize-memory', 'shutdown'];++// Hooks subcommands+const HOOKS_SUBCOMMANDS = ['pre-edit', 'post-edit', 'pre-command', 'post-command', 'pre-task', 'post-task', 'route', 'explain', 'pretrain', 'build-agents', 'metrics', 'transfer', 'list', 'intelligence'];++// Generate bash completion script+function generateBashCompletion(): string {+ return `# claude-flow bash completion+# Generated by claude-flow completions bash+# Add this to ~/.bashrc or ~/.bash_completion++_claude_flow_completions() {+ local cur prev words cword+ _init_completion -n : || return++ local commands="${TOP_LEVEL_COMMANDS.join(' ')}"++ # Subcommand completions+ local swarm_commands="${SWARM_SUBCOMMANDS.join(' ')}"+ local agent_commands="${AGENT_SUBCOMMANDS.join(' ')}"+ local task_commands="${TASK_SUBCOMMANDS.join(' ')}"+ local memory_commands="${MEMORY_SUBCOMMANDS.join(' ')}"+ local hive_mind_commands="${HIVE_MIND_SUBCOMMANDS.join(' ')}"+ local hooks_commands="${HOOKS_SUBCOMMANDS.join(' ')}"++ case "\${words[1]}" in+ swarm)+ COMPREPLY=( $(compgen -W "\${swarm_commands}" -- "\${cur}") )+ return 0+ ;;+ agent)+ COMPREPLY=( $(compgen -W "\${agent_commands}" -- "\${cur}") )+ return 0+ ;;+ task)+ COMPREPLY=( $(compgen -W "\${task_commands}" -- "\${cur}") )+ return 0+ ;;+ memory)+ COMPREPLY=( $(compgen -W "\${memory_commands}" -- "\${cur}") )+ return 0+ ;;+ hive-mind|hive)+ COMPREPLY=( $(compgen -W "\${hive_mind_commands}" -- "\${cur}") )+ return 0+ ;;+ hooks)+ COMPREPLY=( $(compgen -W "\${hooks_commands}" -- "\${cur}") )+ return 0+ ;;+ neural)+ COMPREPLY=( $(compgen -W "train status patterns predict optimize" -- "\${cur}") )+ return 0+ ;;+ security)+ COMPREPLY=( $(compgen -W "scan cve threats audit secrets" -- "\${cur}") )+ return 0+ ;;+ performance)+ COMPREPLY=( $(compgen -W "benchmark profile metrics optimize bottleneck" -- "\${cur}") )+ return 0+ ;;+ plugins)+ COMPREPLY=( $(compgen -W "list install uninstall toggle info create" -- "\${cur}") )+ return 0+ ;;+ deployment|deploy)+ COMPREPLY=( $(compgen -W "deploy status rollback history environments logs" -- "\${cur}") )+ return 0+ ;;+ claims)+ COMPREPLY=( $(compgen -W "list check grant revoke roles policies" -- "\${cur}") )+ return 0+ ;;+ embeddings)+ COMPREPLY=( $(compgen -W "generate search compare collections index providers" -- "\${cur}") )+ return 0+ ;;+ daemon)+ COMPREPLY=( $(compgen -W "start stop status trigger enable" -- "\${cur}") )+ return 0+ ;;+ providers)+ COMPREPLY=( $(compgen -W "list configure test models usage" -- "\${cur}") )+ return 0+ ;;+ doctor)+ COMPREPLY=( $(compgen -W "--fix --component --verbose" -- "\${cur}") )+ return 0+ ;;+ esac++ if [[ \${cword} -eq 1 ]]; then+ COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )+ return 0+ fi+}++complete -F _claude_flow_completions claude-flow+complete -F _claude_flow_completions npx\\ @claude-flow/cli@v3alpha+`;+}++// Generate zsh completion script+function generateZshCompletion(): string {+ return `#compdef claude-flow+# claude-flow zsh completion+# Generated by claude-flow completions zsh+# Add to ~/.zfunc/_claude-flow or ~/.zsh/completions/_claude-flow++_claude_flow() {+ local -a commands+ local -a subcommands++ commands=(+ 'swarm:Multi-agent swarm orchestration'+ 'agent:Agent lifecycle management'+ 'task:Task creation and management'+ 'session:Session management'+ 'config:Configuration management'+ 'memory:Memory operations with AgentDB'+ 'workflow:Workflow automation'+ 'hive-mind:Queen-led consensus coordination'+ 'hooks:Self-learning automation hooks'+ 'daemon:Background service management'+ 'neural:Neural pattern training'+ 'security:Security scanning and CVE detection'+ 'performance:Performance profiling'+ 'providers:AI provider management'+ 'plugins:Plugin management'+ 'deployment:Deployment management'+ 'claims:Claims-based authorization'+ 'embeddings:Vector embeddings'+ 'doctor:System diagnostics'+ 'completions:Shell completion scripts'+ 'help:Show help'+ 'version:Show version'+ )++ _arguments -C \\+ '1: :->command' \\+ '2: :->subcommand' \\+ '*:: :->args' && return++ case $state in+ command)+ _describe -t commands 'claude-flow commands' commands+ ;;+ subcommand)+ case $words[2] in+ swarm)+ subcommands=(+ 'init:Initialize swarm'+ 'status:Show swarm status'+ 'scale:Scale agent count'+ 'destroy:Shutdown swarm'+ 'monitor:Real-time monitoring'+ 'optimize:Optimize topology'+ )+ ;;+ agent)+ subcommands=(+ 'spawn:Create new agent'+ 'terminate:Stop agent'+ 'status:Check agent status'+ 'list:List all agents'+ 'pool:Manage agent pool'+ 'health:Health check'+ 'update:Update agent config'+ )+ ;;+ task)+ subcommands=(+ 'create:Create new task'+ 'status:Check task status'+ 'list:List all tasks'+ 'complete:Mark task complete'+ 'cancel:Cancel task'+ )+ ;;+ memory)+ subcommands=(+ 'store:Store data'+ 'retrieve:Retrieve data'+ 'search:Semantic search'+ 'list:List entries'+ 'delete:Delete entry'+ 'stats:Show statistics'+ 'configure:Configure backend'+ 'cleanup:Clean stale data'+ 'compress:Compress storage'+ 'export:Export to file'+ 'import:Import from file'+ )+ ;;+ hive-mind|hive)+ subcommands=(+ 'init:Initialize hive mind'+ 'spawn:Spawn worker agents'+ 'status:Show hive status'+ 'task:Submit task'+ 'join:Join agent to hive'+ 'leave:Remove agent'+ 'consensus:Consensus management'+ 'broadcast:Broadcast message'+ 'memory:Shared memory'+ 'optimize-memory:Optimize patterns'+ 'shutdown:Shutdown hive'+ )+ ;;+ hooks)+ subcommands=(+ 'pre-edit:Before file editing'+ 'post-edit:After file editing'+ 'pre-command:Before command execution'+ 'post-command:After command execution'+ 'pre-task:Before task start'+ 'post-task:After task completion'+ 'route:Route task to agent'+ 'explain:Explain routing'+ 'pretrain:Bootstrap intelligence'+ 'build-agents:Generate agent configs'+ 'metrics:Show metrics'+ 'transfer:Transfer learning'+ 'list:List hooks'+ 'intelligence:Neural intelligence commands'+ )+ ;;+ neural)+ subcommands=(+ 'train:Train neural patterns'+ 'status:Check neural status'+ 'patterns:Manage patterns'+ 'predict:Make predictions'+ 'optimize:Optimize models'+ )+ ;;+ security)+ subcommands=(+ 'scan:Security scan'+ 'cve:CVE detection'+ 'threats:Threat modeling'+ 'audit:Security audit'+ 'secrets:Secrets scanning'+ )+ ;;+ performance)+ subcommands=(+ 'benchmark:Run benchmarks'+ 'profile:Profile code'+ 'metrics:Show metrics'+ 'optimize:Optimize performance'+ 'bottleneck:Find bottlenecks'+ )+ ;;+ plugins)+ subcommands=(+ 'list:List plugins'+ 'install:Install plugin'+ 'uninstall:Remove plugin'+ 'toggle:Enable/disable'+ 'info:Plugin details'+ 'create:Scaffold plugin'+ )+ ;;+ deployment|deploy)+ subcommands=(+ 'deploy:Deploy to environment'+ 'status:Deployment status'+ 'rollback:Rollback version'+ 'history:Deployment history'+ 'environments:List environments'+ 'logs:View logs'+ )+ ;;+ claims)+ subcommands=(+ 'list:List claims'+ 'check:Check permission'+ 'grant:Grant claim'+ 'revoke:Revoke claim'+ 'roles:Manage roles'+ 'policies:Manage policies'+ )+ ;;+ embeddings)+ subcommands=(+ 'generate:Generate embeddings'+ 'search:Semantic search'+ 'compare:Compare vectors'+ 'collections:Manage collections'+ 'index:Index operations'+ 'providers:Embedding providers'+ )+ ;;+ daemon)+ subcommands=(+ 'start:Start daemon'+ 'stop:Stop daemon'+ 'status:Daemon status'+ 'trigger:Trigger event'+ 'enable:Enable feature'+ )+ ;;+ providers)+ subcommands=(+ 'list:List providers'+ 'configure:Configure provider'+ 'test:Test connection'+ 'models:Available models'+ 'usage:Usage statistics'+ )+ ;;+ esac+ _describe -t subcommands 'subcommands' subcommands+ ;;+ esac+}++_claude_flow "$@"+`;+}++// Generate fish completion script+function generateFishCompletion(): string {+ return `# claude-flow fish completion+# Generated by claude-flow completions fish+# Save to ~/.config/fish/completions/claude-flow.fish++# Disable file completion by default+complete -c claude-flow -f++# Top-level commands+${TOP_LEVEL_COMMANDS.map(cmd => `complete -c claude-flow -n "__fish_use_subcommand" -a "${cmd}"`).join('\n')}++# Swarm subcommands+${SWARM_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from swarm" -a "${sub}"`).join('\n')}++# Agent subcommands+${AGENT_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from agent" -a "${sub}"`).join('\n')}++# Task subcommands+${TASK_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from task" -a "${sub}"`).join('\n')}++# Memory subcommands+${MEMORY_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from memory" -a "${sub}"`).join('\n')}++# Hive-mind subcommands+${HIVE_MIND_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from hive-mind hive" -a "${sub}"`).join('\n')}++# Hooks subcommands+${HOOKS_SUBCOMMANDS.map(sub => `complete -c claude-flow -n "__fish_seen_subcommand_from hooks" -a "${sub}"`).join('\n')}++# Neural subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from neural" -a "train status patterns predict optimize"++# Security subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from security" -a "scan cve threats audit secrets"++# Performance subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from performance" -a "benchmark profile metrics optimize bottleneck"++# Plugins subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from plugins" -a "list install uninstall toggle info create"++# Deployment subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from deployment deploy" -a "deploy status rollback history environments logs"++# Claims subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from claims" -a "list check grant revoke roles policies"++# Embeddings subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from embeddings" -a "generate search compare collections index providers"++# Daemon subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from daemon" -a "start stop status trigger enable"++# Providers subcommands+complete -c claude-flow -n "__fish_seen_subcommand_from providers" -a "list configure test models usage"+`;+}++// Generate PowerShell completion script+function generatePowerShellCompletion(): string {+ return `# claude-flow PowerShell completion+# Generated by claude-flow completions powershell+# Add to $PROFILE or save to a separate file and dot-source it++$script:ClaudeFlowCommands = @(+ '${TOP_LEVEL_COMMANDS.join("',\n '")}'+)++$script:SubCommands = @{+ 'swarm' = @('${SWARM_SUBCOMMANDS.join("', '")}')+ 'agent' = @('${AGENT_SUBCOMMANDS.join("', '")}')+ 'task' = @('${TASK_SUBCOMMANDS.join("', '")}')+ 'memory' = @('${MEMORY_SUBCOMMANDS.join("', '")}')+ 'hive-mind' = @('${HIVE_MIND_SUBCOMMANDS.join("', '")}')+ 'hive' = @('${HIVE_MIND_SUBCOMMANDS.join("', '")}')+ 'hooks' = @('${HOOKS_SUBCOMMANDS.join("', '")}')+ 'neural' = @('train', 'status', 'patterns', 'predict', 'optimize')+ 'security' = @('scan', 'cve', 'threats', 'audit', 'secrets')+ 'performance' = @('benchmark', 'profile', 'metrics', 'optimize', 'bottleneck')+ 'plugins' = @('list', 'install', 'uninstall', 'toggle', 'info', 'create')+ 'deployment' = @('deploy', 'status', 'rollback', 'history', 'environments', 'logs')+ 'deploy' = @('deploy', 'status', 'rollback', 'history', 'environments', 'logs')+ 'claims' = @('list', 'check', 'grant', 'revoke', 'roles', 'policies')+ 'embeddings' = @('generate', 'search', 'compare', 'collections', 'index', 'providers')+ 'daemon' = @('start', 'stop', 'status', 'trigger', 'enable')+ 'providers' = @('list', 'configure', 'test', 'models', 'usage')+}++Register-ArgumentCompleter -Native -CommandName claude-flow -ScriptBlock {+ param($wordToComplete, $commandAst, $cursorPosition)++ $tokens = $commandAst.ToString().Split(' ')+ $command = $tokens[1]++ if ($tokens.Count -eq 2) {+ # Complete top-level commands+ $script:ClaudeFlowCommands | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {+ [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)+ }+ }+ elseif ($tokens.Count -eq 3 -and $script:SubCommands.ContainsKey($command)) {+ # Complete subcommands+ $script:SubCommands[$command] | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {+ [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)+ }+ }+}+`;+}++// Bash subcommand+const bashCommand: Command = {+ name: 'bash',+ description: 'Generate bash completion script',+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const script = generateBashCompletion();+ output.writeln(script);+ return { success: true };+ }+};++// Zsh subcommand+const zshCommand: Command = {+ name: 'zsh',+ description: 'Generate zsh completion script',+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const script = generateZshCompletion();+ output.writeln(script);+ return { success: true };+ }+};++// Fish subcommand+const fishCommand: Command = {+ name: 'fish',+ description: 'Generate fish completion script',+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const script = generateFishCompletion();+ output.writeln(script);+ return { success: true };+ }+};++// PowerShell subcommand+const powershellCommand: Command = {+ name: 'powershell',+ aliases: ['pwsh'],+ description: 'Generate PowerShell completion script',+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const script = generatePowerShellCompletion();+ output.writeln(script);+ return { success: true };+ }+};++// Main completions command+export const completionsCommand: Command = {+ name: 'completions',+ description: 'Generate shell completion scripts',+ subcommands: [bashCommand, zshCommand, fishCommand, powershellCommand],+ options: [],+ examples: [+ { command: 'claude-flow completions bash > ~/.bash_completion.d/claude-flow', description: 'Install bash completions' },+ { command: 'claude-flow completions zsh > ~/.zfunc/_claude-flow', description: 'Install zsh completions' },+ { command: 'claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish', description: 'Install fish completions' },+ { command: 'claude-flow completions powershell >> $PROFILE', description: 'Install PowerShell completions' }+ ],+ action: async (): Promise<CommandResult> => {+ output.writeln();+ output.writeln(output.bold('Shell Completions'));+ output.writeln();+ output.writeln('Generate shell completion scripts for tab completion support.');+ output.writeln();+ output.writeln('Supported shells:');+ output.printList([+ `${output.highlight('bash')} - Bash completion`,+ `${output.highlight('zsh')} - Zsh completion`,+ `${output.highlight('fish')} - Fish completion`,+ `${output.highlight('powershell')} - PowerShell completion`+ ]);+ output.writeln();+ output.writeln('Installation:');+ output.writeln();+ output.writeln(output.bold('Bash:'));+ output.writeln(output.dim(' claude-flow completions bash > ~/.bash_completion.d/claude-flow'));+ output.writeln(output.dim(' source ~/.bash_completion.d/claude-flow'));+ output.writeln();+ output.writeln(output.bold('Zsh:'));+ output.writeln(output.dim(' mkdir -p ~/.zfunc'));+ output.writeln(output.dim(' claude-flow completions zsh > ~/.zfunc/_claude-flow'));+ output.writeln(output.dim(' # Add to ~/.zshrc: fpath=(~/.zfunc $fpath); autoload -Uz compinit && compinit'));+ output.writeln();+ output.writeln(output.bold('Fish:'));+ output.writeln(output.dim(' claude-flow completions fish > ~/.config/fish/completions/claude-flow.fish'));+ output.writeln();+ output.writeln(output.bold('PowerShell:'));+ output.writeln(output.dim(' claude-flow completions powershell >> $PROFILE'));++ return { success: true };+ }+};++export default completionsCommand;diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.tsnew file mode 100644index 0000000000..a0629d5af5--- /dev/null+++ b/v3/@claude-flow/cli/src/commands/doctor.ts@@ -0,0 +1,378 @@+/**+ * V3 CLI Doctor Command+ * System diagnostics, dependency checks, config validation+ *+ * Created with ruv.io+ */++import type { Command, CommandContext, CommandResult } from '../types.js';+import { output } from '../output.js';+import { existsSync, readFileSync } from 'fs';+import { join } from 'path';+import { execSync } from 'child_process';++interface HealthCheck {+ name: string;+ status: 'pass' | 'warn' | 'fail';+ message: string;+ fix?: string;+}++// Check Node.js version+async function checkNodeVersion(): Promise<HealthCheck> {+ const requiredMajor = 20;+ const version = process.version;+ const major = parseInt(version.slice(1).split('.')[0], 10);++ if (major >= requiredMajor) {+ return { name: 'Node.js Version', status: 'pass', message: `${version} (>= ${requiredMajor} required)` };+ } else if (major >= 18) {+ return { name: 'Node.js Version', status: 'warn', message: `${version} (>= ${requiredMajor} recommended)`, fix: 'nvm install 20 && nvm use 20' };+ } else {+ return { name: 'Node.js Version', status: 'fail', message: `${version} (>= ${requiredMajor} required)`, fix: 'nvm install 20 && nvm use 20' };+ }+}++// Check npm version+async function checkNpmVersion(): Promise<HealthCheck> {+ try {+ const version = execSync('npm --version', { encoding: 'utf8' }).trim();+ const major = parseInt(version.split('.')[0], 10);+ if (major >= 9) {+ return { name: 'npm Version', status: 'pass', message: `v${version}` };+ } else {+ return { name: 'npm Version', status: 'warn', message: `v${version} (>= 9 recommended)`, fix: 'npm install -g npm@latest' };+ }+ } catch {+ return { name: 'npm Version', status: 'fail', message: 'npm not found', fix: 'Install Node.js from https://nodejs.org' };+ }+}++// Check config file+async function checkConfigFile(): Promise<HealthCheck> {+ const configPaths = [+ '.claude-flow/config.json',+ 'claude-flow.config.json',+ '.claude-flow.json'+ ];++ for (const configPath of configPaths) {+ if (existsSync(configPath)) {+ try {+ const content = readFileSync(configPath, 'utf8');+ JSON.parse(content);+ return { name: 'Config File', status: 'pass', message: `Found: ${configPath}` };+ } catch (e) {+ return { name: 'Config File', status: 'fail', message: `Invalid JSON: ${configPath}`, fix: 'Fix JSON syntax in config file' };+ }+ }+ }++ return { name: 'Config File', status: 'warn', message: 'No config file (using defaults)', fix: 'claude-flow config init' };+}++// Check daemon status+async function checkDaemonStatus(): Promise<HealthCheck> {+ try {+ const pidFile = '.claude-flow/daemon.pid';+ if (existsSync(pidFile)) {+ const pid = readFileSync(pidFile, 'utf8').trim();+ try {+ process.kill(parseInt(pid, 10), 0); // Check if process exists+ return { name: 'Daemon Status', status: 'pass', message: `Running (PID: ${pid})` };+ } catch {+ return { name: 'Daemon Status', status: 'warn', message: 'Stale PID file', fix: 'rm .claude-flow/daemon.pid && claude-flow daemon start' };+ }+ }+ return { name: 'Daemon Status', status: 'warn', message: 'Not running', fix: 'claude-flow daemon start' };+ } catch {+ return { name: 'Daemon Status', status: 'warn', message: 'Unable to check', fix: 'claude-flow daemon status' };+ }+}++// Check memory database+async function checkMemoryDatabase(): Promise<HealthCheck> {+ const dbPaths = [+ '.claude-flow/memory.db',+ '.swarm/memory.db',+ 'data/memory.db'+ ];++ for (const dbPath of dbPaths) {+ if (existsSync(dbPath)) {+ try {+ const stats = require('fs').statSync(dbPath);+ const sizeMB = (stats.size / 1024 / 1024).toFixed(2);+ return { name: 'Memory Database', status: 'pass', message: `${dbPath} (${sizeMB} MB)` };+ } catch {+ return { name: 'Memory Database', status: 'warn', message: `${dbPath} (unable to stat)` };+ }+ }+ }++ return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };+}++// Check API keys+async function checkApiKeys(): Promise<HealthCheck> {+ const keys = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY', 'OPENAI_API_KEY'];+ const found: string[] = [];++ for (const key of keys) {+ if (process.env[key]) {+ found.push(key);+ }+ }++ if (found.includes('ANTHROPIC_API_KEY') || found.includes('CLAUDE_API_KEY')) {+ return { name: 'API Keys', status: 'pass', message: `Found: ${found.join(', ')}` };+ } else if (found.length > 0) {+ return { name: 'API Keys', status: 'warn', message: `Found: ${found.join(', ')} (no Claude key)`, fix: 'export ANTHROPIC_API_KEY=your_key' };+ } else {+ return { name: 'API Keys', status: 'warn', message: 'No API keys found', fix: 'export ANTHROPIC_API_KEY=your_key' };+ }+}++// Check git+async function checkGit(): Promise<HealthCheck> {+ try {+ const version = execSync('git --version', { encoding: 'utf8' }).trim();+ return { name: 'Git', status: 'pass', message: version.replace('git version ', 'v') };+ } catch {+ return { name: 'Git', status: 'warn', message: 'Not installed', fix: 'Install git from https://git-scm.com' };+ }+}++// Check if in git repo+async function checkGitRepo(): Promise<HealthCheck> {+ try {+ execSync('git rev-parse --git-dir', { encoding: 'utf8', stdio: 'pipe' });+ return { name: 'Git Repository', status: 'pass', message: 'In a git repository' };+ } catch {+ return { name: 'Git Repository', status: 'warn', message: 'Not a git repository', fix: 'git init' };+ }+}++// Check MCP servers+async function checkMcpServers(): Promise<HealthCheck> {+ const mcpConfigPaths = [+ join(process.env.HOME || '', '.claude/claude_desktop_config.json'),+ join(process.env.HOME || '', '.config/claude/mcp.json'),+ '.mcp.json'+ ];++ for (const configPath of mcpConfigPaths) {+ if (existsSync(configPath)) {+ try {+ const content = JSON.parse(readFileSync(configPath, 'utf8'));+ const servers = content.mcpServers || content.servers || {};+ const count = Object.keys(servers).length;+ const hasClaudeFlow = 'claude-flow' in servers || 'claude-flow_alpha' in servers;+ if (hasClaudeFlow) {+ return { name: 'MCP Servers', status: 'pass', message: `${count} servers (claude-flow configured)` };+ } else {+ return { name: 'MCP Servers', status: 'warn', message: `${count} servers (claude-flow not found)`, fix: 'claude mcp add claude-flow npx @claude-flow/cli@v3alpha mcp start' };+ }+ } catch {+ // continue to next path+ }+ }+ }++ return { name: 'MCP Servers', status: 'warn', message: 'No MCP config found', fix: 'claude mcp add claude-flow npx @claude-flow/cli@v3alpha mcp start' };+}++// Check disk space+async function checkDiskSpace(): Promise<HealthCheck> {+ try {+ if (process.platform === 'win32') {+ return { name: 'Disk Space', status: 'pass', message: 'Check skipped on Windows' };+ }+ const output_str = execSync('df -h . | tail -1', { encoding: 'utf8' });+ const parts = output_str.split(/\s+/);+ const available = parts[3];+ const usePercent = parseInt(parts[4]?.replace('%', '') || '0', 10);++ if (usePercent > 90) {+ return { name: 'Disk Space', status: 'fail', message: `${available} available (${usePercent}% used)`, fix: 'Free up disk space' };+ } else if (usePercent > 80) {+ return { name: 'Disk Space', status: 'warn', message: `${available} available (${usePercent}% used)` };+ }+ return { name: 'Disk Space', status: 'pass', message: `${available} available` };+ } catch {+ return { name: 'Disk Space', status: 'warn', message: 'Unable to check' };+ }+}++// Check TypeScript/build+async function checkBuildTools(): Promise<HealthCheck> {+ try {+ const tscVersion = execSync('npx tsc --version 2>/dev/null || echo "not found"', { encoding: 'utf8' }).trim();+ if (tscVersion.includes('not found')) {+ return { name: 'TypeScript', status: 'warn', message: 'Not installed locally', fix: 'npm install -D typescript' };+ }+ return { name: 'TypeScript', status: 'pass', message: tscVersion.replace('Version ', 'v') };+ } catch {+ return { name: 'TypeScript', status: 'warn', message: 'Unable to check' };+ }+}++// Format health check result+function formatCheck(check: HealthCheck): string {+ const icon = check.status === 'pass' ? output.success('✓') :+ check.status === 'warn' ? output.warning('⚠') :+ output.error('✗');+ return `${icon} ${check.name}: ${check.message}`;+}++// Main doctor command+export const doctorCommand: Command = {+ name: 'doctor',+ description: 'System diagnostics and health checks',+ options: [+ {+ name: 'fix',+ short: 'f',+ description: 'Show fix commands for issues',+ type: 'boolean',+ default: false+ },+ {+ name: 'component',+ short: 'c',+ description: 'Check specific component (node, config, daemon, memory, api, git, mcp)',+ type: 'string'+ },+ {+ name: 'verbose',+ short: 'v',+ description: 'Verbose output',+ type: 'boolean',+ default: false+ }+ ],+ examples: [+ { command: 'claude-flow doctor', description: 'Run full health check' },+ { command: 'claude-flow doctor --fix', description: 'Show fixes for issues' },+ { command: 'claude-flow doctor -c daemon', description: 'Check specific component' }+ ],+ action: async (ctx: CommandContext): Promise<CommandResult> => {+ const showFix = ctx.flags.fix as boolean;+ const component = ctx.flags.component as string;+ const verbose = ctx.flags.verbose as boolean;++ output.writeln();+ output.writeln(output.bold('Claude Flow Doctor'));+ output.writeln(output.dim('System diagnostics and health check'));+ output.writeln(output.dim('─'.repeat(50)));+ output.writeln();++ const allChecks: (() => Promise<HealthCheck>)[] = [+ checkNodeVersion,+ checkNpmVersion,+ checkGit,+ checkGitRepo,+ checkConfigFile,+ checkDaemonStatus,+ checkMemoryDatabase,+ checkApiKeys,+ checkMcpServers,+ checkDiskSpace,+ checkBuildTools+ ];++ const componentMap: Record<string, () => Promise<HealthCheck>> = {+ 'node': checkNodeVersion,+ 'npm': checkNpmVersion,+ 'config': checkConfigFile,+ 'daemon': checkDaemonStatus,+ 'memory': checkMemoryDatabase,+ 'api': checkApiKeys,+ 'git': checkGit,+ 'mcp': checkMcpServers,+ 'disk': checkDiskSpace,+ 'typescript': checkBuildTools+ };++ let checksToRun = allChecks;+ if (component && componentMap[component]) {+ checksToRun = [componentMap[component]];+ }++ const results: HealthCheck[] = [];+ const fixes: string[] = [];++ for (const check of checksToRun) {+ const spinner = output.createSpinner({ text: 'Checking...', spinner: 'dots' });+ spinner.start();++ try {+ const result = await check();+ results.push(result);++ spinner.stop();+ output.writeln(formatCheck(result));++ if (result.fix && (result.status === 'fail' || result.status === 'warn')) {+ fixes.push(`${result.name}: ${result.fix}`);+ }+ } catch (error) {+ spinner.stop();+ const errorResult: HealthCheck = {+ name: 'Check',+ status: 'fail',+ message: error instanceof Error ? error.message : 'Unknown error'+ };+ results.push(errorResult);+ output.writeln(formatCheck(errorResult));+ }+ }++ // Summary+ const passed = results.filter(r => r.status === 'pass').length;+ const warnings = results.filter(r => r.status === 'warn').length;+ const failed = results.filter(r => r.status === 'fail').length;++ output.writeln();+ output.writeln(output.dim('─'.repeat(50)));+ output.writeln();++ const summaryParts = [+ output.success(`${passed} passed`),+ warnings > 0 ? output.warning(`${warnings} warnings`) : null,+ failed > 0 ? output.error(`${failed} failed`) : null+ ].filter(Boolean);++ output.writeln(`Summary: ${summaryParts.join(', ')}`);++ // Show fixes+ if (showFix && fixes.length > 0) {+ output.writeln();+ output.writeln(output.bold('Suggested Fixes:'));+ output.writeln();+ for (const fix of fixes) {+ output.writeln(output.dim(` ${fix}`));+ }+ } else if (fixes.length > 0 && !showFix) {+ output.writeln();+ output.writeln(output.dim(`Run with --fix to see ${fixes.length} suggested fix${fixes.length > 1 ? 'es' : ''}`));+ }++ // Overall result+ if (failed > 0) {+ output.writeln();+ output.writeln(output.error('Some checks failed. Please address the issues above.'));+ return { success: false, exitCode: 1, data: { passed, warnings, failed, results } };+ } else if (warnings > 0) {+ output.writeln();+ output.writeln(output.warning('All checks passed with some warnings.'));+ return { success: true, data: { passed, warnings, failed, results } };+ } else {+ output.writeln();+ output.writeln(output.success('All checks passed! System is healthy.'));+ return { success: true, data: { passed, warnings, failed, results } };+ }+ }+};++export default doctorCommand;diff --git a/v3/@claude-flow/cli/src/commands/index.ts b/v3/@claude-flow/cli/src/commands/index.tsindex 8dd5241978..dc1f0a5c6c 100644--- a/v3/@claude-flow/cli/src/commands/index.ts+++ b/v3/@claude-flow/cli/src/commands/index.ts@@ -30,6 +30,9 @@ import { pluginsCommand } from './plugins.js';import { deploymentCommand } from './deployment.js';import { claimsCommand } from './claims.js';import { embeddingsCommand } from './embeddings.js';+// P0 Commands+import { completionsCommand } from './completions.js';+import { doctorCommand } from './doctor.js';// Export all commandsexport { agentCommand } from './agent.js';@@ -58,6 +61,9 @@ export { pluginsCommand } from './plugins.js';export { deploymentCommand } from './deployment.js';export { claimsCommand } from './claims.js';export { embeddingsCommand } from './embeddings.js';+// P0 Commands+export { completionsCommand } from './completions.js';+export { doctorCommand } from './doctor.js';/*** All available commands@@ -90,6 +96,9 @@ export const commands: Command[] = [deploymentCommand,claimsCommand,embeddingsCommand,+ // P0 Commands+ completionsCommand,+ doctorCommand,];/**diff --git a/v3/@claude-flow/cli/src/commands/memory.ts b/v3/@claude-flow/cli/src/commands/memory.tsindex 64685fefd3..019958e3f3 100644--- a/v3/@claude-flow/cli/src/commands/memory.ts+++ b/v3/@claude-flow/cli/src/commands/memory.ts@@ -30,8 +30,8 @@ const storeCommand: Command = {},{name: 'value',- short: 'v',- description: 'Value to store',+ // Note: No short flag - global -v is reserved for verbose+ description: 'Value to store (use --value)',type: 'string'},{diff --git a/v3/@claude-flow/cli/src/index.ts b/v3/@claude-flow/cli/src/index.tsindex 726e77b030..61b6678d1b 100644--- a/v3/@claude-flow/cli/src/index.ts+++ b/v3/@claude-flow/cli/src/index.ts@@ -11,7 +11,8 @@ import { dirname, join } from 'path';import type { Command, CommandContext, CommandResult, V3Config, CLIError } from './types.js';import { CommandParser, commandParser } from './parser.js';import { OutputFormatter, output } from './output.js';-import { commands, commandRegistry, getCommand } from './commands/index.js';+import { commands, commandRegistry, getCommand, getCommandNames } from './commands/index.js';+import { suggestCommand } from './suggest.js';// Read version from package.json at runtimefunction getPackageVersion(): string {@@ -114,7 +115,10 @@ export class CLI {if (!command) {this.output.printError(`Unknown command: ${commandName}`);- this.output.writeln(`Run "${this.name} --help" for available commands`);+ // Smart suggestions+ const availableCommands = Array.from(new Set(commands.map(c => c.name)));+ const { message } = suggestCommand(commandName, availableCommands);+ this.output.writeln(this.output.dim(` ${message}`));process.exit(1);}diff --git a/v3/@claude-flow/cli/src/suggest.ts b/v3/@claude-flow/cli/src/suggest.tsnew file mode 100644index 0000000000..247c97dc87--- /dev/null+++ b/v3/@claude-flow/cli/src/suggest.ts@@ -0,0 +1,245 @@+/**+ * V3 CLI Smart Error Suggestions+ * Levenshtein distance and command suggestions+ *+ * Created with ruv.io+ */++/**+ * Calculate Levenshtein distance between two strings+ */+export function levenshteinDistance(a: string, b: string): number {+ const m = a.length;+ const n = b.length;++ // Early termination for empty strings+ if (m === 0) return n;+ if (n === 0) return m;++ // Create distance matrix+ const d: number[][] = Array(m + 1).fill(null).map(() => Array(n + 1).fill(0));++ // Initialize first column+ for (let i = 0; i <= m; i++) {+ d[i][0] = i;+ }++ // Initialize first row+ for (let j = 0; j <= n; j++) {+ d[0][j] = j;+ }++ // Fill in the rest of the matrix+ for (let j = 1; j <= n; j++) {+ for (let i = 1; i <= m; i++) {+ const cost = a[i - 1] === b[j - 1] ? 0 : 1;+ d[i][j] = Math.min(+ d[i - 1][j] + 1, // deletion+ d[i][j - 1] + 1, // insertion+ d[i - 1][j - 1] + cost // substitution+ );+ }+ }++ return d[m][n];+}++/**+ * Calculate similarity score (0-1) between two strings+ */+export function similarityScore(a: string, b: string): number {+ const maxLen = Math.max(a.length, b.length);+ if (maxLen === 0) return 1;+ const distance = levenshteinDistance(a.toLowerCase(), b.toLowerCase());+ return 1 - distance / maxLen;+}++/**+ * Find similar strings from a list+ */+export function findSimilar(+ input: string,+ candidates: string[],+ options: {+ maxSuggestions?: number;+ minSimilarity?: number;+ maxDistance?: number;+ } = {}+): string[] {+ const {+ maxSuggestions = 3,+ minSimilarity = 0.4,+ maxDistance = 3+ } = options;++ const inputLower = input.toLowerCase();++ // Score all candidates+ const scored = candidates+ .map(candidate => ({+ candidate,+ distance: levenshteinDistance(inputLower, candidate.toLowerCase()),+ similarity: similarityScore(inputLower, candidate),+ // Boost prefix matches+ prefixBoost: candidate.toLowerCase().startsWith(inputLower) ? 0.3 : 0+ }))+ .filter(s => s.distance <= maxDistance || s.similarity >= minSimilarity)+ .map(s => ({+ ...s,+ score: s.similarity + s.prefixBoost+ }))+ .sort((a, b) => b.score - a.score)+ .slice(0, maxSuggestions);++ return scored.map(s => s.candidate);+}++/**+ * Format suggestion message for CLI errors+ */+export function formatSuggestion(+ invalidInput: string,+ suggestions: string[],+ context: 'command' | 'subcommand' | 'option' | 'value' = 'command'+): string {+ if (suggestions.length === 0) {+ return '';+ }++ const contextMap = {+ command: 'Did you mean',+ subcommand: 'Available subcommands',+ option: 'Did you mean',+ value: 'Valid values'+ };++ const prefix = contextMap[context];++ if (suggestions.length === 1) {+ return `\n ${prefix}: ${suggestions[0]}`;+ }++ return `\n ${prefix}:\n${suggestions.map(s => ` - ${s}`).join('\n')}`;+}++/**+ * Common typos and their corrections+ */+export const COMMON_TYPOS: Record<string, string> = {+ 'init': 'init',+ 'initi': 'init',+ 'inizialize': 'init',+ 'staus': 'status',+ 'stauts': 'status',+ 'stats': 'stats',+ 'stat': 'status',+ 'swarrm': 'swarm',+ 'swarn': 'swarm',+ 'agnet': 'agent',+ 'agen': 'agent',+ 'memroy': 'memory',+ 'mem': 'memory',+ 'memmory': 'memory',+ 'confg': 'config',+ 'conf': 'config',+ 'configu': 'config',+ 'hook': 'hooks',+ 'hoks': 'hooks',+ 'hive': 'hive-mind',+ 'hivemind': 'hive-mind',+ 'hive_mind': 'hive-mind',+ 'neurl': 'neural',+ 'nueral': 'neural',+ 'securty': 'security',+ 'sec': 'security',+ 'perf': 'performance',+ 'performace': 'performance',+ 'provider': 'providers',+ 'plugin': 'plugins',+ 'dep': 'deployment',+ 'depoly': 'deployment',+ 'deploy': 'deployment',+ 'claim': 'claims',+ 'embed': 'embeddings',+ 'embeding': 'embeddings',+ 'daemon': 'daemon',+ 'deamon': 'daemon',+ 'doc': 'doctor',+ 'docter': 'doctor',+ 'complete': 'completions',+ 'completion': 'completions',+ 'comp': 'completions',+ 'task': 'task',+ 'taks': 'task',+ 'sessio': 'session',+ 'sess': 'session',+ 'sesssion': 'session',+ 'workflow': 'workflow',+ 'wf': 'workflow',+ 'wokflow': 'workflow'+};++/**+ * Get corrected command if it's a common typo+ */+export function getTypoCorrection(input: string): string | undefined {+ return COMMON_TYPOS[input.toLowerCase()];+}++/**+ * Smart command suggestion for unknown commands+ */+export function suggestCommand(+ unknownCommand: string,+ availableCommands: string[]+): {+ correction?: string;+ suggestions: string[];+ message: string;+} {+ // Check for common typo first+ const correction = getTypoCorrection(unknownCommand);+ if (correction && availableCommands.includes(correction)) {+ return {+ correction,+ suggestions: [correction],+ message: `Did you mean "${correction}"?`+ };+ }++ // Find similar commands+ const suggestions = findSimilar(unknownCommand, availableCommands, {+ maxSuggestions: 3,+ minSimilarity: 0.3,+ maxDistance: 4+ });++ if (suggestions.length === 0) {+ return {+ suggestions: [],+ message: 'Run "claude-flow --help" to see available commands.'+ };+ }++ if (suggestions.length === 1) {+ return {+ suggestions,+ message: `Did you mean "${suggestions[0]}"?`+ };+ }++ return {+ suggestions,+ message: `Did you mean one of these?\n${suggestions.map(s => ` - ${s}`).join('\n')}`+ };+}++export default {+ levenshteinDistance,+ similarityScore,+ findSimilar,+ formatSuggestion,+ suggestCommand,+ getTypoCorrection,+ COMMON_TYPOS+};diff --git a/v3/@claude-flow/embeddings/agents/architect.yaml b/v3/@claude-flow/embeddings/agents/architect.yamlindex 2f8632fc1c..60e6b327b2 100644--- a/v3/@claude-flow/embeddings/agents/architect.yaml+++ b/v3/@claude-flow/embeddings/agents/architect.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- context-caching- memory-persistence-createdAt: "2026-01-07T04:20:22.495Z"+createdAt: "2026-01-07T04:34:45.999Z"diff --git a/v3/@claude-flow/embeddings/agents/coder.yaml b/v3/@claude-flow/embeddings/agents/coder.yamlindex 48396c28f7..16dd32c575 100644--- a/v3/@claude-flow/embeddings/agents/coder.yaml+++ b/v3/@claude-flow/embeddings/agents/coder.yaml@@ -8,4 +8,4 @@ capabilities:optimizations:- flash-attention- token-reduction-createdAt: "2026-01-07T04:20:22.494Z"+createdAt: "2026-01-07T04:34:45.999Z"diff --git a/v3/@claude-flow/embeddings/agents/reviewer.yaml b/v3/@claude-flow/embeddings/agents/reviewer.yamlindex 8a9347d1ab..a178bc138b 100644--- a/v3/@claude-flow/embeddings/agents/reviewer.yaml+++ b/v3/@claude-flow/embeddings/agents/reviewer.yaml@@ -7,4 +7,4 @@ capabilities:- best-practicesoptimizations:- incremental-analysis-createdAt: "2026-01-07T04:20:22.495Z"+createdAt: "2026-01-07T04:34:46.000Z"diff --git a/v3/@claude-flow/embeddings/agents/security-architect.yaml b/v3/@claude-flow/embeddings/agents/security-architect.yamlindex 26f15b36a6..d633a16b23 100644--- a/v3/@claude-flow/embeddings/agents/security-architect.yaml+++ b/v3/@claude-flow/embeddings/agents/security-architect.yaml@@ -7,4 +7,4 @@ capabilities:- security-reviewoptimizations:- pattern-matching-createdAt: "2026-01-07T04:20:22.495Z"+createdAt: "2026-01-07T04:34:46.000Z"diff --git a/v3/@claude-flow/embeddings/agents/tester.yaml b/v3/@claude-flow/embeddings/agents/tester.yamlindex 3f8eccc73b..7f017c417f 100644--- a/v3/@claude-flow/embeddings/agents/tester.yaml+++ b/v3/@claude-flow/embeddings/agents/tester.yaml@@ -7,4 +7,4 @@ capabilities:- coverageoptimizations:- parallel-execution-createdAt: "2026-01-07T04:20:22.495Z"+createdAt: "2026-01-07T04:34:46.000Z"diff --git a/v3/@claude-flow/embeddings/src/persistent-cache.ts b/v3/@claude-flow/embeddings/src/persistent-cache.tsnew file mode 100644index 0000000000..341d7a608f--- /dev/null+++ b/v3/@claude-flow/embeddings/src/persistent-cache.ts@@ -0,0 +1,314 @@+/**+ * SQLite-backed Persistent Cache for Embeddings+ *+ * Features:+ * - Disk persistence across sessions+ * - LRU eviction with configurable max size+ * - Automatic schema creation+ * - TTL support for cache entries+ * - Lazy initialization (no startup cost if not used)+ */++import { existsSync, mkdirSync } from 'fs';+import { dirname } from 'path';++// SQLite types (dynamically imported)+type Database = {+ prepare(sql: string): Statement;+ exec(sql: string): void;+ close(): void;+};++type Statement = {+ run(...params: unknown[]): { changes: number };+ get(...params: unknown[]): unknown;+ all(...params: unknown[]): unknown[];+};++/**+ * Configuration for persistent cache+ */+export interface PersistentCacheConfig {+ /** Path to SQLite database file */+ dbPath: string;+ /** Maximum number of entries (default: 10000) */+ maxSize?: number;+ /** TTL in milliseconds (default: 7 days) */+ ttlMs?: number;+ /** Enable compression for large embeddings */+ compress?: boolean;+}++/**+ * Cache statistics+ */+export interface PersistentCacheStats {+ size: number;+ maxSize: number;+ hitRate: number;+ hits: number;+ misses: number;+ dbSizeBytes?: number;+}++/**+ * SQLite-backed persistent embedding cache+ */+export class PersistentEmbeddingCache {+ private db: Database | null = null;+ private initialized = false;+ private hits = 0;+ private misses = 0;++ private readonly dbPath: string;+ private readonly maxSize: number;+ private readonly ttlMs: number;++ constructor(config: PersistentCacheConfig) {+ this.dbPath = config.dbPath;+ this.maxSize = config.maxSize ?? 10000;+ this.ttlMs = config.ttlMs ?? 7 * 24 * 60 * 60 * 1000; // 7 days+ }++ /**+ * Lazily initialize database connection+ */+ private async ensureInitialized(): Promise<void> {+ if (this.initialized) return;++ try {+ // Dynamically import better-sqlite3+ const BetterSqlite3 = (await import('better-sqlite3')).default;++ // Ensure directory exists+ const dir = dirname(this.dbPath);+ if (!existsSync(dir)) {+ mkdirSync(dir, { recursive: true });+ }++ this.db = new BetterSqlite3(this.dbPath) as unknown as Database;++ // Create schema+ this.db.exec(`+ CREATE TABLE IF NOT EXISTS embeddings (+ key TEXT PRIMARY KEY,+ embedding BLOB NOT NULL,+ dimensions INTEGER NOT NULL,+ created_at INTEGER NOT NULL,+ accessed_at INTEGER NOT NULL,+ access_count INTEGER DEFAULT 1+ );++ CREATE INDEX IF NOT EXISTS idx_accessed_at ON embeddings(accessed_at);+ CREATE INDEX IF NOT EXISTS idx_created_at ON embeddings(created_at);+ `);++ // Clean expired entries on startup+ this.cleanExpired();++ this.initialized = true;+ } catch (error) {+ // If better-sqlite3 not available, fall back gracefully+ console.warn('[persistent-cache] SQLite not available, cache disabled:',+ error instanceof Error ? error.message : error);+ this.initialized = true; // Mark as initialized to prevent retry+ }+ }++ /**+ * Generate cache key from text+ */+ private hashKey(text: string): string {+ // FNV-1a hash for fast, deterministic key generation+ let hash = 0x811c9dc5;+ for (let i = 0; i < text.length; i++) {+ hash ^= text.charCodeAt(i);+ hash = (hash * 0x01000193) >>> 0;+ }+ return `emb_${hash.toString(16)}_${text.length}`;+ }++ /**+ * Serialize Float32Array to Buffer+ */+ private serializeEmbedding(embedding: Float32Array): Buffer {+ return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);+ }++ /**+ * Deserialize Buffer to Float32Array+ */+ private deserializeEmbedding(buffer: Buffer, dimensions: number): Float32Array {+ const arrayBuffer = buffer.buffer.slice(+ buffer.byteOffset,+ buffer.byteOffset + buffer.byteLength+ );+ return new Float32Array(arrayBuffer);+ }++ /**+ * Get embedding from cache+ */+ async get(text: string): Promise<Float32Array | null> {+ await this.ensureInitialized();+ if (!this.db) {+ this.misses++;+ return null;+ }++ const key = this.hashKey(text);+ const now = Date.now();++ try {+ const row = this.db.prepare(`+ SELECT embedding, dimensions, created_at+ FROM embeddings+ WHERE key = ?+ `).get(key) as { embedding: Buffer; dimensions: number; created_at: number } | undefined;++ if (!row) {+ this.misses++;+ return null;+ }++ // Check TTL+ if (now - row.created_at > this.ttlMs) {+ this.db.prepare('DELETE FROM embeddings WHERE key = ?').run(key);+ this.misses++;+ return null;+ }++ // Update access time and count+ this.db.prepare(`+ UPDATE embeddings+ SET accessed_at = ?, access_count = access_count + 1+ WHERE key = ?+ `).run(now, key);++ this.hits++;+ return this.deserializeEmbedding(row.embedding, row.dimensions);+ } catch (error) {+ console.error('[persistent-cache] Get error:', error);+ this.misses++;+ return null;+ }+ }++ /**+ * Store embedding in cache+ */+ async set(text: string, embedding: Float32Array): Promise<void> {+ await this.ensureInitialized();+ if (!this.db) return;++ const key = this.hashKey(text);+ const now = Date.now();+ const buffer = this.serializeEmbedding(embedding);++ try {+ // Upsert entry+ this.db.prepare(`+ INSERT INTO embeddings (key, embedding, dimensions, created_at, accessed_at, access_count)+ VALUES (?, ?, ?, ?, ?, 1)+ ON CONFLICT(key) DO UPDATE SET+ embedding = excluded.embedding,+ accessed_at = excluded.accessed_at,+ access_count = access_count + 1+ `).run(key, buffer, embedding.length, now, now);++ // Check size and evict if needed+ await this.evictIfNeeded();+ } catch (error) {+ console.error('[persistent-cache] Set error:', error);+ }+ }++ /**+ * Evict oldest entries if cache exceeds max size+ */+ private async evictIfNeeded(): Promise<void> {+ if (!this.db) return;++ const count = (this.db.prepare('SELECT COUNT(*) as count FROM embeddings').get() as { count: number }).count;++ if (count > this.maxSize) {+ const toDelete = count - this.maxSize + Math.floor(this.maxSize * 0.1); // Delete 10% extra+ this.db.prepare(`+ DELETE FROM embeddings+ WHERE key IN (+ SELECT key FROM embeddings+ ORDER BY accessed_at ASC+ LIMIT ?+ )+ `).run(toDelete);+ }+ }++ /**+ * Clean expired entries+ */+ private cleanExpired(): void {+ if (!this.db) return;++ const cutoff = Date.now() - this.ttlMs;+ this.db.prepare('DELETE FROM embeddings WHERE created_at < ?').run(cutoff);+ }++ /**+ * Get cache statistics+ */+ async getStats(): Promise<PersistentCacheStats> {+ await this.ensureInitialized();++ const total = this.hits + this.misses;+ const stats: PersistentCacheStats = {+ size: 0,+ maxSize: this.maxSize,+ hitRate: total > 0 ? this.hits / total : 0,+ hits: this.hits,+ misses: this.misses,+ };++ if (this.db) {+ const row = this.db.prepare('SELECT COUNT(*) as count FROM embeddings').get() as { count: number };+ stats.size = row.count;+ }++ return stats;+ }++ /**+ * Clear all cached entries+ */+ async clear(): Promise<void> {+ await this.ensureInitialized();+ if (!this.db) return;++ this.db.exec('DELETE FROM embeddings');+ this.hits = 0;+ this.misses = 0;+ }++ /**+ * Close database connection+ */+ async close(): Promise<void> {+ if (this.db) {+ this.db.close();+ this.db = null;+ this.initialized = false;+ }+ }+}++/**+ * Check if persistent cache is available (better-sqlite3 installed)+ */+export async function isPersistentCacheAvailable(): Promise<boolean> {+ try {+ await import('better-sqlite3');+ return true;+ } catch {+ return false;+ }+}