Module: Llmemory::MemoryModule

Included in:
LongTerm::Episodic::Memory, LongTerm::FileBased::Memory, LongTerm::GraphBased::Memory, LongTerm::Procedural::Memory
Defined in:
lib/llmemory/memory_module.rb

Overview

Uniform contract for queryable long-term memories (file-based, graph-based, episodic). CoALA argues agents should be modular with standardized abstractions; this mixin gives any memory store the same agent-facing surface so frameworks can treat them polymorphically:

read(query, user_id:, limit:)          -> relevant entries (retrieval)
write(payload, ...)                    -> ingest into the store (learning)
list(user_id:, limit:, offset:)        -> enumerate stored entries (paginated)
stats(user_id:)                        -> counts and metadata

‘read` defaults to the de-facto `search_candidates` interface the retrieval Engine already relies on. `write`, `list` and `stats` are implemented by each including class over its native API.

Deliberately excluded: session-state stores (Checkpoint, WorkingMemory) are a different abstraction (K/V session state, not a retrievable corpus), and deletion/forgetting semantics are deferred to a coherent unlearning API.

Instance Method Summary collapse

Instance Method Details

#forget(ids:, reason: nil, mode: :soft) ⇒ Object

Removes entries by id (the same ids returned by #read) and records the removal in a ForgetLog audit. Returns the number of entries removed.

mode:

:soft (default) — soft-archive: entries are excluded from list/search/
  retrieval but remain accessible by id (think "trash"). Reversible if
  the store supports it.
:hard           — physical deletion. Irreversible.

Implemented by stores with a clear deletion model; others may not support it (CoALA-style “unlearning” is understudied; deletion semantics differ).

Raises:

  • (NotImplementedError) 


52
53
54
 
# File 'lib/llmemory/memory_module.rb', line 52

def forget(ids:, reason: nil, mode: :soft)
  raise NotImplementedError, "#{self.class} does not support #forget"
end

#forget_log ⇒ Object

Shared audit trail for #forget. Lazily built; override or inject by setting



58
59
60
 
# File 'lib/llmemory/memory_module.rb', line 58

def forget_log
  @forget_log ||= Llmemory::ForgetLog.new
end

#list(user_id: nil, limit: nil, offset: nil) ⇒ Object

Raises:

  • (NotImplementedError) 


33
34
35
 
# File 'lib/llmemory/memory_module.rb', line 33

def list(user_id: nil, limit: nil, offset: nil)
  raise NotImplementedError, "#{self.class} must implement #list"
end

#read(query, user_id: nil, limit: 20) ⇒ Object 



22
23
24
25
26
27
 
# File 'lib/llmemory/memory_module.rb', line 22

def read(query, user_id: nil, limit: 20)
  unless respond_to?(:search_candidates)
    raise NotImplementedError, "#{self.class} must implement #read or #search_candidates"
  end
  search_candidates(query, user_id: user_id, top_k: limit)
end

#stats(user_id: nil) ⇒ Object

Raises:

  • (NotImplementedError) 


37
38
39
 
# File 'lib/llmemory/memory_module.rb', line 37

def stats(user_id: nil)
  raise NotImplementedError, "#{self.class} must implement #stats"
end

#write ⇒ Object

Raises:

  • (NotImplementedError) 


29
30
31
 
# File 'lib/llmemory/memory_module.rb', line 29

def write(*, **)
  raise NotImplementedError, "#{self.class} must implement #write"
end