sigmap 8.19.0 → 8.20.0

package/CHANGELOG.md

@@ -10,6 +10,19 @@ Format: [Semantic Versioning](https://semver.org/)
 
 ---
 
+## [8.20.0] — 2026-07-19
+
+Minor release — **"Semantic Bridge I" (v8.20)**: the JS/TS extractors gain the same doc-comment hints Python has carried for releases, and the cross-session stores get a single inspect/prune surface.
+
+### Added
+- **JS/TS doc-comment hints (#498, PR #499):** `buildDocHints` in the JavaScript and TypeScript extractors mines the first prose sentence of the JSDoc block immediately preceding each top-level function form (exported function, exported arrow const, top-level function) and appends it after the line anchor as `  # <hint>` — byte-format identical to the Python extractor's `extractDocHint`, restoring cross-language consistency. A tempered comment-body pattern prevents cross-block hint misattribution (caught in smoke testing before landing). The semantic value is proven directly by a new vocab-mismatch fixture: a query whose vocabulary is fully disjoint from every identifier retrieves the file **only** via its hint (BM25 score 0 without).
+- **`sigmap memory` (#498, PR #499):** one view over the existing `.context/` cross-session stores — session, notes, weights, evidence, gain, usage — with per-store entry counts, size, and age; `--json`; and explicit `--clear <session|notes|weights|evidence|all>`. Tracking stores (gain/usage) are listed but protected (they keep their own reset flows). No new storage, zero dependencies.
+
+### Changed
+- **Headline metric shift, documented honestly:** doc hints add English tokens that compete on the lexical-favoring corpus — one borderline task (`svelte-t002`) fell out of top-5 because competing public-API files' hints carry the query's words. **hit@5 86.4% → 85.5% task-level (−0.9pt), honest lift 2.02× → 2.00×**; grep baseline unchanged at 42.7%. Shipped default-on per the v8.18 anchors precedent and Python-parity; the v8.22 hard-split corpus (A3) will measure the semantic upside these hints exist for. 10 new integration tests (126 test files).
+
+---
+
 ## [8.19.0] — 2026-07-19
 
 Minor release — **"Honest Numbers" (v8.19, P0)**: the published retrieval lift now comes from a measured grep-agent comparison, not a random-file baseline, and every proxy metric says so on the label.

package/README.md

@@ -59,10 +59,10 @@ That map is exactly what agentic grep is worst at: reproducible, auditable conte
 
 **Proof it pays off** (full benchmark below):
 <!--SM:whyMetrics-->
-- **86.7% hit@5** — right file in top 5 results (vs 42.7% single-shot grep baseline — 2.02× lift)
-- **96.9% token reduction** — average across 21 real repos
-- **68.9% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
-- **1.44 prompts per task** — down from 2.84 (49.2% fewer retries, modeled)
+- **85.6% hit@5** — right file in top 5 results (vs 42.7% single-shot grep baseline — 2.00× lift)
+- **96.8% token reduction** — average across 21 real repos
+- **67.8% task-success proxy** — modeled from retrieval tiers, not measured LLM sessions
+- **1.47 prompts per task** — down from 2.84 (48.4% fewer retries, modeled)
 <!--/SM:whyMetrics-->
 - **<!--SM:languages-->33<!--/SM:languages--> languages supported** — TypeScript, Python, Go, Rust, Java, R, and more
 - **No vendor lock-in** — works with any AI assistant or local LLM
@@ -98,7 +98,7 @@ sigmap verify answer.md --report        # standalone red/amber/green HTML report
 | Without SigMap | With SigMap |
 |---|---|
 | ❌ Non-reproducible agent guesses | ✅ Deterministic map — same input, same output, every time |
-| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->87%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
+| ❌ "Trust me" AI answers | ✅ Grounded — right file in context <!--SM:hitWhole-->86%<!--/SM:hitWhole--> of the time, every symbol on a real line anchor |
 | ❌ Embeddings / vector DB required | ✅ Zero deps, no infra, fully offline |
 
 ---
@@ -122,13 +122,13 @@ Ask → Rank → Context → Validate → Judge → Learn
 
 <!--SM:benchmarkBlock-->
 ```
-Benchmark : sigmap-v8.19-main (21 repositories, including R language)
+Benchmark : sigmap-v8.20-main (21 repositories, including R language)
 Date      : 2026-07-19
 
-Hit@5          : 86.7%   (grep-agent baseline 42.7%  — 2.02× lift)
-Token reduction: 96.9%   (across 21 repos)
-Prompt reduction : 49.2% (2.84 → 1.44 prompts per task, modeled)
-Task success   : 68.9%   (proxy — modeled from retrieval tiers)
+Hit@5          : 85.6%   (grep-agent baseline 42.7%  — 2.00× lift)
+Token reduction: 96.8%   (across 21 repos)
+Prompt reduction : 48.4% (2.84 → 1.47 prompts per task, modeled)
+Task success   : 67.8%   (proxy — modeled from retrieval tiers)
 Repos tested   : 21 (JavaScript, Python, Go, Rust, Java, R, C++, C#, Dart, Swift, Ruby, PHP, Scala, Kotlin, and more)
 ```
 <!--/SM:benchmarkBlock-->

package/gen-context.js

@@ -6203,7 +6203,12 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
     const anchors = [];
+    // docHintFor[i] is the doc-comment hint for sigs[i] (top-level functions
+    // only), appended after the anchor as `  # <hint>` — same convention as the
+    // Python extractor's extractDocHint.
+    const docHintFor = [];
     const returnHints = buildReturnHints(src);
+    const docHints = buildDocHints(src);
 
     // Block comments are blanked newline-by-newline (non-newline chars → spaces)
     // so character offsets AND line numbers stay exact for anchors.
@@ -6238,6 +6243,7 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
       const retStr = formatReturnHint(returnHints.get(m[1]));
       const startLn = lineAt(stripped, m.index);
       sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      docHintFor[sigs.length - 1] = docHints.get(m[1]);
       anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
 
@@ -6247,6 +6253,7 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
       const retStr = formatReturnHint(returnHints.get(m[1]));
       const startLn = lineAt(stripped, m.index);
       sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
+      docHintFor[sigs.length - 1] = docHints.get(m[1]);
       anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
 
@@ -6267,10 +6274,14 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
       const retStr = formatReturnHint(returnHints.get(m[1]));
       const startLn = lineAt(stripped, m.index);
       sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+      docHintFor[sigs.length - 1] = docHints.get(m[1]);
       anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
     }
 
-    const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+    const withAnchors = sigs.map((s, i) => {
+      const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+      return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+    });
     return capWithNotice(withAnchors, 25, 'signatures');
   }
 
@@ -6319,6 +6330,36 @@ __factories["./src/extractors/javascript"] = function(module, exports) {
     return hints;
   }
 
+  // First prose sentence of the JSDoc block immediately preceding a top-level
+  // function (same three shapes as buildReturnHints). Mirrors the Python
+  // extractor's extractDocHint: first sentence only, 60-char cap.
+  function buildDocHints(src) {
+    const hints = new Map();
+    // Body may not contain `*/` — otherwise a failed adjacency check would let
+    // the match expand across a whole function to the next comment block and
+    // misattribute the hint.
+    const patterns = [
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g,
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g,
+    ];
+    for (const re of patterns) {
+      for (const m of src.matchAll(re)) {
+        const hint = firstDocSentence(m[1]);
+        if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+      }
+    }
+    return hints;
+  }
+
+  // First non-tag prose line of a JSDoc body → first sentence, 60-char cap.
+  function firstDocSentence(body) {
+    const line = String(body).split('\n')
+      .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+      .find((l) => l && !l.startsWith('@'));
+    if (!line) return '';
+    return line.split(/[.!?]/)[0].trim().slice(0, 60);
+  }
+
   function normalizeType(type) {
     if (!type) return '';
     return type.trim().replace(/\s+/g, ' ').slice(0, 25);
@@ -8307,6 +8348,11 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
   function extract(src) {
     if (!src || typeof src !== 'string') return [];
     const sigs = [];
+    // docHintFor[i] is the doc-comment hint for sigs[i] (exported top-level
+    // functions only), appended after the anchor as `  # <hint>` — same
+    // convention as the Python extractor's extractDocHint.
+    const docHintFor = [];
+    const docHints = buildDocHints(src);
     // anchors[i] is [start, end] for a top-level sig, or null for an indented member.
     // Kept parallel to `sigs` so existing push/mutation logic stays untouched;
     // anchors are applied once at return.
@@ -8374,6 +8420,7 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
       const retStr = retType ? ` → ${retType}` : '';
       const bodyStart = m.index + m[0].length;
       sigs.push(`export ${asyncKw}function ${m[1]}(${params})${retStr}`);
+      docHintFor[sigs.length - 1] = docHints.get(m[1]);
       anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
 
       // Hooks: capture compact return object shape for use* functions.
@@ -8398,6 +8445,7 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
       const asyncKw = /=\s*async\s+/.test(m[0]) ? 'async ' : '';
       const params = normalizeParams(m[2]);
       sigs.push(`export const ${m[1]} = ${asyncKw}(${params}) =>`);
+      docHintFor[sigs.length - 1] = docHints.get(m[1]);
       const bodyStart = stripped.indexOf('{', m.index + m[0].length);
       const endLn = bodyStart !== -1
         ? lineAt(stripped, blockEndIdx(bodyStart + 1))
@@ -8447,7 +8495,10 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
       }
     }
 
-    const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+    const withAnchors = sigs.map((s, i) => {
+      const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+      return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+    });
     return capWithNotice(withAnchors, 35, 'signatures');
   }
 
@@ -8512,6 +8563,36 @@ __factories["./src/extractors/typescript"] = function(module, exports) {
     return params.trim().replace(/\s+/g, ' ').replace(/:[^,)]+/g, '').trim();
   }
 
+  // First prose sentence of the JSDoc block immediately preceding an exported
+  // top-level function (function or arrow-const form). Mirrors the Python
+  // extractor's extractDocHint: first sentence only, 60-char cap.
+  function buildDocHints(src) {
+    const hints = new Map();
+    // Body may not contain `*/` — otherwise a failed adjacency check would let
+    // the match expand across a whole function to the next comment block and
+    // misattribute the hint.
+    const patterns = [
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+(?:async\s+)?function\s+(\w+)\s*[<(]/g,
+      /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\s+(\w+)\s*[:=]/g,
+    ];
+    for (const re of patterns) {
+      for (const m of src.matchAll(re)) {
+        const hint = firstDocSentence(m[1]);
+        if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+      }
+    }
+    return hints;
+  }
+
+  // First non-tag prose line of a JSDoc body → first sentence, 60-char cap.
+  function firstDocSentence(body) {
+    const line = String(body).split('\n')
+      .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+      .find((l) => l && !l.startsWith('@'));
+    if (!line) return '';
+    return line.split(/[.!?]/)[0].trim().slice(0, 60);
+  }
+
   module.exports = { extract };
   
 };
@@ -14607,7 +14688,7 @@ __factories["./src/mcp/server"] = function(module, exports) {
 
   const SERVER_INFO = {
     name: 'sigmap',
-    version: '8.19.0',
+    version: '8.20.0',
     description: 'SigMap MCP server — code signatures on demand',
   };
 
@@ -17202,6 +17283,96 @@ __factories["./src/session/memory"] = function(module, exports) {
   
 };
 
+// ── ./src/session/memory-inspect ──
+__factories["./src/session/memory-inspect"] = function(module, exports) {
+  
+  /**
+   * memory-inspect.js — one view over SigMap's existing cross-session stores.
+   * No new storage: reads the JSON/NDJSON files the session, notes, weights,
+   * evidence, and tracking modules already own under `.context/`.
+   */
+
+  const fs = require('fs');
+  const path = require('path');
+
+  /** store name → { file, kind } (kind drives the entry count). */
+  const STORES = {
+    session: { file: 'session.json', kind: 'json' },
+    notes: { file: 'notes.ndjson', kind: 'ndjson' },
+    weights: { file: 'weights.json', kind: 'weights' },
+    evidence: { file: 'evidence-pack.json', kind: 'json' },
+    gain: { file: 'gain.ndjson', kind: 'ndjson' },
+    usage: { file: 'usage.ndjson', kind: 'ndjson' },
+  };
+
+  /** Stores `clearMemory` may delete ('gain'/'usage' have their own reset flows). */
+  const CLEARABLE = ['session', 'notes', 'weights', 'evidence'];
+
+  function storePath(cwd, name) {
+    return path.join(cwd, '.context', STORES[name].file);
+  }
+
+  function countEntries(kind, filePath) {
+    try {
+      if (kind === 'ndjson') {
+        return fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean).length;
+      }
+      if (kind === 'weights') {
+        const w = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        return Object.keys((w && w.files) || w || {}).length;
+      }
+      return 1; // json: a single snapshot object
+    } catch (_) {
+      return 0;
+    }
+  }
+
+  /**
+   * Describe every cross-session store.
+   * @param {string} cwd
+   * @returns {Array<{store:string, path:string, exists:boolean, entries:number, bytes:number, modified:string|null, clearable:boolean}>}
+   */
+  function inspectMemory(cwd) {
+    return Object.entries(STORES).map(([store, { file, kind }]) => {
+      const p = storePath(cwd, store);
+      let stat = null;
+      try { stat = fs.statSync(p); } catch (_) {}
+      return {
+        store,
+        path: path.join('.context', file),
+        exists: !!stat,
+        entries: stat ? countEntries(kind, p) : 0,
+        bytes: stat ? stat.size : 0,
+        modified: stat ? new Date(stat.mtimeMs).toISOString() : null,
+        clearable: CLEARABLE.includes(store),
+      };
+    });
+  }
+
+  /**
+   * Delete one clearable store (or 'all' clearable stores).
+   * @param {string} cwd
+   * @param {string} store - session|notes|weights|evidence|all
+   * @returns {string[]} names of stores actually removed
+   */
+  function clearMemory(cwd, store) {
+    const targets = store === 'all' ? CLEARABLE : [store];
+    for (const t of targets) {
+      if (!CLEARABLE.includes(t)) {
+        throw new Error(`unknown or protected store "${t}" — clearable: ${CLEARABLE.join(', ')}, all`);
+      }
+    }
+    const removed = [];
+    for (const t of targets) {
+      try { fs.unlinkSync(storePath(cwd, t)); removed.push(t); } catch (_) {}
+    }
+    return removed;
+  }
+
+  module.exports = { inspectMemory, clearMemory, STORES, CLEARABLE };
+  
+};
+
 // ── ./src/session/notes ──
 __factories["./src/session/notes"] = function(module, exports) {
   
@@ -19710,7 +19881,7 @@ function __tryGit(args, opts = {}) {
   catch (_) { return ''; }
 }
 
-const VERSION = '8.19.0';
+const VERSION = '8.20.0';
 const MARKER = '\n\n## Auto-generated signatures\n<!-- Updated by gen-context.js -->\n';
 
 function requireSourceOrBundled(key) {
@@ -21593,6 +21764,8 @@ Usage:
   ${cmd} evidence "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
   ${cmd} evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
   ${cmd} evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
+  ${cmd} memory                            List cross-session stores (.context/) — entries, size, age
+  ${cmd} memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
   ${cmd} note "<text>"                     Append a note to the cross-session decision log
   ${cmd} note                              List recent notes (also: note --list <N>)
   ${cmd} status                            Show repo state — branch, dirty files, index freshness, notes
@@ -22986,6 +23159,56 @@ function main() {
 
   // `sigmap note "<text>"` — append to the cross-session decision log.
   // With no text, lists recent notes (also `note --list [N]`).
+  // `sigmap memory` — one view over the cross-session stores in .context/.
+  if (args[0] === 'memory') {
+    const jsonOut = args.includes('--json');
+    const { inspectMemory, clearMemory } = requireSourceOrBundled('./src/session/memory-inspect');
+    const clearIdx = args.indexOf('--clear');
+
+    if (clearIdx !== -1) {
+      const store = args[clearIdx + 1];
+      if (!store || store.startsWith('--')) {
+        console.error('[sigmap] usage: sigmap memory --clear <session|notes|weights|evidence|all>');
+        process.exit(1);
+      }
+      let removed;
+      try {
+        removed = clearMemory(cwd, store);
+      } catch (err) {
+        console.error(`[sigmap] ${err.message}`);
+        process.exit(1);
+      }
+      if (jsonOut) {
+        process.stdout.write(JSON.stringify({ cleared: removed }) + '\n');
+      } else {
+        console.log(removed.length
+          ? `[sigmap] cleared: ${removed.join(', ')}`
+          : `[sigmap] nothing to clear for "${store}"`);
+      }
+      process.exit(0);
+    }
+
+    const stores = inspectMemory(cwd);
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify({ stores }) + '\n');
+      process.exit(0);
+    }
+    const fmtAge = (iso) => {
+      if (!iso) return '—';
+      const m = Math.floor((Date.now() - Date.parse(iso)) / 60000);
+      const h = Math.floor(m / 60), d = Math.floor(h / 24);
+      return d > 0 ? `${d}d ago` : h > 0 ? `${h}h ago` : `${m}m ago`;
+    };
+    const fmtKB = (b) => (b >= 1024 ? `${(b / 1024).toFixed(1)}KB` : `${b}B`);
+    console.log('[sigmap] cross-session memory (.context/)');
+    for (const s of stores) {
+      const state = s.exists ? `${String(s.entries).padStart(5)} entries  ${fmtKB(s.bytes).padStart(8)}  ${fmtAge(s.modified)}` : '    — empty';
+      console.log(`  ${s.store.padEnd(9)} ${state}${s.clearable ? '' : '   (reset via its own command)'}`);
+    }
+    console.log('  clear: sigmap memory --clear <session|notes|weights|evidence|all>');
+    process.exit(0);
+  }
+
   if (args[0] === 'note') {
     const jsonOut = args.includes('--json');
     const { addNote, readNotes, formatNotes } = requireSourceOrBundled('./src/session/notes');

package/llms-full.txt

@@ -11,20 +11,20 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.19.0 | Benchmark: sigmap-v8.19-main (2026-07-19)
+# Version: 8.20.0 | Benchmark: sigmap-v8.20-main (2026-07-19)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
 ---
 
-## Core metrics (benchmark: sigmap-v8.19-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.20-main, 2026-07-19)
 
 | Metric | Without SigMap | With SigMap |
 |--------|----------------|-------------|
-| Retrieval hit@5 | 42.7% (single-shot grep) | 86.7% (2.02× lift) |
-| Token reduction | — | 96.9% average |
-| Task-success proxy (modeled) | — | 68.9% |
-| Prompts per task | 2.84 | 1.44 (49.2% fewer) |
+| Retrieval hit@5 | 42.7% (single-shot grep) | 85.6% (2.00× lift) |
+| Token reduction | — | 96.8% average |
+| Task-success proxy (modeled) | — | 67.8% |
+| Prompts per task | 2.84 | 1.47 (48.4% fewer) |
 | Supported languages | — | 33 |
 | MCP tools | — | 20 |
 | npm runtime dependencies | — | 0 |
@@ -123,6 +123,8 @@ sigmap ask "<query>" --squeeze-threshold N  Min reduction %% to prompt (default
 sigmap evidence "<query>"                Build a deterministic Evidence Pack (JSON) → .context/evidence-pack.json
 sigmap evidence "<query>" --markdown     Emit the Markdown handoff rendering to stdout
 sigmap evidence "<query>" --top <n> --budget <n> --out <path>   Tune ranked files / token budget / write rendered output
+sigmap memory                            List cross-session stores (.context/) — entries, size, age
+sigmap memory --clear <store>            Clear one store: session|notes|weights|evidence|all (--json supported)
 sigmap note "<text>"                     Append a note to the cross-session decision log
 sigmap note                              List recent notes (also: note --list <N>)
 sigmap status                            Show repo state — branch, dirty files, index freshness, notes

package/llms.txt

@@ -11,7 +11,7 @@ ranking keeps the relevant context in scope (cutting tokens ~97% as a side
 effect), with no LLM calls, embeddings, or vector database. Works with Claude,
 Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 
-# Version: 8.19.0 | Benchmark: sigmap-v8.19-main (2026-07-19)
+# Version: 8.20.0 | Benchmark: sigmap-v8.20-main (2026-07-19)
 # Source: auto-generated from package.json, version.json, benchmarks/latest.json, src/mcp/tools.js, src/config/defaults.js
 # Regenerate: npm run generate:llms   |   Validate: npm run validate:llms
 
@@ -23,12 +23,12 @@ Cursor, GitHub Copilot, Aider, Windsurf, local LLMs, and MCP.
 - No blast-radius awareness before editing a hub file — `--impact` shows every file a change touches.
 - Pasted stack traces, CI logs, and JSON bloat the prompt — `squeeze` minimizes them and enriches the top frame from the symbol index.
 
-## Core metrics (benchmark: sigmap-v8.19-main, 2026-07-19)
+## Core metrics (benchmark: sigmap-v8.20-main, 2026-07-19)
 
-- hit@5 retrieval: 86.7% vs 42.7% single-shot grep baseline (2.02× lift)
-- Token reduction: 96.9% average across benchmark repos
-- Task-success proxy: 68.9% (modeled from retrieval tiers, not measured LLM sessions)
-- Prompts per task: 1.44 vs 2.84 baseline (49.2% fewer, modeled)
+- hit@5 retrieval: 85.6% vs 42.7% single-shot grep baseline (2.00× lift)
+- Token reduction: 96.8% average across benchmark repos
+- Task-success proxy: 67.8% (modeled from retrieval tiers, not measured LLM sessions)
+- Prompts per task: 1.47 vs 2.84 baseline (48.4% fewer, modeled)
 - Languages: 33 supported · MCP tools: 20
 - Dependencies: zero npm runtime dependencies · fully offline
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "The deterministic, verifiable grounding layer for AI code work — a zero-dependency signature-and-evidence map that grounds Claude, Cursor, Copilot, Aider, Windsurf, local LLMs & MCP agents against your real code (repo + installed libraries) so they stop hallucinating files, imports & APIs. Runs offline via npx; byte-stable output; ~97% token reduction as proof.",
   "main": "packages/core/index.js",
   "exports": {

package/packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-cli",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "SigMap CLI wrapper — thin adapter for programmatic CLI invocation",
   "main": "index.js",
   "keywords": [

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sigmap-core",
-  "version": "8.19.0",
+  "version": "8.20.0",
   "description": "SigMap core library — zero-dependency code signature extraction, retrieval, and security scanning",
   "main": "index.js",
   "keywords": [

package/src/extractors/javascript.js

@@ -14,7 +14,12 @@ function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
   const anchors = [];
+  // docHintFor[i] is the doc-comment hint for sigs[i] (top-level functions
+  // only), appended after the anchor as `  # <hint>` — same convention as the
+  // Python extractor's extractDocHint.
+  const docHintFor = [];
   const returnHints = buildReturnHints(src);
+  const docHints = buildDocHints(src);
 
   // Block comments are blanked newline-by-newline (non-newline chars → spaces)
   // so character offsets AND line numbers stay exact for anchors.
@@ -49,6 +54,7 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`export ${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
@@ -58,6 +64,7 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`export const ${m[1]} = ${asyncKw}(${normalizeParams(m[2])}) =>${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
@@ -78,10 +85,14 @@ function extract(src) {
     const retStr = formatReturnHint(returnHints.get(m[1]));
     const startLn = lineAt(stripped, m.index);
     sigs.push(`${asyncKw}function ${m[1]}(${normalizeParams(m[2])})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([startLn, fnEndLine(m.index + m[0].length, startLn)]);
   }
 
-  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  const withAnchors = sigs.map((s, i) => {
+    const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+    return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+  });
   return capWithNotice(withAnchors, 25, 'signatures');
 }
 
@@ -130,6 +141,36 @@ function buildReturnHints(src) {
   return hints;
 }
 
+// First prose sentence of the JSDoc block immediately preceding a top-level
+// function (same three shapes as buildReturnHints). Mirrors the Python
+// extractor's extractDocHint: first sentence only, 60-char cap.
+function buildDocHints(src) {
+  const hints = new Map();
+  // Body may not contain `*/` — otherwise a failed adjacency check would let
+  // the match expand across a whole function to the next comment block and
+  // misattribute the hint.
+  const patterns = [
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\(/g,
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\s+(\w+)\s*=\s*(?:async\s+)?\(/g,
+  ];
+  for (const re of patterns) {
+    for (const m of src.matchAll(re)) {
+      const hint = firstDocSentence(m[1]);
+      if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+    }
+  }
+  return hints;
+}
+
+// First non-tag prose line of a JSDoc body → first sentence, 60-char cap.
+function firstDocSentence(body) {
+  const line = String(body).split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .find((l) => l && !l.startsWith('@'));
+  if (!line) return '';
+  return line.split(/[.!?]/)[0].trim().slice(0, 60);
+}
+
 function normalizeType(type) {
   if (!type) return '';
   return type.trim().replace(/\s+/g, ' ').slice(0, 25);

package/src/extractors/typescript.js

@@ -13,6 +13,11 @@ const { capWithNotice, capMembersWithNotice } = require('../util/truncate');
 function extract(src) {
   if (!src || typeof src !== 'string') return [];
   const sigs = [];
+  // docHintFor[i] is the doc-comment hint for sigs[i] (exported top-level
+  // functions only), appended after the anchor as `  # <hint>` — same
+  // convention as the Python extractor's extractDocHint.
+  const docHintFor = [];
+  const docHints = buildDocHints(src);
   // anchors[i] is [start, end] for a top-level sig, or null for an indented member.
   // Kept parallel to `sigs` so existing push/mutation logic stays untouched;
   // anchors are applied once at return.
@@ -80,6 +85,7 @@ function extract(src) {
     const retStr = retType ? ` → ${retType}` : '';
     const bodyStart = m.index + m[0].length;
     sigs.push(`export ${asyncKw}function ${m[1]}(${params})${retStr}`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     anchors.push([lineAt(stripped, m.index), lineAt(stripped, blockEndIdx(bodyStart))]);
 
     // Hooks: capture compact return object shape for use* functions.
@@ -104,6 +110,7 @@ function extract(src) {
     const asyncKw = /=\s*async\s+/.test(m[0]) ? 'async ' : '';
     const params = normalizeParams(m[2]);
     sigs.push(`export const ${m[1]} = ${asyncKw}(${params}) =>`);
+    docHintFor[sigs.length - 1] = docHints.get(m[1]);
     const bodyStart = stripped.indexOf('{', m.index + m[0].length);
     const endLn = bodyStart !== -1
       ? lineAt(stripped, blockEndIdx(bodyStart + 1))
@@ -153,7 +160,10 @@ function extract(src) {
     }
   }
 
-  const withAnchors = sigs.map((s, i) => (anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s));
+  const withAnchors = sigs.map((s, i) => {
+    const anchored = anchors[i] ? withAnchor(s, anchors[i][0], anchors[i][1]) : s;
+    return docHintFor[i] ? `${anchored}  # ${docHintFor[i]}` : anchored;
+  });
   return capWithNotice(withAnchors, 35, 'signatures');
 }
 
@@ -218,4 +228,34 @@ function normalizeParams(params) {
   return params.trim().replace(/\s+/g, ' ').replace(/:[^,)]+/g, '').trim();
 }
 
+// First prose sentence of the JSDoc block immediately preceding an exported
+// top-level function (function or arrow-const form). Mirrors the Python
+// extractor's extractDocHint: first sentence only, 60-char cap.
+function buildDocHints(src) {
+  const hints = new Map();
+  // Body may not contain `*/` — otherwise a failed adjacency check would let
+  // the match expand across a whole function to the next comment block and
+  // misattribute the hint.
+  const patterns = [
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+(?:async\s+)?function\s+(\w+)\s*[<(]/g,
+    /\/\*\*((?:[^*]|\*(?!\/))*)\*\/\s*export\s+const\s+(\w+)\s*[:=]/g,
+  ];
+  for (const re of patterns) {
+    for (const m of src.matchAll(re)) {
+      const hint = firstDocSentence(m[1]);
+      if (hint && !hints.has(m[2])) hints.set(m[2], hint);
+    }
+  }
+  return hints;
+}
+
+// First non-tag prose line of a JSDoc body → first sentence, 60-char cap.
+function firstDocSentence(body) {
+  const line = String(body).split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .find((l) => l && !l.startsWith('@'));
+  if (!line) return '';
+  return line.split(/[.!?]/)[0].trim().slice(0, 60);
+}
+
 module.exports = { extract };

package/src/mcp/server.js

@@ -18,7 +18,7 @@ const { readContext, searchSignatures, getMap, createCheckpoint, getRouting, exp
 
 const SERVER_INFO = {
   name: 'sigmap',
-  version: '8.19.0',
+  version: '8.20.0',
   description: 'SigMap MCP server — code signatures on demand',
 };
 

package/src/session/memory-inspect.js

@@ -0,0 +1,86 @@
+'use strict';
+
+/**
+ * memory-inspect.js — one view over SigMap's existing cross-session stores.
+ * No new storage: reads the JSON/NDJSON files the session, notes, weights,
+ * evidence, and tracking modules already own under `.context/`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** store name → { file, kind } (kind drives the entry count). */
+const STORES = {
+  session: { file: 'session.json', kind: 'json' },
+  notes: { file: 'notes.ndjson', kind: 'ndjson' },
+  weights: { file: 'weights.json', kind: 'weights' },
+  evidence: { file: 'evidence-pack.json', kind: 'json' },
+  gain: { file: 'gain.ndjson', kind: 'ndjson' },
+  usage: { file: 'usage.ndjson', kind: 'ndjson' },
+};
+
+/** Stores `clearMemory` may delete ('gain'/'usage' have their own reset flows). */
+const CLEARABLE = ['session', 'notes', 'weights', 'evidence'];
+
+function storePath(cwd, name) {
+  return path.join(cwd, '.context', STORES[name].file);
+}
+
+function countEntries(kind, filePath) {
+  try {
+    if (kind === 'ndjson') {
+      return fs.readFileSync(filePath, 'utf8').split('\n').filter(Boolean).length;
+    }
+    if (kind === 'weights') {
+      const w = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+      return Object.keys((w && w.files) || w || {}).length;
+    }
+    return 1; // json: a single snapshot object
+  } catch (_) {
+    return 0;
+  }
+}
+
+/**
+ * Describe every cross-session store.
+ * @param {string} cwd
+ * @returns {Array<{store:string, path:string, exists:boolean, entries:number, bytes:number, modified:string|null, clearable:boolean}>}
+ */
+function inspectMemory(cwd) {
+  return Object.entries(STORES).map(([store, { file, kind }]) => {
+    const p = storePath(cwd, store);
+    let stat = null;
+    try { stat = fs.statSync(p); } catch (_) {}
+    return {
+      store,
+      path: path.join('.context', file),
+      exists: !!stat,
+      entries: stat ? countEntries(kind, p) : 0,
+      bytes: stat ? stat.size : 0,
+      modified: stat ? new Date(stat.mtimeMs).toISOString() : null,
+      clearable: CLEARABLE.includes(store),
+    };
+  });
+}
+
+/**
+ * Delete one clearable store (or 'all' clearable stores).
+ * @param {string} cwd
+ * @param {string} store - session|notes|weights|evidence|all
+ * @returns {string[]} names of stores actually removed
+ */
+function clearMemory(cwd, store) {
+  const targets = store === 'all' ? CLEARABLE : [store];
+  for (const t of targets) {
+    if (!CLEARABLE.includes(t)) {
+      throw new Error(`unknown or protected store "${t}" — clearable: ${CLEARABLE.join(', ')}, all`);
+    }
+  }
+  const removed = [];
+  for (const t of targets) {
+    try { fs.unlinkSync(storePath(cwd, t)); removed.push(t); } catch (_) {}
+  }
+  return removed;
+}
+
+module.exports = { inspectMemory, clearMemory, STORES, CLEARABLE };