@kevin0181/memoc 1.1.10 → 1.2.0

package/README.md

@@ -144,7 +144,7 @@ Run it from the project root. It preserves existing project memory, including:
 - `.memoc/systems/`
 - `.memoc/wiki/`
 
-It refreshes the managed blocks, project-local wrappers, runtime copy, PATH helpers, and missing template files. If `memoc` is not on PATH after upgrading, keep using:
+It refreshes the managed blocks, project-local wrappers, runtime copy, PATH helpers, and memoc-owned protocol templates. User-owned memory files such as `session-summary.md`, `03-decisions.md`, `04-handoff.md`, `06-project-rules.md`, and wiki topic/source pages are preserved. Upgrade also runs the `trim-summary` compaction pass so startup memory stays small. If `memoc` is not on PATH after upgrading, keep using:
 
 ```bash
 # Windows
@@ -277,7 +277,7 @@ Actor detection order:
 
 `activity.md`, `actors/README.md`, and `worklog/README.md` are regenerated indexes. Run `memoc activity --write` when you want to refresh them from worklog files.
 
-`log.md` is legacy. New installs do not create it, and shared activity should live in worklog files. Existing projects can delete `.memoc/log.md` after preserving any useful history in worklogs or archives.
+`log.md` is legacy. New installs do not create it, and shared activity should live in worklog files. On upgrade, an existing `.memoc/log.md` is moved to `.memoc/raw/legacy-log.md` so old history is preserved but no longer part of the normal memory flow.
 
 ---
 

package/bin/cli.js

@@ -209,6 +209,12 @@ function write(filePath, content) {
   fs.writeFileSync(filePath, content, 'utf8');
 }
 
+function writeChanged(filePath, content) {
+  if (fs.existsSync(filePath) && fs.readFileSync(filePath, 'utf8') === content) return false;
+  write(filePath, content);
+  return true;
+}
+
 function slugify(value, fallback = 'note') {
   const slug = String(value || '')
     .toLowerCase()
@@ -228,6 +234,76 @@ function uniquePath(filePath) {
   return `${base}-${i}${ext}`;
 }
 
+function archiveLegacyLog(dir, mark) {
+  const logPath = path.join(dir, '.memoc', 'log.md');
+  if (!fs.existsSync(logPath)) {
+    mark('skip', '.memoc/log.md (legacy; no file)');
+    return;
+  }
+  const archivePath = uniquePath(path.join(dir, '.memoc', 'raw', 'legacy-log.md'));
+  fs.mkdirSync(path.dirname(archivePath), { recursive: true });
+  fs.renameSync(logPath, archivePath);
+  mark('move', `${path.relative(dir, logPath)} -> ${path.relative(dir, archivePath)}`);
+}
+
+function summarySectionBulletCounts(src) {
+  const counts = {};
+  let current = '';
+  for (const line of String(src || '').split(/\r?\n/)) {
+    const heading = line.match(/^##\s+(.+?)\s*$/);
+    if (heading) {
+      current = heading[1].trim();
+      counts[current] = counts[current] || 0;
+      continue;
+    }
+    if (current && /^-\s+/.test(line)) counts[current] = (counts[current] || 0) + 1;
+  }
+  return counts;
+}
+
+function trimSummaryFile(dir) {
+  const summaryPath = path.join(dir, '.memoc', 'session-summary.md');
+  const archivePath = path.join(dir, '.memoc', 'session-summary-archive.md');
+  if (!fs.existsSync(summaryPath)) {
+    write(summaryPath, tplSessionSummary());
+    return { action: 'add' };
+  }
+
+  const src = fs.readFileSync(summaryPath, 'utf8');
+  const beforeBytes = Buffer.byteLength(src, 'utf8');
+  const counts = summarySectionBulletCounts(src);
+  const tooManyBullets = Object.values(counts).some(count => count > 3);
+  if (beforeBytes <= 800 && !tooManyBullets) {
+    return { action: 'skip', beforeBytes };
+  }
+
+  const compact = compactSessionSummary(src);
+  const afterBytes = Buffer.byteLength(compact, 'utf8');
+  const archiveHeader = fs.existsSync(archivePath)
+    ? ''
+    : '# Session Summary Archive\n\nOlder oversized startup summaries moved by `memoc trim-summary`.\n';
+  fs.appendFileSync(archivePath, `${archiveHeader}\n## [${nowISO()}] archived summary (${beforeBytes}B)\n\n${src.trimEnd()}\n`, 'utf8');
+  write(summaryPath, compact);
+  return { action: 'trim', beforeBytes, afterBytes };
+}
+
+function migrateLegacyLogReferences(filePath) {
+  if (!fs.existsSync(filePath)) return false;
+  const before = fs.readFileSync(filePath, 'utf8');
+  let after = before
+    .replace(/- \[Project Log\]\(log\.md\)\n/g, '- [Activity](activity.md)\n- [Worklog](worklog/README.md)\n')
+    .replace(/\| `\.memoc\/log\.md` \| For append-only history \|\n/g, '| `.memoc/activity.md` | Generated worklog index |\n| `.memoc/worklog/` | Actor-scoped work history |\n')
+    .replace(/See `\.memoc\/log\.md` for full history\./g, 'See `.memoc/worklog/` for full shared activity history.')
+    .replace(/See `\.memoc\/log\.md`\./g, 'See `.memoc/worklog/` and generated `.memoc/activity.md`.')
+    .replace(/- \[ \] `\.memoc\/log\.md` has a new entry for meaningful work\./g, '- [ ] Meaningful shared work has a `.memoc/worklog/<actor>/YYYY-MM/*.md` entry.')
+    .replace(/Append `\.memoc\/log\.md` for meaningful changes, decisions, and handoffs\./g, 'Create a short actor worklog with `memoc work "<title>" --from-git` for meaningful changes, decisions, and handoffs.')
+    .replace(/Keep completed history in `\.memoc\/log\.md`; keep current-state files short\./g, 'Keep completed history in actor worklogs; keep current-state files short.')
+    .replace(/Append `\.memoc\/log\.md`\./g, 'If the change is meaningful shared work, run `memoc work "<title>" --from-git`.');
+  if (after === before) return false;
+  write(filePath, after);
+  return true;
+}
+
 function markdownTitle(src, fallback) {
   const m = String(src || '').match(/^#\s+(.+)$/m);
   return m ? m[1].trim() : fallback;
@@ -2252,10 +2328,18 @@ function run(dir, forceUpdate, action = 'update') {
       mark('add', 'llms.txt');
     }
 
-    // Dynamic memory files — update managed sections only
+    // Generated memory maps — replace so old protocols do not linger.
+    const generatedRefresh = [
+      [path.join(memDir, '00-project-brief.md'),       () => tplProjectBrief(p)],
+      [path.join(memDir, '00-agent-index.md'),         () => tplAgentIndex(p)],
+    ];
+    for (const [fp, tpl] of generatedRefresh) {
+      const rel = path.relative(dir, fp);
+      mark(writeChanged(fp, tpl()) ? 'update' : 'skip', rel);
+    }
+
+    // Dynamic user-owned memory files — update managed sections only
     const dynUpdates = [
-      [path.join(memDir, '00-project-brief.md'),       () => tplProjectBrief(p),   ID_S,   ID_E,   identityInner(p)],
-      [path.join(memDir, '00-agent-index.md'),         () => tplAgentIndex(p),     SNAP_S, SNAP_E, snapshotInner(p)],
       [path.join(memDir, '02-current-project-state.md'), () => tplCurrentState(p), SNAP_S, SNAP_E, snapshotInner(p)],
     ];
     for (const [fp, tpl, s, e, inner] of dynUpdates) {
@@ -2283,18 +2367,27 @@ function run(dir, forceUpdate, action = 'update') {
       mark('add', '.memoc/session-summary.md');
     }
 
-    // Static + user-owned files — only add if missing
-    const addIfMissing = [
+    // Protocol/template files — replace on update so old instructions are removed.
+    const templateRefresh = [
       [path.join(memDir, 'boot.md'),                   tplBoot],
       [path.join(memDir, '01-agent-workflow.md'),      tplWorkflow],
+      [path.join(memDir, '05-done-checklist.md'),      tplDoneChecklist],
+      [path.join(memDir, 'memoc-usage.md'),            tplMemocUsage],
+      [path.join(dir,    'skills/project-memory-maintainer/SKILL.md'), tplSkillMaintainer],
+    ];
+    for (const [fp, tpl] of templateRefresh) {
+      const rel = path.relative(dir, fp);
+      mark(writeChanged(fp, tpl()) ? 'update' : 'skip', rel);
+    }
+
+    // Static indexes/scaffolds — add if missing; content may be user- or command-owned.
+    const addIfMissing = [
       [path.join(memDir, '03-decisions.md'),           tplDecisions],
       [path.join(memDir, '04-handoff.md'),             tplHandoff],
-      [path.join(memDir, '05-done-checklist.md'),      tplDoneChecklist],
       [path.join(memDir, '06-project-rules.md'),       tplProjectRules],
       [path.join(memDir, 'activity.md'),               tplActivity],
       [path.join(memDir, 'actors/README.md'),          tplActorsReadme],
       [path.join(memDir, 'worklog/README.md'),         tplWorklogReadme],
-      [path.join(memDir, 'memoc-usage.md'),    tplMemocUsage],
       [path.join(memDir, 'systems/README.md'),         tplSystemsReadme],
       [path.join(memDir, 'raw/README.md'),             tplRawReadme],
       [path.join(memDir, 'raw/files/README.md'),       tplRawFilesReadme],
@@ -2309,7 +2402,6 @@ function run(dir, forceUpdate, action = 'update') {
       [path.join(memDir, 'wiki/sources/README.md'),    tplWikiSourcesReadme],
       [path.join(memDir, 'wiki/topics/README.md'),     tplWikiTopicsReadme],
       [path.join(memDir, 'wiki/global/README.md'),     tplWikiGlobalReadme],
-      [path.join(dir,    'skills/project-memory-maintainer/SKILL.md'), tplSkillMaintainer],
     ];
     for (const [fp, tpl] of addIfMissing) {
       const rel = path.relative(dir, fp);
@@ -2318,8 +2410,20 @@ function run(dir, forceUpdate, action = 'update') {
     }
     ensureWikiScaffoldLinks(memDir, mark);
 
-    // Obsidian graph filters — add/merge memoc tags for existing installs too
-    ensureObsidianFrontmatter(dir, mark);
+    const legacyReferenceFiles = [
+      path.join(memDir, '02-current-project-state.md'),
+      path.join(memDir, '04-handoff.md'),
+      path.join(memDir, '06-project-rules.md'),
+      path.join(memDir, 'systems/README.md'),
+      path.join(memDir, 'wiki/index.md'),
+      path.join(memDir, 'wiki/sources.md'),
+      path.join(memDir, 'wiki/glossary.md'),
+      path.join(memDir, 'wiki/questions.md'),
+      path.join(memDir, 'wiki/lint.md'),
+    ];
+    for (const fp of legacyReferenceFiles) {
+      if (migrateLegacyLogReferences(fp)) mark('update', `${path.relative(dir, fp)} (legacy refs)`);
+    }
 
     // PATH helpers — let agents run memoc even when the npm bin is not on PATH
     ensureClaudeStopHookFile(dir, mark);
@@ -2327,7 +2431,20 @@ function run(dir, forceUpdate, action = 'update') {
     ensurePathHelpers(dir, mark);
     ensurePathRegistration(dir, mark);
 
-    mark('skip', '.memoc/log.md (legacy; shared history belongs in worklog)');
+    archiveLegacyLog(dir, mark);
+
+    const trim = trimSummaryFile(dir);
+    if (trim.action === 'trim') {
+      mark('update', `.memoc/session-summary.md (trimmed ${trim.beforeBytes}B -> ${trim.afterBytes}B)`);
+      mark('update', '.memoc/session-summary-archive.md');
+    } else if (trim.action === 'add') {
+      mark('add', '.memoc/session-summary.md');
+    } else {
+      mark('skip', `.memoc/session-summary.md (compact ${trim.beforeBytes || 0}B)`);
+    }
+
+    // Obsidian graph filters — add/merge memoc tags for existing installs too
+    ensureObsidianFrontmatter(dir, mark);
   }
 
   hideOnWindows(memDir);
@@ -3326,37 +3443,24 @@ function runCompress(dir) {
 // ═══════════════════════════════════════════════════════════════════
 
 function runTrimSummary(dir) {
-  const summaryPath = path.join(dir, '.memoc', 'session-summary.md');
-  const archivePath = path.join(dir, '.memoc', 'session-summary-archive.md');
-  if (!fs.existsSync(summaryPath)) {
-    write(summaryPath, tplSessionSummary());
+  const result = trimSummaryFile(dir);
+  if (result.action === 'add') {
     console.log('\n  memoc trim-summary\n');
     console.log('    Added .memoc/session-summary.md');
     console.log('\n  Done.\n');
     return;
   }
 
-  const src = fs.readFileSync(summaryPath, 'utf8');
-  const beforeBytes = Buffer.byteLength(src, 'utf8');
-  const compact = compactSessionSummary(src);
-  const afterBytes = Buffer.byteLength(compact, 'utf8');
-
-  if (src === compact && beforeBytes <= 800) {
+  if (result.action === 'skip') {
     console.log('\n  memoc trim-summary\n');
-    console.log(`    session-summary.md is already compact (${beforeBytes}B).`);
+    console.log(`    session-summary.md is already compact (${result.beforeBytes}B).`);
     console.log('\n  Done.\n');
     return;
   }
 
-  const archiveHeader = fs.existsSync(archivePath)
-    ? ''
-    : '# Session Summary Archive\n\nOlder oversized startup summaries moved by `memoc trim-summary`.\n';
-  fs.appendFileSync(archivePath, `${archiveHeader}\n## [${nowISO()}] archived summary (${beforeBytes}B)\n\n${src.trimEnd()}\n`, 'utf8');
-  write(summaryPath, compact);
-
   console.log('\n  memoc trim-summary\n');
   console.log(`    Archived  .memoc/session-summary-archive.md`);
-  console.log(`    Rewrote   .memoc/session-summary.md (${beforeBytes}B → ${afterBytes}B)`);
+  console.log(`    Rewrote   .memoc/session-summary.md (${result.beforeBytes}B → ${result.afterBytes}B)`);
   console.log('    Reminder  Completed history belongs in worklog; resume details belong in 04-handoff.md.');
   console.log('\n  Done.\n');
 }

package/package.json

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