claude_memory 0.7.0 → 0.8.0

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

@@ -30,7 +30,9 @@ module ClaudeMemory
         "recover" => "RecoverCommand",
         "compact" => "CompactCommand",
         "export" => "ExportCommand",
-        "git-lfs" => "GitLfsCommand"
+        "git-lfs" => "GitLfsCommand",
+        "install-skill" => "InstallSkillCommand",
+        "completion" => "CompletionCommand"
       }.freeze
 
       # Find a command class by name

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

@@ -0,0 +1,98 @@
+# 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: uses_database, uses_framework, convention, decision, auth_method, deployment_platform, depends_on, testing_strategy
+- 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

data/lib/claude_memory/core/fact_ranker.rb

@@ -88,8 +88,8 @@ module ClaudeMemory
       # @param text_results [Array<Hash>] Results from text search with :fact and :similarity
       # @param limit [Integer] Maximum results to return
       # @return [Array<Hash>] Merged results sorted by RRF score descending
-      def self.merge_search_results(vector_results, text_results, limit)
-        RRFusion.fuse(vector_results, text_results, limit)
+      def self.merge_search_results(vector_results, text_results, limit, explain: false)
+        RRFusion.fuse(vector_results, text_results, limit, explain: explain)
       end
     end
   end

data/lib/claude_memory/core/rr_fusion.rb

@@ -22,16 +22,23 @@ module ClaudeMemory
       # @param vector_weight [Float] Weight multiplier for vector rankings (default 1.0)
       # @param text_weight [Float] Weight multiplier for text rankings (default 1.0)
       # @return [Array<Hash>] Fused results sorted by RRF score, with :similarity set to RRF score
-      def self.fuse(vector_results, text_results, limit, vector_weight: 1.0, text_weight: 1.0)
+      def self.fuse(vector_results, text_results, limit, vector_weight: 1.0, text_weight: 1.0, explain: false)
         scores = {}
+        traces = {} if explain
         fact_data = {}
 
         # Score vector results by rank position
         vector_results.each_with_index do |result, idx|
           fact_id = result[:fact][:id]
           rank = idx + 1 # 1-based rank
-          scores[fact_id] = (scores[fact_id] || 0.0) + (vector_weight / (K + rank))
-          scores[fact_id] += TOP_BONUS.fetch(rank, 0.0)
+          contribution = (vector_weight / (K + rank)) + TOP_BONUS.fetch(rank, 0.0)
+          scores[fact_id] = (scores[fact_id] || 0.0) + contribution
+          if explain
+            traces[fact_id] ||= {vec_rank: nil, vec_score: nil, fts_rank: nil, fts_score: nil, vec_rrf: nil, fts_rrf: nil}
+            traces[fact_id][:vec_rank] = rank
+            traces[fact_id][:vec_score] = result[:similarity]
+            traces[fact_id][:vec_rrf] = contribution.round(6)
+          end
           # Prefer vector result data (has real similarity score)
           fact_data[fact_id] = result
         end
@@ -40,8 +47,14 @@ module ClaudeMemory
         text_results.each_with_index do |result, idx|
           fact_id = result[:fact][:id]
           rank = idx + 1
-          scores[fact_id] = (scores[fact_id] || 0.0) + (text_weight / (K + rank))
-          scores[fact_id] += TOP_BONUS.fetch(rank, 0.0)
+          contribution = (text_weight / (K + rank)) + TOP_BONUS.fetch(rank, 0.0)
+          scores[fact_id] = (scores[fact_id] || 0.0) + contribution
+          if explain
+            traces[fact_id] ||= {vec_rank: nil, vec_score: nil, fts_rank: nil, fts_score: nil, vec_rrf: nil, fts_rrf: nil}
+            traces[fact_id][:fts_rank] = rank
+            traces[fact_id][:fts_score] = result[:similarity]
+            traces[fact_id][:fts_rrf] = contribution.round(6)
+          end
           # Only use text data if not already present from vector
           fact_data[fact_id] ||= result
         end
@@ -50,7 +63,11 @@ module ClaudeMemory
         scores
           .sort_by { |_id, score| -score }
           .take(limit)
-          .map { |fact_id, score| fact_data[fact_id].merge(similarity: score) }
+          .map do |fact_id, score|
+            merged = fact_data[fact_id].merge(similarity: score)
+            merged[:score_trace] = traces[fact_id].merge(rrf_final: score.round(6)) if explain
+            merged
+          end
       end
     end
   end

data/lib/claude_memory/core/snippet_extractor.rb

@@ -32,8 +32,7 @@ module ClaudeMemory
 
         lines = parsed[:lines]
         best_line_idx = parsed[:best_line_idx]
-        start_idx = [best_line_idx - CONTEXT_BEFORE, 0].max
-        end_idx = [best_line_idx + CONTEXT_AFTER, lines.size - 1].min
+        start_idx, end_idx = snippet_range(lines, best_line_idx)
 
         {
           snippet: build_snippet(lines, best_line_idx),
@@ -81,10 +80,15 @@ module ClaudeMemory
       end
 
       # @api private
-      def self.build_snippet(lines, center_idx)
+      def self.snippet_range(lines, center_idx)
         start_idx = [center_idx - CONTEXT_BEFORE, 0].max
         end_idx = [center_idx + CONTEXT_AFTER, lines.size - 1].min
+        [start_idx, end_idx]
+      end
 
+      # @api private
+      def self.build_snippet(lines, center_idx)
+        start_idx, end_idx = snippet_range(lines, center_idx)
         snippet = lines[start_idx..end_idx].join("\n")
         truncate(snippet)
       end

data/lib/claude_memory/core/text_builder.rb

@@ -18,6 +18,17 @@ module ClaudeMemory
         parts.join(" ").strip
       end
 
+      # Truncate text to a maximum length with a suffix
+      # @param text [String, nil] Text to truncate
+      # @param max_length [Integer] Maximum length before truncation
+      # @param suffix [String] Suffix to append when truncated
+      # @return [String] Truncated text or original if within limit
+      def self.truncate(text, max_length, suffix: "...")
+        return "" if text.nil?
+        return text if text.length <= max_length
+        text[0, max_length] + suffix
+      end
+
       # Transform hash keys from strings to symbols
       # @param hash [Hash] Hash with string or symbol keys
       # @return [Hash] Hash with symbolized keys

data/lib/claude_memory/domain/provenance.rb

@@ -41,7 +41,6 @@ module ClaudeMemory
 
       def validate!
         raise ArgumentError, "fact_id required" if fact_id.nil?
-        raise ArgumentError, "content_item_id required" if content_item_id.nil?
       end
     end
   end

data/lib/claude_memory/embeddings/api_adapter.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module ClaudeMemory
+  module Embeddings
+    # Adapter for any OpenAI-compatible /v1/embeddings endpoint.
+    # Works with OpenAI, Voyage, Ollama, LiteLLM, etc.
+    #
+    # Required ENV:
+    #   CLAUDE_MEMORY_EMBEDDING_API_KEY or OPENAI_API_KEY
+    #
+    # Optional ENV:
+    #   CLAUDE_MEMORY_EMBEDDING_API_URL (default: https://api.openai.com/v1/embeddings)
+    #   CLAUDE_MEMORY_EMBEDDING_MODEL   (default: text-embedding-3-small)
+    #
+    class ApiAdapter
+      class ApiError < StandardError; end
+
+      DEFAULT_API_URL = "https://api.openai.com/v1/embeddings"
+      DEFAULT_MODEL = "text-embedding-3-small"
+
+      def initialize(env: ENV)
+        @api_key = env["CLAUDE_MEMORY_EMBEDDING_API_KEY"] || env["OPENAI_API_KEY"]
+        @api_url = env["CLAUDE_MEMORY_EMBEDDING_API_URL"] || DEFAULT_API_URL
+        @model = env["CLAUDE_MEMORY_EMBEDDING_MODEL"] || DEFAULT_MODEL
+
+        raise ArgumentError, "Set CLAUDE_MEMORY_EMBEDDING_API_KEY or OPENAI_API_KEY" unless @api_key
+      end
+
+      def name = "api"
+
+      # Dimensions are lazy — derived from the first API response and cached.
+      def dimensions
+        @dimensions ||= fetch_dimensions
+      end
+
+      # Generate embedding for a query text.
+      # @param text [String] input text to embed
+      # @return [Array<Float>] embedding vector
+      def generate(text)
+        return zero_vector if text.nil? || text.empty?
+
+        response = call_api(text)
+        embedding = response.dig("data", 0, "embedding")
+
+        raise ApiError, "No embedding returned in API response" unless embedding
+
+        @dimensions ||= embedding.size
+        embedding
+      end
+
+      # Alias for passage encoding — API providers don't distinguish query vs passage
+      alias_method :generate_passage, :generate
+
+      private
+
+      def fetch_dimensions
+        # Make a minimal API call to discover dimensions
+        embedding = generate("dimension probe")
+        embedding.size
+      end
+
+      def call_api(text)
+        uri = URI(@api_url)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.open_timeout = 10
+        http.read_timeout = 30
+
+        request = Net::HTTP::Post.new(uri.path)
+        request["Authorization"] = "Bearer #{@api_key}"
+        request["Content-Type"] = "application/json"
+        request.body = JSON.generate({input: text, model: @model})
+
+        response = http.request(request)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ApiError, "HTTP #{response.code}: #{response.body}"
+        end
+
+        JSON.parse(response.body)
+      end
+
+      def zero_vector
+        # If dimensions haven't been discovered yet, we can't return a properly-sized zero vector.
+        # Return empty array; callers handle nil/empty gracefully.
+        return [] unless @dimensions
+
+        Array.new(@dimensions, 0.0)
+      end
+    end
+  end
+end

data/lib/claude_memory/embeddings/dimension_check.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Embeddings
+    # Value object that detects embedding dimension mismatches.
+    # Returns a Result so the caller decides how to handle mismatches —
+    # no hidden side effects like dropping tables.
+    class DimensionCheck
+      Result = Data.define(:status, :stored, :current)
+
+      # @param store [Store::SQLiteStore] database to check meta against
+      # @param provider [#dimensions] embedding provider
+      # @return [Result] status is :fresh, :match, or :mismatch
+      def self.call(store, provider)
+        stored = store.get_meta("embedding_dimensions")&.to_i
+        return Result.new(status: :fresh, stored: nil, current: provider.dimensions) unless stored
+        return Result.new(status: :match, stored: stored, current: provider.dimensions) if stored == provider.dimensions
+
+        Result.new(status: :mismatch, stored: stored, current: provider.dimensions)
+      end
+    end
+  end
+end

data/lib/claude_memory/embeddings/fastembed_adapter.rb

@@ -17,6 +17,10 @@ module ClaudeMemory
       EMBEDDING_DIM = 384
       DEFAULT_MODEL = "BAAI/bge-small-en-v1.5"
 
+      def name = "fastembed"
+
+      def dimensions = EMBEDDING_DIM
+
       def initialize(model_name: DEFAULT_MODEL)
         require "fastembed"
         @model = Fastembed::TextEmbedding.new(model_name: model_name)

data/lib/claude_memory/embeddings/generator.rb

@@ -12,6 +12,10 @@ module ClaudeMemory
     class Generator
       EMBEDDING_DIM = 384
 
+      def name = "tfidf"
+
+      def dimensions = EMBEDDING_DIM
+
       # Common technical terms and programming concepts for vocabulary
       VOCABULARY = %w[
         database framework library module class function method

data/lib/claude_memory/embeddings/resolver.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Embeddings
+    # Resolves an embedding provider by name or ENV.
+    # Three providers: tfidf (default), fastembed, api.
+    def self.resolve(name = nil, env: ENV)
+      provider = name || env["CLAUDE_MEMORY_EMBEDDING_PROVIDER"] || "tfidf"
+
+      case provider
+      when "tfidf" then Generator.new
+      when "fastembed" then FastembedAdapter.new
+      when "api" then ApiAdapter.new(env: env)
+      else raise ArgumentError, "Unknown embedding provider: #{provider}. Available: tfidf, fastembed, api"
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/context_injector.rb

@@ -9,6 +9,10 @@ module ClaudeMemory
       MAX_DECISIONS = 5
       MAX_CONVENTIONS = 5
       MAX_ARCHITECTURE = 5
+      MAX_UNDISTILLED = 3
+      MAX_TEXT_PER_ITEM = 1500
+
+      FRESH_SESSION_SOURCES = %w[startup resume clear].freeze
 
       QUERIES = {
         decisions: {query: "decision constraint rule requirement", scope: "all"},
@@ -16,8 +20,9 @@ module ClaudeMemory
         architecture: {query: "uses framework implements architecture pattern", scope: "all"}
       }.freeze
 
-      def initialize(manager)
+      def initialize(manager, source: nil)
         @manager = manager
+        @source = source
         @recall = Recall.new(manager)
       end
 
@@ -33,6 +38,11 @@ module ClaudeMemory
         architecture = fetch(:architecture, MAX_ARCHITECTURE)
         sections << format_section("Architecture", architecture) if architecture.any?
 
+        if fresh_session?
+          undistilled = fetch_undistilled(MAX_UNDISTILLED)
+          sections << format_distillation_prompt(undistilled) if undistilled.any?
+        end
+
         return nil if sections.empty?
 
         sections.join("\n")
@@ -40,11 +50,16 @@ module ClaudeMemory
 
       private
 
+      def fresh_session?
+        @source.nil? || FRESH_SESSION_SOURCES.include?(@source)
+      end
+
       def fetch(category, limit)
         config = QUERIES.fetch(category)
         results = @recall.query(config[:query], limit: limit, scope: config[:scope])
         results.map { |r| format_fact(r[:fact]) }
-      rescue => _e
+      rescue => e
+        ClaudeMemory.logger.debug("ContextInjector#fetch(#{category}) failed: #{e.message}")
         []
       end
 
@@ -62,6 +77,47 @@ module ClaudeMemory
         end
       end
 
+      def fetch_undistilled(limit)
+        stores = []
+        stores << @manager.project_store if @manager.project_store
+        stores << @manager.global_store if @manager.global_store
+
+        items = stores.flat_map { |s|
+          s.undistilled_content_items(limit: limit, min_length: 200)
+        }
+
+        items
+          .sort_by { |i| i[:occurred_at] || "" }
+          .reverse
+          .first(limit)
+      rescue => e
+        ClaudeMemory.logger.warn("ContextInjector#fetch_undistilled failed: #{e.message}")
+        []
+      end
+
+      def format_distillation_prompt(items)
+        lines = [
+          "## Pending Knowledge Extraction",
+          "",
+          "The following transcript segments haven't been deeply analyzed yet.",
+          "Extract facts, entities, and decisions, then call `memory.store_extraction`",
+          "followed by `memory.mark_distilled` for each item.",
+          "",
+          "**What to extract:** technology decisions, conventions, preferences, architecture",
+          "**What to skip:** debugging steps, code output, transient errors"
+        ]
+
+        items.each do |item|
+          ago = Core::RelativeTime.format(item[:occurred_at]) || "unknown"
+          truncated = Core::TextBuilder.truncate(item[:raw_text], MAX_TEXT_PER_ITEM)
+          lines << ""
+          lines << "### Content Item #{item[:id]} (#{ago})"
+          lines << truncated
+        end
+
+        lines.join("\n")
+      end
+
       def format_section(title, items)
         items = items.compact.uniq
         return nil if items.empty?