cmp-memory-system 1.0.0

package/README.md

@@ -0,0 +1,541 @@
+# cmp-memory-system
+
+> Unified memory & workflow system for Claude Code projects
+
+## Features
+
+- **Task Tracking** - Automatic task registration in database
+- **Idea Capture** - Collect ideas and improvements during work
+- **Work Plans** - Persistent work plans across sessions
+- **Memory System** - Session context and memory management
+- **Auto-Improvement** - Pattern detection → ESLint rule generation
+- **Dashboard** - Web UI for visualization
+- **MCP Server** - Model Context Protocol integration
+- **Analytics** - Usage tracking and insights
+
+## Installation
+
+```bash
+npm install cmp-memory-system
+```
+
+## Quick Start
+
+```bash
+# Initialize in project
+cmp-memory init --system MYPROJECT --name "My Project"
+
+# Check status
+cmp-memory status
+
+# Check status
+claude-memory status
+```
+
+## CLI Commands
+
+### `claude-memory init`
+
+Initialize memory system in current project.
+
+```bash
+claude-memory init [options]
+
+Options:
+  -s, --system <system>  System identifier (SWARMSCALE, PANEL)
+  -n, --name <name>      Project name
+  -f, --force            Overwrite existing configuration
+```
+
+### `claude-memory generate`
+
+Generate embedding registry from documentation.
+
+```bash
+claude-memory generate [options]
+
+Options:
+  -i, --incremental     Only update changed files
+  --files <files>       Specific files (comma-separated)
+```
+
+### `claude-memory scan`
+
+Scan codebase for patterns.
+
+```bash
+claude-memory scan [options]
+
+Options:
+  -d, --dir <directory>   Directory to scan (default: src)
+  -t, --threshold <n>     Pattern threshold (default: 3)
+```
+
+### `claude-memory improve`
+
+Run auto-improvement for triggered patterns.
+
+```bash
+claude-memory improve [options]
+
+Options:
+  --dry-run              Show without making changes
+  -p, --pattern <id>     Specific pattern to improve
+```
+
+### `claude-memory status`
+
+Show memory system status.
+
+### `claude-memory dashboard`
+
+Start the memory dashboard web UI.
+
+```bash
+claude-memory dashboard [options]
+
+Options:
+  -p, --port <port>  Port to run on (default: 3847)
+  --no-open          Don't open browser automatically
+```
+
+### `claude-memory analytics`
+
+Show analytics and system health.
+
+```bash
+claude-memory analytics [options]
+
+Options:
+  -p, --period <period>  Time period (day, week, month)
+  --json                 Output as JSON
+```
+
+### `claude-memory feedback`
+
+View feedback statistics.
+
+### `claude-memory mcp`
+
+Start the MCP server for Claude integration.
+
+---
+
+## Workflow Commands (NEW)
+
+### `claude-memory tasks`
+
+View and manage tasks.
+
+```bash
+claude-memory tasks [options]
+
+Options:
+  -a, --all              Show all tasks including completed
+  -l, --limit <number>   Limit number of tasks (default: 10)
+```
+
+### `claude-memory ideas`
+
+View captured ideas.
+
+```bash
+claude-memory ideas [options]
+
+Options:
+  -c, --category <cat>   Filter by category (feature, refactor, bug, optimization, documentation)
+  -p, --priority <pri>   Filter by priority (high, medium, low)
+  -l, --limit <number>   Limit number of ideas (default: 20)
+```
+
+### `claude-memory improvements`
+
+View suggested improvements.
+
+```bash
+claude-memory improvements [options]
+
+Options:
+  -t, --type <type>      Filter by type (code_quality, performance, security, ux, architecture)
+  -e, --effort <effort>  Filter by effort (small, medium, large)
+  -l, --limit <number>   Limit number (default: 20)
+```
+
+### `claude-memory plan`
+
+Manage work plans.
+
+```bash
+claude-memory plan [options]
+
+Options:
+  -s, --status           Show current plan status
+  -c, --complete         Complete current task
+  -n, --next             Move to next task
+  -h, --history          Show plan history
+```
+
+### `claude-memory capture <text>`
+
+Quick capture an idea or improvement. Auto-categorizes based on content.
+
+```bash
+claude-memory capture "Consider adding caching to API calls"
+```
+
+### `claude-memory export`
+
+Export ideas and improvements as markdown.
+
+```bash
+claude-memory export [options]
+
+Options:
+  -o, --output <file>    Output file (default: IDEAS_AND_IMPROVEMENTS.md)
+```
+
+---
+
+## Architecture
+
+```
+@metanautical/claude-memory
+├── src/
+│   ├── hooks/
+│   │   ├── session-start.ts      # Context loader on session start
+│   │   ├── pre-tool-use.ts       # Guards + embedding injection
+│   │   ├── post-tool-use.ts      # Record changes after Edit/Write
+│   │   └── memory-checkpoint.ts  # Record learnings after changes
+│   ├── registry/
+│   │   ├── generator.ts          # Parse docs → embeddings
+│   │   └── embeddings.ts         # OpenAI/Gemini embedding service
+│   ├── auto-improve/
+│   │   ├── pattern-detector.ts   # Detect repeated violations
+│   │   └── eslint-generator.ts   # Generate ESLint rules
+│   ├── db/
+│   │   ├── client.ts             # DEV_Items database client (mock)
+│   │   └── drizzle-client.ts     # Real Drizzle ORM client
+│   ├── mcp/
+│   │   └── server.ts             # MCP server for Claude tools
+│   ├── dashboard/
+│   │   ├── server.ts             # Express dashboard server
+│   │   └── ui.ts                 # React UI generator
+│   ├── feedback/
+│   │   └── collector.ts          # User feedback collection
+│   ├── analytics/
+│   │   └── tracker.ts            # Usage analytics & insights
+│   ├── utils/
+│   │   ├── config.ts             # Configuration management
+│   │   └── paths.ts              # Path utilities
+│   ├── types/
+│   │   └── index.ts              # Type definitions
+│   ├── cli/
+│   │   └── index.ts              # CLI commands
+│   └── index.ts                  # Main exports
+```
+
+## Configuration
+
+### `.claude/memory-config.json`
+
+```json
+{
+  "system": "SWARMSCALE",
+  "projectName": "SwarmScale",
+  "domains": ["video-studio", "avatars", "campaigns"],
+  "guards": {
+    "enabled": true,
+    "rules": [
+      {
+        "id": "schema-protection",
+        "type": "block",
+        "filePattern": "src/server/schema/auth.ts",
+        "message": "PANEL_* tables are READ-ONLY"
+      }
+    ]
+  },
+  "embedding": {
+    "enabled": true,
+    "threshold": 0.60,
+    "maxSections": 3
+  },
+  "autoImprovement": {
+    "enabled": true,
+    "violationThreshold": 3,
+    "generateEslintRules": true
+  }
+}
+```
+
+### `.claude/settings.json`
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx node_modules/@metanautical/claude-memory/dist/hooks/pre-tool-use.js"
+        }]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{
+          "type": "command",
+          "command": "npx tsx node_modules/@metanautical/claude-memory/dist/hooks/session-start.js"
+        }]
+      }
+    ]
+  },
+  "plugins": {
+    "metanautical-memory": {
+      "version": "1.0.0",
+      "enabled": true
+    }
+  }
+}
+```
+
+## Hooks
+
+### SessionStart Hook
+
+Executes on session start:
+1. Detects module from `git diff` (last 24h)
+2. Queries DEV_Items for relevant memories
+3. Returns formatted context
+
+```typescript
+import { SessionStartHook } from '@metanautical/claude-memory/hooks'
+
+const hook = new SessionStartHook()
+const result = await hook.execute()
+// result.context contains session context
+```
+
+### PreToolUse Hook
+
+Executes before Edit/Write/Task tools:
+1. **Edit/Write**: Validates against guard rules
+2. **Task**: Injects relevant knowledge via embeddings
+
+```typescript
+import { PreToolUseHook } from '@metanautical/claude-memory/hooks'
+
+const hook = new PreToolUseHook()
+const result = await hook.execute({
+  tool_name: 'Edit',
+  parameters: { file_path: 'src/file.ts', new_string: '...' }
+})
+
+if (result.mode === 'block') {
+  // Guard violation - block operation
+}
+```
+
+## Auto-Improvement
+
+### Pattern Detection
+
+Built-in patterns detected:
+- `any-type` - Using `any` type
+- `console-log` - Console.log in production
+- `eslint-disable` - ESLint disable comments
+- `hardcoded-string` - UI strings not using i18n
+- `direct-db-query` - Database queries in components
+- `inline-style` - Inline styles instead of Tailwind
+
+### ESLint Rule Generation
+
+When a pattern is detected 3+ times:
+
+```bash
+# Scan for patterns
+claude-memory scan
+
+# Output:
+# 🔴 any-type [high]
+#    Count: 5, Files: 3
+# ⚠️ Patterns ready for auto-improvement
+
+# Generate ESLint rule
+claude-memory improve
+
+# Creates: eslint-plugin-charter/rules/no-any-type.js
+```
+
+## Programmatic Usage
+
+```typescript
+import {
+  loadConfig,
+  PatternDetector,
+  ESLintGenerator,
+  RegistryGenerator
+} from '@metanautical/claude-memory'
+
+// Load config
+const config = await loadConfig(process.cwd())
+
+// Detect patterns
+const detector = new PatternDetector(config)
+const patterns = detector.scan(fileContent, filePath)
+const results = detector.getResults()
+
+// Generate ESLint rules
+const generator = new ESLintGenerator()
+await generator.generateAllRules(results.triggered)
+
+// Generate registry
+const registry = new RegistryGenerator()
+await registry.generate()
+```
+
+## System Isolation
+
+Data is isolated by `system` field in DEV_Items:
+
+| System | Project |
+|--------|---------|
+| `SWARMSCALE` | SwarmScale |
+| `PANEL` | TheCharterPanel |
+| `ECOSYSTEM` | Cross-project |
+
+Always filter by system:
+
+```typescript
+// Correct
+db.select().from(devItems).where(eq(devItems.system, 'SWARMSCALE'))
+
+// Wrong - returns ALL projects' data
+db.select().from(devItems)
+```
+
+## Environment Variables
+
+```bash
+# Required for embedding generation
+OPENAI_API_KEY=sk-...      # Preferred
+GEMINI_API_KEY=...         # Fallback
+
+# Optional
+MEMORY_DEBUG=true          # Enable debug logging
+```
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run dev
+
+# Run tests
+npm test
+
+# Link for local development
+npm link
+```
+
+## MCP Server
+
+The MCP (Model Context Protocol) server exposes memory tools that Claude can use directly:
+
+```bash
+# Start MCP server
+claude-memory mcp
+```
+
+**Available Tools:**
+- `memory_search` - Search memories by query
+- `memory_write` - Write new memory/learning
+- `memory_list` - List recent memories
+- `pattern_check` - Check for detected patterns
+- `pattern_report` - Report a new pattern occurrence
+- `session_context` - Get current session context
+- `feedback_submit` - Submit feedback on a memory
+
+## Dashboard
+
+Start the standalone web dashboard:
+
+```bash
+claude-memory dashboard
+# Opens http://localhost:3847
+```
+
+**Features:**
+- View all memories with search and filtering
+- Browse detected patterns
+- See session history
+- Submit feedback on memories
+- Create new memories
+- View analytics and system health
+
+## Feedback Loop
+
+The feedback system adjusts memory relevance based on user feedback:
+
+```typescript
+import { createFeedbackCollector } from '@metanautical/claude-memory'
+
+const collector = createFeedbackCollector('SWARMSCALE')
+
+// Submit feedback
+await collector.submitFeedback(memoryId, true, 'Very helpful!')
+
+// Get feedback stats
+const stats = await collector.getStats()
+// { helpfulRate: 0.85, topHelpfulMemories: [...] }
+
+// Get suggestions for deprecation
+const deprecations = await collector.getSuggestedDeprecations()
+```
+
+## Analytics
+
+Track usage and get insights:
+
+```typescript
+import { createAnalyticsTracker } from '@metanautical/claude-memory'
+
+const tracker = createAnalyticsTracker('SWARMSCALE')
+
+// Track an event
+await tracker.track('memory_access', { memoryId: '...' })
+
+// Get usage stats
+const usage = await tracker.getUsageStats('week')
+// { sessions: 12, memoriesCreated: 5, searchesPerformed: 23, ... }
+
+// Get system health
+const health = await tracker.getSystemHealth()
+// { status: 'healthy', issues: [], recommendations: [...] }
+
+// Generate full report
+const report = await tracker.generateReport()
+```
+
+## Database Configuration
+
+Set environment variables for database connection:
+
+```bash
+DATABASE_HOST=localhost
+DATABASE_PORT=3306
+DATABASE_USER=root
+DATABASE_PASSWORD=your-password
+DATABASE_NAME=metanautical
+```
+
+## License
+
+MIT - MetaNautical Group

package/dist/analytics/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Analytics module exports
+ */
+export { AnalyticsTracker, createAnalyticsTracker, type AnalyticsEvent, type UsageStats, type MemoryInsights, type PatternInsights, type SystemHealth, } from './tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/analytics/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,YAAY,GAClB,MAAM,cAAc,CAAA"}

package/dist/analytics/index.js

@@ -0,0 +1,5 @@
+/**
+ * Analytics module exports
+ */
+export { AnalyticsTracker, createAnalyticsTracker, } from './tracker.js';
+//# sourceMappingURL=index.js.map

package/dist/analytics/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/analytics/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,gBAAgB,EAChB,sBAAsB,GAMvB,MAAM,cAAc,CAAA"}

package/dist/analytics/tracker.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Analytics Tracker
+ *
+ * Tracks memory system usage and provides insights for optimization.
+ */
+import type { DevSystem } from '../types/index.js';
+export interface AnalyticsEvent {
+    type: 'session_start' | 'memory_access' | 'memory_create' | 'pattern_detected' | 'feedback_given' | 'search_performed';
+    metadata: Record<string, unknown>;
+    timestamp: string;
+}
+export interface UsageStats {
+    period: 'day' | 'week' | 'month';
+    sessions: number;
+    memoriesCreated: number;
+    memoriesAccessed: number;
+    searchesPerformed: number;
+    patternsDetected: number;
+    feedbackGiven: number;
+    avgSessionDuration: number;
+}
+export interface MemoryInsights {
+    mostAccessedMemories: Array<{
+        id: string;
+        title: string;
+        accessCount: number;
+    }>;
+    leastUsedMemories: Array<{
+        id: string;
+        title: string;
+        daysSinceAccess: number;
+    }>;
+    domainDistribution: Record<string, number>;
+    sourceDistribution: Record<string, number>;
+    memoryGrowthTrend: Array<{
+        date: string;
+        count: number;
+    }>;
+}
+export interface PatternInsights {
+    mostFrequentPatterns: Array<{
+        patternId: string;
+        occurrences: number;
+        severity: string;
+    }>;
+    patternsOverTime: Array<{
+        date: string;
+        patternId: string;
+        count: number;
+    }>;
+    autoImprovementCandidates: Array<{
+        patternId: string;
+        occurrences: number;
+        files: number;
+    }>;
+}
+export interface SystemHealth {
+    status: 'healthy' | 'degraded' | 'critical';
+    metrics: {
+        totalMemories: number;
+        activePatterns: number;
+        triggeredPatterns: number;
+        recentSessions: number;
+        feedbackRate: number;
+        avgMemoryAge: number;
+    };
+    issues: string[];
+    recommendations: string[];
+}
+export declare class AnalyticsTracker {
+    private client;
+    private system;
+    constructor(system: DevSystem);
+    /**
+     * Track an analytics event
+     */
+    track(type: AnalyticsEvent['type'], metadata?: Record<string, unknown>): Promise<void>;
+    /**
+     * Get usage statistics for a time period
+     */
+    getUsageStats(period?: UsageStats['period']): Promise<UsageStats>;
+    /**
+     * Get memory insights
+     */
+    getMemoryInsights(): Promise<MemoryInsights>;
+    /**
+     * Get pattern insights
+     */
+    getPatternInsights(): Promise<PatternInsights>;
+    /**
+     * Get system health status
+     */
+    getSystemHealth(): Promise<SystemHealth>;
+    /**
+     * Generate a comprehensive analytics report
+     */
+    generateReport(): Promise<{
+        generatedAt: string;
+        system: DevSystem;
+        health: SystemHealth;
+        usage: UsageStats;
+        memoryInsights: MemoryInsights;
+        patternInsights: PatternInsights;
+    }>;
+}
+export declare function createAnalyticsTracker(system: DevSystem): AnalyticsTracker;
+//# sourceMappingURL=tracker.d.ts.map

package/dist/analytics/tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracker.d.ts","sourceRoot":"","sources":["../../src/analytics/tracker.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAiC,MAAM,mBAAmB,CAAA;AAOjF,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,GAAG,eAAe,GAAG,eAAe,GAAG,kBAAkB,GAAG,gBAAgB,GAAG,kBAAkB,CAAA;IACtH,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,CAAA;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,gBAAgB,EAAE,MAAM,CAAA;IACxB,iBAAiB,EAAE,MAAM,CAAA;IACzB,gBAAgB,EAAE,MAAM,CAAA;IACxB,aAAa,EAAE,MAAM,CAAA;IACrB,kBAAkB,EAAE,MAAM,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,oBAAoB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC/E,iBAAiB,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAChF,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC1C,iBAAiB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,eAAe;IAC9B,oBAAoB,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACzF,gBAAgB,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC3E,yBAAyB,EAAE,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAC5F;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;IAC3C,OAAO,EAAE;QACP,aAAa,EAAE,MAAM,CAAA;QACrB,cAAc,EAAE,MAAM,CAAA;QACtB,iBAAiB,EAAE,MAAM,CAAA;QACzB,cAAc,EAAE,MAAM,CAAA;QACtB,YAAY,EAAE,MAAM,CAAA;QACpB,YAAY,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,eAAe,EAAE,MAAM,EAAE,CAAA;CAC1B;AAMD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,MAAM,CAAW;gBAEb,MAAM,EAAE,SAAS;IAK7B;;OAEG;IACG,KAAK,CACT,IAAI,EAAE,cAAc,CAAC,MAAM,CAAC,EAC5B,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACrC,OAAO,CAAC,IAAI,CAAC;IAchB;;OAEG;IACG,aAAa,CAAC,MAAM,GAAE,UAAU,CAAC,QAAQ,CAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAuE/E;;OAEG;IACG,iBAAiB,IAAI,OAAO,CAAC,cAAc,CAAC;IAwFlD;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC,eAAe,CAAC;IAmDpD;;OAEG;IACG,eAAe,IAAI,OAAO,CAAC,YAAY,CAAC;IAsF9C;;OAEG;IACG,cAAc,IAAI,OAAO,CAAC;QAC9B,WAAW,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,SAAS,CAAA;QACjB,MAAM,EAAE,YAAY,CAAA;QACpB,KAAK,EAAE,UAAU,CAAA;QACjB,cAAc,EAAE,cAAc,CAAA;QAC9B,eAAe,EAAE,eAAe,CAAA;KACjC,CAAC;CAiBH;AAMD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,GAAG,gBAAgB,CAE1E"}