Class: SwarmSDK::V3::Memory::Adapters::FilesystemAdapter

Inherits:
Base
  • Object
show all
Includes:
FaissSupport, VectorUtils
Defined in:
lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb

Overview

Filesystem-based storage adapter with FAISS vector index

Stores cards as individual JSON files, edges and clusters in aggregate JSON files, and vectors in a FAISS IndexFlatIP index (cosine similarity via L2-normalized vectors + inner product).

Directory structure:

.swarm/memory/
├── cards/
│   ├── card_a1b2c3.json
│   └── ...
├── edges.json
├── clusters.json
└── index.faiss

Examples:

adapter = FilesystemAdapter.new("/path/to/.swarm/memory")
adapter.load
adapter.write_card(card)
adapter.save

Constant Summary

Constants included from FaissSupport

SwarmSDK::V3::Memory::Adapters::FaissSupport::EMBEDDING_DIMENSIONS

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from FaissSupport

#rebuild_index, #vector_search

Methods included from VectorUtils

#similarity

Methods inherited from Base

#list_cards_for_compression, #rebuild_index, #similarity, #transaction, #vector_search

Constructor Details

#initialize(directory) ⇒ FilesystemAdapter

Returns a new instance of FilesystemAdapter.

Parameters:

  • directory (String) —

    Root directory for memory storage



35
36
37
38
39
40
41
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 35

def initialize(directory)
  super()
  @directory = File.expand_path(directory)
  @edges = []
  @clusters = []
  initialize_faiss!
end

Instance Attribute Details

#directory ⇒ String (readonly)

Returns Root directory for storage.

Returns:

  • (String) —

    Root directory for storage



32
33
34
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 32

def directory
  @directory
end

Instance Method Details

#delete_card(id) ⇒ void

This method returns an undefined value.

Parameters:

  • id (String) —

    Card ID



66
67
68
69
70
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 66

def delete_card(id)
  path = card_path(id)
  File.delete(path) if File.exist?(path)
  remove_from_vector_index(id)
end

#delete_edges_for(card_id) ⇒ void

This method returns an undefined value.

Parameters:

  • card_id (String) —

    Card ID



102
103
104
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 102

def delete_edges_for(card_id)
  @edges.reject! { |e| e.from_id == card_id || e.to_id == card_id }
end

#edges_for(card_id, type: nil) ⇒ Array<Edge>

Parameters:

  • card_id (String) —

    Card ID

  • type (Symbol, nil) (defaults to: nil) —

    Filter by edge type

Returns:



94
95
96
97
98
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 94

def edges_for(card_id, type: nil)
  results = @edges.select { |e| e.from_id == card_id || e.to_id == card_id }
  results = results.select { |e| e.type == type } if type
  results
end

#list_cards(prefix: nil) ⇒ Array<Card>

Parameters:

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

    ID prefix filter

Returns:



74
75
76
77
78
79
80
81
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 74

def list_cards(prefix: nil)
  ensure_directories!
  pattern = prefix ? "#{prefix}*.json" : "*.json"
  Dir.glob(File.join(cards_dir, pattern)).map do |path|
    data = JSON.parse(File.read(path))
    Card.from_h(data)
  end
end

#list_clusters ⇒ Array<Cluster>

Returns:



126
127
128
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 126

def list_clusters
  @clusters.dup
end

#load ⇒ void

This method returns an undefined value.

Load edges, clusters, and FAISS index from disk



145
146
147
148
149
150
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 145

def load
  ensure_directories!
  load_edges
  load_clusters
  load_faiss_index
end

#read_card(id) ⇒ Card?

Parameters:

  • id (String) —

    Card ID

Returns:



56
57
58
59
60
61
62
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 56

def read_card(id)
  path = card_path(id)
  return unless File.exist?(path)

  data = JSON.parse(File.read(path))
  Card.from_h(data)
end

#read_cluster(id) ⇒ Cluster?

Parameters:

  • id (String) —

    Cluster ID

Returns:



121
122
123
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 121

def read_cluster(id)
  @clusters.find { |c| c.id == id }
end

#save ⇒ void

This method returns an undefined value.

Save edges, clusters, and FAISS index to disk



135
136
137
138
139
140
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 135

def save
  ensure_directories!
  save_edges
  save_clusters
  save_faiss_index
end

#write_card(card) ⇒ void

This method returns an undefined value.

Parameters:

  • card (Card) —

    Card to write



47
48
49
50
51
52
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 47

def write_card(card)
  ensure_directories!
  path = card_path(card.id)
  File.write(path, JSON.pretty_generate(card.to_h))
  add_to_vector_index(card) if card.embedding
end

#write_cluster(cluster) ⇒ void

This method returns an undefined value.

Parameters:

  • cluster (Cluster) —

    Cluster to write



110
111
112
113
114
115
116
117
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 110

def write_cluster(cluster)
  idx = @clusters.index { |c| c.id == cluster.id }
  if idx
    @clusters[idx] = cluster
  else
    @clusters << cluster
  end
end

#write_edge(edge) ⇒ void

This method returns an undefined value.

Parameters:

  • edge (Edge) —

    Edge to write



87
88
89
 
# File 'lib/swarm_sdk/v3/memory/adapters/filesystem_adapter.rb', line 87

def write_edge(edge)
  @edges << edge
end