memoflow 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 97fdae7d1b162b5a4cae8ca5e7fcb1aba0fae6bf25e03361a4c54eccb7416272
+  data.tar.gz: d0373fbe16f0381c29762c5863cfb19a28c4d66bd243fe388a59db5a1b349efd
+SHA512:
+  metadata.gz: ffbd60efe40c52e1c1226be2352faae6cfbf54eb07711bb4618c4377deb761a0feb6890d8a2a34e8d34149d9d2051b9c386265e9bcfbded591a0f24c7a82ce87
+  data.tar.gz: 14cc267c251c5641f361ccf2a0907e17839982793aab811cef1d06e69a44dfdded7948408e1228fc36efa58478a01c37543a78c2d13cd83a4be7e4e6949e9579

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,198 @@
+# Memoflow
+
+Memoflow is a lightweight Ruby gem that captures repository context for AI coding assistants. It stores commit metadata, task notes, and problem statements in compressed and encrypted records with a small local query API and CLI.
+
+## What it captures
+
+- Git commit metadata: sha, author, timestamp, subject, body, changed files
+- Task and session records with active-task linkage to captured commits
+- Optional task annotations and problem statements
+- GitHub/GitLab pull request metadata when available from local environment
+- Repository metadata for retrieval and AI session warm-up
+- Compact hashed vectors for semantic-style retrieval without an external service
+
+## Installation
+
+Add the gem to your project:
+
+```ruby
+gem "memoflow"
+```
+
+Then configure it with one initializer:
+
+```ruby
+Memoflow.configure do |config|
+  config.encryption_key = ENV.fetch("MEMOFLOW_KEY")
+end
+```
+
+If you do not want a Rails initializer, the CLI can operate with `MEMOFLOW_KEY` alone.
+
+Optional embedding provider:
+
+```ruby
+Memoflow.configure do |config|
+  config.encryption_key = ENV.fetch("MEMOFLOW_KEY")
+  config.embedding_command = ["ruby", "script/embedder.rb"]
+  config.embedding_timeout = 5
+end
+```
+
+The embedding command receives JSON on stdin:
+
+```json
+{"text":"your text here"}
+```
+
+It must print either:
+
+```json
+[0.1, 0.2, 0.3]
+```
+
+or:
+
+```json
+{"embedding":[0.1, 0.2, 0.3]}
+```
+
+Optional external storage:
+
+```ruby
+Memoflow.configure do |config|
+  config.encryption_key = ENV.fetch("MEMOFLOW_KEY")
+  config.storage_policy = :external
+  config.storage_path = File.expand_path("~/secure-memories/my_app")
+end
+```
+
+## Quick start
+
+Initialize storage in the repository:
+
+```bash
+bundle exec memoflow init
+bundle exec memoflow install-hook
+bundle exec memoflow task start "Fix webhook retry handling"
+bundle exec memoflow task note "Sentry shows duplicate retries after timeout"
+bundle exec memoflow capture --last
+bundle exec memoflow annotate "Problem statement: fix webhook retries"
+bundle exec memoflow query "webhook retries"
+```
+
+Rails initializer example:
+
+```ruby
+# config/initializers/memoflow.rb
+Memoflow.configure do |config|
+  config.encryption_key = ENV.fetch("MEMOFLOW_KEY")
+  config.storage_policy = :repo
+end
+```
+
+## Storage design
+
+- Records are stored under `.memoflow` by default
+- Each record is JSON, compressed with `Zlib::Deflate`, then encrypted with `AES-256-GCM`
+- Storage location is configurable and can live inside or outside the repository
+- Active task/session state is also encrypted on disk so commit capture can link work automatically
+
+## AI integration
+
+Use the Ruby API:
+
+```ruby
+client = Memoflow.client(repo_path: Dir.pwd)
+client.capture_last_commit
+client.annotate("Investigating flaky job retries", tags: ["task"])
+
+context = client.query("job retries", limit: 5)
+context.each do |entry|
+  puts "#{entry[:type]} #{entry[:timestamp]} #{entry[:summary]}"
+end
+```
+
+Build a compact session packet:
+
+```ruby
+packet = client.context_packet(query: "continue work on retries")
+puts packet
+```
+
+Expose the data to an AI assistant over local HTTP:
+
+```bash
+bundle exec memoflow serve 4599
+curl "http://127.0.0.1:4599/query?q=retry"
+curl "http://127.0.0.1:4599/context?q=retry"
+```
+
+Retrieval ranking is task-aware and weights matches in:
+
+- active task linkage
+- commit subject and summaries
+- task titles/descriptions
+- changed file paths
+- PR titles and bodies
+- recent activity
+
+It also blends in a compact vector similarity score built from hashed token embeddings stored with each record.
+If `embedding_command` is configured, Memoflow uses that provider and falls back to local hashed vectors on any failure.
+
+If local provider CLIs are installed, Memoflow will also try:
+
+- `gh pr view --json number,title,body`
+- `glab mr view --output json`
+
+This is optional and only runs locally.
+
+## Backup and retention
+
+Export the encrypted store to a portable bundle:
+
+```bash
+bundle exec memoflow export tmp/memoflow.bundle
+bundle exec memoflow import tmp/memoflow.bundle
+```
+
+Prune older records or cap store size:
+
+```bash
+bundle exec memoflow prune --days 30
+bundle exec memoflow prune --max 500
+```
+
+## Hook strategy
+
+`memoflow install-hook` installs:
+
+- `post-commit` to capture the newest commit
+- `prepare-commit-msg` to append a saved task/problem note into the commit message as `Problem-Statement: ...`
+
+Use `memoflow task note "..."` before committing to persist a one-off problem statement into `.git/MEMOFLOW_TASK_NOTE`.
+
+## Security notes
+
+- Set `MEMOFLOW_KEY` to a project-specific secret
+- The key is not written to disk
+- Records are authenticated with GCM tags
+- Query output is decrypted only when requested
+- The local HTTP server binds to `127.0.0.1` by default
+- PR metadata is captured only from local git/CI environment, not from network calls
+- Export bundles are encrypted with the same configured key
+- Provider embeddings are optional; the default path stays fully local and offline
+
+## Development
+
+```bash
+bundle exec rake test
+```
+
+## Release checklist
+
+```bash
+ruby -Ilib:test test/memoflow_test.rb
+ruby -Ilib bin/memoflow init
+gem build memoflow.gemspec
+```

data/bin/memoflow

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+require_relative "../lib/memoflow"
+
+Memoflow::CLI.start(ARGV)

data/examples/embedder.rb

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "json"
+
+input = JSON.parse($stdin.read)
+text = input.fetch("text", "")
+tokens = text.downcase.scan(/[a-z0-9_]+/)
+
+embedding = Array.new(8, 0.0)
+tokens.each_with_index do |token, index|
+  embedding[index % embedding.length] += token.length
+end
+
+puts JSON.generate(embedding: embedding)

data/lib/memoflow/cli.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Memoflow
+  class CLI
+    class << self
+      def start(argv)
+        command = argv.shift
+
+        case command
+        when "init" then init
+        when "capture" then capture(argv)
+        when "annotate" then annotate(argv)
+        when "query" then query(argv)
+        when "task" then task(argv)
+        when "context" then context(argv)
+        when "serve" then serve(argv)
+        when "export" then export_bundle(argv)
+        when "import" then import_bundle(argv)
+        when "prune" then prune(argv)
+        when "install-hook" then install_hook
+        else
+          puts usage
+          exit(command ? 1 : 0)
+        end
+      rescue Memoflow::Error => e
+        warn("memoflow: #{e.message}")
+        exit(1)
+      end
+
+      private
+
+      def client
+        Memoflow.client(repo_path: Dir.pwd)
+      end
+
+      def init
+        client.init!
+        puts JSON.pretty_generate(
+          storage: Memoflow.configuration.resolved_storage_path(Dir.pwd).to_s,
+          embedding_mode: client.embedding_mode
+        )
+      end
+
+      def capture(argv)
+        sha = argv[0] if argv[0] && !argv[0].start_with?("--")
+        sha = client.last_commit_sha if argv.include?("--last") || sha.nil?
+        record = client.capture_commit(sha)
+        puts JSON.pretty_generate(record)
+      end
+
+      def annotate(argv)
+        text = argv.join(" ").strip
+        raise Error, "annotation text is required" if text.empty?
+
+        record = client.annotate(text)
+        puts JSON.pretty_generate(record)
+      end
+
+      def query(argv)
+        term = argv.join(" ").strip
+        puts JSON.pretty_generate(client.query(term.empty? ? nil : term))
+      end
+
+      def install_hook
+        path = HookInstaller.new(repo_path: Dir.pwd).install!
+        puts "installed #{path}"
+      end
+
+      def task(argv)
+        subcommand = argv.shift
+        case subcommand
+        when "start"
+          title = argv.join(" ").strip
+          raise Error, "task title is required" if title.empty?
+
+          puts JSON.pretty_generate(client.start_task(title))
+        when "finish"
+          id = argv.shift
+          puts JSON.pretty_generate(client.finish_task(id))
+        when "resume"
+          id = argv.shift
+          raise Error, "task id is required" if id.to_s.empty?
+
+          puts JSON.pretty_generate(client.resume_task(id))
+        when "list"
+          puts JSON.pretty_generate(client.tasks)
+        when "current"
+          puts JSON.pretty_generate(client.current_task)
+        when "note"
+          text = argv.join(" ").strip
+          raise Error, "task note is required" if text.empty?
+
+          File.write(File.join(".git", "MEMOFLOW_TASK_NOTE"), text)
+          puts "saved task note"
+        else
+          raise Error, "unknown task command"
+        end
+      end
+
+      def context(argv)
+        term = argv.join(" ").strip
+        puts client.context_packet(query: term.empty? ? nil : term)
+      end
+
+      def serve(argv)
+        port = argv[0] ? Integer(argv[0]) : Memoflow.configuration.server_port
+        server = Server.new(
+          client: client,
+          host: Memoflow.configuration.server_host,
+          port: port
+        )
+        puts "memoflow listening on http://#{Memoflow.configuration.server_host}:#{port}"
+        server.start
+      end
+
+      def export_bundle(argv)
+        path = argv.shift
+        raise Error, "export path is required" if path.to_s.empty?
+
+        puts client.export_bundle(path)
+      end
+
+      def import_bundle(argv)
+        path = argv.shift
+        raise Error, "import path is required" if path.to_s.empty?
+
+        client.import_bundle(path)
+        puts "imported #{path}"
+      end
+
+      def prune(argv)
+        keep_days = nil
+        max_records = nil
+        until argv.empty?
+          flag = argv.shift
+          case flag
+          when "--days" then keep_days = Integer(argv.shift)
+          when "--max" then max_records = Integer(argv.shift)
+          else
+            raise Error, "unknown prune option #{flag}"
+          end
+        end
+
+        removed = client.prune!(keep_days: keep_days, max_records: max_records)
+        puts JSON.pretty_generate(removed: removed, count: removed.length)
+      end
+
+      def usage
+        <<~TEXT
+          Usage:
+            memoflow init
+            memoflow capture [SHA|--last]
+            memoflow annotate TEXT
+            memoflow query [TERM]
+            memoflow context [TERM]
+            memoflow task start TITLE
+            memoflow task finish [TASK_ID]
+            memoflow task resume TASK_ID
+            memoflow task list
+            memoflow task current
+            memoflow task note TEXT
+            memoflow serve [PORT]
+            memoflow export PATH
+            memoflow import PATH
+            memoflow prune [--days N] [--max N]
+            memoflow install-hook
+        TEXT
+      end
+    end
+  end
+end