claude-memory-admin 1.5.1 → 1.6.0

package/README.md

@@ -21,13 +21,24 @@ itself, and worth saying out loud.
 
 ---
 
-### Prune: see what MEMORY.md actually costs you
+### Cleanup: what MEMORY.md costs you and what is broken, in one list
 
-![The Prune tab, showing how much of the MEMORY.md load limit a project uses and a sortable list of memories by age, size and inbound links](assets/prune.webp)
+![The Cleanup tab: the MEMORY.md load meter, then one worst-first list beneath it - a broken wikilink with Remove link, two over-long index hooks and two that only restate the description, each with its own Edit hook button, an empty section, and an orphan offered the MEMORY.md bullet it is missing](assets/cleanup.webp)
+
+### Memory: the list, the index and the graph
+
+![The Memory tab, List segment: memories grouped by their MEMORY.md section with age, size and inbound link count on each, a sort control and a Select toggle above them, and the opened memory beside the list with its metadata, its swept origin transcript struck through, and its wikilinks](assets/memory.webp)
 
 ### Graph: see how memories link to each other
 
-![The Graph tab, showing memories as nodes coloured by type with wikilinks as edges](assets/graph.webp)
+![The Graph segment of the Memory tab, showing memories as nodes coloured by type with wikilinks as edges, orphans below a dashed line and a dashed outline where a link points at nothing](assets/graph.webp)
+
+### Environment: what every session loads before a project is even chosen
+
+![The Global entry, whose only tab is Environment, showing the estimated token cost of the user-scope instruction files, a rule file reached twice through both an import and the rules directory so its tokens are paid for twice, and the order the files load in](assets/context.webp)
+
+There is a light theme and a dark one, toggled with `t`; the Memory shot above is
+the light one and the rest are dark.
 
 ---
 
@@ -66,6 +77,17 @@ project is to the cliff, and makes it quick to get back under it.
 
 ## What it does
 
+Everything lives under three tabs, each answering one question:
+
+| Tab | The question | Holds |
+| --- | --- | --- |
+| **Memory** | what is in here? | the memory list, `MEMORY.md`, the graph |
+| **Cleanup** | what should I fix? | the load meter and one worst-first list of fixable things |
+| **Environment** | what else does Claude load? | instructions, settings, sessions - all read-only |
+
+Undo is a button in the project header rather than a fourth tab, because it is a
+safety net and not a place you browse.
+
 - **Projects by real path.** The directories on disk are slugified cwds
   (`-Users-me-repos-Blog`) and the slugification is lossy. The true path is
   recovered from the `cwd` field in the session transcripts stored next to each
@@ -93,23 +115,27 @@ project is to the cliff, and makes it quick to get back under it.
   with snippets and match highlighting. Press `/` to jump to it.
 - **Read each memory** with its frontmatter as structured metadata and
   `[[wikilinks]]` as clickable links. Dead links are struck through in red.
-- **Prune** (see below).
-- **Graph** the wikilinks between memories. Hovering dims everything that is not
-  a neighbour, which is the only practical way to read a dense cluster.
+- **Cleanup** (see below).
+- **Graph** the wikilinks between memories, under Memory. Hovering dims everything
+  that is not a neighbour, which is the only practical way to read a dense cluster.
 - **Where each memory came from.** Claude Code stamps `originSessionId` into a
   memory's frontmatter, and the transcript it names sits next to the store until
   the sweep takes it. The memory reads *written in "Release process notes", on
   `main`* while that transcript is there, and says so plainly once it is gone:
   a swept id is struck through in red, like a dead wikilink, because why the
   memory exists can no longer be traced from anything on disk.
-- **Sessions**: the transcripts beside a store, with the retention window drawn
+- **Sessions** (under Environment): the transcripts beside a store, with the retention window drawn
   the way MEMORY.md's cutoff is - each session a tick, the sweep line where it
-  falls. Titles are the ones Claude Code generated, falling back to the session
+  falls. Under it, a tile per day shades how much work that day held, and
+  clicking one narrows the list to it; the grid spans the retention window
+  rather than a fixed year, because a year of empty tiles would read as *no
+  sessions* when it only means *already swept*. Titles are the ones Claude Code
+  generated, falling back to the session
   slug and then the opening prompt; a session that names itself nowhere in the
   part read is shown by id rather than given an invented name. Only the head of
   each file is ever read, so a 200MB store of transcripts costs a quarter of a
-  second, and nothing on this tab deletes one.
-- **Health**: orphans, dangling pointers, broken wikilinks, files linked only
+  second, and nothing here deletes one.
+- **What Cleanup checks**: orphans, dangling pointers, broken wikilinks, files linked only
   mid-sentence, `name` fields that disagree with the filename, two files claiming
   one `name`, a file bulleted twice, a blank `description`, a `type` outside the
   four documented ones, a memory that is frontmatter and little else, a hook that
@@ -118,19 +144,20 @@ project is to the cliff, and makes it quick to get back under it.
   been swept, a project whose last proof of its own path is about to be, and
   sessions that produced no memory at all while auto memory was on. An orphan
   can be given the `MEMORY.md` bullet it is missing without leaving the page.
-- **Every count is visible before you click.** Each tab carries a badge, coloured
-  amber for something to tidy and red for something actively broken, and the
-  sidebar gives each store a dot of its worst severity - memory, instructions and
-  settings together. Which project is in trouble is the first thing the app tells
-  you, not something you find by opening eight tabs each.
+- **Every count is visible before you click.** Each of the three tabs carries a
+  badge, coloured amber for something to tidy and red for something actively
+  broken, and the sidebar gives each store a dot of its worst severity - memory,
+  instructions and settings together. Which project is in trouble is the first
+  thing the app tells you, not something you find by opening every tab in turn.
 - **Dates you can trust.** Claude Code stamps `modified` into frontmatter, but
   only on files that already have some, and never adds frontmatter to a file
   without it. Anything falling back to the file's mtime is labelled, because
   mtime is reset by any copy or restore.
-- **Context**: what a session starting in this project would load as
-  *instructions*, which is the other half of the startup budget (see below).
-- **Settings**: every layer Claude Code would read, side by side, with the value
-  that wins and the ones it shadows (see below).
+- **Instructions** (under Environment): what a session starting in this project
+  would load as *instructions*, which is the other half of the startup budget
+  (see below).
+- **Settings** (under Environment): every layer Claude Code would read, side by
+  side, with the value that wins and the ones it shadows (see below).
 - **Delete with cascade**, always reversible.
 
 Everything above works the same on both kinds of store. The load meter, graph,
@@ -140,17 +167,20 @@ memory directory is a `MEMORY.md` index plus topic files under the same 200-line
 
 ## Keeping MEMORY.md small
 
-The **Prune** tab exists because a bloated index costs tokens on every single
-session and, past the limit, silently stops loading.
+The **Cleanup** tab exists because a bloated index costs tokens on every single
+session and, past the limit, silently stops loading. It is one list: the load
+meter, then everything worth doing something about, worst first, each row
+carrying its own fix. A finding and its fix are never on different tabs.
 
 - **Load meter**. How much of the 200-line / 25KB budget the index uses, and
   which of the two is binding. Frontmatter and HTML comments are excluded,
   because Claude Code strips those before loading.
-- **The cutoff, drawn where it falls**. Past the limit, the MEMORY.md tab rules a
-  line across the file and dims everything below it, and Prune names the memories
-  that stopped being loaded. Because the stripping shifts every line, the cutoff
+- **The cutoff, drawn where it falls**. Past the limit, the MEMORY.md segment rules
+  a line across the file and dims everything below it, and Cleanup lists the
+  memories that stopped being loaded at the top of the worklist, each with
+  **Move up**. Because the stripping shifts every line, the cutoff
   is mapped back to real line numbers rather than counted in the loaded text. The
-  tab reads the index either **rendered** — headings, lists and clickable entries,
+  segment reads the index either **rendered** — headings, lists and clickable entries,
   with pointers to files that do not exist struck through — or as **source**, with
   line numbers. Either way the cutoff is drawn in the same place. The choice is
   remembered.
@@ -163,16 +193,18 @@ session and, past the limit, silently stops loading.
 - **Move above the cutoff**. Past the limit, an entry is on disk but invisible.
   **Move up** relocates its bullet, and the indented lines under it, to the end
   of any section that starts above the cutoff. It moves one entry rather than
-  making room, so whatever is now last drops below the line instead - the tab
+  making room, so whatever is now last drops below the line instead - the app
   says so before you do it.
 - **Possible overlap**. Pairs of memories ranked by shared *rare* vocabulary, to
   surface the same lesson saved three times from three sessions. It is a hint,
-  not a verdict. **Merge** folds one into the other: the body moves under a
-  heading you name, every `[[wikilink]]` that pointed at the source is repointed
-  rather than broken, a link the survivor had to the source becomes plain text
-  instead of a self-link, and the two index bullets collapse to one.
-- **Bulk prune**. Sort by age, size, or inbound links, tick several, delete them
-  as one restore point.
+  not a verdict, so it sorts last. **Merge** folds one into the other: the body
+  moves under a heading you name, every `[[wikilink]]` that pointed at the source
+  is repointed rather than broken, a link the survivor had to the source becomes
+  plain text instead of a self-link, and the two index bullets collapse to one.
+
+Bulk pruning is not here, because it is browsing rather than fixing: the **Memory**
+list sorts by age, size or inbound links, and **Select** turns on the checkboxes so
+several can go as one restore point. One list of memories, not two.
 
 Anthropic's own guidance for the index: one line per entry, detail in the topic
 files, merge or drop stale entries.
@@ -180,13 +212,13 @@ files, merge or drop stale entries.
 ## The other half of the budget
 
 `MEMORY.md` is not the only thing loaded at the start of every session. The
-**Context** tab resolves what else is, in load order: managed policy, your
+**Environment** tab's **Instructions** segment resolves what else is, in load order: managed policy, your
 `~/.claude/CLAUDE.md` and `~/.claude/rules/`, every `CLAUDE.md` and
 `CLAUDE.local.md` from the filesystem root down to the project, `.claude/CLAUDE.md`,
 and `.claude/rules/`, with `@path` imports expanded and `claudeMdExcludes` applied.
 
 Unlike `MEMORY.md`, none of it is truncated: `CLAUDE.md` files load in full
-however long they are. So the tab reports cost rather than a cliff, and separates
+however long they are. So it reports cost rather than a cliff, and separates
 what every session pays for from the path-scoped rules that only load on a match.
 
 It also finds the failures that leave a file silently doing nothing:
@@ -212,7 +244,7 @@ Backticks are respected, so a `` `@README` `` in your prose is not reported as a
 import, and neither is an email address.
 
 Every file listed opens in place, so you can read what actually loads without
-leaving the tab. Nothing here is editable: the app never rewrites a `CLAUDE.md`.
+leaving the page. Nothing here is editable: the app never rewrites a `CLAUDE.md`.
 
 ### The user scope on its own
 
@@ -226,7 +258,7 @@ It holds instructions rather than memory, so it is read-only and has no MEMORY.m
 graph or trash. Search does not reach into it.
 
 This is re-derived from the documented resolution rules rather than reported by
-Claude Code, and the tab says so. Run `/context` in a session for the ground
+Claude Code, and the app says so. Run `/context` in a session for the ground
 truth, or the `InstructionsLoaded` hook to log exactly what loaded and why.
 
 ## The one check that reads your code
@@ -237,7 +269,7 @@ it takes the paths a memory names in a code span and asks whether anything in th
 repository still matches them. A memory whose `Foo.cs` was renamed two months ago
 still reads as authoritative, and nothing else on this page can tell.
 
-Turn it on from the Health tab, per store; the choice is remembered in the browser
+Turn it on from the bottom of the Cleanup tab, per store; the choice is remembered in the browser
 and nothing is written to disk. It walks the project once, skipping `.git`,
 `node_modules`, build output and the like, and matches by suffix - a memory that
 says `Infrastructure/Reporting/Foo.cs` for a file that really lives under
@@ -246,13 +278,14 @@ alone reported seven real paths in ten as missing. Only a token with a real sour
 extension is treated as a claim about a file, because memories are also full of
 HTTP routes and type names that no file was ever going to match.
 
-It is a pointer, not a verdict, and the tab says so: a file that moved reads the
+It is a pointer, not a verdict, and the app says so: a file that moved reads the
 same as one the memory never got right.
 
 ## Which settings are actually in force
 
 Five files can set the keys this tool cares about, and the one everybody edits,
-`~/.claude/settings.json`, is the weakest of them. The **Settings** tab reads all
+`~/.claude/settings.json`, is the weakest of them. The **Environment** tab's
+**Settings** segment reads all
 five and shows, per key, the value that wins and the ones it shadows, struck
 through, each labelled with the file it came from:
 
@@ -267,9 +300,10 @@ It also names the failures that are otherwise silent:
 - A file that parses but is not an object, or cannot be read at all.
 - An `autoMemoryDirectory` that is neither absolute nor `~/`-prefixed.
 - A value Claude Code accepts the key of but not the number, like a
-  `cleanupPeriodDays` below 1: the tab shows what is written *and* what applies.
+  `cleanupPeriodDays` below 1: it shows what is written *and* what applies.
 
-The tab is read-only. It reports what is configured; it never writes a setting.
+Every segment of Environment is read-only. It reports what is configured; it never
+writes a setting.
 
 ## Everything it writes is reversible
 
@@ -282,12 +316,14 @@ operation, and they are trashed and restored as a single step.
 one restore point. Session transcripts (`*.jsonl`) and the project folder are
 never touched, only the contents of `memory/`.
 
-**Remove link** in the Health tab clears a `[[wikilink]]` whose target no longer
+**Remove link** in the Cleanup tab clears a `[[wikilink]]` whose target no longer
 exists. The markup goes and the words stay, so `see [[gone]] for details` becomes
 `see gone for details`.
 
 Everything lands in `memory/.trash/` with a restore record and comes back from the
-Trash tab, one undo per operation however many files it touched.
+**Undo** control in the project header, one undo per operation however many files
+it touched. Undo is not a place you browse, so it is a button with a count rather
+than a tab of its own.
 
 The app never writes a memory file of its own. It edits `MEMORY.md` a line at a
 time - a hook rewritten, a bullet added or moved - and each of those keeps every
@@ -363,87 +399,6 @@ No bundler and no build step to run it: the backend is `node:http` plus `node:fs
 and the frontend is plain ES modules the browser loads directly. Two runtime
 dependencies, `marked` and `dompurify`, both only for rendering memory bodies safely.
 
-Styling is the one thing that is compiled. `styles/app.css` is the Tailwind v4
-source and `public/styles.css` is its committed output, so an installed copy is
-ready to serve and never builds anything. After editing the source, run
-`npm run build:css` and commit the result — CI rebuilds it and fails on drift.
-
-| Path | Purpose |
-| --- | --- |
-| `bin/claude-memory-admin.mjs` | CLI entry point and argument parsing |
-| `server.mjs` | HTTP server: static files + JSON API |
-| `src/projects.mjs` | Project discovery, slug → real path resolution |
-| `src/settings.mjs` | Layered reads of Claude Code's settings files, and the report behind the Settings tab |
-| `src/pathcache.mjs` | The opt-in record of confirmed project paths |
-| `src/sessions.mjs` | Session transcripts: bounded head reads, retention, provenance |
-| `src/stores.mjs` | Store discovery: the user scope, auto memory and the three agent scopes |
-| `src/instructions.mjs` | CLAUDE.md chain, `@` imports and rules resolution |
-| `src/parse.mjs` | `MEMORY.md` and frontmatter parsers, wikilinks |
-| `src/checks.mjs` | The consistency checks, as pure functions over parsed data |
-| `src/pathcheck.mjs` | The opt-in check of paths a memory names, against the repo |
-| `src/model.mjs` | Joins index, files, graph and health into one model |
-| `src/stats.mjs` | Load-limit accounting and overlap detection |
-| `src/search.mjs` | Full-text search across every store |
-| `src/mutate.mjs` | Delete / edit / merge / restore, the only code that writes |
-| `styles/app.css` | Tailwind source, compiled to `public/styles.css` |
-| `public/` | Frontend |
-
-Tests run against committed fixtures under `test/fixtures/`: a projects store
-encoding the awkward shapes real memory directories contain, including one index
-deliberately past the load limit, an `agents/` tree covering all three subagent
-scopes, and an `instructions/` tree covering the import and glob edge cases. Your own
-`~/.claude/projects` is additionally checked when it exists, always on a
-throwaway copy.
-
-### Releasing
-
-Publishing runs in CI. You do not bump anything by hand.
-
-Go to **Actions, Release, Run workflow**, pick `patch`, `minor` or `major`, and
-run it. The workflow tests, bumps `package.json` and `package-lock.json`, commits
-and tags the bump, pushes both, then publishes to npm.
-
-If you would rather cut the version locally, that still works:
-
-```bash
-npm version patch
-git push --follow-tags
-```
-
-Pushing a `v*` tag publishes whatever is in `package.json`, after checking the
-two agree. Either route refuses to publish a version that is already on npm,
-because npm never allows one to be replaced.
-
-It needs one repository secret:
-
-| Secret | Value |
-| --- | --- |
-| `NPM_TOKEN` | an npm **Automation** access token with publish rights |
-
-Add it under *Settings, Secrets and variables, Actions, New repository secret*.
-An Automation token is the right kind because it bypasses 2FA, which an
-unattended workflow cannot satisfy.
-
-Releases are published with [npm provenance](https://docs.npmjs.com/generating-provenance-statements),
-so every version carries a signed, verifiable record of the workflow run and
-commit that built it. That needs the `id-token: write` permission the workflow
-already requests, a public repository, and the `repository` field in
-`package.json` pointing at this repo.
-
-Two things that will bite if they apply to you: the workflow pushes the bump
-commit to the default branch, so a branch protection rule that blocks pushes
-will stop it; and the tag it pushes uses `GITHUB_TOKEN`, which by design does
-not trigger other workflows, so there is no double publish.
-
-### Screenshots and demo data
-
-The screenshots come from an invented store, never a real one:
-
-```bash
-node scripts/demo-store.mjs /tmp/demo-store
-npm start -- --root /tmp/demo-store
-```
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-memory-admin",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Browse, audit and prune the auto memory Claude Code keeps under ~/.claude/projects",
   "keywords": [
     "claude",

package/public/api.mjs

@@ -0,0 +1,26 @@
+import * as ui from '/ui.mjs';
+import { el, node } from '/dom.mjs';
+
+export async function api(path, options) {
+  const response = await fetch(path, {
+    headers: { 'content-type': 'application/json' },
+    ...options,
+  });
+  const data = await response.json().catch(() => ({ error: 'Bad response from server' }));
+  if (!response.ok) throw new Error(data.error || `Request failed (${response.status})`);
+  return data;
+}
+
+export function toast(message, { error = false, action } = {}) {
+  const element = node('div', { class: ui.toast(error) });
+  element.append(document.createTextNode(message));
+  if (action) {
+    element.append(node('button', {
+      class: ui.toastAction,
+      text: action.label,
+      onclick: () => { element.remove(); action.run(); },
+    }));
+  }
+  el('toast-root').append(element);
+  setTimeout(() => element.remove(), action ? 12000 : 4500);
+}