Skip to content

simulatecraft.memory.retrieval

simulatecraft.memory.retrieval

Retrieval: recency + importance + embedding-similarity scoring over a MemoryStream.

EmbeddingBackend

Swappable embedding backend. Implement embed(list[str]) -> (n, dim) float32.

HashingEmbedding 

HashingEmbedding(dim: int = 128, ngram: int = 3)

Bases: EmbeddingBackend

Dependency-free deterministic embeddings via character n-gram hashing.

Quality is far below a real model but it keeps tests and offline demos working with zero downloads. Swap in SentenceTransformerBackend for real use.

Source code in src/simulatecraft/memory/retrieval.py 
28
29
30
def __init__(self, dim: int = 128, ngram: int = 3) -> None:
    self.dim = dim
    self.ngram = ngram

SentenceTransformerEmbedding 

SentenceTransformerEmbedding(model_name: str = 'all-MiniLM-L6-v2')

Bases: EmbeddingBackend

Local sentence-transformers model (downloaded on first use).

Source code in src/simulatecraft/memory/retrieval.py 
51
52
53
54
def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
    from sentence_transformers import SentenceTransformer

    self.model = SentenceTransformer(model_name)

Retriever 

Retriever(stream: MemoryStream, embedding_backend: EmbeddingBackend | None = None, *, w_relevance: float = 1.0, w_recency: float = 1.0, w_importance: float = 1.0, recency_decay: float = 0.995)

Weighted relevance+recency+importance retrieval (Generative Agents style).

Source code in src/simulatecraft/memory/retrieval.py 
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
def __init__(
    self,
    stream: MemoryStream,
    embedding_backend: EmbeddingBackend | None = None,
    *,
    w_relevance: float = 1.0,
    w_recency: float = 1.0,
    w_importance: float = 1.0,
    recency_decay: float = 0.995,
) -> None:
    self.stream = stream
    self.embedding_backend = embedding_backend or HashingEmbedding()
    self.w_relevance = w_relevance
    self.w_recency = w_recency
    self.w_importance = w_importance
    self.recency_decay = recency_decay

default_backend 

default_backend(prefer_transformer: bool = False) -> EmbeddingBackend

Use hashing embeddings by default (zero downloads).

Pass prefer_transformer=True or set SIMULATECRAFT_EMBEDDINGS=transformer to load sentence-transformers (requires the optional embeddings extra).

Source code in src/simulatecraft/memory/retrieval.py 
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
def default_backend(prefer_transformer: bool = False) -> EmbeddingBackend:
    """Use hashing embeddings by default (zero downloads).

    Pass ``prefer_transformer=True`` or set ``SIMULATECRAFT_EMBEDDINGS=transformer``
    to load sentence-transformers (requires the optional ``embeddings`` extra).
    """
    import os

    if os.getenv("SIMULATECRAFT_EMBEDDINGS", "").strip().lower() in {"transformer", "st", "hf"}:
        prefer_transformer = True
    if prefer_transformer:
        try:
            return SentenceTransformerEmbedding()
        except Exception:
            pass
    return HashingEmbedding()