memoryintel 1.0.2 → 1.1.1

package/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent, cross-session project memory for AI coding agents.",
-    "version": "1.0.2"
+    "version": "1.1.1"
   },
   "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.2"
+      "version": "1.1.1"
     }
   ]
 }

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.2",
+  "version": "1.1.1",
   "author": {
     "name": "Adeesh Sharma",
     "url": "https://github.com/adeeshsharma"

package/dist/adapters/genericPointer.js

@@ -28,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.
 
@@ -39,6 +40,28 @@ section, content, reason), write it to a file, and run \`memoryintel update <pla
 nothing piped to stdin fails (there is no plan to apply). Reuse exact existing heading names from
 the manifest \`load\` gave you. If nothing meaningful changed, do nothing — do not call \`update\`.
 
+**The exact TOON format \`update\` expects** - this is the one place a malformed plan fails
+outright rather than degrading gracefully, so match it exactly rather than improvising:
+
+    items[2]{file,action,section,content,reason}:
+      "path/to/file.md","append","Section Heading","New paragraph to add.","Why this changed"
+      "path/to/other.md","create-section","New Heading","Content, comma and all.","Why"
+
+- The header line is literal: \`items[\`, the row count, \`]{\`, the field names in this exact
+  order and spelling (\`file,action,section,content,reason\` - add \`,kind\` only for a compaction
+  row, see "Compaction" below), \`}:\`. The row count MUST equal the number of rows that follow, or
+  \`update\` rejects the whole plan with nothing applied.
+- \`action\` is exactly one of three values: \`append\` (add to the end of an existing section's
+  content), \`replace\` (overwrite the section's entire content), or \`create-section\` (add a new
+  \`##\` heading if it doesn't already exist - degrades to a plain \`append\` if it does).
+- Each row is comma-separated fields in that same header order, indented two spaces.
+- **Quote a field in double quotes whenever its content contains a comma, a double quote, a
+  newline, or starts with whitespace** - leave every other field unquoted. Double any literal
+  \`"\` inside a quoted field (\`"\` becomes \`""\`). A quoted field may span multiple physical lines.
+  Example: content \`He said "hi", then left\` must be written as \`"He said ""hi"", then left"\`.
+- \`context/currentMentalModel.md\` is the one exception to \`action\`: its row's \`content\` replaces
+  the file's entire content verbatim, regardless of what \`action\`/\`section\` say.
+
 Also include a row for \`context/currentMentalModel.md\` whenever the update is more than a small,
 localized fact — anything that shifts what the project *is* or where it currently stands (not
 every single decision/progress entry needs one). Unlike every other file, it is a **whole-file
@@ -115,8 +138,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.2",
+  "version": "1.1.1",
   "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.