Memory Recipes

Standard memory recipes for common episodic memory patterns.

recency_memory

recency_memory(path, max_results=5)

Return a recency-based episodic memory backed by a JSONL file.

Recalls the max_results most recently recorded episodes. No embedding or similarity search is performed.

Parameters:

Name	Type	Description	Default
path	Path	Directory in which the backing JSONL file is stored.	required
max_results	int	Maximum number of recent episodes to recall. Defaults to 5.	5

Returns:

Name	Type	Description
Memory	Memory	Configured memory instance.

Source code in src/llm_agents_from_scratch/memory/recipes.py

def recency_memory(
    path: Path,
    max_results: int = 5,
) -> Memory:
    """Return a recency-based episodic memory backed by a JSONL file.

    Recalls the ``max_results`` most recently recorded episodes. No
    embedding or similarity search is performed.

    Args:
        path (Path): Directory in which the backing JSONL file is stored.
        max_results (int): Maximum number of recent episodes to recall.
            Defaults to 5.

    Returns:
        Memory: Configured memory instance.
    """
    return Memory(store=JSONMemoryStore(dir=path, max_results=max_results))

similarity_memory

similarity_memory(collection='episodes', max_results=5)

Return a similarity-based episodic memory backed by Qdrant.

Recalls the max_results most semantically similar past episodes using cosine similarity over FastEmbed vectors.

Parameters:

Name	Type	Description	Default
collection	str	Name of the Qdrant collection. Defaults to "episodes".	'episodes'
max_results	int	Maximum number of similar episodes to recall. Defaults to 5.	5

Returns:

Name	Type	Description
Memory	Memory	Configured memory instance.

Source code in src/llm_agents_from_scratch/memory/recipes.py

def similarity_memory(
    collection: str = "episodes",
    max_results: int = 5,
) -> Memory:
    """Return a similarity-based episodic memory backed by Qdrant.

    Recalls the ``max_results`` most semantically similar past episodes
    using cosine similarity over FastEmbed vectors.

    Args:
        collection (str): Name of the Qdrant collection. Defaults to
            ``"episodes"``.
        max_results (int): Maximum number of similar episodes to recall.
            Defaults to 5.

    Returns:
        Memory: Configured memory instance.
    """
    return Memory(
        store=QdrantMemoryStore(
            collection_name=collection,
            max_results=max_results,
        ),
    )

reflective_memory

reflective_memory(
    llm, collection="episodes", max_results=5, template=None
)

Return a reflective episodic memory backed by Qdrant.

Implements the Reflexion pattern: at record time an LLM distils a one-sentence lesson from the episode and stores it under episode.metadata["reflection"], which is then surfaced on recall via Episode.format(). Episodes are retrieved by similarity search so semantically related past reflections surface naturally.

Parameters:

Name	Type	Description	Default
llm	BaseLLM	LLM used to generate the reflection.	required
collection	str	Name of the Qdrant collection. Defaults to "episodes".	'episodes'
max_results	int	Maximum number of similar episodes to recall. Defaults to 5.	5
template	str | None	Prompt template for the reflection step. Must contain {instruction} and {result} placeholders. Defaults to None, which uses the built-in one-sentence lesson template.	None

Returns:

Name	Type	Description
Memory	Memory	Configured memory instance.

Source code in src/llm_agents_from_scratch/memory/recipes.py

def reflective_memory(
    llm: BaseLLM,
    collection: str = "episodes",
    max_results: int = 5,
    template: str | None = None,
) -> Memory:
    """Return a reflective episodic memory backed by Qdrant.

    Implements the Reflexion pattern: at record time an LLM distils a
    one-sentence lesson from the episode and stores it under
    ``episode.metadata["reflection"]``, which is then surfaced on
    recall via ``Episode.format()``. Episodes are retrieved by
    similarity search so semantically related past reflections surface
    naturally.

    Args:
        llm (BaseLLM): LLM used to generate the reflection.
        collection (str): Name of the Qdrant collection. Defaults to
            ``"episodes"``.
        max_results (int): Maximum number of similar episodes to recall.
            Defaults to 5.
        template (str | None): Prompt template for the reflection step.
            Must contain ``{instruction}`` and ``{result}`` placeholders.
            Defaults to ``None``, which uses the built-in one-sentence
            lesson template.

    Returns:
        Memory: Configured memory instance.
    """
    reflection_template = template or _REFLECTION_TEMPLATE

    async def _reflect(episode: Episode) -> str:
        prompt = reflection_template.format(
            instruction=episode.task.instruction,
            result=episode.result.content,
        )
        result = await llm.complete(prompt)
        return result.response  # type: ignore[no-any-return]

    return Memory(
        store=QdrantMemoryStore(
            collection_name=collection,
            max_results=max_results,
        ),
        metadata_fns={"reflection": _reflect},
    )