memoryintel 1.1.0 → 1.1.2

package/.claude-plugin/marketplace.json

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

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

package/dist/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { readFileSync, realpathSync } from 'node:fs';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { findMemoryIntelRoot } from './core/discovery.js';
 import { runUpdate } from './commands/update.js';
@@ -13,6 +13,26 @@ 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';
+// Every command below that resolves .memoryintel/ by walking up from a starting directory
+// previously always used process.cwd() with no override - meaning a long, multi-project
+// session had to religiously `cd` before every single call, with silently-wrong output the
+// only feedback for getting it wrong (mitigated separately by printing the resolved root, but
+// that only helps you NOTICE the mistake, not avoid making it). --root <path> lets a caller
+// that already knows its target project say so directly; MEMORYINTEL_ROOT is the same thing
+// as an env var, for a session-start hook or similar context where passing an extra CLI flag
+// isn't convenient. --root wins when both are given. Either way this is resolved exactly like
+// process.cwd() always was - a starting point findMemoryIntelRoot() walks up from, not
+// required to already BE the exact .memoryintel directory itself.
+function resolveStartDir(argv) {
+    const rootFlagIndex = argv.indexOf('--root');
+    if (rootFlagIndex !== -1 && argv[rootFlagIndex + 1]) {
+        return resolve(process.cwd(), argv[rootFlagIndex + 1]);
+    }
+    if (process.env.MEMORYINTEL_ROOT) {
+        return resolve(process.cwd(), process.env.MEMORYINTEL_ROOT);
+    }
+    return process.cwd();
+}
 export const USAGE = `Usage: memoryintel <command> [options]
 
 Commands:
@@ -52,24 +72,24 @@ export function dispatch(argv) {
         case 'load': {
             const domainFlagIndex = argv.indexOf('--domain');
             const domain = domainFlagIndex !== -1 ? argv[domainFlagIndex + 1] : undefined;
-            const output = runLoad(process.cwd(), domain);
+            const output = runLoad(resolveStartDir(argv), domain);
             return { exitCode: 0, stdout: output, stderr: '' };
         }
         case 'status': {
-            const root = findMemoryIntelRoot(process.cwd());
+            const root = findMemoryIntelRoot(resolveStartDir(argv));
             if (!root)
                 return { exitCode: 1, stdout: '', stderr: 'No .memoryintel/ found.\n' };
             return { exitCode: 0, stdout: runStatus(root), stderr: '' };
         }
         case 'check-stop': {
-            const root = findMemoryIntelRoot(process.cwd());
+            const root = findMemoryIntelRoot(resolveStartDir(argv));
             if (!root)
                 return { exitCode: 0, stdout: '', stderr: '' };
             const result = runCheckStop(root);
             return { exitCode: 0, stdout: JSON.stringify(result) + '\n', stderr: '' };
         }
         case 'doctor': {
-            const root = findMemoryIntelRoot(process.cwd());
+            const root = findMemoryIntelRoot(resolveStartDir(argv));
             if (!root)
                 return { exitCode: 1, stdout: '', stderr: 'No .memoryintel/ found.\n' };
             const force = argv.includes('--force');
@@ -130,13 +150,18 @@ async function main() {
             return;
         }
         if (command === 'update') {
-            const root = findMemoryIntelRoot(process.cwd());
+            const root = findMemoryIntelRoot(resolveStartDir(argv));
             if (!root) {
                 process.stderr.write('No .memoryintel/ found.\n');
                 process.exitCode = 1;
                 return;
             }
-            const source = argv[1] ?? '-';
+            // The plan-file path is the first REMAINING positional argument after stripping the
+            // command name itself and a --root <path> pair, if given - otherwise "--root"'s own
+            // value would get misread as the plan-file path.
+            const rootFlagIndex = argv.indexOf('--root');
+            const positional = argv.filter((_, i) => i !== 0 && i !== rootFlagIndex && i !== rootFlagIndex + 1);
+            const source = positional[0] ?? '-';
             const planText = source === '-' ? readFileSync(0, 'utf-8') : readFileSync(source, 'utf-8');
             // Caught live: an agent ran bare `memoryintel update` (no plan-file argument, no piped
             // stdin) as a one-shot Bash tool call. `source` defaulted to '-' (read stdin), stdin was
@@ -144,12 +169,14 @@ async function main() {
             // generic "Malformed TOON table header" error - true, but useless for figuring out what
             // actually went wrong. This is the one case worth naming explicitly before it gets there.
             if (planText.trim().length === 0) {
-                process.stderr.write('memoryintel: No update-plan given. Pass a TOON plan file (`memoryintel update <path>`) or pipe TOON content via stdin. See .memoryintel/instructions.md for the update-plan format.\n');
+                process.stderr.write('memoryintel: No update-plan given. Pass a plan file (TOON or JSON, `memoryintel update <path>`) or pipe it via stdin. See .memoryintel/instructions.md for the update-plan format.\n');
                 process.exitCode = 1;
                 return;
             }
             const result = await runUpdate(root, planText);
-            process.stdout.write(`Applied: ${result.applied.join(', ') || '(none)'}\nSkipped: ${result.skipped.join(', ') || '(none)'}\n`);
+            // root printed first, same reasoning as load/status: a wrong-directory update should
+            // never be silent.
+            process.stdout.write(`root: ${root}\nApplied: ${result.applied.join(', ') || '(none)'}\nSkipped: ${result.skipped.join(', ') || '(none)'}\n`);
             process.exitCode = 0;
             return;
         }

package/dist/commands/init.js

@@ -40,6 +40,36 @@ 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.
+
+**\`update\` also accepts a plain JSON array of the same rows instead of TOON**, auto-detected by
+whether the file/stdin content starts with \`[\` or \`{\` after trimming - if you'd rather
+\`JSON.stringify\` a plan than hand-write TOON's quoting rule above, this is the safer default:
+\`[{"file": "path/to/file.md", "action": "append", "section": "Section Heading", "content": "New
+paragraph to add.", "reason": "Why this changed"}]\`. Same fields, same required order doesn't
+matter (JSON is keyed, not positional), same \`context/currentMentalModel.md\` exception. Neither
+format is preferred - use whichever you're less likely to get wrong.
+
 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

package/dist/commands/load.js

@@ -7,6 +7,7 @@ import { getCeilingLines, countLines } from '../core/compressionConfig.js';
 import { ensureDaemonRunning } from '../daemon/lifecycle.js';
 import { upsertRegistryEntry } from '../daemon/registry.js';
 import { appendEvent } from '../core/eventLog.js';
+import { readIndex } from '../core/memoryIndex.js';
 const ALWAYS_LOAD = ['context/currentMentalModel.md', 'context/activeContext.md'];
 const DOMAIN_FILES = {
     technical: ['technical/architecture.md', 'technical/techContext.md', 'technical/patterns.md'],
@@ -44,6 +45,11 @@ export function runLoad(cwd, domain) {
     const files = [...ALWAYS_LOAD, ...(domain ? DOMAIN_FILES[domain] : [])];
     const sections = [];
     const manifestRows = [];
+    // `status` already surfaces lastUpdated from this same index - `load` is the one command
+    // instructions.md tells every session to run FIRST, though, and previously gave zero signal
+    // for "just updated" vs. "nobody has touched this in months" without a separate `status`
+    // call nothing prompts an agent to make.
+    const index = readIndex(join(root, 'memory-index.json'));
     for (const relFile of files) {
         const absPath = join(root, relFile);
         if (!existsSync(absPath))
@@ -58,7 +64,8 @@ export function runLoad(cwd, domain) {
             headings: extractHeadings(content).join('|'),
             lines: String(lines),
             ceiling: String(ceiling),
-            status
+            status,
+            lastUpdated: index[relFile]?.lastUpdated ?? 'never'
         });
     }
     try {
@@ -78,5 +85,10 @@ export function runLoad(cwd, domain) {
         // KPI telemetry is best-effort - never let logging a load break the load itself.
     }
     const manifest = encodeToonTable(manifestRows);
-    return `${manifest}\n${sections.join('\n')}`;
+    // A leading, plainly-labeled root line - silently loading the wrong project's (or wrong
+    // worktree/branch's) memory has happened in practice: findMemoryIntelRoot() walks up from
+    // cwd with no built-in visibility into which root it actually found, so confidently-wrong
+    // content came back with nothing to flag it. This is always the first thing printed,
+    // whether or not --domain is given.
+    return `root: ${root}\n${manifest}\n${sections.join('\n')}`;
 }

package/dist/commands/status.js

@@ -3,8 +3,12 @@ import { join } from 'node:path';
 import { readIndex } from '../core/memoryIndex.js';
 export function runStatus(root) {
     const lines = [];
+    // Always first: silently reading the wrong project's (or wrong worktree/branch's) memory
+    // has happened in practice - findMemoryIntelRoot() walks up from cwd with no built-in
+    // visibility into which root it actually resolved.
+    lines.push('=== Root ===', root);
     const mentalModelPath = join(root, 'context', 'currentMentalModel.md');
-    lines.push('=== Current Mental Model ===');
+    lines.push('', '=== Current Mental Model ===');
     lines.push(existsSync(mentalModelPath) ? readFileSync(mentalModelPath, 'utf-8').trim() : '(none)');
     lines.push('', '=== Memory Index ===');
     const index = readIndex(join(root, 'memory-index.json'));

package/dist/commands/update.js

@@ -1,6 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join, posix, dirname } from 'node:path';
-import { decodeToonTable } from '../core/toon.js';
+import { decodePlanRows } from '../core/toon.js';
 import { applySectionUpdate, isNearDuplicate, getSectionContent } from '../core/sectionWriter.js';
 import { assertSafePath } from '../core/pathSafety.js';
 import { upsertIndexEntry } from '../core/memoryIndex.js';
@@ -20,7 +20,7 @@ export async function runUpdate(root, planText) {
     catch {
         // Dashboard visibility is best-effort — never let it break `update`.
     }
-    const rows = decodeToonTable(planText);
+    const rows = decodePlanRows(planText);
     return withLock(join(root, '.lock'), () => {
         // Phase 1: validate every entry against current disk state, compute the writes, write nothing yet.
         const writes = [];

package/dist/core/toon.js

@@ -66,7 +66,10 @@ function parseCsvRows(text) {
         }
     }
     if (inQuotes) {
-        throw new Error('Malformed TOON table: unterminated quoted field.');
+        // rows.length is exactly how many COMPLETE rows were parsed before the failure - the
+        // failing row is the next one, at that same 0-indexed position (matching how a
+        // field-count-mismatch error below reports rowIndex).
+        throw new Error(`Malformed TOON table: unterminated quoted field in row ${rows.length}.`);
     }
     if (rowStarted)
         endRow();
@@ -116,3 +119,63 @@ export function decodeToonTable(text) {
         return row;
     });
 }
+const REQUIRED_PLAN_ROW_FIELDS = ['file', 'action', 'section', 'content', 'reason'];
+const OPTIONAL_PLAN_ROW_FIELDS = ['kind'];
+function decodeJsonPlan(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`Malformed JSON plan: ${message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error('Malformed JSON plan: expected an array of rows.');
+    }
+    return parsed.map((row, rowIndex) => {
+        if (row === null || typeof row !== 'object' || Array.isArray(row)) {
+            throw new Error(`Malformed JSON plan: row ${rowIndex} must be an object.`);
+        }
+        const record = row;
+        for (const field of REQUIRED_PLAN_ROW_FIELDS) {
+            if (!(field in record)) {
+                throw new Error(`Malformed JSON plan: row ${rowIndex} is missing required field "${field}".`);
+            }
+        }
+        const result = {};
+        for (const field of [...REQUIRED_PLAN_ROW_FIELDS, ...OPTIONAL_PLAN_ROW_FIELDS]) {
+            if (!(field in record))
+                continue;
+            const value = record[field];
+            if (typeof value !== 'string') {
+                throw new Error(`Malformed JSON plan: row ${rowIndex}'s "${field}" must be a string.`);
+            }
+            result[field] = value;
+        }
+        return result;
+    });
+}
+/**
+ * Accepts either format update() itself needs to parse: TOON text (the
+ * default, more compact for a human/agent to scan), or a JSON array of the
+ * same row shape - auto-detected by a leading '[' after trimming, since a
+ * real TOON header always starts with the literal 'items['; this can never
+ * misfire on a genuinely malformed TOON table. JSON exists specifically so
+ * an agent that would rather JSON.stringify a plan than hand-author TOON's
+ * own quoting rules (double an internal '"' as '""', not backslash-escape
+ * it - a real, repeated mistake in practice, not hypothetical) never has to
+ * risk getting that escaping wrong at all. decodeToonTable itself is
+ * unchanged and still exported directly for anyone who wants TOON
+ * specifically.
+ */
+export function decodePlanRows(text) {
+    const trimmed = text.trimStart();
+    // A real TOON header never starts with '[' or '{' either (always the literal
+    // 'items[') - catching '{' too means a plan mistakenly wrapped as a single
+    // object instead of an array gets the clear "expected an array" error below,
+    // not an unrelated, confusing TOON header error.
+    if (trimmed.startsWith('[') || trimmed.startsWith('{'))
+        return decodeJsonPlan(trimmed);
+    return decodeToonTable(text);
+}

package/package.json

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