`simulatecraft.memory`¶

simulatecraft.memory ¶

Long-term memory: streams, retrieval, and periodic reflection.

ReflectionEngine ¶

ReflectionEngine(summarizer: Summarizer, *, every_n_records: int = 20, min_records: int = 5)

Triggers every every_n_records additions to the stream.

Source code in src/simulatecraft/memory/reflection.py

def __init__(
    self, summarizer: Summarizer, *, every_n_records: int = 20, min_records: int = 5
) -> None:
    self.summarizer = summarizer
    self.every_n_records = every_n_records
    self.min_records = min_records

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

def __init__(self, dim: int = 128, ngram: int = 3) -> None:
    self.dim = dim
    self.ngram = ngram

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

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

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

def __init__(self, model_name: str = "all-MiniLM-L6-v2") -> None:
    from sentence_transformers import SentenceTransformer

    self.model = SentenceTransformer(model_name)

MemoryStream ¶

MemoryStream(scorer: ImportanceScorer | None = None)

Append-only memory log. Records get IDs and wall-clock timestamps.

Source code in src/simulatecraft/memory/stream.py

def __init__(self, scorer: ImportanceScorer | None = None) -> None:
    self.records: list[MemoryRecord] = []
    self._ids = itertools.count(1)
    self.scorer = scorer

simulatecraft.memory¶