claude-mneme 2.9.1

package/commands/entity.md

@@ -0,0 +1,64 @@
+---
+description: Look up what Mneme knows about a file, function, or entity
+---
+
+## Your task
+
+The user wants to query what Mneme knows about a specific entity (file, function, error, or package). They may have provided the entity name after the command.
+
+If the user provided a query (e.g., `/entity auth.ts`), search for it directly.
+
+If no query was provided, ask the user: "What entity would you like to look up? (e.g., a file name, function, or package)"
+
+## How to query entities
+
+Use the mem-entity script to search the entity index:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-entity.mjs" [options] [query]
+```
+
+Options:
+- `--list` - List all indexed entities with their mention counts
+- `--category <cat>` - Filter by category: files, functions, errors, packages
+- `<query>` - Search for entities matching this name (partial match supported)
+
+## Examples
+
+```bash
+# Look up a specific file
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-entity.mjs" auth.ts
+
+# List all indexed files
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-entity.mjs" --list --category files
+
+# Search for functions containing "handle"
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-entity.mjs" --category functions handle
+```
+
+## Output format
+
+The script returns JSON with:
+- `matches` - Entities matching the query
+- Each match includes: `name`, `category`, `mentions`, `lastSeen`, `contexts` (recent activity)
+
+## How to respond
+
+1. Run the query
+2. Present results in a readable format, highlighting:
+   - How many times the entity was mentioned
+   - When it was last seen
+   - Recent contexts where it appeared
+3. If no matches found, suggest similar entities or let user know
+4. For broad queries, summarize the top results
+
+## Example response
+
+For `/entity auth.ts`:
+
+> **auth.ts** (file) — 12 mentions, last seen 2 hours ago
+>
+> Recent activity:
+> - [commit] Added JWT validation to auth middleware
+> - [task] Implementing auth flow
+> - [prompt] User asked about auth token refresh

package/commands/forget.md

@@ -0,0 +1,69 @@
+---
+description: Remove entries from remembered items
+---
+
+## Your task
+
+The user wants to remove something from their remembered items. They may have specified what to forget, or you may need to show them the list.
+
+## How to use the forget script
+
+The mem-forget script has three modes:
+
+### List all entries
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-forget.mjs" --list
+```
+Returns JSON array of entries with their indices.
+
+### Remove entries by index
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-forget.mjs" --remove 0,2,3
+```
+Removes entries at the specified indices (comma-separated).
+
+### Find matching entries (AI-assisted)
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-forget.mjs" --match "description of what to forget"
+```
+Uses AI to identify which entries match the description. Returns matching indices.
+
+## Workflow
+
+### If the user specified what to forget (e.g., `/forget my tabs preference`)
+
+1. Run the script with `--match` to find matching entries
+2. If matches found, show the user what will be removed
+3. Ask for confirmation before removing
+4. On confirmation, run `--remove` with the indices
+
+### If the user just said `/forget` with no content
+
+1. Run `--list` to show all remembered items
+2. Display them numbered (starting from 0) with type and content
+3. Ask the user which ones to remove (they can specify by number or describe what to remove)
+4. If they give numbers: confirm and remove those indices
+5. If they describe what to remove: use `--match` to find them, confirm, then remove
+
+## Guidelines
+
+1. Always show the user exactly what will be removed before doing it
+2. Require explicit confirmation before removing anything
+3. After removal, confirm what was removed
+4. If no matches found, let the user know and offer to list all entries
+
+## Example interactions
+
+User: `/forget my preference about tabs`
+→ Run `--match "preference about tabs"`
+→ Show: "Found 1 matching entry: [preference] Prefers tabs over spaces. Remove it?"
+→ On yes: Run `--remove 0`
+→ Confirm: "Removed 1 entry."
+
+User: `/forget`
+→ Run `--list`
+→ Show numbered list of all entries
+→ Ask: "Which would you like to remove? (Enter numbers or describe)"
+→ User: "1 and 3"
+→ Confirm: "Remove these 2 entries? [show them]"
+→ On yes: Run `--remove 1,3`

package/commands/remember.md

@@ -0,0 +1,60 @@
+---
+description: Save something to memory for future sessions
+---
+
+## Your task
+
+The user wants to save something to memory. They may have provided the content after the /remember command, or you may need to ask them what to remember.
+
+If the user provided content (e.g., `/remember I prefer using TypeScript`), save it directly.
+
+If no content was provided, ask the user: "What would you like me to remember?"
+
+## How to save memories
+
+Use the mem-add script to save the memory:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-add.mjs" <type> "<content>"
+```
+
+Types to use:
+- `preference` - User preferences (coding style, tools, workflows)
+- `project` - Project information and status
+- `fact` - Facts about the user or environment
+- `note` - General notes
+- `lesson` - Lessons learned, anti-patterns, approaches that failed — things to avoid repeating
+
+## How it works
+
+Remembered items are stored in a dedicated persistent file (`remembered.json`) separate from the activity log. They are **never summarized or removed automatically** — they are injected into every session exactly as saved.
+
+If the user wants to remove or edit remembered items, they must manually edit the file:
+`~/.claude-mneme/projects/<project>/remembered.json`
+
+Let the user know this when saving, e.g.: "Saved. This will persist across all future sessions. To remove it later, edit `remembered.json` in your project's memory directory."
+
+## Guidelines
+
+1. Parse what the user wants to remember and choose the appropriate type
+2. Keep the content concise but complete
+3. Confirm what was saved and briefly explain persistence
+4. If ambiguous, default to `note` type
+5. Use `lesson` when the user describes something that didn't work, a mistake to avoid, or an anti-pattern discovered
+
+## Examples
+
+User: `/remember I prefer functional programming over OOP`
+-> Save as `preference`: "Prefers functional programming over OOP"
+
+User: `/remember working on a React Native app called GhostTube`
+-> Save as `project`: "Working on React Native app called GhostTube"
+
+User: `/remember don't use git reset --hard in this repo, it wipes untracked test fixtures`
+-> Save as `lesson`: "Don't use git reset --hard — it wipes untracked test fixtures"
+
+User: `/remember tried using Redis for caching but latency was worse than in-memory due to serialization overhead`
+-> Save as `lesson`: "Redis caching attempt failed — serialization overhead made it slower than in-memory"
+
+User: `/remember`
+-> Ask: "What would you like me to remember?"

package/commands/status.md

@@ -0,0 +1,90 @@
+---
+description: Check plugin health and diagnose issues
+---
+
+## Your task
+
+The user wants to check the health status of the claude-mneme plugin. Run the health check and report the results clearly.
+
+## How to check status
+
+Run the health check script:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-status.mjs"
+```
+
+To clear the error log:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-status.mjs" --clear-errors
+```
+
+## Understanding the output
+
+The script returns JSON with:
+
+- `overall`: "healthy", "degraded", or "unhealthy"
+- `checks`: Individual check results
+- `errors`: Critical issues that need fixing
+- `warnings`: Non-critical issues to be aware of
+
+### Check Categories
+
+1. **config** - Is the config file valid?
+2. **claudeBinary** - Can we find the claude executable for summarization?
+3. **directories** - Are memory directories writable?
+4. **memoryFiles** - Status of log, summary, remembered items, entities
+5. **errorLog** - Recent errors from the last 24 hours
+6. **sync** - Sync server configuration (if enabled)
+
+## How to respond
+
+Present the results in a clear, actionable format:
+
+### If healthy:
+> **Plugin Status: Healthy** ✓
+>
+> All checks passed. Memory is working correctly.
+>
+> - Log: X entries
+> - Summary: Last updated Y ago
+> - Remembered: Z items
+
+### If degraded:
+> **Plugin Status: Degraded** ⚠️
+>
+> The plugin is working but has warnings:
+> - [list warnings]
+>
+> Recent errors:
+> - [list if any]
+
+### If unhealthy:
+> **Plugin Status: Unhealthy** ✗
+>
+> Critical issues found:
+> - [list errors with fixes]
+>
+> **How to fix:**
+> 1. [specific fix instructions]
+
+## Common issues and fixes
+
+| Issue | Fix |
+|-------|-----|
+| Claude binary not found | Remove `claudePath` from config or set correct path |
+| Directories not writable | Check permissions on `~/.claude-mneme/` |
+| Config parse error | Check JSON syntax in `~/.claude-mneme/config.json` |
+| Log needs summarization | Run `/summarize` to compress the log |
+| Recent errors | Check error details and fix underlying issue |
+
+## Clearing errors
+
+If the user asks to clear the error log:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-status.mjs" --clear-errors
+```
+
+Confirm: "Error log cleared. Future errors will be logged fresh."

package/commands/summarize.md

@@ -0,0 +1,69 @@
+---
+description: Force immediate memory summarization
+---
+
+## Your task
+
+The user wants to manually trigger memory summarization. This compresses older log entries into the structured summary, freeing up space in the activity log.
+
+## When to use this
+
+Summarization normally runs automatically when the log reaches 50 entries. Use `/summarize` to:
+- Force summarization before that threshold
+- Compress the log after a busy session
+- Update the summary with recent work
+
+## How to summarize
+
+First, check what would be summarized with a dry run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-summarize.mjs" --dry-run
+```
+
+This shows:
+- Number of log entries
+- How many would be summarized vs kept
+- Whether a summary already exists
+
+If the user confirms (or didn't ask for dry-run), run the actual summarization:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/mem-summarize.mjs"
+```
+
+## Understanding the output
+
+The script outputs JSON with status:
+
+- `status: "success"` - Summarization completed
+- `status: "empty"` - No log entries to summarize
+- `status: "skipped"` - Not enough entries (minimum 3 required)
+- `status: "locked"` - Another summarization is in progress
+- `status: "error"` - Something went wrong
+
+## What happens during summarization
+
+1. Pending log entries are flushed
+2. Entries are deduplicated (related entries grouped)
+3. Older entries are sent to Haiku for analysis
+4. Summary is updated with new decisions, state, and work
+5. Log is trimmed to keep only recent entries (default: 10)
+
+## Configuration
+
+These settings in `~/.claude-mneme/config.json` affect summarization:
+
+- `keepRecentEntries` (default: 10) - Entries to keep after summarization
+- `model` (default: "haiku") - Model for summarization
+
+## Example responses
+
+After successful summarization:
+> "Summarized 42 entries into the project memory. Kept the 10 most recent entries in the log. The summary now includes [brief description of what was added]."
+
+If nothing to summarize:
+> "The log only has 5 entries, which is below the minimum threshold. Summarization will run automatically when you have more activity, or you can wait until there's more to compress."
+
+If already running:
+> "Summarization is already in progress. Please wait a moment and try again."

package/hooks/hooks.json

@@ -0,0 +1,123 @@
+{
+  "description": "Lightweight memory system hooks",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-start.mjs\"",
+            "timeout": 30
+          }
+        ]
+      },
+      {
+        "matcher": "compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-compact.mjs\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/user-prompt-submit.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      },
+      {
+        "matcher": "TaskCreate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      },
+      {
+        "matcher": "TaskUpdate",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/post-tool-use.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/subagent-stop.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/stop-capture.mjs\"",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/session-stop.mjs\"",
+            "timeout": 120
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pre-compact.mjs\"",
+            "timeout": 120
+          }
+        ]
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "claude-mneme",
+  "version": "2.9.1",
+  "type": "module",
+  "scripts": {
+    "install-deps": "npm install",
+    "test": "node --test scripts/utils.test.mjs"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.31"
+  }
+}

package/scripts/mem-add.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * Add a memory entry to the project's persistent remembered.json
+ * Usage: node mem-add.mjs <type> <content>
+ * Types: fact, project, preference, note
+ *
+ * Unlike log.jsonl entries, remembered items are never summarized away.
+ * Users must manually remove entries they no longer need.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { existsSync } from 'fs';
+import { ensureMemoryDirs, getProjectName, invalidateCache, withFileLock, logError } from './utils.mjs';
+
+const cwd = process.cwd();
+const paths = ensureMemoryDirs(cwd);
+const projectName = getProjectName(cwd);
+
+const VALID_TYPES = ['fact', 'project', 'preference', 'note', 'lesson'];
+
+const args = process.argv.slice(2);
+const type = args[0] || 'note';
+const content = args.slice(1).join(' ');
+
+if (!content) {
+  console.error('Usage: node mem-add.mjs <type> <content>');
+  console.error(`Types: ${VALID_TYPES.join(', ')}`);
+  process.exit(1);
+}
+
+if (!VALID_TYPES.includes(type)) {
+  console.error(`Invalid type "${type}". Must be one of: ${VALID_TYPES.join(', ')}`);
+  process.exit(1);
+}
+
+// Read-modify-write under lock to prevent lost updates from concurrent sessions
+const lockPath = paths.remembered + '.lock';
+withFileLock(lockPath, () => {
+  let entries = [];
+  if (existsSync(paths.remembered)) {
+    try {
+      entries = JSON.parse(readFileSync(paths.remembered, 'utf-8'));
+    } catch (e) {
+      logError(e, 'mem-add:remembered.json');
+      entries = [];
+    }
+  }
+
+  entries.push({
+    ts: new Date().toISOString(),
+    type,
+    content
+  });
+
+  writeFileSync(paths.remembered, JSON.stringify(entries, null, 2) + '\n');
+}, 10);
+
+invalidateCache(cwd);
+console.log(`Remembered for "${projectName}": [${type}] ${content}`);

package/scripts/mem-entity.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Entity Query Script
+ * Queries the entity index to find information about files, functions, errors, packages.
+ *
+ * Usage:
+ *   node mem-entity.mjs [options] [query]
+ *
+ * Options:
+ *   --list              List all entities
+ *   --category <cat>    Filter by category (files, functions, errors, packages)
+ *   <query>             Search for entities matching this name
+ */
+
+import { loadEntityIndex, ensureMemoryDirs, getProjectName } from './utils.mjs';
+
+const args = process.argv.slice(2);
+const cwd = process.cwd();
+const projectName = getProjectName(cwd);
+
+// Parse arguments
+let listMode = false;
+let category = null;
+let query = null;
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i];
+  if (arg === '--list') {
+    listMode = true;
+  } else if (arg === '--category' && args[i + 1]) {
+    category = args[++i];
+  } else if (!arg.startsWith('--')) {
+    query = arg;
+  }
+}
+
+// Load entity index
+const index = loadEntityIndex(cwd);
+
+// Check if index has any data
+const hasData = index.files && (
+  Object.keys(index.files).length > 0 ||
+  Object.keys(index.functions || {}).length > 0 ||
+  Object.keys(index.errors || {}).length > 0 ||
+  Object.keys(index.packages || {}).length > 0
+);
+
+if (!hasData) {
+  console.log(JSON.stringify({
+    project: projectName,
+    status: 'empty',
+    message: 'No entities indexed yet. Entities are extracted from log entries as you work.'
+  }));
+  process.exit(0);
+}
+
+// List mode - show all entities
+if (listMode) {
+  const result = {
+    project: projectName,
+    status: 'ok',
+    categories: {}
+  };
+
+  const categories = category ? [category] : ['files', 'functions', 'errors', 'packages'];
+
+  for (const cat of categories) {
+    if (!index[cat]) continue;
+
+    const entities = Object.entries(index[cat])
+      .map(([name, data]) => ({
+        name,
+        mentions: data.mentions,
+        lastSeen: data.lastSeen
+      }))
+      .sort((a, b) => b.mentions - a.mentions);
+
+    if (entities.length > 0) {
+      result.categories[cat] = entities;
+    }
+  }
+
+  console.log(JSON.stringify(result, null, 2));
+  process.exit(0);
+}
+
+// Query mode - search for matching entities
+if (query) {
+  const queryLower = query.toLowerCase();
+  const matches = [];
+
+  const categories = category ? [category] : ['files', 'functions', 'errors', 'packages'];
+
+  for (const cat of categories) {
+    if (!index[cat]) continue;
+
+    for (const [name, data] of Object.entries(index[cat])) {
+      // Match if name contains query (case-insensitive)
+      if (name.toLowerCase().includes(queryLower)) {
+        matches.push({
+          name,
+          category: cat,
+          mentions: data.mentions,
+          lastSeen: data.lastSeen,
+          contexts: data.contexts || []
+        });
+      }
+    }
+  }
+
+  // Sort by relevance: exact match first, then by mentions
+  matches.sort((a, b) => {
+    const aExact = a.name.toLowerCase() === queryLower ? 1 : 0;
+    const bExact = b.name.toLowerCase() === queryLower ? 1 : 0;
+    if (aExact !== bExact) return bExact - aExact;
+    return b.mentions - a.mentions;
+  });
+
+  console.log(JSON.stringify({
+    project: projectName,
+    query,
+    status: matches.length > 0 ? 'ok' : 'not_found',
+    matches: matches.slice(0, 20) // Limit to top 20
+  }, null, 2));
+  process.exit(0);
+}
+
+// No query and not list mode - show summary
+const summary = {
+  project: projectName,
+  status: 'ok',
+  lastUpdated: index.lastUpdated,
+  counts: {
+    files: Object.keys(index.files || {}).length,
+    functions: Object.keys(index.functions || {}).length,
+    errors: Object.keys(index.errors || {}).length,
+    packages: Object.keys(index.packages || {}).length
+  },
+  hint: 'Use --list to see all entities, or provide a query to search.'
+};
+
+console.log(JSON.stringify(summary, null, 2));
+process.exit(0);