nodestep.middleware.memory

Long-term memory for the model, stored as JSON files by FilesystemMemory.

See Memory.

Middleware

BaseMemory

Base class for middleware that gives the model long-term memory.

Subclass of Middleware.

Methods

tools()

Return the memory tools.

tools() -> Iterable[Tool]

FilesystemMemory

FilesystemMemory(root_dir, *, scope)

Memory tools that store entries as UTF-8 JSON files under root_dir.

Subclass of BaseMemory.

Entries of scope "user:42" live in root_dir/memories/user/42/.

Parameters

root_dir	str | Path	Storage directory; created on the first write.
scope	str | Callable[[ToolContext], str]	The scope, or a function of the call's ToolContext that returns it, e.g. lambda ctx: f"user:{ctx.context.user_id}". Segments are separated by :; empty, . and .. segments are refused.

Raises

MemoryConfigError	If root_dir is an existing file or scope is an invalid string.
TypeError	If scope is neither a string nor callable.

Methods

scope_for(ctx)

Return the scope of a tool call.

scope_for(ctx) -> str

Parameters

ctx	ToolContext

Raises

TypeError

If the scope callable returns something other than a str.

tools()

Return the save, search, list and delete tools.

tools() -> tuple[Tool, ...]

Entries and tool results

Memory

Memory(*, key, title, content, memory_type='fact', scope='global', created_at=None, updated_at=None)

A stored memory entry.

Attributes

key	str	Name of the entry within its scope; saving the same key replaces it.
title	str
content	str
memory_type	str	Free label chosen by the model, such as "fact".
scope	str	Scope such as "global" or "user:42", set by the middleware.
created_at	datetime | None	Set to the current time when not given; a save keeps the stored one.
updated_at	datetime | None	Set to the current time when not given and on every save.

Methods

searchable_text()

Text used for keyword search.

searchable_text() -> str

MemorySearchResult

MemorySearchResult(*, query, results, skipped=[])

Result of the search_memory tool.

Attributes

query	str
results	list[Memory]	Matching memories, best first.
skipped	list[str]	Memory files that could not be read.

MemoryListResult

MemoryListResult(*, scope, entries, skipped=[])

Memories of one scope, the result of the list_memories tool.

Attributes

scope	str
entries	list[Memory]
skipped	list[str]	Memory files that could not be read.

MemoryDeleteResult

MemoryDeleteResult(*, key, scope, deleted)

Result of the delete_memory tool.

Attributes

key	str
scope	str
deleted	bool	Whether an entry with the key existed and was deleted.

Storage and search

save_memory_to_disk

save_memory_to_disk(root_dir, memory) -> Memory

Write a memory as JSON, keeping its original creation time.

Parameters

root_dir	Path	Folder that holds the memories folder.
memory	Memory

Raises

ValueError

If a file for the key exists but is not valid UTF-8 memory JSON; the file is left as it is.

load_memories_from_disk

load_memories_from_disk(root_dir, scope) -> MemoryListResult

Load all memories of a scope.

Parameters

root_dir	Path	Folder that holds the memories folder.
scope	str	Scope such as "global" or "user:42".

Returns

MemoryListResult

The memories, and in skipped the names of files that are not valid UTF-8 memory JSON.

delete_memory_from_disk

delete_memory_from_disk(root_dir, scope, key) -> bool

Delete one memory.

Parameters

root_dir	Path	Folder that holds the memories folder.
scope	str
key	str

Returns

bool	Whether a memory was deleted.

bm25_search

bm25_search(memories, query, top_k=10, k1=1.2, b=0.75) -> list[Memory]

Rank memories against a query with BM25 keyword scoring.

Parameters

memories	list[Memory]
query	str	Words to look for in the titles and contents.
top_k	int	Maximum number of results.
k1	float	BM25 term saturation: how much repeated words count.
b	float	BM25 length normalization, from 0 (none) to 1 (full).

Returns

list[Memory]

Matching memories, best first.

Raises

ValueError

If top_k is smaller than 1.

Errors

MemoryConfigError

Raised when FilesystemMemory is configured with an unusable root or scope.

Subclass of NodestepError.