Class: SwarmMemory::Adapters::Base

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_memory/adapters/base.rb

Overview

Abstract base adapter interface for memory storage backends

Subclasses must implement all public methods to provide different storage backends (filesystem, Redis, SQLite, etc.)

Direct Known Subclasses

FilesystemAdapter

Constant Summary collapse

MAX_ENTRY_SIZE =

Maximum size per entry (3MB)

3_000_000
MAX_TOTAL_SIZE =

Maximum total storage size (100GB)

100_000_000_000

Instance Method Summary collapse

Instance Method Details

#clear ⇒ void

This method returns an undefined value.

Clear all entries

Raises:

  • (NotImplementedError) 


86
87
88
 
# File 'lib/swarm_memory/adapters/base.rb', line 86

def clear
  raise NotImplementedError, "Subclass must implement #clear"
end

#delete(file_path:) ⇒ void

This method returns an undefined value.

Delete a specific entry

Parameters:

  • file_path (String) —

    Path to delete

Raises:

  • (ArgumentError) —

    If path not found



52
53
54
 
# File 'lib/swarm_memory/adapters/base.rb', line 52

def delete(file_path:)
  raise NotImplementedError, "Subclass must implement #delete"
end

#glob(pattern:) ⇒ Array<Hash>

Search entries by glob pattern

Parameters:

  • pattern (String) —

    Glob pattern (e.g., "**/.txt", "parallel//task_*")

Returns:

  • (Array<Hash>) —

    Array of matching entry metadata, sorted by most recent first

Raises:

  • (NotImplementedError) 


68
69
70
 
# File 'lib/swarm_memory/adapters/base.rb', line 68

def glob(pattern:)
  raise NotImplementedError, "Subclass must implement #glob"
end

#grep(pattern:, case_insensitive: false, output_mode: "files_with_matches", path: nil) ⇒ Array<Hash>, String

Search entry content by pattern

Parameters:

  • pattern (String) —

    Regular expression pattern to search for

  • case_insensitive (Boolean) (defaults to: false) —

    Whether to perform case-insensitive search

  • output_mode (String) (defaults to: "files_with_matches") —

    Output mode: "files_with_matches" (default), "content", or "count"

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

    Optional path prefix filter (e.g., "concept/", "fact/api-design")

Returns:

  • (Array<Hash>, String) —

    Results based on output_mode

Raises:

  • (NotImplementedError) 


79
80
81
 
# File 'lib/swarm_memory/adapters/base.rb', line 79

def grep(pattern:, case_insensitive: false, output_mode: "files_with_matches", path: nil)
  raise NotImplementedError, "Subclass must implement #grep"
end

#list(prefix: nil) ⇒ Array<Hash>

List entries, optionally filtered by prefix

Parameters:

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

    Filter by path prefix

Returns:

  • (Array<Hash>) —

    Array of entry metadata (path, title, size, updated_at)

Raises:

  • (NotImplementedError) 


60
61
62
 
# File 'lib/swarm_memory/adapters/base.rb', line 60

def list(prefix: nil)
  raise NotImplementedError, "Subclass must implement #list"
end

#read(file_path:) ⇒ String

Read content from storage

Parameters:

  • file_path (String) —

    Path to read from

Returns:

  • (String) —

    Content at the path

Raises:

  • (ArgumentError) —

    If path not found



34
35
36
 
# File 'lib/swarm_memory/adapters/base.rb', line 34

def read(file_path:)
  raise NotImplementedError, "Subclass must implement #read"
end

#read_entry(file_path:) ⇒ Core::Entry

Read full entry with metadata

Parameters:

  • file_path (String) —

    Path to read from

Returns:

Raises:

  • (ArgumentError) —

    If path not found



43
44
45
 
# File 'lib/swarm_memory/adapters/base.rb', line 43

def read_entry(file_path:)
  raise NotImplementedError, "Subclass must implement #read_entry"
end

#semantic_search(embedding:, top_k: 10, threshold: 0.0) ⇒ Array<Hash>

Semantic search by embedding vector

Searches all entries with embeddings and returns those similar to the query. Results are sorted by cosine similarity in descending order.

Each result hash must contain:

- :path (String) - logical file path
- :similarity (Float) - cosine similarity score 0.0-1.0
- :title (String) - entry title
- :size (Integer) - content size in bytes
- :updated_at (Time) - last update timestamp
- :metadata (Hash) - nested hash with type, tags, domain, etc.

Examples:

results = adapter.semantic_search(
  embedding: query_embedding,
  top_k: 5,
  threshold: 0.65
)

Parameters:

  • embedding (Array<Float>) —

    Query embedding vector

  • top_k (Integer) (defaults to: 10) —

    Number of results to return

  • threshold (Float) (defaults to: 0.0) —

    Minimum similarity score (0.0-1.0)

Returns:

  • (Array<Hash>) —

    Results with similarity scores

Raises:

  • (NotImplementedError) 


128
129
130
 
# File 'lib/swarm_memory/adapters/base.rb', line 128

def semantic_search(embedding:, top_k: 10, threshold: 0.0)
  raise NotImplementedError, "Subclass must implement #semantic_search"
end

#size ⇒ Integer

Get number of entries

Returns:

  • (Integer) —

    Number of entries

Raises:

  • (NotImplementedError) 


100
101
102
 
# File 'lib/swarm_memory/adapters/base.rb', line 100

def size
  raise NotImplementedError, "Subclass must implement #size"
end

#total_size ⇒ Integer

Get current total size

Returns:

  • (Integer) —

    Total size in bytes

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/swarm_memory/adapters/base.rb', line 93

def total_size
  raise NotImplementedError, "Subclass must implement #total_size"
end

#write(file_path:, content:, title:, embedding: nil, metadata: nil) ⇒ Core::Entry

Write content to storage

Parameters:

  • file_path (String) —

    Path to store content

  • content (String) —

    Content to store

  • title (String) —

    Brief title describing the content

  • embedding (Array<Float>, nil) (defaults to: nil) —

    Optional embedding vector

  • metadata (Hash, nil) (defaults to: nil) —

    Optional metadata

Returns:

Raises:

  • (ArgumentError) —

    If size limits are exceeded



25
26
27
 
# File 'lib/swarm_memory/adapters/base.rb', line 25

def write(file_path:, content:, title:, embedding: nil, metadata: nil)
  raise NotImplementedError, "Subclass must implement #write"
end