kodelyth-ecc 1.3.0 → 1.4.0

package/install.sh

@@ -47,7 +47,7 @@ echo -e "${RED}${BOLD}  ║   DANGER LEVEL: GOD TIER    ·    NOT FOR JUNIOR DEV
 echo -e "${RED}${BOLD}  ╚══════════════════════════════════════════════════════════════╝${RESET}"
 echo ""
 echo -e "${BOLD}  Kodelyth ECC — The most dangerous AI coding toolkit on the planet${RESET}"
-echo -e "${CYAN}  58 specialist agents  ·  187 skills  ·  79 commands  ·  18+ hooks  ·  god-tier intent routing${RESET}"
+echo -e "${CYAN}  59 specialist agents  ·  188 skills  ·  80 commands  ·  18+ hooks  ·  intent routing  ·  local memory${RESET}"
 echo -e "${CYAN}  Any language  ·  Any framework  ·  Any scale  ·  300B-level quality${RESET}"
 echo ""
 echo -e "  github.com/sifxprime/kodelyth-ecc"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kodelyth-ecc",
-  "version": "1.3.0",
-  "description": "Production-grade AI coding toolkit — 58 agents, 187 skills, 79 commands, god-tier intent routing. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
+  "version": "1.4.0",
+  "description": "Production-grade AI coding toolkit — 59 agents, 188 skills, 79 commands, god-tier intent routing, local self-learning memory. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",
   "repository": {
@@ -19,6 +19,8 @@
     "ai-agents",
     "coding-toolkit",
     "llm",
+    "memory",
+    "self-learning",
     "kodelyth"
   ],
   "bin": {

package/rules/common/memory-protocol.md

@@ -0,0 +1,56 @@
+# Kodelyth Memory Protocol
+
+> Auto-loaded every session. Tells the AI when to consult and contribute to local memory.
+
+## What is Kodelyth Memory
+
+A local file at `~/.kodelyth/memory/memories.jsonl` storing solutions, patterns, and gotchas extracted from past sessions. Retrieval is BM25 (keyword + tag matching). It is **not** a learned model — it is a retrieval store that gives you better context.
+
+If the SessionStart hook ran, you have already received a memory block in your initial context with:
+- The user's recurring patterns (tags seen across multiple sessions)
+- Recent solutions in this project
+- Their detected stack
+
+## When to recall memory mid-session
+
+Trigger a memory recall (run the `kodelyth-memory` agent or `node scripts/memory/cli.js search "<query>"`) when **any** of these is true:
+
+1. The user describes a task in a domain that matches a tag in their memory (`payments`, `auth`, `database`, `deployment`, etc.)
+2. The user asks "have I done this before?" or "how did I solve X last time?"
+3. The user mentions a library, framework, or service by name that appears in past memories
+4. You're about to commit to an architectural decision and want to check past precedent
+
+## How to surface a recalled memory
+
+Naturally, never robotically. Pattern:
+
+> I checked your memory — you solved a similar problem in `<project>` on `<date>`. The approach that worked was `<approach>`. Want me to apply the same here, or is this case different?
+
+Always end by giving the user the option to override. Memory is a hint, not a command.
+
+## When to capture a new memory
+
+Capture when **all** are true:
+- The user signals success (`"that worked"`, `"perfect"`, `"fixed it"`, `"thanks"`, `"done"`)
+- The work involved real iteration (not a one-shot trivial fix)
+- The lesson is reusable (would help in another similar problem, not just this exact file)
+
+Show the user the draft memory before storing. Never silently capture.
+
+## What you must not do
+
+- **Never** auto-recall the same memory twice in one session (the user has seen it)
+- **Never** capture without explicit confirmation (`yes`, `store it`, `remember`)
+- **Never** treat a recalled memory as ground truth — it could be stale
+- **Never** transmit memory data anywhere — it is local-only by design
+- **Never** fabricate a memory ("you usually...") if no relevant memory exists — say nothing
+
+## Cache-aware behaviour
+
+The injected memory block is structured so its prefix is identical across calls in the same project. Do not rewrite or reorder this block during a session — that defeats the prompt cache and burns tokens. If you need to add session-specific notes, append them after the block.
+
+## Honest disclosure
+
+If the user asks "how do you know that about me?", answer plainly:
+
+> "It's in your local Kodelyth Memory at `~/.kodelyth/memory/`. You can inspect it, edit it, or delete it any time. Nothing was sent anywhere."

package/scripts/memory/cli.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kodelyth ECC — Memory CLI
+//
+// Usage:
+//   node scripts/memory/cli.js list
+//   node scripts/memory/cli.js search "<query>"
+//   node scripts/memory/cli.js remember "<title>" --approach "<text>" --tags tag1,tag2
+//   node scripts/memory/cli.js forget <id>
+//   node scripts/memory/cli.js stats
+//   node scripts/memory/cli.js inject [--query "<text>"]
+//   node scripts/memory/cli.js extract <session.jsonl>
+//   node scripts/memory/cli.js rebuild-index
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+const store   = require('./store');
+const { buildContextBlock } = require('./inject');
+const { extractCandidates } = require('./extract');
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const cmd  = args[0];
+  const positional = [];
+  const flags = {};
+  for (let i = 1; i < args.length; i++) {
+    const a = args[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = args[i + 1];
+      if (!next || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = next;
+        i += 1;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { cmd, positional, flags };
+}
+
+function help() {
+  console.log(`
+Kodelyth ECC — Memory CLI
+
+Commands:
+  list                              Show all stored memories
+  search "<query>"                  BM25 search across memories
+  remember "<title>"                Add a memory (use --approach, --tags, --language)
+  forget <id>                       Mark a memory deleted
+  stats                             Show memory store stats
+  inject [--query "<text>"]         Print the cache-friendly context block
+  extract <session.jsonl>           Extract memory candidates from a session log
+  rebuild-index                     Rebuild the BM25 index from memories.jsonl
+
+Storage: ${store.PATHS.dir}
+`);
+}
+
+function fmt(memory, full = false) {
+  const date = (memory.captured_at || '').slice(0, 10);
+  const tags = (memory.tags || []).join(',');
+  if (!full) {
+    return `${memory.id}  ${date}  [${memory.language || '-'}]  ${memory.problem.slice(0, 70)}  (${tags})`;
+  }
+  return [
+    `id:        ${memory.id}`,
+    `captured:  ${memory.captured_at}`,
+    `language:  ${memory.language || '-'}`,
+    `tags:      ${tags || '-'}`,
+    `project:   ${memory.project_path || '-'}`,
+    `problem:   ${memory.problem}`,
+    `approach:`,
+    ...(memory.approach || '').split('\n').map(l => `  ${l}`),
+    memory.gotchas?.length ? `gotchas:` : '',
+    ...(memory.gotchas || []).map(g => `  - ${g}`),
+  ].filter(Boolean).join('\n');
+}
+
+function main() {
+  const { cmd, positional, flags } = parseArgs(process.argv);
+
+  if (!cmd || cmd === 'help' || cmd === '-h' || cmd === '--help') {
+    help();
+    return;
+  }
+
+  switch (cmd) {
+    case 'list': {
+      const all = store.listAll();
+      if (all.length === 0) {
+        console.log('No memories yet. Add one with: memory remember "<title>" --approach "<text>"');
+        return;
+      }
+      for (const m of all) console.log(fmt(m));
+      console.log(`\n${all.length} total`);
+      return;
+    }
+
+    case 'search': {
+      const query = positional[0];
+      if (!query) { console.error('Usage: search "<query>"'); process.exit(1); }
+      const results = store.recall(query, { limit: Number(flags.limit) || 5 });
+      if (results.length === 0) { console.log('No matches.'); return; }
+      for (const m of results) {
+        console.log(`[score ${m.score.toFixed(2)}] ${fmt(m)}`);
+      }
+      return;
+    }
+
+    case 'remember': {
+      const title    = positional[0];
+      const approach = flags.approach;
+      if (!title || !approach) {
+        console.error('Usage: remember "<title>" --approach "<what worked>" [--tags a,b] [--language ts]');
+        process.exit(1);
+      }
+      const memory = store.capture({
+        problem:  title,
+        approach,
+        tags:     (flags.tags || '').split(',').filter(Boolean),
+        project:  flags.project || process.cwd(),
+        language: flags.language || null,
+        files:    (flags.files || '').split(',').filter(Boolean),
+        gotchas:  (flags.gotchas || '').split(';').filter(Boolean),
+        source:   'cli',
+      });
+      console.log(`Captured: ${memory.id}`);
+      return;
+    }
+
+    case 'forget': {
+      const id = positional[0];
+      if (!id) { console.error('Usage: forget <id>'); process.exit(1); }
+      const ok = store.forget(id);
+      console.log(ok ? `Forgotten: ${id}` : `Not found: ${id}`);
+      return;
+    }
+
+    case 'stats': {
+      const s = store.stats();
+      console.log(`Total memories:  ${s.total}`);
+      console.log(`Storage:         ${s.storageDir}`);
+      console.log(`Projects:        ${s.projects}`);
+      console.log(`By language:`);
+      for (const [lang, count] of Object.entries(s.byLanguage)) {
+        console.log(`  ${lang.padEnd(12)} ${count}`);
+      }
+      console.log(`Top tags:`);
+      for (const [tag, count] of s.topTags) {
+        console.log(`  ${tag.padEnd(20)} ${count}`);
+      }
+      return;
+    }
+
+    case 'inject': {
+      const block = buildContextBlock({
+        projectRoot: flags.project || process.cwd(),
+        query:       flags.query || null,
+      });
+      if (!block) { console.log(''); return; }
+      console.log(block.text);
+      return;
+    }
+
+    case 'extract': {
+      const sessionPath = positional[0];
+      if (!sessionPath) { console.error('Usage: extract <session.jsonl>'); process.exit(1); }
+      const candidates = extractCandidates(path.resolve(sessionPath));
+      if (candidates.length === 0) { console.log('No memory candidates found.'); return; }
+      console.log(`Found ${candidates.length} candidate memories:\n`);
+      candidates.forEach((c, i) => {
+        console.log(`[${i + 1}] (score ${c.score})  ${c.problem}`);
+        console.log(`    tags:     ${c.tags.join(', ') || '-'}`);
+        console.log(`    language: ${c.language || '-'}`);
+        console.log(`    approach: ${c.approach.slice(0, 200)}...`);
+        console.log('');
+      });
+      console.log('Review and confirm with: memory remember "<problem>" --approach "<approach>"');
+      return;
+    }
+
+    case 'rebuild-index': {
+      const r = store.rebuildIndex();
+      console.log(`Rebuilt index for ${r.count} memories.`);
+      return;
+    }
+
+    default:
+      console.error(`Unknown command: ${cmd}`);
+      help();
+      process.exit(1);
+  }
+}
+
+main();

package/scripts/memory/extract.js

@@ -0,0 +1,176 @@
+// =============================================================================
+// Kodelyth ECC — Session Learning Extractor
+// Reads a session transcript (JSONL) and extracts capture-worthy memories.
+//
+// Strategy: heuristic scoring, no LLM call. We look for signals that a real
+// problem was solved:
+//   1. Edit/Write tool followed by a passing test or successful build
+//   2. User saying "that worked", "fixed it", "great", "thanks"
+//   3. Same file edited 3+ times in one session (iteration → solution)
+//   4. Long Bash output ending in exit code 0 after several failures
+//
+// Each candidate becomes a draft memory. The user (or the AI) reviews and
+// confirms via /memory review. Nothing is auto-stored without confirmation —
+// silent capture is how memory systems become noisy and useless.
+// =============================================================================
+
+'use strict';
+
+const fs = require('fs');
+
+const SUCCESS_PHRASES = [
+  /\bthat worked\b/i,
+  /\bfixed it\b/i,
+  /\bperfect\b/i,
+  /\bnice\b.*\bworks\b/i,
+  /\bthanks\b/i,
+  /\bgreat\b/i,
+  /\bsolved\b/i,
+  /\bdone\b/i,
+];
+
+const FAILURE_PHRASES = [
+  /\bstill broken\b/i,
+  /\bdoesn'?t work\b/i,
+  /\bnope\b/i,
+  /\bsame error\b/i,
+];
+
+function readTranscript(jsonlPath) {
+  if (!fs.existsSync(jsonlPath)) return [];
+  const lines = fs.readFileSync(jsonlPath, 'utf8').split('\n').filter(Boolean);
+  const events = [];
+  for (const line of lines) {
+    try { events.push(JSON.parse(line)); } catch { /* skip malformed */ }
+  }
+  return events;
+}
+
+function extractText(event) {
+  if (typeof event.content === 'string') return event.content;
+  if (Array.isArray(event.content)) {
+    return event.content
+      .filter(c => c && (c.type === 'text' || typeof c.text === 'string'))
+      .map(c => c.text || '')
+      .join('\n');
+  }
+  if (event.message?.content) return extractText({ content: event.message.content });
+  return '';
+}
+
+function detectLanguage(filesTouched) {
+  const exts = filesTouched.map(f => (f.match(/\.[a-z0-9]+$/i) || [''])[0].toLowerCase());
+  if (exts.includes('.ts') || exts.includes('.tsx')) return 'typescript';
+  if (exts.includes('.js') || exts.includes('.jsx')) return 'javascript';
+  if (exts.includes('.py'))   return 'python';
+  if (exts.includes('.go'))   return 'golang';
+  if (exts.includes('.rs'))   return 'rust';
+  if (exts.includes('.java')) return 'java';
+  if (exts.includes('.kt'))   return 'kotlin';
+  if (exts.includes('.swift')) return 'swift';
+  if (exts.includes('.rb'))   return 'ruby';
+  if (exts.includes('.php'))  return 'php';
+  return null;
+}
+
+function extractTags(text) {
+  const tags = new Set();
+  const taxonomy = {
+    'api-integration':  /\b(api|endpoint|rest|graphql|grpc|webhook)\b/i,
+    'authentication':   /\b(auth|jwt|oauth|sso|login|session|token)\b/i,
+    'database':         /\b(sql|postgres|mysql|mongo|redis|orm|migration|query)\b/i,
+    'testing':          /\b(test|jest|vitest|pytest|playwright|cypress|coverage)\b/i,
+    'deployment':       /\b(deploy|vercel|netlify|aws|docker|kubernetes|ci|cd)\b/i,
+    'performance':      /\b(slow|optimize|perf|cache|n\+1|memory leak)\b/i,
+    'security':         /\b(secure|xss|csrf|injection|vuln|sanitiz)\b/i,
+    'state-management': /\b(redux|zustand|context|signal|state|store)\b/i,
+    'styling':          /\b(css|tailwind|styled|theme|responsive)\b/i,
+    'routing':          /\b(router|navigation|route|next-router|react-router)\b/i,
+    'forms':            /\b(form|validation|zod|yup|formik|hook-form)\b/i,
+    'streaming':        /\b(stream|sse|websocket|realtime)\b/i,
+    'payments':         /\b(stripe|paypal|payment|checkout|billing|subscription)\b/i,
+    'ai-llm':           /\b(openai|anthropic|llm|gpt|claude|gemini|prompt)\b/i,
+  };
+  for (const [tag, pattern] of Object.entries(taxonomy)) {
+    if (pattern.test(text)) tags.add(tag);
+  }
+  return Array.from(tags);
+}
+
+function scoreCandidate(events, candidateIdx) {
+  let score = 0;
+  const around = events.slice(Math.max(0, candidateIdx - 5), candidateIdx + 5);
+
+  for (const ev of around) {
+    const text = extractText(ev);
+    if (ev.role === 'user' && SUCCESS_PHRASES.some(rx => rx.test(text))) score += 3;
+    if (ev.role === 'user' && FAILURE_PHRASES.some(rx => rx.test(text))) score -= 2;
+    if (ev.tool_name === 'Bash' && /exit code 0|tests passed|all passed/i.test(text)) score += 2;
+    if (ev.tool_name === 'Edit' || ev.tool_name === 'Write') score += 1;
+  }
+  return score;
+}
+
+function extractCandidates(jsonlPath) {
+  const events = readTranscript(jsonlPath);
+  if (events.length < 4) return [];
+
+  const editsByFile = {};
+  const candidates  = [];
+
+  for (let i = 0; i < events.length; i++) {
+    const ev = events[i];
+    const filePath = ev.tool_input?.file_path || ev.tool_input?.path;
+    if ((ev.tool_name === 'Edit' || ev.tool_name === 'Write') && filePath) {
+      editsByFile[filePath] = (editsByFile[filePath] || 0) + 1;
+    }
+  }
+
+  // Find user success messages — those mark candidate moments
+  for (let i = 0; i < events.length; i++) {
+    const ev = events[i];
+    if (ev.role !== 'user') continue;
+    const text = extractText(ev);
+    if (!SUCCESS_PHRASES.some(rx => rx.test(text))) continue;
+
+    const score = scoreCandidate(events, i);
+    if (score < 3) continue;
+
+    // Look back to find the problem and approach
+    const window = events.slice(Math.max(0, i - 20), i);
+    const problemEvent = window.find(e => e.role === 'user');
+    const problem = problemEvent ? extractText(problemEvent).split('\n')[0].slice(0, 280) : null;
+
+    const filesTouched = Array.from(new Set(
+      window
+        .filter(e => e.tool_name === 'Edit' || e.tool_name === 'Write')
+        .map(e => e.tool_input?.file_path || e.tool_input?.path)
+        .filter(Boolean)
+    )).slice(0, 5);
+
+    const lastAssistant = window.reverse().find(e => e.role === 'assistant');
+    const approach = lastAssistant ? extractText(lastAssistant).slice(0, 600) : null;
+
+    if (!problem || !approach) continue;
+
+    candidates.push({
+      problem,
+      approach,
+      tags: extractTags(`${problem} ${approach}`),
+      files: filesTouched,
+      language: detectLanguage(filesTouched),
+      score,
+    });
+  }
+
+  // Dedupe by problem
+  const seen = new Set();
+  return candidates.filter(c => {
+    const key = c.problem.toLowerCase().slice(0, 60);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+module.exports = { extractCandidates };

package/scripts/memory/inject.js

@@ -0,0 +1,145 @@
+// =============================================================================
+// Kodelyth ECC — Memory Injection
+// Builds a cache-friendly context block from relevant past memories.
+//
+// Output is structured into a STABLE prefix (first 80% of the block) and a
+// VARIABLE suffix (current-session triggers). The stable prefix is identical
+// across calls in the same project, which lets prompt-cache-aware models
+// (Anthropic, OpenAI) hit cache and charge ~10% on the cached tokens.
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+const fs   = require('fs');
+const { recallForProject, listAll, projectHash } = require('./store');
+
+const MAX_PATTERNS = 8;
+const MAX_RECENT   = 5;
+const MAX_RELEVANT = 5;
+
+function loadProjectContextSignals(projectRoot) {
+  const signals = [];
+
+  // package.json — language + framework
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+      const frameworks = ['next','react','vue','svelte','nuxt','express','fastify','nest'];
+      for (const fw of frameworks) {
+        if (deps[fw]) signals.push(fw);
+      }
+      if (deps.typescript) signals.push('typescript');
+    } catch {}
+  }
+
+  // pyproject / requirements
+  if (fs.existsSync(path.join(projectRoot, 'pyproject.toml'))) signals.push('python');
+  if (fs.existsSync(path.join(projectRoot, 'go.mod')))         signals.push('golang');
+  if (fs.existsSync(path.join(projectRoot, 'Cargo.toml')))     signals.push('rust');
+
+  return signals;
+}
+
+function summarisePatterns(memories) {
+  // Patterns = recurring tags across the user's memory corpus
+  const tagCounts = {};
+  for (const m of memories) {
+    for (const tag of m.tags || []) tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+  }
+  return Object.entries(tagCounts)
+    .filter(([, count]) => count >= 2)
+    .sort(([, a], [, b]) => b - a)
+    .slice(0, MAX_PATTERNS);
+}
+
+function recentMemories(memories, limit = MAX_RECENT) {
+  return memories
+    .slice()
+    .sort((a, b) => new Date(b.captured_at) - new Date(a.captured_at))
+    .slice(0, limit);
+}
+
+function formatMemory(m) {
+  const lines = [`- **${m.problem}**`];
+  if (m.approach) lines.push(`  Approach: ${m.approach.split('\n')[0].slice(0, 240)}`);
+  if (m.gotchas && m.gotchas.length) lines.push(`  Gotcha: ${m.gotchas[0].slice(0, 200)}`);
+  if (m.tags && m.tags.length) lines.push(`  Tags: ${m.tags.slice(0, 5).join(', ')}`);
+  return lines.join('\n');
+}
+
+function buildContextBlock({
+  projectRoot = process.cwd(),
+  query       = null,
+  modelHint   = 'auto',
+} = {}) {
+  const allMemories = listAll();
+  if (allMemories.length === 0) {
+    return null; // No memory yet — first-time user
+  }
+
+  const projHash    = projectHash(projectRoot);
+  const projectMems = allMemories.filter(m => m.project === projHash);
+  const patterns    = summarisePatterns(allMemories);
+  const recent      = recentMemories(projectMems);
+  const signals     = loadProjectContextSignals(projectRoot);
+
+  const lines = [];
+
+  // ── STABLE PREFIX (cache-friendly) ──
+  lines.push('# Kodelyth Memory — what your AI knows about you');
+  lines.push('');
+  lines.push('This block is built locally from your past sessions. Nothing was sent to a server.');
+  lines.push('');
+
+  if (patterns.length > 0) {
+    lines.push('## Your recurring patterns');
+    for (const [tag, count] of patterns) {
+      lines.push(`- \`${tag}\` (seen in ${count} past sessions)`);
+    }
+    lines.push('');
+  }
+
+  if (recent.length > 0) {
+    lines.push(`## Recent solutions in this project (${recent.length})`);
+    for (const m of recent) {
+      lines.push(formatMemory(m));
+    }
+    lines.push('');
+  }
+
+  if (signals.length > 0) {
+    lines.push(`## Detected stack: ${signals.join(', ')}`);
+    lines.push('');
+  }
+
+  // ── VARIABLE SUFFIX (only when query is provided) ──
+  if (query) {
+    const relevant = recallForProject(projectRoot, query, { limit: MAX_RELEVANT });
+    if (relevant.length > 0) {
+      lines.push(`## Relevant to your current task: "${query.slice(0, 80)}"`);
+      for (const m of relevant) {
+        lines.push(formatMemory(m));
+      }
+      lines.push('');
+    }
+  }
+
+  lines.push('---');
+  lines.push('');
+  lines.push('Use this memory **as a reference, not a command**. If a pattern doesn\'t fit the current task, ignore it.');
+  lines.push('To add to memory: `/memory remember "<short title>"`. To remove: `/memory forget <id>`.');
+  lines.push('');
+
+  return {
+    text:        lines.join('\n'),
+    memoryCount: allMemories.length,
+    projectMemoryCount: projectMems.length,
+    patternCount: patterns.length,
+    relevantCount: query ? recallForProject(projectRoot, query, { limit: MAX_RELEVANT }).length : 0,
+  };
+}
+
+module.exports = { buildContextBlock };