llmemory 0.2.3 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e44ccb1c23fc659d9607e1eb3181e598a57edb95f47b94df4060ad46bfe7c31
-  data.tar.gz: 5d80e1fefb1dd77cbdc8c0b4d24e588abaf6f18c570db10e3fc0b2c808b09461
+  metadata.gz: eb36583aecef9a4a0d4a89e703d1edf7326112df260ceccd1b181cf1411a45d1
+  data.tar.gz: b91c1b67b6c88c12d0515a03304aa04b0f61bc310acbb6e1b02391fbe9944d08
 SHA512:
-  metadata.gz: edb2f849efc9a6d1dbabc0be0a1210bf21e77f33174b965e3b22e9df3ca90aa536e47152c75891e548d6b43a08d82cfda29afa59d3b2e777aa144f4a3900570f
-  data.tar.gz: a8c84411d9c262dee5b5a0c07835c05816283a17749c1b6b282c75694dc56a497d8fb9f2b18eeccd242a82d5dce36234342ede75a13e2739ad11f99fb23ae005
+  metadata.gz: 597d6cd707b07ebc3c754e2ac67269143c6bff221a22529e692b8a4cc4fc4415180b83f97d7336f95e6eef025c75a18f64819daa740588f032052fccca1a3632
+  data.tar.gz: 7b9ec61f4edb2cc053e86f1f478e7a23c82784732fbc918ca6bf35756583e568c92039c7a1cdf2939c6066df76e85ee99176f03b44c82ae708f2705093cb67e8

data/README.md

@@ -14,6 +14,8 @@ gem "llmemory"
 
 Then run `bundle install`.
 
+**Upgrading?** See the [Migration guide](docs/MIGRATION.md) for database columns, encryption backfill, and graph store configuration changes.
+
 ## Quick Start (Unified API)
 
 The recommended way to use llmemory in a chat is the unified `Llmemory::Memory` API. It abstracts short-term (conversation history) and long-term (extracted facts) and combines retrieval from both:
@@ -51,6 +53,39 @@ memory.clear_session!
 - **`prune!(mode: nil)`** — Prunes oversized tool results (soft-trim or hard-clear). Only when `prune_tool_results_enabled` is true.
 - **`check_context_window!`** — Triggers consolidate and compact when context exceeds configured thresholds.
 - **`clear_session!`** — Clears short-term only.
+- **`llm_usage`** — Returns cumulative LLM token usage for this `user_id` (chat/completions + embeddings), persisted in the short-term store.
+
+## LLM token usage
+
+llmemory captures **real token counts** from OpenAI and Anthropic API responses (chat and embeddings), accumulates them per `user_id`, and exposes them for cost monitoring.
+
+```ruby
+memory = Llmemory::Memory.new(user_id: "user_123")
+memory.consolidate!
+memory.maintain!
+
+usage = memory.llm_usage
+# => {
+#      invoke: { input_tokens: 1200, output_tokens: 400, total_tokens: 1600, calls: 3 },
+#      embed:  { total_tokens: 48, calls: 2 },
+#      updated_at: "2026-07-02T12:00:00Z"
+#    }
+```
+
+| What | Details |
+|------|---------|
+| **Counted** | `consolidate!`, reflection, skill mining, compaction summaries, iterative retrieval, graph/file extraction, OpenAI embeddings (index + search) |
+| **Scope** | Cumulative per `user_id` (not per session); stored under pseudo-session `__llm_usage__` |
+| **Not counted** | `context_tokens` (local byte estimate), retrieval context budget, MCP auth tokens |
+| **Cache** | Embedding cache hits record zero tokens |
+
+**Other surfaces:**
+
+- **CLI:** `llmemory stats USER_ID` prints an `LLM TOKEN USAGE` section.
+- **MCP:** `memory_stats` includes the same totals.
+- **Rails metrics:** subscribe to `llm_invoke.llmemory` and `llm_embed.llmemory` (payload includes `input_tokens`, `output_tokens`, `total_tokens`, `response_chars`).
+
+Dollar cost is not computed — multiply tokens by your model pricing externally. For lower-level access, `Llmemory::LLM::OpenAI#invoke` returns a `Response` with `#content` (via `#to_s`) and `#usage`.
 
 ## Configuration
 
@@ -138,7 +173,7 @@ memory = Llmemory::Memory.new(user_id: "agent-1", encryption_key: "tenant-specif
 **What is encrypted:** conversation checkpoints (redis/postgres/active_record), file-based facts/resources/categories, episodic/procedural documents, graph node names/types/predicates (deterministic) and properties (random IV). **Vector embeddings are not encrypted** (required for pgvector search); associated `text_content` metadata is encrypted.
 
 **Trade-offs:**
-- Database keyword search (`LIKE`, BM25 on encrypted columns) no longer works on ciphertext; file backends still search in memory after decrypt.
+- Database keyword search on encrypted columns requires the `search_tokens` blind-index column (see [Migration guide](docs/MIGRATION.md)); file backends search in memory after decrypt without schema changes.
 - `:memory` backends are in-process only and are **not** encrypted at rest.
 - Existing plaintext data remains readable (markers `enc:v1:` / `encd:v1:`); new writes are encrypted when enabled.
 - Deterministic encryption on graph identifiers leaks equality (same name ⇒ same ciphertext) but keeps graph traversal working.
@@ -685,7 +720,7 @@ MCP_TOKEN=your-secret-token llmemory mcp serve --http --port 443 \
 | `memory_timeline_context` | Get N items before/after a specific memory |
 | `memory_add_message` | Add message to short-term conversation (roles: user, assistant, system, tool, tool_result) |
 | `memory_consolidate` | Extract facts from conversation to long-term |
-| `memory_stats` | Get memory statistics for a user |
+| `memory_stats` | Get memory statistics for a user (includes LLM token usage) |
 | `memory_info` | Documentation on how to use the tools |
 | `memory_episode_record` / `memory_episodes` | Record / list episodic trajectories |
 | `memory_skill_register` / `memory_skill_report` / `memory_skills` | Register / outcome-track / list procedural skills |

data/lib/generators/llmemory/install/templates/create_llmemory_tables.rb

@@ -6,6 +6,7 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :id, null: false, primary_key: true
       t.string :user_id, null: false
       t.text :text, null: false
+      t.text :search_tokens
       t.timestamps
     end
     add_index :llmemory_resources, :user_id
@@ -18,6 +19,7 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :source_resource_id
       t.float :importance, default: 0.7
       t.jsonb :provenance
+      t.text :search_tokens
       t.timestamps
     end
     add_index :llmemory_items, :user_id
@@ -36,6 +38,7 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :user_id, null: false
       t.jsonb :data, null: false, default: {}
       t.text :search_text
+      t.text :search_tokens
       t.datetime :archived_at
       t.timestamps
     end
@@ -47,6 +50,8 @@ class CreateLlmemoryTables < ActiveRecord::Migration[7.0]
       t.string :user_id, null: false
       t.jsonb :data, null: false, default: {}
       t.text :search_text
+      t.text :search_tokens
+      t.text :name_det
       t.datetime :archived_at
       t.timestamps
     end

data/lib/llmemory/cli/commands/stats.rb

@@ -41,6 +41,11 @@ module Llmemory
             puts "Long-term (file) categories: #{storage.list_categories(user_id).size}"
             puts "Long-term (file) resources: #{storage.list_resources(user_id: user_id).size}"
           end
+
+          puts "---"
+          puts Llmemory::LLM::UsageLedger.format_text(
+            Llmemory::LLM::UsageLedger.new(store: short_store).totals(user_id)
+          )
         end
 
         def print_global_stats(short_store, long_type)

data/lib/llmemory/crypto/cipher.rb

@@ -36,6 +36,10 @@ module Llmemory
       def encrypted?(str)
         false
       end
+
+      def blind_index(token)
+        token.to_s.downcase
+      end
     end
 
     # AES-256-GCM encryption with separate content (random IV) and index
@@ -111,6 +115,14 @@ module Llmemory
         s.start_with?(MARKER) || s.start_with?(DETERMINISTIC_MARKER)
       end
 
+      # Deterministic HMAC digest for blind-index keyword search over encrypted fields.
+      def blind_index(token)
+        str = token.to_s.downcase
+        return str if str.empty?
+
+        OpenSSL::HMAC.hexdigest("SHA256", @index_key, str)[0, 32]
+      end
+
       private
 
       def encrypt_with_key(plaintext, key, iv:, marker:)

data/lib/llmemory/crypto/field_helpers.rb

@@ -105,6 +105,31 @@ module Llmemory
       rescue JSON::ParserError
         nil
       end
+
+      # Space-delimited blind-index digests for encrypted keyword search.
+      def search_tokens_for(text)
+        tokens = Llmemory::Tokenizer.tokenize(text).uniq
+        return nil if tokens.empty?
+
+        digests = tokens.map { |t| cipher.blind_index(t) }
+        " #{digests.join(' ')} "
+      end
+
+      # OR-of-token SQL filter. Uses blind index on `search_tokens_column` when
+      # encryption is enabled; otherwise LIKE on the plaintext `column`.
+      def blind_token_filter(column, query, start_index, search_tokens_column: nil)
+        tokens = Llmemory::Tokenizer.tokenize(query)
+        return ["", []] if tokens.empty?
+
+        if cipher.enabled? && search_tokens_column
+          digests = tokens.map { |t| cipher.blind_index(t) }
+          likes = digests.each_index.map { |i| "#{search_tokens_column} LIKE $#{start_index + i}" }
+          [" AND (#{likes.join(' OR ')})", digests.map { |d| "% #{d} %" }]
+        else
+          likes = tokens.each_index.map { |i| "LOWER(#{column}) LIKE $#{start_index + i}" }
+          [" AND (#{likes.join(' OR ')})", tokens.map { |t| "%#{t}%" }]
+        end
+      end
     end
   end
 end

data/lib/llmemory/instrumentation.rb

@@ -10,8 +10,10 @@ module Llmemory
   # Events (payload keys are best-effort; subscribers should treat them as
   # optional):
   #
-  #   llm_invoke.llmemory       provider:, model:, prompt_chars:, response_chars:
-  #   llm_embed.llmemory        provider:, model:, text_chars:, dimensions:
+  #   llm_invoke.llmemory       provider:, model:, prompt_chars:, response_chars:,
+  #                             input_tokens:, output_tokens:, total_tokens:
+  #   llm_embed.llmemory        provider:, model:, text_chars:, input_tokens:,
+  #                             output_tokens:, total_tokens:
   #   memory_write.llmemory     memory_type:, user_id:
   #   memory_forget.llmemory    memory_type:, user_id:, count:
   #   retrieve.llmemory         query_chars:, candidates:, results:

data/lib/llmemory/llm/anthropic.rb

@@ -11,6 +11,7 @@ module Llmemory
       DEFAULT_MODEL = "claude-sonnet-4-6"
 
       def initialize(api_key: nil, model: nil, base_url: nil)
+        super()
         @api_key = api_key || config.llm_api_key || ENV["ANTHROPIC_API_KEY"]
         @model = model || config.llm_model || DEFAULT_MODEL
         @base_url = base_url || config.llm_base_url || DEFAULT_BASE_URL
@@ -18,7 +19,8 @@ module Llmemory
 
       def invoke(prompt)
         result = nil
-        Llmemory::Instrumentation.instrument(:llm_invoke, provider: :anthropic, model: @model, prompt_chars: prompt.to_s.length) do
+        payload = { provider: :anthropic, model: @model, prompt_chars: prompt.to_s.length }
+        Llmemory::Instrumentation.instrument(:llm_invoke, payload) do
           response = connection.post("v1/messages") do |req|
             req.body = {
               model: @model,
@@ -33,8 +35,11 @@ module Llmemory
           raise Llmemory::LLMError, "Anthropic API error: #{response.body}" unless response.success?
 
           body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
-          content = body.dig("content", 0, "text")
-          result = content&.strip || ""
+          content = body.dig("content", 0, "text")&.strip || ""
+          usage = parse_anthropic_usage(body["usage"])
+          record_usage(usage)
+          payload.merge!(instrumentation_payload(usage, content))
+          result = Response.new(content, usage: usage)
         end
         result
       end

data/lib/llmemory/llm/base.rb

@@ -1,8 +1,17 @@
 # frozen_string_literal: true
 
+require_relative "usage"
+require_relative "response"
+
 module Llmemory
   module LLM
     class Base
+      attr_reader :last_usage
+
+      def initialize(*)
+        @last_usage = Usage.zero
+      end
+
       def invoke(prompt)
         raise NotImplementedError, "#{self.class}#invoke must be implemented"
       end
@@ -18,6 +27,39 @@ module Llmemory
       def config
         Llmemory.configuration
       end
+
+      def parse_openai_chat_usage(raw)
+        return Usage.zero unless raw.is_a?(Hash)
+
+        Usage.new(
+          input_tokens: raw["prompt_tokens"] || raw[:prompt_tokens] || 0,
+          output_tokens: raw["completion_tokens"] || raw[:completion_tokens] || 0,
+          total_tokens: raw["total_tokens"] || raw[:total_tokens]
+        )
+      end
+
+      def parse_anthropic_usage(raw)
+        return Usage.zero unless raw.is_a?(Hash)
+
+        input = raw["input_tokens"] || raw[:input_tokens] || 0
+        output = raw["output_tokens"] || raw[:output_tokens] || 0
+        Usage.new(input_tokens: input, output_tokens: output)
+      end
+
+      def parse_openai_embed_usage(raw)
+        return Usage.zero unless raw.is_a?(Hash)
+
+        total = raw["total_tokens"] || raw[:total_tokens] || 0
+        Usage.new(input_tokens: 0, output_tokens: 0, total_tokens: total)
+      end
+
+      def record_usage(usage)
+        @last_usage = usage
+      end
+
+      def instrumentation_payload(usage, content, extra = {})
+        usage.to_h.merge(response_chars: content.to_s.length).merge(extra)
+      end
     end
   end
 end

data/lib/llmemory/llm/openai.rb

@@ -11,6 +11,7 @@ module Llmemory
       DEFAULT_MODEL = "gpt-4"
 
       def initialize(api_key: nil, model: nil, base_url: nil)
+        super()
         @api_key = api_key || config.llm_api_key
         @model = model || config.llm_model || DEFAULT_MODEL
         @base_url = base_url || config.llm_base_url || DEFAULT_BASE_URL
@@ -18,7 +19,8 @@ module Llmemory
 
       def invoke(prompt)
         result = nil
-        Llmemory::Instrumentation.instrument(:llm_invoke, provider: :openai, model: @model, prompt_chars: prompt.to_s.length) do
+        payload = { provider: :openai, model: @model, prompt_chars: prompt.to_s.length }
+        Llmemory::Instrumentation.instrument(:llm_invoke, payload) do
           response = connection.post("chat/completions") do |req|
             req.body = {
               model: @model,
@@ -32,7 +34,11 @@ module Llmemory
           raise Llmemory::LLMError, "OpenAI API error: #{response.body}" unless response.success?
 
           body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
-          result = body.dig("choices", 0, "message", "content")&.strip || ""
+          content = body.dig("choices", 0, "message", "content")&.strip || ""
+          usage = parse_openai_chat_usage(body["usage"])
+          record_usage(usage)
+          payload.merge!(instrumentation_payload(usage, content))
+          result = Response.new(content, usage: usage)
         end
         result
       end
@@ -54,18 +60,27 @@ module Llmemory
             }
           }
         }
-        response = connection.post("chat/completions") do |req|
-          req.body = payload.to_json
-          req.headers["Content-Type"] = "application/json"
-          req.headers["Authorization"] = "Bearer #{@api_key}"
-        end
+        parsed = nil
+        instrument_payload = { provider: :openai, model: @model, prompt_chars: prompt.to_s.length }
+        Llmemory::Instrumentation.instrument(:llm_invoke, instrument_payload) do
+          response = connection.post("chat/completions") do |req|
+            req.body = payload.to_json
+            req.headers["Content-Type"] = "application/json"
+            req.headers["Authorization"] = "Bearer #{@api_key}"
+          end
 
-        raise Llmemory::LLMError, "OpenAI API error: #{response.body}" unless response.success?
+          raise Llmemory::LLMError, "OpenAI API error: #{response.body}" unless response.success?
+
+          body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
+          content = body.dig("choices", 0, "message", "content")&.strip
+          usage = parse_openai_chat_usage(body["usage"])
+          record_usage(usage)
+          instrument_payload.merge!(instrumentation_payload(usage, content.to_s))
+          return {} if content.nil? || content.empty?
 
-        body = response.body.is_a?(Hash) ? response.body : JSON.parse(response.body.to_s)
-        content = body.dig("choices", 0, "message", "content")&.strip
-        return {} if content.nil? || content.empty?
-        JSON.parse(content)
+          parsed = JSON.parse(content)
+        end
+        parsed
       rescue JSON::ParserError => e
         raise Llmemory::LLMError, "Failed to parse JSON response: #{e.message}"
       end

data/lib/llmemory/llm/response.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module LLM
+    class Response
+      attr_reader :content, :usage
+
+      def initialize(content, usage: Usage.zero)
+        @content = content.to_s
+        @usage = usage
+      end
+
+      def to_s
+        @content
+      end
+    end
+  end
+end

data/lib/llmemory/llm/tracking_client.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require_relative "usage_recorder"
+
+module Llmemory
+  module LLM
+    # Transparent wrapper that records token usage to the per-user ledger.
+    class TrackingClient
+      def initialize(inner, user_id:, store: nil, api_key: nil)
+        @inner = inner
+        @user_id = user_id
+        @store = store
+        @api_key = api_key
+      end
+
+      def invoke(prompt)
+        response = inner_client.invoke(prompt)
+        usage = if response.respond_to?(:usage)
+                  response.usage
+                elsif inner_client.respond_to?(:last_usage)
+                  inner_client.last_usage
+                else
+                  Usage.zero
+                end
+        UsageRecorder.record(user_id: @user_id, usage: usage, operation: :invoke, store: @store)
+        response
+      end
+
+      def invoke_with_json_schema(prompt, json_schema)
+        result = inner_client.invoke_with_json_schema(prompt, json_schema)
+        usage = inner_client.respond_to?(:last_usage) ? inner_client.last_usage : Usage.zero
+        UsageRecorder.record(user_id: @user_id, usage: usage, operation: :invoke, store: @store)
+        result
+      end
+
+      def last_usage
+        return inner_client.last_usage if inner_client.respond_to?(:last_usage)
+
+        Usage.zero
+      end
+
+      def respond_to?(method, include_private = false)
+        inner_client.respond_to?(method, include_private) || super
+      end
+
+      def method_missing(method, *args, &block)
+        if inner_client.respond_to?(method)
+          inner_client.public_send(method, *args, &block)
+        else
+          super
+        end
+      end
+
+      private
+
+      def inner_client
+        @inner_client ||= @inner || Llmemory::LLM.client(api_key: @api_key)
+      end
+    end
+  end
+end

data/lib/llmemory/llm/usage.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Llmemory
+  module LLM
+    class Usage
+      attr_reader :input_tokens, :output_tokens, :total_tokens
+
+      def initialize(input_tokens:, output_tokens:, total_tokens: nil)
+        @input_tokens = input_tokens.to_i
+        @output_tokens = output_tokens.to_i
+        @total_tokens = total_tokens.nil? ? (@input_tokens + @output_tokens) : total_tokens.to_i
+      end
+
+      def self.zero
+        new(input_tokens: 0, output_tokens: 0, total_tokens: 0)
+      end
+
+      def +(other)
+        self.class.new(
+          input_tokens: @input_tokens + other.input_tokens,
+          output_tokens: @output_tokens + other.output_tokens,
+          total_tokens: @total_tokens + other.total_tokens
+        )
+      end
+
+      def to_h
+        { input_tokens: @input_tokens, output_tokens: @output_tokens, total_tokens: @total_tokens }
+      end
+    end
+  end
+end

data/lib/llmemory/llm/usage_ledger.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "../short_term/stores"
+
+module Llmemory
+  module LLM
+    # Cumulative LLM token usage per user, persisted in the short-term store
+    # under a pseudo-session key (same pattern as ForgetLog).
+    class UsageLedger
+      SESSION_KEY = "__llm_usage__"
+
+      def initialize(store: nil)
+        @store = store || ShortTerm::Stores.build
+      end
+
+      def record(user_id, usage, operation:)
+        state = load_raw(user_id)
+        case operation.to_sym
+        when :invoke
+          bucket = symbolize_bucket(state[:invoke] || state["invoke"])
+          state = state.merge(
+            invoke: {
+              input_tokens: bucket[:input_tokens] + usage.input_tokens,
+              output_tokens: bucket[:output_tokens] + usage.output_tokens,
+              total_tokens: bucket[:total_tokens] + usage.total_tokens,
+              calls: bucket[:calls] + 1
+            }
+          )
+        when :embed
+          bucket = symbolize_bucket(state[:embed] || state["embed"], embed: true)
+          state = state.merge(
+            embed: {
+              total_tokens: bucket[:total_tokens] + usage.total_tokens,
+              calls: bucket[:calls] + 1
+            }
+          )
+        else
+          return totals(user_id)
+        end
+        state[:updated_at] = Time.now.iso8601
+        @store.save(user_id, SESSION_KEY, stringify(state))
+        totals(user_id)
+      end
+
+      def totals(user_id)
+        normalize(load_raw(user_id))
+      end
+
+      def reset!(user_id)
+        empty = default_state
+        @store.save(user_id, SESSION_KEY, stringify(empty))
+        empty
+      end
+
+      def self.format_text(totals)
+        inv = totals[:invoke]
+        emb = totals[:embed]
+        lines = [
+          "LLM TOKEN USAGE:",
+          "  Chat/completions: #{inv[:total_tokens]} total (#{inv[:input_tokens]} in, #{inv[:output_tokens]} out, #{inv[:calls]} calls)",
+          "  Embeddings: #{emb[:total_tokens]} total (#{emb[:calls]} calls)"
+        ]
+        lines << "  Last updated: #{totals[:updated_at]}" if totals[:updated_at]
+        lines.join("\n")
+      end
+
+      private
+
+      def load_raw(user_id)
+        state = @store.load(user_id, SESSION_KEY)
+        return default_state unless state.is_a?(Hash)
+        normalize(state)
+      end
+
+      def default_state
+        {
+          invoke: { input_tokens: 0, output_tokens: 0, total_tokens: 0, calls: 0 },
+          embed: { total_tokens: 0, calls: 0 },
+          updated_at: nil
+        }
+      end
+
+      def normalize(state)
+        invoke = symbolize_bucket(state[:invoke] || state["invoke"])
+        embed = symbolize_bucket(state[:embed] || state["embed"], embed: true)
+        {
+          invoke: invoke,
+          embed: embed,
+          updated_at: state[:updated_at] || state["updated_at"]
+        }
+      end
+
+      def symbolize_bucket(bucket, embed: false)
+        bucket = {} unless bucket.is_a?(Hash)
+        if embed
+          {
+            total_tokens: (bucket[:total_tokens] || bucket["total_tokens"] || 0).to_i,
+            calls: (bucket[:calls] || bucket["calls"] || 0).to_i
+          }
+        else
+          {
+            input_tokens: (bucket[:input_tokens] || bucket["input_tokens"] || 0).to_i,
+            output_tokens: (bucket[:output_tokens] || bucket["output_tokens"] || 0).to_i,
+            total_tokens: (bucket[:total_tokens] || bucket["total_tokens"] || 0).to_i,
+            calls: (bucket[:calls] || bucket["calls"] || 0).to_i
+          }
+        end
+      end
+
+      def stringify(state)
+        state.transform_keys(&:to_s).transform_values do |v|
+          v.is_a?(Hash) ? v.transform_keys(&:to_s) : v
+        end
+      end
+    end
+  end
+end

data/lib/llmemory/llm/usage_recorder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative "usage_ledger"
+
+module Llmemory
+  module LLM
+    module UsageRecorder
+      module_function
+
+      def record(user_id:, usage:, operation:, store: nil)
+        return if user_id.nil? || user_id.to_s.empty?
+        return if usage.nil?
+
+        UsageLedger.new(store: store).record(user_id, usage, operation: operation)
+      end
+
+      def record_embed_from_store(user_id:, vector_store:, store: nil)
+        usage = embed_usage_from(vector_store)
+        return unless usage
+
+        record(user_id: user_id, usage: usage, operation: :embed, store: store)
+      end
+
+      def embed_usage_from(vector_store)
+        return nil unless vector_store
+
+        if vector_store.respond_to?(:last_usage)
+          usage = vector_store.last_usage
+          return usage unless usage.nil?
+        end
+
+        provider = vector_store.instance_variable_get(:@embedding_provider) if vector_store.instance_variable_defined?(:@embedding_provider)
+        provider&.last_usage if provider&.respond_to?(:last_usage)
+      end
+    end
+  end
+end

data/lib/llmemory/llm.rb

@@ -1,6 +1,11 @@
 # frozen_string_literal: true
 
 require_relative "llm/base"
+require_relative "llm/usage"
+require_relative "llm/response"
+require_relative "llm/usage_ledger"
+require_relative "llm/usage_recorder"
+require_relative "llm/tracking_client"
 require_relative "llm/openai"
 require_relative "llm/anthropic"
 

data/lib/llmemory/long_term/episodic/memory.rb

@@ -135,6 +135,7 @@ module Llmemory
           vs = vector_store
           return if vs.nil? || text.to_s.strip.empty?
           embedding = vs.embed(text)
+          record_embed_usage(vs)
           return unless embedding
           vs.store(id: id, embedding: embedding, metadata: { text: text, created_at: Time.now }, user_id: @user_id)
         rescue StandardError
@@ -142,7 +143,9 @@ module Llmemory
         end
 
         def vector_candidates(query, top_k, vs)
-          vs.search_by_text(query.to_s, top_k: top_k, user_id: @user_id).filter_map do |r|
+          results = vs.search_by_text(query.to_s, top_k: top_k, user_id: @user_id)
+          record_embed_usage(vs)
+          results.filter_map do |r|
             raw = @storage.get_episode(@user_id, r[:id] || r["id"])
             raw && candidate_for(raw, (r[:score] || r["score"] || 1.0).to_f)
           end
@@ -183,6 +186,14 @@ module Llmemory
           return nil if actions.empty?
           "Episode with #{normalized.size} step(s): #{actions.join(' -> ')}"
         end
+
+        def record_embed_usage(vector_store)
+          Llmemory::LLM::UsageRecorder.record_embed_from_store(
+            user_id: @user_id,
+            vector_store: vector_store,
+            store: Llmemory::ShortTerm::Stores.build(cipher: @cipher)
+          )
+        end
       end
     end
   end