claude-memory-explorer 0.1.0

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "claude-memory-explorer",
+  "version": "0.1.0",
+  "description": "Browse, dedupe, lint, and promote your Claude Code auto-memory across every project. CLI + TUI + MCP server.",
+  "type": "module",
+  "bin": {
+    "memex": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "skills",
+    ".claude-plugin",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hseinmoussa/claude-memory-explorer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/hseinmoussa/claude-memory-explorer/issues"
+  },
+  "homepage": "https://github.com/hseinmoussa/claude-memory-explorer#readme",
+  "scripts": {
+    "build": "tsc && chmod +x dist/cli/index.js",
+    "dev": "tsx src/cli/index.ts",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm test && npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "memory",
+    "mcp",
+    "mcp-server",
+    "anthropic",
+    "cli",
+    "tui",
+    "ink",
+    "plugin",
+    "dedupe",
+    "lint"
+  ],
+  "author": "Hussein Moussa",
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.0",
+    "ink-testing-library": "^4.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "gray-matter": "^4.0.3",
+    "ink": "^5.0.1",
+    "react": "^18.3.1",
+    "zod": "^3.23.0"
+  }
+}

package/skills/curate-memory/SKILL.md

@@ -0,0 +1,60 @@
+---
+description: Curate Claude Code auto-memory across all projects — find duplicates, stale facts, conflicts, structural issues (broken YAML, dangling references, over-cap MEMORY.md), and memories that should be promoted to global (~/.claude/CLAUDE.md). Use when the user says "clean up my memory", "dedupe my memory", "find stale memories", "promote this memory to global", "memex doctor", "/curate-memory", or describes wanting the memory tree in better shape. Operates across ALL projects (~/.claude/projects/*/memory/) — covers the cross-project gap that the built-in consolidate-memory skill does not.
+allowed-tools: Read mcp__memex__*
+---
+
+# Curate auto-memory
+
+You have an MCP server `memex` available. Use its tools to audit and improve the user's memory tree without making destructive changes the user hasn't confirmed.
+
+## Available tools
+
+(All tools are exposed at `mcp__memex__<name>` — the model handles the
+namespace prefix; we use the short names in this skill for readability.)
+
+Read-only:
+- `memex.doctor` — full health report. **Always start here.**
+- `memex.list_memories` — Memory[] across all projects, filterable
+- `memex.find_duplicates` — cross-project clusters
+- `memex.lint` — structural issues (broken-yaml, dangling-ref, missing-index, orphan-file, untyped-file, over-cap)
+- `memex.journal_list` / `memex.journal_latest` — the mutation log
+
+Plan generators (build a Plan, do NOT execute):
+- `memex.plan_merge` — collapse a duplicate cluster to its representative
+- `memex.plan_promote_memory` — move one memory to ~/.claude/CLAUDE.md
+- `memex.plan_promote_cluster` — replace whole cluster with one CLAUDE.md block
+
+Mutating (only run after confirming with the user):
+- `memex.apply_plan` — execute a Plan. Always journaled at ~/.claude/.memex/log/
+- `memex.undo` — reverse the most recent applied plan (or any by id)
+
+## Workflow
+
+1. **Always start with `doctor`.** It's the cheapest, most informative single call.
+2. **Triage**:
+   - Any `error`-severity issues (broken-yaml, over-cap, unreadable) — surface them first; offer to help the user fix manually (broken YAML is not safely auto-fixable).
+   - Cross-project duplicate clusters flagged as `promotionCandidate` — strongly suggest `plan_promote_cluster` (one block in CLAUDE.md replaces N project copies).
+   - Plain duplicates (cluster, not promote candidate) — suggest `plan_merge` to collapse to the representative.
+   - `info` issues (untyped-file, orphan-file when no pointer index) — mention but don't push.
+3. **Before any mutation**: call the appropriate `plan_*` tool, then show the resulting Plan to the user (count of ops, file paths, byte savings). Ask: "Apply this? (y/n)". Only call `apply_plan` after explicit yes.
+4. **After applying**: print the new journal entry id and tell the user how to reverse: `memex undo` (CLI) or call `memex.undo` again here.
+5. **Composition**: this skill is cross-project. The built-in `consolidate-memory` skill is intra-project. They compose — run consolidate-memory per project first if needed, then run this for the cross-project sweep.
+
+## What NOT to do
+
+- **Never call `apply_plan` without explicit user confirmation.** The plan generator output is the confirmation surface — show it and wait.
+- **Never modify files outside `~/.claude/projects/<slug>/memory/` and `~/.claude/CLAUDE.md`.** memex enforces this, but don't suggest workarounds that would.
+- **Don't try to fix broken-yaml automatically.** Report the file path + the hint memex gives, and let the user open it.
+- **Don't promote `project`- or `reference`-typed memories** — those are project-scoped by design. Only `user` and `feedback` types are sensible promotion candidates.
+
+## Example session
+
+User: "clean up my claude memory"
+
+You:
+1. Call `memex.doctor` → see 1 error (broken-yaml) and 1 promotion candidate cluster.
+2. Report the broken-yaml first; suggest the user open the file (provide the path + hint).
+3. Call `memex.plan_promote_cluster` for the candidate cluster.
+4. Show the Plan: "Would write 1 block to ~/.claude/CLAUDE.md and delete 3 source files across 3 projects. Apply?"
+5. On confirm, call `memex.apply_plan` with the plan.
+6. Confirm success and provide the undo id.