@shahmilsaari/memory-core 1.0.13 → 1.0.16

package/README.md

@@ -292,7 +292,7 @@ npx @shahmilsaari/memory-core remember "Use DTOs for all API responses" \
 |---|---|---|
 | `--type` | `decision` `rule` `pattern` `note` | `decision` |
 | `--scope` | `global` `project` | `project` |
-| `--reason` | any text | asked interactively |
+| `--reason` | any text | asked interactively; fallback is stored if blank |
 | `--applies-to` | comma-separated use cases | none |
 | `--avoid-when` | comma-separated exceptions | none |
 | `--example` | comma-separated examples | none |
@@ -394,6 +394,7 @@ When `--path` is provided, it must point to the project root (the directory cont
 
 ```bash
 npx @shahmilsaari/memory-core check --staged           # check staged files
+npx @shahmilsaari/memory-core check --staged --fast    # deterministic-only staged check
 npx @shahmilsaari/memory-core check --staged --verbose # with extra detail
 npx @shahmilsaari/memory-core check --staged --debug   # show prompt, diff, and raw model output
 npx @shahmilsaari/memory-core check --ci               # CI mode using memories.json
@@ -401,7 +402,7 @@ npx @shahmilsaari/memory-core check --all              # scan all tracked source
 npx @shahmilsaari/memory-core check --all --path src/  # scan only tracked files under src/
 ```
 
-`--staged` is the same path used by the pre-commit hook. `--ci` reads `memories.json` and uses a deterministic CI-friendly diff check, so pull requests can enforce rules without a local database or Ollama setup.  
+`--staged` is the same path used by the pre-commit hook. Add `--fast` to skip AI and memory retrieval when you need a low-latency deterministic check. `--ci` reads `memories.json` and uses a deterministic CI-friendly diff check, so pull requests can enforce rules without a local database or Ollama setup.  
 `--all` runs a full tracked-file snapshot check and exits non-zero if violations are found.
 `--all` and `--ci` are mutually exclusive in the same command.
 
@@ -413,10 +414,13 @@ npx @shahmilsaari/memory-core check --all --path src/  # scan only tracked files
 npx @shahmilsaari/memory-core hook install             # advisory mode (default)
 npx @shahmilsaari/memory-core hook install --advisory  # logs violations, never blocks
 npx @shahmilsaari/memory-core hook install --strict    # blocks commits on violations
+npx @shahmilsaari/memory-core hook install --fast      # deterministic-only hook
 ```
 
 Installs a git pre-commit hook in the current project. Every time you run `git commit`, your code is checked against your architecture rules.
 
+Add `--fast` to make the hook skip AI and memory retrieval for lower latency.
+
 **Advisory mode (default):** violations are logged so you can see them, but the commit always goes through. Useful for getting used to the rules without disrupting your flow.
 
 **Strict mode:** violations block the commit entirely. You see exactly what's wrong and how to fix it:

package/dist/{chunk-PRRVI3YM.js → chunk-ECYSBYMM.js}

@@ -90,12 +90,17 @@ var Config = {
 };
 
 // src/embedding.ts
+function getEmbeddingTimeoutMs() {
+  const raw = Number(process.env.EMBEDDING_TIMEOUT_MS ?? process.env.MEMORY_CORE_RETRIEVAL_TIMEOUT_MS ?? 5e3);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 5e3;
+}
 async function embed(text) {
   let response;
   try {
     response = await fetch(`${Config.ollamaUrl}/api/embeddings`, {
       method: "POST",
       headers: { "Content-Type": "application/json" },
+      signal: AbortSignal.timeout(getEmbeddingTimeoutMs()),
       body: JSON.stringify({ model: Config.ollamaModel, prompt: text })
     });
   } catch {
@@ -122,10 +127,25 @@ function getChatConfig() {
     apiKey: process.env.CHAT_API_KEY ?? ""
   };
 }
-async function callOllama(cfg, messages) {
+function getDefaultTimeoutMs() {
+  const raw = Number(process.env.CHAT_TIMEOUT_MS ?? 2e4);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : 2e4;
+}
+function timeoutSignal(timeoutMs) {
+  return AbortSignal.timeout(timeoutMs ?? getDefaultTimeoutMs());
+}
+function normalizeChatError(err, timeoutMs) {
+  const ms = timeoutMs ?? getDefaultTimeoutMs();
+  if (err instanceof Error && err.name === "AbortError") {
+    return new Error(`TIMEOUT:${ms}`);
+  }
+  return err instanceof Error ? err : new Error(String(err));
+}
+async function callOllama(cfg, messages, options = {}) {
   const res = await fetch(`${cfg.ollamaUrl}/api/chat`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
+    signal: timeoutSignal(options.timeoutMs),
     body: JSON.stringify({ model: cfg.model, messages, stream: false, format: "json" })
   });
   if (!res.ok) {
@@ -138,13 +158,14 @@ async function callOllama(cfg, messages) {
   const data = await res.json();
   return data.message.content.trim();
 }
-async function callOpenAI(cfg, messages) {
+async function callOpenAI(cfg, messages, options = {}) {
   const res = await fetch("https://api.openai.com/v1/chat/completions", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "Authorization": `Bearer ${cfg.apiKey}`
     },
+    signal: timeoutSignal(options.timeoutMs),
     body: JSON.stringify({
       model: cfg.model,
       messages,
@@ -155,7 +176,7 @@ async function callOpenAI(cfg, messages) {
   const data = await res.json();
   return data.choices[0].message.content.trim();
 }
-async function callAnthropic(cfg, messages) {
+async function callAnthropic(cfg, messages, options = {}) {
   const system = messages.find((m) => m.role === "system")?.content ?? "";
   const userMessages = messages.filter((m) => m.role !== "system");
   const res = await fetch("https://api.anthropic.com/v1/messages", {
@@ -165,6 +186,7 @@ async function callAnthropic(cfg, messages) {
       "x-api-key": cfg.apiKey,
       "anthropic-version": "2023-06-01"
     },
+    signal: timeoutSignal(options.timeoutMs),
     body: JSON.stringify({
       model: cfg.model,
       max_tokens: 4096,
@@ -176,13 +198,14 @@ async function callAnthropic(cfg, messages) {
   const data = await res.json();
   return data.content[0].text.trim();
 }
-async function callMiniMax(cfg, messages) {
+async function callMiniMax(cfg, messages, options = {}) {
   const res = await fetch("https://api.minimax.io/v1/chat/completions", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       "Authorization": `Bearer ${cfg.apiKey}`
     },
+    signal: timeoutSignal(options.timeoutMs),
     body: JSON.stringify({
       model: cfg.model,
       messages,
@@ -193,17 +216,21 @@ async function callMiniMax(cfg, messages) {
   const data = await res.json();
   return data.choices[0].message.content.trim();
 }
-async function callChatModel(messages) {
+async function callChatModel(messages, options = {}) {
   const cfg = getChatConfig();
-  switch (cfg.provider) {
-    case "openai":
-      return callOpenAI(cfg, messages);
-    case "anthropic":
-      return callAnthropic(cfg, messages);
-    case "minimax":
-      return callMiniMax(cfg, messages);
-    default:
-      return callOllama(cfg, messages);
+  try {
+    switch (cfg.provider) {
+      case "openai":
+        return await callOpenAI(cfg, messages, options);
+      case "anthropic":
+        return await callAnthropic(cfg, messages, options);
+      case "minimax":
+        return await callMiniMax(cfg, messages, options);
+      default:
+        return await callOllama(cfg, messages, options);
+    }
+  } catch (err) {
+    throw normalizeChatError(err, options.timeoutMs);
   }
 }
 function getChatProviderLabel() {
@@ -218,6 +245,10 @@ import { createHash } from "crypto";
 var { Pool } = pg;
 var pool = null;
 var migrationsRun = false;
+function readPositiveIntEnv(name, fallback) {
+  const raw = Number(process.env[name]);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : fallback;
+}
 function hashMemoryContent(content) {
   return createHash("md5").update(content.trim()).digest("hex");
 }
@@ -226,7 +257,13 @@ function getPool() {
     if (!Config.databaseUrl) {
       throw new Error("DATABASE_URL is not set. Add it to your .env or .memory-core.env file.");
     }
-    pool = new Pool({ connectionString: Config.databaseUrl });
+    const timeoutMs = readPositiveIntEnv("DATABASE_TIMEOUT_MS", 5e3);
+    pool = new Pool({
+      connectionString: Config.databaseUrl,
+      connectionTimeoutMillis: timeoutMs,
+      query_timeout: timeoutMs,
+      statement_timeout: timeoutMs
+    });
   }
   return pool;
 }
@@ -235,6 +272,7 @@ async function runMigrations() {
   const client = await getPool().connect();
   try {
     await client.query("BEGIN");
+    await client.query(`ALTER TABLE memories ALTER COLUMN scope SET DEFAULT 'project'`);
     await client.query(`ALTER TABLE memories ADD COLUMN IF NOT EXISTS reason TEXT`);
     await client.query(`ALTER TABLE memories ADD COLUMN IF NOT EXISTS content_hash TEXT`);
     await client.query(`ALTER TABLE memories ADD COLUMN IF NOT EXISTS context JSONB NOT NULL DEFAULT '{}'::jsonb`);
@@ -1243,13 +1281,22 @@ var MemoryEngineService = class {
   }
   memoryRepository;
   embeddingProvider;
+  withReason(input) {
+    const reason = input.reason?.trim();
+    return {
+      ...input,
+      reason: reason || `Captured as a ${input.type} memory because it should be remembered: ${input.content}`
+    };
+  }
   async remember(input) {
-    const embedding = await this.embeddingProvider.embed(input.content);
-    return this.memoryRepository.upsert({ ...input, embedding });
+    const normalized = this.withReason(input);
+    const embedding = await this.embeddingProvider.embed(normalized.content);
+    return this.memoryRepository.upsert({ ...normalized, embedding });
   }
   async rememberForce(input) {
-    const embedding = await this.embeddingProvider.embed(input.content);
-    await this.memoryRepository.save({ ...input, embedding });
+    const normalized = this.withReason(input);
+    const embedding = await this.embeddingProvider.embed(normalized.content);
+    await this.memoryRepository.save({ ...normalized, embedding });
   }
   async list(filters = {}) {
     return this.memoryRepository.list(filters);

package/dist/cli.js

@@ -20,7 +20,7 @@ import {
   retrieveMemorySelection,
   runMigrations,
   seeds
-} from "./chunk-PRRVI3YM.js";
+} from "./chunk-ECYSBYMM.js";
 
 // src/cli.ts
 import { Command } from "commander";
@@ -122,8 +122,9 @@ var reasonMap = new Map(
 );
 var HOOK_PATH = join2(".git", "hooks", "pre-commit");
 var HOOK_MARKER = "# archmind-memory-core";
-function buildHookBody(advisory) {
+function buildHookBody(advisory, fast = false) {
   const suffix = advisory ? " || true" : "";
+  const checkArgs = fast ? "check --staged --fast" : "check --staged";
   return `${HOOK_MARKER}${advisory ? " advisory" : ""}
 if [ "\${MEMORY_CORE_SKIP_HOOK:-}" = "1" ] || [ "\${ARCHMIND_SKIP_HOOK:-}" = "1" ] || [ "\${HUSKY:-}" = "0" ] || [ "\${HUSKY_SKIP_HOOKS:-}" = "1" ]; then
   exit 0
@@ -135,20 +136,20 @@ if [ -n "\${SKIP_HOOKS:-}" ]; then
   exit 0
 fi
 if command -v memory-core >/dev/null 2>&1; then
-  memory-core check --staged${suffix}
+  memory-core ${checkArgs}${suffix}
 elif [ -f "./node_modules/.bin/memory-core" ]; then
-  ./node_modules/.bin/memory-core check --staged${suffix}
+  ./node_modules/.bin/memory-core ${checkArgs}${suffix}
 elif [ -f "./dist/cli.js" ]; then
-  node ./dist/cli.js check --staged${suffix}
+  node ./dist/cli.js ${checkArgs}${suffix}
 else
-  npx --no-install memory-core check --staged 2>/dev/null || exit 0
+  npx --no-install memory-core ${checkArgs} 2>/dev/null || exit 0
 fi
 `;
 }
-function buildHookScript(advisory) {
+function buildHookScript(advisory, fast = false) {
   return `#!/bin/sh
 
-${buildHookBody(advisory)}`;
+${buildHookBody(advisory, fast)}`;
 }
 function normalizeHookPreamble(content) {
   const lines = content.split("\n");
@@ -165,6 +166,26 @@ function normalizeHookPreamble(content) {
   }
   return normalized.join("\n").replace(/\n{3,}/g, "\n\n").trim();
 }
+function readPositiveIntEnv(name, fallback) {
+  const raw = Number(process.env[name]);
+  return Number.isFinite(raw) && raw > 0 ? Math.floor(raw) : fallback;
+}
+function isFastCheck(options) {
+  return options.fast === true || process.env.MEMORY_CORE_CHECK_FAST === "1";
+}
+async function withTimeout(promise, timeoutMs, fallback) {
+  let timer;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((resolve2) => {
+        timer = setTimeout(() => resolve2(fallback), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
 function recordViolations(violations, source = "hook") {
   const statsPath = join2(process.cwd(), ".memory-core-stats.json");
   let stats = { rules: {}, files: {} };
@@ -219,11 +240,12 @@ async function promptToSaveViolations(violations) {
       message: "Why should this rule exist?",
       default: selected.reason ?? selected.issue ?? ""
     });
+    const storedReason = reason.trim() || selected.reason || selected.issue || `Captured from violation: ${selected.rule}`;
     await app.services.memoryEngine.remember({
       type: "rule",
       scope: "project",
       content: selected.rule,
-      reason: reason || void 0,
+      reason: storedReason,
       tags: ["violation"]
     });
     console.log(chalk.green("  \u2713 Saved as project rule. Run memory-core sync to propagate it.\n"));
@@ -493,10 +515,11 @@ ${JSON.stringify(options.allowPatterns, null, 2)}`;
     console.log(chalk.dim("  \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   }
   try {
+    const recheckTimeoutMs = readPositiveIntEnv("MEMORY_CORE_FALSE_POSITIVE_TIMEOUT_MS", 6e3);
     const raw = await callChatModel([
       { role: "system", content: systemPrompt },
       { role: "user", content: userPrompt }
-    ]);
+    ], { timeoutMs: recheckTimeoutMs });
     const parsed = parseFalsePositiveDecisions(raw);
     if (!parsed.valid) return [];
     const existing = new Set(options.allowPatterns.map((pattern) => pattern.toLowerCase()));
@@ -637,13 +660,13 @@ function filterModelViolationsByStagedDiff(violations, stagedFiles, diff) {
   }
   return filtered;
 }
-function installHook(advisory = true) {
+function installHook(advisory = true, fast = false) {
   if (!existsSync2(".git")) {
     console.error(chalk.red("\n  Not a git repository. Run from project root.\n"));
     process.exit(1);
   }
-  const script = buildHookScript(advisory);
-  const body = buildHookBody(advisory).trimEnd();
+  const script = buildHookScript(advisory, fast);
+  const body = buildHookBody(advisory, fast).trimEnd();
   if (existsSync2(HOOK_PATH)) {
     const existing = readFileSync2(HOOK_PATH, "utf-8");
     if (existing.includes(HOOK_MARKER)) {
@@ -660,6 +683,7 @@ ${body}
       chmodSync(HOOK_PATH, 493);
       const modeLabel2 = advisory ? chalk.cyan("advisory") : chalk.yellow("strict");
       console.log(chalk.green("\n  \u2713 Pre-commit hook updated") + chalk.dim(` (${modeLabel2} mode)`));
+      if (fast) console.log(chalk.gray(`    Check mode: fast deterministic checks`));
       return;
     }
     writeFileSync2(HOOK_PATH, existing.trimEnd() + "\n\n" + body + "\n");
@@ -669,7 +693,7 @@ ${body}
   chmodSync(HOOK_PATH, 493);
   const modeLabel = advisory ? "advisory (logs violations, never blocks)" : "strict (blocks commits on violations)";
   console.log(chalk.green("\n  \u2713 Pre-commit hook installed") + chalk.dim(` \u2014 ${modeLabel}`));
-  console.log(chalk.gray(`    Chat model: ${process.env.OLLAMA_CHAT_MODEL ?? "llama3.2"}`));
+  console.log(chalk.gray(fast ? "    Check mode: fast deterministic checks" : `    Chat model: ${process.env.OLLAMA_CHAT_MODEL ?? "llama3.2"}`));
   console.log(chalk.gray("    To uninstall: memory-core hook uninstall\n"));
 }
 function uninstallHook() {
@@ -720,17 +744,22 @@ async function checkStaged(options = {}) {
   if (!existsSync2(configPath)) return;
   const config = JSON.parse(readFileSync2(configPath, "utf-8"));
   const { rules: fallbackRules, avoids } = getProfileRules(config);
-  const [rules, ignores] = await Promise.all([
-    loadRelevantRules(config, diff, stagedFiles, fallbackRules),
-    loadIgnorePatterns()
+  const fast = isFastCheck(options);
+  const ruleLoadTimeoutMs = readPositiveIntEnv("MEMORY_CORE_RULE_LOAD_TIMEOUT_MS", 2e3);
+  const ignoreLoadTimeoutMs = readPositiveIntEnv("MEMORY_CORE_IGNORE_LOAD_TIMEOUT_MS", 1500);
+  const [rules, ignores] = fast ? [fallbackRules, []] : await Promise.all([
+    withTimeout(loadRelevantRules(config, diff, stagedFiles, fallbackRules), ruleLoadTimeoutMs, fallbackRules),
+    withTimeout(loadIgnorePatterns(), ignoreLoadTimeoutMs, [])
   ]);
   const allowPatterns = [.../* @__PURE__ */ new Set([...getAllowPatterns(config), ...ignores])];
   if (rules.length === 0) return;
-  const modelInput = buildModelInputFromDiff(diff, 8e3);
+  const modelInputMaxChars = readPositiveIntEnv("MEMORY_CORE_MODEL_INPUT_MAX_CHARS", 8e3);
+  const modelInput = buildModelInputFromDiff(diff, modelInputMaxChars);
   console.log(chalk.cyan("\n  archmind \u2014 checking staged changes against rules\u2026"));
   if (options.verbose || options.debug) {
     const sourceLabel = modelInput.source === "added-lines" ? "added lines" : "diff";
-    console.log(chalk.gray(`  model: ${getChatProviderLabel()}  rules: ${rules.length}  diff: ${diff.length} chars  input: ${sourceLabel}${modelInput.truncated ? " (truncated)" : ""}`));
+    const modelLabel = fast ? "skipped (--fast)" : getChatProviderLabel();
+    console.log(chalk.gray(`  model: ${modelLabel}  rules: ${rules.length}  diff: ${diff.length} chars  input: ${sourceLabel}${modelInput.truncated ? " (truncated)" : ""}`));
   }
   const rulesWithReasons = rules.map((r, i) => {
     const why = reasonMap.get(r);
@@ -773,13 +802,19 @@ Do not include any text outside the JSON object.`;
     reasonLookup: reasonMap
   });
   let modelViolations = [];
-  try {
+  let aiFallback = fast;
+  if (fast) {
+    if (options.verbose || options.debug) {
+      console.log(chalk.gray("  AI check skipped; running deterministic checks only."));
+    }
+  } else try {
+    const checkTimeoutMs = readPositiveIntEnv("MEMORY_CORE_CHECK_TIMEOUT_MS", readPositiveIntEnv("CHAT_TIMEOUT_MS", 2e4));
     const raw = await callChatModel([
       { role: "system", content: systemPrompt },
       { role: "user", content: `Review these staged changes:
 
 ${modelInput.text}` }
-    ]);
+    ], { timeoutMs: checkTimeoutMs });
     if (options.verbose || options.debug) {
       console.log(chalk.gray(`  raw response: ${options.debug ? raw : raw.slice(0, 200)}`));
     }
@@ -792,22 +827,32 @@ ${modelInput.text}` }
   } catch (err) {
     if (err.message?.startsWith("MODEL_NOT_FOUND:")) {
       printModelMissing(err.message.split(":")[1]);
+      aiFallback = true;
+      modelViolations = [];
+    } else if (err.message?.startsWith("TIMEOUT:")) {
+      const timeoutMs = err.message.split(":")[1];
+      console.log(chalk.yellow(`
+  \u26A0  AI check timed out after ${timeoutMs}ms \u2014 switching to fast deterministic checks for this run.`));
+      console.log(chalk.gray("     Set MEMORY_CORE_CHECK_TIMEOUT_MS to tune this.\n"));
+      aiFallback = true;
       modelViolations = [];
     } else if (err.cause?.code === "ECONNREFUSED" || err.message?.includes("ECONNREFUSED")) {
       console.log(chalk.yellow("\n  \u26A0  Ollama not running \u2014 using deterministic checks only."));
       console.log(chalk.gray("     Start it: ollama serve\n"));
+      aiFallback = true;
       modelViolations = [];
     } else {
       console.log(chalk.yellow(`
   \u26A0  AI rule check failed: ${err.message}`));
       console.log(chalk.gray("     Using deterministic checks only.\n"));
+      aiFallback = true;
       modelViolations = [];
     }
   }
   modelViolations = filterModelViolationsByStagedDiff(modelViolations, stagedFiles, diff);
   let violations = dedupeViolations([...deterministicViolations, ...astViolations, ...modelViolations]);
   violations = applyAllowPatterns(violations, allowPatterns);
-  if (violations.length > 0) {
+  if (!aiFallback && violations.length > 0) {
     const learnedPatterns = await learnGlobalIgnoresFromFalsePositives({
       diff,
       currentViolations: violations,
@@ -1305,6 +1350,11 @@ function buildMemoryContext(opts) {
   if (opts.source?.trim()) context.source = opts.source.trim();
   return Object.keys(context).length ? context : void 0;
 }
+function memoryReasonOrFallback(reason, content, type = "memory") {
+  const trimmed = reason?.trim();
+  if (trimmed) return trimmed;
+  return `Captured as a ${type} memory because it should be remembered: ${content}`;
+}
 function truncate(value, length) {
   if (!value) return "";
   return value.length > length ? `${value.slice(0, Math.max(0, length - 1))}\u2026` : value;
@@ -1960,27 +2010,29 @@ program.command("auto-sync [mode]").description("Show or change automatic agent
 });
 program.command("remember <text>").description("Save a new memory to the central database").option("-t, --type <type>", "Memory type (decision|rule|pattern|note)", "decision").option("-s, --scope <scope>", "Scope (global|project)", "project").option("--tags <tags>", "Comma-separated tags").option("-r, --reason <reason>", "Why this rule exists \u2014 helps agents understand intent and debug violations").option("--applies-to <items>", "Comma-separated situations where this memory applies").option("--avoid-when <items>", "Comma-separated situations where this memory should not be used").option("--example <items>", "Comma-separated examples that teach agents how to apply this memory").option("--source <source>", "Human-readable source for this memory").option("--no-sync", "Skip automatic agent file sync after saving").action(async (text, opts) => {
   const config = readProjectConfig();
+  const scope = opts.scope?.trim() || "project";
   let reason = opts.reason;
   if (!reason) {
     reason = await input({
-      message: chalk2.dim("Why does this rule exist? (optional \u2014 helps agents debug violations)"),
+      message: chalk2.dim("Why should this memory exist?"),
       default: ""
     });
   }
+  const storedReason = memoryReasonOrFallback(reason, text, opts.type);
   const spinner = ora("Saving memory\u2026").start();
   try {
     await phase1.services.memoryEngine.remember({
       type: opts.type,
-      scope: opts.scope,
+      scope,
       architecture: config?.backendArchitecture ?? config?.frontendFramework,
-      projectName: config?.projectName,
+      projectName: scope === "project" ? config?.projectName : void 0,
       content: text,
-      reason: reason || void 0,
+      reason: storedReason,
       context: buildMemoryContext(opts),
       tags: parseTags(opts.tags)
     });
-    const reasonLine = reason ? chalk2.gray(`
-  Why: ${reason}`) : "";
+    const reasonLine = chalk2.gray(`
+  Why: ${storedReason}`);
     spinner.succeed(chalk2.green(`Memory saved: "${text}"`) + reasonLine);
     await autoSyncGeneratedFiles(config, "remember", opts.sync);
   } catch (err) {
@@ -2162,7 +2214,7 @@ program.command("edit <id>").description("Edit a memory interactively").option("
       scope,
       title: title || void 0,
       content,
-      reason: reason || void 0,
+      reason: memoryReasonOrFallback(reason, content, type),
       context: buildMemoryContext({ appliesTo, avoidWhen, example: examples, source }),
       tags: parseTags(tags)
     });
@@ -2378,7 +2430,7 @@ program.command("dashboard").description("Start the live Svelte dashboard with W
     }
     return void 0;
   };
-  const { startDashboard } = await import("./dashboard-server-53HVL7LF.js");
+  const { startDashboard } = await import("./dashboard-server-4WOUQTJN.js");
   await startDashboard({
     port: parseInt(opts.port, 10),
     path: resolveDashboardPath(),
@@ -2775,14 +2827,14 @@ graph.command("diff <leftSnapshotId> [rightSnapshotId]").description("Diff two s
   }
 });
 var hook = program.command("hook").description("Manage the pre-commit rule enforcement hook");
-hook.command("install").description("Install pre-commit hook (advisory mode by default \u2014 logs violations, never blocks)").option("--advisory", "Log violations but never block commits (default)").option("--strict", "Block commits that violate your rules").action((opts) => {
+hook.command("install").description("Install pre-commit hook (advisory mode by default \u2014 logs violations, never blocks)").option("--advisory", "Log violations but never block commits (default)").option("--strict", "Block commits that violate your rules").option("--fast", "Use deterministic checks only in the hook").action((opts) => {
   const advisory = opts.strict ? false : true;
-  installHook(advisory);
+  installHook(advisory, opts.fast ?? false);
 });
 hook.command("uninstall").description("Remove the pre-commit hook").action(() => {
   uninstallHook();
 });
-program.command("check").description("Check staged changes against architecture rules (used by pre-commit hook)").option("--staged", "Check git staged diff (default behaviour)").option("--ci", `Check CI diff using ${MEMORY_FILE}`).option("--all", "Check all tracked source files, including already-committed files").option("--path <dir>", "Directory to check for --all mode (default: current directory)").option("--verbose", "Show model and diff details").option("--debug", "Show prompt, diff, and raw model response").action(async (opts) => {
+program.command("check").description("Check staged changes against architecture rules (used by pre-commit hook)").option("--staged", "Check git staged diff (default behaviour)").option("--ci", `Check CI diff using ${MEMORY_FILE}`).option("--all", "Check all tracked source files, including already-committed files").option("--path <dir>", "Directory to check for --all mode (default: current directory)").option("--verbose", "Show model and diff details").option("--debug", "Show prompt, diff, and raw model response").option("--fast", "Skip AI and memory retrieval; run deterministic checks only").action(async (opts) => {
   if (opts.ci && opts.all) {
     console.error(chalk2.red("\n  Choose one mode: --ci or --all.\n"));
     process.exit(1);
@@ -2800,7 +2852,7 @@ program.command("check").description("Check staged changes against architecture
     if (summary.violations > 0) process.exit(1);
     return;
   }
-  await checkStaged({ verbose: opts.verbose ?? false, debug: opts.debug ?? false });
+  await checkStaged({ verbose: opts.verbose ?? false, debug: opts.debug ?? false, fast: opts.fast ?? false });
 });
 program.command("watch").description("Watch source files and check violations in real-time on every save").option("--path <dir>", "Directory to watch (default: current directory)").option("--scan-on-start", "Run an initial full snapshot scan before watching file changes").option("--verbose", "Show diff size and model details per file").option("--debug", "Show prompt, diff, and raw model response").action(async (opts) => {
   await phase1.providers.watchService.start({

package/dist/{dashboard-server-53HVL7LF.js → dashboard-server-4WOUQTJN.js}

@@ -12,7 +12,7 @@ import {
   saveMemory,
   startWatch,
   updateMemory
-} from "./chunk-PRRVI3YM.js";
+} from "./chunk-ECYSBYMM.js";
 
 // src/dashboard-server.ts
 import { createHash } from "crypto";
@@ -474,14 +474,16 @@ async function handleApi(req, res, url) {
       }
       const config = readProjectConfig();
       const activeArchitectures = inferProjectArchitectures(projectRoot, config);
+      const scope = typeof body.scope === "string" && body.scope.trim() ? body.scope.trim() : "project";
+      const reason = typeof body.reason === "string" && body.reason.trim() ? body.reason.trim() : `Captured as a ${typeof body.type === "string" ? body.type : "rule"} memory because it should be remembered: ${content}`;
       await saveMemory({
         type: typeof body.type === "string" ? body.type : "rule",
-        scope: typeof body.scope === "string" ? body.scope : "project",
+        scope,
         architecture: typeof config?.backendArchitecture === "string" ? config.backendArchitecture : typeof config?.frontendFramework === "string" ? config.frontendFramework : activeArchitectures[0],
-        projectName: typeof config?.projectName === "string" ? config.projectName : void 0,
+        projectName: scope === "project" && typeof config?.projectName === "string" ? config.projectName : void 0,
         title: typeof body.title === "string" ? body.title : void 0,
         content,
-        reason: typeof body.reason === "string" && body.reason.trim() ? body.reason.trim() : void 0,
+        reason,
         context: {},
         tags: parseTags(body.tags),
         embedding: await embed(content)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shahmilsaari/memory-core",
-  "version": "1.0.13",
+  "version": "1.0.16",
   "description": "Universal AI memory core — generate AI context files from architecture profiles with RAG support",
   "homepage": "https://memory-core.shahmilsaari.my/",
   "type": "module",