Agent Zero AI framework
Make bundled memory behavior reliable
Alessandrobaa97dcb8778
diff --git a/plugins/_memory/AGENTS.md b/plugins/_memory/AGENTS.mdindex ed8b56d11..1d7f19b44 100644--- a/plugins/_memory/AGENTS.md+++ b/plugins/_memory/AGENTS.md@@ -16,7 +16,10 @@- Keep memory scoped by configured subdirectory/context.- Preserve embedding metadata needed to rebuild indexes safely.+- Delayed recall results must survive `LoopData` replacement, stay scoped to the originating memory/profile/project, and be consumed once by the next prompt; do not persist live task objects into chat JSON.- `memory_load` accepts numeric `threshold` and `limit` values as native numbers or numeric strings and coerces them before vector search.+- Grouped tool-prompt declarations must start with `arg` or `args` so native Responses models receive every memory tool.+- Auto-recall embeds each prepared query once and reuses that vector for the memory and solution filters; manual `memory_load` keeps the ordinary text-query path.- Avoid storing transient action-history noise as durable memory.## Work Guidancediff --git a/plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.py b/plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.pyindex 42fb393b0..0e010b245 100644--- a/plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.py+++ b/plugins/_memory/extensions/python/message_loop_prompts_after/_50_recall_memories.py@@ -1,18 +1,37 @@import asynciofrom helpers.extension import Extensionfrom agent import LoopData-from helpers import dirty_json, errors, log, plugins+from helpers import cache, dirty_json, errors, log, plugins# Direct import - this extension lives inside the memory plugin-from plugins._memory.helpers.memory import Memory+from plugins._memory.helpers.memory import Memory, get_agent_memory_subdirfrom plugins._memory.tools.memory_load import DEFAULT_THRESHOLD as DEFAULT_MEMORY_THRESHOLDDATA_NAME_TASK = "_recall_memories_task"DATA_NAME_ITER = "_recall_memories_iter"+DATA_NAME_LOOP = "_recall_memories_loop"+DATA_NAME_RESULT = "_recall_memories_result"+DATA_NAME_RESULT_SCOPE = "_recall_memories_result_scope"SEARCH_TIMEOUT = 30+def apply_recall_result(loop_data: LoopData, result: dict | None):+ extras = loop_data.extras_persistent+ extras.pop("memories", None)+ extras.pop("solutions", None)+ if not isinstance(result, dict):+ return+ for key in ("memories", "solutions"):+ if result.get(key):+ extras[key] = result[key]+++def get_recall_scope(agent):+ memory_subdir = get_agent_memory_subdir(agent)+ return cache.determine_cache_key(agent, memory_subdir)++class RecallMemories(Extension):# INTERVAL = 3@@ -35,43 +54,97 @@ class RecallMemories(Extension):if not set["memory_recall_enabled"]:return None+ recall_scope = get_recall_scope(self.agent)+ cached_result = self.agent.get_data(DATA_NAME_RESULT)+ if cached_result is not None:+ if self.agent.get_data(DATA_NAME_RESULT_SCOPE) == recall_scope:+ apply_recall_result(loop_data, cached_result)+ else:+ cached_result = None+ self.agent.set_data(DATA_NAME_RESULT, None)+ self.agent.set_data(DATA_NAME_RESULT_SCOPE, None)+# every X iterations (or the first one) recall memories- if loop_data.iteration % set["memory_recall_interval"] == 0:+ if loop_data.iteration % set["memory_recall_interval"] != 0:+ return- # show util message right away- log_item = self.agent.context.log.log(- type="util",- heading="Searching memories...",- )+ previous_task = self.agent.get_data(DATA_NAME_TASK)+ previous_loop = self.agent.get_data(DATA_NAME_LOOP)+ if previous_task and not previous_task.done():+ if previous_loop is loop_data:+ return+ previous_task.cancel()- task = asyncio.create_task(- asyncio.wait_for(- self.search_memories(loop_data=loop_data, log_item=log_item, **kwargs),- timeout=SEARCH_TIMEOUT,- )+ if cached_result is None:+ apply_recall_result(loop_data, {})++ # show util message right away+ log_item = self.agent.context.log.log(+ type="util",+ heading="Searching memories...",+ )++ task = asyncio.create_task(+ self.search_and_cache(+ loop_data=loop_data,+ log_item=log_item,+ recall_scope=recall_scope,+ **kwargs,)- else:- task = None+ )# set to agent to be able to wait for itself.agent.set_data(DATA_NAME_TASK, task)self.agent.set_data(DATA_NAME_ITER, loop_data.iteration)+ self.agent.set_data(DATA_NAME_LOOP, loop_data)- async def search_memories(self, log_item: log.LogItem, loop_data: LoopData, **kwargs):+ async def search_and_cache(+ self, log_item: log.LogItem, loop_data: LoopData, recall_scope, **kwargs+ ):if not self.agent:- return-- # cleanup- extras = loop_data.extras_persistent- if "memories" in extras:- del extras["memories"]- if "solutions" in extras:- del extras["solutions"]-+ return {}+ try:+ result = await asyncio.wait_for(+ self.search_memories(+ loop_data=loop_data,+ log_item=log_item,+ memory_subdir=recall_scope[-1],+ **kwargs,+ ),+ timeout=SEARCH_TIMEOUT,+ )+ except TimeoutError:+ log_item.update(heading="Memory recall timed out")+ result = {}+ except Exception as e:+ self.agent.context.log.log(+ type="warning",+ heading="Memory recall error",+ content=errors.format_error(e),+ )+ result = {}+ if get_recall_scope(self.agent) == recall_scope:+ self.agent.set_data(DATA_NAME_RESULT, result)+ self.agent.set_data(DATA_NAME_RESULT_SCOPE, recall_scope)+ else:+ result = {}+ self.agent.set_data(DATA_NAME_RESULT, None)+ self.agent.set_data(DATA_NAME_RESULT_SCOPE, None)+ return result++ async def search_memories(+ self,+ log_item: log.LogItem,+ loop_data: LoopData,+ memory_subdir: str = "",+ **kwargs,+ ):+ if not self.agent:+ return {}set = plugins.get_plugin_config("_memory", self.agent)if not set:- return None+ return {}# try:# get system message and chat history for util llm@@ -113,7 +186,7 @@ class RecallMemories(Extension):log_item.update(heading="Failed to generate memory query",)- return+ return {}# otherwise use the message and history as queryelse:@@ -124,10 +197,16 @@ class RecallMemories(Extension):log_item.update(query="No relevant memory query generated, skipping search",)- return+ return {}# get memory database+ if memory_subdir and get_agent_memory_subdir(self.agent) != memory_subdir:+ return {}db = await Memory.get(self.agent)+ if memory_subdir and db.memory_subdir != memory_subdir:+ return {}++ embedding = await db.embed_query(query)# search for general memories and fragmentsmemories = await db.search_similarity_threshold(@@ -135,6 +214,7 @@ class RecallMemories(Extension):limit=set["memory_recall_memories_max_search"],threshold=set["memory_recall_similarity_threshold"],filter=f"area == '{Memory.Area.MAIN.value}' or area == '{Memory.Area.FRAGMENTS.value}'", # exclude solutions+ embedding=embedding,)# search for solutions@@ -143,13 +223,14 @@ class RecallMemories(Extension):limit=set["memory_recall_solutions_max_search"],threshold=set["memory_recall_similarity_threshold"],filter=f"area == '{Memory.Area.SOLUTIONS.value}'", # exclude solutions+ embedding=embedding,)if not memories and not solutions:log_item.update(heading="No memories or solutions found",)- return+ return {}# if post filtering is enabledif set["memory_recall_post_filter"]:@@ -218,12 +299,13 @@ class RecallMemories(Extension):if solutions_txt:log_item.update(solutions=solutions_txt)- # place to prompt+ result = {}if memories_txt:- extras["memories"] = self.agent.parse_prompt(+ result["memories"] = self.agent.parse_prompt("agent.system.memories.md", memories=memories_txt)if solutions_txt:- extras["solutions"] = self.agent.parse_prompt(+ result["solutions"] = self.agent.parse_prompt("agent.system.solutions.md", solutions=solutions_txt)+ return resultdiff --git a/plugins/_memory/extensions/python/message_loop_prompts_after/_91_recall_wait.py b/plugins/_memory/extensions/python/message_loop_prompts_after/_91_recall_wait.pyindex 6076847ca..e446385f4 100644--- a/plugins/_memory/extensions/python/message_loop_prompts_after/_91_recall_wait.py+++ b/plugins/_memory/extensions/python/message_loop_prompts_after/_91_recall_wait.py@@ -1,6 +1,13 @@from helpers.extension import Extensionfrom agent import LoopData-from plugins._memory.extensions.python.message_loop_prompts_after._50_recall_memories import DATA_NAME_TASK as DATA_NAME_TASK_MEMORIES, DATA_NAME_ITER as DATA_NAME_ITER_MEMORIES+from plugins._memory.extensions.python.message_loop_prompts_after._50_recall_memories import (+ DATA_NAME_ITER as DATA_NAME_ITER_MEMORIES,+ DATA_NAME_RESULT as DATA_NAME_RESULT_MEMORIES,+ DATA_NAME_RESULT_SCOPE as DATA_NAME_RESULT_SCOPE_MEMORIES,+ DATA_NAME_TASK as DATA_NAME_TASK_MEMORIES,+ apply_recall_result,+ get_recall_scope,+)from helpers import pluginsclass RecallWait(Extension):@@ -16,15 +23,23 @@ class RecallWait(Extension):task = self.agent.get_data(DATA_NAME_TASK_MEMORIES)iter = self.agent.get_data(DATA_NAME_ITER_MEMORIES) or 0- if task and not task.done():+ if task:# if memory recall is set to delayed mode, do not await on the iteration it was calledif set["memory_recall_delayed"]:- if iter == loop_data.iteration:+ if iter == loop_data.iteration and not task.done():# insert info about delayed memory to extrasdelay_text = self.agent.read_prompt("memory.recall_delay_msg.md")loop_data.extras_temporary["memory_recall_delayed"] = delay_textreturn# otherwise await the task- await task+ result = await task+ if self.agent.get_data(DATA_NAME_RESULT_SCOPE_MEMORIES) == get_recall_scope(+ self.agent+ ):+ apply_recall_result(loop_data, result)+ else:+ apply_recall_result(loop_data, {})+ self.agent.set_data(DATA_NAME_RESULT_MEMORIES, None)+ self.agent.set_data(DATA_NAME_RESULT_SCOPE_MEMORIES, None)diff --git a/plugins/_memory/helpers/memory.py b/plugins/_memory/helpers/memory.pyindex 364bfe76c..d598f7ba6 100644--- a/plugins/_memory/helpers/memory.py+++ b/plugins/_memory/helpers/memory.py@@ -337,11 +337,31 @@ class Memory:def get_document_by_id(self, id: str) -> Document | None:return self.db.get_by_ids(id)[0]+ async def embed_query(self, query: str) -> list[float]:+ return await self.db.embedding_function.aembed_query(query)+async def search_similarity_threshold(- self, query: str, limit: int, threshold: float, filter: str = ""+ self,+ query: str,+ limit: int,+ threshold: float,+ filter: str = "",+ embedding: list[float] | None = None,):comparator = Memory._get_comparator(filter) if filter else None+ if embedding is not None:+ docs_and_scores = await self.db.asimilarity_search_with_score_by_vector(+ embedding,+ k=limit,+ filter=comparator,+ )+ return [+ doc+ for doc, score in docs_and_scores+ if Memory._cosine_normalizer(score) >= threshold+ ]+return await self.db.asearch(query,search_type="similarity_score_threshold",diff --git a/plugins/_memory/prompts/agent.system.tool.memory.md b/plugins/_memory/prompts/agent.system.tool.memory.mdindex 02f10a974..03195fa18 100644--- a/plugins/_memory/prompts/agent.system.tool.memory.md+++ b/plugins/_memory/prompts/agent.system.tool.memory.md@@ -1,10 +1,9 @@## memory toolsuse when durable recall or storage is useful-- `memory_load`: search stored memories by meaning and metadata-- `memory_save`: store durable information for future recall-- `memory_delete`: delete memories by exact ID-- `memory_forget`: find and remove memories matching a query-args: load uses `query`, optional `threshold`, `limit`, `filter`; save uses `text`, optional `area` and metadata; delete uses comma-separated `ids`; forget uses `query`, optional `threshold`, `filter`+- `memory_load`: args `query`, optional `threshold`, `limit`, `filter`; search by meaning and metadata+- `memory_save`: args `text`, optional `area` and metadata; store durable information; returns a memory ID on success+- `memory_delete`: arg comma-separated `ids`; delete memories by exact ID+- `memory_forget`: args `query`, optional `threshold`, `filter`; find and remove matching memoriesnotes:- `threshold` is similarity from `0` to `1`diff --git a/tests/test_memory_cleanup.py b/tests/test_memory_cleanup.pyindex 49ee90fdd..ce5d66b8e 100644--- a/tests/test_memory_cleanup.py+++ b/tests/test_memory_cleanup.py@@ -36,6 +36,32 @@ class FakeFaiss:return [self.docs[doc_id] for doc_id in ids if doc_id in self.docs]+class FakeEmbeddings:+ def __init__(self):+ self.queries: list[str] = []++ async def aembed_query(self, query: str):+ self.queries.append(query)+ return [0.25, 0.75]+++class FakeVectorSearch:+ def __init__(self):+ self.embedding_function = FakeEmbeddings()+ self.docs = [+ (Document(page_content="main", metadata={"area": "main"}), 0.8),+ (Document(page_content="solution", metadata={"area": "solutions"}), 0.7),+ (Document(page_content="weak", metadata={"area": "main"}), 0.2),+ ]+ self.embeddings: list[list[float]] = []++ async def asimilarity_search_with_score_by_vector(+ self, embedding, *, k, filter+ ):+ self.embeddings.append(embedding)+ return [(doc, score) for doc, score in self.docs if filter(doc.metadata)][:k]++def test_memory_forget_removes_exact_matches_and_derived_fragments():main = Document(page_content="User currently prefers memory cleanup token banana-397.",@@ -91,3 +117,33 @@ def test_memory_delete_cascades_even_when_original_id_is_already_missing():assert [doc.metadata["id"] for doc in removed] == ["replacement-1"]assert fake_db.deleted == ["replacement-1"]assert fake_db.docs == {}+++def test_memory_reuses_one_query_embedding_across_filtered_searches():+ fake_db = FakeVectorSearch()+ memory = Memory(fake_db, memory_subdir="test")++ async def search():+ embedding = await memory.embed_query("shared recall query")+ memories = await memory.search_similarity_threshold(+ query="shared recall query",+ limit=12,+ threshold=0.7,+ filter="area == 'main'",+ embedding=embedding,+ )+ solutions = await memory.search_similarity_threshold(+ query="shared recall query",+ limit=8,+ threshold=0.7,+ filter="area == 'solutions'",+ embedding=embedding,+ )+ return memories, solutions++ memories, solutions = asyncio.run(search())++ assert fake_db.embedding_function.queries == ["shared recall query"]+ assert fake_db.embeddings == [[0.25, 0.75], [0.25, 0.75]]+ assert [doc.page_content for doc in memories] == ["main"]+ assert [doc.page_content for doc in solutions] == ["solution"]diff --git a/tests/test_memory_recall.py b/tests/test_memory_recall.pynew file mode 100644index 000000000..dc70b5e0e--- /dev/null+++ b/tests/test_memory_recall.py@@ -0,0 +1,171 @@+import asyncio+import sys+from pathlib import Path+from types import SimpleNamespace++import pytest++PROJECT_ROOT = Path(__file__).resolve().parents[1]+if str(PROJECT_ROOT) not in sys.path:+ sys.path.insert(0, str(PROJECT_ROOT))++from agent import LoopData+from plugins._memory.extensions.python.message_loop_prompts_after import (+ _50_recall_memories as recall_module,+ _91_recall_wait as wait_module,+)+++class _LogItem:+ def update(self, **_kwargs):+ pass+++class _Agent:+ def __init__(self):+ self.data = {}+ self.project = "project-a"+ self.config = SimpleNamespace(profile="agent0")+ self.context = SimpleNamespace(+ log=SimpleNamespace(log=lambda **_kwargs: _LogItem()),+ get_data=lambda *_args, **_kwargs: self.project,+ )++ def get_data(self, key):+ return self.data.get(key)++ def set_data(self, key, value):+ self.data[key] = value++ def read_prompt(self, _name):+ return "Recall is running in the background."+++def _settings():+ return {+ "memory_recall_enabled": True,+ "memory_recall_delayed": True,+ "memory_recall_interval": 1,+ }+++async def test_delayed_recall_result_reaches_the_next_monologue(monkeypatch):+ agent = _Agent()+ recall = recall_module.RecallMemories(agent=agent)+ monkeypatch.setattr(+ recall_module.plugins, "get_plugin_config", lambda *_args: _settings()+ )++ async def search_memories(**_kwargs):+ return {"memories": "recalled context"}++ monkeypatch.setattr(recall, "search_memories", search_memories)++ first_loop = LoopData()+ first_loop.iteration = 0+ await recall.execute(loop_data=first_loop)+ await agent.get_data(recall_module.DATA_NAME_TASK)++ next_loop = LoopData()+ next_loop.iteration = 0+ await recall.execute(loop_data=next_loop)+ await agent.get_data(recall_module.DATA_NAME_TASK)++ assert next_loop.extras_persistent["memories"] == "recalled context"+++async def test_delayed_recall_task_survives_the_next_internal_iteration(monkeypatch):+ agent = _Agent()+ recall = recall_module.RecallMemories(agent=agent)+ wait = wait_module.RecallWait(agent=agent)+ settings = _settings()+ monkeypatch.setattr(+ recall_module.plugins, "get_plugin_config", lambda *_args: settings+ )++ release = asyncio.Event()++ async def search_memories(**_kwargs):+ await release.wait()+ return {"solutions": "recalled solution"}++ monkeypatch.setattr(recall, "search_memories", search_memories)++ loop_data = LoopData()+ loop_data.iteration = 0+ await recall.execute(loop_data=loop_data)+ first_task = agent.get_data(recall_module.DATA_NAME_TASK)+ await wait.execute(loop_data=loop_data)+ assert "memory_recall_delayed" in loop_data.extras_temporary++ loop_data.iteration = 1+ await recall.execute(loop_data=loop_data)+ next_task = agent.get_data(recall_module.DATA_NAME_TASK)+ release.set()+ await first_task+ if next_task is not first_task:+ await next_task++ assert next_task is first_task+ await wait.execute(loop_data=loop_data)+ assert loop_data.extras_persistent["solutions"] == "recalled solution"+++async def test_completed_blocking_recall_is_applied(monkeypatch):+ agent = _Agent()+ recall = recall_module.RecallMemories(agent=agent)+ wait = wait_module.RecallWait(agent=agent)+ settings = {**_settings(), "memory_recall_delayed": False}+ monkeypatch.setattr(+ recall_module.plugins, "get_plugin_config", lambda *_args: settings+ )++ async def search_memories(**_kwargs):+ return {"memories": "ready before wait"}++ monkeypatch.setattr(recall, "search_memories", search_memories)++ loop_data = LoopData()+ loop_data.iteration = 0+ await recall.execute(loop_data=loop_data)+ await agent.get_data(recall_module.DATA_NAME_TASK)+ await wait.execute(loop_data=loop_data)++ assert loop_data.extras_persistent["memories"] == "ready before wait"+++async def test_delayed_recall_result_does_not_cross_profile_or_project(monkeypatch):+ agent = _Agent()+ recall = recall_module.RecallMemories(agent=agent)+ monkeypatch.setattr(+ recall_module.plugins, "get_plugin_config", lambda *_args: _settings()+ )++ release = asyncio.Event()++ async def search_memories(**_kwargs):+ await release.wait()+ return {"memories": "project-a memory"}++ monkeypatch.setattr(recall, "search_memories", search_memories)++ first_loop = LoopData()+ first_loop.iteration = 0+ await recall.execute(loop_data=first_loop)+ first_task = agent.get_data(recall_module.DATA_NAME_TASK)++ agent.project = "project-b"+ agent.config.profile = "developer"+ release.set()+ await first_task++ next_loop = LoopData()+ next_loop.iteration = 0+ await recall.execute(loop_data=next_loop)++ assert "memories" not in next_loop.extras_persistent+ await agent.get_data(recall_module.DATA_NAME_TASK)diff --git a/tests/test_responses_tools.py b/tests/test_responses_tools.pyindex 154f5b060..67e5fabc4 100644--- a/tests/test_responses_tools.py+++ b/tests/test_responses_tools.py@@ -292,3 +292,16 @@ durable memory operationsassert responses_tools._tool_names_from_prompt(prompt, fallback="memory") == ["memory_load"]+++def test_bundled_memory_prompt_exposes_every_memory_tool():+ prompt = (+ PROJECT_ROOT / "plugins/_memory/prompts/agent.system.tool.memory.md"+ ).read_text(encoding="utf-8")++ assert responses_tools._tool_names_from_prompt(prompt, fallback="memory") == [+ "memory_load",+ "memory_save",+ "memory_delete",+ "memory_forget",+ ]