@engramlabs/mcp 0.1.8-alpha → 0.2.0-alpha

package/hooks/engram-recall-pi.cjs

@@ -14,18 +14,67 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 
+/** Repo-pinned scope: <repo>/.pi/engram.json {"project": "...", "storage": "..."}
+ *  overrides the cwd-basename default (env vars still win). */
+function repoConfig() {
+  let dir = __dirname;
+  for (let i = 0; i < 8; i++) {
+    const f = path.join(dir, '.pi', 'engram.json');
+    if (fs.existsSync(f)) {
+      try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch {}
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return {};
+}
+
 module.exports = (pi) => {
-  const storage = process.env.ENGRAM_STORAGE || path.join(os.homedir(), '.engram');
+  const repo = repoConfig();
+  const storage =
+    process.env.ENGRAM_STORAGE || repo.storage || path.join(os.homedir(), '.engram');
   const project =
-    process.env.ENGRAM_PROJECT || path.basename(process.cwd()) || 'default';
+    process.env.ENGRAM_PROJECT || repo.project || path.basename(process.cwd()) || 'default';
   const hooksOff = process.env.ENGRAM_HOOKS === '0';
 
+  function resolveBinary() {
+    // Ordered: env override → repo build (release, then debug — whichever
+    // is freshest for development) → npm platform package.
+    if (process.env.ENGRAM_MCP_BIN) return process.env.ENGRAM_MCP_BIN;
+    // Walk up from this extension to find the repo's target/ dir.
+    let dir = __dirname;
+    for (let i = 0; i < 8; i++) {
+      const rel = path.join(dir, 'target');
+      if (fs.existsSync(path.join(rel, 'release', 'engram-mcp')))
+        return path.join(rel, 'release', 'engram-mcp');
+      if (fs.existsSync(path.join(rel, 'debug', 'engram-mcp')))
+        return path.join(rel, 'debug', 'engram-mcp');
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    try {
+      const { platform, arch } = process;
+      const suffix =
+        platform === 'darwin' && arch === 'arm64' ? 'mcp-darwin-arm64' :
+        platform === 'darwin' && arch === 'x64' ? 'mcp-darwin-x64' :
+        platform === 'win32' ? 'mcp-win32-x64' :
+        platform === 'linux' && arch === 'arm64' ? 'mcp-linux-arm64-gnu' :
+        'mcp-linux-x64-gnu';
+      const { createRequire } = require('node:module');
+      const req = createRequire(__filename);
+      const manifest = req.resolve(`@engramlabs/${suffix}/package.json`);
+      const bin = path.join(path.dirname(manifest), 'engram-mcp');
+      if (fs.existsSync(bin)) return bin;
+    } catch {}
+    return null;
+  }
+
   function recallOnce(query, limit = 5) {
     return new Promise((resolve) => {
-      const bin =
-        process.env.ENGRAM_MCP_BIN ||
-        path.join(os.homedir(), 'projects', 'mem-alpha', 'target', 'release', 'engram-mcp');
-      if (!fs.existsSync(bin)) return resolve(null);
+      const bin = resolveBinary();
+      if (!bin) return resolve(null);
       const child = spawn(
         bin,
         ['recall', '--storage', storage, '--project', project, '--no-vector', '--json', '--limit', String(limit), '--query', query],
@@ -48,19 +97,37 @@ module.exports = (pi) => {
     });
   }
 
-  function gate(payload) {
+  function termOverlap(query, text) {
+    const STOP = new Set(['the','a','an','is','are','was','do','does','did','i','you','we','it','in','on','for','of','to','and','or','how','what','why','when','with','my','me','this','that','right']);
+    const norm = (s) => String(s).toLowerCase().replace(/[^a-z0-9s/-]+/g, ' ').split(/[\s/-]+/).map((w) => (w.length > 3 && w.endsWith('s') ? w.slice(0, -1) : w)).filter((w) => w.length > 2 && !STOP.has(w));
+    const q = norm(query);
+    if (q.length === 0) return 0;
+    const t = new Set(norm(text));
+    let hit = 0;
+    for (const w of q) if (t.has(w)) hit++;
+    return hit / q.length;
+  }
+
+  // Gate v2: overlap OR separation (see recall-context.cjs for the measured
+  // rationale — separation alone over-silences on real corpora).
+  function gate(payload, query) {
     if (!payload || !payload.ok || !Array.isArray(payload.results) || payload.results.length === 0) {
       return [];
     }
     const scores = payload.results.map((r) => Number(r.score) || 0).sort((a, b) => b - a);
-    if (scores.length < 2) return [];
+    if (scores.length < 1) return [];
     const median = scores[Math.floor(scores.length / 2)];
     const top = scores[0];
-    const topEvidence = payload.results[0].evidence || 'weak';
-    if (median > 0 && top / median >= 1.8 && topEvidence !== 'weak') {
-      return payload.results.slice(0, 3);
-    }
-    return [];
+    const topResult = payload.results[0];
+    const topEvidence = topResult.evidence || 'weak';
+    const MEMORY_LANES = new Set(['memory', 'belief', 'document']);
+    const overlap = termOverlap(query, topResult.content || '');
+    const sepPass = scores.length >= 2 && median > 0 && top / median >= 1.8 && topEvidence !== 'weak';
+    const overlapPass =
+      topEvidence !== 'weak' &&
+      (MEMORY_LANES.has(topResult.kind) || topEvidence === 'exact') &&
+      overlap >= 0.35;
+    return sepPass || overlapPass ? payload.results.slice(0, 3) : [];
   }
 
   function block(items) {
@@ -79,7 +146,7 @@ module.exports = (pi) => {
     const words = prompt.split(/\s+/).filter(Boolean);
     if (words.length < 3 || prompt.startsWith('/')) return;
     const payload = await recallOnce(prompt);
-    const items = gate(payload);
+    const items = gate(payload, prompt);
     if (items.length === 0) return;
     return {
       message: {

package/hooks/recall-context.cjs

@@ -118,6 +118,33 @@ function heartbeat(storage, event, fields) {
   } catch {}
 }
 
+/**
+ * Fraction of query content-words present in the hit's text (0..1).
+ * Deterministic, scale-free, works on real corpora where BM25 scores
+ * compress. Light normalization: lowercase, split hyphens/paths, strip
+ * plural 's' and trailing punctuation. Stopwords removed.
+ */
+function termOverlap(query, text) {
+  const STOP = new Set([
+    'the', 'a', 'an', 'is', 'are', 'was', 'were', 'do', 'does', 'did', 'i',
+    'you', 'we', 'it', 'in', 'on', 'for', 'of', 'to', 'and', 'or', 'how',
+    'what', 'why', 'when', 'with', 'my', 'me', 'this', 'that', 'right',
+  ]);
+  const norm = (s) =>
+    String(s)
+      .toLowerCase()
+      .replace(/[^a-z0-9s/-]+/g, ' ')
+      .split(/[\s/-]+/)
+      .map((w) => (w.length > 3 && w.endsWith('s') ? w.slice(0, -1) : w))
+      .filter((w) => w.length > 2 && !STOP.has(w));
+  const q = norm(query);
+  if (q.length === 0) return 0;
+  const t = new Set(norm(text));
+  let hit = 0;
+  for (const w of q) if (t.has(w)) hit++;
+  return hit / q.length;
+}
+
 function main() {
   const t0 = Date.now();
   if (process.env.ENGRAM_HOOKS === '0') process.exit(0);
@@ -199,13 +226,29 @@ function main() {
   // average-of-two convention would cap 2-hit separation at 1.33x).
   const median = scores.length >= 2 ? scores[Math.floor(scores.length / 2)] : 0;
   const top = scores[0];
-  const topEvidence = payload.results[0].evidence || 'weak';
+  const topResult = payload.results[0];
+  const topEvidence = topResult.evidence || 'weak';
+
+  // Gate v2 — overlap OR separation (measured on the 9.7k-entity self-index
+  // 2026-10-19: lexical scores compress on real corpora, so pure separation
+  // silenced CORRECT top hits (sep 1.04x) while junk code entities matching
+  // one query word scored HIGHER separation (1.55x). Query-term overlap is
+  // the discriminative signal: 0.58 for the right memory, 0.06-0.08 for junk.
+  // Separation stays as the semantic path (vector-mode hits don't overlap
+  // lexically with reworded queries).
+  const MEMORY_LANES = new Set(['memory', 'belief', 'document']);
+  const overlap = termOverlap(query, topResult.content || '');
+  const MIN_OVERLAP = parseFloat(process.env.ENGRAM_RECALL_MIN_OVERLAP || '0.35');
+  const sepPass =
+    scores.length >= 2 && median > 0 && top / median >= MIN_SEP && topEvidence !== 'weak';
+  const overlapPass =
+    topEvidence !== 'weak' &&
+    (MEMORY_LANES.has(topResult.kind) || topEvidence === 'exact') &&
+    overlap >= MIN_OVERLAP;
 
   // Session packs: any real hit qualifies (it's once per session, and the
   // query is a fixed discovery probe, not a user prompt).
-  const passes = isSessionStart
-    ? scores.length >= 1
-    : scores.length >= 2 && median > 0 && top / median >= MIN_SEP && topEvidence !== 'weak';
+  const passes = isSessionStart ? scores.length >= 1 : sepPass || overlapPass;
   if (!passes) {
     heartbeat(storage, 'recall', { ok: true, gated: true, hits: payload.hit_count });
     process.exit(0); // silence beats a wrong pointer

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engramlabs/mcp",
-  "version": "0.1.8-alpha",
+  "version": "0.2.0-alpha",
   "description": "Local-first agentic memory: the engram MCP server launcher. Memory + knowledge graph + beliefs + code intelligence for any MCP client.",
   "license": "MIT",
   "repository": {
@@ -32,11 +32,11 @@
     "local-first"
   ],
   "optionalDependencies": {
-    "@engramlabs/mcp-linux-x64-gnu": "0.1.8-alpha",
-    "@engramlabs/mcp-linux-arm64-gnu": "0.1.8-alpha",
-    "@engramlabs/mcp-darwin-arm64": "0.1.8-alpha",
-    "@engramlabs/mcp-darwin-x64": "0.1.8-alpha",
-    "@engramlabs/mcp-win32-x64": "0.1.8-alpha"
+    "@engramlabs/mcp-linux-x64-gnu": "0.2.0-alpha",
+    "@engramlabs/mcp-linux-arm64-gnu": "0.2.0-alpha",
+    "@engramlabs/mcp-darwin-arm64": "0.2.0-alpha",
+    "@engramlabs/mcp-darwin-x64": "0.2.0-alpha",
+    "@engramlabs/mcp-win32-x64": "0.2.0-alpha"
   },
   "scripts": {
     "test": "node --test test/*.test.cjs"