@kevin0181/memoc 1.0.5 → 1.0.8

package/README.md

@@ -46,9 +46,13 @@ npx @kevin0181/memoc update
 # Print current status in ~10 lines
 npx @kevin0181/memoc summary
 
-# Find relevant files before opening them (token-efficient)
-npx @kevin0181/memoc search "auth"
-npx @kevin0181/memoc search "auth" --snippets --limit 5
+# Search memory/agent docs first (token-efficient)
+npx @kevin0181/memoc search "auth"
+npx @kevin0181/memoc search "auth" --snippets --limit 5
+
+# Search project source/text files only when memory is not enough
+npx @kevin0181/memoc grep "GetParticles"
+npx @kevin0181/memoc grep "GetParticles" --snippets --limit 5
 
 # Estimate token cost of current memory files
 npx @kevin0181/memoc tokens

package/bin/cli.js

@@ -208,16 +208,16 @@ function write(filePath, content) {
   fs.writeFileSync(filePath, content, 'utf8');
 }
 
-function tplMemocCmdWrapper() {
-  return `@echo off\r\nnpm exec --yes --package "@kevin0181/memoc" -- memoc %*\r\n`;
+function tplMemocCmdWrapper(cliPath = runtimeCliPath()) {
+  return `@echo off\r\nnode "${escapeCmdPath(cliPath)}" %*\r\n`;
 }
 
-function tplMemocPs1Wrapper() {
-  return `npm exec --yes --package '@kevin0181/memoc' -- memoc @args\nexit $LASTEXITCODE\n`;
+function tplMemocPs1Wrapper(cliPath = runtimeCliPath()) {
+  return `& node ${psSingleQuote(cliPath)} @args\nexit $LASTEXITCODE\n`;
 }
 
-function tplMemocShWrapper() {
-  return `#!/bin/sh\nexec npm exec --yes --package '@kevin0181/memoc' -- memoc "$@"\n`;
+function tplMemocShWrapper(cliPath = runtimeCliPath()) {
+  return `#!/bin/sh\nexec node ${shellSingleQuote(cliPath)} "$@"\n`;
 }
 
 function defaultUserBinDir() {
@@ -228,6 +228,18 @@ function defaultUserBinDir() {
   return path.join(process.env.HOME || process.cwd(), '.local', 'bin');
 }
 
+function defaultRuntimeDir() {
+  if (process.env.MEMOC_RUNTIME_DIR) return process.env.MEMOC_RUNTIME_DIR;
+  if (currentPlatform() === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(process.env.USERPROFILE || process.cwd(), 'AppData', 'Local'), 'memoc', 'runtime');
+  }
+  return path.join(process.env.HOME || process.cwd(), '.local', 'share', 'memoc', 'runtime');
+}
+
+function runtimeCliPath() {
+  return path.join(defaultRuntimeDir(), 'bin', 'cli.js');
+}
+
 function tplEnvPs1() {
   return `$memocBin = Join-Path $PSScriptRoot 'bin'\n$parts = $env:PATH -split [IO.Path]::PathSeparator\nif ($parts -notcontains $memocBin) {\n  $env:PATH = \"$memocBin$([IO.Path]::PathSeparator)$env:PATH\"\n}\n`;
 }
@@ -237,10 +249,11 @@ function tplEnvSh() {
 }
 
 function ensurePathHelpers(dir, mark) {
+  const cliPath = ensureRuntimeInstall(mark);
   const files = [
-    [path.join(dir, '.memoc', 'bin', 'memoc.cmd'), tplMemocCmdWrapper, false],
-    [path.join(dir, '.memoc', 'bin', 'memoc.ps1'), tplMemocPs1Wrapper, false],
-    [path.join(dir, '.memoc', 'bin', 'memoc'), tplMemocShWrapper, true],
+    [path.join(dir, '.memoc', 'bin', 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
+    [path.join(dir, '.memoc', 'bin', 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
+    [path.join(dir, '.memoc', 'bin', 'memoc'), () => tplMemocShWrapper(cliPath), true],
     [path.join(dir, '.memoc', 'env.ps1'), tplEnvPs1, false],
     [path.join(dir, '.memoc', 'env.sh'), tplEnvSh, true],
   ];
@@ -255,15 +268,15 @@ function ensurePathHelpers(dir, mark) {
 
 function ensureUserLauncher(mark) {
   const userBin = defaultUserBinDir();
-  writeLaunchers(userBin, mark, 'user bin');
+  writeLaunchers(userBin, mark, 'user bin', ensureRuntimeInstall(mark));
   return userBin;
 }
 
-function writeLaunchers(binDir, mark, label) {
+function writeLaunchers(binDir, mark, label, cliPath = ensureRuntimeInstall(mark)) {
   const files = [
-    [path.join(binDir, 'memoc.cmd'), tplMemocCmdWrapper, false],
-    [path.join(binDir, 'memoc.ps1'), tplMemocPs1Wrapper, false],
-    [path.join(binDir, 'memoc'), tplMemocShWrapper, true],
+    [path.join(binDir, 'memoc.cmd'), () => tplMemocCmdWrapper(cliPath), false],
+    [path.join(binDir, 'memoc.ps1'), () => tplMemocPs1Wrapper(cliPath), false],
+    [path.join(binDir, 'memoc'), () => tplMemocShWrapper(cliPath), true],
   ];
 
   for (const [fp, tpl, executable] of files) {
@@ -341,10 +354,32 @@ function ensureCurrentPathLauncher(mark) {
     mark('skip', 'active PATH launcher (no writable PATH directory found)');
     return false;
   }
-  writeLaunchers(target, mark, 'active PATH');
+  writeLaunchers(target, mark, 'active PATH', ensureRuntimeInstall(mark));
   return true;
 }
 
+function ensureRuntimeInstall(mark) {
+  const runtimeDir = defaultRuntimeDir();
+  const sourceRoot = path.join(__dirname, '..');
+  const files = [
+    [path.join(sourceRoot, 'bin', 'cli.js'), path.join(runtimeDir, 'bin', 'cli.js')],
+    [path.join(sourceRoot, 'package.json'), path.join(runtimeDir, 'package.json')],
+  ];
+
+  for (const [src, dest] of files) {
+    try {
+      const content = fs.readFileSync(src, 'utf8');
+      const changed = writeIfChanged(dest, content);
+      mark(changed, `runtime ${path.relative(runtimeDir, dest)}`);
+    } catch {
+      mark('skip', `runtime ${path.basename(dest)} unavailable`);
+    }
+  }
+
+  chmodExecutable(path.join(runtimeDir, 'bin', 'cli.js'));
+  return path.join(runtimeDir, 'bin', 'cli.js');
+}
+
 function findWritablePathDir() {
   const dirs = [...new Set((process.env.PATH || '').split(path.delimiter).filter(Boolean))];
   const npmBin = npmGlobalBinDir();
@@ -447,6 +482,14 @@ function shellSingleQuote(value) {
   return `'${String(value).replace(/'/g, `'\\''`)}'`;
 }
 
+function psSingleQuote(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function escapeCmdPath(value) {
+  return String(value).replace(/"/g, '""');
+}
+
 function samePath(a, b) {
   if (!a || !b) return false;
   const norm = p => path.resolve(p).toLowerCase().replace(/[\\/]+$/, '');
@@ -503,7 +546,8 @@ function managedBlock() {
 ## Before Opening More Files
 - [ ] Run memoc commands in this order: \`memoc search "<query>"\` → \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` (Windows) or \`.memoc/bin/memoc search "<query>"\` (sh) → \`npx @kevin0181/memoc search "<query>"\`
 - [ ] Open on demand: \`02\` status · \`04\` resume · \`06\` rules · \`llms.txt\` map
-- [ ] Keep output small: \`summary\`, \`search --limit\`, \`search --snippets\`
+- [ ] If memory search is not enough, search project files with \`memoc grep "<query>" --limit 5\`
+- [ ] Keep output small: \`summary\`, \`search --limit\`, \`grep --limit\`, \`--snippets\`
 
 ## Before Finishing _(update only applicable files; skip Q&A / throwaway exploration)_
 - [ ] Code/config/deps changed → \`02\` (version, commands list, Last synced) + \`session-summary.md\` (status, changed, open tasks)
@@ -816,7 +860,8 @@ On-demand reference only. The entry-file managed block is authoritative.
 
 ## Search First
 
-\`memoc search "<query>"\` — returns file:line matches across all memory files.
+\`memoc search "<query>"\` — returns file:line matches across memory and agent docs only.
+\`memoc grep "<query>"\` — searches project source/text files when memory docs are not enough.
 If \`memoc\` is not on PATH, try \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` on Windows or \`.memoc/bin/memoc search "<query>"\` in sh, then \`npx @kevin0181/memoc search "<query>"\`.
 Use it before opening any file to avoid reading more than needed.
 `;
@@ -996,9 +1041,13 @@ memoc update
 # Tiny status overview
 memoc summary
 
-# Find files first; add --snippets only when needed
-memoc search "<query>" --limit 12
+# Search memory first; add --snippets only when needed
+memoc search "<query>" --limit 12
 memoc search "<query>" --snippets --limit 5
+
+# Search project source/text files when memory is not enough
+memoc grep "<query>" --limit 12
+memoc grep "<query>" --snippets --limit 5
 \`\`\`
 
 If \`memoc\` is not on PATH, use \`.\\.memoc\\bin\\memoc.cmd <command>\` on Windows or \`.memoc/bin/memoc <command>\` in sh. If that is unavailable, use \`npx @kevin0181/memoc <command>\`.
@@ -1007,9 +1056,9 @@ If \`memoc\` is not on PATH, use \`.\\.memoc\\bin\\memoc.cmd <command>\` on Wind
 
 1. Entry-file managed block.
 2. \`.memoc/session-summary.md\` only.
-3. Search in this order: \`memoc search "<query>"\`, \`.\\.memoc\\bin\\memoc.cmd search "<query>"\` or \`.memoc/bin/memoc search "<query>"\`, \`npx @kevin0181/memoc search "<query>"\`.
-4. Use \`--snippets\` only when file names are not enough.
-5. Open only task-relevant memory files.
+3. Search memory first: \`memoc search "<query>"\`.
+4. If memory is not enough, search project files: \`memoc grep "<query>" --limit 5\`.
+5. Use \`--snippets\` only when file names are not enough.
 
 ## When To Run Memory Updates
 
@@ -1103,7 +1152,7 @@ Use this local skill after meaningful project work so future agents can continue
 ## Required Reads
 
 1. \`.memoc/session-summary.md\`
-2. \`memoc summary\` or \`memoc search "<query>"\`; if unavailable, use \`.\\.memoc\\bin\\memoc.cmd <command>\` or \`.memoc/bin/memoc <command>\`, then \`npx @kevin0181/memoc <command>\`
+2. \`memoc summary\` or \`memoc search "<query>"\`; use \`memoc grep "<query>"\` only when source/text search is needed
 3. Open only files you will use or update.
 
 ## Maintenance Checklist
@@ -1427,9 +1476,9 @@ function runAdd(dir) {
 // SEARCH
 // ═══════════════════════════════════════════════════════════════════
 
-function runSearch(dir) {
-  const rawArgs = process.argv.slice(3);
-  const opts = { mode: 'files', limit: 12, all: false };
+function runSearch(dir, scope = 'memory') {
+  const rawArgs = process.argv.slice(3);
+  const opts = { mode: 'files', limit: 12, all: false };
   const queryParts = [];
 
   for (let i = 0; i < rawArgs.length; i++) {
@@ -1450,19 +1499,12 @@ function runSearch(dir) {
     queryParts.push(arg);
   }
 
-  const query = queryParts.join(' ').toLowerCase();
-
-  const searchRoots = [
-    path.join(dir, '.memoc'),
-    path.join(dir, 'skills'),
-    path.join(dir, 'llms.txt'),
-    path.join(dir, 'AGENTS.md'),
-    path.join(dir, 'CLAUDE.md'),
-    ...Object.values(AGENT_REGISTRY).map(agent => path.join(dir, agent.file)),
-  ];
+  const query = queryParts.join(' ').toLowerCase();
+
+  const searchRoots = scope === 'project' ? [dir] : memorySearchRoots(dir);
 
   if (!query) {
-    // No query — list all memory files sorted by recency
+    // No query — list searchable files sorted by recency
     const allFiles = [];
     function collectFile(fp) {
       if (!fs.existsSync(fp)) return;
@@ -1476,8 +1518,10 @@ function runSearch(dir) {
       for (const entry of fs.readdirSync(d)) {
         const fp = path.join(d, entry);
         try {
-          if (fs.statSync(fp).isDirectory()) collectDir(fp);
-          else if (entry.endsWith('.md') || entry === 'llms.txt' || entry.endsWith('rules')) collectFile(fp);
+          const st = fs.statSync(fp);
+          if (st.isDirectory()) {
+            if (!shouldSkipSearchDir(entry)) collectDir(fp);
+          } else if (isSearchableFile(fp, entry, st, scope)) collectFile(fp);
         } catch {}
       }
     }
@@ -1498,11 +1542,15 @@ function runSearch(dir) {
 
   const matchesByFile = new Map(); // rel -> { matches: [], mtime: number }
 
-  function searchFile(fp) {
-    if (!fs.existsSync(fp)) return;
-    const rel = path.relative(dir, fp);
-    let mtime = 0;
-    try { mtime = fs.statSync(fp).mtimeMs; } catch {}
+  function searchFile(fp) {
+    if (!fs.existsSync(fp)) return;
+    const rel = path.relative(dir, fp);
+    let mtime = 0;
+    try {
+      const st = fs.statSync(fp);
+      if (!isSearchableFile(fp, path.basename(fp), st, scope)) return;
+      mtime = st.mtimeMs;
+    } catch {}
     const lines = fs.readFileSync(fp, 'utf8').split('\n');
     lines.forEach((line, i) => {
       if (line.toLowerCase().includes(query)) {
@@ -1517,8 +1565,10 @@ function runSearch(dir) {
     for (const entry of fs.readdirSync(d)) {
       const fp = path.join(d, entry);
       try {
-        if (fs.statSync(fp).isDirectory()) walkDir(fp);
-        else if (entry.endsWith('.md') || entry === 'llms.txt' || entry.endsWith('rules')) searchFile(fp);
+        const st = fs.statSync(fp);
+        if (st.isDirectory()) {
+          if (!shouldSkipSearchDir(entry)) walkDir(fp);
+        } else if (isSearchableFile(fp, entry, st, scope)) searchFile(fp);
       } catch {}
     }
   }
@@ -1552,7 +1602,44 @@ function runSearch(dir) {
       console.log(`... ${snippets.length - limited.length} more matches. Use --all to show all, or --limit N.`);
     }
   }
-}
+}
+
+function memorySearchRoots(dir) {
+  return [
+    path.join(dir, '.memoc'),
+    path.join(dir, 'skills'),
+    path.join(dir, 'llms.txt'),
+    path.join(dir, 'AGENTS.md'),
+    path.join(dir, 'CLAUDE.md'),
+    ...Object.values(AGENT_REGISTRY).map(agent => path.join(dir, agent.file)),
+  ];
+}
+
+function shouldSkipSearchDir(name) {
+  return new Set([
+    '.git', 'node_modules', '.next', 'dist', 'build', 'out', 'coverage',
+    'Saved', 'Intermediate', 'DerivedDataCache', 'Binaries',
+    '.venv', 'venv', '__pycache__', '.pytest_cache',
+  ]).has(name);
+}
+
+function isSearchableFile(fp, name, st, scope = 'memory') {
+  if (!st || !st.isFile()) return false;
+  if (st.size > 1024 * 1024) return false;
+  if (name === 'llms.txt' || name.endsWith('rules')) return true;
+  const ext = path.extname(fp).toLowerCase();
+  if (scope === 'memory') {
+    return new Set(['.md', '.txt']).has(ext);
+  }
+  return new Set([
+    '.md', '.txt', '.json', '.jsonc', '.yaml', '.yml', '.toml', '.ini', '.env',
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',
+    '.py', '.rs', '.go', '.java', '.cs', '.cpp', '.cc', '.cxx', '.c', '.h', '.hpp', '.hxx',
+    '.html', '.css', '.scss', '.sass', '.vue', '.svelte',
+    '.sql', '.graphql', '.gql', '.sh', '.bash', '.zsh', '.ps1', '.bat', '.cmd',
+    '.xml', '.gradle', '.kts', '.cmake',
+  ]).has(ext);
+}
 
 // ═══════════════════════════════════════════════════════════════════
 // TOKENS — estimate token cost of current memory state
@@ -1730,7 +1817,8 @@ if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
   console.log('  tokens             Estimate token cost of current memory files');
   console.log('  compress           Archive old log.md entries to keep file small');
   console.log('  add <agent>        Add entry file for a specific agent (run without args to list)');
-  console.log('  search "<query>"   Find matching files (use --snippets for line matches)');
+  console.log('  search "<query>"   Search memory/agent docs (use --snippets for line matches)');
+  console.log('  grep "<query>"     Search project source/text files (use --snippets for line matches)');
   console.log('\nSearch flags:');
   console.log('  --files            Show file names and match counts, sorted by relevance + recency (default)');
   console.log('  --snippets         Show matching lines');
@@ -1747,7 +1835,8 @@ if (cmd === 'summary')  { runSummary(cwd);    process.exit(0); }
 if (cmd === 'tokens')   { runTokens(cwd);     process.exit(0); }
 if (cmd === 'compress') { runCompress(cwd);   process.exit(0); }
 if (cmd === 'add')      { runAdd(cwd);        process.exit(0); }
-if (cmd === 'search')   { runSearch(cwd);     process.exit(0); }
+if (cmd === 'search')   { runSearch(cwd, 'memory');  process.exit(0); }
+if (cmd === 'grep')     { runSearch(cwd, 'project'); process.exit(0); }
 
 console.error(`Unknown command: ${cmd}`);
 console.error('Run "memoc --help" for usage.');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kevin0181/memoc",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Give AI agents a memory. Scaffolds session-to-session context for Claude Code, Codex, Cursor, and more.",
   "keywords": [
     "ai",