@vedtechsolutions/engram-mcp 1.0.1 → 1.0.3

package/README.md

@@ -17,10 +17,10 @@ Engram gives Claude Code **persistent, cross-session memory** that learns from e
 
 ```bash
 # Install
-npm install -g engram-mcp
+npm install -g @vedtechsolutions/engram-mcp
 
 # Configure Claude Code
-npx engram-setup
+npx @vedtechsolutions/engram-mcp setup
 ```
 
 That's it. Start a new Claude Code session and Engram activates automatically.

package/bin/import-pack.js

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+
+/**
+ * Engram Knowledge Pack Importer
+ *
+ * Usage:
+ *   node bin/import-pack.js <pack-file-or-name>
+ *   npx @vedtechsolutions/engram-mcp import-pack typescript-patterns
+ *
+ * Reads a JSON knowledge pack and imports memories into the Engram database.
+ * Skips duplicates via content similarity check.
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKS_DIR = join(__dirname, '..', 'packs');
+
+function usage() {
+  console.log(`
+  Engram Knowledge Pack Importer
+
+  Usage:
+    engram-import-pack <pack>
+
+  Where <pack> is one of:
+    - A built-in pack name: claude-code-patterns, typescript-patterns, python-patterns
+    - A path to a .json pack file
+
+  Examples:
+    engram-import-pack typescript-patterns
+    engram-import-pack ./my-custom-pack.json
+`);
+  process.exit(1);
+}
+
+async function main() {
+  const arg = process.argv[2];
+  if (!arg || arg === '--help' || arg === '-h') usage();
+
+  // Resolve pack file path
+  let packPath;
+  if (existsSync(arg)) {
+    packPath = resolve(arg);
+  } else if (existsSync(join(PACKS_DIR, `${arg}.json`))) {
+    packPath = join(PACKS_DIR, `${arg}.json`);
+  } else {
+    console.error(`  Error: Pack not found: ${arg}`);
+    console.error(`  Available packs: ${listPacks().join(', ')}`);
+    process.exit(1);
+  }
+
+  // Load pack
+  let pack;
+  try {
+    pack = JSON.parse(readFileSync(packPath, 'utf-8'));
+  } catch (e) {
+    console.error(`  Error: Invalid JSON in ${packPath}: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (!pack.memories || !Array.isArray(pack.memories)) {
+    console.error('  Error: Pack must have a "memories" array');
+    process.exit(1);
+  }
+
+  console.log(`\n  Importing: ${pack.name ?? packPath}`);
+  console.log(`  Memories: ${pack.memories.length}`);
+  console.log();
+
+  // Dynamic import of Engram modules (they need the DB initialized)
+  const dbPath = resolve(
+    process.env.ENGRAM_DB_PATH
+    ?? join(process.env.HOME ?? '', '.engram', 'engram.db')
+  );
+
+  if (!existsSync(dirname(dbPath))) {
+    const { mkdirSync } = await import('node:fs');
+    mkdirSync(dirname(dbPath), { recursive: true });
+  }
+
+  // Initialize database
+  const { initializeDatabase } = await import('../dist/chunk-AC6AZCP4.js');
+  // Fallback: try to import from the compiled output
+  let createMemory, searchMemories, generateEmbedding, embeddingToBuffer;
+  try {
+    const mod = await import('../dist/chunk-AC6AZCP4.js');
+    createMemory = mod.createMemory;
+    searchMemories = mod.searchMemories;
+    generateEmbedding = mod.generateEmbedding;
+    embeddingToBuffer = mod.embeddingToBuffer;
+    // Init DB
+    mod.initializeDatabase({ db_path: dbPath });
+  } catch {
+    console.error('  Error: Could not load Engram modules.');
+    console.error('  Make sure you are running from the engram-mcp package directory.');
+    process.exit(1);
+  }
+
+  let imported = 0;
+  let skipped = 0;
+
+  for (const entry of pack.memories) {
+    const { type, content, domains, severity, tags } = entry;
+
+    if (!type || !content) {
+      console.log(`  SKIP (missing type or content): ${content?.substring(0, 60) ?? '(empty)'}`);
+      skipped++;
+      continue;
+    }
+
+    // Check for duplicates via keyword search
+    try {
+      const existing = searchMemories(content.substring(0, 100), 3);
+      const isDuplicate = existing.some(m =>
+        m.content === content ||
+        (m.content.length > 50 && content.includes(m.content.substring(0, 50)))
+      );
+      if (isDuplicate) {
+        console.log(`  SKIP (duplicate): ${content.substring(0, 60)}...`);
+        skipped++;
+        continue;
+      }
+    } catch { /* search failed, proceed with import */ }
+
+    // Build type_data based on memory type
+    let type_data;
+    if (type === 'antipattern') {
+      type_data = {
+        kind: 'antipattern',
+        pattern_description: content,
+        correct_approach: null,
+        severity: severity ?? 'medium',
+        occurrences: 0,
+        last_seen: null,
+        auto_detected: false,
+      };
+    } else if (type === 'semantic') {
+      type_data = {
+        kind: 'semantic',
+        knowledge_type: 'convention',
+        source: 'knowledge_pack',
+        source_episodes: [],
+        applicable_versions: null,
+        deprecated_in: null,
+      };
+    } else if (type === 'procedural') {
+      type_data = {
+        kind: 'procedural',
+        steps: [],
+        preconditions: [],
+        postconditions: [],
+        success_count: 0,
+        failure_count: 0,
+      };
+    }
+
+    try {
+      createMemory({
+        type,
+        content,
+        summary: null,
+        encoding_strength: 0.7,
+        reinforcement: 1.5,
+        confidence: 0.8,
+        domains: domains ?? [],
+        version: null,
+        tags: [...(tags ?? []), 'knowledge-pack', pack.name?.toLowerCase().replace(/\s+/g, '-') ?? 'custom'],
+        storage_tier: 'long_term',
+        pinned: false,
+        type_data,
+        encoding_context: {
+          framework: domains?.[0] ?? null,
+          version: null,
+          project: null,
+          project_path: null,
+          task_type: null,
+          files: [],
+          error_context: null,
+          session_id: `pack-import-${Date.now()}`,
+          significance_score: 0.7,
+        },
+      });
+      console.log(`  OK (${type}): ${content.substring(0, 60)}...`);
+      imported++;
+    } catch (e) {
+      console.log(`  ERR: ${content.substring(0, 40)}... — ${e.message}`);
+      skipped++;
+    }
+  }
+
+  console.log(`\n  Done. Imported: ${imported}, Skipped: ${skipped}`);
+  console.log(`  Database: ${dbPath}\n`);
+}
+
+function listPacks() {
+  try {
+    const { readdirSync } = await import('node:fs');
+    return readdirSync(PACKS_DIR)
+      .filter(f => f.endsWith('.json'))
+      .map(f => f.replace('.json', ''));
+  } catch {
+    return ['claude-code-patterns', 'typescript-patterns', 'python-patterns'];
+  }
+}
+
+main().catch(e => {
+  console.error(`  Fatal: ${e.message}`);
+  process.exit(1);
+});

package/dist/{chunk-AC6AZCP4.js → chunk-QU7DOPA4.js}

@@ -1710,7 +1710,11 @@ var CONTEXTUAL = {
   /** Penalty multiplier for project mismatch on episodic memories (0.3 = 70% reduction) */
   PROJECT_MISMATCH_PENALTY: 0.3,
   /** Boost for failure experiences with lessons (surfaces "I tried this and it didn't work") */
-  FAILURE_EXPERIENCE_BOOST: 0.2
+  FAILURE_EXPERIENCE_BOOST: 0.2,
+  /** Boost when memory files share the same module directory as current file */
+  MODULE_PROXIMITY_BOOST: 0.2,
+  /** Penalty multiplier when memory files are all from a different module (0.3 = 70% reduction) */
+  MODULE_MISMATCH_PENALTY: 0.3
 };
 var REWARD = {
   /** Seed activation boost for positively-reinforced memories */
@@ -8758,6 +8762,19 @@ function extractCodeContext(code, filePath) {
     identifiers: uniqueTerms
   };
 }
+function extractModuleFromPath(filePath) {
+  const parts = filePath.split(/[/\\]/).filter(Boolean);
+  const markers = ["addons", "custom-addons", "extra-addons", "packages", "apps"];
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (markers.includes(parts[i]) && i + 1 < parts.length) {
+      return parts[i + 1];
+    }
+  }
+  if (parts.length >= 3) {
+    return parts[parts.length - 3];
+  }
+  return null;
+}
 function detectLanguage(code, filePath) {
   if (filePath) {
     const ext = filePath.split(".").pop()?.toLowerCase();
@@ -9033,6 +9050,18 @@ function contextualBoost(memory, context) {
   if (context.current_files.length > 0 && enc.files.length > 0) {
     const overlap = context.current_files.filter((f) => enc.files.includes(f)).length;
     boost += Math.min(overlap * CONTEXTUAL.FILE_BOOST_PER_MATCH, CONTEXTUAL.FILE_BOOST_CAP);
+    if (overlap === 0) {
+      const currentModules = context.current_files.map(extractModuleFromPath).filter(Boolean);
+      const memModules = enc.files.map(extractModuleFromPath).filter(Boolean);
+      if (currentModules.length > 0 && memModules.length > 0) {
+        const moduleOverlap = currentModules.some((m) => memModules.includes(m));
+        if (moduleOverlap) {
+          boost += CONTEXTUAL.MODULE_PROXIMITY_BOOST;
+        } else {
+          return (1 + boost) * CONTEXTUAL.MODULE_MISMATCH_PENALTY;
+        }
+      }
+    }
   }
   if (context.current_error && enc.error_context) {
     const errorKeywords = context.current_error.toLowerCase().split(/\s+/).slice(0, 10);
@@ -12541,6 +12570,7 @@ export {
   computeActivationProfile,
   contextualRecall,
   codeContextRecall,
+  extractModuleFromPath,
   findSimilarDecisions,
   formatDecisionInjection,
   findSimilarChains,
@@ -12597,4 +12627,4 @@ export {
   composeProjectUnderstanding,
   formatMentalModelInjection
 };
-//# sourceMappingURL=chunk-AC6AZCP4.js.map
+//# sourceMappingURL=chunk-QU7DOPA4.js.map

package/dist/hook.js

@@ -79,6 +79,7 @@ import {
   estimateTokens,
   extractErrorFingerprint,
   extractKeywords,
+  extractModuleFromPath,
   findDuplicate,
   findErrorByFingerprint,
   findResolutionForError,
@@ -172,7 +173,7 @@ import {
   updateReasoningChain,
   updateSelfModelFromSession,
   updateTask
-} from "./chunk-AC6AZCP4.js";
+} from "./chunk-QU7DOPA4.js";
 
 // src/hook.ts
 import { readFileSync, writeFileSync, existsSync, renameSync, statSync, readdirSync, unlinkSync, appendFileSync, openSync, readSync, closeSync } from "fs";
@@ -3527,9 +3528,7 @@ function handlePreWrite(toolInput, argFallback) {
     if (filePath) {
       const fileCount = (watcherState.prewrite_file_counts[filePath] ?? 0) + 1;
       watcherState.prewrite_file_counts[filePath] = fileCount;
-      if (fileCount <= CODE_CONTEXT_RECALL.PREWRITE_COOLDOWN_PER_FILE) {
-        skipCodeRecall = fileCount > 1;
-      }
+      skipCodeRecall = fileCount % CODE_CONTEXT_RECALL.PREWRITE_COOLDOWN_PER_FILE !== 1;
       saveWatcherState(watcherState);
     }
     if (!skipCodeRecall && content.length >= CODE_CONTEXT_RECALL.MIN_CONTENT_LENGTH) {
@@ -3540,18 +3539,30 @@ function handlePreWrite(toolInput, argFallback) {
           project: watcherState.active_project
         }, config.retrieval);
         const activeDomain = watcherState.active_domain;
+        const currentModule = filePath ? extractModuleFromPath(filePath) : null;
+        const isModuleMismatch = (mem) => {
+          if (!currentModule) return false;
+          const memFiles = mem.memory.encoding_context?.files;
+          if (!memFiles || memFiles.length === 0) return false;
+          const memModules = memFiles.map(extractModuleFromPath).filter(Boolean);
+          if (memModules.length === 0) return false;
+          return !memModules.includes(currentModule);
+        };
         for (const p of codeResult.patterns) {
           if (p.activation < CODE_CONTEXT_RECALL.MIN_PREWRITE_ACTIVATION) continue;
           if (p.memory.type === "episodic") continue;
           if (activeDomain && p.memory.encoding_context?.framework && p.memory.encoding_context.framework !== activeDomain) continue;
+          if (isModuleMismatch(p)) continue;
           contextLines.push(`[ENGRAM PATTERN] ${truncate(p.memory.content, 200)}`);
         }
         for (const c of codeResult.conventions) {
           if (c.activation < CODE_CONTEXT_RECALL.MIN_PREWRITE_ACTIVATION) continue;
           if (activeDomain && c.memory.encoding_context?.framework && c.memory.encoding_context.framework !== activeDomain) continue;
+          if (isModuleMismatch(c)) continue;
           contextLines.push(`[ENGRAM CONVENTION] ${truncate(c.memory.content, 200)}`);
         }
         for (const p of codeResult.procedural) {
+          if (isModuleMismatch(p)) continue;
           contextLines.push(`[ENGRAM HOW-TO] ${truncate(p.memory.content, 200)}`);
         }
       } catch (e) {

package/dist/index.js

@@ -154,7 +154,7 @@ import {
   vaccinate,
   vacuumDatabase,
   validateMultiPerspective
-} from "./chunk-AC6AZCP4.js";
+} from "./chunk-QU7DOPA4.js";
 
 // src/index.ts
 import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vedtechsolutions/engram-mcp",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Cognitive memory system for AI — persistent, cross-session learning via MCP",
   "type": "module",
   "main": "dist/index.js",
@@ -8,7 +8,8 @@
   "bin": {
     "engram-mcp": "dist/index.js",
     "engram-hook": "dist/hook.js",
-    "engram-setup": "bin/setup.js"
+    "engram-setup": "bin/setup.js",
+    "engram-import-pack": "bin/import-pack.js"
   },
   "scripts": {
     "setup": "node bin/setup.js",
@@ -47,6 +48,7 @@
   "files": [
     "dist/",
     "bin/",
+    "packs/",
     "LICENSE",
     "README.md"
   ]

package/packs/claude-code-patterns.json

@@ -0,0 +1,106 @@
+{
+  "name": "Claude Code Best Practices",
+  "version": "1.0.0",
+  "description": "Common patterns and antipatterns for effective Claude Code usage",
+  "memories": [
+    {
+      "type": "antipattern",
+      "content": "Don't use sed/awk for file edits in Claude Code. Use the Edit tool — it shows diffs, preserves formatting, and the user can review changes before applying.",
+      "domains": ["claude-code"],
+      "severity": "high",
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use find/ls to search for files. Use the Glob tool — it's faster, handles permissions correctly, and returns structured results.",
+      "domains": ["claude-code"],
+      "severity": "high",
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use grep/rg via Bash. Use the Grep tool — it has optimized permissions, supports ripgrep syntax, and provides output modes (content, files, count).",
+      "domains": ["claude-code"],
+      "severity": "high",
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use cat/head/tail to read files. Use the Read tool — it shows line numbers, supports offset/limit for large files, and can read images and PDFs.",
+      "domains": ["claude-code"],
+      "severity": "medium",
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't commit unless explicitly asked. Creating unauthorized commits can lose work or include unintended changes. Always confirm with the user first.",
+      "domains": ["claude-code", "git"],
+      "severity": "high",
+      "tags": ["git", "workflow"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use git push --force or git reset --hard without explicit user permission. These are destructive operations that can lose work.",
+      "domains": ["claude-code", "git"],
+      "severity": "critical",
+      "tags": ["git", "destructive"]
+    },
+    {
+      "type": "semantic",
+      "content": "Read a file before editing it. The Edit tool requires the file to have been read first in the conversation. Always Read before Edit.",
+      "domains": ["claude-code"],
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use the Agent tool for broad codebase exploration and deep research. Use Glob/Grep directly for simple, directed searches (specific file/class/function).",
+      "domains": ["claude-code"],
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "semantic",
+      "content": "Make independent tool calls in parallel. If multiple reads or searches don't depend on each other, call them all in the same response for efficiency.",
+      "domains": ["claude-code"],
+      "tags": ["performance"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't over-engineer. Only make changes directly requested or clearly necessary. A bug fix doesn't need surrounding code cleaned up. Don't add docstrings, comments, or type annotations to code you didn't change.",
+      "domains": ["claude-code"],
+      "severity": "medium",
+      "tags": ["workflow"]
+    },
+    {
+      "type": "semantic",
+      "content": "When editing, the old_string must be unique in the file. If it's not unique, include more surrounding context to make it unique, or use replace_all for global renames.",
+      "domains": ["claude-code"],
+      "tags": ["tool-usage"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't skip git hooks with --no-verify. If a pre-commit hook fails, investigate and fix the underlying issue rather than bypassing it.",
+      "domains": ["claude-code", "git"],
+      "severity": "high",
+      "tags": ["git"]
+    },
+    {
+      "type": "semantic",
+      "content": "For git commits, always use a HEREDOC for the message to ensure proper formatting: git commit -m \"$(cat <<'EOF'\\nMessage here\\nEOF\\n)\"",
+      "domains": ["claude-code", "git"],
+      "tags": ["git"]
+    },
+    {
+      "type": "semantic",
+      "content": "Avoid backwards-compatibility hacks like renaming unused _vars, re-exporting types, or adding // removed comments. If something is unused, delete it completely.",
+      "domains": ["claude-code"],
+      "tags": ["code-quality"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't generate or guess URLs unless confident they're for programming help. Only use URLs provided by the user or found in local files.",
+      "domains": ["claude-code"],
+      "severity": "medium",
+      "tags": ["security"]
+    }
+  ]
+}

package/packs/python-patterns.json

@@ -0,0 +1,106 @@
+{
+  "name": "Python Common Patterns",
+  "version": "1.0.0",
+  "description": "Common Python antipatterns and best practices",
+  "memories": [
+    {
+      "type": "antipattern",
+      "content": "Never use mutable default arguments: def foo(items=[]). The list is shared across all calls. Use def foo(items=None): items = items or [] instead.",
+      "domains": ["python"],
+      "severity": "high",
+      "tags": ["gotchas"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use bare except: clauses. Always catch specific exceptions: except ValueError or at minimum except Exception. Bare except catches SystemExit and KeyboardInterrupt.",
+      "domains": ["python"],
+      "severity": "high",
+      "tags": ["error-handling"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use 'is' to compare values. 'is' checks identity (same object), not equality. Use == for value comparison. Exception: 'is None' is correct and preferred.",
+      "domains": ["python"],
+      "severity": "medium",
+      "tags": ["gotchas"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use pathlib.Path instead of os.path for path manipulation. Path objects support / operator, are more readable, and handle cross-platform differences: Path('src') / 'main.py'.",
+      "domains": ["python"],
+      "tags": ["stdlib"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't modify a list while iterating over it. Use a list comprehension to filter: items = [x for x in items if x.valid] or iterate over a copy: for x in items[:].",
+      "domains": ["python"],
+      "severity": "high",
+      "tags": ["gotchas"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use f-strings for string formatting (Python 3.6+): f'{name} is {age}' — faster than .format() and more readable than % formatting.",
+      "domains": ["python"],
+      "tags": ["style"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use 'type(x) == int' for type checking. Use isinstance(x, int) — it handles subclasses correctly and supports tuple of types: isinstance(x, (int, float)).",
+      "domains": ["python"],
+      "severity": "medium",
+      "tags": ["type-checking"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use context managers (with statement) for resource management: files, database connections, locks. They guarantee cleanup even on exceptions: with open('f') as fh:",
+      "domains": ["python"],
+      "tags": ["patterns"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use wildcard imports: from module import *. It pollutes the namespace, makes code harder to read, and can cause subtle name collisions. Import explicitly.",
+      "domains": ["python"],
+      "severity": "medium",
+      "tags": ["imports"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use dataclasses for simple data containers (Python 3.7+): @dataclass with type annotations. For immutable data, use @dataclass(frozen=True). Prefer over plain dicts or namedtuples.",
+      "domains": ["python"],
+      "tags": ["patterns"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use global variables for shared state. Use function parameters, class attributes, or dependency injection. Globals make testing hard and introduce hidden coupling.",
+      "domains": ["python"],
+      "severity": "medium",
+      "tags": ["architecture"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use enumerate() instead of manual index tracking: for i, item in enumerate(items) — not for i in range(len(items)). Cleaner and less error-prone.",
+      "domains": ["python"],
+      "tags": ["style"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't concatenate strings in loops with +=. Use ''.join(parts) — string concatenation creates a new string each time (O(n^2)), while join is O(n).",
+      "domains": ["python"],
+      "severity": "medium",
+      "tags": ["performance"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use typing module for type hints: def greet(name: str) -> str. For complex types: list[str], dict[str, int], Optional[str], Union[int, str]. Enables IDE support and static analysis.",
+      "domains": ["python"],
+      "tags": ["type-checking"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't silence exceptions with pass: except SomeError: pass. At minimum log the error. Silent failures hide bugs and make debugging extremely difficult.",
+      "domains": ["python"],
+      "severity": "high",
+      "tags": ["error-handling"]
+    }
+  ]
+}

package/packs/typescript-patterns.json

@@ -0,0 +1,106 @@
+{
+  "name": "TypeScript Common Patterns",
+  "version": "1.0.0",
+  "description": "Common TypeScript antipatterns and best practices",
+  "memories": [
+    {
+      "type": "antipattern",
+      "content": "Never use 'as any' to silence type errors. Use type guards (typeof, instanceof, discriminated unions) or proper generics. 'as any' hides real bugs and defeats the purpose of TypeScript.",
+      "domains": ["typescript"],
+      "severity": "high",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use == for null checks. Use === null or === undefined explicitly, or use the nullish coalescing operator (??) and optional chaining (?.).",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use @ts-ignore to suppress errors. Use @ts-expect-error instead — it will alert you when the error is fixed, preventing stale suppressions.",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "semantic",
+      "content": "ESM requires .js extension in import paths even when the source file is .ts. TypeScript does not rewrite extensions: import { foo } from './bar.js' (not ./bar.ts).",
+      "domains": ["typescript", "node"],
+      "tags": ["esm", "modules"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use enum for string unions. Use 'type Foo = \"a\" | \"b\" | \"c\"' instead — it produces no runtime JavaScript, tree-shakes better, and is more idiomatic.",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["patterns"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't mutate function parameters. TypeScript won't warn you but it causes subtle bugs. Clone objects/arrays before modifying: const copy = { ...obj } or [...arr].",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["immutability"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use 'satisfies' to validate a value matches a type without widening: const config = { port: 3000 } satisfies Config. This preserves literal types while checking structure.",
+      "domains": ["typescript"],
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use ! (non-null assertion) liberally. It tells TypeScript 'trust me, this isn't null' — but if you're wrong, it's a runtime crash. Use proper null checks or optional chaining.",
+      "domains": ["typescript"],
+      "severity": "high",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use Omit<T, K> to create types without specific properties, Pick<T, K> to select specific ones. Prefer these over redefining interfaces manually.",
+      "domains": ["typescript"],
+      "tags": ["utility-types"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use Object as a type. Use Record<string, unknown> for dictionaries, or define a proper interface. 'Object' matches almost anything and provides no safety.",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use 'readonly' on properties and arrays that shouldn't be mutated: readonly items: readonly string[]. This catches accidental mutation at compile time.",
+      "domains": ["typescript"],
+      "tags": ["immutability"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't catch errors as 'any'. Use 'catch (e: unknown)' and narrow with instanceof Error. In TypeScript strict mode, caught values are 'unknown' by default.",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["error-handling"]
+    },
+    {
+      "type": "semantic",
+      "content": "Use discriminated unions for state management: type State = { status: 'loading' } | { status: 'success'; data: T } | { status: 'error'; error: Error }. Switch on the discriminant for exhaustive handling.",
+      "domains": ["typescript"],
+      "tags": ["patterns"]
+    },
+    {
+      "type": "antipattern",
+      "content": "Don't use 'any' in generic constraints. Use 'unknown' instead: function foo<T extends unknown>() not function foo<T extends any>(). 'unknown' is the safe top type.",
+      "domains": ["typescript"],
+      "severity": "medium",
+      "tags": ["type-safety"]
+    },
+    {
+      "type": "semantic",
+      "content": "For Node.js TypeScript projects: set 'module': 'node16' or 'nodenext' in tsconfig, not 'commonjs' or 'esnext'. This enables proper ESM/CJS interop resolution.",
+      "domains": ["typescript", "node"],
+      "tags": ["config"]
+    }
+  ]
+}