claude_memory 0.5.1 → 0.6.0

data/lib/claude_memory/ingest/observation_compressor.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module Ingest
+    # Compresses tool call observations into human-readable summaries.
+    # Reduces ~70% token usage vs raw tool I/O in provenance descriptions.
+    #
+    # @example
+    #   compressor = ObservationCompressor.new
+    #   summary = compressor.compress("Edit", '{"file_path":"/src/auth.rb","old_string":"def login","new_string":"def async_login"}')
+    #   # => "Edited auth.rb: 'def login' → 'def async_login'"
+    class ObservationCompressor
+      MAX_SUMMARY_LENGTH = 200
+
+      def compress(tool_name, tool_input_json)
+        return nil if tool_input_json.nil? || tool_input_json.empty?
+
+        input = parse_input(tool_input_json)
+        return nil unless input
+
+        summary = case tool_name
+        when "Edit"
+          compress_edit(input)
+        when "Write"
+          compress_write(input)
+        when "Bash"
+          compress_bash(input)
+        when "Read"
+          compress_read(input)
+        when "Glob"
+          compress_glob(input)
+        when "Grep"
+          compress_grep(input)
+        when "Task"
+          compress_task(input)
+        when "WebFetch"
+          compress_web_fetch(input)
+        when "WebSearch"
+          compress_web_search(input)
+        when "NotebookEdit"
+          compress_notebook_edit(input)
+        else
+          compress_generic(tool_name, input)
+        end
+
+        truncate(summary)
+      end
+
+      private
+
+      def parse_input(json_str)
+        JSON.parse(json_str)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def compress_edit(input)
+        file = short_path(input["file_path"])
+        old_str = truncate_str(input["old_string"], 40)
+        new_str = truncate_str(input["new_string"], 40)
+
+        if old_str && new_str
+          "Edited #{file}: '#{old_str}' → '#{new_str}'"
+        elsif file
+          "Edited #{file}"
+        end
+      end
+
+      def compress_write(input)
+        file = short_path(input["file_path"])
+        content = input["content"]
+        size = content ? content.length : 0
+
+        "Created #{file} (#{size} chars)"
+      end
+
+      def compress_bash(input)
+        command = input["command"]
+        return "Ran shell command" unless command
+
+        desc = input["description"]
+        cmd = truncate_str(command, 80)
+
+        if desc
+          "Ran: #{desc}"
+        else
+          "Ran: #{cmd}"
+        end
+      end
+
+      def compress_read(input)
+        file = short_path(input["file_path"])
+        offset = input["offset"]
+        limit = input["limit"]
+
+        parts = ["Read #{file}"]
+        parts << "lines #{offset}-#{offset + limit}" if offset && limit
+        parts.join(" ")
+      end
+
+      def compress_glob(input)
+        pattern = input["pattern"]
+        path = input["path"]
+
+        if path
+          "Glob #{pattern} in #{short_path(path)}"
+        else
+          "Glob #{pattern}"
+        end
+      end
+
+      def compress_grep(input)
+        pattern = input["pattern"]
+        path = input["path"]
+
+        if path
+          "Searched '#{truncate_str(pattern, 40)}' in #{short_path(path)}"
+        else
+          "Searched '#{truncate_str(pattern, 40)}'"
+        end
+      end
+
+      def compress_task(input)
+        desc = input["description"]
+        agent_type = input["subagent_type"]
+
+        if desc
+          "Spawned #{agent_type || "agent"}: #{truncate_str(desc, 60)}"
+        else
+          "Spawned #{agent_type || "agent"}"
+        end
+      end
+
+      def compress_web_fetch(input)
+        url = input["url"]
+        "Fetched #{truncate_str(url, 60)}"
+      end
+
+      def compress_web_search(input)
+        query = input["query"]
+        "Searched web: '#{truncate_str(query, 60)}'"
+      end
+
+      def compress_notebook_edit(input)
+        path = short_path(input["notebook_path"])
+        mode = input["edit_mode"] || "replace"
+        "Notebook #{mode} in #{path}"
+      end
+
+      def compress_generic(tool_name, input)
+        keys = input.keys.first(3).join(", ")
+        "#{tool_name}(#{keys})"
+      end
+
+      def short_path(path)
+        return "unknown" unless path
+
+        File.basename(path)
+      end
+
+      def truncate_str(str, max_len)
+        return nil unless str
+
+        str = str.gsub(/\s+/, " ").strip
+        (str.length > max_len) ? str[0...max_len] + "..." : str
+      end
+
+      def truncate(summary)
+        return nil unless summary
+
+        (summary.length > MAX_SUMMARY_LENGTH) ? summary[0...MAX_SUMMARY_LENGTH] + "..." : summary
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/instructions_builder.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module MCP
+    # Generates dynamic MCP server instructions from database state.
+    # Injected into the LLM system prompt via the initialize response,
+    # giving Claude immediate context about memory state without extra tool calls.
+    #
+    # Source: QMD mcp.ts:91-98 (buildInstructions pattern)
+    module InstructionsBuilder
+      module_function
+
+      def build(store_or_manager)
+        parts = ["ClaudeMemory v#{ClaudeMemory::VERSION} — long-term memory for Claude Code."]
+
+        if store_or_manager.is_a?(Store::StoreManager)
+          parts << database_summary(store_or_manager)
+          parts << conflict_summary(store_or_manager)
+        elsif store_or_manager.respond_to?(:facts)
+          parts << single_db_summary(store_or_manager)
+        end
+
+        parts << usage_hint
+        parts.compact.join("\n\n")
+      rescue => _e
+        # Never fail initialization — return minimal instructions
+        "ClaudeMemory v#{ClaudeMemory::VERSION} — long-term memory for Claude Code."
+      end
+
+      def database_summary(manager)
+        lines = []
+
+        if manager.global_exists?
+          manager.ensure_global!
+          global = manager.global_store
+          g_facts = global.facts.where(status: "active").count
+          lines << "Global: #{g_facts} active facts"
+        end
+
+        if manager.project_exists?
+          manager.ensure_project!
+          project = manager.project_store
+          p_facts = project.facts.where(status: "active").count
+          lines << "Project: #{p_facts} active facts"
+        end
+
+        return nil if lines.empty?
+        "Database state: #{lines.join(", ")}."
+      end
+
+      def single_db_summary(store)
+        facts = store.facts.where(status: "active").count
+        "Database state: #{facts} active facts."
+      end
+
+      def conflict_summary(manager)
+        count = 0
+
+        if manager.global_exists?
+          count += manager.global_store.conflicts.where(status: "open").count
+        end
+
+        if manager.project_exists?
+          count += manager.project_store.conflicts.where(status: "open").count
+        end
+
+        return nil if count == 0
+        "#{count} open conflict#{"s" unless count == 1} — use memory.conflicts to review."
+      end
+
+      def usage_hint
+        "Use memory.recall to search facts, memory.decisions for architectural decisions, memory.conventions for coding style."
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/server.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "instructions_builder"
 require_relative "query_guide"
 require_relative "text_summary"
 
@@ -85,7 +86,8 @@ module ClaudeMemory
             serverInfo: {
               name: "claude-memory",
               version: ClaudeMemory::VERSION
-            }
+            },
+            instructions: InstructionsBuilder.build(@store_or_manager)
           }
         }
       end

data/lib/claude_memory/mcp/tool_definitions.rb

@@ -11,21 +11,21 @@ module ClaudeMemory
         [
           {
             name: "memory.recall",
-            description: "Search facts matching a query from both global and project memory databases.",
+            description: "Search facts matching a query from both global and project memory databases. Returns full facts with provenance (~800 tokens/result, ~300 with compact: true). For token-efficient browsing, use memory.recall_index first (~200 tokens/result), then memory.recall_details for selected facts.",
             inputSchema: {
               type: "object",
               properties: {
                 query: {type: "string", description: "Search query for existing knowledge (e.g., 'authentication flow', 'error handling', 'database setup')"},
                 limit: {type: "integer", description: "Max results", default: 10},
                 scope: {type: "string", enum: ["all", "global", "project"], description: "Filter by scope: 'all' (default), 'global', or 'project'", default: "all"},
-                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses", default: false}
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
               },
               required: ["query"]
             }
           },
           {
             name: "memory.recall_index",
-            description: "Lightweight search returning fact previews, IDs, and token costs. Follow up with memory.recall_details for full information.",
+            description: "Lightweight search returning fact previews, IDs, and token costs (~200 tokens/result). Step 1 of progressive disclosure: browse results here, then call memory.recall_details with selected fact IDs for full information (~500 tokens/fact). Saves ~60% tokens vs memory.recall when you only need a few facts.",
             inputSchema: {
               type: "object",
               properties: {
@@ -38,7 +38,7 @@ module ClaudeMemory
           },
           {
             name: "memory.recall_details",
-            description: "Fetch full details for specific fact IDs. Use after memory.recall_index.",
+            description: "Fetch full details for specific fact IDs (~500 tokens/fact). Step 2 of progressive disclosure: use after memory.recall_index to get provenance and metadata for selected facts only.",
             inputSchema: {
               type: "object",
               properties: {
@@ -234,7 +234,7 @@ module ClaudeMemory
           },
           {
             name: "memory.recall_semantic",
-            description: "Search facts using semantic similarity (finds conceptually related facts using vector embeddings)",
+            description: "Search facts using semantic similarity (finds conceptually related facts using vector embeddings). ~800 tokens/result, ~300 with compact: true.",
             inputSchema: {
               type: "object",
               properties: {
@@ -242,7 +242,7 @@ module ClaudeMemory
                 mode: {type: "string", enum: ["vector", "text", "both"], default: "both", description: "Search mode: vector (embeddings), text (FTS), or both (hybrid)"},
                 limit: {type: "integer", default: 10, description: "Maximum results to return"},
                 scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
-                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses", default: false}
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
               },
               required: ["query"]
             }
@@ -262,7 +262,7 @@ module ClaudeMemory
                 },
                 limit: {type: "integer", default: 10, description: "Maximum results to return"},
                 scope: {type: "string", enum: ["all", "global", "project"], default: "all", description: "Filter by scope"},
-                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses", default: false}
+                compact: {type: "boolean", description: "Omit provenance receipts for ~60% smaller responses (~800 → ~300 tokens/result)", default: false}
               },
               required: ["concepts"]
             }
@@ -287,6 +287,14 @@ module ClaudeMemory
               type: "object",
               properties: {}
             }
+          },
+          {
+            name: "memory.list_projects",
+            description: "List all known memory databases with fact counts and status. Shows global database, current project, and other projects discovered from promoted facts. Helps discover available search scopes before querying.",
+            inputSchema: {
+              type: "object",
+              properties: {}
+            }
           }
         ]
       end

data/lib/claude_memory/mcp/tools.rb

@@ -68,6 +68,8 @@ module ClaudeMemory
           fact_graph(arguments)
         when "memory.check_setup"
           check_setup
+        when "memory.list_projects"
+          list_projects
         else
           {error: "Unknown tool: #{name}"}
         end
@@ -507,8 +509,112 @@ module ClaudeMemory
         }
       end
 
+      def list_projects
+        result = {global: nil, current_project: nil, other_projects: []}
+
+        if @manager
+          result[:global] = list_global_database
+          result[:current_project] = list_current_project
+          result[:other_projects] = discover_other_projects
+        elsif @legacy_store
+          result[:global] = {
+            exists: true,
+            path: @legacy_store.db.opts[:database],
+            facts_active: @legacy_store.facts.where(status: "active").count,
+            entities: @legacy_store.entities.count
+          }
+        end
+
+        result[:project_count] = 1 + result[:other_projects].size
+        result
+      end
+
+      def list_global_database
+        if @manager.global_exists?
+          @manager.ensure_global!
+          store = @manager.global_store
+          {
+            exists: true,
+            path: @manager.global_db_path,
+            facts_active: store.facts.where(status: "active").count,
+            facts_total: store.facts.count,
+            entities: store.entities.count
+          }
+        else
+          {exists: false, path: @manager.global_db_path}
+        end
+      end
+
+      def list_current_project
+        if @manager.project_exists?
+          @manager.ensure_project!
+          store = @manager.project_store
+          {
+            exists: true,
+            path: @manager.project_path,
+            db_path: @manager.project_db_path,
+            facts_active: store.facts.where(status: "active").count,
+            facts_total: store.facts.count,
+            entities: store.entities.count
+          }
+        else
+          {exists: false, path: @manager.project_path, db_path: @manager.project_db_path}
+        end
+      end
+
+      def discover_other_projects
+        return [] unless @manager.global_exists?
+
+        @manager.ensure_global!
+        global = @manager.global_store
+
+        # Find project paths from promoted facts
+        promoted_paths = global.facts
+          .where(Sequel.like(:created_from, "promoted:%"))
+          .select(:created_from)
+          .distinct
+          .all
+          .filter_map { |f|
+            match = f[:created_from]&.match(/\Apromoted:(.+):\d+\z/)
+            match[1] if match
+          }
+          .uniq
+
+        # Also check for project_path values on facts
+        fact_paths = global.facts
+          .exclude(project_path: nil)
+          .select(:project_path)
+          .distinct
+          .all
+          .map { |f| f[:project_path] }
+
+        all_paths = (promoted_paths + fact_paths).uniq
+        current = @manager.project_path
+
+        all_paths.filter_map { |path|
+          next if path == current
+
+          db_path = File.join(path, ".claude", "memory.sqlite3")
+          entry = {path: path, db_path: db_path, exists: File.exist?(db_path)}
+
+          if entry[:exists]
+            begin
+              temp_store = Store::SQLiteStore.new(db_path)
+              entry[:facts_active] = temp_store.facts.where(status: "active").count
+              entry[:facts_total] = temp_store.facts.count
+              entry[:entities] = temp_store.entities.count
+              temp_store.close
+            rescue => _e
+              entry[:error] = "Could not read database"
+            end
+          end
+
+          entry
+        }
+      end
+
       def db_stats(store)
-        {
+        stats = {
           exists: true,
           facts_total: store.facts.count,
           facts_active: store.facts.where(status: "active").count,
@@ -516,12 +622,18 @@ module ClaudeMemory
           open_conflicts: store.conflicts.where(status: "open").count,
           schema_version: store.schema_version
         }
+
+        vec_index = store.vector_index
+        stats[:vec_available] = vec_index.available?
+        stats[:vec_indexed] = vec_index.coverage_stats[:vec_indexed] if vec_index.available?
+
+        stats
       end
 
       def detailed_stats(store)
         active_facts = store.facts.where(status: "active").count
 
-        {
+        stats = {
           exists: true,
           facts: fact_stats(store, active_facts),
           entities: entity_stats(store),
@@ -530,6 +642,10 @@ module ClaudeMemory
           conflicts: conflict_stats(store),
           schema_version: store.schema_version
         }
+
+        stats[:vec] = vec_stats(store, active_facts)
+
+        stats
       end
 
       def fact_stats(store, active_facts)
@@ -594,6 +710,13 @@ module ClaudeMemory
         }
       end
 
+      def vec_stats(store, _active_facts)
+        vec_index = store.vector_index
+        result = {available: vec_index.available?}
+        result.merge!(vec_index.coverage_stats) if vec_index.available?
+        result
+      end
+
       def conflict_stats(store)
         open = store.conflicts.where(status: "open").count
         resolved = store.conflicts.where(status: "resolved").count

data/lib/claude_memory/publish.rb

@@ -14,19 +14,8 @@ module ClaudeMemory
     end
 
     def generate_snapshot(since: nil)
-      facts = fetch_active_facts
-      conflicts = @store.open_conflicts
-      recent_supersessions = fetch_recent_supersessions(since)
-
-      sections = []
-      sections << generate_decisions_section(facts)
-      sections << generate_conventions_section(facts)
-      sections << generate_constraints_section(facts)
-      sections << generate_conflicts_section(conflicts) if conflicts.any?
-      sections << generate_supersessions_section(recent_supersessions) if recent_supersessions.any?
-
       header = <<~HEADER
-        <!-- 
+        <!--
           This file is auto-generated by claude-memory.
           Do not edit manually - changes will be overwritten.
           Generated: #{Time.now.utc.iso8601}
@@ -36,14 +25,15 @@ module ClaudeMemory
 
       HEADER
 
-      header + sections.compact.reject(&:empty?).join("\n")
+      header + generate_body(since: since)
     end
 
     def publish!(mode: :shared, granularity: :repo, since: nil, rules_dir: nil)
-      content = generate_snapshot(since: since)
       path = output_path(mode, rules_dir: rules_dir)
+      body = generate_body(since: since)
 
-      if should_write?(path, content)
+      if should_write?(path, body)
+        content = generate_snapshot(since: since)
         @fs.write(path, content)
         ensure_import_exists(mode, path, rules_dir: rules_dir)
         {status: :updated, path: path}
@@ -163,22 +153,33 @@ module ClaudeMemory
       lines.join("\n") + "\n"
     end
 
-    def should_write?(path, content)
-      return true unless @fs.exist?(path)
+    def generate_body(since: nil)
+      facts = fetch_active_facts
+      conflicts = @store.open_conflicts
+      recent_supersessions = fetch_recent_supersessions(since)
+
+      sections = []
+      sections << generate_decisions_section(facts)
+      sections << generate_conventions_section(facts)
+      sections << generate_constraints_section(facts)
+      sections << generate_conflicts_section(conflicts) if conflicts.any?
+      sections << generate_supersessions_section(recent_supersessions) if recent_supersessions.any?
 
-      # Compare content without timestamp to avoid unnecessary rewrites
-      existing_content = @fs.read(path)
-      existing_normalized = normalize_for_comparison(existing_content)
-      new_normalized = normalize_for_comparison(content)
+      sections.compact.reject(&:empty?).join("\n")
+    end
+
+    def should_write?(path, new_body)
+      return true unless @fs.exist?(path)
 
-      existing_hash = Digest::SHA256.hexdigest(existing_normalized)
-      new_hash = Digest::SHA256.hexdigest(new_normalized)
-      existing_hash != new_hash
+      existing_body = extract_body(@fs.read(path))
+      existing_body != new_body
     end
 
-    def normalize_for_comparison(content)
-      # Remove timestamp line for comparison to prevent churn on timestamp-only changes
-      content.gsub(/^  Generated: .+$/, "")
+    def extract_body(content)
+      # Strip the HTML comment header and "# Project Memory" heading
+      content
+        .sub(/\A<!--.*?-->\s*/m, "")
+        .sub(/\A# Project Memory\s*/m, "")
     end
 
     def ensure_import_exists(mode, path, rules_dir: nil)

data/lib/claude_memory/recall/dual_query_template.rb

@@ -44,20 +44,9 @@ module ClaudeMemory
       end
 
       def query_store(source_label, &operation)
-        store = (source_label == :project) ? @manager.project_store : @manager.global_store
-        return [] unless store
-
-        ensure_store!(source_label)
+        store = @manager.store_for_scope(source_label.to_s)
         operation.call(store, source_label)
       end
-
-      def ensure_store!(source_label)
-        if source_label == :project
-          @manager.ensure_project!
-        else
-          @manager.ensure_global!
-        end
-      end
     end
   end
 end