@shahmilsaari/memory-core 1.0.13 → 1.0.18

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 |
@@ -393,58 +393,56 @@ When `--path` is provided, it must point to the project root (the directory cont
 ### `check` — Manual check (for CI)
 
 ```bash
-npx @shahmilsaari/memory-core check --staged           # check staged files
-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
-npx @shahmilsaari/memory-core check --all              # scan all tracked source files (not just staged changes)
-npx @shahmilsaari/memory-core check --all --path src/  # scan only tracked files under src/
+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 --commit-msg          # check .git/COMMIT_EDITMSG
+npx @shahmilsaari/memory-core check --commit-msg <file>   # check a specific message file
+npx @shahmilsaari/memory-core check --ci                  # CI mode using memories.json
+npx @shahmilsaari/memory-core check --all                 # scan all tracked source files
+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.  
-`--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.
+`--staged` is the same path used by the pre-commit hook. Add `--fast` to skip AI and memory retrieval for a low-latency deterministic check. `--commit-msg` validates a commit message file against `commitRules` — this is called automatically by the `commit-msg` hook. `--ci` reads `memories.json` with no database or Ollama required. `--all` and `--ci` are mutually exclusive.
 
 ---
 
-### `hook install` — Install the pre-commit hook
+### `hook install` — Install hooks
 
 ```bash
 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.
+Installs **two** git hooks:
+- `.git/hooks/pre-commit` — checks staged code against architecture rules.
+- `.git/hooks/commit-msg` — checks commit messages against `commitRules` (see `commit-rules` command).
 
-**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.
+**Advisory mode (default):** violations are logged but the commit always goes through.
 
-**Strict mode:** violations block the commit entirely. You see exactly what's wrong and how to fix it:
+**Strict mode:** violations block the commit. You see exactly what's wrong:
 
 ```
   ✗ 2 rule violations found — commit blocked
 
-  [1] src/controllers/user.ts:32
-      Rule:   Thin controllers — business logic belongs in services
-      Why:    Logic in controllers cannot be reused from other entry points
-              — it gets siloed and duplicated across handlers
-      Issue:  Password validation logic inside route handler
-      Fix:    Move to UserService.validateCredentials()
+  [1] Thin controllers  ×2
+      src/controllers/user.ts:32   Password validation in route handler
+      src/controllers/auth.ts:18   DB query inside controller
 
   [2] src/domain/user.entity.ts:5
       Rule:   Domain has zero external imports
-      Why:    Framework imports tie business logic to infrastructure
       Issue:  Imports 'typeorm' directly
       Fix:    Define IUserRepository interface in domain/
 
-  To bypass: git commit --no-verify
-  To save as memory: memory-core remember "<lesson>"
+  To bypass: MEMORY_CORE_SKIP_HOOK=1 git commit
+  Manage rules: memory-core commit-rules --list
 ```
 
-The hook mode is chosen during `init` — no separate step needed unless you want to change it later.
-
 ```bash
-npx @shahmilsaari/memory-core hook uninstall   # remove the hook
+npx @shahmilsaari/memory-core hook uninstall   # remove both hooks
 ```
 
 ---
@@ -578,6 +576,28 @@ Stores lightweight per-project allowlist strings in `.memory-core.json`. Hook an
 
 ---
 
+### `commit-rules` — Enforce commit message format
+
+```bash
+npx @shahmilsaari/memory-core commit-rules "^(feat|fix|chore)" --message "Use conventional commits"
+npx @shahmilsaari/memory-core commit-rules "^WIP" --message "Don't commit WIP" --negate
+npx @shahmilsaari/memory-core commit-rules "PROJ-\d+" --message "Reference a JIRA ticket" --advisory
+npx @shahmilsaari/memory-core commit-rules --list
+npx @shahmilsaari/memory-core commit-rules --remove "^WIP"
+```
+
+Stores regex-based rules in `.memory-core.json` under `commitRules`. The `commit-msg` git hook (installed by `hook install`) validates every commit message against these rules before the commit is accepted.
+
+| Flag | What it does |
+|---|---|
+| `--message <msg>` | Required. Error message shown on violation. |
+| `--negate` | Pattern must NOT match (default: must match) |
+| `--advisory` | Warn only — do not block the commit |
+| `--list` | Show all saved commit rules |
+| `--remove <pattern>` | Remove a rule by pattern |
+
+---
+
 ### `ci-setup` — GitHub Actions integration
 
 ```bash
@@ -592,13 +612,33 @@ Generates `.github/workflows/memory-core.yml`. Adds a PR check that runs `npx @s
 
 ```bash
 npx @shahmilsaari/memory-core stats
+npx @shahmilsaari/memory-core stats --tune
 npx @shahmilsaari/memory-core stats --reset
 ```
 
-Shows which rules fire most often and which files have the most violations.
-- If live watch state exists, `stats` shows current live counters.
-- Otherwise it shows historical counters recorded over time.
-- Use `--reset` to clear counters and recent violation history.
+Shows which rules fire most often and which files have the most violations. Each rule shows hit count and false-positive rate where available.
+
+- `--tune` shows only noisy rules (>40% false-positive rate) with their exact disable commands.
+- `--reset` clears all counters and recent violation history.
+- Live watch-state counters are shown when available.
+
+---
+
+### `tune` — Silence noisy rules
+
+```bash
+npx @shahmilsaari/memory-core tune
+npx @shahmilsaari/memory-core tune --threshold 30
+npx @shahmilsaari/memory-core tune --yes
+```
+
+Interactively reviews rules with a high false-positive rate and adds them to `allowPatterns` in `.memory-core.json`.
+
+| Flag | What it does |
+|---|---|
+| `--threshold <n>` | False-positive % cutoff (default `40`) |
+| `--min-count <n>` | Minimum hits required (default `5`) |
+| `--yes` | Silence all qualifying rules without prompting |
 
 ---
 
@@ -852,20 +892,24 @@ npm run smoke:npx
 | ✓ | NestJS profile and 39 rules |
 | ✓ | Hook auto-prompt — hook mode offered during init, no separate step needed |
 | ✓ | CI/CD — `ci-setup` generates GitHub Actions workflow for PR enforcement |
-| ✓ | Violation stats — see which rules fire most and which files break most |
 | ✓ | Agent selection — choose which agents to generate files for during init |
 | ✓ | Auto-sync — memory-changing commands refresh selected agent files by default |
 | ✓ | Export / import — portable memories.json for version control and team sharing |
 | ✓ | List / remove / edit — full CRUD for stored memories |
-| ✓ | False positive tagging — `ignore` command saves exceptions for hook and watcher |
-| ✓ | Cleanup commands — `reset` regenerates/reinitializes files; `uninstall` removes memory-core from a project |
-| ✓ | Test suite — smoke tests for all core commands and providers |
+| ✓ | False positive tagging — `ignore` and `allow` save exceptions for hook and watcher |
+| ✓ | Cleanup commands — `reset` regenerates/reinitializes files; `uninstall` removes memory-core |
+| ✓ | Test suite — 94 tests using Node.js built-in `node:test` |
 | ✓ | Multi-provider code checking — Ollama, OpenAI, Anthropic, MiniMax |
 | ✓ | Context-aware retrieval — surface the most relevant rules for the file being edited |
 | ✓ | Setup management — `status`, `provider set`, `model set`, `model doctor` |
 | ✓ | `--debug` flag — verbose output for diagnosing hook and watcher issues |
-| ✓ | Local Svelte dashboard — WebSocket live feed, runtime status, stats, and architecture-filtered rules |
-| ✓ | Live config reload — dashboard updates when `.env`, `.memory-core.env`, project config, or stats change |
+| ✓ | Local Svelte dashboard — WebSocket live feed, runtime status, stats, and rules browser |
+| ✓ | Rule cache — 5-min TTL cache, invalidated by config or DB version change |
+| ✓ | Batch suppression — same rule ≥3× on same file auto-suppressed with a notice |
+| ✓ | False-positive tracking — `{ count, falsePositives }` stored per rule in stats |
+| ✓ | Violation clustering — violations grouped by rule, compact multi-location display |
+| ✓ | Auto-tuning — `memory-core tune` silences noisy rules interactively |
+| ✓ | Commit message linting — `commit-rules` + `commit-msg` git hook |
 | | Model guidance during init — recommend a model based on machine specs |
 | | Violation → rule pipeline — auto-suggest a new rule when the same violation repeats |
 | | Team sync — shared database so the whole team works from the same rule set |

package/dist/{chunk-PRRVI3YM.js → chunk-UNGXRKD2.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 {
@@ -119,13 +124,29 @@ function getChatConfig() {
     provider,
     model,
     ollamaUrl: process.env.OLLAMA_URL ?? "http://localhost:11434",
-    apiKey: process.env.CHAT_API_KEY ?? ""
+    apiKey: process.env.CHAT_API_KEY ?? "",
+    baseUrl: process.env.CHAT_BASE_URL ?? ""
   };
 }
-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 +159,15 @@ async function callOllama(cfg, messages) {
   const data = await res.json();
   return data.message.content.trim();
 }
-async function callOpenAI(cfg, messages) {
-  const res = await fetch("https://api.openai.com/v1/chat/completions", {
+async function callOpenAICompat(cfg, messages, options = {}) {
+  const base = (cfg.baseUrl ?? "").replace(/\/$/, "") || "https://api.openai.com/v1";
+  const res = await fetch(`${base}/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 +178,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 +188,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 +200,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,22 +218,31 @@ 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":
+      case "openai-compatible":
+        return await callOpenAICompat(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() {
   const cfg = getChatConfig();
   if (cfg.provider === "ollama") return `ollama (${cfg.model})`;
+  if (cfg.provider === "openai-compatible") {
+    const host = cfg.baseUrl ? new URL(cfg.baseUrl).hostname : "custom";
+    return `openai-compat/${host} (${cfg.model})`;
+  }
   return `${cfg.provider} (${cfg.model})`;
 }
 
@@ -218,6 +252,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 +264,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 +279,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 +1288,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);