memorylink 1.0.0

package/IMPLEMENTATION_PLANS_DETAILED.md

@@ -0,0 +1,516 @@
+# 📋 Detailed Implementation Plans - MemoryLink v1.0.1 & v1.1
+
+**Source**: Mistral AI Comprehensive Analysis  
+**Status**: ✅ Ready for Implementation  
+**Date**: December 14, 2025
+
+---
+
+## 🎯 Priority 1: File Watcher + Auto-Injection (v1.0.1)
+
+### Goal
+Auto-detect file changes and inject context into AI tools **without manual intervention**.
+
+### Technical Specs
+- **Language**: Node.js
+- **Dependencies**: `chokidar`, `fs-extra`, `commander`
+- **Files to Create**: `src/watch.ts`, `src/inject.ts`
+- **Files to Modify**: `src/cli.ts`, `package.json`
+
+### Step-by-Step Implementation
+
+#### Step 1: Install Dependencies
+```bash
+npm install chokidar fs-extra --save
+```
+
+#### Step 2: Create File Watcher (`src/watch.ts`)
+```typescript
+import chokidar from 'chokidar';
+import fs from 'fs-extra';
+import path from 'path';
+import { updateAITools } from './inject';
+
+export function startWatching(projectDir: string) {
+  const watcher = chokidar.watch([
+    path.join(projectDir, '**/*.{js,ts,md,json}'),
+    '!.memorylink/**',
+    '!node_modules/**'
+  ], {
+    ignored: /(^|[\/\\])\../,
+    persistent: true,
+    ignoreInitial: true
+  });
+
+  watcher
+    .on('add', (filePath) => logChange('add', filePath))
+    .on('change', (filePath) => logChange('change', filePath))
+    .on('unlink', (filePath) => logChange('delete', filePath))
+    .on('error', (error) => console.error(`Watcher error: ${error}`));
+
+  console.log(`Watching ${projectDir} for changes...`);
+}
+
+function logChange(type: string, filePath: string) {
+  const memoryEntry = {
+    type: 'change',
+    action: type,
+    file: filePath,
+    timestamp: new Date().toISOString()
+  };
+  
+  fs.appendFileSync(
+    path.join('.memorylink', 'memory.log'),
+    JSON.stringify(memoryEntry) + '\n'
+  );
+  
+  updateAITools(filePath, type);
+}
+```
+
+#### Step 3: Create Auto-Injection (`src/inject.ts`)
+```typescript
+import fs from 'fs-extra';
+import path from 'path';
+
+export function updateAITools(filePath: string, action: string) {
+  const context = extractContext(filePath, action);
+  updateCursorRules(context);
+  updateClaudeInstructions(context);
+  updateRulesMD(context);
+}
+
+function extractContext(filePath: string, action: string): string {
+  const ext = path.extname(filePath);
+  return `[${action}] ${filePath}: Updated ${ext} file`;
+}
+
+function updateCursorRules(context: string) {
+  const cursorRulesPath = '.cursorrules';
+  let rules: any = {};
+  
+  if (fs.existsSync(cursorRulesPath)) {
+    try {
+      rules = fs.readJSONSync(cursorRulesPath);
+    } catch {
+      rules = {};
+    }
+  }
+  
+  rules.context = rules.context || [];
+  rules.context.unshift({
+    timestamp: new Date().toISOString(),
+    content: context,
+    priority: 'high'
+  });
+  
+  // Keep only last 50 entries
+  rules.context = rules.context.slice(0, 50);
+  
+  fs.writeJSONSync(cursorRulesPath, rules, { spaces: 2 });
+}
+
+function updateClaudeInstructions(context: string) {
+  const claudePath = 'CLAUDE_INSTRUCTIONS.md';
+  let content = '';
+  
+  if (fs.existsSync(claudePath)) {
+    content = fs.readFileSync(claudePath, 'utf-8');
+  }
+  
+  const newSection = `## Recent Changes\n- [${new Date().toISOString()}] ${context}\n\n`;
+  content = newSection + content;
+  
+  // Keep only last 100 lines
+  const lines = content.split('\n');
+  content = lines.slice(0, 100).join('\n');
+  
+  fs.writeFileSync(claudePath, content);
+}
+
+function updateRulesMD(context: string) {
+  const rulesPath = '.memorylink/rules.md';
+  let content = '';
+  
+  if (fs.existsSync(rulesPath)) {
+    content = fs.readFileSync(rulesPath, 'utf-8');
+  }
+  
+  const newSection = `### Recent Change\n${context}\n\n`;
+  content = newSection + content;
+  
+  fs.writeFileSync(rulesPath, content);
+}
+```
+
+#### Step 4: Add CLI Command
+```typescript
+// In src/cli.ts
+import { startWatching } from './watch';
+
+program
+  .command('watch')
+  .description('Watch project files for changes and auto-log')
+  .option('--ignore <patterns>', 'Ignore patterns (comma-separated)')
+  .action((opts) => {
+    startWatching(process.cwd());
+  });
+```
+
+#### Step 5: Testing
+```bash
+# Test file watcher
+memorylink watch
+
+# In another terminal, edit a file
+echo "test" >> test.js
+
+# Verify:
+# 1. Change logged in .memorylink/memory.log
+# 2. .cursorrules updated
+# 3. CLAUDE_INSTRUCTIONS.md updated
+```
+
+### Timeline
+- **File watcher setup**: 3 days
+- **Auto-injection logic**: 4 days
+- **CLI integration**: 1 day
+- **Testing**: 2 days
+- **Total**: 10 days
+
+---
+
+## 🎯 Priority 2: Vector Search (v1.1)
+
+### Goal
+Replace linear search with embedding-based semantic search for faster, more relevant results.
+
+### Technical Specs
+- **Language**: Node.js
+- **Dependencies**: `chroma-db`, `@tensorflow/tfjs-node`
+- **Files to Create**: `src/vector-search.ts`
+- **Files to Modify**: `src/search.ts`, `src/cli.ts`
+
+### Step-by-Step Implementation
+
+#### Step 1: Install Dependencies
+```bash
+npm install chroma-db @tensorflow/tfjs-node --save
+```
+
+#### Step 2: Create Vector Search Module
+```typescript
+// src/vector-search.ts
+import { ChromaClient } from 'chroma-db';
+import * as tf from '@tensorflow/tfjs-node';
+import fs from 'fs';
+import path from 'path';
+
+const client = new ChromaClient();
+let collection: any = null;
+
+export async function initializeVectorDB(projectDir: string) {
+  try {
+    collection = await client.getOrCreateCollection({ name: 'memories' });
+  } catch {
+    collection = await client.createCollection({ name: 'memories' });
+  }
+  
+  // Index existing memories
+  await indexMemories(projectDir);
+  return collection;
+}
+
+async function indexMemories(projectDir: string) {
+  const memoryLog = path.join(projectDir, '.memorylink', 'memory.log');
+  if (!fs.existsSync(memoryLog)) return;
+  
+  const memories = fs.readFileSync(memoryLog, 'utf-8')
+    .split('\n')
+    .filter(line => line.trim())
+    .map(line => JSON.parse(line));
+  
+  for (const memory of memories) {
+    const embedding = await generateEmbedding(memory.details || memory.content || '');
+    await collection.add({
+      ids: [memory.id || memory.timestamp],
+      embeddings: [embedding],
+      metadatas: [{ 
+        tags: memory.tags?.join(',') || '',
+        type: memory.type || 'note'
+      }],
+      documents: [memory.details || memory.content || '']
+    });
+  }
+}
+
+async function generateEmbedding(text: string): Promise<number[]> {
+  // Use Universal Sentence Encoder
+  const model = await tf.loadLayersModel(
+    'https://tfhub.dev/google/tfjs-model/universal-sentence-encoder/1/default/1'
+  );
+  const embedding = await model.predict(tf.tensor([text]));
+  return Array.from(embedding.dataSync());
+}
+
+export async function vectorSearch(query: string, limit: number = 10) {
+  if (!collection) {
+    throw new Error('Vector DB not initialized. Run: memorylink index --vector');
+  }
+  
+  const queryEmbedding = await generateEmbedding(query);
+  const results = await collection.query({
+    queryEmbeddings: [queryEmbedding],
+    nResults: limit
+  });
+  
+  return results;
+}
+```
+
+#### Step 3: Integrate with Search Command
+```typescript
+// In src/search.ts
+import { vectorSearch } from './vector-search';
+
+export async function searchMemories(query: string, options: SearchOptions) {
+  if (options.vector) {
+    return await vectorSearch(query, options.limit || 10);
+  } else {
+    // Fallback to existing linear search
+    return linearSearch(query, options);
+  }
+}
+```
+
+#### Step 4: Add Index Command
+```typescript
+// In src/cli.ts
+program
+  .command('index')
+  .description('Build vector index for semantic search')
+  .option('--vector', 'Use vector embeddings')
+  .action(async (opts) => {
+    if (opts.vector) {
+      await initializeVectorDB(process.cwd());
+      console.log('✅ Vector index built');
+    }
+  });
+```
+
+### Timeline
+- **Vector DB setup**: 3 days
+- **Embedding generation**: 2 days
+- **CLI integration**: 1 day
+- **Testing**: 2 days
+- **Total**: 8 days
+
+---
+
+## 🎯 Priority 3: MCP Server (v1.1)
+
+### Goal
+Push context to AI tools in real-time without manual intervention.
+
+### Technical Specs
+- **Language**: Node.js
+- **Dependencies**: `express`, `ws`, `fs-extra`
+- **Files to Create**: `src/server.ts`
+- **Files to Modify**: `src/cli.ts`
+
+### Step-by-Step Implementation
+
+#### Step 1: Install Dependencies
+```bash
+npm install express ws fs-extra --save
+```
+
+#### Step 2: Create MCP Server
+```typescript
+// src/server.ts
+import express from 'express';
+import WebSocket from 'ws';
+import fs from 'fs-extra';
+import path from 'path';
+
+const app = express();
+const PORT = 3000;
+const WS_PORT = 3001;
+
+app.use(express.json());
+
+// HTTP endpoint for AI tools to fetch context
+app.get('/context', (req, res) => {
+  const rulesPath = path.join('.memorylink', 'rules.md');
+  if (fs.existsSync(rulesPath)) {
+    const context = fs.readFileSync(rulesPath, 'utf-8');
+    res.json({ context });
+  } else {
+    res.json({ context: '' });
+  }
+});
+
+// WebSocket for real-time updates
+const wss = new WebSocket.Server({ port: WS_PORT });
+
+wss.on('connection', (ws) => {
+  console.log('AI tool connected');
+  
+  // Send initial context
+  const rulesPath = path.join('.memorylink', 'rules.md');
+  if (fs.existsSync(rulesPath)) {
+    const context = fs.readFileSync(rulesPath, 'utf-8');
+    ws.send(JSON.stringify({ type: 'context', data: context }));
+  }
+  
+  // Watch for changes
+  const watcher = fs.watch('.memorylink', (event, filename) => {
+    if (filename === 'rules.md') {
+      const context = fs.readFileSync(rulesPath, 'utf-8');
+      ws.send(JSON.stringify({ type: 'update', data: context }));
+    }
+  });
+  
+  ws.on('close', () => {
+    watcher.close();
+  });
+});
+
+app.listen(PORT, () => {
+  console.log(`MCP Server running on http://localhost:${PORT}`);
+  console.log(`WebSocket server running on ws://localhost:${WS_PORT}`);
+});
+```
+
+#### Step 3: Add Server Command
+```typescript
+// In src/cli.ts
+program
+  .command('server')
+  .description('Start MCP server for auto-injection')
+  .option('--port <number>', 'HTTP port', '3000')
+  .option('--ws-port <number>', 'WebSocket port', '3001')
+  .action((opts) => {
+    require('./server');
+  });
+```
+
+### Timeline
+- **MCP server setup**: 3 days
+- **WebSocket integration**: 2 days
+- **AI tool configuration**: 1 day
+- **Testing**: 2 days
+- **Total**: 8 days
+
+---
+
+## 🎯 Priority 4: Pagination & Streaming (v1.1)
+
+### Goal
+Handle 10K+ entries efficiently.
+
+### Technical Specs
+- **Language**: Node.js
+- **Dependencies**: None (built-in streams)
+- **Files to Modify**: `src/cli.ts`, `src/utils.ts`
+
+### Step-by-Step Implementation
+
+#### Step 1: Add Pagination
+```typescript
+// In src/cli.ts
+program
+  .command('get-context')
+  .option('--page <number>', 'Page number', parseInt)
+  .option('--per-page <number>', 'Results per page', parseInt)
+  .action((opts) => {
+    const page = opts.page || 1;
+    const perPage = opts.perPage || 10;
+    const memories = getMemories();
+    const total = memories.length;
+    const start = (page - 1) * perPage;
+    const end = start + perPage;
+    const paginated = memories.slice(start, end);
+    
+    console.log(`Page ${page} of ${Math.ceil(total / perPage)}`);
+    console.log(`Showing ${start + 1}-${Math.min(end, total)} of ${total}`);
+    console.log(paginated);
+  });
+```
+
+#### Step 2: Add Streaming
+```typescript
+// In src/utils.ts
+import { createReadStream } from 'fs';
+import { createInterface } from 'readline';
+
+export async function streamMemories(filePath: string, callback: (memory: any) => void) {
+  const fileStream = createReadStream(filePath);
+  const rl = createInterface({
+    input: fileStream,
+    crlfDelay: Infinity
+  });
+  
+  for await (const line of rl) {
+    if (line.trim()) {
+      try {
+        const memory = JSON.parse(line);
+        callback(memory);
+      } catch (e) {
+        // Skip invalid JSON
+      }
+    }
+  }
+}
+```
+
+#### Step 3: Add Stream Flag
+```typescript
+// In src/cli.ts
+program
+  .command('search')
+  .option('--stream', 'Stream results')
+  .action(async (opts) => {
+    if (opts.stream) {
+      await streamMemories('.memorylink/memory.log', (memory) => {
+        console.log(memory);
+      });
+    } else {
+      // Existing logic
+    }
+  });
+```
+
+### Timeline
+- **Pagination logic**: 1 day
+- **Streaming logic**: 1 day
+- **CLI integration**: 0.5 day
+- **Testing**: 0.5 day
+- **Total**: 3 days
+
+---
+
+## 📊 Implementation Summary
+
+| Feature                  | Version  | Timeline   | Priority | Status |
+|--------------------------|----------|------------|----------|--------|
+| File Watcher + Auto-Injection | v1.0.1   | 10 days    | Critical | Ready |
+| Vector Search            | v1.1     | 8 days     | High     | Ready |
+| MCP Server               | v1.1     | 8 days     | High     | Ready |
+| Pagination/Streaming     | v1.1     | 3 days     | Medium   | Ready |
+
+**Total v1.0.1 + v1.1**: 29 days (6 weeks)
+
+---
+
+## ✅ Validation Checklist
+
+- [x] All implementation plans detailed
+- [x] Code examples provided
+- [x] Dependencies listed
+- [x] Timeline estimated
+- [x] Testing approach defined
+- [x] Ready for development
+
+**Status**: ✅ **READY TO IMPLEMENT**
+