npm - claude-memory-explorer - Versions diffs - 0.1.0 - Mend

claude-memory-explorer 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (80) hide show

package/.claude-plugin/plugin.json +19 -0
package/LICENSE +21 -0
package/README.md +177 -0
package/dist/cli/commands/dedupe.d.ts +1 -0
package/dist/cli/commands/dedupe.js +187 -0
package/dist/cli/commands/dedupe.js.map +1 -0
package/dist/cli/commands/doctor.d.ts +1 -0
package/dist/cli/commands/doctor.js +177 -0
package/dist/cli/commands/doctor.js.map +1 -0
package/dist/cli/commands/lint.d.ts +1 -0
package/dist/cli/commands/lint.js +139 -0
package/dist/cli/commands/lint.js.map +1 -0
package/dist/cli/commands/list.d.ts +1 -0
package/dist/cli/commands/list.js +97 -0
package/dist/cli/commands/list.js.map +1 -0
package/dist/cli/commands/mcp.d.ts +1 -0
package/dist/cli/commands/mcp.js +105 -0
package/dist/cli/commands/mcp.js.map +1 -0
package/dist/cli/commands/merge.d.ts +1 -0
package/dist/cli/commands/merge.js +111 -0
package/dist/cli/commands/merge.js.map +1 -0
package/dist/cli/commands/promote.d.ts +1 -0
package/dist/cli/commands/promote.js +157 -0
package/dist/cli/commands/promote.js.map +1 -0
package/dist/cli/commands/tui.d.ts +1 -0
package/dist/cli/commands/tui.js +60 -0
package/dist/cli/commands/tui.js.map +1 -0
package/dist/cli/commands/undo.d.ts +1 -0
package/dist/cli/commands/undo.js +157 -0
package/dist/cli/commands/undo.js.map +1 -0
package/dist/cli/index.d.ts +2 -0
package/dist/cli/index.js +85 -0
package/dist/cli/index.js.map +1 -0
package/dist/cli/tui/App.d.ts +8 -0
package/dist/cli/tui/App.js +333 -0
package/dist/cli/tui/App.js.map +1 -0
package/dist/core/apply.d.ts +27 -0
package/dist/core/apply.js +191 -0
package/dist/core/apply.js.map +1 -0
package/dist/core/claudeMd.d.ts +27 -0
package/dist/core/claudeMd.js +103 -0
package/dist/core/claudeMd.js.map +1 -0
package/dist/core/dedupe.d.ts +78 -0
package/dist/core/dedupe.js +212 -0
package/dist/core/dedupe.js.map +1 -0
package/dist/core/doctor.d.ts +35 -0
package/dist/core/doctor.js +106 -0
package/dist/core/doctor.js.map +1 -0
package/dist/core/journal.d.ts +31 -0
package/dist/core/journal.js +64 -0
package/dist/core/journal.js.map +1 -0
package/dist/core/lint.d.ts +26 -0
package/dist/core/lint.js +254 -0
package/dist/core/lint.js.map +1 -0
package/dist/core/memoryIndex.d.ts +42 -0
package/dist/core/memoryIndex.js +81 -0
package/dist/core/memoryIndex.js.map +1 -0
package/dist/core/merge.d.ts +19 -0
package/dist/core/merge.js +58 -0
package/dist/core/merge.js.map +1 -0
package/dist/core/parse.d.ts +2 -0
package/dist/core/parse.js +84 -0
package/dist/core/parse.js.map +1 -0
package/dist/core/plan.d.ts +34 -0
package/dist/core/plan.js +85 -0
package/dist/core/plan.js.map +1 -0
package/dist/core/promote.d.ts +29 -0
package/dist/core/promote.js +103 -0
package/dist/core/promote.js.map +1 -0
package/dist/core/scan.d.ts +16 -0
package/dist/core/scan.js +81 -0
package/dist/core/scan.js.map +1 -0
package/dist/core/types.d.ts +36 -0
package/dist/core/types.js +4 -0
package/dist/core/types.js.map +1 -0
package/dist/mcp/server.d.ts +13 -0
package/dist/mcp/server.js +211 -0
package/dist/mcp/server.js.map +1 -0
package/package.json +71 -0
package/skills/curate-memory/SKILL.md +60 -0

package/dist/core/claudeMd.js ADDED Viewed

@@ -0,0 +1,103 @@
+// Helpers for managing `~/.claude/CLAUDE.md` — the always-loaded user-level
+// instructions file Claude Code reads at the start of every session.
+//
+// memex never touches content outside its own marker blocks. The managed
+// format:
+//
+//   <!-- memex:start:<slug> -->
+//   ## <heading>
+//
+//   <body>
+//
+//   <!-- memex:end:<slug> -->
+//
+// Slug is a `[a-z0-9_-]+` identifier derived from the source filename. If
+// a block with the same slug exists, it's replaced in place; otherwise the
+// block is appended to the file under a memex-owned section header that's
+// added lazily on the first promote.
+import { homedir } from "node:os";
+import { join } from "node:path";
+const HEADER_BANNER = "## Promoted memories (managed by memex — do not edit between markers)\n";
+export function defaultClaudeMdPath() {
+    return join(homedir(), ".claude", "CLAUDE.md");
+}
+/** Normalize an arbitrary string into a safe block slug. */
+export function toBlockSlug(name) {
+    return name
+        .toLowerCase()
+        .replace(/\.md$/, "")
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64);
+}
+function startMarker(slug) {
+    return `<!-- memex:start:${slug} -->`;
+}
+function endMarker(slug) {
+    return `<!-- memex:end:${slug} -->`;
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function blockPatternFor(slug) {
+    // Match the block including a trailing newline if present.
+    return new RegExp(`${escapeRegex(startMarker(slug))}[\\s\\S]*?${escapeRegex(endMarker(slug))}\\n?`, "g");
+}
+export function renderBlock(block) {
+    const body = block.body.trimEnd();
+    return [
+        startMarker(block.slug),
+        `## ${block.heading}`,
+        "",
+        body,
+        endMarker(block.slug),
+    ].join("\n");
+}
+/**
+ * Upsert a managed block into a CLAUDE.md document.
+ *
+ * - If a block with the same slug exists, replace it in place.
+ * - Otherwise append after ensuring the header banner is present.
+ * - Returns the new content (caller decides what to do with it).
+ */
+export function upsertBlock(currentContent, block) {
+    const rendered = renderBlock(block);
+    const pattern = blockPatternFor(block.slug);
+    if (pattern.test(currentContent)) {
+        // Replace existing block.
+        return currentContent.replace(pattern, `${rendered}\n`);
+    }
+    // Append. Ensure the file ends with a newline, the banner is present, and
+    // there's exactly one blank line between the previous content and our
+    // new block.
+    let out = currentContent;
+    if (out.length > 0 && !out.endsWith("\n"))
+        out += "\n";
+    if (!out.includes(HEADER_BANNER)) {
+        if (out.length > 0)
+            out += "\n";
+        out += HEADER_BANNER;
+    }
+    out += "\n" + rendered + "\n";
+    return out;
+}
+/**
+ * Remove a managed block by slug. Used by undo/promote-revert. Leaves
+ * unmanaged content alone. Returns { content, modified }.
+ */
+export function removeBlock(currentContent, slug) {
+    const pattern = blockPatternFor(slug);
+    if (!pattern.test(currentContent))
+        return { content: currentContent, modified: false };
+    return { content: currentContent.replace(pattern, ""), modified: true };
+}
+/** List the slugs of memex-managed blocks currently in a document. */
+export function listBlockSlugs(currentContent) {
+    const re = /<!--\s*memex:start:([a-z0-9_-]+)\s*-->/g;
+    const out = [];
+    let m;
+    while ((m = re.exec(currentContent)) !== null)
+        out.push(m[1]);
+    return out;
+}
+//# sourceMappingURL=claudeMd.js.map

package/dist/core/claudeMd.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"claudeMd.js","sourceRoot":"","sources":["../../src/core/claudeMd.ts"],"names":[],"mappings":"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"}

package/dist/core/dedupe.d.ts ADDED Viewed

@@ -0,0 +1,78 @@
+import { type ScanOptions } from "./scan.js";
+import type { Memory, MemoryTypeOrUntyped } from "./types.js";
+/** Collapse `-foo-bar--claude-worktrees-xyz` → `-foo-bar`. */
+export declare function collapseWorktreeSlug(slug: string): string;
+/**
+ * Normalize a string for fingerprinting. Idempotent.
+ *
+ * The pipeline is intentionally conservative — too-aggressive normalization
+ * causes false positives (e.g. stripping code blocks merges unrelated logcli
+ * notes). Too-lenient causes false negatives. This sits in the middle.
+ */
+export declare function normalizeForHash(s: string): string;
+/** Normalize a name field — additionally strips trailing parentheticals. */
+export declare function normalizeName(name: string | null | undefined): string;
+export declare function computeBodyHash(body: string): string;
+export declare function computeFullHash(memory: Memory): string;
+export interface ClusterMember {
+    id: string;
+    filePath: string;
+    /** Worktree-collapsed slug (the "logical" project). */
+    project: string;
+    /** Raw slug as it appears on disk. */
+    rawProjectSlug: string;
+    name: string | null;
+    description: string | null;
+    type: MemoryTypeOrUntyped;
+    bodyBytes: number;
+    mtime: string;
+    fullHash: string;
+}
+export interface DuplicateCluster {
+    /** Short stable id like "c1", easier to reference than the hash. */
+    id: string;
+    /** Which hash matched. v0.1 always reports "bodyHash". */
+    tier: "bodyHash";
+    /** Hex digest. */
+    fingerprint: string;
+    /** Number of members. */
+    count: number;
+    /** Type of the cluster (taken from the representative). */
+    type: MemoryTypeOrUntyped;
+    /** True if every member lives in one logical project. */
+    intraProject: boolean;
+    /** Number of *distinct* worktree-collapsed projects. */
+    distinctProjects: number;
+    /** True iff `distinctProjects >= 3 && type in {user, feedback}`. */
+    promotionCandidate: boolean;
+    /** The member best suited as the merge target. */
+    representative: {
+        id: string;
+        reason: string;
+    };
+    members: ClusterMember[];
+}
+export interface DedupeResult {
+    version: "1";
+    scannedAt: string;
+    config: {
+        normalization: "v1";
+        tier: "bodyHash";
+    };
+    clusters: DuplicateCluster[];
+    summary: {
+        memoriesScanned: number;
+        projectsScanned: number;
+        clusterCount: number;
+        duplicateFileCount: number;
+        wastedBytes: number;
+        promotionCandidates: number;
+        skippedEmptyBodies: number;
+    };
+}
+export interface DedupeOptions extends ScanOptions {
+    projectFilter?: string;
+    /** Include `untyped` memories in clustering. Default: true (treat as wildcard). */
+    includeUntyped?: boolean;
+}
+export declare function findDuplicates(opts?: DedupeOptions): DedupeResult;

package/dist/core/dedupe.js ADDED Viewed

@@ -0,0 +1,212 @@
+// Cross-project duplicate detection (Phase 4).
+//
+// Design choices (see research/dedupe.md or commit message for rationale):
+//
+// - **Two-tier fingerprints**: `bodyHash` is the primary cluster key — Claude
+//   tends to write the same rule with slightly different `name`/`description`
+//   across projects but stable body text. `fullHash` (type+name+desc+body) is
+//   reported alongside so callers can subdivide clusters by stricter identity.
+//
+// - **Normalization**: NFC unicode → smart-quote ASCII fold → lowercase →
+//   strip trivial markdown wrappers → collapse whitespace. No full markdown
+//   AST — too expensive and too lossy. URLs/code blocks stay in (they're
+//   often *the* memory).
+//
+// - **Worktree collapse**: project slugs containing `--claude-worktrees-`
+//   collapse to their base slug for the `distinctProjects` count. Avoids
+//   counting worktree-A and worktree-B of the same repo as separate
+//   projects when computing `promotionCandidate`.
+//
+// - **Empty bodies skipped**: every empty-body memory would cluster with every
+//   other and dwarf real findings. Routed out of `clusters`.
+//
+// - **Representative selection**: longest normalized body → most recent
+//   mtime. That's the "merge target" if the user later runs `memex merge`.
+//
+// - **Promotion candidate**: `distinctProjects >= 3 && type ∈ {user,
+//   feedback}`. The realistic "this should live in ~/.claude/CLAUDE.md"
+//   trigger.
+import { createHash } from "node:crypto";
+import { scanAll } from "./scan.js";
+const WORKTREE_SUFFIX_RE = /--claude-worktrees-.*$/;
+const SMART_QUOTES = [
+    [/[‘’‚‛]/g, "'"], // ' ' ‚ ‛
+    [/[“”„‟]/g, '"'], // " " „ ‟
+    [/[–—]/g, "-"], // – —
+    [/…/g, "..."], // …
+];
+/** Collapse `-foo-bar--claude-worktrees-xyz` → `-foo-bar`. */
+export function collapseWorktreeSlug(slug) {
+    return slug.replace(WORKTREE_SUFFIX_RE, "");
+}
+/**
+ * Normalize a string for fingerprinting. Idempotent.
+ *
+ * The pipeline is intentionally conservative — too-aggressive normalization
+ * causes false positives (e.g. stripping code blocks merges unrelated logcli
+ * notes). Too-lenient causes false negatives. This sits in the middle.
+ */
+export function normalizeForHash(s) {
+    if (!s)
+        return "";
+    let out = s.normalize("NFC");
+    out = out.replace(/\r\n/g, "\n");
+    for (const [re, replacement] of SMART_QUOTES)
+        out = out.replace(re, replacement);
+    out = out.toLowerCase();
+    // Strip trivial markdown wrappers WITHOUT touching code/URLs.
+    out = out
+        .replace(/^[ \t]*(?:[-*+]|\d+\.)[ \t]+/gm, "") // list markers
+        .replace(/^[ \t]*#{1,6}[ \t]+/gm, "") // headings
+        .replace(/(\*\*|__)([^*_]+?)\1/g, "$2") // bold
+        .replace(/(\*|_)([^*_]+?)\1/g, "$2"); // italic
+    out = out.replace(/\s+/g, " ").trim();
+    return out;
+}
+/** Normalize a name field — additionally strips trailing parentheticals. */
+export function normalizeName(name) {
+    if (!name)
+        return "";
+    return normalizeForHash(name.replace(/\s*\([^)]*\)\s*$/, ""));
+}
+function sha256Hex(input) {
+    return createHash("sha256").update(input).digest("hex");
+}
+export function computeBodyHash(body) {
+    return sha256Hex(normalizeForHash(body));
+}
+export function computeFullHash(memory) {
+    // For type=untyped, treat type as wildcard so missing metadata doesn't
+    // split otherwise-identical clusters.
+    const typePart = memory.type === "untyped" ? "*" : memory.type;
+    const parts = [
+        typePart,
+        normalizeName(memory.name),
+        normalizeForHash(memory.description ?? ""),
+        normalizeForHash(memory.body),
+    ];
+    return sha256Hex(parts.join("\n"));
+}
+const PROMOTION_TYPES = new Set(["user", "feedback"]);
+function memberFromMemory(m, mtimeIso, fullHash) {
+    return {
+        id: m.id,
+        filePath: m.filePath,
+        project: collapseWorktreeSlug(m.projectSlug),
+        rawProjectSlug: m.projectSlug,
+        name: m.name,
+        description: m.description,
+        type: m.type,
+        bodyBytes: Buffer.byteLength(m.body, "utf8"),
+        mtime: mtimeIso,
+        fullHash,
+    };
+}
+function pickRepresentative(members) {
+    // longest body → most recent mtime → first by id as tiebreak
+    const sorted = [...members].sort((a, b) => {
+        if (a.bodyBytes !== b.bodyBytes)
+            return b.bodyBytes - a.bodyBytes;
+        if (a.mtime !== b.mtime)
+            return a.mtime < b.mtime ? 1 : -1;
+        return a.id.localeCompare(b.id);
+    });
+    return { id: sorted[0].id, reason: "longest body, most recent mtime" };
+}
+export function findDuplicates(opts = {}) {
+    const includeUntyped = opts.includeUntyped ?? true;
+    const projects = scanAll(opts).filter((p) => !opts.projectFilter || p.slug.includes(opts.projectFilter));
+    const memories = projects.flatMap((p) => p.memories);
+    const consideredMemories = includeUntyped
+        ? memories
+        : memories.filter((m) => m.type !== "untyped");
+    // Group by bodyHash, skipping empty bodies.
+    const groups = new Map();
+    let skippedEmptyBodies = 0;
+    for (const m of consideredMemories) {
+        const normalized = normalizeForHash(m.body);
+        if (normalized.length === 0) {
+            skippedEmptyBodies++;
+            continue;
+        }
+        const hash = computeBodyHash(m.body);
+        const arr = groups.get(hash) ?? [];
+        arr.push(m);
+        groups.set(hash, arr);
+    }
+    // Materialize clusters where count >= 2, stable-sorted by:
+    //   distinctProjects DESC, count DESC, fingerprint ASC
+    const rawClusters = [];
+    for (const [fingerprint, mems] of groups.entries()) {
+        if (mems.length < 2)
+            continue;
+        const members = mems.map((m) => memberFromMemory(m, new Date(m.mtimeMs).toISOString(), computeFullHash(m)));
+        rawClusters.push({ fingerprint, members });
+    }
+    rawClusters.sort((a, b) => {
+        const aDP = new Set(a.members.map((m) => m.project)).size;
+        const bDP = new Set(b.members.map((m) => m.project)).size;
+        if (aDP !== bDP)
+            return bDP - aDP;
+        if (a.members.length !== b.members.length)
+            return b.members.length - a.members.length;
+        return a.fingerprint.localeCompare(b.fingerprint);
+    });
+    const clusters = rawClusters.map((raw, idx) => {
+        const distinctProjects = new Set(raw.members.map((m) => m.project)).size;
+        const intraProject = distinctProjects === 1;
+        // Cluster type = most common member type (ties broken alphabetically).
+        const typeCounts = new Map();
+        for (const m of raw.members)
+            typeCounts.set(m.type, (typeCounts.get(m.type) ?? 0) + 1);
+        const clusterType = [...typeCounts.entries()].sort((a, b) => {
+            if (a[1] !== b[1])
+                return b[1] - a[1];
+            return a[0].localeCompare(b[0]);
+        })[0][0];
+        const promotionCandidate = distinctProjects >= 3 && PROMOTION_TYPES.has(clusterType);
+        return {
+            id: `c${idx + 1}`,
+            tier: "bodyHash",
+            fingerprint: raw.fingerprint,
+            count: raw.members.length,
+            type: clusterType,
+            intraProject,
+            distinctProjects,
+            promotionCandidate,
+            representative: pickRepresentative(raw.members),
+            members: [...raw.members].sort((a, b) => a.id.localeCompare(b.id)),
+        };
+    });
+    // Summary stats
+    let duplicateFileCount = 0;
+    let wastedBytes = 0;
+    let promotionCandidates = 0;
+    for (const c of clusters) {
+        duplicateFileCount += c.count;
+        // "Wasted" = bytes used by every non-representative member.
+        const repId = c.representative.id;
+        for (const m of c.members) {
+            if (m.id !== repId)
+                wastedBytes += m.bodyBytes;
+        }
+        if (c.promotionCandidate)
+            promotionCandidates++;
+    }
+    return {
+        version: "1",
+        scannedAt: new Date().toISOString(),
+        config: { normalization: "v1", tier: "bodyHash" },
+        clusters,
+        summary: {
+            memoriesScanned: consideredMemories.length,
+            projectsScanned: projects.length,
+            clusterCount: clusters.length,
+            duplicateFileCount,
+            wastedBytes,
+            promotionCandidates,
+            skippedEmptyBodies,
+        },
+    };
+}
+//# sourceMappingURL=dedupe.js.map

package/dist/core/dedupe.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"dedupe.js","sourceRoot":"","sources":["../../src/core/dedupe.ts"],"names":[],"mappings":"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"}

package/dist/core/doctor.d.ts ADDED Viewed

@@ -0,0 +1,35 @@
+import { type ScanOptions } from "./scan.js";
+import { type LintIssue, type Severity } from "./lint.js";
+import type { MemoryTypeOrUntyped } from "./types.js";
+declare const SOFT_LINE_THRESHOLD: number;
+declare const SOFT_BYTE_THRESHOLD: number;
+export interface ProjectHealth {
+    slug: string;
+    memoryCount: number;
+    hasIndex: boolean;
+    indexLineCount: number | null;
+    indexByteSize: number | null;
+    /** True when the index is over either soft threshold but under both hard caps. */
+    indexApproachingCap: boolean;
+    /** True when the index has crossed either hard cap. */
+    indexOverCap: boolean;
+    issues: LintIssue[];
+    worstSeverity: Severity | null;
+}
+export interface DoctorReport {
+    generatedAt: string;
+    projectsScanned: number;
+    filesScanned: number;
+    totals: {
+        issuesBySeverity: Record<Severity, number>;
+        memoriesByType: Record<MemoryTypeOrUntyped, number>;
+    };
+    projects: ProjectHealth[];
+    /** Prioritized next-action list (errors first, then warns). */
+    nextActions: LintIssue[];
+}
+export interface DoctorOptions extends ScanOptions {
+    projectFilter?: string;
+}
+export declare function runDoctor(opts?: DoctorOptions): DoctorReport;
+export { SOFT_LINE_THRESHOLD, SOFT_BYTE_THRESHOLD };

package/dist/core/doctor.js ADDED Viewed

@@ -0,0 +1,106 @@
+// Doctor — aggregates scan + lint into a single health snapshot.
+//
+// `lint` is the per-issue stream optimized for jq/MCP/CI. `doctor` is the
+// human-readable "what's the state of my memory?" command. It adds stats,
+// per-project grouping, and soft "approaching limit" signals that aren't
+// lint-rule violations yet but are worth knowing about.
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { scanAll } from "./scan.js";
+import { lintAll, INDEX_BYTE_CAP, INDEX_LINE_CAP } from "./lint.js";
+import { parseMemoryIndex } from "./memoryIndex.js";
+// Soft cap = 80% of hard cap. When MEMORY.md crosses this we surface it in
+// doctor but do NOT escalate to a lint rule (no data loss yet).
+const SOFT_LINE_RATIO = 0.8;
+const SOFT_BYTE_RATIO = 0.8;
+const SOFT_LINE_THRESHOLD = Math.floor(INDEX_LINE_CAP * SOFT_LINE_RATIO);
+const SOFT_BYTE_THRESHOLD = Math.floor(INDEX_BYTE_CAP * SOFT_BYTE_RATIO);
+const SEV_ORDER = { error: 0, warn: 1, info: 2 };
+function indexStats(project) {
+    const idxPath = join(project.path, "memory", "MEMORY.md");
+    if (!existsSync(idxPath))
+        return { lineCount: null, byteSize: null };
+    try {
+        const parsed = parseMemoryIndex(idxPath);
+        return { lineCount: parsed.lineCount, byteSize: parsed.byteSize };
+    }
+    catch {
+        // If we can't parse, fall back to raw byte size so the user still gets a signal.
+        try {
+            const size = statSync(idxPath).size;
+            return { lineCount: null, byteSize: size };
+        }
+        catch {
+            return { lineCount: null, byteSize: null };
+        }
+    }
+}
+export function runDoctor(opts = {}) {
+    const projects = scanAll(opts).filter((p) => !opts.projectFilter || p.slug.includes(opts.projectFilter));
+    const lintResult = lintAll(opts);
+    // Group issues by project for fast lookup.
+    const issuesByProject = new Map();
+    for (const issue of lintResult.issues) {
+        const arr = issuesByProject.get(issue.projectSlug) ?? [];
+        arr.push(issue);
+        issuesByProject.set(issue.projectSlug, arr);
+    }
+    const issuesBySeverity = { error: 0, warn: 0, info: 0 };
+    for (const i of lintResult.issues)
+        issuesBySeverity[i.severity]++;
+    const memoriesByType = {
+        user: 0,
+        feedback: 0,
+        project: 0,
+        reference: 0,
+        untyped: 0,
+    };
+    const projectHealth = projects.map((project) => {
+        for (const m of project.memories)
+            memoriesByType[m.type]++;
+        const { lineCount, byteSize } = indexStats(project);
+        const overCap = (lineCount !== null && lineCount > INDEX_LINE_CAP) ||
+            (byteSize !== null && byteSize > INDEX_BYTE_CAP);
+        const approachingCap = !overCap &&
+            ((lineCount !== null && lineCount > SOFT_LINE_THRESHOLD) ||
+                (byteSize !== null && byteSize > SOFT_BYTE_THRESHOLD));
+        const issues = issuesByProject.get(project.slug) ?? [];
+        const worstSeverity = issues.length === 0
+            ? null
+            : issues.reduce((acc, i) => (SEV_ORDER[i.severity] < SEV_ORDER[acc] ? i.severity : acc), "info");
+        return {
+            slug: project.slug,
+            memoryCount: project.memories.length,
+            hasIndex: project.hasIndex,
+            indexLineCount: lineCount,
+            indexByteSize: byteSize,
+            indexApproachingCap: approachingCap,
+            indexOverCap: overCap,
+            issues,
+            worstSeverity,
+        };
+    });
+    // Sort projects: worst severity first, then by name.
+    projectHealth.sort((a, b) => {
+        const aSev = a.worstSeverity ? SEV_ORDER[a.worstSeverity] : 99;
+        const bSev = b.worstSeverity ? SEV_ORDER[b.worstSeverity] : 99;
+        if (aSev !== bSev)
+            return aSev - bSev;
+        return a.slug.localeCompare(b.slug);
+    });
+    // Next actions: errors first, then warns, in lint's original order (which is
+    // already deterministic by project + code).
+    const nextActions = [...lintResult.issues]
+        .filter((i) => i.severity !== "info")
+        .sort((a, b) => SEV_ORDER[a.severity] - SEV_ORDER[b.severity]);
+    return {
+        generatedAt: new Date().toISOString(),
+        projectsScanned: lintResult.projectsScanned,
+        filesScanned: lintResult.filesScanned,
+        totals: { issuesBySeverity, memoriesByType },
+        projects: projectHealth,
+        nextActions,
+    };
+}
+export { SOFT_LINE_THRESHOLD, SOFT_BYTE_THRESHOLD };
+//# sourceMappingURL=doctor.js.map

package/dist/core/doctor.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../src/core/doctor.ts"],"names":[],"mappings":"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"}

package/dist/core/journal.d.ts ADDED Viewed

@@ -0,0 +1,31 @@
+import type { Operation, Plan } from "./plan.js";
+export interface AppliedOp {
+    op: Operation;
+    /** The op that reverses this one. Captured at apply time from on-disk state. */
+    inverse: Operation;
+    appliedAt: string;
+    result: "success" | "skipped" | "failure";
+    /** Populated when result === "failure". */
+    error?: string;
+}
+export interface JournalEntry {
+    plan: Plan;
+    status: "complete" | "partial" | "failed";
+    startedAt: string;
+    finishedAt: string;
+    ops: AppliedOp[];
+    /** If this entry undoes another, the id of the original. */
+    undoOf?: string;
+}
+export declare function defaultJournalDir(): string;
+export interface JournalOptions {
+    /** Override the journal directory (used in tests). */
+    journalDir?: string;
+}
+export declare function ensureJournalDir(opts?: JournalOptions): string;
+export declare function writeJournalEntry(entry: JournalEntry, opts?: JournalOptions): string;
+export declare function readJournalEntry(id: string, opts?: JournalOptions): JournalEntry | null;
+/** Lists journal entries, newest first. */
+export declare function listJournal(opts?: JournalOptions): JournalEntry[];
+/** Most-recent entry, or null if the journal is empty. */
+export declare function latestJournalEntry(opts?: JournalOptions): JournalEntry | null;

package/dist/core/journal.js ADDED Viewed

@@ -0,0 +1,64 @@
+// Write-ahead journal at `~/.claude/.memex/log/<id>.json`.
+//
+// Every applied plan produces one journal entry. The entry stores the
+// original plan, the per-op execution result, and the inverse ops needed
+// to undo the plan. `memex undo` reads the most recent entry and applies
+// its inverses in reverse order.
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const JOURNAL_DIRNAME = ".memex";
+export function defaultJournalDir() {
+    return join(homedir(), ".claude", JOURNAL_DIRNAME, "log");
+}
+function resolveDir(opts) {
+    return opts.journalDir ?? defaultJournalDir();
+}
+export function ensureJournalDir(opts = {}) {
+    const dir = resolveDir(opts);
+    mkdirSync(dir, { recursive: true });
+    return dir;
+}
+/** Sort key embedded in the filename: ISO timestamp prefix makes lex == time. */
+function fileNameForId(id) {
+    return `${id}.json`;
+}
+export function writeJournalEntry(entry, opts = {}) {
+    const dir = ensureJournalDir(opts);
+    const file = join(dir, fileNameForId(entry.plan.id));
+    writeFileSync(file, JSON.stringify(entry, null, 2));
+    return file;
+}
+export function readJournalEntry(id, opts = {}) {
+    const file = join(resolveDir(opts), fileNameForId(id));
+    if (!existsSync(file))
+        return null;
+    return JSON.parse(readFileSync(file, "utf8"));
+}
+/** Lists journal entries, newest first. */
+export function listJournal(opts = {}) {
+    const dir = resolveDir(opts);
+    if (!existsSync(dir))
+        return [];
+    const files = readdirSync(dir)
+        .filter((n) => n.endsWith(".json"))
+        .sort()
+        .reverse();
+    const out = [];
+    for (const name of files) {
+        try {
+            out.push(JSON.parse(readFileSync(join(dir, name), "utf8")));
+        }
+        catch {
+            // Skip corrupt entries — they're informational only and shouldn't break
+            // listing of healthy entries.
+        }
+    }
+    return out;
+}
+/** Most-recent entry, or null if the journal is empty. */
+export function latestJournalEntry(opts = {}) {
+    const all = listJournal(opts);
+    return all.length > 0 ? all[0] : null;
+}
+//# sourceMappingURL=journal.js.map