Class: SwarmSDK::V3::Memory::Card

Inherits:
Object
  • Object
show all
Defined in:
lib/swarm_sdk/v3/memory/card.rb

Overview

A self-contained memory unit (<=250 words)

Cards are the atomic unit of the memory system. Each card captures a single idea, fact, decision, or concept with enough context to be understood in isolation.

Examples:

Create a fact card

card = Card.new(
  text: "The API uses JWT tokens for authentication with RS256 signing.",
  type: :fact,
  entities: ["API", "JWT", "RS256"],
  source_turn_ids: ["turn_001"],
)

Constant Summary collapse

TYPES = 
[:fact, :concept, :decision, :constraint, :preference, :incident].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(text:, type: :fact, entities: [], source_turn_ids: [], id: nil, embedding: nil, importance: 0.5, confidence: 1.0, access_count: 0, last_accessed: nil, dwell: 0.0, compression_level: 0, canonical_id: nil, created_at: nil, updated_at: nil) ⇒ Card

Create a new memory card

Parameters:

  • text (String) —

    Card content

  • type (Symbol) (defaults to: :fact) —

    Card type

  • entities (Array<String>) (defaults to: []) —

    Named entities

  • source_turn_ids (Array<String>) (defaults to: []) —

    Contributing turn IDs

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

    Card ID (auto-generated if nil)

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

    Embedding vector

  • importance (Float) (defaults to: 0.5) —

    Importance score

  • confidence (Float) (defaults to: 1.0) —

    Confidence score (0.0-1.0)

  • access_count (Integer) (defaults to: 0) —

    Access count

  • last_accessed (Time, nil) (defaults to: nil) —

    Last access time

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

    Dwell time weight

  • compression_level (Integer) (defaults to: 0) —

    Compression level (0-4)

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

    Canonical card ID

  • created_at (Time, nil) (defaults to: nil) —

    Creation time

  • updated_at (Time, nil) (defaults to: nil) —

    Update time

Raises:

  • (ArgumentError) —

    If type is invalid



86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 86

def initialize(
  text:,
  type: :fact,
  entities: [],
  source_turn_ids: [],
  id: nil,
  embedding: nil,
  importance: 0.5,
  confidence: 1.0,
  access_count: 0,
  last_accessed: nil,
  dwell: 0.0,
  compression_level: 0,
  canonical_id: nil,
  created_at: nil,
  updated_at: nil
)
  @id = id || "card_#{SecureRandom.hex(6)}"
  @text = text
  @type = type.to_sym
  @entities = Array(entities)
  @source_turn_ids = Array(source_turn_ids)
  @embedding = embedding
  @importance = importance.to_f
  @confidence = confidence.to_f
  @access_count = access_count.to_i
  @last_accessed = last_accessed
  @dwell = dwell.to_f
  @compression_level = compression_level.to_i
  @canonical_id = canonical_id
  @created_at = created_at || Time.now
  @updated_at = updated_at || Time.now

  validate!
end

Instance Attribute Details

#access_count ⇒ Integer

Returns Number of times this card was retrieved.

Returns:

  • (Integer) —

    Number of times this card was retrieved



47
48
49
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 47

def access_count
  @access_count
end

#canonical_id ⇒ String?

Returns ID of canonical card if this was merged.

Returns:

  • (String, nil) —

    ID of canonical card if this was merged



59
60
61
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 59

def canonical_id
  @canonical_id
end

#compression_level ⇒ Integer

Returns Compression level (0=raw, 1=summary, 2=bullets, 3=schema, 4=embedding-only).

Returns:

  • (Integer) —

    Compression level (0=raw, 1=summary, 2=bullets, 3=schema, 4=embedding-only)



56
57
58
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 56

def compression_level
  @compression_level
end

#confidence ⇒ Float

Returns Confidence score (0.0-1.0, default 1.0).

Returns:

  • (Float) —

    Confidence score (0.0-1.0, default 1.0)



44
45
46
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 44

def confidence
  @confidence
end

#created_at ⇒ Time (readonly)

Returns Creation timestamp.

Returns:

  • (Time) —

    Creation timestamp



62
63
64
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 62

def created_at
  @created_at
end

#dwell ⇒ Float

Returns Dwell time weight (how long card was in context).

Returns:

  • (Float) —

    Dwell time weight (how long card was in context)



53
54
55
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 53

def dwell
  @dwell
end

#embedding ⇒ Array<Float>?

Returns Embedding vector (384 dimensions for MiniLM).

Returns:

  • (Array<Float>, nil) —

    Embedding vector (384 dimensions for MiniLM)



38
39
40
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 38

def embedding
  @embedding
end

#entities ⇒ Array<String>

Returns Named entities mentioned in the card.

Returns:

  • (Array<String>) —

    Named entities mentioned in the card



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

def entities
  @entities
end

#id ⇒ String (readonly)

Returns Unique card identifier (card_<hex>).

Returns:

  • (String) —

    Unique card identifier (card_<hex>)



23
24
25
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 23

def id
  @id
end

#importance ⇒ Float

Returns Importance score (0.0-1.0).

Returns:

  • (Float) —

    Importance score (0.0-1.0)



41
42
43
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 41

def importance
  @importance
end

#last_accessed ⇒ Time?

Returns Last time this card was accessed.

Returns:

  • (Time, nil) —

    Last time this card was accessed



50
51
52
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 50

def last_accessed
  @last_accessed
end

#source_turn_ids ⇒ Array<String>

Returns Turn IDs that contributed to this card.

Returns:

  • (Array<String>) —

    Turn IDs that contributed to this card



35
36
37
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 35

def source_turn_ids
  @source_turn_ids
end

#text ⇒ String

Returns Card content (<=250 words, self-contained).

Returns:

  • (String) —

    Card content (<=250 words, self-contained)



26
27
28
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 26

def text
  @text
end

#type ⇒ Symbol (readonly)

Returns Card type (fact, concept, decision, constraint, preference, incident).

Returns:

  • (Symbol) —

    Card type (fact, concept, decision, constraint, preference, incident)



29
30
31
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 29

def type
  @type
end

#updated_at ⇒ Time

Returns Last update timestamp.

Returns:

  • (Time) —

    Last update timestamp



65
66
67
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 65

def updated_at
  @updated_at
end

Class Method Details

.from_h(hash) ⇒ Card

Deserialize from a hash

Parameters:

  • hash (Hash) —

    Serialized card data

Returns:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 172

def from_h(hash)
  hash = hash.transform_keys(&:to_sym)
  new(
    id: hash[:id],
    text: hash[:text],
    type: hash[:type]&.to_sym || :fact,
    entities: hash[:entities] || [],
    source_turn_ids: hash[:source_turn_ids] || [],
    embedding: hash[:embedding],
    importance: hash[:importance] || 0.5,
    confidence: hash[:confidence] || 1.0,
    access_count: hash[:access_count] || 0,
    last_accessed: hash[:last_accessed] ? Time.parse(hash[:last_accessed]) : nil,
    dwell: hash[:dwell] || 0.0,
    compression_level: hash[:compression_level] || 0,
    canonical_id: hash[:canonical_id],
    created_at: hash[:created_at] ? Time.parse(hash[:created_at]) : nil,
    updated_at: hash[:updated_at] ? Time.parse(hash[:updated_at]) : nil,
  )
end

Instance Method Details

#merged? ⇒ Boolean

Whether this card has been merged into a canonical card

Returns:

  • (Boolean) 


140
141
142
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 140

def merged?
  !@canonical_id.nil?
end

#record_access!(dwell_increment: 1.0) ⇒ void

This method returns an undefined value.

Record an access to this card (included in working context)

Increments access count, updates last accessed time, and increases dwell weight to track how often this card has been included in the working context.

Parameters:

  • dwell_increment (Float) (defaults to: 1.0) —

    Amount to add to dwell (default: 1.0)



130
131
132
133
134
135
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 130

def record_access!(dwell_increment: 1.0)
  @access_count += 1
  @last_accessed = Time.now
  @dwell += dwell_increment
  @updated_at = Time.now
end

#to_h ⇒ Hash

Serialize to a hash for JSON storage

Returns:

  • (Hash) —

    Serializable representation



147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
 
# File 'lib/swarm_sdk/v3/memory/card.rb', line 147

def to_h
  {
    id: @id,
    text: @text,
    type: @type.to_s,
    entities: @entities,
    source_turn_ids: @source_turn_ids,
    embedding: @embedding,
    importance: @importance,
    confidence: @confidence,
    access_count: @access_count,
    last_accessed: @last_accessed&.iso8601,
    dwell: @dwell,
    compression_level: @compression_level,
    canonical_id: @canonical_id,
    created_at: @created_at.iso8601,
    updated_at: @updated_at.iso8601,
  }
end