claude-code-memory-explorer 0.4.0 → 0.5.0

package/package.json

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

package/public/app.js

@@ -258,6 +258,7 @@ const LOAD_ICONS = {
   conditional: '\u25CB',
   ondemand: '\u25CC',
   import: '@',
+  link: '\u2197',
 };
 const LOAD_TITLES = {
   always: 'Always loaded',
@@ -265,6 +266,7 @@ const LOAD_TITLES = {
   conditional: 'Conditional (path-scoped)',
   ondemand: 'On-demand',
   import: 'Imported by parent file',
+  link: 'Referenced via markdown link (not auto-loaded)',
 };
 
 let treeIndex = null;
@@ -282,17 +284,12 @@ function getTreeIndex() {
       groups[s.scope].push(s);
     }
   }
-  const navOrder = [];
-  function collect(item) {
-    navOrder.push(item);
-    const children = childrenOf[item.id];
-    if (children) for (const c of children) collect(c);
-  }
-  for (const scope of SCOPE_ORDER) {
-    const items = groups[scope];
-    if (items) for (const item of items) collect(item);
+  // Default-expand parents whose children are real discovered files (e.g. auto-memory
+  // dirs indexed by MEMORY.md). Pure @import/link references (importedBy set) stay collapsed.
+  for (const parentId in childrenOf) {
+    if (childrenOf[parentId].some((c) => !c.importedBy)) expandedItems.add(parentId);
   }
-  treeIndex = { groups, childrenOf, navOrder };
+  treeIndex = { groups, childrenOf };
   return treeIndex;
 }
 
@@ -315,16 +312,21 @@ function renderTree() {
     const loadIcon = LOAD_ICONS[item.load] || '';
     const loadTitle = LOAD_TITLES[item.load] || item.load;
     const meta = `${item.lines}L`;
-    const isConditional = item.load === 'conditional' || item.load === 'ondemand';
+    const isConditional = item.load === 'conditional' || item.load === 'ondemand' || item.load === 'link';
     const pad = indent ? ` style="padding-left:${12 + indent * 16}px"` : '';
     const muted = item.scope === 'agent-memory' ? ' tree-agent-item' : '';
+    const children = childrenOf[item.id];
+    const expanded = children && isItemExpanded(item.id);
+    const chevron = children
+      ? `<span class="tree-chevron" onclick="_toggleItem(event,'${escJs(item.id)}')" title="${children.length} referenced">${expanded ? '▾' : '▸'}</span>`
+      : '<span class="tree-chevron-spacer"></span>';
     let h = `<div class="tree-item${sel}${indent ? ' tree-child' : ''}${isConditional ? ' tree-conditional' : ''}${muted}" data-id="${esc(item.id)}" title="${esc(item.path)}" onclick="selectFile('${escJs(item.id)}')"${pad}>`;
+    h += chevron;
     h += `<span class="load-icon" title="${loadTitle}" style="color:var(--scope-${item.scope})">${loadIcon}</span>`;
     h += `<span class="file-name">${esc(item.name)}</span>`;
     h += `<span class="file-meta">${meta}</span>`;
     h += '</div>';
-    const children = childrenOf[item.id];
-    if (children) {
+    if (expanded) {
       for (const child of children) h += renderItem(child, (indent || 0) + 1);
     }
     return h;
@@ -396,6 +398,26 @@ function expandGroupForItem(item) {
   if (scope && isGroupCollapsed(scope)) setGroupCollapsed(scope, false);
 }
 
+// Referenced/child files are collapsed by default; expand on click. Only top-level
+// "root" files (those not pulled in via an import/link) are shown until expanded.
+const expandedItems = new Set();
+function isItemExpanded(id) {
+  return expandedItems.has(id);
+}
+function _toggleItem(event, id) {
+  event.stopPropagation();
+  if (expandedItems.has(id)) expandedItems.delete(id);
+  else expandedItems.add(id);
+  renderTree();
+}
+function expandItemAncestors(item) {
+  let cur = item;
+  while (cur?.parentId) {
+    expandedItems.add(cur.parentId);
+    cur = stackData.find((s) => s.id === cur.parentId);
+  }
+}
+
 function pushFileState(id) {
   const url = id ? `#${encodeURIComponent(id)}` : location.pathname;
   history.pushState({ fileId: id }, '', url);
@@ -403,6 +425,13 @@ function pushFileState(id) {
 
 function selectFile(id, pushState = true) {
   selectedFileId = selectedFileId === id ? null : id;
+  if (selectedFileId) {
+    const item = stackData.find((s) => s.id === selectedFileId);
+    if (item) {
+      expandGroupForItem(item);
+      expandItemAncestors(item);
+    }
+  }
   if (pushState) pushFileState(selectedFileId);
   renderTree();
   renderPreview();
@@ -413,47 +442,76 @@ function scrollToSelected() {
   if (el) el.scrollIntoView({ block: 'nearest' });
 }
 
+function currentItem() {
+  return stackData.find((s) => s.id === selectedFileId) || null;
+}
+
+function selectNav(id) {
+  selectedFileId = id;
+  pushFileState(id);
+  renderTree();
+  renderPreview();
+  scrollToSelected();
+}
+
+// Visible traversal order: collapsed subtrees and collapsed groups are skipped.
+function getVisibleOrder() {
+  const { groups, childrenOf } = getTreeIndex();
+  const order = [];
+  const walk = (item) => {
+    order.push(item);
+    if (isItemExpanded(item.id)) {
+      const children = childrenOf[item.id];
+      if (children) for (const c of children) walk(c);
+    }
+  };
+  for (const scope of SCOPE_ORDER) {
+    if (isGroupCollapsed(scope)) continue;
+    const items = groups[scope];
+    if (items) for (const item of items) walk(item);
+  }
+  return order;
+}
+
 function navigateTree(direction) {
-  const { navOrder } = getTreeIndex();
-  if (!navOrder.length) return;
-  let idx = navOrder.findIndex((s) => s.id === selectedFileId);
+  const order = getVisibleOrder();
+  if (!order.length) return;
+  let idx = order.findIndex((s) => s.id === selectedFileId);
   if (idx === -1) {
-    idx = direction > 0 ? 0 : navOrder.length - 1;
+    idx = direction > 0 ? 0 : order.length - 1;
   } else {
     idx += direction;
-    if (idx < 0) idx = navOrder.length - 1;
-    if (idx >= navOrder.length) idx = 0;
+    if (idx < 0) idx = order.length - 1;
+    if (idx >= order.length) idx = 0;
   }
-  const target = navOrder[idx];
-  selectedFileId = target.id;
-  expandGroupForItem(target);
-  pushFileState(selectedFileId);
-  renderTree();
-  renderPreview();
-  scrollToSelected();
+  selectNav(order[idx].id);
 }
 
-function navigateGroup(direction) {
-  const { groups } = getTreeIndex();
-  const activeScopes = SCOPE_ORDER.filter((sc) => groups[sc]?.length);
-  if (!activeScopes.length) return;
-
-  const current = stackData.find((s) => s.id === selectedFileId);
-  let scopeIdx = activeScopes.indexOf(getItemScope(current));
-  if (scopeIdx === -1) {
-    scopeIdx = direction > 0 ? 0 : activeScopes.length - 1;
+// l / Right: expand a collapsed node, descend into an expanded one, leaf = no-op.
+function expandOrDescend() {
+  const item = currentItem();
+  if (!item) return navigateTree(1);
+  const children = getTreeIndex().childrenOf[item.id];
+  if (!children?.length) return;
+  if (!isItemExpanded(item.id)) {
+    expandedItems.add(item.id);
+    renderTree();
   } else {
-    scopeIdx += direction;
-    if (scopeIdx < 0) scopeIdx = activeScopes.length - 1;
-    if (scopeIdx >= activeScopes.length) scopeIdx = 0;
-  }
-  const target = groups[activeScopes[scopeIdx]][0];
-  selectedFileId = target.id;
-  expandGroupForItem(target);
-  pushFileState(selectedFileId);
-  renderTree();
-  renderPreview();
-  scrollToSelected();
+    selectNav(children[0].id);
+  }
+}
+
+// h / Left: collapse an expanded node, otherwise ascend to its parent.
+function collapseOrAscend() {
+  const item = currentItem();
+  if (!item) return navigateTree(-1);
+  const children = getTreeIndex().childrenOf[item.id];
+  if (children?.length && isItemExpanded(item.id)) {
+    expandedItems.delete(item.id);
+    renderTree();
+  } else if (item.parentId) {
+    selectNav(item.parentId);
+  }
 }
 
 // #endregion RENDER_TREE
@@ -821,21 +879,23 @@ document.addEventListener('keydown', (e) => {
     e.preventDefault();
     changeProject();
   }
-  if (e.key === 'j' || e.key === 'ArrowDown') {
+  // Skip when modifiers are held (e.g. hub's Ctrl+Alt+Arrow app switching).
+  const plain = !e.ctrlKey && !e.altKey && !e.metaKey;
+  if (plain && (e.key === 'j' || e.key === 'ArrowDown')) {
     e.preventDefault();
     navigateTree(1);
   }
-  if (e.key === 'k' || e.key === 'ArrowUp') {
+  if (plain && (e.key === 'k' || e.key === 'ArrowUp')) {
     e.preventDefault();
     navigateTree(-1);
   }
-  if (e.key === 'h' || e.key === 'ArrowLeft') {
+  if (plain && (e.key === 'h' || e.key === 'ArrowLeft')) {
     e.preventDefault();
-    navigateGroup(-1);
+    collapseOrAscend();
   }
-  if (e.key === 'l' || e.key === 'ArrowRight') {
+  if (plain && (e.key === 'l' || e.key === 'ArrowRight')) {
     e.preventDefault();
-    navigateGroup(1);
+    expandOrDescend();
   }
   if (e.key === 'Enter' && selectedFileId) renderPreview();
   if (e.key === 'e' && selectedFileId) {
@@ -979,8 +1039,11 @@ document.addEventListener('DOMContentLoaded', async () => {
   await loadData();
   // Restore file selection from hash
   const hash = decodeURIComponent(location.hash.slice(1));
-  if (hash && stackData.find((s) => s.id === hash)) {
+  const hashItem = hash && stackData.find((s) => s.id === hash);
+  if (hashItem) {
     selectedFileId = hash;
+    expandGroupForItem(hashItem);
+    expandItemAncestors(hashItem);
     renderTree();
     renderPreview();
   }

package/public/index.html

@@ -157,8 +157,8 @@
             <table class="shortcut-table">
               <tr><td><kbd>j</kbd> / <kbd>&darr;</kbd></td><td>Next item</td></tr>
               <tr><td><kbd>k</kbd> / <kbd>&uarr;</kbd></td><td>Previous item</td></tr>
-              <tr><td><kbd>h</kbd> / <kbd>&larr;</kbd></td><td>Previous group</td></tr>
-              <tr><td><kbd>l</kbd> / <kbd>&rarr;</kbd></td><td>Next group</td></tr>
+              <tr><td><kbd>l</kbd> / <kbd>&rarr;</kbd></td><td>Expand / enter child</td></tr>
+              <tr><td><kbd>h</kbd> / <kbd>&larr;</kbd></td><td>Collapse / parent</td></tr>
               <tr><td><kbd>Enter</kbd></td><td>Select item</td></tr>
               <tr><td><kbd>Esc</kbd></td><td>Close modal</td></tr>
             </table>

package/public/style.css

@@ -42,13 +42,12 @@ body {
   background: var(--bg-deep);
   color: var(--text-primary);
   font-family: var(--font-sans);
-  font-size: 13px;
+  font-size: 14px;
   line-height: 1.5;
-  height: calc(100vh / 1.25);
+  height: 100vh;
   display: flex;
   flex-direction: column;
   overflow: hidden;
-  zoom: 1.25;
 }
 .mono {
   font-family: var(--font-mono);
@@ -299,10 +298,10 @@ body {
   color: var(--text-muted);
 }
 .tree-agent-item .file-name {
-  opacity: 0.7;
+  opacity: 0.78;
 }
 body.light .tree-agent-item .file-name {
-  opacity: 0.8;
+  opacity: 0.86;
 }
 .tree-item {
   padding: 5px 12px 5px 24px;
@@ -321,6 +320,25 @@ body.light .tree-agent-item .file-name {
   background: var(--accent-dim);
   color: var(--accent);
 }
+.tree-item .tree-chevron,
+.tree-item .tree-chevron-spacer {
+  width: 12px;
+  flex-shrink: 0;
+  text-align: center;
+}
+.tree-item .tree-chevron {
+  font-size: 9px;
+  color: var(--text-muted);
+  cursor: pointer;
+  border-radius: 3px;
+  transition:
+    color 0.1s,
+    background 0.1s;
+}
+.tree-item .tree-chevron:hover {
+  color: var(--accent-text);
+  background: var(--accent-dim);
+}
 .tree-item .load-icon {
   font-size: 10px;
   width: 12px;
@@ -329,7 +347,7 @@ body.light .tree-agent-item .file-name {
 }
 .tree-item .file-name {
   font-family: var(--font-mono);
-  font-size: 11px;
+  font-size: 13px;
   flex: 1;
   overflow: hidden;
   text-overflow: ellipsis;
@@ -342,13 +360,13 @@ body.light .tree-agent-item .file-name {
   flex-shrink: 0;
 }
 .tree-child .file-name {
-  opacity: 0.75;
+  opacity: 0.82;
 }
 .tree-conditional .file-name {
-  opacity: 0.55;
+  opacity: 0.68;
 }
 body.light .tree-conditional .file-name {
-  opacity: 0.75;
+  opacity: 0.8;
 }
 /* #endregion TREE */
 
@@ -366,8 +384,8 @@ body.light .tree-conditional .file-name {
 }
 .preview-title .file-path {
   font-family: var(--font-mono);
-  font-size: 11px;
-  color: var(--text-muted);
+  font-size: 12px;
+  color: var(--text-tertiary);
   overflow: hidden;
   text-overflow: ellipsis;
 }
@@ -383,10 +401,10 @@ body.light .tree-conditional .file-name {
   margin-top: 6px;
 }
 .preview-filepath {
-  padding: 4px 16px;
+  padding: 5px 16px;
   font-family: var(--font-mono);
-  font-size: 10px;
-  color: var(--text-muted);
+  font-size: 12px;
+  color: var(--text-tertiary);
   background: var(--bg-deep);
   border-bottom: 1px solid var(--border);
   overflow: hidden;
@@ -395,9 +413,9 @@ body.light .tree-conditional .file-name {
 }
 .preview-code {
   font-family: var(--font-mono);
-  font-size: 11px;
+  font-size: 13px;
   line-height: 1.6;
-  color: var(--text-secondary);
+  color: var(--text-primary);
   white-space: pre-wrap;
   word-break: break-word;
   padding: 12px 16px;
@@ -860,8 +878,8 @@ kbd {
   color: var(--error);
 }
 .toast.success {
-  border-color: #2ea043;
-  color: #2ea043;
+  border-color: var(--success);
+  color: var(--success);
 }
 @keyframes slideIn {
   from {
@@ -878,15 +896,18 @@ kbd {
 /* #region LIGHT_THEME */
 body.light {
   --bg-deep: #e8e6e3;
-  --bg-surface: #f4f3f1;
-  --bg-elevated: #dddbd8;
+  --bg-surface: #efede9;
+  --bg-elevated: #fbfaf9;
   --bg-hover: #d2d0cc;
-  --border: #a09b94;
+  --border: #cfcbc4;
   --text-primary: #0a0a0a;
   --text-secondary: #444444;
   --text-tertiary: #666666;
   --text-muted: #888888;
   --accent-text: #b85a20;
+  --accent-dim: rgba(232, 111, 51, 0.18);
+  --accent-glow: rgba(232, 111, 51, 0.5);
+  --success: #1a8a5a;
 }
 /* #endregion LIGHT_THEME */
 

package/server.js

@@ -17,21 +17,19 @@ function getArg(name) {
   return process.argv[eqIdx + 1] || null;
 }
 
+const expandHome = (p) => (p || '').replace(/^~/, os.homedir());
+
 const PORT = getArg('port') || process.env.PORT || 3459;
 const AUTO_OPEN = process.argv.includes('--open');
 const claudeDirArg = getArg('dir');
-const CLAUDE_DIR = claudeDirArg
-  ? claudeDirArg.replace(/^~/, os.homedir())
-  : path.join(os.homedir(), '.claude');
+const CLAUDE_DIR = claudeDirArg ? expandHome(claudeDirArg) : path.join(os.homedir(), '.claude');
 const projectDirArg = getArg('project');
 
 // #endregion CLI_ARGS
 
 // #region STATE
 
-let currentProjectPath = projectDirArg
-  ? path.resolve(projectDirArg.replace(/^~/, os.homedir()))
-  : process.cwd();
+let currentProjectPath = projectDirArg ? path.resolve(expandHome(projectDirArg)) : process.cwd();
 
 const cache = {};
 const CACHE_TTL = 30_000;
@@ -129,7 +127,7 @@ function parseImports(content) {
 function resolveImport(importPath, fromFile) {
   let resolved = importPath;
   if (resolved.startsWith('~')) {
-    resolved = resolved.replace(/^~/, os.homedir());
+    resolved = expandHome(resolved);
   } else {
     resolved = path.resolve(path.dirname(fromFile), resolved);
   }
@@ -325,7 +323,7 @@ function discoverMemorySources(projectPath) {
     }
   }
 
-  // 6. Auto memory
+  // 6. Auto memory (projects base honors `autoMemoryDirectory` user setting)
   const memoryDir = findMemoryDir(projectPath);
   if (memoryDir && fs.existsSync(memoryDir)) {
     pushMemoryDir(memoryDir, 'memory', 'memory');
@@ -376,10 +374,10 @@ function discoverMemorySources(projectPath) {
       if (!info) continue;
       const { resolved: imports, resolvedSoft: softImports, unresolved: unresolvedImports } = resolveAllImports(imp, info.content);
       const source = {
-        id: `import-${path.basename(imp, '.md')}-${depth}`,
+        id: `import-${imp.replace(/[^a-zA-Z0-9]/g, '-')}`,
         name: path.basename(imp),
         scope: parent.scope,
-        load: 'import',
+        load: hard ? 'import' : 'link',
         ...info,
         importedBy: parent.path,
         parentId: parent.id,
@@ -428,7 +426,7 @@ function getAncestorDirs(projectPath) {
 }
 
 function findMemoryDir(projectPath) {
-  const projectsDir = path.join(CLAUDE_DIR, 'projects');
+  const projectsDir = getProjectsBaseDir();
   if (!fs.existsSync(projectsDir)) return null;
   const encoded = encodeProjectPath(projectPath);
   const memDir = path.join(projectsDir, encoded, 'memory');
@@ -467,8 +465,17 @@ function encodeProjectPath(projectPath) {
     .replace(/\//g, '-');
 }
 
+// User-scope `autoMemoryDirectory` only — Claude Code rejects this key from project/local settings for security.
+function getProjectsBaseDir() {
+  let settings = {};
+  try { settings = JSON.parse(fs.readFileSync(path.join(CLAUDE_DIR, 'settings.json'), 'utf-8')); } catch { /* no settings */ }
+  const raw = settings.autoMemoryDirectory;
+  if (typeof raw === 'string' && raw.trim()) return path.resolve(expandHome(raw));
+  return path.join(CLAUDE_DIR, 'projects');
+}
+
 function findMemoryDirBySubstring(projectPath) {
-  const projectsDir = path.join(CLAUDE_DIR, 'projects');
+  const projectsDir = getProjectsBaseDir();
   if (!fs.existsSync(projectsDir)) return null;
   // Match by last 2-3 path segments
   const segments = projectPath.replace(/\\/g, '/').split('/').filter(Boolean);
@@ -525,7 +532,7 @@ app.get('/api/project', (_req, res) => {
 app.put('/api/project', (req, res) => {
   const { path: dirPath } = req.body;
   if (!dirPath) return res.status(400).json({ error: 'path required' });
-  const resolved = path.resolve(dirPath.replace(/^~/, os.homedir()));
+  const resolved = path.resolve(expandHome(dirPath));
   if (!fs.existsSync(resolved)) return res.status(404).json({ error: 'directory not found' });
   if (resolved !== path.resolve(currentProjectPath)) {
     currentProjectPath = resolved;
@@ -541,8 +548,12 @@ app.post('/api/refresh', (_req, res) => {
 
 function resolveAllowedPath(filePath) {
   if (!filePath) return { error: { status: 400, message: 'path required' } };
-  const resolved = path.resolve(filePath.replace(/^~/, os.homedir()));
-  const roots = [path.resolve(CLAUDE_DIR), path.resolve(currentProjectPath)];
+  const resolved = path.resolve(expandHome(filePath));
+  const roots = [
+    path.resolve(CLAUDE_DIR),
+    path.resolve(currentProjectPath),
+    getProjectsBaseDir(),
+  ];
   const inRoot = roots.some((r) => resolved === r || resolved.startsWith(r + path.sep));
   if (!inRoot) return { error: { status: 403, message: 'path outside allowed roots' } };
   return { resolved };
@@ -597,7 +608,7 @@ app.post('/api/memory/cleanup-orphans', (req, res) => {
 app.post('/api/open-in-editor', (req, res) => {
   const { path: filePath } = req.body;
   if (!filePath) return res.status(400).json({ error: 'path required' });
-  const resolved = filePath.replace(/^~/, os.homedir());
+  const resolved = expandHome(filePath);
   if (!fs.existsSync(resolved)) return res.status(404).json({ error: 'file not found' });
   const { exec } = require('child_process');
   exec(`code "${resolved}"`, (err) => {