Skip to content

Agent Zero AI framework

Make bundled memory behavior reliable

Alessandrobaa97dcb8778
diff --git a/plugins/_memory/AGENTS.md b/plugins/_memory/AGENTS.md
index 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 Guidance
diff --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.py
index 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 asyncio
from helpers.extension import Extension
from 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_subdir
from plugins._memory.tools.memory_load import DEFAULT_THRESHOLD as DEFAULT_MEMORY_THRESHOLD
DATA_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 it
self.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 query
else:
@@ -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 fragments
memories = 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 enabled
if 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 result
diff --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.py
index 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 Extension
from 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 plugins
class 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 called
if set["memory_recall_delayed"]:
- if iter == loop_data.iteration:
+ if iter == loop_data.iteration and not task.done():
# insert info about delayed memory to extras
delay_text = self.agent.read_prompt("memory.recall_delay_msg.md")
loop_data.extras_temporary["memory_recall_delayed"] = delay_text
return
# 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.py
index 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.md
index 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 tools
use 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 memories
notes:
- `threshold` is similarity from `0` to `1`
diff --git a/tests/test_memory_cleanup.py b/tests/test_memory_cleanup.py
index 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.py
new file mode 100644
index 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.py
index 154f5b060..67e5fabc4 100644
--- a/tests/test_responses_tools.py
+++ b/tests/test_responses_tools.py
@@ -292,3 +292,16 @@ durable memory operations
assert 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",
+ ]