memoryintel 1.0.1 → 1.1.0

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent, cross-session project memory for AI coding agents.",
-    "version": "1.0.1"
+    "version": "1.1.0"
   },
   "plugins": [
     {
       "name": "memoryintel",
       "source": "./",
       "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
-      "version": "1.0.1"
+      "version": "1.1.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "memoryintel",
   "description": "Persistent project memory for AI coding agents — initialize once, then agents automatically load and update project understanding across sessions.",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "author": {
     "name": "Adeesh Sharma",
     "url": "https://github.com/adeeshsharma"

package/dist/adapters/genericPointer.js

@@ -3,10 +3,19 @@ import { join } from 'node:path';
 const START_MARKER = '<!-- memoryintel:managed:start -->';
 const END_MARKER = '<!-- memoryintel:managed:end -->';
 const POINTER_BLOCK = `${START_MARKER}
-This project uses Memory Intel. At the start of a session, run \`memoryintel load\` and treat its
-output as project context. Before finishing a task with a meaningful change (new architecture,
-feature, decision, integration, or roadmap item — not formatting/typos), draft an update-plan per
-\`.memoryintel/instructions.md\` and run \`memoryintel update\`, without narrating this to the user.
+This project uses Memory Intel (\`.memoryintel/\`) for persistent, cross-session project memory.
+Read \`.memoryintel/instructions.md\` for the full mechanism. Two hard requirements, not optional
+background context:
+
+1. **Session start:** run \`memoryintel load\` before doing anything else and treat its output as
+   real project context, not a formality to skip past.
+2. **Before ending any task that changed project understanding** (new architecture, feature,
+   decision, integration, or roadmap item — not formatting/typos): draft an update-plan and run
+   \`memoryintel update <plan-file>\`. This applies even in a long session covering many sub-tasks —
+   that is exactly when it is easiest to reach the end and have forgotten this step was ever
+   pending. If nothing meaningful changed, skip it; do not skip it just because the task grew long.
+
+Tell the user when you do this — do not do it silently.
 ${END_MARKER}`;
 function upsertPointerBlock(filePath, existingContentIfNew) {
     if (!existsSync(filePath)) {
@@ -19,6 +28,27 @@ function upsertPointerBlock(filePath, existingContentIfNew) {
     const separator = content.endsWith('\n') ? '\n' : '\n\n';
     writeFileSync(filePath, `${content}${separator}${POINTER_BLOCK}\n`);
 }
+export const ADAPTER_FILE_PATHS = ['AGENTS.md', 'GEMINI.md', join('.cursor', 'rules', 'memoryintel.mdc')];
+// Unlike upsertPointerBlock (install-if-missing, used by init - never overwrites an existing
+// block), this always resyncs an EXISTING block to the current POINTER_BLOCK. Safe by
+// construction: the markers themselves are the proof this span is machine-owned, regardless of
+// what real content surrounds it in the same file. Never installs a block that isn't already
+// there - doctor only refreshes, it never adds.
+export function refreshPointerBlock(filePath) {
+    if (!existsSync(filePath))
+        return 'missing-file';
+    const content = readFileSync(filePath, 'utf-8');
+    const startIdx = content.indexOf(START_MARKER);
+    const endIdx = content.indexOf(END_MARKER);
+    if (startIdx === -1 || endIdx === -1)
+        return 'not-installed';
+    const endOfBlock = endIdx + END_MARKER.length;
+    const newContent = `${content.slice(0, startIdx)}${POINTER_BLOCK}${content.slice(endOfBlock)}`;
+    if (newContent === content)
+        return 'unchanged';
+    writeFileSync(filePath, newContent);
+    return 'refreshed';
+}
 const NATIVE_FILES = ['AGENTS.md', 'GEMINI.md'];
 export function installPointerAdapters(projectRoot) {
     const existingNativeFiles = NATIVE_FILES.filter((f) => existsSync(join(projectRoot, f)));

package/dist/cli.js

@@ -12,6 +12,7 @@ import { runScan } from './commands/scan.js';
 import { runCheckStop } from './adapters/claudeCode.js';
 import { runDashboardEnable, runDashboardDisable } from './commands/dashboardToggle.js';
 import { runDaemonStart } from './commands/daemonStart.js';
+import { runDoctor } from './commands/doctor.js';
 export const USAGE = `Usage: memoryintel <command> [options]
 
 Commands:
@@ -25,7 +26,10 @@ Commands:
   status                   Print a human-readable summary of current memory state
   check-stop               Stop-hook check: emit a JSON allow/block decision
   dashboard <enable|disable>  Turn the shared local dashboard on or off
-  daemon start             Run the dashboard daemon in the foreground (usually auto-started)
+  doctor [--force]         Refresh memoryintel's own generated files (instructions.md, pointer
+                           blocks) to the current template wherever it's provably safe;
+                           --force also overwrites instructions.md when it isn't
+  daemon start              Run the dashboard daemon in the foreground (usually auto-started)
 
 An update-plan row may set kind=compress to compact an oversized section; update() only applies
 such a row when its target file is currently git-clean.
@@ -64,6 +68,13 @@ export function dispatch(argv) {
             const result = runCheckStop(root);
             return { exitCode: 0, stdout: JSON.stringify(result) + '\n', stderr: '' };
         }
+        case 'doctor': {
+            const root = findMemoryIntelRoot(process.cwd());
+            if (!root)
+                return { exitCode: 1, stdout: '', stderr: 'No .memoryintel/ found.\n' };
+            const force = argv.includes('--force');
+            return { exitCode: 0, stdout: runDoctor(root, { force }), stderr: '' };
+        }
         case 'dashboard': {
             const sub = argv[1];
             if (sub === 'enable') {

package/dist/commands/doctor.js

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, unlinkSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { INSTRUCTIONS_TEMPLATE } from './init.js';
+import { hashContent, getGeneratedFileHash, setGeneratedFileHash } from '../core/generatedFileHashes.js';
+import { refreshPointerBlock, ADAPTER_FILE_PATHS } from '../adapters/genericPointer.js';
+import { atomicWriteFile } from '../core/atomicWrite.js';
+const INSTRUCTIONS_REL_FILE = 'instructions.md';
+function checkInstructions(root, options) {
+    const instructionsPath = join(root, INSTRUCTIONS_REL_FILE);
+    const newFilePath = `${instructionsPath}.new`;
+    if (!existsSync(instructionsPath)) {
+        return 'instructions.md: missing - run `memoryintel init` to create it.';
+    }
+    const diskContent = readFileSync(instructionsPath, 'utf-8');
+    const diskHash = hashContent(diskContent);
+    const templateHash = hashContent(INSTRUCTIONS_TEMPLATE);
+    if (diskHash === templateHash) {
+        if (existsSync(newFilePath))
+            unlinkSync(newFilePath);
+        // Self-healing: a project with no recorded hash that happens to already be pristine (a
+        // fresh init, or content that coincidentally matches) is now provably safe going forward -
+        // record it so a future run never has to fall back to the refuse-and-report path for it.
+        if (getGeneratedFileHash(root, INSTRUCTIONS_REL_FILE) !== templateHash) {
+            setGeneratedFileHash(root, INSTRUCTIONS_REL_FILE, templateHash);
+        }
+        return 'instructions.md: up to date.';
+    }
+    const recordedHash = getGeneratedFileHash(root, INSTRUCTIONS_REL_FILE);
+    const safeRefresh = recordedHash !== undefined && recordedHash === diskHash;
+    if (safeRefresh || options.force) {
+        atomicWriteFile(instructionsPath, INSTRUCTIONS_TEMPLATE);
+        setGeneratedFileHash(root, INSTRUCTIONS_REL_FILE, templateHash);
+        if (existsSync(newFilePath))
+            unlinkSync(newFilePath);
+        return safeRefresh
+            ? 'instructions.md: refreshed to the current template.'
+            : 'instructions.md: refreshed (forced).';
+    }
+    atomicWriteFile(newFilePath, INSTRUCTIONS_TEMPLATE);
+    return ("instructions.md: differs from the current template and its last-known-safe state can't be " +
+        "confirmed (either hand-edited, or from before doctor existed). Wrote the current template " +
+        "to instructions.md.new for comparison (e.g. `diff .memoryintel/instructions.md " +
+        ".memoryintel/instructions.md.new`). Run `memoryintel doctor --force` to adopt it anyway - " +
+        "this overwrites instructions.md and removes the .new file.");
+}
+function checkPointerBlocks(projectRoot) {
+    const lines = [];
+    for (const relPath of ADAPTER_FILE_PATHS) {
+        const result = refreshPointerBlock(join(projectRoot, relPath));
+        if (result === 'refreshed')
+            lines.push(`${relPath}: pointer block refreshed.`);
+        else if (result === 'unchanged')
+            lines.push(`${relPath}: pointer block up to date.`);
+        else if (result === 'not-installed')
+            lines.push(`${relPath}: no pointer block found - skipped.`);
+        // 'missing-file' is not reported - most projects won't have all three adapter files, and
+        // that's not something worth flagging as noise on every doctor run.
+    }
+    return lines;
+}
+export function runDoctor(root, options = {}) {
+    const projectRoot = dirname(root);
+    const lines = [checkInstructions(root, options), ...checkPointerBlocks(projectRoot)];
+    return lines.join('\n') + '\n';
+}

package/dist/commands/init.js

@@ -2,7 +2,8 @@ import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { STARTER_FILES, MENTAL_MODEL_STARTER } from '../templates/starterFiles.js';
 import { installPointerAdapters } from '../adapters/genericPointer.js';
-const INSTRUCTIONS_TEMPLATE = `# Memory Intel Instructions
+import { hashContent, setGeneratedFileHash } from '../core/generatedFileHashes.js';
+export const INSTRUCTIONS_TEMPLATE = `# Memory Intel Instructions
 
 This project uses Memory Intel. Read this file at the start of every session.
 
@@ -58,6 +59,24 @@ on a real project: a "known limitation, deliberately left unfixed" entry was sti
 \`currentMentalModel.md\`, but never reconciled against the older, now-wrong decisions entry right
 next to it.
 
+## Committing \`.memoryintel/\` itself
+\`.memoryintel/\` is a normal, git-committed part of the project — \`memoryintel update\` only writes
+files to disk, it never runs git for you. After a successful \`update\`, commit \`.memoryintel/\`'s
+changes yourself, ideally in the same commit as (or immediately after) whatever code change
+prompted the update, so it travels with the same commit/PR automatically instead of being left
+behind as an uncommitted diff.
+
+This matters most in a git worktree, a container, or any other isolated checkout: an uncommitted
+\`.memoryintel/\` change only exists in that one working directory. Merging a feature branch's PR and
+pulling the primary checkout up to date only brings memory updates along if they were actually
+committed first, the same as any other file — there is nothing worktree-specific about the
+mechanism itself, only that a worktree's own uncommitted state is easier to lose track of, since it
+is invisible everywhere else once the session ends and that directory stops being looked at. Found
+on a real project: a full feature built end-to-end in a worktree, with real, meaningful
+architecture changes throughout, reached a merged PR with \`.memoryintel/\` never once updated or
+committed — not because updating was hard, but because nothing in the session ever came back to it
+before the worktree's job was considered done.
+
 ## Compaction
 A file marked \`status: over\` in \`load\`'s manifest has grown past its configured line ceiling.
 This is a signal, not a command — compact it only when it's a sensible moment to (the same
@@ -97,8 +116,13 @@ function ensureFile(path, content) {
 export function runInit(targetDir) {
     const root = join(targetDir, '.memoryintel');
     mkdirSync(root, { recursive: true });
-    ensureFile(join(root, 'instructions.md'), INSTRUCTIONS_TEMPLATE);
     ensureFile(join(root, 'memory-config.json'), JSON.stringify({ initializedAt: new Date().toISOString(), version: '0.1.0' }, null, 2) + '\n');
+    const instructionsPath = join(root, 'instructions.md');
+    const instructionsIsNew = !existsSync(instructionsPath);
+    ensureFile(instructionsPath, INSTRUCTIONS_TEMPLATE);
+    if (instructionsIsNew) {
+        setGeneratedFileHash(root, 'instructions.md', hashContent(INSTRUCTIONS_TEMPLATE));
+    }
     ensureFile(join(root, 'memory-index.json'), '{}\n');
     ensureFile(join(root, 'memory-events.jsonl'), '');
     ensureFile(join(root, 'context', 'currentMentalModel.md'), MENTAL_MODEL_STARTER);

package/dist/core/generatedFileHashes.js

@@ -0,0 +1,42 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+import { atomicWriteFile } from './atomicWrite.js';
+export function hashContent(content) {
+    return createHash('sha256').update(content, 'utf-8').digest('hex');
+}
+function configPath(root) {
+    return join(root, 'memory-config.json');
+}
+// Missing file or corrupt JSON both fall back to an empty object - the same defensive,
+// never-throw read pattern compressionConfig.ts already uses for this same file, since neither
+// getGeneratedFileHash nor setGeneratedFileHash should ever abort doctor/init over a config
+// read problem that isn't this feature's to fix.
+function readConfig(root) {
+    const path = configPath(root);
+    if (!existsSync(path))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return parsed && typeof parsed === 'object' ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function getGeneratedFileHash(root, relFile) {
+    const hashes = readConfig(root).generatedFileHashes;
+    if (hashes && typeof hashes === 'object') {
+        const value = hashes[relFile];
+        return typeof value === 'string' ? value : undefined;
+    }
+    return undefined;
+}
+export function setGeneratedFileHash(root, relFile, hash) {
+    const config = readConfig(root);
+    const existingHashes = config.generatedFileHashes && typeof config.generatedFileHashes === 'object'
+        ? config.generatedFileHashes
+        : {};
+    config.generatedFileHashes = { ...existingHashes, [relFile]: hash };
+    atomicWriteFile(configPath(root), JSON.stringify(config, null, 2) + '\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoryintel",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Persistent, cross-session project memory for AI coding agents.",
   "type": "module",
   "bin": {

package/skills/memoryintel/SKILL.md

@@ -48,7 +48,10 @@ Commands:
   status                   Print a human-readable summary of current memory state
   check-stop               Stop-hook check: emit a JSON allow/block decision
   dashboard <enable|disable>  Turn the shared local dashboard on or off
-  daemon start             Run the dashboard daemon in the foreground (usually auto-started)
+  doctor [--force]         Refresh memoryintel's own generated files (instructions.md, pointer
+                           blocks) to the current template wherever it's provably safe;
+                           --force also overwrites instructions.md when it isn't
+  daemon start              Run the dashboard daemon in the foreground (usually auto-started)
 
 An update-plan row may set kind=compress to compact an oversized section; update() only applies
 such a row when its target file is currently git-clean.