kodelyth-ecc 2.25.0 → 2.29.0

package/scripts/lib/state-store/index.js

@@ -3,7 +3,6 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const initSqlJs = require('sql.js');
 
 const { applyMigrations, getAppliedMigrations } = require('./migrations');
 const { createQueryApi } = require('./queries');
@@ -11,6 +10,40 @@ const { assertValidEntity, validateEntity } = require('./schema');
 
 const DEFAULT_STATE_STORE_RELATIVE_PATH = path.join('.claude', 'ecc', 'state.db');
 
+// sql.js is OPTIONAL. It powers the session store, the status DB, and the
+// skill-evolution tracker — not the core (memory, RTK, Terse, codebase graph),
+// which stay pure-JS and need nothing. It used to be required at module load, so
+// importing state-store threw "Cannot find module 'sql.js'" for every install
+// that did not have it (which, since it was never a declared dependency, was all
+// of them) — before any caller's try/catch could run. Load it lazily and turn a
+// missing module into a clean, catchable error instead of an import-time crash.
+function loadSqlJs() {
+  try {
+    return require('sql.js');
+  } catch (cause) {
+    const err = new Error(
+      'SQLite support is unavailable: the optional dependency "sql.js" is not installed. ' +
+      'Install it (npm i sql.js, or reinstall kodelyth-ecc) to enable the session store, ' +
+      'status DB, and skill-evolution tracker. Core memory, RTK, Terse, and the codebase ' +
+      'graph do not need it.'
+    );
+    err.code = 'ECC_SQLITE_UNAVAILABLE';
+    err.cause = cause;
+    throw err;
+  }
+}
+
+// Non-throwing probe for callers and `doctor`: is the optional SQLite layer
+// usable on this install?
+function isSqliteAvailable() {
+  try {
+    require.resolve('sql.js');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function resolveStateStorePath(options = {}) {
   if (options.dbPath) {
     if (options.dbPath === ':memory:') {
@@ -163,6 +196,7 @@ async function openDatabase(SQL, dbPath) {
 
 async function createStateStore(options = {}) {
   const dbPath = resolveStateStorePath(options);
+  const initSqlJs = loadSqlJs();
   const SQL = await initSqlJs();
   const db = await openDatabase(SQL, dbPath);
   const appliedMigrations = applyMigrations(db);
@@ -188,4 +222,5 @@ module.exports = {
   DEFAULT_STATE_STORE_RELATIVE_PATH,
   createStateStore,
   resolveStateStorePath,
+  isSqliteAvailable,
 };

package/scripts/lib/state-store/schema.js

@@ -2,7 +2,11 @@
 
 const fs = require('fs');
 const path = require('path');
-const Ajv = require('ajv');
+// `ajv` is loaded lazily inside getAjv(), NOT at module top. It is an OPTIONAL
+// dependency (it validates the optional SQLite state-store's entities), and
+// requiring it here eagerly made importing state-store throw "Cannot find module
+// 'ajv'" on any install without it — which is every default install, and which
+// broke the pre-publish test step in CI. Same bug class as the sql.js one.
 
 const SCHEMA_PATH = path.join(__dirname, '..', '..', '..', 'schemas', 'state-store.schema.json');
 
@@ -33,6 +37,19 @@ function getAjv() {
     return cachedAjv;
   }
 
+  let Ajv;
+  try {
+    Ajv = require('ajv');
+  } catch (cause) {
+    const err = new Error(
+      'state-store schema validation needs the optional dependency "ajv", which is not installed. ' +
+      'Install it (or reinstall kodelyth-ecc) to enable session-store / status-DB validation.'
+    );
+    err.code = 'ECC_AJV_UNAVAILABLE';
+    err.cause = cause;
+    throw err;
+  }
+
   cachedAjv = new Ajv({
     allErrors: true,
     strict: false,

package/scripts/mcp/register-self.js

@@ -25,17 +25,14 @@ function claudeDesktopConfigPath() {
   return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
 }
 
-// MCP config paths for the non-Claude IDEs ECC can auto-wire. Every target below
-// uses the SAME `{ mcpServers: { <name>: { command, args, env } } }` shape as
-// Claude Code, so the hardened readConfig + registerInFile merge works for all of
-// them unchanged — only the file location differs. That is why memory and the
-// whole MCP tool surface, previously Claude-only, reach these IDEs out of the
-// box once this runs.
+// MCP config paths for the non-Claude IDEs ECC can auto-wire via JSON. Every
+// target below uses the SAME `{ mcpServers: { <name>: {...} } }` shape as Claude
+// Code (Kiro included — it is MCP-native), so the hardened readConfig +
+// registerInFile merge works unchanged; only the file location differs. Codex is
+// TOML and handled separately (registerCodexToml).
 //
-// Deliberately excluded (different format or fragile location — handled manually
-// for now, tracked as a follow-up):
-//   - Codex CLI      → ~/.codex/config.toml  (TOML, not JSON)
-//   - Cline / Roo    → VS Code globalStorage (editor-version-specific path)
+// Still manual (fragile, editor-version-specific path): Cline / Roo Code store
+// MCP settings in VS Code globalStorage, so ECC does not guess that path.
 function mcpPathsForTarget(target, cwd = process.cwd()) {
   const home = os.homedir();
   switch (target) {
@@ -53,24 +50,68 @@ function mcpPathsForTarget(target, cwd = process.cwd()) {
     case 'gemini-home':
     case 'gemini-project':
       return [path.join(home, '.gemini', 'settings.json')];
+    case 'kiro':
+    case 'kiro-project':
+      return [path.join(cwd, '.kiro', 'settings', 'mcp.json')];
+    case 'kiro-home':
+      return [path.join(home, '.kiro', 'settings', 'mcp.json')];
     default:
       return [];
   }
 }
 
+function codexConfigPath() {
+  return path.join(os.homedir(), '.codex', 'config.toml');
+}
+
+// Codex CLI stores MCP servers in TOML as [mcp_servers.<name>] tables. Without
+// pulling in a TOML parser, add our table only when it is absent (idempotent),
+// and otherwise leave the file exactly as it is. Appending a table is
+// order-independent in TOML, so this never clobbers existing servers or settings.
+function registerCodexToml(file, { dryRun = false } = {}) {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      return { file, action: 'error', error: `cannot read ${file}: ${err.message}` };
+    }
+  }
+  if (/\[mcp_servers\.(?:"?kodelyth-ecc"?)\]/.test(raw)) {
+    return { file, action: 'unchanged' };
+  }
+  const table = `\n[mcp_servers."${SERVER_NAME}"]\ncommand = "kodelythecc"\nargs = ["mcp"]\n`;
+  const next = raw.length && !raw.endsWith('\n') ? `${raw}\n${table}` : `${raw}${table}`;
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    safeFs.replaceFilePreservingMode(file, next);
+  }
+  return { file, action: 'added' };
+}
+
 // Returns the list of targets this module can auto-wire (for help text / docs).
 function supportedMcpTargets() {
-  return ['claude-code', 'cursor', 'windsurf', 'gemini-cli'];
+  return ['claude-code', 'cursor', 'windsurf', 'gemini-cli', 'kiro', 'codex'];
 }
 
-// Register ECC's MCP server for one install target. Reuses the same merge that
-// protects ~/.claude.json: absent files are created, present files are merged
-// without clobbering other servers, and an unparseable file is refused, never
-// overwritten. Never throws — a bad config for one IDE must not fail an install.
+// Register ECC's MCP server for one install target. JSON targets reuse the same
+// merge that protects ~/.claude.json (absent → created, present → merged without
+// clobbering, unparseable → refused); Codex uses the TOML writer above. Never
+// throws — a bad config for one IDE must not fail an install.
 function registerForTarget(target, { cwd = process.cwd(), log = () => {}, dryRun = false } = {}) {
+  if (target === 'codex' || target === 'codex-home') {
+    try {
+      const r = registerCodexToml(codexConfigPath(), { dryRun });
+      log(`  ${r.action}: ${r.file}`);
+      return [{ target, ...r }];
+    } catch (e) {
+      log(`  skipped codex: ${e.message}`);
+      return [{ target, file: codexConfigPath(), action: 'error', error: e.message }];
+    }
+  }
   const paths = mcpPathsForTarget(target, cwd);
   if (paths.length === 0) {
-    return [{ target, action: 'unsupported', reason: `no known JSON MCP config path for "${target}"` }];
+    return [{ target, action: 'unsupported', reason: `no known MCP config path for "${target}"` }];
   }
   const results = [];
   for (const p of paths) {
@@ -231,6 +272,8 @@ module.exports = {
   mcpPathsForTarget,
   supportedMcpTargets,
   registerForTarget,
+  registerCodexToml,
+  codexConfigPath,
   registerAll,
   unregisterAll,
   statusAll,

package/scripts/memory/cli.js

@@ -19,6 +19,7 @@ const path = require('path');
 const store   = require('./store');
 const { buildContextBlock } = require('./inject');
 const { extractCandidates } = require('./extract');
+const pending = require('./pending');
 
 function parseArgs(argv) {
   const args = argv.slice(2);
@@ -190,6 +191,40 @@ function main() {
       return;
     }
 
+    // ── Auto-capture review queue ────────────────────────────────────────────
+    // The Stop hook auto-extracts candidates from each session into the queue;
+    // these three commands are the consent gate that turns them into memories.
+    case 'list-pending':
+    case 'review-pending': {
+      const items = pending.listPending();
+      if (items.length === 0) { console.log('No memory candidates pending review.'); return; }
+      console.log(`${items.length} candidate(s) pending review:\n`);
+      items.forEach((c) => {
+        console.log(`[${c.id}] (score ${c.score ?? '-'})  ${c.problem}`);
+        console.log(`    tags:     ${(c.tags || []).join(', ') || '-'}`);
+        console.log(`    approach: ${String(c.approach).slice(0, 200)}`);
+        console.log('');
+      });
+      console.log('Confirm with: memory promote-pending <id|all>   ·   drop with: memory discard-pending <id|all>');
+      return;
+    }
+
+    case 'promote-pending': {
+      const sel = positional[0] || 'all';
+      const stored = pending.promotePending(sel === 'all' ? 'all' : sel);
+      if (stored.length === 0) { console.log('Nothing promoted (no matching pending candidate).'); return; }
+      console.log(`Stored ${stored.length} memor${stored.length === 1 ? 'y' : 'ies'}:`);
+      stored.forEach(m => console.log(`  ${m.id}  ${m.problem}`));
+      return;
+    }
+
+    case 'discard-pending': {
+      const sel = positional[0] || 'all';
+      const n = pending.discardPending(sel === 'all' ? 'all' : sel);
+      console.log(`Discarded ${n} pending candidate(s).`);
+      return;
+    }
+
     default:
       console.error(`Unknown command: ${cmd}`);
       help();

package/scripts/memory/embedding-providers/local-transformers.js

@@ -0,0 +1,44 @@
+// scripts/memory/embedding-providers/local-transformers.js
+//
+// Local, on-device embedding provider. Runs a small sentence-embedding model
+// through the OPTIONAL `@xenova/transformers` dependency (WASM/ONNX — no native
+// build). After the model is cached once, inference is fully on-device, so the
+// "100% local, zero-network" property holds at recall time; only the first-ever
+// load fetches the model.
+//
+// This module is required ONLY when the user has opted into embeddings
+// (KODELYTH_MEMORY_EMBEDDINGS=on). If the optional dependency is not installed,
+// the require throws and embeddings.getProvider() catches it and falls back to
+// BM25 — so a default install never needs this and never loads it.
+//
+// Not exercised by the CI suite (it needs the heavy optional dependency and a
+// model download); the fusion/gating logic it feeds IS covered, via a stub
+// provider, in tests/memory/embeddings.test.js.
+'use strict';
+
+const MODEL = process.env.KODELYTH_EMBEDDING_MODEL || 'Xenova/all-MiniLM-L6-v2';
+
+let _pipelinePromise = null;
+
+async function createProvider() {
+  // require is inside the function so a missing optional dependency surfaces to
+  // the caller (embeddings.getProvider) as a catchable error, not an import-time
+  // crash of the memory module.
+  const { pipeline } = require('@xenova/transformers');
+  if (!_pipelinePromise) {
+    _pipelinePromise = pipeline('feature-extraction', MODEL);
+  }
+  const extractor = await _pipelinePromise;
+  return {
+    model: MODEL,
+    async embed(text) {
+      if (!text) return null;
+      // Mean-pooled, L2-normalized sentence embedding — the standard recipe for
+      // all-MiniLM-style models. output.data is a Float32Array.
+      const output = await extractor(String(text), { pooling: 'mean', normalize: true });
+      return Array.from(output.data);
+    },
+  };
+}
+
+module.exports = { createProvider, MODEL };

package/scripts/memory/embeddings.js

@@ -0,0 +1,98 @@
+// scripts/memory/embeddings.js
+//
+// OPTIONAL, OFF BY DEFAULT semantic layer for memory recall. The default recall
+// path stays pure BM25 — sync, zero-dependency, zero-network — exactly as
+// advertised. This module only does anything when a user opts in
+// (KODELYTH_MEMORY_EMBEDDINGS=on) AND a local embedding provider is actually
+// available. If either is false, every function here degrades to "no semantics",
+// and recall falls back to BM25 unchanged.
+//
+// The provider is pluggable: the real one (scripts/memory/embedding-providers/
+// local-transformers.js) runs a local model via the optional `@xenova/
+// transformers` dependency, so inference is on-device. Tests inject a
+// deterministic stub instead, so the fusion/gating logic is verified without the
+// heavy dependency or a model download.
+'use strict';
+
+// Test seam: when set (including to null), overrides provider resolution.
+let _providerOverride;
+let _hasOverride = false;
+
+function _setProviderForTest(provider) { _providerOverride = provider; _hasOverride = true; }
+function _clearProviderForTest() { _providerOverride = undefined; _hasOverride = false; }
+
+// Off unless explicitly enabled. Keeps the default session zero-network/zero-dep.
+function isEnabled() {
+  const v = String(process.env.KODELYTH_MEMORY_EMBEDDINGS || '').trim().toLowerCase();
+  return v === '1' || v === 'on' || v === 'true' || v === 'yes';
+}
+
+// Resolve the embedding provider, or null. Null means "no semantics" — a
+// disabled flag, a missing optional dependency, or a load failure all collapse
+// to the same safe BM25-only behaviour.
+async function getProvider() {
+  if (_hasOverride) return _providerOverride;
+  if (!isEnabled()) return null;
+  try {
+    const { createProvider } = require('./embedding-providers/local-transformers');
+    return await createProvider();
+  } catch {
+    return null; // optional dep not installed, or model load failed
+  }
+}
+
+// Cosine similarity of two equal-length numeric vectors. Returns 0 for missing,
+// mismatched, or zero-magnitude vectors rather than NaN, so it is always safe to
+// sort by.
+function cosineSim(a, b) {
+  if (!a || !b || a.length === 0 || a.length !== b.length) return 0;
+  let dot = 0, na = 0, nb = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    na += a[i] * a[i];
+    nb += b[i] * b[i];
+  }
+  if (na === 0 || nb === 0) return 0;
+  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+}
+
+// Fuse BM25 relevance with semantic similarity and re-rank. Pure function.
+//
+//   results:  BM25 results, each { id, score, ... }, already relevance-ranked
+//   queryVec: the query embedding (or null → returns results unchanged)
+//   vecById:  { [id]: vector } for whichever results have a stored embedding
+//   weight:   semantic weight in [0,1] (default 0.5). final =
+//             weight*semantic + (1-weight)*bm25norm, with BM25 min-max normalized
+//             across this result set. A result with no stored vector keeps its
+//             BM25-normalized score (semantic contribution 0), so missing
+//             embeddings never push a relevant memory down unfairly.
+function fuseHybrid(results, { queryVec, vecById = {}, weight = 0.5 } = {}) {
+  if (!Array.isArray(results) || results.length === 0) return results || [];
+  if (!queryVec) return results;
+
+  const scores = results.map(r => r.score || 0);
+  const min = Math.min(...scores);
+  const max = Math.max(...scores);
+  const span = max - min;
+  const norm = (s) => (span === 0 ? 1 : (s - min) / span);
+
+  const w = Math.min(1, Math.max(0, weight));
+  return results
+    .map(r => {
+      const vec = vecById[r.id];
+      const bm25n = norm(r.score || 0);
+      const sem = vec ? Math.max(0, cosineSim(queryVec, vec)) : bm25n;
+      const fused = w * sem + (1 - w) * bm25n;
+      return { ...r, _bm25norm: bm25n, _semantic: vec ? sem : null, _hybrid: fused };
+    })
+    .sort((a, b) => b._hybrid - a._hybrid);
+}
+
+module.exports = {
+  isEnabled,
+  getProvider,
+  cosineSim,
+  fuseHybrid,
+  _setProviderForTest,
+  _clearProviderForTest,
+};

package/scripts/memory/pending.js

@@ -0,0 +1,125 @@
+// scripts/memory/pending.js
+//
+// The consent-respecting half of auto-capture. The Stop hook
+// (hooks/memory/capture-stop.js) already AUTO-EXTRACTS memory candidates from a
+// finished session and queues them to pending-review.jsonl — it never stores
+// them. But nothing ever read that queue or promoted it, so the candidates piled
+// up with no way to confirm them (the `/memory review-pending` the hook points at
+// did not exist). This module closes the loop while honouring the memory
+// protocol's rule: "never capture without explicit confirmation."
+//
+//   listPending()      — review what the session proposed
+//   promotePending(id) — the confirmation gate: store it (capture() redacts)
+//   discardPending(id) — throw it away
+//
+// Candidates are auto-collected; storing them is one explicit command. Nothing
+// enters the recall store silently.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const safeFs = require('../lib/safe-fs.js');
+const store = require('./store.js');
+
+function pendingFile() {
+  return path.join(store.PATHS.dir, 'pending-review.jsonl');
+}
+
+// Stable id from content, so the same proposal queued across several sessions
+// folds to one entry and the user can reference it to confirm/discard.
+function candidateId(c) {
+  return crypto.createHash('sha256')
+    .update(`${(c && c.problem) || ''}::${(c && c.approach) || ''}`)
+    .digest('hex')
+    .slice(0, 8);
+}
+
+function readQueue() {
+  const f = pendingFile();
+  if (!fs.existsSync(f)) return [];
+  const out = [];
+  for (const line of fs.readFileSync(f, 'utf8').split('\n')) {
+    if (!line) continue;
+    let row; try { row = JSON.parse(line); } catch { continue; }
+    if (!row || !row.problem || !row.approach) continue;
+    out.push(row);
+  }
+  return out;
+}
+
+function writeQueue(rows) {
+  const f = pendingFile();
+  if (rows.length === 0) {
+    try { fs.unlinkSync(f); } catch { /* already gone */ }
+    return;
+  }
+  safeFs.replaceFilePreservingMode(f, rows.map(r => JSON.stringify(r)).join('\n') + '\n');
+}
+
+// Deduped view of the queue, newest first, each with its stable id.
+function listPending() {
+  const byId = new Map();
+  for (const c of readQueue()) {
+    const id = candidateId(c);
+    const prior = byId.get(id);
+    if (!prior || (c.queued_at || '') > (prior.queued_at || '')) {
+      byId.set(id, { ...c, id });
+    }
+  }
+  return [...byId.values()].sort((a, b) => (b.queued_at || '').localeCompare(a.queued_at || ''));
+}
+
+function countPending() {
+  return listPending().length;
+}
+
+function selectIds(selector) {
+  if (selector === 'all' || selector == null) return new Set(listPending().map(c => c.id));
+  const arr = Array.isArray(selector) ? selector : [selector];
+  return new Set(arr.map(String));
+}
+
+// The confirmation gate. Promotes the selected candidates into the recall store
+// via capture() — which redacts secrets — then removes them from the queue.
+// Returns the stored memories.
+function promotePending(selector = 'all') {
+  const ids = selectIds(selector);
+  const promotedContentIds = new Set();
+  const stored = [];
+  for (const c of listPending()) {
+    if (!ids.has(c.id)) continue;
+    stored.push(store.capture({
+      problem:  c.problem,
+      approach: c.approach,
+      tags:     c.tags || [],
+      project:  c.project_path || null,
+      language: c.language || null,
+      files:    c.files || [],
+      source:   'auto-confirmed',
+    }));
+    promotedContentIds.add(c.id); // c.id === candidateId(c)
+  }
+  const remaining = readQueue().filter(c => !promotedContentIds.has(candidateId(c)));
+  writeQueue(remaining);
+  return stored;
+}
+
+// Remove candidates from the queue without storing them. Returns the count removed.
+function discardPending(selector = 'all') {
+  const ids = selectIds(selector);
+  const discardContentIds = new Set(listPending().filter(c => ids.has(c.id)).map(c => c.id));
+  const before = readQueue();
+  const remaining = before.filter(c => !discardContentIds.has(candidateId(c)));
+  writeQueue(remaining);
+  return before.length - remaining.length;
+}
+
+module.exports = {
+  pendingFile,
+  candidateId,
+  listPending,
+  countPending,
+  promotePending,
+  discardPending,
+};

package/scripts/memory/project-id.js

@@ -0,0 +1,93 @@
+// scripts/memory/project-id.js
+//
+// One project-identity resolver for the memory subsystem. Memory used to key a
+// project by sha256(absolute path), while the observer keyed it by git remote —
+// so the moment you cloned, moved, or renamed a repo, its absolute path changed
+// and all of its memories orphaned (they were filed under the old path hash).
+//
+// This resolver is git-remote-first with a path fallback, and NORMALIZES the
+// remote so the same repo always hashes the same way regardless of protocol,
+// host form, .git suffix, embedded credentials, or trailing slash:
+//
+//   git@github.com:owner/repo.git     ─┐
+//   https://github.com/owner/repo/     ├─→  remote:github.com/owner/repo  → one id
+//   ssh://git@github.com/owner/repo    ─┘
+//
+// Backward compatibility is handled by read-both: new memories are written under
+// the git-remote id, but recall also matches the LEGACY path id, so memories
+// captured before this change are never lost. Zero deps, local only.
+'use strict';
+
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+function sha12(s) {
+  return crypto.createHash('sha256').update(String(s)).digest('hex').slice(0, 12);
+}
+
+function runGit(args, cwd) {
+  try {
+    const r = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+    if (r.status !== 0) return '';
+    return (r.stdout || '').trim();
+  } catch {
+    return '';
+  }
+}
+
+// Strip `://user:pass@` so a credential-bearing remote and a clean one map to the
+// same project (and so a secret never ends up in a hash input we might log).
+function stripRemoteCredentials(url) {
+  if (!url) return '';
+  return String(url).replace(/:\/\/[^@]+@/, '://');
+}
+
+// Canonical form of a git remote URL — see the header for the shapes this folds
+// together. Returns '' for empty input.
+function normalizeRemote(url) {
+  let u = stripRemoteCredentials(url).trim();
+  if (!u) return '';
+  u = u.replace(/^[a-z][a-z0-9+.-]*:\/\//i, '');   // strip scheme://
+  u = u.replace(/^git@/i, '');                      // strip scp-style user
+  u = u.replace(/^([^/:]+):(?!\d)/, '$1/');         // host:owner/repo → host/owner/repo (scp form, not host:port)
+  u = u.replace(/\.git$/i, '');                     // drop a trailing .git
+  u = u.replace(/\/+$/, '');                        // drop trailing slashes
+  return u.toLowerCase();
+}
+
+// The legacy, path-only id the memory store used before this change. Kept so
+// memories captured under the old scheme are still found (read-both).
+function legacyPathId(projectRoot) {
+  return sha12(projectRoot);
+}
+
+// The canonical id for a project: git-remote-first (stable across clone/move),
+// path fallback (local-only repos, non-git directories).
+function resolveProjectId(projectRoot, { cwd } = {}) {
+  if (!projectRoot) return 'global';
+  const dir = cwd || projectRoot;
+  const remote = normalizeRemote(runGit(['remote', 'get-url', 'origin'], dir));
+  if (remote) return sha12('remote:' + remote);
+  return legacyPathId(projectRoot);
+}
+
+// Every id that should match this project when recalling: the canonical id AND
+// the legacy path id, de-duped. New memories are written under the first; old
+// ones are still found via the second. (When the repo has no remote the two are
+// identical and this collapses to one.)
+function matchingProjectIds(projectRoot, opts = {}) {
+  if (!projectRoot) return [];
+  const ids = new Set();
+  ids.add(resolveProjectId(projectRoot, opts));
+  ids.add(legacyPathId(projectRoot));
+  return [...ids];
+}
+
+module.exports = {
+  sha12,
+  stripRemoteCredentials,
+  normalizeRemote,
+  legacyPathId,
+  resolveProjectId,
+  matchingProjectIds,
+};