memoflow 0.1.0

data/lib/memoflow/client.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class Client
+    def initialize(configuration:, repo_path:, env: ENV, embedding_provider: nil)
+      @configuration = configuration
+      @repo_path = Pathname.new(repo_path)
+      @env = env
+      @git = GitContext.new(repo_path: @repo_path, env: @env)
+      @embedding_provider = embedding_provider || EmbeddingProvider.new(configuration: configuration)
+      @store = Store.new(
+        root: configuration.resolved_storage_path(@repo_path),
+        encryptor: Encryptor.new(configuration.encryption_key)
+      )
+    end
+
+    def init!
+      @store.setup!
+    end
+
+    def capture_last_commit
+      capture_commit(@git.last_commit_sha)
+    end
+
+    def last_commit_sha
+      @git.last_commit_sha
+    end
+
+    def capture_commit(sha, task_id: current_task_id)
+      record = @git.capture_commit(sha)
+      record[:task_id] = task_id if task_id
+      record[:embedding] = embed_record(record)
+      return record if @store.commit?(sha)
+
+      @store.write_commit(record)
+      record
+    end
+
+    def annotate(text, tags: [], related_sha: nil, source: "manual")
+      record = {
+        id: SecureRandom.uuid,
+        type: "annotation",
+        source: source,
+        tags: tags,
+        related_sha: related_sha,
+        task_id: current_task_id,
+        summary: text,
+        body: text,
+        timestamp: Time.now.utc.iso8601
+      }
+      record[:embedding] = embed_record(record)
+      @store.write_annotation(record)
+      record
+    end
+
+    def start_task(title, description: nil, tags: [])
+      task_id = SecureRandom.uuid
+      timestamp = Time.now.utc.iso8601
+      task = {
+        id: task_id,
+        type: "task",
+        title: title,
+        description: description,
+        tags: tags,
+        status: "active",
+        created_at: timestamp,
+        updated_at: timestamp,
+        repo_root: @repo_path.to_s
+      }
+      task[:embedding] = embed_record(task)
+      session = start_session(task_id)
+      @store.write_task(task)
+      @store.write_state("current_task", { task_id: task_id, session_id: session[:id], updated_at: timestamp })
+      task.merge(current_session_id: session[:id])
+    end
+
+    def finish_task(task_id = current_task_id, status: "completed")
+      raise Error, "no active task" unless task_id
+
+      task = find_task(task_id)
+      raise Error, "task not found" unless task
+
+      updated = task.merge(status: status, updated_at: Time.now.utc.iso8601)
+      updated[:embedding] = embed_record(updated)
+      @store.write_task(updated)
+      finish_current_session(task_id)
+      clear_current_task if current_task_id == task_id
+      updated
+    end
+
+    def resume_task(task_id)
+      task = find_task(task_id)
+      raise Error, "task not found" unless task
+
+      session = start_session(task_id)
+      now = Time.now.utc.iso8601
+      updated = task.merge(status: "active", updated_at: now)
+      updated[:embedding] = embed_record(updated)
+      @store.write_task(updated)
+      @store.write_state("current_task", { task_id: task_id, session_id: session[:id], updated_at: now })
+      updated.merge(current_session_id: session[:id])
+    end
+
+    def tasks(limit: 20, status: nil)
+      items = @store.read_scope("tasks")
+      items.select! { |task| task[:status] == status } if status
+      items.sort_by { |task| sortable_time(task, :updated_at) }.reverse.first(limit)
+    end
+
+    def current_task
+      task_id = current_task_id
+      task_id ? find_task(task_id) : nil
+    end
+
+    def current_task_id
+      @store.read_state("current_task")&.dig(:task_id)
+    end
+
+    def query(term = nil, limit: 5)
+      entries = @store.read_all
+      query_vector = term.to_s.strip.empty? ? nil : embed_text(term)
+      ranked = entries.map { |entry| [score(entry, term), entry] }
+                      .select { |score_value, _entry| term.to_s.strip.empty? || score_value.positive? }
+                      .sort_by { |score_value, entry| [-score_value, sortable_time(entry)] }
+                      .map(&:last)
+
+      ranked.first(limit).map { |entry| present(entry, query_vector: query_vector) }
+    end
+
+    def context_packet(query: nil, limit: 5)
+      entries = query(query, limit: limit)
+      header = current_task ? "current_task=#{current_task[:title]} status=#{current_task[:status]}" : nil
+      lines = entries.map do |entry|
+        parts = [entry[:type], entry[:timestamp], entry[:summary]]
+        files = entry[:changed_files]
+        parts << "files=#{files.join(",")}" if files && !files.empty?
+        parts.compact.join(" | ")
+      end
+      ([header] + lines).compact.join("\n")
+    end
+
+    private
+
+    def present(entry, query_vector: nil)
+      {
+        id: entry[:id] || entry[:sha],
+        type: entry[:type],
+        timestamp: entry[:timestamp] || entry[:committed_at],
+        summary: entry[:summary] || entry[:subject],
+        body: entry[:body],
+        changed_files: entry[:changed_files],
+        tags: entry[:tags],
+        related_sha: entry[:related_sha],
+        task_id: entry[:task_id],
+        status: entry[:status],
+        title: entry[:title],
+        description: entry[:description],
+        provider: entry[:provider],
+        repository: entry[:repository],
+        pull_request: entry[:pull_request],
+        semantic_score: query_vector ? Vectorizer.similarity(entry[:embedding], query_vector).round(4) : nil
+      }
+    end
+
+    def sortable_time(entry, key = nil)
+      source = key ? entry[key] : (entry[:timestamp] || entry[:committed_at])
+      Time.parse(source || Time.at(0).utc.iso8601)
+    end
+
+    def score(entry, term)
+      return default_score(entry) if term.to_s.strip.empty?
+
+      tokens = term.downcase.split(/\s+/)
+      fields = normalized_fields(entry)
+      score = tokens.sum do |token|
+        field_score(fields, token)
+      end
+
+      score + recency_boost(entry) + task_boost(entry) + semantic_boost(entry, term)
+    end
+
+    def find_task(task_id)
+      @store.read_scope("tasks").reverse.find { |task| task[:id] == task_id }
+    end
+
+    def start_session(task_id)
+      record = {
+        id: SecureRandom.uuid,
+        type: "session",
+        task_id: task_id,
+        started_at: Time.now.utc.iso8601,
+        status: "active"
+      }
+      @store.write_session(record)
+      record
+    end
+
+    def finish_current_session(task_id)
+      current = @store.read_state("current_task")
+      return unless current && current[:task_id] == task_id
+
+      session = @store.read_scope("sessions").reverse.find { |item| item[:id] == current[:session_id] }
+      return unless session
+
+      @store.write_session(session.merge(status: "closed", ended_at: Time.now.utc.iso8601))
+    end
+
+    def clear_current_task
+      @store.write_state("current_task", { task_id: nil, session_id: nil, updated_at: Time.now.utc.iso8601 })
+    end
+
+    def normalized_fields(entry)
+      pr = entry[:pull_request] || {}
+      {
+        summary: entry[:summary].to_s.downcase,
+        subject: entry[:subject].to_s.downcase,
+        body: entry[:body].to_s.downcase,
+        title: entry[:title].to_s.downcase,
+        description: entry[:description].to_s.downcase,
+        files: Array(entry[:changed_files]).join(" ").downcase,
+        tags: Array(entry[:tags]).join(" ").downcase,
+        task_id: entry[:task_id].to_s.downcase,
+        repository: entry[:repository].to_s.downcase,
+        provider: entry[:provider].to_s.downcase,
+        pr_title: pr[:title].to_s.downcase,
+        pr_body: pr[:body].to_s.downcase,
+        pr_number: pr[:number].to_s.downcase
+      }
+    end
+
+    def field_score(fields, token)
+      score = 0
+      score += 6 if exact_or_prefix_match?(fields[:title], token)
+      score += 5 if exact_or_prefix_match?(fields[:subject], token)
+      score += 5 if exact_or_prefix_match?(fields[:summary], token)
+      score += 4 if exact_or_prefix_match?(fields[:pr_title], token)
+      score += 3 if exact_or_prefix_match?(fields[:files], token)
+      score += 2 if exact_or_prefix_match?(fields[:tags], token)
+      score += 2 if exact_or_prefix_match?(fields[:repository], token)
+      score += 1 if exact_or_prefix_match?(fields[:body], token)
+      score += 1 if exact_or_prefix_match?(fields[:description], token)
+      score += 1 if exact_or_prefix_match?(fields[:pr_body], token)
+      score += 1 if exact_or_prefix_match?(fields[:pr_number], token)
+      score += 1 if exact_or_prefix_match?(fields[:provider], token)
+      score += 1 if exact_or_prefix_match?(fields[:task_id], token)
+      score
+    end
+
+    def exact_or_prefix_match?(text, token)
+      return false if text.empty?
+
+      text.split(/\W+/).any? { |part| part == token || part.start_with?(token) } || text.include?(token)
+    end
+
+    def recency_boost(entry)
+      timestamp = sortable_time(entry)
+      age_in_days = ((Time.now.utc - timestamp) / 86_400.0)
+      return 0 if age_in_days.negative?
+      return 2 if age_in_days <= 1
+      return 1 if age_in_days <= 7
+
+      0
+    end
+
+    def task_boost(entry)
+      current_task_id && entry[:task_id] == current_task_id ? 4 : 0
+    end
+
+    def default_score(entry)
+      recency_boost(entry) + task_boost(entry) + 1
+    end
+
+    def semantic_boost(entry, term)
+      vector = entry[:embedding]
+      return 0 if vector.nil? || term.to_s.strip.empty?
+
+      (Vectorizer.similarity(vector, embed_text(term)) * 10).round(4)
+    end
+
+    public
+
+    def export_bundle(path)
+      @store.export_bundle(path)
+    end
+
+    def import_bundle(path)
+      @store.import_bundle(path)
+    end
+
+    def prune!(keep_days: nil, max_records: nil)
+      @store.prune!(keep_days: keep_days, max_records: max_records)
+    end
+
+    def embedding_mode
+      @embedding_provider.enabled? ? "provider" : "local"
+    end
+
+    private
+
+    def embed_record(record)
+      embed_text(Vectorizer.indexable_text(record))
+    end
+
+    def embed_text(text)
+      @embedding_provider.embed(text)
+    end
+  end
+end

data/lib/memoflow/configuration.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class Configuration
+    attr_accessor :storage_path, :encryption_key, :logger, :storage_policy, :server_host, :server_port,
+                  :embedding_command, :embedding_timeout
+
+    def initialize
+      @storage_path = ".memoflow"
+      @encryption_key = ENV["MEMOFLOW_KEY"]
+      @logger = nil
+      @storage_policy = :repo
+      @server_host = "127.0.0.1"
+      @server_port = 4599
+      @embedding_command = nil
+      @embedding_timeout = 5
+    end
+
+    def resolved_storage_path(repo_path)
+      path = configured_storage_path(repo_path)
+      return path if path.absolute?
+
+      Pathname.new(repo_path).join(path)
+    end
+
+    private
+
+    def configured_storage_path(repo_path)
+      return Pathname.new(storage_path) unless storage_path.to_s.empty?
+
+      case storage_policy.to_sym
+      when :external
+        Pathname.new(Dir.home).join(".memoflow", Pathname.new(repo_path).basename)
+      else
+        Pathname.new(".memoflow")
+      end
+    end
+  end
+end

data/lib/memoflow/embedding_provider.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class EmbeddingProvider
+    def initialize(configuration:, runner: nil)
+      @configuration = configuration
+      @runner = runner || method(:default_runner)
+    end
+
+    def enabled?
+      command.any?
+    end
+
+    def embed(text)
+      return fallback(text) unless enabled?
+
+      payload = call_provider(text)
+      vector = payload.is_a?(Array) ? payload : payload["embedding"]
+      return fallback(text) unless vector.is_a?(Array) && !vector.empty?
+
+      normalize(vector.map(&:to_f))
+    rescue JSON::ParserError, Errno::ENOENT, Memoflow::Error
+      fallback(text)
+    end
+
+    private
+
+    def command
+      Array(@configuration.embedding_command)
+    end
+
+    def call_provider(text)
+      result = @runner.call(command, text, @configuration.embedding_timeout)
+      raise Error, "embedding command failed" unless result[:success]
+
+      JSON.parse(result[:output])
+    end
+
+    def fallback(text)
+      Vectorizer.encode(text)
+    end
+
+    def normalize(vector)
+      magnitude = Math.sqrt(vector.sum { |value| value * value })
+      return vector if magnitude.zero?
+
+      vector.map { |value| (value / magnitude).round(6) }
+    end
+
+    def default_runner(command, text, timeout)
+      output = nil
+      status = nil
+      Open3.popen3(*command) do |stdin, stdout, stderr, wait_thr|
+        stdin.write(JSON.generate(text: text))
+        stdin.close
+        if wait_thr.join(timeout)
+          output = stdout.read
+          status = wait_thr.value
+        else
+          Process.kill("TERM", wait_thr.pid)
+          raise Error, "embedding command timed out"
+        end
+        output = stderr.read unless status.success?
+      end
+      { success: status.success?, output: output.to_s }
+    end
+  end
+end

data/lib/memoflow/encryptor.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class Encryptor
+    NONCE_BYTES = 12
+
+    def initialize(secret)
+      raise ConfigurationError, "missing encryption key" if secret.to_s.empty?
+
+      @key = OpenSSL::Digest::SHA256.digest(secret)
+    end
+
+    def encrypt(payload)
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.encrypt
+      cipher.key = @key
+      nonce = SecureRandom.random_bytes(NONCE_BYTES)
+      cipher.iv = nonce
+
+      compressed = Zlib::Deflate.deflate(payload)
+      ciphertext = cipher.update(compressed) + cipher.final
+      tag = cipher.auth_tag
+
+      [nonce, tag, ciphertext].map { |part| [part.bytesize].pack("N") + part }.join
+    end
+
+    def decrypt(blob)
+      nonce, tag, ciphertext = unpack(blob)
+
+      cipher = OpenSSL::Cipher.new("aes-256-gcm")
+      cipher.decrypt
+      cipher.key = @key
+      cipher.iv = nonce
+      cipher.auth_tag = tag
+
+      compressed = cipher.update(ciphertext) + cipher.final
+      Zlib::Inflate.inflate(compressed)
+    end
+
+    private
+
+    def unpack(blob)
+      cursor = 0
+      parts = 3.times.map do
+        length = blob.byteslice(cursor, 4).unpack1("N")
+        cursor += 4
+        part = blob.byteslice(cursor, length)
+        cursor += length
+        part
+      end
+      parts
+    end
+  end
+end

data/lib/memoflow/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class Error < StandardError; end
+  class ConfigurationError < Error; end
+  class GitError < Error; end
+end

data/lib/memoflow/git_context.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class GitContext
+    def initialize(repo_path:, env: ENV)
+      @repo_path = Pathname.new(repo_path)
+      @env = env
+    end
+
+    def ensure_repo!
+      run_git("rev-parse --is-inside-work-tree")
+      true
+    rescue GitError
+      raise GitError, "#{@repo_path} is not a git repository"
+    end
+
+    def last_commit_sha
+      run_git("rev-parse HEAD").strip
+    end
+
+    def capture_commit(sha)
+      ensure_repo!
+
+      subject, body = commit_message_parts(sha)
+      record = {
+        type: "commit",
+        sha: sha,
+        repo_name: @repo_path.basename.to_s,
+        repo_root: repo_root,
+        branch: current_branch,
+        author_name: show(sha, "%an"),
+        author_email: show(sha, "%ae"),
+        committed_at: show(sha, "%aI"),
+        subject: subject,
+        body: body,
+        changed_files: changed_files(sha),
+        summary: [subject, body].reject(&:empty?).join(" | ")
+      }
+      provider_metadata = ProviderContext.new(remote_url: remote_url, repo_path: @repo_path, env: @env).capture
+      record.merge(provider_metadata).merge(embedding: Vectorizer.encode(Vectorizer.indexable_text(record.merge(provider_metadata))))
+    end
+
+    def repo_root
+      run_git("rev-parse --show-toplevel").strip
+    end
+
+    private
+
+    def current_branch
+      run_git("rev-parse --abbrev-ref HEAD").strip
+    end
+
+    def remote_url
+      run_git("config --get remote.origin.url").strip
+    rescue GitError
+      ""
+    end
+
+    def commit_message_parts(sha)
+      message = run_git("log -1 --pretty=%B #{Shellwords.escape(sha)}")
+      lines = message.lines.map(&:rstrip)
+      subject = lines.shift.to_s
+      body = lines.drop_while(&:empty?).join("\n")
+      [subject, body]
+    end
+
+    def changed_files(sha)
+      run_git("diff-tree --root --no-commit-id --name-only -r #{Shellwords.escape(sha)}").lines.map(&:strip).reject(&:empty?)
+    end
+
+    def show(sha, format)
+      run_git("show -s --format=#{Shellwords.escape(format)} #{Shellwords.escape(sha)}").strip
+    end
+
+    def run_git(args)
+      output, status = Open3.capture2e("git", "-C", @repo_path.to_s, *Shellwords.split(args))
+      raise GitError, output.strip unless status.success?
+
+      output
+    end
+  end
+end

data/lib/memoflow/hook_installer.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class HookInstaller
+    def initialize(repo_path:)
+      @repo_path = Pathname.new(repo_path)
+    end
+
+    def install!
+      hooks_dir = @repo_path.join(".git", "hooks")
+      raise GitError, "missing .git/hooks directory" unless hooks_dir.directory?
+
+      write_hook(hooks_dir.join("post-commit"), <<~SH)
+        #!/usr/bin/env sh
+        if command -v bundle >/dev/null 2>&1; then
+          bundle exec memoflow capture --last >/dev/null 2>&1 || true
+        else
+          memoflow capture --last >/dev/null 2>&1 || true
+        fi
+      SH
+
+      write_hook(hooks_dir.join("prepare-commit-msg"), <<~SH)
+        #!/usr/bin/env sh
+        NOTE_FILE=".git/MEMOFLOW_TASK_NOTE"
+        COMMIT_MSG_FILE="$1"
+        if [ -f "$NOTE_FILE" ] && [ -f "$COMMIT_MSG_FILE" ]; then
+          printf "\\n\\nProblem-Statement: %s\\n" "$(cat "$NOTE_FILE")" >> "$COMMIT_MSG_FILE"
+        fi
+      SH
+
+      hooks_dir
+    end
+
+    private
+
+    def write_hook(path, script)
+      File.write(path, script)
+      File.chmod(0o755, path)
+    end
+  end
+end