pocketrb 0.1.0 → 0.3.0

data/lib/pocketrb/config.rb

@@ -5,12 +5,17 @@ require "yaml"
 module Pocketrb
   # Configuration management
   class Config
+    # Default configuration filename
     CONFIG_FILE = "config.yml"
+    # Configuration directory name
     CONFIG_DIR = ".pocketrb"
 
+    # Default configuration values
     DEFAULTS = {
       provider: "anthropic",
-      model: "claude-sonnet-4-20250514",
+      model: "claude-sonnet-5-5",
+      compaction_model: nil,
+      compaction_pressure: nil,
       max_iterations: 50,
       heartbeat_interval: 1800, # 30 minutes (1800s)
       mcp_endpoint: "http://localhost:7878",
@@ -21,6 +26,8 @@ module Pocketrb
 
     attr_reader :workspace, :data
 
+    # Initialize configuration
+    # @param workspace [String, Pathname, nil] Workspace directory path for loading workspace-specific config
     def initialize(workspace: nil)
       @workspace = workspace ? Pathname.new(workspace) : nil
       @data = DEFAULTS.dup
@@ -28,32 +35,46 @@ module Pocketrb
     end
 
     # Get a config value
+    # @param key [String, Symbol] Configuration key to retrieve
+    # @return [Object, nil] Configuration value or nil if not found
     def [](key)
       @data[key.to_sym] || @data[key.to_s]
     end
 
     # Set a config value
+    # @param key [String, Symbol] Configuration key to set
+    # @param value [Object] Configuration value (string, number, boolean, hash, etc.)
+    # @return [Object] The stored value
     def []=(key, value)
       @data[key.to_sym] = value
     end
 
     # Get with default
+    # @param key [String, Symbol] Configuration key to retrieve
+    # @param default [Object, nil] Default value if key not found
+    # @return [Object] Configuration value or default
     def get(key, default = nil)
       self[key] || default
     end
 
     # Set a value and save
+    # @param key [String, Symbol] Configuration key to set
+    # @param value [Object] Configuration value to persist to disk
+    # @return [void]
     def set(key, value)
       self[key] = value
       save!
     end
 
     # Check if key exists
+    # @param key [String, Symbol] Configuration key to check
+    # @return [Boolean] true if key exists in configuration
     def key?(key)
       @data.key?(key.to_sym) || @data.key?(key.to_s)
     end
 
-    # Get provider configuration
+    # Get provider configuration with API keys and model settings
+    # @return [Hash] provider configuration hash
     def provider_config
       # Warn about deprecated API key environment variables
       warn_env_deprecated("ANTHROPIC_API_KEY", "anthropic_api_key") if ENV["ANTHROPIC_API_KEY"]
@@ -65,6 +86,8 @@ module Pocketrb
         anthropic_api_key: ENV["ANTHROPIC_API_KEY"] || self[:anthropic_api_key],
         openrouter_api_key: ENV["OPENROUTER_API_KEY"] || self[:openrouter_api_key],
         openai_api_key: ENV["OPENAI_API_KEY"] || self[:openai_api_key],
+        openai_compatible_base_url: self[:openai_compatible_base_url],
+        openai_compatible_api_key: self[:openai_compatible_api_key],
         brave_api_key: ENV["BRAVE_API_KEY"] || self[:brave_api_key],
         model: self[:model],
         autonomous: self[:autonomous],
@@ -74,7 +97,8 @@ module Pocketrb
       }.compact
     end
 
-    # Save configuration
+    # Save configuration to workspace config file
+    # @return [void]
     def save!
       return unless @workspace
 
@@ -87,42 +111,53 @@ module Pocketrb
       Pocketrb.logger.debug("Saved config to #{config_file}")
     end
 
-    # Reload configuration
+    # Reload configuration from defaults, workspace, global, and env
+    # @return [void]
     def reload!
       @data = DEFAULTS.dup
       load_config!
     end
 
     # Merge configuration
+    # @param hash [Hash] Hash of configuration values to merge
+    # @return [void]
     def merge!(hash)
       hash.each do |key, value|
         @data[key.to_sym] = value
       end
     end
 
-    # Convert to hash
+    # Convert configuration to hash
+    # @return [Hash] copy of configuration data
     def to_h
       @data.dup
     end
 
     # Class method to load config
+    # @param workspace [String, Pathname] Workspace directory path
+    # @return [Config] New configuration instance
     def self.load(workspace)
       new(workspace: workspace)
     end
 
-    # Global default config
+    # Global default config without workspace
+    # @return [Config] default configuration instance
     def self.default
       @default ||= new
     end
 
     private
 
+    # Load all configuration sources in priority order
+    # @return [void]
     def load_config!
       load_workspace_config if @workspace
       load_global_config
       load_env_overrides
     end
 
+    # Load workspace-specific configuration from .pocketrb/config.yml
+    # @return [void]
     def load_workspace_config
       config_file = @workspace.join(CONFIG_DIR, CONFIG_FILE)
       return unless config_file.exist?
@@ -133,6 +168,8 @@ module Pocketrb
       Pocketrb.logger.warn("Failed to load workspace config: #{e.message}")
     end
 
+    # Load global configuration from ~/.pocketrb/config.yml
+    # @return [void]
     def load_global_config
       global_config = Pathname.new(Dir.home).join(".pocketrb", CONFIG_FILE)
       return unless global_config.exist?
@@ -144,6 +181,8 @@ module Pocketrb
       Pocketrb.logger.warn("Failed to load global config: #{e.message}")
     end
 
+    # Apply environment variable overrides to configuration
+    # @return [void]
     def load_env_overrides
       # Environment variables override config file
       warn_env_deprecated("POCKETRB_PROVIDER", "provider") if ENV["POCKETRB_PROVIDER"]
@@ -160,6 +199,16 @@ module Pocketrb
       warn_env_deprecated("MCP_ENDPOINT", "mcp_endpoint") if ENV["MCP_ENDPOINT"]
       @data[:mcp_endpoint] = ENV["MCP_ENDPOINT"] if ENV["MCP_ENDPOINT"]
 
+      if ENV["POCKETRB_COMPACTION_MODEL"]
+        warn_env_deprecated("POCKETRB_COMPACTION_MODEL", "compaction_model")
+        @data[:compaction_model] = ENV["POCKETRB_COMPACTION_MODEL"]
+      end
+
+      if ENV["POCKETRB_COMPACTION_PRESSURE"]
+        warn_env_deprecated("POCKETRB_COMPACTION_PRESSURE", "compaction_pressure")
+        @data[:compaction_pressure] = ENV["POCKETRB_COMPACTION_PRESSURE"].to_f
+      end
+
       # Autonomous mode (for sandboxed environments)
       if %w[1 true].include?(ENV["POCKETRB_AUTONOMOUS"])
         warn_env_deprecated("POCKETRB_AUTONOMOUS", "autonomous")

data/lib/pocketrb/cron/job.rb

@@ -1,24 +1,37 @@
 # frozen_string_literal: true
 
 module Pocketrb
+  # Cron job scheduling system
   module Cron
     # Schedule types
     # - :at - one-time execution at specific timestamp
     # - :every - interval-based execution (every N seconds)
     # - :cron - cron expression-based execution
     Schedule = Data.define(:kind, :at_ms, :every_ms, :expr, :tz) do
+      # Initialize schedule
+      # @param kind [Symbol] Schedule type (:at, :every, or :cron)
+      # @param at_ms [Integer, nil] Timestamp in milliseconds for one-time execution
+      # @param every_ms [Integer, nil] Interval in milliseconds for recurring execution
+      # @param expr [String, nil] Cron expression for cron-based scheduling
+      # @param tz [String, nil] Timezone identifier (e.g., "America/New_York")
       def initialize(kind:, at_ms: nil, every_ms: nil, expr: nil, tz: nil)
         super
       end
 
+      # Check if schedule is one-time execution
+      # @return [Boolean] True if schedule type is :at
       def one_time?
         kind == :at
       end
 
+      # Check if schedule is interval-based
+      # @return [Boolean] True if schedule type is :every
       def interval?
         kind == :every
       end
 
+      # Check if schedule is cron expression-based
+      # @return [Boolean] True if schedule type is :cron
       def cron?
         kind == :cron
       end
@@ -26,6 +39,11 @@ module Pocketrb
 
     # Payload for job execution
     Payload = Data.define(:message, :deliver, :channel, :to) do
+      # Initialize payload
+      # @param message [String] Content to send or task description when job executes
+      # @param deliver [Boolean] Whether to deliver via messaging channel (defaults to false)
+      # @param channel [Symbol, nil] Channel identifier for delivery (:telegram, :cli, etc.)
+      # @param to [String, nil] Recipient identifier for channel delivery
       def initialize(message:, deliver: false, channel: nil, to: nil)
         super
       end
@@ -33,6 +51,11 @@ module Pocketrb
 
     # Job execution state
     JobState = Data.define(:next_run_at_ms, :last_run_at_ms, :last_status, :last_error) do
+      # Initialize job state
+      # @param next_run_at_ms [Integer, nil] Timestamp in milliseconds for next scheduled run
+      # @param last_run_at_ms [Integer, nil] Timestamp in milliseconds of last execution
+      # @param last_status [String, nil] Status of last execution (success, failed, etc.)
+      # @param last_error [String, nil] Error message from last failed execution
       def initialize(next_run_at_ms: nil, last_run_at_ms: nil, last_status: nil, last_error: nil)
         super
       end
@@ -50,6 +73,16 @@ module Pocketrb
       :updated_at_ms,
       :delete_after_run
     ) do
+      # Initialize cron job
+      # @param id [String] Unique job identifier
+      # @param name [String] Human-readable job name
+      # @param schedule [Schedule] Job schedule configuration
+      # @param payload [Payload] Job execution payload
+      # @param enabled [Boolean] Whether job is enabled for execution (defaults to true)
+      # @param state [JobState] Job execution state (defaults to new JobState)
+      # @param created_at_ms [Integer, nil] Creation timestamp in milliseconds
+      # @param updated_at_ms [Integer, nil] Last update timestamp in milliseconds
+      # @param delete_after_run [Boolean] Whether to delete job after execution (defaults to false)
       def initialize(
         id:,
         name:,
@@ -74,6 +107,9 @@ module Pocketrb
         )
       end
 
+      # Check if job is due to run
+      # @param now_ms [Integer, nil] Current timestamp in milliseconds (defaults to Time.now)
+      # @return [Boolean] True if job should execute now
       def due?(now_ms = nil)
         return false unless enabled
         return false unless state.next_run_at_ms
@@ -82,6 +118,8 @@ module Pocketrb
         state.next_run_at_ms <= now_ms
       end
 
+      # Convert job to hash for serialization
+      # @return [Hash] Job data as hash
       def to_h
         {
           "id" => id,
@@ -112,6 +150,9 @@ module Pocketrb
         }
       end
 
+      # Create job from hash representation
+      # @param hash [Hash] Hash containing job data
+      # @return [Job] New job instance
       def self.from_h(hash)
         schedule_h = hash["schedule"]
         schedule = Schedule.new(

data/lib/pocketrb/cron/service.rb

@@ -3,6 +3,7 @@
 require "json"
 require "securerandom"
 require "fileutils"
+require "fugit"
 require_relative "job"
 
 module Pocketrb
@@ -11,6 +12,9 @@ module Pocketrb
     class Service
       attr_reader :jobs
 
+      # Initialize the cron service
+      # @param store_path [String, Pathname] Directory path for persisting job state
+      # @param on_job [Proc] Callback invoked when a job executes, receives the job object
       def initialize(store_path:, on_job:)
         @store_path = Pathname.new(store_path)
         @on_job = on_job
@@ -24,6 +28,7 @@ module Pocketrb
       end
 
       # Start the cron service
+      # @return [void]
       def start
         return if @running
 
@@ -35,6 +40,7 @@ module Pocketrb
       end
 
       # Stop the cron service
+      # @return [void]
       def stop
         @running = false
         @timer_thread&.kill
@@ -57,8 +63,8 @@ module Pocketrb
       # Add a new job
       # @param name [String] Job name
       # @param schedule [Schedule] Schedule configuration
-      # @param message [String] Message to process
-      # @param deliver [Boolean] Deliver to channel vs process as agent task
+      # @param message [String] Content to send or task description when job executes
+      # @param deliver [Boolean] Whether to send directly to channel (true) or process as agent task (false)
       # @param channel [String, nil] Target channel
       # @param to [String, nil] Target chat ID
       # @return [Job] Created job
@@ -96,8 +102,8 @@ module Pocketrb
       # Add a job with interval schedule
       # @param name [String] Job name
       # @param every [Integer] Interval in seconds
-      # @param message [String] Message to process
-      # @param deliver [Boolean] Deliver to channel
+      # @param message [String] Content to send or task description when job executes
+      # @param deliver [Boolean] Whether to send directly to channel (true) or process as agent task (false)
       # @param channel [String, nil] Target channel
       # @param to [String, nil] Target chat ID
       # @return [Job]
@@ -109,9 +115,9 @@ module Pocketrb
       # Add a job with cron expression
       # @param name [String] Job name
       # @param cron [String] Cron expression
-      # @param message [String] Message to process
+      # @param message [String] Content to send or task description when job executes
       # @param tz [String, nil] Timezone
-      # @param deliver [Boolean] Deliver to channel
+      # @param deliver [Boolean] Whether to send directly to channel (true) or process as agent task (false)
       # @param channel [String, nil] Target channel
       # @param to [String, nil] Target chat ID
       # @return [Job]
@@ -123,8 +129,8 @@ module Pocketrb
       # Add a one-time job
       # @param name [String] Job name
       # @param at [Time, Integer] Execution time (Time or Unix timestamp)
-      # @param message [String] Message to process
-      # @param deliver [Boolean] Deliver to channel
+      # @param message [String] Content to send or task description when job executes
+      # @param deliver [Boolean] Whether to send directly to channel (true) or process as agent task (false)
       # @param channel [String, nil] Target channel
       # @param to [String, nil] Target chat ID
       # @return [Job]
@@ -204,10 +210,14 @@ module Pocketrb
 
       private
 
+      # Ensure the store directory exists
+      # @return [void]
       def ensure_store_dir!
         FileUtils.mkdir_p(@store_path.dirname)
       end
 
+      # Load persisted jobs from the store file
+      # @return [void]
       def load_jobs!
         return unless @store_path.exist?
 
@@ -219,6 +229,8 @@ module Pocketrb
         @jobs = {}
       end
 
+      # Persist all jobs to the store file
+      # @return [void]
       def save_jobs!
         @mutex.synchronize do
           data = @jobs.transform_values(&:to_h)
@@ -226,6 +238,8 @@ module Pocketrb
         end
       end
 
+      # Recompute next run times for all enabled jobs
+      # @return [void]
       def compute_next_runs!
         now_ms = (Time.now.to_f * 1000).to_i
 
@@ -241,6 +255,9 @@ module Pocketrb
         save_jobs!
       end
 
+      # Compute the next run time for a job based on its schedule
+      # @param job [Job] job to compute next run for
+      # @return [Job] new job instance with updated next_run_at_ms
       def compute_next_run(job)
         now_ms = (Time.now.to_f * 1000).to_i
         next_ms = case job.schedule.kind
@@ -273,10 +290,11 @@ module Pocketrb
         )
       end
 
+      # Compute the next run time from a cron expression
+      # @param expr [String] cron expression to parse
+      # @param tz [String, nil] timezone for cron evaluation
+      # @return [Integer, nil] next run time in milliseconds since epoch
       def compute_cron_next(expr, tz = nil)
-        # Try to use fugit if available
-
-        require "fugit"
         cron = Fugit.parse_cron(expr)
         return nil unless cron
 
@@ -285,12 +303,10 @@ module Pocketrb
 
         next_time = cron.next_time(now)
         (next_time.to_f * 1000).to_i
-      rescue LoadError
-        # Fallback: simple minute-based scheduling without fugit
-        Pocketrb.logger.warn("Fugit gem not available, cron expressions may not work correctly")
-        ((Time.now.to_f * 1000) + 60_000).to_i
       end
 
+      # Arm the timer thread for the next earliest job
+      # @return [void]
       def arm_timer!
         return unless @running
 
@@ -319,6 +335,8 @@ module Pocketrb
         Pocketrb.logger.debug("Cron timer armed for #{delay_s}s")
       end
 
+      # Process all due jobs and re-arm the timer
+      # @return [void]
       def tick
         now_ms = (Time.now.to_f * 1000).to_i
         due_jobs = @mutex.synchronize do
@@ -332,6 +350,9 @@ module Pocketrb
         arm_timer!
       end
 
+      # Execute a job and update its state
+      # @param job [Job] scheduled cron entry whose callback will be invoked
+      # @return [void]
       def execute_job(job)
         Pocketrb.logger.info("Executing cron job '#{job.name}' (ID: #{job.id})")
 
@@ -352,6 +373,11 @@ module Pocketrb
         end
       end
 
+      # Update a job's execution state after a run
+      # @param job_id [String] job identifier
+      # @param status [String] execution status ("success" or "failed")
+      # @param error [String, nil] error message if failed
+      # @return [void]
       def update_job_state(job_id, status:, error: nil)
         @mutex.synchronize do
           job = @jobs[job_id]
@@ -380,6 +406,9 @@ module Pocketrb
         save_jobs!
       end
 
+      # Recompute and persist the next run time for a job
+      # @param job_id [String] job identifier
+      # @return [void]
       def update_job_next_run(job_id)
         @mutex.synchronize do
           job = @jobs[job_id]

data/lib/pocketrb/heartbeat/service.rb

@@ -1,12 +1,15 @@
 # frozen_string_literal: true
 
 module Pocketrb
+  # Heartbeat system for periodic agent check-ins
   module Heartbeat
     # Periodic wake-up service that checks HEARTBEAT.md for pending tasks
     class Service
       DEFAULT_INTERVAL = 30 * 60 # 30 minutes
+      # Filename for heartbeat tasks
       HEARTBEAT_FILE = "HEARTBEAT.md"
 
+      # Prompt sent to agent on each heartbeat
       HEARTBEAT_PROMPT = <<~PROMPT
         Read HEARTBEAT.md in your workspace. Follow any instructions or tasks listed there.
         If nothing needs attention, reply with: HEARTBEAT_OK
@@ -20,6 +23,11 @@ module Pocketrb
 
       attr_reader :interval, :enabled, :last_run_at
 
+      # Initialize heartbeat service
+      # @param workspace [String, Pathname] Workspace directory containing HEARTBEAT.md
+      # @param on_heartbeat [Proc] Callback to invoke on each heartbeat with message content
+      # @param interval [Integer] Heartbeat interval in seconds (defaults to 3600)
+      # @param enabled [Boolean] Whether heartbeat is enabled (defaults to true)
       def initialize(workspace:, on_heartbeat:, interval: DEFAULT_INTERVAL, enabled: true)
         @workspace = Pathname.new(workspace)
         @on_heartbeat = on_heartbeat
@@ -32,6 +40,7 @@ module Pocketrb
       end
 
       # Start the heartbeat service
+      # @return [void]
       def start
         return unless @enabled
         return if @running
@@ -43,6 +52,7 @@ module Pocketrb
       end
 
       # Stop the heartbeat service
+      # @return [void]
       def stop
         @running = false
         @timer_thread&.kill
@@ -117,6 +127,8 @@ module Pocketrb
 
       private
 
+      # Arm the periodic timer thread
+      # @return [void]
       def arm_timer!
         return unless @running && @enabled
 
@@ -131,10 +143,14 @@ module Pocketrb
         end
       end
 
+      # Path to the HEARTBEAT.md file in the workspace
+      # @return [Pathname] heartbeat file path
       def heartbeat_file
         @workspace.join(HEARTBEAT_FILE)
       end
 
+      # Read heartbeat file contents
+      # @return [String, nil] file contents or nil if not found
       def read_heartbeat_file
         return nil unless heartbeat_file.exist?
 
@@ -144,6 +160,9 @@ module Pocketrb
         nil
       end
 
+      # Check if heartbeat content has no actionable items
+      # @param content [String, nil] heartbeat file content
+      # @return [Boolean] true if content is empty or has no tasks
       def empty_heartbeat?(content)
         return true if content.nil? || content.strip.empty?
 
@@ -163,6 +182,8 @@ module Pocketrb
         end
       end
 
+      # Seconds remaining until next heartbeat
+      # @return [Integer, nil] seconds until next run or nil
       def next_run_in
         return nil unless @running && @enabled && @last_run_at
 

data/lib/pocketrb/mcp/client.rb

@@ -5,15 +5,19 @@ require "json"
 require "securerandom"
 
 module Pocketrb
+  # Model Context Protocol (MCP) integration for memory and tool servers
   module MCP
-    # MCP client for connecting to MCP HTTP Bridge
-    # Implements JSON-RPC 2.0 protocol for MCP communication
+    # MCP client for connecting to MCP HTTP Bridge. Implements JSON-RPC 2.0 protocol for MCP communication
     class Client
+      # Default MCP server endpoint URL
       DEFAULT_ENDPOINT = "http://localhost:7878"
+      # Request timeout in seconds
       TIMEOUT = 30
 
       attr_reader :endpoint, :connected
 
+      # Initialize MCP client
+      # @param endpoint [String, nil] MCP server endpoint URL (defaults to ENV['MCP_ENDPOINT'] or DEFAULT_ENDPOINT)
       def initialize(endpoint: nil)
         @endpoint = endpoint || ENV["MCP_ENDPOINT"] || DEFAULT_ENDPOINT
         @connected = false
@@ -21,6 +25,7 @@ module Pocketrb
       end
 
       # Initialize the MCP connection
+      # @return [Boolean] true if connection succeeded
       def connect
         response = rpc_call("initialize", {
                               protocolVersion: "2024-11-05",
@@ -45,6 +50,7 @@ module Pocketrb
       end
 
       # List available tools from MCP server
+      # @return [Array<Hash>] list of tool definitions
       def list_tools
         ensure_connected!
 
@@ -53,6 +59,10 @@ module Pocketrb
       end
 
       # Call a tool on the MCP server
+      # @param name [String] Tool name to invoke
+      # @param arguments [Hash] Tool arguments
+      # @return [String] Tool execution result
+      # @raise [MCPError] if tool call fails
       def call_tool(name:, arguments: {})
         ensure_connected!
 
@@ -67,6 +77,9 @@ module Pocketrb
       end
 
       # Search memory via MCP
+      # @param query [String] Search query string
+      # @param limit [Integer] Maximum number of results to return
+      # @return [String] Search results
       def search(query:, limit: 10)
         # Try MCP tool first
         if tool_available?("memory_search")
@@ -78,6 +91,9 @@ module Pocketrb
       end
 
       # Store to memory via MCP
+      # @param content [String] Content to store in memory
+      # @param metadata [Hash] Additional metadata for the stored content
+      # @return [String] Storage confirmation
       def store(content:, metadata: {})
         # Try MCP tool first
         if tool_available?("memory_store")
@@ -89,17 +105,22 @@ module Pocketrb
       end
 
       # Check if connected
+      # @return [Boolean] true if connected to MCP server
       def connected?
         @connected
       end
 
       # Disconnect from server
+      # @return [void]
       def disconnect
         @connected = false
       end
 
       private
 
+      # Ensure MCP connection is established, connecting if needed
+      # @return [void]
+      # @raise [MCPError] if connection cannot be established
       def ensure_connected!
         return if @connected
 
@@ -107,6 +128,11 @@ module Pocketrb
         raise MCPError, "Not connected to MCP server" unless @connected
       end
 
+      # Execute a JSON-RPC 2.0 call to the MCP server
+      # @param method [String] RPC method name
+      # @param params [Hash] RPC parameters
+      # @return [Hash] parsed JSON response
+      # @raise [MCPError] on connection or HTTP errors
       def rpc_call(method, params)
         @request_id += 1
 
@@ -128,6 +154,8 @@ module Pocketrb
         raise MCPError, "RPC connection error: #{e.message}"
       end
 
+      # Faraday HTTP client instance
+      # @return [Faraday::Connection] configured HTTP client
       def client
         @client ||= Faraday.new(url: @endpoint) do |f|
           f.headers["Content-Type"] = "application/json"
@@ -136,6 +164,9 @@ module Pocketrb
         end
       end
 
+      # Check if a tool is available on the MCP server
+      # @param name [String] tool name to check
+      # @return [Boolean] true if tool is available
       def tool_available?(name)
         @tools ||= list_tools
         @tools.any? { |t| t["name"] == name }
@@ -143,7 +174,10 @@ module Pocketrb
         false
       end
 
-      # Direct HTTP endpoints (fallback when not using MCP tools)
+      # Search via direct HTTP endpoint (fallback when MCP tools unavailable)
+      # @param query [String] search query
+      # @param limit [Integer] maximum results
+      # @return [Hash, nil] parsed search results or nil on failure
       def http_search(query, limit)
         response = client.post("/search") do |req|
           req.body = { query: query, limit: limit }.to_json
@@ -156,6 +190,10 @@ module Pocketrb
         nil
       end
 
+      # Store via direct HTTP endpoint (fallback when MCP tools unavailable)
+      # @param content [String] text or fact to persist in the memory backend
+      # @param metadata [Hash] metadata to associate with content
+      # @return [Boolean] true if stored successfully
       def http_store(content, metadata)
         response = client.post("/store") do |req|
           req.body = { content: content, metadata: metadata }.to_json