Class: KairosMcp::Storage::Backend

Inherits:
Object
  • Object
show all
Defined in:
lib/kairos_mcp/storage/backend.rb

Overview

Abstract base class for storage backends

KairosChain supports two storage backends:

  • FileBackend (default): File-based storage for individual use
  • SqliteBackend (optional): SQLite-based storage for team use

The backend is selected via config.yml:

storage:
backend: file  # or 'sqlite'

Direct Known Subclasses

FileBackend, SqliteBackend

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.create(config = {}) ⇒ Backend

Create a storage backend based on configuration

Parameters:

  • config (Hash) (defaults to: {}) —

    Configuration hash with :backend key

Returns:

  • (Backend) —

    A FileBackend or SqliteBackend instance



181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
 
# File 'lib/kairos_mcp/storage/backend.rb', line 181

def self.create(config = {})
  backend = config[:backend]&.to_s || 'file'

  # Check SkillSet-registered backends first (e.g. 'postgresql')
  if @registry.key?(backend)
    return @registry[backend].new(config[backend.to_sym] || {})
  end

  case backend
  when 'sqlite'
    begin
      require_relative 'sqlite_backend'
      SqliteBackend.new(config[:sqlite] || {})
    rescue LoadError => e
      warn "[KairosChain] SQLite backend requested but sqlite3 gem not available: #{e.message}"
      warn "[KairosChain] Falling back to file backend"
      require_relative 'file_backend'
      FileBackend.new(config[:file] || {})
    end
  else
    require_relative 'file_backend'
    FileBackend.new(config[:file] || {})
  end
end

.default ⇒ Backend

Create a backend using the default configuration

Returns:

  • (Backend) —

    A FileBackend or SqliteBackend instance



223
224
225
226
 
# File 'lib/kairos_mcp/storage/backend.rb', line 223

def self.default
  config = load_config
  create(config.transform_keys(&:to_sym))
end

.load_config ⇒ Hash

Get the default storage configuration from config.yml

Returns:

  • (Hash) —

    Storage configuration



208
209
210
211
212
213
214
215
216
217
218
219
 
# File 'lib/kairos_mcp/storage/backend.rb', line 208

def self.load_config
  require_relative '../../kairos_mcp'
  config_path = KairosMcp.skills_config_path
  return {} unless File.exist?(config_path)

  require 'yaml'
  config = YAML.safe_load(File.read(config_path), permitted_classes: [Symbol]) || {}
  config['storage'] || {}
rescue StandardError => e
  warn "[KairosChain] Failed to load storage config: #{e.message}"
  {}
end

.register(name, klass) ⇒ Object

Register a named backend class for SkillSet use (e.g. 'postgresql')



30
31
32
 
# File 'lib/kairos_mcp/storage/backend.rb', line 30

def self.register(name, klass)
  @registry[name.to_s] = klass
end

.unregister(name) ⇒ Object

Unregister a named backend



35
36
37
 
# File 'lib/kairos_mcp/storage/backend.rb', line 35

def self.unregister(name)
  @registry.delete(name.to_s)
end

Instance Method Details

#action_history(limit: 50) ⇒ Array<Hash>

Get action history

Parameters:

  • limit (Integer) (defaults to: 50) —

    Maximum number of entries to return

Returns:

  • (Array<Hash>) —

    Recent action log entries

Raises:

  • (NotImplementedError) 


97
98
99
 
# File 'lib/kairos_mcp/storage/backend.rb', line 97

def action_history(limit: 50)
  raise NotImplementedError, "#{self.class}#action_history must be implemented"
end

#all_blocks ⇒ Array<Hash>

Get all blocks

Returns:

  • (Array<Hash>) —

    All blocks

Raises:

  • (NotImplementedError) 


79
80
81
 
# File 'lib/kairos_mcp/storage/backend.rb', line 79

def all_blocks
  raise NotImplementedError, "#{self.class}#all_blocks must be implemented"
end

#backend_type ⇒ Symbol

Get backend type

Returns:

  • (Symbol) —

    :file or :sqlite

Raises:

  • (NotImplementedError) 


162
163
164
 
# File 'lib/kairos_mcp/storage/backend.rb', line 162

def backend_type
  raise NotImplementedError, "#{self.class}#backend_type must be implemented"
end

#clear_action_log! ⇒ Boolean

Clear all action logs

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


103
104
105
 
# File 'lib/kairos_mcp/storage/backend.rb', line 103

def clear_action_log!
  raise NotImplementedError, "#{self.class}#clear_action_log! must be implemented"
end

#delete_knowledge_meta(name) ⇒ Boolean

Delete knowledge metadata

Parameters:

  • name (String) —

    Knowledge name

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


137
138
139
 
# File 'lib/kairos_mcp/storage/backend.rb', line 137

def delete_knowledge_meta(name)
  raise NotImplementedError, "#{self.class}#delete_knowledge_meta must be implemented"
end

#get_knowledge_meta(name) ⇒ Hash?

Get knowledge metadata

Parameters:

  • name (String) —

    Knowledge name

Returns:

  • (Hash, nil) —

    Metadata or nil if not found

Raises:

  • (NotImplementedError) 


124
125
126
 
# File 'lib/kairos_mcp/storage/backend.rb', line 124

def get_knowledge_meta(name)
  raise NotImplementedError, "#{self.class}#get_knowledge_meta must be implemented"
end

#list_knowledge_meta ⇒ Array<Hash>

List all knowledge metadata

Returns:

  • (Array<Hash>) —

    Array of metadata for all knowledge entries

Raises:

  • (NotImplementedError) 


130
131
132
 
# File 'lib/kairos_mcp/storage/backend.rb', line 130

def list_knowledge_meta
  raise NotImplementedError, "#{self.class}#list_knowledge_meta must be implemented"
end

#load_blocks ⇒ Array<Hash>?

Load all blocks from storage

Read contract (a backend that declares #blockchain_file must honour it): nil is returned only when the ledger does not exist. A ledger that cannot be opened or cannot be parsed (including a zero-byte file) raises Storage::Error. Collapsing those into nil would let a damaged ledger pass as "absent" and be rebuilt from genesis.

Returns:

  • (Array<Hash>, nil) —

    Array of block data, or nil when absent

Raises:



53
54
55
 
# File 'lib/kairos_mcp/storage/backend.rb', line 53

def load_blocks
  raise NotImplementedError, "#{self.class}#load_blocks must be implemented"
end

#ready? ⇒ Boolean

Check if the backend is ready

Returns:

  • (Boolean) —

    True if backend is initialized and ready

Raises:

  • (NotImplementedError) 


156
157
158
 
# File 'lib/kairos_mcp/storage/backend.rb', line 156

def ready?
  raise NotImplementedError, "#{self.class}#ready? must be implemented"
end

#record_action(entry) ⇒ Boolean

Record an action to the log

Parameters:

  • entry (Hash) —

    Log entry with :timestamp, :action, :skill_id, :details

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


90
91
92
 
# File 'lib/kairos_mcp/storage/backend.rb', line 90

def record_action(entry)
  raise NotImplementedError, "#{self.class}#record_action must be implemented"
end

#save_all_blocks(blocks) ⇒ Boolean

Save all blocks to storage (for file backend bulk write)

Write contract: failure raises Storage::Error. Returning false for a failed write is forbidden — the caller cannot distinguish "refused" from "wrote and then failed", and a false return reads as a benign result.

Parameters:

  • blocks (Array<Hash>) —

    Array of block data

Returns:

  • (Boolean) —

    true

Raises:



73
74
75
 
# File 'lib/kairos_mcp/storage/backend.rb', line 73

def save_all_blocks(blocks)
  raise NotImplementedError, "#{self.class}#save_all_blocks must be implemented"
end

#save_block(block) ⇒ Boolean

Save a single block to storage

Parameters:

  • block (Hash) —

    Block data to save

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


60
61
62
 
# File 'lib/kairos_mcp/storage/backend.rb', line 60

def save_block(block)
  raise NotImplementedError, "#{self.class}#save_block must be implemented"
end

#save_knowledge_meta(name, meta) ⇒ Boolean

Save knowledge metadata

Parameters:

  • name (String) —

    Knowledge name

  • meta (Hash) —

    Metadata (content_hash, version, description, tags, etc.)

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


117
118
119
 
# File 'lib/kairos_mcp/storage/backend.rb', line 117

def save_knowledge_meta(name, meta)
  raise NotImplementedError, "#{self.class}#save_knowledge_meta must be implemented"
end

#update_knowledge_archived(name, archived, reason: nil) ⇒ Boolean

Update knowledge archived status

Parameters:

  • name (String) —

    Knowledge name

  • archived (Boolean) —

    Archived status

  • reason (String, nil) (defaults to: nil) —

    Archive reason

Returns:

  • (Boolean) —

    Success status

Raises:

  • (NotImplementedError) 


146
147
148
 
# File 'lib/kairos_mcp/storage/backend.rb', line 146

def update_knowledge_archived(name, archived, reason: nil)
  raise NotImplementedError, "#{self.class}#update_knowledge_archived must be implemented"
end