claude_memory 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1483a3663c9c589abad58f80c71d772c592f13727d3fd1339418c2ba1a3db875
-  data.tar.gz: 34beebdf5e3cc8a70d383757ffaf7e21fde0724f963532e2d2548ec2e63ba329
+  metadata.gz: b6df0a3f58a88c1bbec82ec20e26789d51ad2712408d058337a196c5eac90654
+  data.tar.gz: beb9c2ef59ef6a45430eeb03466e37f6b1f741ef1745b5303a1443b02a7c84b4
 SHA512:
-  metadata.gz: 514022df68751e4421942d914c003a1e104a5c2b5ab4a639619ca05bb4d6bafd722d87009dc898a5b578f1b7efdae50df68b5b8232e1cf42a8bb5e88a06e66c3
-  data.tar.gz: 68c5a36361d3048e4c92bba7127e7fa0bc9ff09f6de3779ae59f7799cd4152d63030386ea2b124a90b345063545028b0da0401c9144f284c7e34290b2d674ba7
+  metadata.gz: '06905bca1f77df5642caf0846cde7394ba9a1baf3c954138383ac39927fcaae2ef097ff79dd3c866e6930fa0eac0d0fb958366bded54a0616d8e356a316e616c'
+  data.tar.gz: 9a8e3c455c20ae616bc239b766e1d4e2aa4c6e5448f494294d9c6a646a8a613428e9b63218624c5cae7e30f389704dd3bee6b788e97a369cb719b115abffddd7

data/.claude/rules/claude_memory.generated.md

@@ -1,21 +1,113 @@
-<!-- 
+<!--
   This file is auto-generated by claude-memory.
   Do not edit manually - changes will be overwritten.
-  Generated: 2026-02-05T18:27:44Z
+  Generated: 2026-04-16T17:54:51Z
 -->
 
 # Project Memory
 
 ## Current Decisions
 
+- MCP tool-call telemetry stores minimal columns (tool_name, duration_ms, result_count, scope, error_class) — deliberately no query_text or query_hash. YAGNI: hashes are write-only without the raw text, and raw text adds privacy concerns without clear value beyond existing shortcut tools (memory.decisions, memory.conventions).
 - From QMD 2026-02-02 restudy: adopt Claude Code plugin format, MCP structured content pattern, MCP query guide prompt, inline status checks. Carry forward sqlite-vec, RRF, docids, smart expansion from 2026-01-26. Reject custom fine-tuned models, LLM reranking, YAML collections.
 - From claude-supermemory study: adopt SessionStart hook context injection (hookSpecificOutput.additionalContext), tool-specific observation compression, and relative time formatting. Reject cloud storage dependency and no-test approach.
 
 ## Conventions
 
+- Curated predicate vocabulary has 8 entries: multi-value (convention, decision, architecture, uses_framework, uses_language) and single-value (uses_database, deployment_platform, auth_method). Pruned 7 dead predicates after multi-project survey confirmed zero usage.
+- Before making design changes to schemas, vocabularies, or policies, survey actual usage data across multiple project databases under ~/src/ — single-project analysis can validate wrong assumptions. The uses_framework cardinality bug was only visible across multi-project data.
+- A/B testing memory plugin: use 'claude --bare --mcp-config=/tmp/mcp-test.json -p' with serve-mcp.sh path. --plugin-dir doesn't work with --bare despite docs claiming it should. Architecture/convention/preference questions differentiate best; grep-able and one-shot code-gen questions don't.
+- NullDistiller emits uses_language for language-type entities (added 0.9.0), alongside existing uses_database, uses_framework, deployment_platform. Migration v14 canonicalizes stale predicate names (has_convention → convention, primary_language → uses_language) in existing facts.
+- CLAUDE.md scope-system example text ('this app uses PostgreSQL') causes recurring distiller hallucinations. Reject + re-ingest creates rejection churn because rejection metadata doesn't block re-insertion at content level. Open product gap — workaround: wrap example text in <no-memory> tags.
+- claude-memory restore --predicate NAME recovers facts superseded by obsolete single-value classifications. Uses Jaccard token overlap (threshold 0.5) to distinguish bug-caused supersession from real corrections. Only operates on predicates currently classified multi-value. Opt-in per DB, supports --dry-run.
+- claude-memory reject <id_or_docid> marks facts as rejected and resolves associated open conflicts in a single transaction. Accepts integer fact IDs or 8-char hex docids. memory.reject_fact MCP tool mirrors the CLI.
+- The /release skill automates gem releases in three phases: prepare (version bump across 3 files, bundle install, MCP verify, tests, lint, CHANGELOG check, commit), publish (user-driven: git push + rake release), announce (fix GitHub Latest flags, create gh release from CHANGELOG). Never auto-pushes.
+- Never use Sequel.sqlite for DB reads; this gem only depends on extralite. Use Sequel.connect("extralite://#{db_path}") or SQLiteStore.new. Sequel.sqlite requires the ungem'd sqlite3 adapter and fails at runtime.
+- Two distinct tool_calls tables exist: tool_calls (v3) for transcript-observed Claude Code tool usage, and mcp_tool_calls (v13) for MCP server telemetry. Disjoint purposes, never join.
+- MCP tool-call telemetry is recorded via MCP::Telemetry wrapping Server#handle_tools_call. Writes to mcp_tool_calls table in the project DB. Swallows DB errors so telemetry never breaks a real tool response. Viewable via 'claude-memory stats --tools [--since DAYS]'.
+- mcp_tool_calls retention is 90 days, enforced by Sweep::Maintenance#prune_old_mcp_tool_calls wired into Sweeper#run!. Configurable via mcp_tool_call_retention_days in Maintenance DEFAULT_CONFIG.
+- CLAUDE_CONFIG_DIR env var overrides the default ~/.claude location for Configuration#global_db_path. Access via Configuration#claude_config_dir. Additive, backwards compatible.
+- Registry::COMMANDS stores {class:, description:} entries as the single source of truth for command name, class reference, and shell-completion description. Class constants stored directly (no const_get). Registry.descriptions feeds CompletionCommand; adding a new command requires updating only this hash.
+- Prefer do...end over braces when a block has repeated argument names, multiple expressions, or non-trivial body. Single-expression simple blocks can still use braces.
+- EXPECTED_HOOKS constant must stay in sync with events in HooksConfigurator#build_hooks_config. Adding a new hook event without updating EXPECTED_HOOKS causes false doctor warnings.
+- Tests using --db for hook context only set the project DB path. StoreManager still connects to the real global DB. Must stub Configuration to return a temp global path for isolation.
+- Version must be updated in three places: lib/claude_memory/version.rb, .claude-plugin/plugin.json, .claude-plugin/marketplace.json. Runtime code uses ClaudeMemory::VERSION dynamically.
+- Use module inclusion (not class extraction) to break up god objects — preserves public API so zero tests need modification
+- Configuration class has instance methods only — use Configuration.new.global_db_path, not Configuration.global_db_path. Stub with instance_double + allow(Configuration).to receive(:new).and_return(config)
+- OperationTracker.reset_stuck_operations only resets operations older than 24 hours (STALE_THRESHOLD_SECONDS). Tests must backdate started_at to trigger resets.
+- SCHEMA_VERSION constant lives in Store::SchemaManager module but is accessible as SQLiteStore::SCHEMA_VERSION via Ruby include-based constant lookup
 - MCP tools return dual content (text summary) + structuredContent (JSON) via TextSummary module and Server#handle_tools_call. Compact mode (compact: true) omits receipts for ~60% smaller responses.
 - ContentSanitizer strips system-reminder, local-command-caveat, command-message, command-name, command-args tags in addition to private/no-memory/secret/claude-memory-context.
 - Core::RelativeTime module provides progressive time formatting: just now → Xm ago → Xh ago → Xd ago → YYYY-MM-DD. Used in ResponseFormatter for *_ago fields.
 - MCP server registers memory_guide prompt via prompts/list and prompts/get endpoints. QueryGuide module holds prompt content.
 - Claude Code plugin with marketplace.json, skill definitions, MCP server bundling. 5,700+ stars, by Tobi Lütke. Custom fine-tuned query expansion (Qwen3-1.7B, SFT+GRPO). Dual content/structuredContent MCP pattern.
 - Cloud-backed Claude Code plugin (~1,195 LOC JavaScript) using Supermemory API for persistent memory across sessions. Uses hooks for SessionStart context injection and Stop transcript capture. No local database.
+
+## Technical Constraints
+
+- **Uses framework**: rails
+- **Deployment platform**: aws
+- **Uses database**: sqlite
+
+## Additional Knowledge
+
+### Architecture
+
+- repo: PredicatePolicy is the single source of truth for predicate vocabulary (POLICIES), cardinality, snapshot section mapping (SECTION_MAP), synonym canonicalization (SYNONYMS), and LLM guidance. tool_definitions.rb, publish.rb, and distill-transcripts.md all derive from PredicatePolicy. Never hardcode predicate names elsewhere.
+- MCP::Tools: Thin 104-line dispatcher that includes 6 handler modules in mcp/handlers/: QueryHandlers, ShortcutHandlers, ContextHandlers, ManagementHandlers, StatsHandlers, SetupHandlers
+- Recall: 94-line facade delegating to @engine (DualEngine or LegacyEngine), both include shared QueryCore module with all store-level query logic
+- SQLiteStore: 386-line CRUD class that includes RetryHandler (retry/connection logic) and SchemaManager (migrations/version sync) modules
+- Embeddings: Pluggable providers via Embeddings.resolve(name, env:). Three providers: tfidf (default), fastembed, api. Duck-typed contract: name, dimensions, generate(text). ENV: CLAUDE_MEMORY_EMBEDDING_PROVIDER
+- Embeddings::DimensionCheck: Pure value object — DimensionCheck.call(store, provider) returns Data.define Result with :fresh/:match/:mismatch status. No side effects; caller decides how to handle mismatch.
+
+
+## Open Conflicts
+
+The following facts are in conflict and need resolution:
+
+- Conflict #12: Fact 21 vs Fact 43
+- Conflict #13: Fact 21 vs Fact 44
+- Conflict #14: Fact 45 vs Fact 46
+- Conflict #15: Fact 45 vs Fact 47
+- Conflict #16: Fact 48 vs Fact 49
+- Conflict #17: Fact 45 vs Fact 50
+- Conflict #18: Fact 21 vs Fact 51
+- Conflict #19: Fact 48 vs Fact 52
+- Conflict #20: Fact 21 vs Fact 53
+- Conflict #21: Fact 21 vs Fact 54
+- Conflict #22: Fact 21 vs Fact 55
+- Conflict #23: Fact 21 vs Fact 56
+- Conflict #24: Fact 21 vs Fact 57
+- Conflict #25: Fact 48 vs Fact 58
+- Conflict #26: Fact 48 vs Fact 59
+- Conflict #27: Fact 48 vs Fact 60
+- Conflict #28: Fact 21 vs Fact 61
+- Conflict #29: Fact 21 vs Fact 62
+- Conflict #30: Fact 21 vs Fact 63
+- Conflict #31: Fact 45 vs Fact 64
+- Conflict #32: Fact 21 vs Fact 65
+- Conflict #33: Fact 21 vs Fact 66
+- Conflict #34: Fact 21 vs Fact 67
+- Conflict #35: Fact 45 vs Fact 68
+- Conflict #36: Fact 45 vs Fact 69
+- Conflict #37: Fact 48 vs Fact 70
+- Conflict #38: Fact 48 vs Fact 71
+- Conflict #39: Fact 21 vs Fact 72
+- Conflict #40: Fact 21 vs Fact 73
+- Conflict #41: Fact 21 vs Fact 74
+- Conflict #42: Fact 21 vs Fact 75
+- Conflict #43: Fact 21 vs Fact 76
+- Conflict #44: Fact 45 vs Fact 77
+- Conflict #45: Fact 45 vs Fact 78
+- Conflict #46: Fact 45 vs Fact 79
+- Conflict #47: Fact 45 vs Fact 80
+- Conflict #48: Fact 45 vs Fact 81
+- Conflict #49: Fact 48 vs Fact 82
+- Conflict #50: Fact 48 vs Fact 83
+- Conflict #51: Fact 48 vs Fact 84
+- Conflict #52: Fact 48 vs Fact 85
+- Conflict #53: Fact 48 vs Fact 86
+- Conflict #54: Fact 48 vs Fact 87
+- Conflict #55: Fact 48 vs Fact 88
+- Conflict #56: Fact 48 vs Fact 89
+- Conflict #57: Fact 48 vs Fact 90

data/.claude/settings.json

@@ -5,17 +5,21 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 5
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 5,
+            "statusMessage": "Saving memory..."
           }
         ]
-      },
+      }
+    ],
+    "StopFailure": [
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 5
+            "timeout": 5,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -26,87 +30,56 @@
           {
             "type": "command",
             "command": "claude-memory hook context",
-            "timeout": 5
+            "timeout": 5,
+            "statusMessage": "Loading memory..."
           }
         ]
       }
     ],
     "PreCompact": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep",
-            "timeout": 30
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
     ],
     "SessionEnd": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 30
-          },
-          {
-            "type": "command",
-            "command": "claude-memory hook sweep",
-            "timeout": 30
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Saving memory..."
           },
           {
             "type": "command",
             "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 30
+            "timeout": 30,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }
     ],
     "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 10
-          }
-        ]
-      },
       {
         "hooks": [
           {
             "type": "command",
             "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 10
+            "timeout": 10,
+            "statusMessage": "Saving memory..."
           }
         ]
       }
@@ -116,17 +89,22 @@
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest",
-            "timeout": 15
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 15,
+            "statusMessage": "Saving memory..."
           }
         ]
-      },
+      }
+    ],
+    "Notification": [
       {
+        "matcher": "idle_prompt",
         "hooks": [
           {
             "type": "command",
-            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
-            "timeout": 15
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 10,
+            "statusMessage": "Sweeping memory..."
           }
         ]
       }

data/.claude/settings.local.json

@@ -48,7 +48,9 @@
       "Bash(claude-memory search:*)",
       "Bash(bundle exec:*)",
       "Skill(improve)",
-      "Skill(improve:*)"
+      "Skill(improve:*)",
+      "WebFetch(domain:arxiv.org)",
+      "mcp__memory__memory_conflicts"
     ]
   },
   "enableAllProjectMcpServers": true,

data/.claude/skills/release/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: release
+description: Prepare and publish a new gem release — bumps version across all required files, validates tests/linting/MCP server, commits, and creates the GitHub release. Use this skill when the user says "release", "publish a new version", "bump the version", "cut a release", "prepare for release", "ship it", or any variation of wanting to publish a new gem version. Also use when the user asks about the release process or what steps are needed to release.
+agent: general-purpose
+allowed-tools: Read, Grep, Edit, Write, Bash
+arguments:
+  - name: version
+    description: "The new version number (e.g., '0.10.0'). If omitted, you'll be asked."
+    required: false
+---
+
+# Release Workflow
+
+Automate the full release lifecycle for the ClaudeMemory gem. This workflow was codified from the actual 0.9.0 release process.
+
+The release has three phases: **prepare** (automated), **publish** (user-driven), and **announce** (automated). The middle phase requires user action because it pushes to a shared remote and publishes to RubyGems — destructive operations that must never happen without explicit confirmation.
+
+## Phase 1: Prepare
+
+### Step 1: Determine the new version
+
+If a version was passed as an argument, use it. Otherwise, read the current version from `lib/claude_memory/version.rb` and ask the user what the new version should be.
+
+### Step 2: Find and update all version references
+
+The version lives in exactly three files. Grep to confirm there are no others:
+
+```bash
+grep -rn "CURRENT_VERSION" --include="*.rb" --include="*.json" --include="*.gemspec" . | grep -v "CHANGELOG\|node_modules\|vendor\|\.git/"
+```
+
+Update all three:
+
+1. **`lib/claude_memory/version.rb`** — the `VERSION` constant (canonical source)
+2. **`.claude-plugin/plugin.json`** — the `"version"` field
+3. **`.claude-plugin/marketplace.json`** — the `"version"` field inside the plugins array
+
+If grep reveals any additional hardcoded references, update those too and flag them to the user as something that should be DRYed up.
+
+### Step 3: Update Gemfile.lock
+
+```bash
+bundle install
+```
+
+Verify both `claude_memory (X.Y.Z)` entries in Gemfile.lock match the new version.
+
+### Step 4: Verify MCP server reports the new version
+
+The MCP server reads `ClaudeMemory::VERSION` dynamically. Confirm it picks up the change:
+
+```bash
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | bundle exec claude-memory serve-mcp 2>/dev/null | grep -o '"version":"[^"]*"'
+```
+
+Expected output: `"version":"X.Y.Z"` matching the new version. If it doesn't match, something is wrong with the require chain — investigate before proceeding.
+
+### Step 5: Run the full test suite
+
+```bash
+bundle exec rspec
+```
+
+All tests must pass. Do not proceed with any failures. Fix them first.
+
+### Step 6: Run the linter
+
+```bash
+bundle exec rake standard:fix
+```
+
+Ensure no remaining violations.
+
+### Step 7: Verify CHANGELOG.md
+
+The CHANGELOG should already have a release section written during development (via `/improve`, manual commits, or other workflow). **Do not auto-generate release notes** — they should reflect the actual development narrative.
+
+Check that:
+- The `## [X.Y.Z] - YYYY-MM-DD` section exists with today's date
+- It has Added, Changed, Fixed subsections as appropriate
+- Upgrade Notes are included if there are breaking changes or manual migration steps
+- The `## [Unreleased]` section above it is empty or ready for the next cycle
+
+If the CHANGELOG section is missing or incomplete, **stop and ask the user**. Do not fabricate release notes.
+
+### Step 8: Commit the version bump
+
+```bash
+git add lib/claude_memory/version.rb .claude-plugin/plugin.json .claude-plugin/marketplace.json Gemfile.lock
+git commit -m "[Release] Bump version to X.Y.Z"
+```
+
+Do NOT push yet. Report what was committed and proceed to Phase 2.
+
+## Phase 2: Publish (User-Driven)
+
+This phase involves pushing to a shared remote and publishing to RubyGems. These are **irreversible shared-state operations** — never execute them automatically.
+
+Tell the user:
+
+> Version X.Y.Z is prepared and committed locally. To publish:
+>
+> ```bash
+> git push origin main
+> rake release
+> ```
+>
+> `rake release` will create the git tag, build the gem, and push to RubyGems. Let me know when that's done and I'll create the GitHub release.
+
+Wait for the user to confirm before proceeding to Phase 3.
+
+## Phase 3: Announce
+
+### Step 9: Fix any stale "Latest" flags on GitHub releases
+
+Check current release state:
+
+```bash
+gh release list --limit 5
+```
+
+If an older release is incorrectly marked "Latest" (this happens when releases are created out of order or with `--latest` set manually):
+
+```bash
+gh release edit v<old-version> --latest=false
+```
+
+### Step 10: Create the GitHub release
+
+Extract the release notes from CHANGELOG.md — everything between `## [X.Y.Z]` and the next `## [` heading. Write to a temp file:
+
+```bash
+# Extract the section between the new version header and the next version header
+sed -n '/^## \[X\.Y\.Z\]/,/^## \[/{ /^## \[X\.Y\.Z\]/d; /^## \[/d; p; }' CHANGELOG.md > /tmp/release-notes.md
+```
+
+Create the release:
+
+```bash
+gh release create vX.Y.Z \
+  --title "vX.Y.Z — Short descriptive title" \
+  --latest \
+  --verify-tag \
+  --notes-file /tmp/release-notes.md
+```
+
+The title should capture the theme of the release in a few words (e.g., "Predicate Design Overhaul, Reject/Restore, Telemetry"). Read the CHANGELOG to derive this — don't ask the user unless the theme isn't obvious.
+
+### Step 11: Verify the release
+
+```bash
+gh release list --limit 5
+```
+
+Confirm:
+- The new release appears at the top
+- It's marked "Latest"
+- No older release is incorrectly marked "Latest"
+
+Report the release URL to the user.
+
+## Error Handling
+
+- **Tests fail**: Fix first. Never release with failing tests.
+- **CHANGELOG missing**: Ask the user. Never fabricate release notes.
+- **Version already tagged**: The tag may exist from a prior attempt. Ask the user whether to delete and recreate, or use a different version.
+- **`gh` not available**: Tell the user to create the GitHub release manually, providing the release notes content.
+- **`rake release` fails**: Common causes: not logged into RubyGems, tag already exists, uncommitted changes. Help the user diagnose but don't retry automatically.

data/.claude/skills/upgrade-dependencies/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: upgrade-dependencies
+description: "Upgrade all Ruby gem dependencies to their latest versions with release note review and codebase alignment checks. Use this skill whenever the user asks to update, upgrade, or bump dependencies, gems, or packages — even casually like 'update my gems' or 'are my deps up to date?'"
+agent: general-purpose
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write, Agent, WebFetch
+---
+
+# Dependency Upgrade Skill
+
+Systematically upgrade Ruby gem dependencies by researching latest versions, reviewing release notes for breaking changes, updating version constraints, verifying with tests, and confirming codebase alignment.
+
+The goal is a *thoughtful* upgrade — not blindly bumping versions, but understanding what changed and ensuring the codebase is compatible. This matters because a silent API change can introduce bugs that tests don't catch if the tests don't exercise the affected code path.
+
+## Process Overview
+
+1. **Discover** current dependencies and their constraints
+2. **Research** latest versions and release notes (in parallel)
+3. **Analyze** breaking changes and codebase impact
+4. **Upgrade** version constraints and install
+5. **Verify** with the full test suite
+6. **Report** a summary table with upgrade details
+
+## Step 1: Discover Current Dependencies
+
+Read the gemspec and Gemfile to build a complete dependency inventory.
+
+```
+Read *.gemspec        → runtime dependencies (add_dependency)
+Read Gemfile          → development dependencies (gem declarations)
+Run: bundle outdated  → current vs latest versions, which are constrained
+```
+
+Build a working list with these columns:
+- **Gem name**
+- **Source** (gemspec or Gemfile)
+- **Current constraint** (e.g., `~> 5.0`)
+- **Installed version** (from `bundle outdated` or `Gemfile.lock`)
+- **Latest version** (from `bundle outdated`)
+- **Constrained?** (is the version constraint preventing upgrade?)
+
+## Step 2: Research Release Notes
+
+For each gem that has a newer version available, research what changed. Launch these as parallel Agent subagents — one per gem — to avoid sequential delays.
+
+Each research agent should:
+
+1. Run `gem search <name> --exact --versions` to confirm the latest version
+2. Fetch the changelog or release notes from GitHub (check CHANGELOG.md, CHANGES, HISTORY.md, or GitHub Releases)
+3. Summarize changes between the installed version and latest version
+4. Flag any **breaking changes**, **deprecations**, or **API changes**
+5. Note if it's a **major version bump** (higher risk)
+
+For transitive dependencies (not directly declared but showing in `bundle outdated`), research is optional — focus on direct dependencies. Transitive deps are upgraded automatically when their parent gem allows it.
+
+### What to look for in release notes
+
+- **Removed methods or classes** the codebase might use
+- **Renamed options or changed defaults** that could silently alter behavior
+- **New required arguments** to methods we call
+- **Deprecated features** we rely on (working now, but will break later)
+- **Changed return types** or data structures
+- **Minimum Ruby version bumps** that could affect CI or deployment
+
+## Step 3: Analyze Codebase Impact
+
+For each gem with breaking changes or API modifications:
+
+1. **Grep the codebase** for usage of affected APIs
+2. **Check test coverage** — are the affected code paths tested?
+3. **Determine if changes are needed** before or after the upgrade
+
+Classify each upgrade:
+
+- **Safe** — no breaking changes, or breaking changes don't affect our usage
+- **Needs code changes** — our code uses a deprecated or removed API
+- **Held back** — a transitive dependency constraint prevents the upgrade (explain which parent gem and why)
+
+If code changes are needed, make them *before* bumping the version constraint so the upgrade commit is clean.
+
+## Step 4: Upgrade Dependencies
+
+### Gemspec dependencies (runtime)
+
+Update version constraints to target the latest version. Use `~>` with the appropriate precision:
+
+- For stable gems (1.0+): `~> X.Y` allows patch updates (e.g., `~> 5.102` allows 5.102.x)
+- For pre-1.0 gems: `~> 0.X, ">= 0.X.Y"` to pin a minimum while allowing patches
+- For gems where a specific fix matters: add `">= X.Y.Z"` as an additional constraint
+
+### Gemfile dependencies (development)
+
+Same approach. If a major version bump is available (e.g., lefthook 1.x → 2.x), check the migration guide before bumping.
+
+### Install
+
+```bash
+bundle update
+```
+
+If `bundle update` fails due to dependency conflicts, resolve them. Common strategies:
+- Relax an overly tight constraint
+- Update the conflicting parent gem first
+- Accept that a gem can't be upgraded yet and document why
+
+## Step 5: Verify with Tests
+
+Run the full test suite:
+
+```bash
+bundle exec rspec
+```
+
+Also run the linter to catch any style issues:
+
+```bash
+bundle exec rake standard
+```
+
+If tests fail:
+1. Read the failure carefully — is it caused by the upgrade or pre-existing?
+2. If caused by the upgrade, fix the code to work with the new version
+3. If unfixable, revert that specific gem's upgrade and note it in the report
+
+## Step 6: Present Summary
+
+Present a clear summary table of all changes:
+
+```markdown
+| Gem | Old Version | New Version | Old Constraint | New Constraint | Notes |
+|-----|------------|-------------|----------------|----------------|-------|
+| sequel | 5.100.0 | 5.102.0 | ~> 5.0 | ~> 5.102 | No breaking changes |
+| lefthook | 1.13.6 | 2.1.4 | ~> 1.6 | ~> 2.1 | Major version bump, reviewed migration guide |
+```
+
+Follow the table with:
+
+1. **Breaking changes found** — what changed and how the codebase was updated
+2. **Gems held back** — which gems couldn't be upgraded and why (e.g., "diff-lcs 2.0 held back by rspec's ~> 1.4 constraint")
+3. **Notable new features** — anything worth adopting from the new versions
+4. **Test results** — confirmation that all tests pass
+
+## Edge Cases
+
+### Gems with no GitHub repository
+Fall back to `gem info <name>` and the RubyGems page for release history. Note reduced confidence in the review.
+
+### Yanked versions
+If `bundle update` fails because a version was yanked, try the next most recent version.
+
+### Pre-release versions
+Do not upgrade to pre-release or alpha versions unless the user explicitly asks. Stick to stable releases.
+
+### Monorepo gems
+Some gems (like rails components) are versioned together. Upgrade them as a group.

data/.claude-plugin/marketplace.json

@@ -7,9 +7,9 @@
   "plugins": [
     {
       "name": "claude-memory",
-      "version": "0.8.0",
+      "version": "0.9.1",
       "source": "./",
-      "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+      "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
       "repository": "https://github.com/codenamev/claude_memory"
     }
   ]

data/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "claude-memory",
-  "version": "0.8.0",
-  "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+  "version": "0.9.1",
+  "description": "Long-term memory for Claude Code. Recalls architecture, conventions, and decisions across sessions — so Claude explains your codebase without file traversal, follows your patterns, and never re-asks what it already learned.",
   "author": {
     "name": "Valentino Stoll",
     "email": "v@codenamev.com"
@@ -9,7 +9,7 @@
   "homepage": "https://github.com/codenamev/claude_memory",
   "repository": "https://github.com/codenamev/claude_memory",
   "license": "MIT",
-  "keywords": ["memory", "facts", "knowledge", "persistence", "long-term-memory"],
+  "keywords": ["memory", "architecture", "conventions", "decisions", "recall", "preferences", "long-term-memory"],
   "mcpServers": {
     "memory": {
       "command": "${CLAUDE_PLUGIN_ROOT}/scripts/serve-mcp.sh",

data/.claude-plugin/scripts/hook-runner.sh

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# Generic hook delegate for claude-memory.
+# Used by the Claude Code plugin to run hook subcommands.
+# Usage: hook-runner.sh <subcommand> [args...]
+# Exit 0 on missing binary to avoid blocking Claude Code.
+
+set -uo pipefail
+
+if command -v claude-memory > /dev/null 2>&1; then
+  exec claude-memory hook "$@"
+else
+  echo "claude-memory gem not found. Install with: gem install claude_memory" >&2
+  exit 0
+fi