claude_memory 0.1.0

data/lib/claude_memory/store/sqlite_store.rb

@@ -0,0 +1,340 @@
+# frozen_string_literal: true
+
+require "sequel"
+require "json"
+
+module ClaudeMemory
+  module Store
+    class SQLiteStore
+      SCHEMA_VERSION = 2
+
+      attr_reader :db
+
+      def initialize(db_path)
+        @db_path = db_path
+        @db = Sequel.sqlite(db_path)
+        ensure_schema!
+      end
+
+      def close
+        @db.disconnect
+      end
+
+      def schema_version
+        @db[:meta].where(key: "schema_version").get(:value)&.to_i
+      end
+
+      def content_items
+        @db[:content_items]
+      end
+
+      def delta_cursors
+        @db[:delta_cursors]
+      end
+
+      def entities
+        @db[:entities]
+      end
+
+      def entity_aliases
+        @db[:entity_aliases]
+      end
+
+      def facts
+        @db[:facts]
+      end
+
+      def provenance
+        @db[:provenance]
+      end
+
+      def fact_links
+        @db[:fact_links]
+      end
+
+      def conflicts
+        @db[:conflicts]
+      end
+
+      private
+
+      def ensure_schema!
+        create_tables!
+        run_migrations!
+        set_meta("schema_version", SCHEMA_VERSION.to_s)
+        set_meta("created_at", Time.now.utc.iso8601) unless get_meta("created_at")
+      end
+
+      def run_migrations!
+        current = get_meta("schema_version")&.to_i || 0
+
+        migrate_to_v2! if current < 2
+      end
+
+      def migrate_to_v2!
+        columns = @db.schema(:content_items).map(&:first)
+        unless columns.include?(:project_path)
+          @db.alter_table(:content_items) do
+            add_column :project_path, String
+          end
+        end
+
+        columns = @db.schema(:facts).map(&:first)
+        unless columns.include?(:scope)
+          @db.alter_table(:facts) do
+            add_column :scope, String, default: "project"
+            add_column :project_path, String
+            add_index :scope, name: :idx_facts_scope
+            add_index :project_path, name: :idx_facts_project
+          end
+        end
+      end
+
+      def create_tables!
+        @db.create_table?(:meta) do
+          String :key, primary_key: true
+          String :value
+        end
+
+        @db.create_table?(:content_items) do
+          primary_key :id
+          String :source, null: false
+          String :session_id
+          String :transcript_path
+          String :project_path
+          String :occurred_at
+          String :ingested_at, null: false
+          String :text_hash, null: false
+          Integer :byte_len, null: false
+          String :raw_text, text: true
+          String :metadata_json, text: true
+        end
+
+        @db.create_table?(:delta_cursors) do
+          primary_key :id
+          String :session_id, null: false
+          String :transcript_path, null: false
+          Integer :last_byte_offset, null: false, default: 0
+          String :updated_at, null: false
+          unique [:session_id, :transcript_path]
+        end
+
+        @db.create_table?(:entities) do
+          primary_key :id
+          String :type, null: false
+          String :canonical_name, null: false
+          String :slug, null: false, unique: true
+          String :created_at, null: false
+        end
+
+        @db.create_table?(:entity_aliases) do
+          primary_key :id
+          foreign_key :entity_id, :entities, null: false
+          String :source
+          String :alias, null: false
+          Float :confidence, default: 1.0
+        end
+
+        @db.create_table?(:facts) do
+          primary_key :id
+          foreign_key :subject_entity_id, :entities
+          String :predicate, null: false
+          foreign_key :object_entity_id, :entities
+          String :object_literal
+          String :datatype
+          String :polarity, default: "positive"
+          String :valid_from
+          String :valid_to
+          String :status, default: "active"
+          Float :confidence, default: 1.0
+          String :created_from
+          String :created_at, null: false
+          String :scope, default: "project"
+          String :project_path
+        end
+
+        @db.create_table?(:provenance) do
+          primary_key :id
+          foreign_key :fact_id, :facts, null: false
+          foreign_key :content_item_id, :content_items
+          String :quote, text: true
+          foreign_key :attribution_entity_id, :entities
+          String :strength, default: "stated"
+        end
+
+        @db.create_table?(:fact_links) do
+          primary_key :id
+          foreign_key :from_fact_id, :facts, null: false
+          foreign_key :to_fact_id, :facts, null: false
+          String :link_type, null: false
+        end
+
+        @db.create_table?(:conflicts) do
+          primary_key :id
+          foreign_key :fact_a_id, :facts, null: false
+          foreign_key :fact_b_id, :facts, null: false
+          String :status, default: "open"
+          String :detected_at, null: false
+          String :notes, text: true
+        end
+
+        create_index_if_not_exists(:facts, :predicate, :idx_facts_predicate)
+        create_index_if_not_exists(:facts, :subject_entity_id, :idx_facts_subject)
+        create_index_if_not_exists(:facts, :status, :idx_facts_status)
+        create_index_if_not_exists(:facts, :scope, :idx_facts_scope)
+        create_index_if_not_exists(:facts, :project_path, :idx_facts_project)
+        create_index_if_not_exists(:provenance, :fact_id, :idx_provenance_fact)
+        create_index_if_not_exists(:entity_aliases, :entity_id, :idx_entity_aliases_entity)
+        create_index_if_not_exists(:content_items, :session_id, :idx_content_items_session)
+        create_index_if_not_exists(:content_items, :project_path, :idx_content_items_project)
+      end
+
+      def create_index_if_not_exists(table, column, name)
+        @db.run("CREATE INDEX IF NOT EXISTS #{name} ON #{table}(#{column})")
+      end
+
+      def set_meta(key, value)
+        @db[:meta].insert_conflict(target: :key, update: {value: value}).insert(key: key, value: value)
+      end
+
+      def get_meta(key)
+        @db[:meta].where(key: key).get(:value)
+      end
+
+      public
+
+      def upsert_content_item(source:, text_hash:, byte_len:, session_id: nil, transcript_path: nil,
+        project_path: nil, occurred_at: nil, raw_text: nil, metadata: nil)
+        existing = content_items.where(text_hash: text_hash, session_id: session_id).get(:id)
+        return existing if existing
+
+        now = Time.now.utc.iso8601
+        content_items.insert(
+          source: source,
+          session_id: session_id,
+          transcript_path: transcript_path,
+          project_path: project_path,
+          occurred_at: occurred_at || now,
+          ingested_at: now,
+          text_hash: text_hash,
+          byte_len: byte_len,
+          raw_text: raw_text,
+          metadata_json: metadata&.to_json
+        )
+      end
+
+      def get_delta_cursor(session_id, transcript_path)
+        delta_cursors.where(session_id: session_id, transcript_path: transcript_path).get(:last_byte_offset)
+      end
+
+      def update_delta_cursor(session_id, transcript_path, offset)
+        now = Time.now.utc.iso8601
+        delta_cursors
+          .insert_conflict(
+            target: [:session_id, :transcript_path],
+            update: {last_byte_offset: offset, updated_at: now}
+          )
+          .insert(
+            session_id: session_id,
+            transcript_path: transcript_path,
+            last_byte_offset: offset,
+            updated_at: now
+          )
+      end
+
+      def find_or_create_entity(type:, name:)
+        slug = slugify(type, name)
+        existing = entities.where(slug: slug).get(:id)
+        return existing if existing
+
+        now = Time.now.utc.iso8601
+        entities.insert(type: type, canonical_name: name, slug: slug, created_at: now)
+      end
+
+      def insert_fact(subject_entity_id:, predicate:, object_entity_id: nil, object_literal: nil,
+        datatype: nil, polarity: "positive", valid_from: nil, status: "active",
+        confidence: 1.0, created_from: nil, scope: "project", project_path: nil)
+        now = Time.now.utc.iso8601
+        facts.insert(
+          subject_entity_id: subject_entity_id,
+          predicate: predicate,
+          object_entity_id: object_entity_id,
+          object_literal: object_literal,
+          datatype: datatype,
+          polarity: polarity,
+          valid_from: valid_from || now,
+          status: status,
+          confidence: confidence,
+          created_from: created_from,
+          created_at: now,
+          scope: scope,
+          project_path: project_path
+        )
+      end
+
+      def update_fact(fact_id, status: nil, valid_to: nil, scope: nil, project_path: nil)
+        updates = {}
+        updates[:status] = status if status
+        updates[:valid_to] = valid_to if valid_to
+
+        if scope
+          updates[:scope] = scope
+          updates[:project_path] = (scope == "global") ? nil : project_path
+        end
+
+        return false if updates.empty?
+
+        facts.where(id: fact_id).update(updates)
+        true
+      end
+
+      def facts_for_slot(subject_entity_id, predicate, status: "active")
+        facts
+          .where(subject_entity_id: subject_entity_id, predicate: predicate, status: status)
+          .select(:id, :subject_entity_id, :predicate, :object_entity_id, :object_literal,
+            :datatype, :polarity, :valid_from, :valid_to, :status, :confidence,
+            :created_from, :created_at)
+          .all
+      end
+
+      def insert_provenance(fact_id:, content_item_id: nil, quote: nil, attribution_entity_id: nil, strength: "stated")
+        provenance.insert(
+          fact_id: fact_id,
+          content_item_id: content_item_id,
+          quote: quote,
+          attribution_entity_id: attribution_entity_id,
+          strength: strength
+        )
+      end
+
+      def provenance_for_fact(fact_id)
+        provenance.where(fact_id: fact_id).all
+      end
+
+      def insert_conflict(fact_a_id:, fact_b_id:, status: "open", notes: nil)
+        now = Time.now.utc.iso8601
+        conflicts.insert(
+          fact_a_id: fact_a_id,
+          fact_b_id: fact_b_id,
+          status: status,
+          detected_at: now,
+          notes: notes
+        )
+      end
+
+      def open_conflicts
+        conflicts.where(status: "open").all
+      end
+
+      def insert_fact_link(from_fact_id:, to_fact_id:, link_type:)
+        fact_links.insert(from_fact_id: from_fact_id, to_fact_id: to_fact_id, link_type: link_type)
+      end
+
+      private
+
+      def slugify(type, name)
+        "#{type}:#{name.downcase.gsub(/[^a-z0-9]+/, "_").gsub(/^_|_$/, "")}"
+      end
+    end
+  end
+end

data/lib/claude_memory/store/store_manager.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module ClaudeMemory
+  module Store
+    class StoreManager
+      attr_reader :global_store, :project_store, :project_path
+
+      def initialize(global_db_path: nil, project_db_path: nil, project_path: nil, env: ENV)
+        @project_path = project_path || env["CLAUDE_PROJECT_DIR"] || Dir.pwd
+        @global_db_path = global_db_path || self.class.default_global_db_path(env)
+        @project_db_path = project_db_path || self.class.default_project_db_path(@project_path)
+
+        @global_store = nil
+        @project_store = nil
+      end
+
+      def self.default_global_db_path(env = ENV)
+        home = env["HOME"] || File.expand_path("~")
+        File.join(home, ".claude", "memory.sqlite3")
+      end
+
+      def self.default_project_db_path(project_path = Dir.pwd)
+        File.join(project_path, ".claude", "memory.sqlite3")
+      end
+
+      def ensure_global!
+        return @global_store if @global_store
+
+        FileUtils.mkdir_p(File.dirname(@global_db_path))
+        @global_store = SQLiteStore.new(@global_db_path)
+      end
+
+      def ensure_project!
+        return @project_store if @project_store
+
+        FileUtils.mkdir_p(File.dirname(@project_db_path))
+        @project_store = SQLiteStore.new(@project_db_path)
+      end
+
+      def ensure_both!
+        ensure_global!
+        ensure_project!
+      end
+
+      attr_reader :global_db_path
+
+      attr_reader :project_db_path
+
+      def global_exists?
+        File.exist?(@global_db_path)
+      end
+
+      def project_exists?
+        File.exist?(@project_db_path)
+      end
+
+      def close
+        @global_store&.close
+        @project_store&.close
+        @global_store = nil
+        @project_store = nil
+      end
+
+      def store_for_scope(scope)
+        case scope
+        when "global"
+          ensure_global!
+          @global_store
+        when "project"
+          ensure_project!
+          @project_store
+        else
+          raise ArgumentError, "Invalid scope: #{scope}. Use 'global' or 'project'"
+        end
+      end
+
+      def promote_fact(fact_id)
+        ensure_both!
+
+        fact = @project_store.facts.where(id: fact_id).first
+        return nil unless fact
+
+        subject = @project_store.entities.where(id: fact[:subject_entity_id]).first
+        return nil unless subject
+
+        global_subject_id = @global_store.find_or_create_entity(
+          type: subject[:type],
+          name: subject[:canonical_name]
+        )
+
+        global_object_id = nil
+        if fact[:object_entity_id]
+          object = @project_store.entities.where(id: fact[:object_entity_id]).first
+          if object
+            global_object_id = @global_store.find_or_create_entity(
+              type: object[:type],
+              name: object[:canonical_name]
+            )
+          end
+        end
+
+        global_fact_id = @global_store.insert_fact(
+          subject_entity_id: global_subject_id,
+          predicate: fact[:predicate],
+          object_entity_id: global_object_id,
+          object_literal: fact[:object_literal],
+          datatype: fact[:datatype],
+          polarity: fact[:polarity],
+          valid_from: fact[:valid_from],
+          status: fact[:status],
+          confidence: fact[:confidence],
+          created_from: "promoted:#{@project_path}:#{fact_id}",
+          scope: "global",
+          project_path: nil
+        )
+
+        copy_provenance(fact_id, global_fact_id)
+
+        global_fact_id
+      end
+
+      private
+
+      def copy_provenance(source_fact_id, target_fact_id)
+        @project_store.provenance.where(fact_id: source_fact_id).each do |prov|
+          @global_store.insert_provenance(
+            fact_id: target_fact_id,
+            content_item_id: nil,
+            quote: prov[:quote],
+            attribution_entity_id: nil,
+            strength: prov[:strength]
+          )
+        end
+      end
+    end
+  end
+end

data/lib/claude_memory/sweep/sweeper.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  module Sweep
+    class Sweeper
+      DEFAULT_CONFIG = {
+        proposed_fact_ttl_days: 14,
+        disputed_fact_ttl_days: 30,
+        content_retention_days: 30,
+        default_budget_seconds: 5
+      }.freeze
+
+      def initialize(store, config: {})
+        @store = store
+        @config = DEFAULT_CONFIG.merge(config)
+        @start_time = nil
+        @stats = nil
+      end
+
+      def run!(budget_seconds: nil)
+        budget = budget_seconds || @config[:default_budget_seconds]
+        @start_time = Time.now
+        @stats = {
+          proposed_facts_expired: 0,
+          disputed_facts_expired: 0,
+          orphaned_provenance_deleted: 0,
+          old_content_pruned: 0
+        }
+
+        expire_proposed_facts if within_budget?
+        expire_disputed_facts if within_budget?
+        prune_orphaned_provenance if within_budget?
+        prune_old_content if within_budget?
+
+        @stats[:elapsed_seconds] = Time.now - @start_time
+        @stats[:budget_honored] = @stats[:elapsed_seconds] <= budget
+        @stats
+      end
+
+      private
+
+      def within_budget?
+        budget = @config[:default_budget_seconds]
+        (Time.now - @start_time) < budget
+      end
+
+      def expire_proposed_facts
+        cutoff = (Time.now - @config[:proposed_fact_ttl_days] * 86400).utc.iso8601
+        @stats[:proposed_facts_expired] = @store.facts
+          .where(status: "proposed")
+          .where { created_at < cutoff }
+          .update(status: "expired")
+      end
+
+      def expire_disputed_facts
+        cutoff = (Time.now - @config[:disputed_fact_ttl_days] * 86400).utc.iso8601
+        @stats[:disputed_facts_expired] = @store.facts
+          .where(status: "disputed")
+          .where { created_at < cutoff }
+          .update(status: "expired")
+      end
+
+      def prune_orphaned_provenance
+        fact_ids = @store.facts.select(:id)
+        @stats[:orphaned_provenance_deleted] = @store.provenance
+          .exclude(fact_id: fact_ids)
+          .delete
+      end
+
+      def prune_old_content
+        cutoff = (Time.now - @config[:content_retention_days] * 86400).utc.iso8601
+        referenced_ids = @store.provenance.exclude(content_item_id: nil).select(:content_item_id)
+        @stats[:old_content_pruned] = @store.content_items
+          .where { ingested_at < cutoff }
+          .exclude(id: referenced_ids)
+          .delete
+      end
+    end
+  end
+end

data/lib/claude_memory/templates/hooks.example.json

@@ -0,0 +1,74 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "matcher": "idle_prompt",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}

data/lib/claude_memory/templates/output-styles/memory-aware.md

@@ -0,0 +1,21 @@
+---
+keep-coding-instructions: true
+---
+
+# Memory-Aware Output Style
+
+When making decisions or establishing conventions:
+- State decisions clearly with "We decided to..." or "We agreed to..."
+- Be explicit about technology choices: "We use PostgreSQL for..."
+- Clarify when replacing previous decisions: "We no longer use X, switching to Y"
+- Note conventions with "Convention:" or "Standard:"
+
+When recalling past context:
+- Use the memory.recall MCP tool to find relevant past decisions
+- Cite specific facts when referencing previous work
+- If unsure, use memory.explain to get provenance for a fact
+
+When conflicts arise:
+- Acknowledge contradictions explicitly
+- Use memory.conflicts to see open disputes
+- Help resolve conflicts by providing clear supersession signals

data/lib/claude_memory/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  VERSION = "0.1.0"
+end

data/lib/claude_memory.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module ClaudeMemory
+  class Error < StandardError; end
+
+  LEGACY_DB_PATH = ".claude_memory.sqlite3"
+  PROJECT_DB_PATH = ".claude/memory.sqlite3"
+
+  def self.global_db_path(env = ENV)
+    home = env["HOME"] || File.expand_path("~")
+    File.join(home, ".claude", "memory.sqlite3")
+  end
+
+  def self.project_db_path(project_path = Dir.pwd)
+    File.join(project_path, ".claude", "memory.sqlite3")
+  end
+end
+
+require_relative "claude_memory/version"
+require_relative "claude_memory/cli"
+require_relative "claude_memory/store/sqlite_store"
+require_relative "claude_memory/store/store_manager"
+require_relative "claude_memory/ingest/transcript_reader"
+require_relative "claude_memory/ingest/ingester"
+require_relative "claude_memory/index/lexical_fts"
+require_relative "claude_memory/distill/extraction"
+require_relative "claude_memory/distill/distiller"
+require_relative "claude_memory/distill/null_distiller"
+require_relative "claude_memory/resolve/predicate_policy"
+require_relative "claude_memory/resolve/resolver"
+require_relative "claude_memory/recall"
+require_relative "claude_memory/sweep/sweeper"
+require_relative "claude_memory/mcp/tools"
+require_relative "claude_memory/mcp/server"
+require_relative "claude_memory/publish"
+require_relative "claude_memory/hook/handler"

data/sig/claude_memory.rbs

@@ -0,0 +1,4 @@
+module ClaudeMemory
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end