claude_memory 0.7.1 → 0.9.0

data/lib/claude_memory/commands/initializers/global_initializer.rb

@@ -65,6 +65,7 @@ module ClaudeMemory
             @skip_hooks = true
           else
             @stdout.puts "\nUpdating hooks..."
+            @replace_hooks = true
           end
         end
 
@@ -73,7 +74,7 @@ module ClaudeMemory
         end
 
         def configure_hooks
-          HooksConfigurator.new(@stdout).configure_global_hooks
+          HooksConfigurator.new(@stdout).configure_global_hooks(replace: @replace_hooks || false)
         end
 
         def configure_mcp

data/lib/claude_memory/commands/initializers/hooks_configurator.rb

@@ -12,7 +12,7 @@ module ClaudeMemory
           @stdout = stdout
         end
 
-        def configure_project_hooks
+        def configure_project_hooks(replace: false)
           settings_path = ".claude/settings.json"
           FileUtils.mkdir_p(File.dirname(settings_path))
 
@@ -24,13 +24,13 @@ module ClaudeMemory
 
           existing = load_json_file(settings_path)
           existing["hooks"] ||= {}
-          merge_hooks!(existing["hooks"], hooks_config["hooks"])
+          merge_hooks!(existing["hooks"], hooks_config["hooks"], replace: replace)
 
           File.write(settings_path, JSON.pretty_generate(existing))
           @stdout.puts "✓ Configured hooks in #{settings_path}"
         end
 
-        def configure_global_hooks
+        def configure_global_hooks(replace: false)
           settings_path = File.join(Dir.home, ".claude", "settings.json")
           FileUtils.mkdir_p(File.dirname(settings_path))
 
@@ -42,7 +42,7 @@ module ClaudeMemory
 
           existing = load_json_file(settings_path)
           existing["hooks"] ||= {}
-          merge_hooks!(existing["hooks"], hooks_config["hooks"])
+          merge_hooks!(existing["hooks"], hooks_config["hooks"], replace: replace)
 
           File.write(settings_path, JSON.pretty_generate(existing))
           @stdout.puts "✓ Configured hooks in #{settings_path}"
@@ -97,28 +97,61 @@ module ClaudeMemory
         private
 
         def build_hooks_config(ingest_cmd, sweep_cmd)
+          context_cmd = "claude-memory hook context"
+
           {
             "hooks" => {
               "Stop" => [{
                 "hooks" => [
-                  {"type" => "command", "command" => ingest_cmd, "timeout" => 10}
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 5,
+                   "statusMessage" => "Saving memory..."}
+                ]
+              }],
+              "StopFailure" => [{
+                "hooks" => [
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 5,
+                   "statusMessage" => "Saving memory..."}
                 ]
               }],
               "SessionStart" => [{
                 "hooks" => [
-                  {"type" => "command", "command" => ingest_cmd, "timeout" => 10}
+                  {"type" => "command", "command" => context_cmd, "timeout" => 5,
+                   "statusMessage" => "Loading memory..."}
                 ]
               }],
               "PreCompact" => [{
                 "hooks" => [
-                  {"type" => "command", "command" => ingest_cmd, "timeout" => 30},
-                  {"type" => "command", "command" => sweep_cmd, "timeout" => 30}
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 30,
+                   "statusMessage" => "Saving memory..."},
+                  {"type" => "command", "command" => sweep_cmd, "timeout" => 30,
+                   "statusMessage" => "Sweeping memory..."}
                 ]
               }],
               "SessionEnd" => [{
                 "hooks" => [
-                  {"type" => "command", "command" => ingest_cmd, "timeout" => 30},
-                  {"type" => "command", "command" => sweep_cmd, "timeout" => 30}
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 30,
+                   "statusMessage" => "Saving memory..."},
+                  {"type" => "command", "command" => sweep_cmd, "timeout" => 30,
+                   "statusMessage" => "Sweeping memory..."}
+                ]
+              }],
+              "TaskCompleted" => [{
+                "hooks" => [
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 10,
+                   "statusMessage" => "Saving memory..."}
+                ]
+              }],
+              "TeammateIdle" => [{
+                "hooks" => [
+                  {"type" => "command", "command" => ingest_cmd, "timeout" => 15,
+                   "statusMessage" => "Saving memory..."}
+                ]
+              }],
+              "Notification" => [{
+                "matcher" => "idle_prompt",
+                "hooks" => [
+                  {"type" => "command", "command" => sweep_cmd, "timeout" => 10,
+                   "statusMessage" => "Sweeping memory..."}
                 ]
               }]
             }
@@ -132,7 +165,18 @@ module ClaudeMemory
           {}
         end
 
-        def merge_hooks!(existing_hooks, new_hooks)
+        def merge_hooks!(existing_hooks, new_hooks, replace: false)
+          if replace
+            # Remove all claude-memory hooks first, then add fresh ones
+            existing_hooks.each do |event, hook_arrays|
+              next unless hook_arrays.is_a?(Array)
+              hook_arrays.reject! do |ha|
+                ha.is_a?(Hash) && ha["hooks"]&.any? { |h| h["command"]&.include?("claude-memory") }
+              end
+            end
+            existing_hooks.delete_if { |_, v| v.is_a?(Array) && v.empty? }
+          end
+
           new_hooks.each do |event, hook_arrays|
             existing_hooks[event] ||= []
 

data/lib/claude_memory/commands/initializers/project_initializer.rb

@@ -68,6 +68,7 @@ module ClaudeMemory
             @skip_hooks = true
           else
             @stdout.puts "\nUpdating hooks..."
+            @replace_hooks = true
           end
         end
 
@@ -81,7 +82,7 @@ module ClaudeMemory
         end
 
         def configure_hooks
-          HooksConfigurator.new(@stdout).configure_project_hooks
+          HooksConfigurator.new(@stdout).configure_project_hooks(replace: @replace_hooks || false)
         end
 
         def configure_mcp

data/lib/claude_memory/commands/install_skill_command.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Commands
+    # Installs embedded skill files (agent definitions) to ~/.claude/commands/
+    # for use as Claude Code slash commands.
+    class InstallSkillCommand < BaseCommand
+      SKILLS_DIR = File.expand_path("../skills", __FILE__)
+
+      AVAILABLE_SKILLS = {
+        "memory-recall" => {
+          file: "memory-recall.md",
+          description: "Memory recall agent — chains recall → explain → fact_graph"
+        },
+        "distill-transcripts" => {
+          file: "distill-transcripts.md",
+          description: "Distill transcripts — extract facts/entities/decisions from undistilled content"
+        }
+      }.freeze
+
+      def call(args)
+        opts = parse_options(args, {list: false, force: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory install-skill [SKILL_NAME] [options]"
+            parser.on("--list", "List available skills") { o[:list] = true }
+            parser.on("--force", "Overwrite existing files") { o[:force] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        if opts[:list] || args.empty?
+          return list_skills
+        end
+
+        skill_name = args.first
+        install_skill(skill_name, force: opts[:force])
+      end
+
+      private
+
+      def list_skills
+        stdout.puts "Available skills:"
+        AVAILABLE_SKILLS.each do |name, info|
+          stdout.puts "  #{name} — #{info[:description]}"
+        end
+        stdout.puts ""
+        stdout.puts "Install with: claude-memory install-skill <name>"
+        0
+      end
+
+      def install_skill(name, force: false)
+        skill = AVAILABLE_SKILLS[name]
+        unless skill
+          return failure("Unknown skill: #{name}. Run --list to see available skills.")
+        end
+
+        source = File.join(SKILLS_DIR, skill[:file])
+        unless File.exist?(source)
+          return failure("Skill file not found: #{source}")
+        end
+
+        target_dir = File.join(Dir.home, ".claude", "commands")
+        FileUtils.mkdir_p(target_dir)
+
+        target = File.join(target_dir, skill[:file])
+
+        if File.exist?(target) && !force
+          return failure("#{target} already exists. Use --force to overwrite.")
+        end
+
+        FileUtils.cp(source, target)
+        stdout.puts "Installed #{name} to #{target}"
+        stdout.puts "Use as: /#{File.basename(name, ".md")} <query>"
+        0
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/registry.rb

@@ -3,46 +3,48 @@
 module ClaudeMemory
   module Commands
     # Registry for CLI command lookup and dispatch
-    # Maps command names to command classes for dynamic dispatch
+    # Maps command names to command classes and short descriptions.
+    # Descriptions are authoritative for shell completion and help output;
+    # keep them current when adding commands.
     class Registry
-      # Map of command names to class names
-      # As more commands are extracted, add them here
+      # Map of command names to {class:, description:} entries.
+      # As more commands are extracted, add them here.
       COMMANDS = {
-        "help" => "HelpCommand",
-        "version" => "VersionCommand",
-        "doctor" => "DoctorCommand",
-        "stats" => "StatsCommand",
-        "promote" => "PromoteCommand",
-        "search" => "SearchCommand",
-        "explain" => "ExplainCommand",
-        "conflicts" => "ConflictsCommand",
-        "changes" => "ChangesCommand",
-        "recall" => "RecallCommand",
-        "sweep" => "SweepCommand",
-        "ingest" => "IngestCommand",
-        "publish" => "PublishCommand",
-        "db:init" => "DbInitCommand",
-        "init" => "InitCommand",
-        "uninstall" => "UninstallCommand",
-        "serve-mcp" => "ServeMcpCommand",
-        "hook" => "HookCommand",
-        "index" => "IndexCommand",
-        "recover" => "RecoverCommand",
-        "compact" => "CompactCommand",
-        "export" => "ExportCommand",
-        "git-lfs" => "GitLfsCommand"
+        "help" => {class: HelpCommand, description: "Show help message"},
+        "version" => {class: VersionCommand, description: "Show version"},
+        "doctor" => {class: DoctorCommand, description: "Check system health"},
+        "stats" => {class: StatsCommand, description: "Show statistics"},
+        "promote" => {class: PromoteCommand, description: "Promote fact to global"},
+        "search" => {class: SearchCommand, description: "Search indexed content"},
+        "explain" => {class: ExplainCommand, description: "Explain a fact with receipts"},
+        "conflicts" => {class: ConflictsCommand, description: "Show open conflicts"},
+        "changes" => {class: ChangesCommand, description: "Show recent fact changes"},
+        "recall" => {class: RecallCommand, description: "Recall facts matching query"},
+        "sweep" => {class: SweepCommand, description: "Run maintenance"},
+        "ingest" => {class: IngestCommand, description: "Ingest transcript delta"},
+        "publish" => {class: PublishCommand, description: "Publish snapshot"},
+        "db:init" => {class: DbInitCommand, description: "Initialize database"},
+        "init" => {class: InitCommand, description: "Initialize ClaudeMemory"},
+        "uninstall" => {class: UninstallCommand, description: "Remove configuration"},
+        "serve-mcp" => {class: ServeMcpCommand, description: "Start MCP server"},
+        "hook" => {class: HookCommand, description: "Run hook entrypoints"},
+        "index" => {class: IndexCommand, description: "Index content"},
+        "recover" => {class: RecoverCommand, description: "Recover database"},
+        "compact" => {class: CompactCommand, description: "Compact databases"},
+        "export" => {class: ExportCommand, description: "Export facts to JSON"},
+        "git-lfs" => {class: GitLfsCommand, description: "Git LFS integration"},
+        "install-skill" => {class: InstallSkillCommand, description: "Install agent skills"},
+        "completion" => {class: CompletionCommand, description: "Generate shell completions"},
+        "embeddings" => {class: EmbeddingsCommand, description: "Inspect embedding backend"},
+        "reject" => {class: RejectCommand, description: "Mark a fact as rejected"},
+        "restore" => {class: RestoreCommand, description: "Restore superseded facts from obsolete single-value classification"}
       }.freeze
 
       # Find a command class by name
       # @param command_name [String] the command name (e.g., "help", "version")
       # @return [Class, nil] the command class, or nil if not found
       def self.find(command_name)
-        return nil if command_name.nil?
-
-        class_name = COMMANDS[command_name]
-        return nil unless class_name
-
-        Commands.const_get(class_name)
+        COMMANDS.dig(command_name, :class)
       end
 
       # Get all registered command names
@@ -57,6 +59,19 @@ module ClaudeMemory
       def self.registered?(command_name)
         COMMANDS.key?(command_name)
       end
+
+      # Get the short description for a command
+      # @param command_name [String] the command name
+      # @return [String, nil] the description, or nil if not registered
+      def self.description(command_name)
+        COMMANDS.dig(command_name, :description)
+      end
+
+      # Get all command descriptions as a hash
+      # @return [Hash{String => String}] command name → description
+      def self.descriptions
+        COMMANDS.transform_values { |entry| entry[:description] }
+      end
     end
   end
 end

data/lib/claude_memory/commands/reject_command.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # Mark a fact as rejected (e.g. a distiller hallucination).
+    # Closes any open conflicts involving the fact.
+    class RejectCommand < BaseCommand
+      # @param args [Array<String>] command line arguments (fact_id_or_docid, --scope, --reason)
+      # @return [Integer] exit code (0 for success, 1 for failure)
+      def call(args)
+        opts = parse_options(args, {scope: "project", reason: nil}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory reject <fact_id_or_docid> [options]"
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+            parser.on("--reason TEXT", "Why this fact is wrong (recorded in conflict notes)") { |v| o[:reason] = v }
+          end
+        end
+        return 1 if opts.nil?
+
+        identifier = args.first
+        return failure("Usage: claude-memory reject <fact_id_or_docid> [options]") if identifier.nil? || identifier.empty?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        fact_id = resolve_fact_id(store, identifier)
+        unless fact_id
+          stderr.puts "Fact '#{identifier}' not found in #{opts[:scope]} database."
+          manager.close
+          return 1
+        end
+
+        result = store.reject_fact(fact_id, reason: opts[:reason])
+        manager.close
+
+        if result.nil?
+          stderr.puts "Fact ##{fact_id} not found."
+          return 1
+        end
+
+        stdout.puts "Rejected fact ##{fact_id} in #{opts[:scope]} database."
+        stdout.puts "Resolved #{result[:conflicts_resolved]} open conflict(s)." if result[:conflicts_resolved] > 0
+        0
+      end
+
+      private
+
+      # Accept either a numeric fact id or an 8-char docid hex string.
+      # @param store [Store::SQLiteStore] database to look up the fact in
+      # @param identifier [String] numeric fact id or hex docid
+      # @return [Integer, nil] resolved fact id, or nil if not found
+      def resolve_fact_id(store, identifier)
+        return identifier.to_i if identifier.match?(/\A\d+\z/)
+
+        row = store.find_fact_by_docid(identifier)
+        row ? row[:id] : nil
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/restore_command.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module ClaudeMemory
+  module Commands
+    # One-time recovery for facts that were superseded because of an
+    # obsolete single-value predicate classification. See
+    # Sweep::Maintenance#restore_multi_value_supersessions for the algorithm
+    # and Jaccard heuristic.
+    class RestoreCommand < BaseCommand
+      # @param args [Array<String>] command line arguments (--predicate, --scope, --dry-run)
+      # @return [Integer] exit code (0 for success, 1 for failure)
+      def call(args)
+        opts = parse_options(args, {predicate: nil, scope: "project", dry_run: false}) do |o|
+          OptionParser.new do |parser|
+            parser.banner = "Usage: claude-memory restore --predicate NAME [options]"
+            parser.on("--predicate NAME", "Predicate to restore (e.g. uses_framework)") { |v| o[:predicate] = v }
+            parser.on("--scope SCOPE", %w[project global], "Database scope (default: project)") { |v| o[:scope] = v }
+            parser.on("--dry-run", "Show what would be restored without writing") { o[:dry_run] = true }
+          end
+        end
+        return 1 if opts.nil?
+
+        return failure("--predicate required (e.g. --predicate uses_framework)") if opts[:predicate].nil?
+
+        manager = ClaudeMemory::Store::StoreManager.new
+        store = manager.store_for_scope(opts[:scope])
+
+        begin
+          result = Sweep::Maintenance.new(store).restore_multi_value_supersessions(
+            predicate: opts[:predicate],
+            dry_run: opts[:dry_run]
+          )
+        rescue ArgumentError => e
+          stderr.puts e.message
+          manager.close
+          return 1
+        ensure
+          manager.close
+        end
+
+        print_result(opts, result)
+        0
+      end
+
+      private
+
+      # Print a summary of restored and skipped facts.
+      # @param opts [Hash] parsed options including :predicate, :scope, :dry_run
+      # @param result [Hash] result from Sweep::Maintenance#restore_multi_value_supersessions
+      # @return [void]
+      def print_result(opts, result)
+        mode = opts[:dry_run] ? "DRY RUN" : "RESTORE"
+        stdout.puts "#{mode}: predicate=#{opts[:predicate]} scope=#{opts[:scope]}"
+        stdout.puts "=" * 50
+        stdout.puts "Inspected:         #{result[:inspected]}"
+        stdout.puts "Restored:          #{result[:restored]}"
+        stdout.puts "Skipped ambiguous: #{result[:skipped_ambiguous]}"
+
+        return if result[:decisions].empty?
+
+        stdout.puts
+        stdout.puts "Decisions:"
+        result[:decisions].each do |d|
+          case d[:action]
+          when :restore
+            stdout.puts "  [restore] ##{d[:fact_id]}  #{d[:object]}"
+          when :skip_ambiguous
+            overlaps = d[:overlaps_with].map { |o| "'#{o}'" }.join(", ")
+            stdout.puts "  [skip]    ##{d[:fact_id]}  #{d[:object]}  (overlaps: #{overlaps})"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/commands/skills/distill-transcripts.md

@@ -0,0 +1,102 @@
+# Distill Transcripts
+
+Extract structured knowledge (facts, entities, decisions) from undistilled transcript content and persist it to long-term memory.
+
+## Usage
+
+```
+/distill-transcripts
+/distill-transcripts --limit 10
+```
+
+## Instructions
+
+You are a knowledge extraction specialist. Your job is to read raw transcript content and extract structured facts, entities, and decisions, then persist them via the memory.store_extraction MCP tool.
+
+### Step 1: Get Undistilled Content
+
+Call `memory.undistilled` with `limit: 10` to get transcript content that hasn't been processed yet.
+
+If no items are returned, report "No undistilled content found" and stop.
+
+### Step 2: Extract Knowledge (per item)
+
+For each content item, carefully read the raw_text and extract:
+
+**Entities** — Named things mentioned:
+- type: database, framework, language, platform, repo, module, person, service
+- name: Canonical name (e.g., "PostgreSQL" not "postgres")
+- confidence: 0.0-1.0
+
+**Facts** — Knowledge learned:
+- subject: Entity name or "repo" for project-level facts
+- predicate: prefer a predicate from the canonical vocabulary defined in
+  `lib/claude_memory/resolve/predicate_policy.rb` (convention, decision,
+  architecture, uses_framework, uses_language, uses_database,
+  deployment_platform, auth_method). Other snake_case predicates are
+  accepted but fall through to the default multi-value policy.
+- object: The value
+- confidence: 0.0-1.0
+- quote: Source excerpt (max 200 chars)
+- strength: "stated" (explicitly said) or "inferred" (implied)
+- scope_hint: "project" (this project only) or "global" (all projects)
+
+**Decisions** — Choices made:
+- title: Short summary (max 100 chars)
+- summary: Full description
+- status_hint: "accepted", "proposed", or "rejected"
+
+### What to Extract
+
+- Technology choices ("we use PostgreSQL", "switched to React")
+- Conventions ("always use frozen_string_literal", "test files go in spec/")
+- Architectural decisions ("API uses REST", "auth via JWT")
+- Preferences ("prefer 4-space indent", "use Standard Ruby")
+- Project structure ("migrations in db/migrations/", "commands in commands/")
+
+### What to Skip
+
+- Debugging steps and transient errors
+- Code output and tool observations
+- File contents that were just being read
+- Ephemeral task details ("fix this test", "run the linter")
+- Information already obvious from the codebase itself
+
+### Scope Detection
+
+Set scope_hint to "global" when the text contains signals like:
+- "I always...", "in all my projects...", "my preference is..."
+- "everywhere", "across all repos"
+
+Default to "project" for everything else.
+
+### Step 3: Persist Each Extraction
+
+For each content item with extracted knowledge:
+
+1. Call `memory.store_extraction` with the entities, facts, and decisions arrays
+2. Call `memory.mark_distilled` with the content_item_id and facts_extracted count
+3. If nothing was extracted, still call `memory.mark_distilled` with facts_extracted: 0
+
+### Step 4: Report
+
+Return a summary:
+
+```
+## Distillation Complete
+
+- Items processed: N
+- Facts extracted: N
+- Entities found: N
+- Decisions captured: N
+- Items skipped (nothing to extract): N
+```
+
+### Guidelines
+
+- Process items one at a time to keep extractions focused
+- Use `compact: true` on `memory.undistilled` for smaller responses
+- Be conservative — only extract facts you're confident about (>0.7)
+- Prefer "stated" strength over "inferred" unless clearly implied
+- Do NOT fabricate facts — only extract what's actually in the text
+- If text is mostly code/tool output with no conversational knowledge, mark as distilled with 0 facts

data/lib/claude_memory/commands/skills/memory-recall.md

@@ -0,0 +1,67 @@
+# Memory Recall Agent
+
+Search long-term memory for facts, decisions, conventions, and architectural knowledge. Chains multiple memory tools to build comprehensive answers while saving main-agent context.
+
+## Usage
+
+Provide a natural language query describing what you want to recall:
+
+```
+/memory-recall database migration strategy
+/memory-recall authentication decisions
+/memory-recall testing conventions
+```
+
+## Workflow
+
+1. **Fast lookup** — Start with `memory.recall` for keyword matches
+2. **Semantic search** — If recall returns few results, try `memory.recall_semantic` for conceptual matches
+3. **Shortcuts** — For known categories, use `memory.decisions`, `memory.conventions`, or `memory.architecture`
+4. **Deep dive** — For specific facts, use `memory.explain` to get provenance and `memory.fact_graph` to see relationships
+5. **Synthesize** — Combine findings into a concise, structured answer
+
+## Instructions
+
+You are a memory recall specialist. Given a query, search ClaudeMemory using the available MCP tools and return a synthesized answer.
+
+### Step 1: Initial Search
+
+Run `memory.recall` with the user's query. If the query mentions decisions, conventions, or architecture, also run the appropriate shortcut tool in parallel.
+
+### Step 2: Expand if Needed
+
+If Step 1 returns fewer than 3 results:
+- Try `memory.recall_semantic` with a rephrased version of the query
+- Try `memory.search_concepts` with 2-3 key concepts extracted from the query
+
+### Step 3: Enrich Key Facts
+
+For the top 2-3 most relevant facts:
+- Run `memory.explain` to get provenance (where the fact came from)
+- If relationships matter, run `memory.fact_graph` to see connected facts
+
+### Step 4: Synthesize
+
+Return a structured response:
+
+```
+## Memory Recall Results
+
+### Key Facts
+- [Fact 1 with provenance]
+- [Fact 2 with provenance]
+
+### Context
+[How these facts relate to the query]
+
+### Confidence
+[High/Medium/Low based on number and freshness of supporting facts]
+```
+
+### Guidelines
+
+- Prefer `memory.recall` (fast, token-efficient) before escalating to semantic search
+- Use `compact: true` on all tool calls to minimize token usage
+- Do NOT fabricate facts — only report what memory tools return
+- If no relevant facts found, say so clearly rather than guessing
+- Include fact IDs so the main agent can reference them