claude_memory 0.1.0

data/lib/claude_memory/distill/distiller.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Distill
+    class Distiller
+      def distill(text, content_item_id: nil)
+        raise NotImplementedError, "Subclasses must implement #distill"
+      end
+    end
+  end
+end

data/lib/claude_memory/distill/extraction.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Distill
+    class Extraction
+      attr_reader :entities, :facts, :decisions, :signals
+
+      def initialize(entities: [], facts: [], decisions: [], signals: [])
+        @entities = entities
+        @facts = facts
+        @decisions = decisions
+        @signals = signals
+      end
+
+      def empty?
+        entities.empty? && facts.empty? && decisions.empty? && signals.empty?
+      end
+
+      def to_h
+        {
+          entities: entities,
+          facts: facts,
+          decisions: decisions,
+          signals: signals
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/distill/json_schema.md

@@ -0,0 +1,78 @@
+# Extraction Schema v1
+
+This document defines the schema for extracted knowledge from transcripts.
+
+## Extraction Object
+
+```json
+{
+  "entities": [...],
+  "facts": [...],
+  "decisions": [...],
+  "signals": [...]
+}
+```
+
+## Entity
+
+```json
+{
+  "type": "string",       // e.g., "database", "framework", "language", "platform", "repo", "module", "person", "service"
+  "name": "string",       // canonical name
+  "aliases": ["string"],  // optional: alternative names
+  "confidence": 0.0-1.0   // optional: extraction confidence
+}
+```
+
+## Fact
+
+```json
+{
+  "subject": "string",           // entity name or "repo" for project-level
+  "predicate": "string",         // e.g., "uses_database", "convention", "auth_method"
+  "object": "string",            // entity name or literal value
+  "polarity": "positive|negative", // default: "positive"
+  "confidence": 0.0-1.0,         // extraction confidence
+  "quote": "string",             // source text excerpt
+  "strength": "stated|inferred", // how strongly evidenced
+  "time_hint": "string",         // optional: ISO timestamp hint
+  "decision_ref": "integer"      // optional: index into decisions array
+}
+```
+
+## Decision
+
+```json
+{
+  "title": "string",              // short summary (max 100 chars)
+  "summary": "string",            // full description
+  "status_hint": "string",        // "accepted", "proposed", "rejected"
+  "emits_fact_indexes": [0, 1]    // optional: indices of facts this decision creates
+}
+```
+
+## Signal
+
+```json
+{
+  "kind": "string",   // "supersession", "conflict", "time_boundary"
+  "value": "any"      // signal-specific value
+}
+```
+
+### Signal Kinds
+
+- **supersession**: `{kind: "supersession", value: true}` - indicates old knowledge may be replaced
+- **conflict**: `{kind: "conflict", value: true}` - indicates contradictory information detected
+- **time_boundary**: `{kind: "time_boundary", value: "2024-01-15"}` - temporal boundary marker
+
+## Predicate Types (MVP)
+
+| Predicate | Cardinality | Exclusive |
+|-----------|-------------|-----------|
+| convention | multi | no |
+| decision | multi (by scope) | no |
+| auth_method | single | yes |
+| uses_database | single | yes |
+| uses_framework | single | yes |
+| deployment_platform | single | yes |

data/lib/claude_memory/distill/null_distiller.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Distill
+    class NullDistiller < Distiller
+      DECISION_PATTERNS = [
+        /\b(?:we\s+)?decided\s+to\s+(.+)/i,
+        /\b(?:we\s+)?agreed\s+(?:to\s+|on\s+)(.+)/i,
+        /\blet'?s\s+(?:go\s+with|use)\s+(.+)/i,
+        /\bgoing\s+(?:forward|ahead)\s+with\s+(.+)/i
+      ].freeze
+
+      CONVENTION_PATTERNS = [
+        /\balways\s+(.+)/i,
+        /\bnever\s+(.+)/i,
+        /\bconvention[:\s]+(.+)/i,
+        /\bstandard[:\s]+(.+)/i,
+        /\bwe\s+use\s+(.+)/i
+      ].freeze
+
+      ENTITY_PATTERNS = {
+        "database" => /\b(postgresql|postgres|mysql|sqlite|mongodb|redis)\b/i,
+        "framework" => /\b(rails|sinatra|django|express|next\.?js|react|vue)\b/i,
+        "language" => /\b(ruby|python|javascript|typescript|go|rust)\b/i,
+        "platform" => /\b(aws|gcp|azure|heroku|vercel|netlify|docker|kubernetes)\b/i
+      }.freeze
+
+      GLOBAL_SCOPE_PATTERNS = [
+        /\bi\s+always\b/i,
+        /\bin\s+all\s+(?:my\s+)?projects\b/i,
+        /\beverywhere\b/i,
+        /\bacross\s+all\s+(?:my\s+)?(?:projects|repos|codebases)\b/i,
+        /\bmy\s+(?:personal\s+)?(?:preference|convention|standard)\b/i,
+        /\bglobally\b/i,
+        /\buniversally\b/i
+      ].freeze
+
+      def distill(text, content_item_id: nil)
+        entities = extract_entities(text)
+        facts = extract_facts(text, entities)
+        decisions = extract_decisions(text)
+        signals = extract_signals(text)
+
+        Extraction.new(
+          entities: entities,
+          facts: facts,
+          decisions: decisions,
+          signals: signals
+        )
+      end
+
+      private
+
+      def extract_entities(text)
+        found = []
+        ENTITY_PATTERNS.each do |type, pattern|
+          text.scan(pattern).flatten.uniq.each do |name|
+            found << {type: type, name: name.downcase, confidence: 0.7}
+          end
+        end
+        found.uniq { |e| [e[:type], e[:name]] }
+      end
+
+      def extract_facts(text, entities)
+        facts = []
+        scope_hint = global_scope_signal?(text) ? "global" : "project"
+
+        entities.each do |entity|
+          case entity[:type]
+          when "database"
+            facts << build_fact("uses_database", entity[:name], text, scope_hint)
+          when "framework"
+            facts << build_fact("uses_framework", entity[:name], text, scope_hint)
+          when "platform"
+            facts << build_fact("deployment_platform", entity[:name], text, scope_hint)
+          end
+        end
+
+        facts
+      end
+
+      def extract_decisions(text)
+        decisions = []
+        DECISION_PATTERNS.each do |pattern|
+          text.scan(pattern).flatten.each do |match|
+            decisions << {
+              title: match.strip.slice(0, 100),
+              summary: match.strip,
+              status_hint: "accepted"
+            }
+          end
+        end
+        decisions.first(5)
+      end
+
+      def extract_signals(text)
+        signals = []
+        signals << {kind: "supersession", value: true} if text.match?(/\b(no longer|stopped using|switched from|replaced|deprecated)\b/i)
+        signals << {kind: "conflict", value: true} if text.match?(/\b(disagree|conflict|contradiction|but.*said|however.*different)\b/i)
+        signals << {kind: "global_scope", value: true} if global_scope_signal?(text)
+        signals
+      end
+
+      def global_scope_signal?(text)
+        GLOBAL_SCOPE_PATTERNS.any? { |pattern| text.match?(pattern) }
+      end
+
+      def build_fact(predicate, object, text, scope_hint = "project")
+        quote = text.slice(0, 200)
+        {
+          subject: "repo",
+          predicate: predicate,
+          object: object,
+          polarity: "positive",
+          confidence: 0.7,
+          quote: quote,
+          strength: "inferred",
+          scope_hint: scope_hint
+        }
+      end
+    end
+  end
+end

data/lib/claude_memory/hook/handler.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Hook
+    class Handler
+      class PayloadError < Error; end
+
+      DEFAULT_SWEEP_BUDGET = 5
+
+      def initialize(store, env: ENV)
+        @store = store
+        @env = env
+      end
+
+      def ingest(payload)
+        session_id = payload["session_id"] || @env["CLAUDE_SESSION_ID"]
+        transcript_path = payload["transcript_path"] || @env["CLAUDE_TRANSCRIPT_PATH"]
+        project_path = payload["project_path"] || @env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+
+        raise PayloadError, "Missing required field: session_id" if session_id.nil? || session_id.empty?
+        raise PayloadError, "Missing required field: transcript_path" if transcript_path.nil? || transcript_path.empty?
+
+        ingester = Ingest::Ingester.new(@store, env: @env)
+        ingester.ingest(
+          source: "claude_code",
+          session_id: session_id,
+          transcript_path: transcript_path,
+          project_path: project_path
+        )
+      end
+
+      def sweep(payload)
+        budget = payload.fetch("budget", DEFAULT_SWEEP_BUDGET).to_i
+        sweeper = Sweep::Sweeper.new(@store)
+        stats = sweeper.run!(budget_seconds: budget)
+
+        {stats: stats}
+      end
+
+      def publish(payload)
+        mode = payload.fetch("mode", "shared").to_sym
+        since = payload["since"]
+
+        publisher = Publish.new(@store)
+        publisher.publish!(mode: mode, since: since)
+      end
+    end
+  end
+end

data/lib/claude_memory/index/lexical_fts.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Index
+    class LexicalFTS
+      def initialize(store)
+        @store = store
+        @db = store.db
+        ensure_fts_table!
+      end
+
+      def index_content_item(content_item_id, text)
+        existing = @db[:content_fts].where(content_item_id: content_item_id).get(:content_item_id)
+        return if existing
+
+        @db[:content_fts].insert(content_item_id: content_item_id, text: text)
+      end
+
+      def search(query, limit: 20)
+        return [] if query.nil? || query.strip.empty?
+
+        if query.strip == "*"
+          return @db[:content_items]
+              .order(Sequel.desc(:id))
+              .limit(limit)
+              .select_map(:id)
+        end
+
+        escaped_query = escape_fts_query(query)
+        @db[:content_fts]
+          .where(Sequel.lit("text MATCH ?", escaped_query))
+          .order(:rank)
+          .limit(limit)
+          .select_map(:content_item_id)
+      end
+
+      def escape_fts_query(query)
+        words = query.split(/\s+/).map do |word|
+          next word if word == "*"
+          escaped = word.gsub('"', '""')
+          %("#{escaped}")
+        end.compact
+
+        return words.first if words.size == 1
+        words.join(" OR ")
+      end
+
+      private
+
+      def ensure_fts_table!
+        @db.run(<<~SQL)
+          CREATE VIRTUAL TABLE IF NOT EXISTS content_fts 
+          USING fts5(content_item_id UNINDEXED, text, tokenize='porter unicode61')
+        SQL
+      end
+    end
+  end
+end

data/lib/claude_memory/ingest/ingester.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module ClaudeMemory
+  module Ingest
+    class Ingester
+      def initialize(store, fts: nil, env: ENV)
+        @store = store
+        @fts = fts || Index::LexicalFTS.new(store)
+        @env = env
+      end
+
+      def ingest(source:, session_id:, transcript_path:, project_path: nil)
+        current_offset = @store.get_delta_cursor(session_id, transcript_path) || 0
+        delta, new_offset = TranscriptReader.read_delta(transcript_path, current_offset)
+
+        return {status: :no_change, bytes_read: 0} if delta.nil?
+
+        resolved_project = project_path || detect_project_path
+
+        text_hash = Digest::SHA256.hexdigest(delta)
+        content_id = @store.upsert_content_item(
+          source: source,
+          session_id: session_id,
+          transcript_path: transcript_path,
+          project_path: resolved_project,
+          text_hash: text_hash,
+          byte_len: delta.bytesize,
+          raw_text: delta
+        )
+
+        @fts.index_content_item(content_id, delta)
+        @store.update_delta_cursor(session_id, transcript_path, new_offset)
+
+        {status: :ingested, content_id: content_id, bytes_read: delta.bytesize, project_path: resolved_project}
+      end
+
+      private
+
+      def detect_project_path
+        @env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+      end
+    end
+  end
+end

data/lib/claude_memory/ingest/transcript_reader.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Ingest
+    class TranscriptReader
+      class FileNotFoundError < ClaudeMemory::Error; end
+
+      def self.read_delta(path, from_offset)
+        raise FileNotFoundError, "File not found: #{path}" unless File.exist?(path)
+
+        file_size = File.size(path)
+        effective_offset = (from_offset > file_size) ? 0 : from_offset
+
+        return [nil, effective_offset] if file_size == effective_offset
+
+        content = File.read(path, nil, effective_offset)
+        [content, file_size]
+      end
+    end
+  end
+end

data/lib/claude_memory/mcp/server.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "json"
+
+module ClaudeMemory
+  module MCP
+    class Server
+      PROTOCOL_VERSION = "2024-11-05"
+
+      def initialize(store_or_manager, input: $stdin, output: $stdout)
+        @store_or_manager = store_or_manager
+        @tools = Tools.new(store_or_manager)
+        @input = input
+        @output = output
+        @running = false
+      end
+
+      def run
+        @running = true
+        while @running
+          line = @input.gets
+          break unless line
+
+          handle_message(line.strip)
+        end
+      end
+
+      def stop
+        @running = false
+      end
+
+      private
+
+      def handle_message(line)
+        return if line.empty?
+
+        request = nil
+        begin
+          request = JSON.parse(line)
+          response = process_request(request)
+          send_response(response) if response
+        rescue JSON::ParserError => e
+          send_error(-32700, "Parse error: #{e.message}", 0)
+        rescue => e
+          request_id = request&.fetch("id", nil) || 0
+          send_error(-32603, "Internal error: #{e.message}", request_id)
+        end
+      end
+
+      def process_request(request)
+        id = request["id"]
+        method = request["method"]
+
+        case method
+        when "initialize"
+          handle_initialize(id, request["params"])
+        when "tools/list"
+          handle_tools_list(id)
+        when "tools/call"
+          handle_tools_call(id, request["params"])
+        when "shutdown"
+          @running = false
+          {jsonrpc: "2.0", id: id, result: nil}
+        else
+          {jsonrpc: "2.0", id: id, error: {code: -32601, message: "Method not found: #{method}"}}
+        end
+      end
+
+      def handle_initialize(id, _params)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: {
+              tools: {}
+            },
+            serverInfo: {
+              name: "claude-memory",
+              version: ClaudeMemory::VERSION
+            }
+          }
+        }
+      end
+
+      def handle_tools_list(id)
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            tools: @tools.definitions
+          }
+        }
+      end
+
+      def handle_tools_call(id, params)
+        name = params["name"]
+        arguments = params["arguments"] || {}
+
+        result = @tools.call(name, arguments)
+
+        {
+          jsonrpc: "2.0",
+          id: id,
+          result: {
+            content: [
+              {type: "text", text: JSON.generate(result)}
+            ]
+          }
+        }
+      end
+
+      def send_response(response)
+        @output.puts(JSON.generate(response))
+        @output.flush
+      end
+
+      def send_error(code, message, id)
+        send_response({
+          jsonrpc: "2.0",
+          id: id,
+          error: {code: code, message: message}
+        })
+      end
+    end
+  end
+end