memoryintel 1.0.0

package/dist/commands/init.js

@@ -0,0 +1,111 @@
+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
+
+This project uses Memory Intel. Read this file at the start of every session.
+
+## Session start
+Run \`memoryintel load [--domain technical|business|research]\` and treat its output as project context.
+Its manifest reports each loaded file's \`lines\`, \`ceiling\`, and \`status\` (\`over\`/\`under\`) — see
+"Compaction" below for what to do about a file marked \`over\`.
+
+## Session end
+If your work changed project understanding (new architecture, feature, decision, integration, or
+roadmap item — not formatting/typos/comments), draft an update-plan (TOON table: file, action,
+section, content, reason), write it to a file, and run \`memoryintel update <plan-file>\` — e.g.
+\`memoryintel update /tmp/plan.toon\`. Running \`memoryintel update\` with no plan-file argument and
+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\`.
+
+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
+replace**: rewrite the entire current-understanding narrative from scratch each time, in plain
+prose, not another append-only log. This is the file the dashboard's "Current understanding"
+section renders directly — a stale or never-written one is the single most common way this
+project's memory looks broken to a human glancing at the dashboard, even when every other file is
+being updated correctly.
+
+Before adding a new \`context/decisions.md\` entry, skim the existing log for one your change
+supersedes or resolves (e.g. a decision your new work reverses, or a "known limitation" it just
+fixed). \`decisions.md\` is append-only by design — there is no mechanism to edit an old entry in
+place — so note the resolution explicitly in the new entry ("supersedes the earlier decision to
+X — see git history for why") rather than leaving the old one standing as if still current. Found
+on a real project: a "known limitation, deliberately left unfixed" entry was still sitting in
+\`decisions.md\` well after a later change fixed exactly that limitation — correctly recorded in
+\`currentMentalModel.md\`, but never reconciled against the older, now-wrong decisions entry right
+next to it.
+
+## 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
+judgment you already apply to whether to update at all), by adding a row to your update-plan with
+one extra field, \`kind: compress\`, and \`action: replace\` against the section that's grown large.
+\`update\` will only apply that row if the target file is currently git-clean — if it isn't, the row
+is rejected and the file is left untouched; commit the current state first, then retry. Aim to
+compact to comfortably under the ceiling, not exactly at it.
+
+git is the archive: nothing is duplicated into a second file. What you cut is still fully
+recoverable from git history — it just won't be loaded by default anymore. Because of that:
+
+- **Keep verbatim, never compress away:** architecture decisions and their rationale, unresolved
+  open questions, anything a future session would need to avoid repeating a mistake or
+  re-deriving a conclusion already reached.
+- **Safe to compress:** resolved narrative ("we tried X, it didn't work, we did Y instead"
+  collapses to "Y (not X — see git history for why)"), routine progress entries fully superseded
+  by a later one, verbose detail a terser statement of the current state already covers.
+- **Rule of thumb:** if a future session would reasonably ask "why is it built this way?" and
+  your summary can't answer, you compressed too much — keep more.
+
+The ceiling itself is configurable in \`memory-config.json\` under a \`compression\` key
+(\`defaultCeilingLines\`, and optional \`domainOverrides\` keyed by domain, e.g. \`"technical": 500\`)
+— the built-in default is 300 lines if unset.
+
+## Dashboard
+If the user asks to turn off the dashboard/web UI, run \`memoryintel dashboard disable\`. This is a
+single shared dashboard for every Memory Intel project on this machine — tell the user it affects
+all of their projects, not just this one. \`memoryintel dashboard enable\` turns it back on.
+`;
+function ensureFile(path, content) {
+    if (existsSync(path))
+        return;
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(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');
+    ensureFile(join(root, 'memory-index.json'), '{}\n');
+    ensureFile(join(root, 'memory-events.jsonl'), '');
+    ensureFile(join(root, 'context', 'currentMentalModel.md'), MENTAL_MODEL_STARTER);
+    for (const file of STARTER_FILES) {
+        const content = file.headings.map((h) => `## ${h}\n`).join('\n');
+        ensureFile(join(root, file.relPath), content);
+    }
+    // No intelligence/*.json scaffolding here: those files back the V2 (semantic retrieval) /
+    // V3 (knowledge graph) roadmap items, which stayed permanently dropped (see prd.md's "Future
+    // roadmap" section) - `update` has never accepted a write to that path (it's not in
+    // WRITABLE_FILES) and nothing else in this codebase reads it. Confirmed dead weight on a real
+    // project (distilled-docs): all three files sat at literal `{}` for its entire build. Creating
+    // files for a permanently-shelved feature just reads as broken/confusing to find later.
+    // Claude Code automation comes from the memoryintel plugin's own hooks/hooks.json (global,
+    // active for every project once the plugin is installed) — init never touches .claude/settings.json.
+    // The pointer-file adapter still runs here for tools with no plugin-hook equivalent (Cursor,
+    // Codex, Gemini CLI, opencode, pi). It touches foreign tools' config files, which this project
+    // does not own and cannot assume is well-formed — a failure there must never abort init's own
+    // job of scaffolding .memoryintel/. Warn and carry on.
+    runAdapter('install pointer-file adapters', () => installPointerAdapters(targetDir));
+}
+function runAdapter(description, fn) {
+    try {
+        fn();
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`Warning: could not ${description}: ${message}\n`);
+    }
+}

package/dist/commands/load.js

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { findMemoryIntelRoot } from '../core/discovery.js';
+import { extractHeadings } from '../core/headingMatch.js';
+import { encodeToonTable } from '../core/toon.js';
+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';
+const ALWAYS_LOAD = ['context/currentMentalModel.md', 'context/activeContext.md'];
+const DOMAIN_FILES = {
+    technical: ['technical/architecture.md', 'technical/techContext.md', 'technical/patterns.md'],
+    business: ['business/productContext.md', 'business/roadmap.md', 'business/stakeholders.md'],
+    research: ['research/findings.md', 'research/hypotheses.md']
+};
+export class UnknownDomainError extends Error {
+    domain;
+    constructor(domain) {
+        super(`Unknown domain "${domain}". Valid domains are: ${Object.keys(DOMAIN_FILES).join(', ')}.`);
+        this.domain = domain;
+        this.name = 'UnknownDomainError';
+    }
+}
+function assertKnownDomain(domain) {
+    if (!Object.prototype.hasOwnProperty.call(DOMAIN_FILES, domain)) {
+        throw new UnknownDomainError(domain);
+    }
+}
+export function runLoad(cwd, domain) {
+    // Validate before touching disk so a bad --domain always produces a clear, named error
+    // rather than spreading `undefined` out of DOMAIN_FILES.
+    if (domain !== undefined)
+        assertKnownDomain(domain);
+    const root = findMemoryIntelRoot(cwd);
+    if (!root)
+        return '';
+    try {
+        ensureDaemonRunning();
+        upsertRegistryEntry(dirname(root));
+    }
+    catch {
+        // Dashboard visibility is best-effort — never let it break `load`.
+    }
+    const files = [...ALWAYS_LOAD, ...(domain ? DOMAIN_FILES[domain] : [])];
+    const sections = [];
+    const manifestRows = [];
+    for (const relFile of files) {
+        const absPath = join(root, relFile);
+        if (!existsSync(absPath))
+            continue;
+        const content = readFileSync(absPath, 'utf-8');
+        const lines = countLines(content);
+        const ceiling = getCeilingLines(root, relFile);
+        const status = lines > ceiling ? 'over' : 'under';
+        sections.push(`--- FILE: ${relFile} ---\n${content}`);
+        manifestRows.push({
+            file: relFile,
+            headings: extractHeadings(content).join('|'),
+            lines: String(lines),
+            ceiling: String(ceiling),
+            status
+        });
+    }
+    try {
+        const totalChars = sections.reduce((sum, s) => sum + s.length, 0);
+        const totalLines = manifestRows.reduce((sum, r) => sum + Number(r.lines), 0);
+        appendEvent(join(root, 'memory-events.jsonl'), {
+            timestamp: new Date().toISOString(),
+            type: 'session-load',
+            summary: `Loaded ${manifestRows.length} file(s)${domain ? ` (domain: ${domain})` : ''}`,
+            affectedFiles: manifestRows.map((r) => r.file),
+            domain: domain ?? null,
+            totalChars,
+            totalLines
+        });
+    }
+    catch {
+        // KPI telemetry is best-effort - never let logging a load break the load itself.
+    }
+    const manifest = encodeToonTable(manifestRows);
+    return `${manifest}\n${sections.join('\n')}`;
+}

package/dist/commands/status.js

@@ -0,0 +1,24 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readIndex } from '../core/memoryIndex.js';
+export function runStatus(root) {
+    const lines = [];
+    const mentalModelPath = join(root, 'context', 'currentMentalModel.md');
+    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'));
+    for (const [file, entry] of Object.entries(index)) {
+        lines.push(`${file}: ${entry.summary} (updated ${entry.lastUpdated})`);
+    }
+    lines.push('', '=== Recent Events ===');
+    const eventsPath = join(root, 'memory-events.jsonl');
+    if (existsSync(eventsPath)) {
+        const eventLines = readFileSync(eventsPath, 'utf-8').trim().split('\n').filter(Boolean);
+        for (const line of eventLines.slice(-5)) {
+            const event = JSON.parse(line);
+            lines.push(`[${event.timestamp}] ${event.type}: ${event.summary}`);
+        }
+    }
+    return lines.join('\n') + '\n';
+}

package/dist/commands/update.js

@@ -0,0 +1,108 @@
+import { readFileSync } from 'node:fs';
+import { join, posix, dirname } from 'node:path';
+import { decodeToonTable } from '../core/toon.js';
+import { applySectionUpdate, isNearDuplicate, getSectionContent } from '../core/sectionWriter.js';
+import { assertSafePath } from '../core/pathSafety.js';
+import { upsertIndexEntry } from '../core/memoryIndex.js';
+import { appendEvent } from '../core/eventLog.js';
+import { atomicWriteFile } from '../core/atomicWrite.js';
+import { withLock } from '../core/lock.js';
+import { ensureDaemonRunning } from '../daemon/lifecycle.js';
+import { upsertRegistryEntry } from '../daemon/registry.js';
+import { resolveCheckStopMarker } from '../adapters/claudeCode.js';
+import { isPathClean } from '../core/gitPorcelain.js';
+const MENTAL_MODEL_FILE = 'context/currentMentalModel.md';
+export async function runUpdate(root, planText) {
+    try {
+        ensureDaemonRunning();
+        upsertRegistryEntry(dirname(root));
+    }
+    catch {
+        // Dashboard visibility is best-effort — never let it break `update`.
+    }
+    const rows = decodeToonTable(planText);
+    return withLock(join(root, '.lock'), () => {
+        // Phase 1: validate every entry against current disk state, compute the writes, write nothing yet.
+        const writes = [];
+        // Tracks each path's content as computed so far *this call*, so a second row targeting a
+        // path already touched by an earlier row builds on that row's result instead of the
+        // original on-disk content (which would otherwise silently discard the earlier edit).
+        const workingContent = new Map();
+        for (const row of rows) {
+            const absPath = assertSafePath(root, row.file);
+            const currentContent = workingContent.has(absPath) ? workingContent.get(absPath) : readFileSync(absPath, 'utf-8');
+            const isCompression = row.kind === 'compress';
+            // A compression row rewrites/collapses content whose only durable record, once
+            // compressed, is git history — so it may only proceed once the pre-compression version
+            // is already a real commit. This check is scoped to this row's own file, never the whole
+            // working tree, and treats "cannot determine git status at all" as unsafe, not as clean.
+            if (isCompression) {
+                // git always reports porcelain paths with forward slashes, regardless of OS - path.join
+                // here would produce a backslash-separated path on Windows that can never match, making
+                // every file look permanently clean there. path.posix.join keeps this comparable to
+                // git's own output on every platform. Caught by CI's Windows matrix job.
+                const clean = isPathClean(dirname(root), posix.join('.memoryintel', row.file));
+                if (clean !== true) {
+                    const reason = clean === null
+                        ? `Could not verify git status for ${row.file} — compression skipped this run.`
+                        : `${row.file} has uncommitted changes — commit the current state before compressing it, then retry.`;
+                    writes.push({ absPath, relFile: row.file, newContent: currentContent, reason, skipped: true, eventType: 'compression-rejected' });
+                    continue;
+                }
+            }
+            if (row.file === MENTAL_MODEL_FILE) {
+                const skipped = currentContent.trim() === row.content.trim();
+                const newContent = skipped ? currentContent : row.content;
+                workingContent.set(absPath, newContent);
+                writes.push({
+                    absPath, relFile: row.file, newContent, reason: row.reason, skipped,
+                    eventType: skipped ? 'skipped-duplicate' : (isCompression ? 'compression' : 'memory-update')
+                });
+                continue;
+            }
+            const updated = applySectionUpdate(currentContent, row.section, row.action, row.content);
+            const sectionContent = getSectionContent(currentContent, row.section);
+            // The duplicate check only makes sense for additive writes. A 'replace' is an explicit,
+            // full restatement of the section — narrowing "Uses Postgres 14 and Redis" down to
+            // "Uses Postgres 14" must be applied, even though the new text is a substring of the old.
+            // ('create-section' that degrades to an append is covered here too; on a genuinely new
+            // section there is no existing content, so the check can never fire.)
+            const skipped = row.action !== 'replace' && isNearDuplicate(sectionContent ?? '', row.content);
+            const newContent = skipped ? currentContent : updated;
+            workingContent.set(absPath, newContent);
+            writes.push({
+                absPath, relFile: row.file, newContent, reason: row.reason, skipped,
+                eventType: skipped ? 'skipped-duplicate' : (isCompression ? 'compression' : 'memory-update')
+            });
+        }
+        // Phase 2: apply. Every entry above already validated, so this cannot fail on content grounds.
+        const applied = [];
+        const skipped = [];
+        for (const w of writes) {
+            if (w.skipped) {
+                // A dropped write is still a fact about this session — log it so `status` can show
+                // that the agent proposed something and it was deduplicated (or, for compression,
+                // rejected) rather than applied (spec §4).
+                appendEvent(join(root, 'memory-events.jsonl'), {
+                    timestamp: new Date().toISOString(),
+                    type: w.eventType,
+                    summary: w.reason,
+                    affectedFiles: [w.relFile]
+                });
+                skipped.push(w.relFile);
+                continue;
+            }
+            atomicWriteFile(w.absPath, w.newContent);
+            upsertIndexEntry(join(root, 'memory-index.json'), w.relFile, w.reason);
+            appendEvent(join(root, 'memory-events.jsonl'), {
+                timestamp: new Date().toISOString(),
+                type: w.eventType,
+                summary: w.reason,
+                affectedFiles: [w.relFile]
+            });
+            applied.push(w.relFile);
+        }
+        resolveCheckStopMarker(root);
+        return { applied, skipped };
+    });
+}

package/dist/core/atomicWrite.js

@@ -0,0 +1,6 @@
+import { writeFileSync, renameSync } from 'node:fs';
+export function atomicWriteFile(path, content) {
+    const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+    writeFileSync(tempPath, content);
+    renameSync(tempPath, path);
+}

package/dist/core/compressionConfig.js

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const DEFAULT_CEILING_LINES = 300;
+// Reads memory-config.json's optional `compression` block. Missing file, missing key, or
+// corrupt JSON all fall back to an empty config (which getCeilingLines then resolves to the
+// built-in default) — this is a read-time convenience for load()/the dashboard, never a place
+// that should throw and interrupt them.
+function readCompressionConfig(root) {
+    const configPath = join(root, 'memory-config.json');
+    if (!existsSync(configPath))
+        return {};
+    try {
+        const parsed = JSON.parse(readFileSync(configPath, 'utf-8'));
+        if (parsed && typeof parsed === 'object' && parsed.compression && typeof parsed.compression === 'object') {
+            return parsed.compression;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+export function countLines(content) {
+    return content.length === 0 ? 0 : content.split('\n').length;
+}
+// relFile's first path segment (e.g. "technical" from "technical/architecture.md", or "context"
+// from "context/activeContext.md") is the domain domainOverrides keys against.
+export function getCeilingLines(root, relFile) {
+    const config = readCompressionConfig(root);
+    const domain = relFile.split('/')[0];
+    const override = config.domainOverrides?.[domain];
+    if (typeof override === 'number')
+        return override;
+    if (typeof config.defaultCeilingLines === 'number')
+        return config.defaultCeilingLines;
+    return DEFAULT_CEILING_LINES;
+}

package/dist/core/discovery.js

@@ -0,0 +1,14 @@
+import { existsSync } from 'node:fs';
+import { join, dirname, parse } from 'node:path';
+export function findMemoryIntelRoot(startDir) {
+    let dir = startDir;
+    const { root } = parse(dir);
+    while (true) {
+        const candidate = join(dir, '.memoryintel');
+        if (existsSync(candidate))
+            return candidate;
+        if (dir === root)
+            return null;
+        dir = dirname(dir);
+    }
+}

package/dist/core/eventLog.js

@@ -0,0 +1,4 @@
+import { appendFileSync } from 'node:fs';
+export function appendEvent(eventsPath, event) {
+    appendFileSync(eventsPath, JSON.stringify(event) + '\n');
+}

package/dist/core/gitPorcelain.js

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+// Returns the raw, non-empty `git status --porcelain` lines for cwd, in the order git reports
+// them, or null if this isn't a git repository / git failed for any reason. Each line keeps its
+// fixed two-character status code + space prefix intact — callers must use porcelainPath (a
+// fixed-offset slice) rather than trimming first, since trimming shifts that offset differently
+// depending on whether the status code itself starts with a space.
+export function runGitStatusPorcelain(cwd) {
+    try {
+        const output = execFileSync('git', ['status', '--porcelain'], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        });
+        return output.split('\n').filter((l) => l.length > 0);
+    }
+    catch {
+        return null;
+    }
+}
+export function porcelainPath(line) {
+    return line.slice(3);
+}
+// Returns the current commit HEAD points at, or null if this isn't a git repository, git
+// failed, or there are no commits yet (a freshly `git init`'d repo has no HEAD to resolve).
+export function runGitRevParseHead(cwd) {
+    try {
+        return execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore']
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+// True if `relPath` (relative to `cwd`, the same way git itself reports paths when invoked with
+// that cwd) has no uncommitted changes, false if it does, or null if git status could not be
+// determined at all — callers must treat null as "cannot verify", never as clean.
+export function isPathClean(cwd, relPath) {
+    const lines = runGitStatusPorcelain(cwd);
+    if (lines === null)
+        return null;
+    return !lines.some((l) => porcelainPath(l) === relPath);
+}

package/dist/core/headingMatch.js

@@ -0,0 +1,44 @@
+export function normalizeHeading(s) {
+    return s.trim().toLowerCase().replace(/\s+/g, ' ');
+}
+export function extractHeadings(markdown) {
+    const headings = [];
+    for (const line of markdown.split('\n')) {
+        const match = /^##[ \t]+(.+?)\s*$/.exec(line);
+        if (match)
+            headings.push(match[1].trim());
+    }
+    return headings;
+}
+export function findHeadingMatch(headings, target) {
+    const normalizedTarget = normalizeHeading(target);
+    return headings.find((h) => normalizeHeading(h) === normalizedTarget) ?? null;
+}
+// Token-overlap similarity: fraction of the smaller token set contained in the larger one,
+// plus a prefix-containment bonus so "Auth" vs "Authentication" scores well.
+function similarity(a, b) {
+    const na = normalizeHeading(a);
+    const nb = normalizeHeading(b);
+    if (na === nb)
+        return 1;
+    if (na.includes(nb) || nb.includes(na))
+        return 0.85;
+    const tokensA = new Set(na.split(' '));
+    const tokensB = new Set(nb.split(' '));
+    const [small, large] = tokensA.size <= tokensB.size ? [tokensA, tokensB] : [tokensB, tokensA];
+    let shared = 0;
+    for (const t of small)
+        if (large.has(t))
+            shared++;
+    return small.size === 0 ? 0 : shared / small.size;
+}
+const SUGGESTION_THRESHOLD = 0.6;
+export function suggestHeading(headings, target) {
+    let best = null;
+    for (const h of headings) {
+        const score = similarity(h, target);
+        if (!best || score > best.score)
+            best = { heading: h, score };
+    }
+    return best && best.score >= SUGGESTION_THRESHOLD ? best.heading : null;
+}

package/dist/core/lock.js

@@ -0,0 +1,67 @@
+import { openSync, closeSync, unlinkSync, constants } from 'node:fs';
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// A blocking sleep, for callers that cannot go async (see withLockSync below) — Atomics.wait on
+// a throwaway SharedArrayBuffer is the standard way to synchronously pause a Node.js thread
+// without a busy-loop burning CPU.
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export async function withLock(lockPath, fn, opts = {}) {
+    const retries = opts.retries ?? 100;
+    const delayMs = opts.delayMs ?? 20;
+    let fd = null;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            fd = openSync(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (attempt === retries)
+                throw new Error(`Timed out waiting for lock: ${lockPath}`);
+            await sleep(delayMs);
+        }
+    }
+    try {
+        return await fn();
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+        unlinkSync(lockPath);
+    }
+}
+// Synchronous sibling of withLock, for callers on a synchronous public API (e.g. runLoad) that
+// cannot be made async without rippling out to every caller. Same atomic exclusive-create
+// technique; a shorter default retry budget since callers using this are on a hot, latency-
+// sensitive path and the critical section (spawnDaemonProcess is a non-blocking spawn().unref())
+// is expected to be sub-millisecond, not something worth blocking a CLI invocation over.
+export function withLockSync(lockPath, fn, opts = {}) {
+    const retries = opts.retries ?? 25;
+    const delayMs = opts.delayMs ?? 4;
+    let fd = null;
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        try {
+            fd = openSync(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY);
+            break;
+        }
+        catch (err) {
+            if (err.code !== 'EEXIST')
+                throw err;
+            if (attempt === retries)
+                throw new Error(`Timed out waiting for lock: ${lockPath}`);
+            sleepSync(delayMs);
+        }
+    }
+    try {
+        return fn();
+    }
+    finally {
+        if (fd !== null)
+            closeSync(fd);
+        unlinkSync(lockPath);
+    }
+}

package/dist/core/memoryIndex.js

@@ -0,0 +1,19 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+export function readIndex(indexPath) {
+    if (!existsSync(indexPath))
+        return {};
+    const raw = readFileSync(indexPath, 'utf-8').trim();
+    if (raw.length === 0)
+        return {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Corrupt memory index at ${indexPath}: ${err.message}`);
+    }
+}
+export function upsertIndexEntry(indexPath, file, summary) {
+    const index = readIndex(indexPath);
+    index[file] = { lastUpdated: new Date().toISOString(), summary };
+    writeFileSync(indexPath, JSON.stringify(index, null, 2) + '\n');
+}

package/dist/core/pathSafety.js

@@ -0,0 +1,43 @@
+import { join, resolve, relative, isAbsolute } from 'node:path';
+export const WRITABLE_FILES = [
+    'context/projectBrief.md',
+    'context/objectives.md',
+    'context/activeContext.md',
+    'context/decisions.md',
+    'context/progress.md',
+    'context/learnings.md',
+    'context/currentMentalModel.md',
+    'technical/architecture.md',
+    'technical/techContext.md',
+    'technical/patterns.md',
+    'technical/integrations.md',
+    'technical/infrastructure.md',
+    'business/productContext.md',
+    'business/roadmap.md',
+    'business/stakeholders.md',
+    'business/marketContext.md',
+    'research/findings.md',
+    'research/references.md',
+    'research/hypotheses.md'
+];
+export class UnsafePathError extends Error {
+    constructor(relFile) {
+        super(`"${relFile}" is not a recognized Memory Intel file and cannot be written.`);
+    }
+}
+export function assertSafePath(root, relFile) {
+    if (isAbsolute(relFile) || !WRITABLE_FILES.includes(relFile)) {
+        throw new UnsafePathError(relFile);
+    }
+    // Containment check via path.relative(), not a hardcoded '/' string prefix - resolve() on
+    // Windows returns backslash-separated paths, so `resolved.startsWith(resolvedRoot + '/')`
+    // fails unconditionally on every call there, rejecting every legitimate write. Caught live by
+    // CI's Windows matrix job the first time it ran - the whole write path was broken on Windows.
+    const resolved = resolve(root, relFile);
+    const resolvedRoot = resolve(root);
+    const rel = relative(resolvedRoot, resolved);
+    if (rel.startsWith('..') || isAbsolute(rel)) {
+        throw new UnsafePathError(relFile);
+    }
+    return join(root, relFile);
+}