claude-code-memory-explorer 0.14.1 → 0.15.0-rc.1

package/README.md

@@ -4,38 +4,70 @@
 [![license](https://img.shields.io/npm/l/claude-code-memory-explorer)](LICENSE)
 [![npm downloads](https://img.shields.io/npm/dm/claude-code-memory-explorer)](https://www.npmjs.com/package/claude-code-memory-explorer)
 
-**[Live Demo & Docs](https://nikiforovall.blog/claude-code-memory/)**
+See every memory file that Claude Code loads for a project, and let Claude find what is stale, false, or in conflict.
 
-> See everything Claude Code knows about your project — and find what's stale, false, or conflicting.
+**[Documentation](https://nikiforovall.blog/claude-code-memory/)**
 
-![Memory Diagnoser overview](assets/overview.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-h3-hub-memory-dark.webp">
+  <img alt="Memory Diagnoser with memory files grouped by user, project, rules, auto memory, and agent memory, the project CLAUDE.md open with four findings, and the summary cards at the bottom" src="website/public/shots/themes/ember-h3-hub-memory-light.webp">
+</picture>
 
-## Getting Started
+## Getting started
+
+You need Node.js 20 or later. Open a terminal in your project directory and run:
 
 ```bash
 npx claude-code-memory-explorer --open
 ```
 
-No config. The dashboard scans the Claude Code memory locations for the current project and renders the full stack. Browsing is read-only; nothing leaves your machine.
+The app scans the memory files for the current directory and opens the page in your browser. The default port is 3544. You do not need a config file. Browsing changes nothing on disk.
+
+To run an analysis, you also need Claude Code, installed and logged in. See [Getting started](https://nikiforovall.blog/claude-code-memory/getting-started/).
 
 ## Features
 
-- **Full memory stack** — user/project/local CLAUDE.md, rules, auto memory, agent memory, managed policies, and resolved `@import` chains in one view
-- **Claude analysis** — audit memory files with headless Claude: health score, per-file findings (stale, false, or conflicting claims) with suggested fixes, merged across runs
-- **Keyboard-driven** — j/k navigation, e to open in editor, Shift+P project picker, ? for help
-- **17 color themes** — each in light and dark, PWA installable
-- **Hub integration** — runs standalone or as a tab in [Claude Code Hub](https://github.com/NikiforovAll/claude-code-hub)
+- **Full memory stack.** Managed policy, user and project `CLAUDE.md` files (including `CLAUDE.local.md` and nested files in subdirectories), user and project rules, project skills, auto memory, agent memory, and the files they import or link, in one tree. See [What Claude Code loads](https://nikiforovall.blog/claude-code-memory/guides/memory-stack/).
+- **Load types.** Each file shows when Claude Code loads it: always, startup, conditional, on-demand, tree, import, or link.
+- **Memory footprint.** A bar and summary cards show the files, characters, and bytes that can load in each session, split by scope. The app does not estimate tokens.
+- **Rules with paths.** A rule with `paths` in its frontmatter shows as conditional, with its globs as badges in the file view.
+- **Auto memory and agent memory.** A `MEMORY.md` index shows as a table of its linked notes, with a mark at the 200-line startup cutoff. A cleanup button removes index lines that point to missing files.
+- **Analyze with Claude.** Runs `claude -p` on your machine with one reviewer subagent per file. Reviewers check each claim against your repository. You get a health score, findings such as duplicates, contradictions, and stale facts, and a suggested fix for each. Copy one finding as a prompt, or several as a fix plan. Each run shows its cost. See [Analyze memory with Claude](https://nikiforovall.blog/claude-code-memory/guides/analyze/).
+- **Keyboard-driven.** <kbd>↓</kbd> <kbd>↑</kbd> or <kbd>j</kbd> <kbd>k</kbd> move through the tree, <kbd>e</kbd> opens the file in your editor, <kbd>Shift</kbd>+<kbd>P</kbd> switches the project, and <kbd>?</kbd> shows all keys. See [Keyboard shortcuts](https://nikiforovall.blog/claude-code-memory/reference/shortcuts/).
+- **17 color themes**, each in light and dark. The app installs as a progressive web app.
+- **Claude Code Hub.** Runs on its own or as a tab in [Claude Code Hub](https://github.com/NikiforovAll/claude-code-hub), with project and theme sync. See [Run inside Claude Code Hub](https://nikiforovall.blog/claude-code-memory/reference/hub/).
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-memory-analysis-dark.webp">
+  <img alt="Claude analysis: health 77 of 100, counts by severity, a memory map colored by worst finding, and the list of findings with suggested fixes" src="website/public/shots/themes/ember-memory-analysis-light.webp">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-h3c-hub-memory-auto-memory-dark.webp">
+  <img alt="The auto memory MEMORY.md with a startup badge, its index table of linked notes, and three findings above the content" src="website/public/shots/themes/ember-h3c-hub-memory-auto-memory-light.webp">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="website/public/shots/themes/ember-h3d-hub-memory-rule-dark.webp">
+  <img alt="The api-design rule with a conditional badge, its paths frontmatter as badges, and one finding" src="website/public/shots/themes/ember-h3d-hub-memory-rule-light.webp">
+</picture>
 
 ## Configuration
 
-```
-PORT=8080                Custom port (default: 3544, falls back if busy)
---dir <path>             Custom Claude config dir (default: ~/.claude)
---project <path>         Project to inspect (default: current directory)
---open                   Open browser on start
-```
+| Flag | What it does | Default |
+| --- | --- | --- |
+| `--port <n>` | Port to listen on. If the port is busy, the app uses a random free port and prints it. | `PORT`, else `3544` |
+| `--open` | Opens the page in your browser after start. | Off |
+| `--dir <path>` | Claude config dir to read. | `CLAUDE_CONFIG_DIR`, else `CLAUDE_DIR`, else `~/.claude` |
+| `--project <path>` | Project the server starts on. | The current directory |
+| `--host <addr>` | Address to bind. | `HOST`, else `127.0.0.1` |
+| `--allowed-hosts <list>` | Comma-separated extra `Host` header values to accept. | `ALLOWED_HOSTS`, else none |
+
+The app has no authentication. Bind a non-loopback address only on a network you trust.
+
+To look at a different project, use the project picker (<kbd>Shift</kbd>+<kbd>P</kbd>) or add `?project=/path` to the URL. The pencil button and <kbd>e</kbd> run the editor in `EDITOR`, or `code` when it is not set. Analyze saves its runs in `<config dir>/memory-analysis/`.
 
-The config dir can also be set via the `CLAUDE_CONFIG_DIR` environment variable; the analyzer's headless `claude` run inherits it. Switch projects at runtime with the picker (Shift+P) or `?project=/path`.
+For all options and the files the app reads and writes, see [CLI and configuration](https://nikiforovall.blog/claude-code-memory/reference/configuration/). For common problems, see [Troubleshooting](https://nikiforovall.blog/claude-code-memory/reference/troubleshooting/).
 
 ## License
 

package/lib/net-guard.js

@@ -181,6 +181,16 @@ function createNetGuard(config = {}) {
     return next();
   }
 
+  // For a WebSocket upgrade, which originGuard must not judge: the handshake is a
+  // GET, and WebSocket has no CORS, so any page can open one. Browsers always send
+  // Origin on the handshake, so a missing or `null` one is refused, not trusted.
+  // Returns null when allowed, or the reason it was refused.
+  function upgradeVerdict(req) {
+    if (!hostAllowed(parseHostHeader(req.headers.host))) return 'unrecognized Host header';
+    if (originVerdict(req.headers.origin) !== true) return 'cross-origin or missing Origin';
+    return null;
+  }
+
   // Constant for the life of the process, and frameGuard runs ahead of
   // express.static — so this is built once rather than per asset fetch.
   //
@@ -229,12 +239,19 @@ function createNetGuard(config = {}) {
    * @param {any} app express app (or any http request handler)
    * @param {number} port 0 selects a free port
    * @param {(port: number) => void} [onReady]
-   * @param {{maxHeaderSize?: number}} [opts]
+   * `onUpgrade` is attached to both servers; a caller that attached it to the
+   * returned one alone would drop every WebSocket that arrives over the other family.
+   *
+   * @param {{maxHeaderSize?: number, onUpgrade?: (req: any, socket: any, head: Buffer) => void}} [opts]
    */
   function listenLoopback(app, port, onReady, opts = {}) {
     const http = require('http');
     const serverOpts = opts.maxHeaderSize ? { maxHeaderSize: opts.maxHeaderSize } : {};
-    const makeServer = (handler) => http.createServer(serverOpts, handler);
+    const makeServer = (handler) => {
+      const s = http.createServer(serverOpts, handler);
+      if (opts.onUpgrade) s.on('upgrade', opts.onUpgrade);
+      return s;
+    };
     const server = makeServer(app);
     let secondary = null;
 
@@ -261,7 +278,7 @@ function createNetGuard(config = {}) {
     return `WARNING: listening on ${BIND_HOST} - reachable from your network, with no authentication.`;
   }
 
-  return { BIND_HOST, ALLOWED_HOSTS, hostGuard, originGuard, frameGuard, listenLoopback, exposureWarning };
+  return { BIND_HOST, ALLOWED_HOSTS, EXPOSED, hostGuard, originGuard, upgradeVerdict, frameGuard, listenLoopback, exposureWarning };
 }
 
 module.exports = { createNetGuard, parseHostHeader, isLoopbackAddress };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-memory-explorer",
-  "version": "0.14.1",
+  "version": "0.15.0-rc.1",
   "description": "Memory explorer dashboard for Claude Code",
   "main": "server.js",
   "bin": {

package/public/style.css

@@ -1246,7 +1246,7 @@ body.light {
   --text-secondary: #444444;
   --text-tertiary: #666666;
   --text-muted: #888888;
-  --accent-text: #b85a20;
+  --accent-text: #a0501c;
   --accent-dim: rgba(232, 111, 51, 0.18);
   --accent-glow: rgba(232, 111, 51, 0.5);
   --success: #1a8a5a;

package/public/themes.css

@@ -11,18 +11,18 @@ body.light .theme-swatch-gruvbox { --sw-bg: #f3eee0; --sw-accent: #d65d0e; --sw-
 body.light .theme-swatch-catppuccin { --sw-bg: #eff1f5; --sw-accent: #8839ef; --sw-ink: #4c4f69; --sw-border: #bcc0cc; }
 .theme-swatch-tokyo-night { --sw-bg: #1a1b26; --sw-accent: #7aa2f7; --sw-ink: #c0caf5; --sw-border: #3b4261; }
 body.light .theme-swatch-tokyo-night { --sw-bg: #e9eaf0; --sw-accent: #2e7de9; --sw-ink: #343b58; --sw-border: #a8aecb; }
-.theme-swatch-solarized { --sw-bg: #073642; --sw-accent: #cb4b16; --sw-ink: #93a1a1; --sw-border: #586e75; }
-body.light .theme-swatch-solarized { --sw-bg: #f5efdc; --sw-accent: #cb4b16; --sw-ink: #073642; --sw-border: #d3cbb7; }
+.theme-swatch-solarized { --sw-bg: #073642; --sw-accent: #c96f47; --sw-ink: #e2dfd0; --sw-border: #586e75; }
+body.light .theme-swatch-solarized { --sw-bg: #fdf6e3; --sw-accent: #2280c2; --sw-ink: #073642; --sw-border: #cdc4ab; }
 .theme-swatch-dracula { --sw-bg: #282a36; --sw-accent: #bd93f9; --sw-ink: #f8f8f2; --sw-border: #565a75; }
 body.light .theme-swatch-dracula { --sw-bg: #f0f0f5; --sw-accent: #7c3aed; --sw-ink: #16161e; --sw-border: #c9c9d6; }
 .theme-swatch-nord { --sw-bg: #2e3440; --sw-accent: #88c0d0; --sw-ink: #eceff4; --sw-border: #4c566a; }
 body.light .theme-swatch-nord { --sw-bg: #eceff4; --sw-accent: #5e81ac; --sw-ink: #2e3440; --sw-border: #c2c9d6; }
 .theme-swatch-rose-pine { --sw-bg: #1f1d2e; --sw-accent: #c4a7e7; --sw-ink: #e0def4; --sw-border: #403d52; }
-body.light .theme-swatch-rose-pine { --sw-bg: #faf4ed; --sw-accent: #907aa9; --sw-ink: #575279; --sw-border: #dfdad9; }
+body.light .theme-swatch-rose-pine { --sw-bg: #faf4ed; --sw-accent: #907aa9; --sw-ink: #575279; --sw-border: #cecacd; }
 .theme-swatch-everforest { --sw-bg: #2d353b; --sw-accent: #a7c080; --sw-ink: #d3c6aa; --sw-border: #475258; }
-body.light .theme-swatch-everforest { --sw-bg: #fdf6e3; --sw-accent: #6f8352; --sw-ink: #4d5960; --sw-border: #d8d3ba; }
+body.light .theme-swatch-everforest { --sw-bg: #f5f4e8; --sw-accent: #6f8352; --sw-ink: #3d484e; --sw-border: #d3d2bf; }
 .theme-swatch-kanagawa { --sw-bg: #1f1f28; --sw-accent: #7e9cd8; --sw-ink: #dcd7ba; --sw-border: #54546d; }
-body.light .theme-swatch-kanagawa { --sw-bg: #f2ecbc; --sw-accent: #4d699b; --sw-ink: #545464; --sw-border: #c7bf94; }
+body.light .theme-swatch-kanagawa { --sw-bg: #f3f0e4; --sw-accent: #4d699b; --sw-ink: #545464; --sw-border: #d2ccb6; }
 .theme-swatch-one-dark { --sw-bg: #282c34; --sw-accent: #61afef; --sw-ink: #d7dae0; --sw-border: #4b5263; }
 body.light .theme-swatch-one-dark { --sw-bg: #fafafa; --sw-accent: #4078f2; --sw-ink: #383a42; --sw-border: #d4d4d6; }
 .theme-swatch-night-owl { --sw-bg: #0b2942; --sw-accent: #82aaff; --sw-ink: #d6deeb; --sw-border: #5f7e97; }
@@ -32,7 +32,7 @@ body.light .theme-swatch-monokai { --sw-bg: #f1efed; --sw-accent: #c08a00; --sw-
 .theme-swatch-github { --sw-bg: #24292e; --sw-accent: #58a6ff; --sw-ink: #e1e4e8; --sw-border: #444d56; }
 body.light .theme-swatch-github { --sw-bg: #f6f8fa; --sw-accent: #0366d6; --sw-ink: #24292e; --sw-border: #d1d5da; }
 .theme-swatch-ayu { --sw-bg: #10141c; --sw-accent: #e6b450; --sw-ink: #bfbdb6; --sw-border: #2d3343; }
-body.light .theme-swatch-ayu { --sw-bg: #f8f9fa; --sw-accent: #f2ae49; --sw-ink: #3d4149; --sw-border: #d8dde2; }
+body.light .theme-swatch-ayu { --sw-bg: #f8f9fa; --sw-accent: #c97612; --sw-ink: #3d4149; --sw-border: #d8dde2; }
 .theme-swatch-vitesse { --sw-bg: #181818; --sw-accent: #4d9375; --sw-ink: #dbd7ca; --sw-border: #333333; }
 body.light .theme-swatch-vitesse { --sw-bg: #f7f7f7; --sw-accent: #1c6b48; --sw-ink: #393a34; --sw-border: #d6d6d6; }
 .theme-swatch-synthwave { --sw-bg: #262335; --sw-accent: #ff7edb; --sw-ink: #ffffff; --sw-border: #495495; }
@@ -136,34 +136,36 @@ body.light[data-color-theme="tokyo-night"] {
 
 /* Solarized */
 body[data-color-theme="solarized"]:not(.light) {
-  --accent: #cb4b16;
-  --accent-text: #e9663a;
-  --accent-dim: rgba(203,75,22,0.25);
-  --accent-glow: rgba(203, 75, 22, 0.55);
+  --accent: #c96f47;
+  --accent-text: #d48a6a;
+  --accent-dim: rgba(201,111,71,0.25);
+  --accent-glow: rgba(201, 111, 71, 0.55);
   --bg-deep: #002b36;
   --bg-surface: #073642;
   --bg-elevated: #0a4250;
   --bg-hover: #11505f;
   --border: #586e75;
-  --text-primary: #93a1a1;
-  --text-secondary: #839496;
-  --text-tertiary: #657b83;
-  --text-muted: #586e75;
+  --text-primary: #e2dfd0;
+  --text-secondary: #b7c0bf;
+  --text-tertiary: #93a1a1;
+  --text-muted: #839496;
 }
 body.light[data-color-theme="solarized"] {
-  --accent: #cb4b16;
-  --accent-text: #b34a12;
-  --accent-dim: rgba(203,75,22,0.18);
-  --accent-glow: rgba(203, 75, 22, 0.5);
+  --accent: #2280c2;
+  --accent-text: #1b6aa3;
+  --accent-dim: rgba(34,128,194,0.18);
+  --accent-glow: rgba(34, 128, 194, 0.5);
   --bg-deep: #eee8d5;
-  --bg-surface: #f5efdc;
-  --bg-elevated: #fdf6e3;
-  --bg-hover: #e4ddc8;
-  --border: #d3cbb7;
+  --bg-surface: #fdf6e3;
+  --bg-elevated: #fffbef;
+  --bg-hover: #efe8d3;
+  --border: #cdc4ab;
   --text-primary: #073642;
-  --text-secondary: #586e75;
-  --text-tertiary: #657b83;
-  --text-muted: #839496;
+  --text-secondary: #4f6369;
+  --text-tertiary: #586e75;
+  --text-muted: #728589;
+  --sidebar-bg: #e6dfc7;
+  --sidebar-item-bg: #f3ecd6;
 }
 
 /* Dracula */
@@ -255,11 +257,11 @@ body.light[data-color-theme="rose-pine"] {
   --bg-surface: #faf4ed;
   --bg-elevated: #fffaf3;
   --bg-hover: #ebdfd4;
-  --border: #dfdad9;
+  --border: #cecacd;
   --text-primary: #575279;
   --text-secondary: #635e87;
-  --text-tertiary: #797593;
-  --text-muted: #9893a5;
+  --text-tertiary: #6e6a88;
+  --text-muted: #857f96;
 }
 
 /* Everforest */
@@ -283,15 +285,15 @@ body.light[data-color-theme="everforest"] {
   --accent-text: #56683f;
   --accent-dim: rgba(111,131,82,0.18);
   --accent-glow: rgba(111, 131, 82, 0.5);
-  --bg-deep: #f4f0d9;
-  --bg-surface: #fdf6e3;
-  --bg-elevated: #fffbef;
-  --bg-hover: #efebd4;
-  --border: #d8d3ba;
-  --text-primary: #4d5960;
-  --text-secondary: #5c6a72;
-  --text-tertiary: #7a8478;
-  --text-muted: #939f91;
+  --bg-deep: #ebeadb;
+  --bg-surface: #f5f4e8;
+  --bg-elevated: #fbfbf4;
+  --bg-hover: #e5e4d3;
+  --border: #d3d2bf;
+  --text-primary: #3d484e;
+  --text-secondary: #55636b;
+  --text-tertiary: #66705f;
+  --text-muted: #7a8577;
 }
 
 /* Kanagawa */
@@ -315,11 +317,11 @@ body.light[data-color-theme="kanagawa"] {
   --accent-text: #38537f;
   --accent-dim: rgba(77,105,155,0.18);
   --accent-glow: rgba(77, 105, 155, 0.5);
-  --bg-deep: #e5ddb0;
-  --bg-surface: #f2ecbc;
-  --bg-elevated: #faf5d2;
-  --bg-hover: #dcd5ac;
-  --border: #c7bf94;
+  --bg-deep: #e9e5d6;
+  --bg-surface: #f3f0e4;
+  --bg-elevated: #faf8f1;
+  --bg-hover: #e2ddcb;
+  --border: #d2ccb6;
   --text-primary: #545464;
   --text-secondary: #66667a;
   --text-tertiary: #716e61;
@@ -408,7 +410,7 @@ body[data-color-theme="monokai"]:not(.light) {
 }
 body.light[data-color-theme="monokai"] {
   --accent: #c08a00;
-  --accent-text: #9a6e00;
+  --accent-text: #856000;
   --accent-dim: rgba(192,138,0,0.18);
   --accent-glow: rgba(192, 138, 0, 0.5);
   --bg-deep: #e9e6e4;
@@ -471,10 +473,10 @@ body[data-color-theme="ayu"]:not(.light) {
   --text-muted: #6c7380;
 }
 body.light[data-color-theme="ayu"] {
-  --accent: #f2ae49;
-  --accent-text: #b87514;
-  --accent-dim: rgba(242,174,73,0.18);
-  --accent-glow: rgba(242, 174, 73, 0.5);
+  --accent: #c97612;
+  --accent-text: #a65e0c;
+  --accent-dim: rgba(201,118,18,0.18);
+  --accent-glow: rgba(201, 118, 18, 0.5);
   --bg-deep: #eff1f3;
   --bg-surface: #f8f9fa;
   --bg-elevated: #fcfcfc;