@lorekit/cli 1.14.0 → 1.15.0

package/README.md

@@ -17,7 +17,7 @@ markdown files if you never want to sign up for anything.
 
 ```bash
 npm install -g @lorekit/cli
-lorekit install     # wires up the skill, MCP server, and hooks
+lorekit install     # wires up the skills, MCP server, and hooks
 lorekit doctor      # verify it's all green
 ```
 
@@ -47,7 +47,7 @@ Linux, and Windows (npm creates the `lorekit` shim on every platform).
 Sets up the full memory loop — the same three parts as the Claude plugin,
 without needing a marketplace:
 
-1. **Skill** (`lorekit-memory`) — the model-invoked authoring judgment.
+1. **Skills** (`lorekit-memory` + `lorekit-setup`) — the model-invoked authoring judgment and the self-improvement loop authoring counterpart.
 2. **MCP server** (`lorekit`) — the connection to your lessons, merged into the
    MCP config (preserving any other servers).
 3. **Hooks** — the *deterministic* layer: lessons injected on every
@@ -75,7 +75,7 @@ lorekit install --global      # set it up for every project
 
 In a TTY it prompts for the scope (and for `--endpoint` / `--token` if missing).
 Flags: `--project` / `--global` pick the scope non-interactively; `--no-hooks`
-installs the skill + MCP only (memory stays model-invoked); `--yes` runs
+installs the skills + MCP only (memory stays model-invoked); `--yes` runs
 non-interactively (endpoint required via flag/env; scope defaults to project);
 `--force` overwrites an existing skill copy. Re-running is idempotent — the hook
 entries are updated in place, never duplicated.
@@ -444,13 +444,53 @@ Two config layers decide the mode:
 - **Repo / team** — a `.lorekit.json` at the repo root (and/or the existing
   `lorekit` block in `.mcp.json` for the connection).
 
-Both files share one schema:
+Both files share this schema — all fields optional:
 
 ```jsonc
+// .lorekit.json  (repo root — safe to commit, no secrets)
+// ~/.lorekit/config.json  (user/machine — personal overrides, not committed)
 {
-  "mode": "local",        // select a mode (off | local | remote)
-  "store": ".lorekit",    // project-tier store dir (relative to repo root, or absolute)
-  "deny": ["remote"]      // forbid modes outright — deny always wins
+  // ── Mode & store ───────────────────────────────────────────────────────────
+  "mode": "local",         // off | local | remote
+  "store": ".lorekit",     // project-tier store path (relative to root, or absolute)
+  "deny": ["remote"],      // forbid modes outright — deny always wins, union across layers
+
+  // ── Connection (repo config only — no token, safe to commit) ───────────────
+  "mcp.endpoint": "https://<ref>.supabase.co/functions/v1/mcp",
+                           // committable MCP URL without token; token still comes
+                           // from .mcp.json or LOREKIT_TOKEN env var
+
+  // ── Write behaviour ────────────────────────────────────────────────────────
+  "tags.default": ["team", "project::my-project"],
+                           // tags appended to every memory.write from this repo/user
+                           // both layers merged: repo tags first, then user tags
+
+  "scope.defaults": {
+    "repo::owner/name":     { "tags": ["team"] },
+    "branch::owner/name::": { "tags": ["ephemeral"] }
+  },
+                           // per-scope tag defaults applied to writes whose scope
+                           // starts with the key; matched by prefix (no wildcards needed)
+                           // repo config only — this is a team-level write policy
+
+  // ── Hook behaviour ─────────────────────────────────────────────────────────
+  "hooks.disabled": ["Stop"],
+                           // suppress specific hook events; union across layers
+                           // values: "SessionStart" | "PostToolUseFailure" | "Stop"
+
+  "hooks.adapter": "claude",
+                           // explicit adapter when auto-detection is ambiguous
+                           // values: "claude" | "cursor" | "codex"
+                           // repo wins over user
+
+  // ── Telemetry ──────────────────────────────────────────────────────────────
+  "telemetry.disabled": true,
+                           // team-level opt-out for orgs with a no-telemetry policy
+                           // env LOREKIT_TELEMETRY=0 always wins if set
+
+  // ── Dedupe threshold ───────────────────────────────────────────────────────
+  "dedupe.threshold": 0.8  // Jaccard similarity cutoff for `lorekit dedupe`
+                           // --threshold flag wins when passed explicitly
 }
 ```
 
@@ -488,7 +528,7 @@ active deny constraints.
 | `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
 | `--apply` | Apply the migration — alias of `--yes` (`migrate`) |
 | `-y, --yes` | Non-interactive / apply; never prompt |
-| `--no-hooks` | Skip wiring the lifecycle hooks; skill + MCP only (`install`) |
+| `--no-hooks` | Skip wiring the lifecycle hooks; skills + MCP only (`install`) |
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe`) |

package/bin/lorekit.mjs

@@ -34,7 +34,7 @@ ${c.bold('Usage')}
 
 ${c.bold('Commands')}
   install     Scaffold the lorekit-memory + lorekit-setup skills, wire the
-              LoreKit MCP server, and install the deterministic hooks (lessons
+              LoreKit MCP server, and install the deterministic hooks (memories
               on SessionStart, a nudge on tool failure + at Stop). Prompts to
               install for this project (.claude) or globally for every project
               (~/.claude); --project / --global choose non-interactively,
@@ -44,39 +44,39 @@ ${c.bold('Commands')}
               other servers, hooks, and settings are left untouched. Prompts
               project vs global; --project / --global choose non-interactively.
   doctor      Verify the skill install, MCP connectivity, token, and scope.
-  list (ls)   List the lessons that apply to the current directory, split into
+  list (ls)   List the memories that apply to the current directory, split into
               an Offline section (local .lorekit/ + ~/.lorekit/) and a Remote
               section (hosted MCP). Groups by scope (project/branch/repo/global).
               --json for scripting, --scope <s> to narrow.
-  search      Full-text search the applicable lessons across both stores and all
+  search      Full-text search the applicable memories across both stores and all
     (grep)    scopes (case-insensitive, literal substring over key + value),
               rendered in the same Offline/Remote split. --json, --scope <s>.
-  show        Inspect one lesson in full: its complete value, scope, key, updated
+  show        Inspect one memory in full: its complete value, scope, key, updated
               date, tags, and which store(s) it lives in (noting any divergence
               when it is in both). --json. Usage: show <scope> <key>.
-  stats       Count the applicable lessons per scope and per store (offline vs
+  stats       Count the applicable memories per scope and per store (offline vs
               remote), with per-store and grand totals, in the same Offline/
               Remote split. --json, --scope <s>.
-  scopes      Store-wide inventory of EVERY distinct scope that holds lessons,
-              with a lesson count per scope — not cwd-scoped like the commands
+  scopes      Store-wide inventory of EVERY distinct scope that holds memories,
+              with a memory count per scope — not cwd-scoped like the commands
               above (it lists scopes anywhere in the store). Offline is exact;
               the remote can't enumerate scopes (honest note). --json, --scope <s>.
   diff        Compare the offline and remote stores for the applicable scopes and
               report divergence: local-only, remote-only, and conflicting keys
               (grouped by scope). Needs both stores readable. --json, --scope <s>.
   tree        Show the injected scopes (project → branch → repo → global) as a precedence
-    (resolve) hierarchy and mark, per key, which scope's lesson WINS and which are
+    (resolve) hierarchy and mark, per key, which scope's memory WINS and which are
               shadowed — the real hook-resolution order. --json, --scope <s>.
-  lint        Flag low-quality lessons (empty/short/untrimmed value, empty key,
+  lint        Flag low-quality memories (empty/short/untrimmed value, empty key,
               malformed scope) across the applicable scopes and both stores. Exits
               non-zero when issues are found (CI gate). --json, --scope <s>.
-  dedupe      Find likely-duplicate lessons via a zero-dep word-overlap HEURISTIC
+  dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
   migrate     Relocate a LoreKit-format local store into the current layout.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
-              JSON on stdin and injects lessons or a retrospective nudge.
+              JSON on stdin and injects memories or a retrospective nudge.
               Not run by hand — wired into a plugin's hook config.
   mcp         Local stdio MCP server. Exposes the memory.* tools backed by the
               resolved store (local .lorekit/ offline, or remote passthrough) so
@@ -143,7 +143,7 @@ ${c.bold('Usage')}
 
 Scaffolds the lorekit-memory (runtime read/write) and lorekit-setup (loop
 authoring) skills, adds the LoreKit MCP server, and wires the deterministic
-hooks (lessons on SessionStart, a nudge on tool failure + at Stop).
+hooks (memories on SessionStart, a nudge on tool failure + at Stop).
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -199,12 +199,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli doctor --mode local
 `,
-  list: `${c.bold('lorekit list')} — list the lessons that apply to the current directory ${c.dim('(alias: ls)')}
+  list: `${c.bold('lorekit list')} — list the memories that apply to the current directory ${c.dim('(alias: ls)')}
 
 ${c.bold('Usage')}
   npx @lorekit/cli list [options]
 
-Shows the lessons for the scopes that resolve for the current directory
+Shows the memories for the scopes that resolve for the current directory
 (project/branch/repo/global), split into an Offline section (the local
 .lorekit/ + ~/.lorekit/ two-tier store) and a Remote section (the hosted MCP
 server). When no remote token/endpoint is configured the Remote section is a
@@ -223,14 +223,14 @@ ${c.bold('Examples')}
   npx @lorekit/cli list --json
   npx @lorekit/cli list --scope global
 `,
-  search: `${c.bold('lorekit search')} — full-text search the applicable lessons ${c.dim('(alias: grep)')}
+  search: `${c.bold('lorekit search')} — full-text search the applicable memories ${c.dim('(alias: grep)')}
 
 ${c.bold('Usage')}
   npx @lorekit/cli search <query> [options]
 
-Searches every lesson for the current directory's scopes (project/branch/repo/
+Searches every memory for the current directory's scopes (project/branch/repo/
 global) across both stores, matching the query case-insensitively as a LITERAL
-substring of a lesson's key or value (regex metacharacters are matched verbatim,
+substring of a memory's key or value (regex metacharacters are matched verbatim,
 never interpreted). Results are shown in the same Offline / Remote split as
 \`list\`; an unconfigured remote degrades to a short note, never an error.
 
@@ -247,12 +247,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli grep "flaky test" --json
   npx @lorekit/cli search migration --scope global
 `,
-  show: `${c.bold('lorekit show')} — inspect one lesson in full
+  show: `${c.bold('lorekit show')} — inspect one memory in full
 
 ${c.bold('Usage')}
   npx @lorekit/cli show <scope> <key> [options]
 
-Prints one lesson's complete (untruncated) value, scope, key, updated date, tags,
+Prints one memory's complete (untruncated) value, scope, key, updated date, tags,
 and which store(s) it lives in. If the same scope::key exists in both the offline
 and remote stores, both are shown and any divergence in their values is flagged.
 Exits non-zero when the key is found in neither readable store.
@@ -268,12 +268,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli show global prefer-guard-clauses
   npx @lorekit/cli show project::widget build-flags --json
 `,
-  stats: `${c.bold('lorekit stats')} — count the applicable lessons per scope and per store
+  stats: `${c.bold('lorekit stats')} — count the applicable memories per scope and per store
 
 ${c.bold('Usage')}
   npx @lorekit/cli stats [options]
 
-Shows how many lessons apply to the current directory's scopes (project/branch/
+Shows how many memories apply to the current directory's scopes (project/branch/
 repo/global), broken down per scope and per store (Offline = the local .lorekit/
 + ~/.lorekit/ two-tier store; Remote = the hosted MCP server), with per-store and
 grand totals. An unconfigured remote degrades to a short note, never an error.
@@ -296,13 +296,13 @@ ${c.bold('Examples')}
 ${c.bold('Usage')}
   npx @lorekit/cli scopes [options]
 
-Lists EVERY distinct scope present in the store, with a lesson count per scope,
+Lists EVERY distinct scope present in the store, with a memory count per scope,
 in the same Offline / Remote split as the other read commands. Unlike \`list\` /
 \`stats\` (which only see the scopes that resolve for the current directory), this
 is a full inventory — it surfaces scopes anywhere in the store, regardless of the
 current directory.
 
-Offline counts are exact: each scope is read from the lesson files' frontmatter,
+Offline counts are exact: each scope is read from the memory files' frontmatter,
 not reverse-mapped from the directory layout. The Remote section is always a
 short note: the hosted MCP surface has no "list all scopes" tool (every read tool
 requires a scope), so a remote inventory isn't possible — never an error (exit 0).
@@ -344,16 +344,16 @@ ${c.bold('Examples')}
   npx @lorekit/cli diff --json
   npx @lorekit/cli diff --scope global
 `,
-  tree: `${c.bold('lorekit tree')} — show the scope precedence hierarchy and which lesson wins ${c.dim('(alias: resolve)')}
+  tree: `${c.bold('lorekit tree')} — show the scope precedence hierarchy and which memory wins ${c.dim('(alias: resolve)')}
 
 ${c.bold('Usage')}
   npx @lorekit/cli tree [options]
 
 Shows the scopes the hooks actually inject for the current directory — project,
 branch, repo, global, in precedence order (most-specific first) — and marks, for any key
-present at more than one scope, which scope's lesson WINS and which are shadowed.
+present at more than one scope, which scope's memory WINS and which are shadowed.
 This mirrors the SessionStart hook's resolution exactly (a more-specific scope
-overrides a broader scope's same-key lesson). Resolved independently per store,
+overrides a broader scope's same-key memory). Resolved independently per store,
 in the same Offline / Remote split.
 
 ${c.bold('Options')}
@@ -368,12 +368,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli tree
   npx @lorekit/cli resolve --json
 `,
-  lint: `${c.bold('lorekit lint')} — flag low-quality lessons across the applicable scopes
+  lint: `${c.bold('lorekit lint')} — flag low-quality memories across the applicable scopes
 
 ${c.bold('Usage')}
   npx @lorekit/cli lint [options]
 
-Checks every lesson for the current directory's scopes (project/branch/repo/
+Checks every memory for the current directory's scopes (project/branch/repo/
 global), across both stores, against a small set of quality rules: empty or
 whitespace-only value, suspiciously short value, untrimmed value, empty key, and
 malformed scope (e.g. a single \`:\` where \`::\` is expected). Each finding names
@@ -393,12 +393,12 @@ ${c.bold('Examples')}
   npx @lorekit/cli lint --json
   npx @lorekit/cli lint --scope global
 `,
-  dedupe: `${c.bold('lorekit dedupe')} — find likely-duplicate lessons (heuristic)
+  dedupe: `${c.bold('lorekit dedupe')} — find likely-duplicate memories (heuristic)
 
 ${c.bold('Usage')}
   npx @lorekit/cli dedupe [options]
 
-Groups lessons whose values overlap heavily into duplicate clusters, per store,
+Groups memories whose values overlap heavily into duplicate clusters, per store,
 across the current directory's scopes. The similarity signal is a zero-dependency
 HEURISTIC — Jaccard overlap of lowercased word tokens, not a semantic/embedding
 measure — so it surfaces candidates for a human to review, and can both miss
@@ -440,7 +440,7 @@ ${c.bold('Examples')}
 ${c.bold('Usage')}
   lorekit hook --adapter <claude|cursor|codex> --event <name> [--dir <path>]
 
-Machine-facing: reads the host's JSON on stdin and injects lessons or a
+Machine-facing: reads the host's JSON on stdin and injects memories or a
 retrospective nudge on stdout, always exiting 0. Wired into a plugin's hook
 config by \`lorekit install\` — not run by hand.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/config.mjs

@@ -345,8 +345,9 @@ export function tokenKind(token) {
 
 // For hooks: resolve the connection closest-scope first — the project's
 // .mcp.json (a project install), then the global ~/.claude.json (a global
-// install), then env. `splitEndpoint` is passed in to avoid a circular import
-// with mcp.mjs.
+// install), then the `mcp.endpoint` field in .lorekit.json (committable URL
+// without token — safe for VCS), then env. `splitEndpoint` is passed in to
+// avoid a circular import with mcp.mjs.
 export function resolveProjectConnection(root, splitEndpoint) {
   const sources = [readLorekitServer(root), readServerFromFile(mcpConfigPath(root, 'global'))];
   for (const configured of sources) {
@@ -360,5 +361,33 @@ export function resolveProjectConnection(root, splitEndpoint) {
       }
     }
   }
+
+  // Fallback: `mcp.endpoint` in .lorekit.json — a committable URL without token.
+  // Token still comes from .mcp.json or LOREKIT_TOKEN.
+  const lorekitJson = readLorekitJson(root);
+  const committedEndpoint =
+    lorekitJson && typeof lorekitJson['mcp.endpoint'] === 'string'
+      ? lorekitJson['mcp.endpoint'].trim()
+      : null;
+  if (committedEndpoint && !committedEndpoint.includes('<project-ref>')) {
+    return {
+      endpoint: committedEndpoint,
+      token: process.env.LOREKIT_TOKEN || null,
+    };
+  }
+
   return resolveConnection({});
 }
+
+// Read .lorekit.json from the repo root without throwing. Exported so other
+// CLI modules can read per-repo config without duplicating the same try/catch.
+// control.mjs uses its own internal readJson(file) for historical reasons and
+// does not import this — that is a known duplication, not a bug.
+export function readLorekitJson(root) {
+  const file = path.join(root, '.lorekit.json');
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8')) || {};
+  } catch {
+    return {};
+  }
+}

package/src/control.mjs

@@ -1,5 +1,11 @@
 // The control model: decide the memory mode (off | local | remote), the store
-// target, who decided, and which deny constraints are active.
+// target, who decided, and which deny constraints are active. Also resolves
+// write-behaviour properties from the config layers:
+//
+//   scope.defaults  — map of scope-prefix → { tags } applied to every matching write
+//   tags.default    — array of tags appended to every write (both layers merged)
+//   hooks.disabled  — array of hook event names to suppress (e.g. ["Stop"])
+//   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
 // Two layers of config, two kinds of statement:
 //   - a SELECT (`mode`) chooses a mode within what is allowed;
@@ -104,7 +110,44 @@ export function resolveControl({
     storeTarget = connection.endpoint || null;
   }
 
-  return { mode: chosen.mode, storeTarget, decidedBy, denies, connection };
+  // 5. Write-behaviour properties resolved from config layers.
+  //    `tags.default` — both layers merged, user supplements repo (no override).
+  const tagsDefault = [
+    ...asList(repoConfig['tags.default']),
+    ...asList(userConfig['tags.default']),
+  ].filter((t) => typeof t === 'string' && t.length > 0);
+
+  // `scope.defaults` — repo layer only (team-scoped write policy).
+  //    Schema: { "<scope-prefix>": { "tags": [...] } }
+  //    Matched against a write's resolved scope using startsWith — no glob dep.
+  const scopeDefaults =
+    repoConfig['scope.defaults'] && typeof repoConfig['scope.defaults'] === 'object'
+      ? repoConfig['scope.defaults']
+      : null;
+
+  // `hooks.disabled` — union of both layers (either layer can suppress an event).
+  const hooksDisabled = new Set([
+    ...asList(repoConfig['hooks.disabled']),
+    ...asList(userConfig['hooks.disabled']),
+  ]);
+
+  // `hooks.adapter` — repo layer wins over user layer (explicit project override).
+  const hooksAdapter =
+    (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
+    (typeof userConfig['hooks.adapter'] === 'string' && userConfig['hooks.adapter'].trim()) ||
+    null;
+
+  return {
+    mode: chosen.mode,
+    storeTarget,
+    decidedBy,
+    denies,
+    connection,
+    tagsDefault,
+    scopeDefaults,
+    hooksDisabled,
+    hooksAdapter,
+  };
 }
 
 // The per-repo project-tier directory: $LOREKIT_STORE, else a `store` override

package/src/core/lessons.mjs

@@ -55,7 +55,7 @@ export async function fetchLessons(store, cwd) {
 export function formatLessons(lessons, scope) {
   if (!lessons || lessons.length === 0) return null;
   const header =
-    `LoreKit — ${lessons.length} shared lesson(s) for ${scope.repoScope || 'this workspace'}. ` +
+    `LoreKit — ${lessons.length} shared ${lessons.length === 1 ? 'memory' : 'memories'} for ${scope.repoScope || 'this workspace'}. ` +
     `Treat as considerations, not rules; trust the current code if they conflict.`;
   const body = lessons
     .map((l) => {
@@ -110,7 +110,7 @@ export function formatRelevantLessons(lessons) {
   if (!lessons || lessons.length === 0) return null;
   const header =
     `LoreKit — you've hit something like this before. ${lessons.length} related ` +
-    'lesson(s) (considerations, not rules; trust the current code if they conflict):';
+    `${lessons.length === 1 ? 'memory' : 'memories'} (considerations, not rules; trust the current code if they conflict):`;
   const body = lessons
     .map((l) => {
       const first = String(l.value || '').split('\n')[0].slice(0, 300);
@@ -120,25 +120,52 @@ export function formatRelevantLessons(lessons) {
   return `${header}\n${body}`;
 }
 
+// Build a tags hint string from config-resolved tags and scope defaults. Returns
+// "" when there are no configured tags (no hint appended to the nudge).
+function tagsHint(writeScope, { tagsDefault = [], scopeDefaults = null } = {}) {
+  const tags = [...tagsDefault];
+  if (scopeDefaults) {
+    for (const [prefix, cfg] of Object.entries(scopeDefaults)) {
+      if (
+        writeScope === prefix ||
+        writeScope.startsWith(prefix.endsWith('::') ? prefix : prefix + '::')
+      ) {
+        for (const t of Array.isArray(cfg.tags) ? cfg.tags : []) {
+          if (typeof t === 'string' && t.length > 0 && !tags.includes(t)) tags.push(t);
+        }
+      }
+    }
+  }
+  if (tags.length === 0) return '';
+  return ` Include tags: [${tags.map((t) => JSON.stringify(t)).join(', ')}].`;
+}
+
 // The retrospective nudge emitted at end-of-turn (one-shot per session).
-export function retrospectiveNudge(scope) {
+// `control` is the resolved control object (optional) — carries tagsDefault and
+// scopeDefaults when the repo/user config defines them.
+export function retrospectiveNudge(scope, control) {
   const writeScope = scope.repoScope || 'global';
+  const hint = tagsHint(writeScope, control);
   return (
     'LoreKit retrospective: if this session hit a stuck loop, a repeated ' +
     'command failure, a surprising gotcha, a near-miss, or a wrong assumption ' +
     'that cost time, record it now via the lorekit-memory skill ' +
-    `(memory.write to ${writeScope}, phrased as an observation). ` +
+    `(memory.write to ${writeScope}, phrased as an observation).${hint} ` +
     'If nothing was durable, do nothing.'
   );
 }
 
 // The nudge emitted when a tool failure is detected.
-export function failureNudge(toolName, scope) {
+// `control` is the resolved control object (optional) — carries tagsDefault and
+// scopeDefaults when the repo/user config defines them.
+export function failureNudge(toolName, scope, control) {
   const writeScope = scope.repoScope || 'global';
+  const hint = tagsHint(writeScope, control);
+  const suffix = hint ? `${hint} So the next run avoids it.` : 'so the next run avoids it.';
   return (
     `LoreKit: the last ${toolName} call failed. If this is a recurring or ` +
-    'non-obvious failure, consider recording the fix as a lesson via ' +
-    `lorekit-memory (memory.write to ${writeScope}), so the next run avoids it.`
+    'non-obvious failure, consider recording the fix as a memory via ' +
+    `lorekit-memory (memory.write to ${writeScope}) — ${suffix}`
   );
 }
 

package/src/dedupe.mjs

@@ -11,7 +11,7 @@
 // Same Offline / Remote split and graceful degradation as `list`. Read-only.
 // Human-facing, so the bin wraps it in `traceCommand`.
 import process from 'node:process';
-import { resolveProjectRoot } from './config.mjs';
+import { resolveProjectRoot, readLorekitJson } from './config.mjs';
 import { deriveScope } from './scope.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
@@ -29,6 +29,16 @@ export function parseThreshold(raw) {
   return Math.min(1, Math.max(0, n));
 }
 
+// Read `dedupe.threshold` from .lorekit.json (non-throwing). Returns the
+// repo-default threshold, or undefined when not configured.
+export function repoThreshold(root) {
+  const cfg = readLorekitJson(root);
+  if (cfg['dedupe.threshold'] !== undefined) {
+    return parseThreshold(cfg['dedupe.threshold']);
+  }
+  return undefined;
+}
+
 // Flatten a `gather()` result into one entry list (each entry keeps its scope)
 // for cross-scope clustering, plus the scopes whose read errored (they can't be
 // clustered and are surfaced, not silently dropped).
@@ -50,7 +60,11 @@ export async function dedupe(args) {
   const env = { ...process.env };
   if (args.store) env.LOREKIT_STORE = args.store;
 
-  const threshold = parseThreshold(args.threshold);
+  // Threshold precedence: --threshold flag > dedupe.threshold in .lorekit.json > default (0.8).
+  const threshold =
+    args.threshold !== undefined
+      ? parseThreshold(args.threshold)
+      : (repoThreshold(root) ?? DEFAULT_THRESHOLD);
   const scopeInfo = deriveScope(root);
   // Default to every applicable scope; `--scope <s>` narrows to one.
   const scopes = args.scope && typeof args.scope === 'string' ? [args.scope] : scopeList(scopeInfo);
@@ -152,7 +166,7 @@ function renderDedupeSection(header, section) {
       cluster.minSimilarity === cluster.maxSimilarity
         ? cluster.minSimilarity.toFixed(2)
         : `${cluster.minSimilarity.toFixed(2)}–${cluster.maxSimilarity.toFixed(2)}`;
-    log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${cluster.size} lessons, similarity ${range})`)}`);
+    log(`  ${c.yellow('•')} cluster ${n} ${c.dim(`(${cluster.size} memories, similarity ${range})`)}`);
     for (const m of cluster.members) {
       log(`    ${c.cyan('-')} ${m.scope}::${m.key}`);
     }

package/src/doctor.mjs

@@ -11,6 +11,7 @@ import {
   readLorekitServer,
   readMcpConfig,
   tokenKind,
+  readLorekitJson,
 } from './config.mjs';
 import { splitEndpoint } from './mcp.mjs';
 import { deriveScope } from './scope.mjs';
@@ -82,9 +83,24 @@ export async function doctor(args) {
   const scope = deriveScope(root);
   if (scope.hasRemote) {
     record('info', 'read scope', scope.readOrder.join('  →  '));
-    record('info', 'write scope', `${scope.repoScope} (default for "went wrong" lessons)`);
+    record('info', 'write scope', `${scope.repoScope} (default for "went wrong" memories)`);
   } else {
-    record('warn', 'scope', 'no git remote here — lessons fall back to global');
+    record('warn', 'scope', 'no git remote here — memories fall back to global');
+  }
+
+  // 6. doctor.require — committed list of checks that MUST pass.
+  //    Useful as a CI gate: any check in the list that did not pass causes a failure.
+  const lorekitJson = readLorekitJson(root);
+  const required = (Array.isArray(lorekitJson['doctor.require']) ? lorekitJson['doctor.require'] : [])
+    .filter((r) => typeof r === 'string');
+  for (const req of required) {
+    // A required check passes if its label is NOT in failedChecks (it either
+    // passed or was never run; unknown labels get a pass to avoid false failures).
+    if (failedChecks.includes(req)) {
+      record('fail', 'doctor.require', `required check failed: ${req}`);
+    } else {
+      record('pass', 'doctor.require', `required check passed: ${req}`);
+    }
   }
 
   // Summary.
@@ -128,7 +144,8 @@ async function checkLocal(control, root, args, record) {
 
   // Home tier — per-user, cross-repo, always available.
   record('pass', 'home store', prettyPath(store.homeDir));
-  record('info', 'home entries', `${await store.home.count(scopes)} lesson(s)`);
+  const homeCount = await store.home.count(scopes);
+  record('info', 'home entries', `${homeCount} ${homeCount === 1 ? 'memory' : 'memories'}`);
 
   // Project tier — opt-in; active only when its directory exists.
   const projRel = path.relative(root, store.projectDir) || store.projectDir;
@@ -137,12 +154,13 @@ async function checkLocal(control, root, args, record) {
       ? 'committed — shared with the team'
       : 'gitignored — private to your checkout';
     record('pass', 'project store', projRel);
-    record('info', 'project entries', `${await store.project.count(scopes)} lesson(s) — ${sharing}`);
+    const projCount = await store.project.count(scopes);
+    record('info', 'project entries', `${projCount} ${projCount === 1 ? 'memory' : 'memories'} — ${sharing}`);
   } else {
     record(
       'info',
       'project store',
-      `${projRel} — not opted-in (create it to persist repo/branch lessons here)`,
+      `${projRel} — not opted-in (create it to persist repo/branch memories here)`,
     );
   }
 

package/src/hook.mjs

@@ -83,6 +83,9 @@ async function run(args) {
   const control = loadControl(root);
   if (control.mode === 'off') return 0;
 
+  // `hooks.disabled` — skip the event if this event name is suppressed by config.
+  if (control.hooksDisabled && control.hooksDisabled.has(event)) return 0;
+
   const emit = (text) => {
     if (text) process.stdout.write(adapter.emit(event, text));
   };
@@ -114,14 +117,14 @@ async function run(args) {
     } catch {
       relevant = null; // never let a lesson lookup break the failure nudge
     }
-    const nudge = failureNudge(parsed.toolName, scope);
+    const nudge = failureNudge(parsed.toolName, scope, control);
     emit(relevant ? `${relevant}\n\n${nudge}` : nudge);
     return 0;
   }
 
   if (intent === 'retrospective') {
     if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
-    emit(retrospectiveNudge(scope));
+    emit(retrospectiveNudge(scope, control));
     return 0;
   }
 

package/src/install.mjs

@@ -113,7 +113,7 @@ export async function install(args) {
   status('pass', mcpLabel, `${existed ? 'updated' : 'created'} lorekit server → ${display(file)}`);
 
   if (!wireHooks) {
-    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but lessons are model-invoked only');
+    status('info', 'hooks', 'skipped (--no-hooks) — the skill still works, but memories are model-invoked only');
   } else {
     const n = hooks.added + hooks.updated;
     const hookState =
@@ -127,9 +127,9 @@ export async function install(args) {
   if (kind === 'none') {
     status('warn', 'token', 'none configured — reads/writes will fail until a token is set');
   } else if (kind === 'read-only') {
-    status('warn', 'token', 'read-only (lk_ro_*) — the skill can read lessons but not write them');
+    status('warn', 'token', 'read-only (lk_ro_*) — the skill can read memories but not write them');
   } else if (kind === 'write-only') {
-    status('warn', 'token', 'write-only (lk_wo_*) — the skill can write lessons but not read them');
+    status('warn', 'token', 'write-only (lk_wo_*) — the skill can write memories but not read them');
   } else if (kind === 'unknown') {
     status('warn', 'token', 'unrecognized prefix — expected lk_rw_*, lk_ro_*, or lk_wo_*');
   } else {
@@ -140,7 +140,7 @@ export async function install(args) {
   if (gitScope.hasRemote) {
     status('info', 'scope', `${gitScope.repoScope}${gitScope.branchScope ? `  ·  ${gitScope.branchScope}` : ''}`);
   } else {
-    status('warn', 'scope', 'no git remote — lessons will fall back to global');
+    status('warn', 'scope', 'no git remote — memories will fall back to global');
   }
 
   log(`\n  Next: ${c.cyan('npx @lorekit/cli doctor')} to verify the connection.`);

package/src/lessons-view.mjs

@@ -429,9 +429,9 @@ export function renderSection(header, section) {
 
   const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
   if (!printable.length) {
-    // `header.empty` lets `search` say "no lessons match" where `list` says
-    // "no lessons found"; both are the same empty-section case.
-    log(`  ${c.dim(header.empty || 'no lessons found in the applicable scopes')}`);
+    // `header.empty` lets `search` say "no memories match" where `list` says
+    // "no memories found"; both are the same empty-section case.
+    log(`  ${c.dim(header.empty || 'no memories found in the applicable scopes')}`);
     return;
   }
 

package/src/list.mjs

@@ -70,7 +70,7 @@ export async function list(args) {
   if (args.json) {
     log(JSON.stringify(buildJson({ root, scopes, offlineSection, remoteSection }), null, 2));
   } else {
-    heading('LoreKit lessons');
+    heading('LoreKit memories');
     log(`  project: ${c.dim(root)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
 

package/src/mcp-server.mjs

@@ -36,7 +36,7 @@ const SERVER_INFO = { name: 'lorekit-local', version: '1.0.0' };
 export const MEMORY_TOOL_DEFS = [
   {
     name: 'memory.write',
-    description: 'Store or update a lesson',
+    description: 'Store or update a memory',
     inputSchema: {
       type: 'object',
       required: ['scope', 'key', 'value'],
@@ -58,24 +58,24 @@ export const MEMORY_TOOL_DEFS = [
   },
   {
     name: 'memory.read',
-    description: 'Read a lesson by scope and key',
+    description: 'Read a memory by scope and key',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
   {
     name: 'memory.list',
-    description: 'List lessons for a scope',
+    description: 'List memories for a scope',
     inputSchema: { type: 'object', required: ['scope'] },
   },
   {
     name: 'memory.search',
-    description: 'Keyword search across lessons',
+    description: 'Keyword search across memories',
     inputSchema: { type: 'object', required: ['q'] },
   },
   {
     name: 'memory.delete',
     description:
-      'Soft-archive a lesson (default) or hard-delete it (force: true). ' +
-      'Archived lessons are hidden from reads but can be restored.',
+      'Soft-archive a memory (default) or hard-delete it (force: true). ' +
+      'Archived memories are hidden from reads but can be restored.',
     inputSchema: {
       type: 'object',
       required: ['scope', 'key'],
@@ -88,7 +88,7 @@ export const MEMORY_TOOL_DEFS = [
   },
   {
     name: 'memory.archive',
-    description: 'Soft-archive a lesson. Hidden from reads but restorable.',
+    description: 'Soft-archive a memory. Hidden from reads but restorable.',
     inputSchema: { type: 'object', required: ['scope', 'key'] },
   },
 ];

package/src/scopes.mjs

@@ -113,7 +113,7 @@ function renderScopesSection(header, section) {
   }
 
   if (!section.scopes.length) {
-    log(`  ${c.dim('no scopes found — the store holds no lessons')}`);
+    log(`  ${c.dim('no scopes found — the store holds no memories')}`);
     return;
   }
 

package/src/search.mjs

@@ -77,7 +77,7 @@ export async function search(args) {
     log(`  query:   ${c.dim(query)}`);
     log(`  scopes:  ${scopes.join('  →  ')}`);
 
-    const empty = 'no lessons match';
+    const empty = 'no memories match';
     renderSection({ title: 'Offline', empty }, offlineSection);
     renderSection(
       { title: 'Remote', subtitle: remoteAvailable ? connection.endpoint : undefined, empty },

package/src/show.mjs

@@ -78,7 +78,7 @@ export async function show(args) {
   if (args.json) {
     log(JSON.stringify(buildJson({ scope, key, offline, remote_, diverged }), null, 2));
   } else {
-    heading('LoreKit lesson');
+    heading('LoreKit memory');
     log(`  scope:  ${c.dim(scope)}`);
     log(`  key:    ${c.dim(key)}`);
 
@@ -95,7 +95,7 @@ export async function show(args) {
     }
     if (!found) {
       log('');
-      log(`  ${c.dim(`no lesson found for ${scope}::${key} in the readable store(s)`)}`);
+      log(`  ${c.dim(`no memory found for ${scope}::${key} in the readable store(s)`)}`);
     }
     log('');
   }

package/src/telemetry.mjs

@@ -25,6 +25,7 @@
 
 import process from 'node:process';
 import { TELEMETRY_TOKEN } from './telemetry-token.mjs';
+import { readLorekitJson } from './config.mjs';
 
 // ── Baked-in defaults (public by design) ──────────────────────────────────────
 // The endpoint is a committed default; the token is injected at publish time
@@ -42,11 +43,13 @@ const OFF_VALUES = new Set(['0', 'off', 'false', 'no', 'disable', 'disabled']);
 // ── Config resolution ─────────────────────────────────────────────────────────
 
 /**
- * Resolve telemetry config from env + baked-in defaults.
+ * Resolve telemetry config from env + baked-in defaults + .lorekit.json.
  * Returns { enabled: false } when disabled or unconfigured, else the endpoint
  * and headers to export with.
+ * @param {object} [env]  defaults to process.env
+ * @param {object} [repoConfig]  pre-loaded .lorekit.json (optional; read from cwd if absent)
  */
-export function resolveTelemetryConfig(env = process.env) {
+export function resolveTelemetryConfig(env = process.env, repoConfig) {
   const optOut = env.LOREKIT_TELEMETRY;
   if (optOut !== undefined && OFF_VALUES.has(String(optOut).trim().toLowerCase())) {
     return { enabled: false };
@@ -57,6 +60,12 @@ export function resolveTelemetryConfig(env = process.env) {
   if (env.DO_NOT_TRACK && String(env.DO_NOT_TRACK).trim() === '1') {
     return { enabled: false };
   }
+  // `telemetry.disabled: true` in .lorekit.json — team-level opt-out committed
+  // to the repo. Checked after env overrides (env always wins).
+  const cfg = repoConfig !== undefined ? repoConfig : readLorekitJson(process.cwd());
+  if (cfg['telemetry.disabled'] === true) {
+    return { enabled: false };
+  }
 
   const endpoint = (env.OTEL_EXPORTER_OTLP_ENDPOINT || DEFAULT_ENDPOINT || '')
     .trim()

package/src/tree.mjs

@@ -107,7 +107,7 @@ function renderTreeSection(header, section) {
 
   const printable = (section.groups || []).filter((g) => g.entries.length || g.error);
   if (!printable.length) {
-    log(`  ${c.dim('no lessons found in the applicable scopes')}`);
+    log(`  ${c.dim('no memories found in the applicable scopes')}`);
     return;
   }