Class: HTM::WorkingMemory

Inherits: Object

Working Memory - Token-limited active context for immediate LLM use

WorkingMemory manages the active conversation context within token limits. When full, it evicts less important or older nodes back to long-term storage.

Thread Safety: All public methods are protected by a mutex to ensure safe concurrent access from multiple threads.

Attributes

max_tokens[RW]

Returns the value of attribute max_tokens.

Instance Methods

add(key, value, token_count:, access_count:0, last_accessed:nil, from_recall:false)

Add a node to working memory

@param [String] Node identifier

@param [String] Node content

@param [Integer] Number of tokens in this node

@param [Integer] Access count from long-term memory (default: 0)

@param [Time, nil] Last access time from long-term memory

@param [Boolean] Whether this node was recalled from long-term memory

@return [void]

add_from_sync(id:, content:, token_count:, created_at:)

Add a node from sync notification (bypasses normal add flow)

Called by RobotGroup when another robot adds to working memory. Does not trigger notifications to avoid infinite loops.

@param [Integer] Node database ID

@param [String] Node content

@param [Integer] Token count

@param [Time] When node was created

@return [void]

assemble_context(strategy:, max_tokens:nil)

Assemble context string for LLM

@param [Symbol] Assembly strategy (:recent, :frequent, :balanced) - :recent - Most recently accessed (LRU) - :frequent - Most frequently accessed (LFU) - :balanced - Combines frequency × recency

@param [Integer, nil] Optional token limit

@return [String] Assembled context

clear()

Clear all nodes from working memory

@return [void]

clear_from_sync()

Clear all nodes from sync notification

Called by RobotGroup when another robot clears working memory.

@return [void]

evict_to_make_space(needed_tokens)

Evict nodes to make space

Uses LFU + LRU strategy: Least Frequently Used + Least Recently Used Nodes with low access count and old timestamps are evicted first

@param [Integer] Number of tokens needed

@return [Array] Evicted nodes

has_space?(token_count)

Check if there's space for a node

@param [Integer] Number of tokens needed

@return [Boolean] true if space available

initialize(max_tokens:)

Initialize working memory

@param [Integer] Maximum tokens allowed in working memory

@return [WorkingMemory] a new instance of WorkingMemory

node_count()

Get node count

@return [Integer] Number of nodes in working memory

remove(key)

Remove a node from working memory

@param [String] Node identifier

@return [void]

remove_from_sync(node_id)

Remove a node from sync notification

Called by RobotGroup when another robot evicts from working memory.

@param [Integer] Node database ID

@return [void]

token_count()

Get current token count

@return [Integer] Total tokens in working memory

utilization_percentage()

Get utilization percentage

@return [Float] Percentage of working memory used