Skip to content

AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.

feat(backend): MemoryEnvelope metadata model, scoped retrieval, and memory hardening (#12765)

Nicholas Tindleab3221a2511a
diff --git a/autogpt_platform/backend/.env.default b/autogpt_platform/backend/.env.default
index c01da95a03..e731f9f9bf 100644
--- a/autogpt_platform/backend/.env.default
+++ b/autogpt_platform/backend/.env.default
@@ -60,7 +60,8 @@ NVIDIA_API_KEY=
# Graphiti Temporal Knowledge Graph Memory
# Rollout controlled by LaunchDarkly flag "graphiti-memory"
-# LLM/embedder keys fall back to OPEN_ROUTER_API_KEY and OPENAI_API_KEY when empty.
+# LLM key falls back to CHAT_API_KEY (AutoPilot), then OPEN_ROUTER_API_KEY.
+# Embedder key falls back to CHAT_OPENAI_API_KEY (AutoPilot), then OPENAI_API_KEY.
GRAPHITI_FALKORDB_HOST=localhost
GRAPHITI_FALKORDB_PORT=6380
GRAPHITI_FALKORDB_PASSWORD=
diff --git a/autogpt_platform/backend/backend/api/features/chat/routes.py b/autogpt_platform/backend/backend/api/features/chat/routes.py
index 7d0521cb81..7496c214ac 100644
--- a/autogpt_platform/backend/backend/api/features/chat/routes.py
+++ b/autogpt_platform/backend/backend/api/features/chat/routes.py
@@ -62,6 +62,10 @@ from backend.copilot.tools.models import (
InputValidationErrorResponse,
MCPToolOutputResponse,
MCPToolsDiscoveredResponse,
+ MemoryForgetCandidatesResponse,
+ MemoryForgetConfirmResponse,
+ MemorySearchResponse,
+ MemoryStoreResponse,
NeedLoginResponse,
NoResultsResponse,
SetupRequirementsResponse,
@@ -1365,6 +1369,10 @@ ToolResponseUnion = (
| DocPageResponse
| MCPToolsDiscoveredResponse
| MCPToolOutputResponse
+ | MemoryStoreResponse
+ | MemorySearchResponse
+ | MemoryForgetCandidatesResponse
+ | MemoryForgetConfirmResponse
)
diff --git a/autogpt_platform/backend/backend/copilot/baseline/service.py b/autogpt_platform/backend/backend/copilot/baseline/service.py
index bb3906811c..dd6aa121b6 100644
--- a/autogpt_platform/backend/backend/copilot/baseline/service.py
+++ b/autogpt_platform/backend/backend/copilot/baseline/service.py
@@ -293,56 +293,69 @@ async def _baseline_llm_caller(
)
tool_calls_by_index: dict[int, dict[str, str]] = {}
- async for chunk in response:
- if chunk.usage:
- state.turn_prompt_tokens += chunk.usage.prompt_tokens or 0
- state.turn_completion_tokens += chunk.usage.completion_tokens or 0
- # Extract cache token details when available (OpenAI /
- # OpenRouter include these in prompt_tokens_details).
- ptd = getattr(chunk.usage, "prompt_tokens_details", None)
- if ptd:
- state.turn_cache_read_tokens += (
- getattr(ptd, "cached_tokens", 0) or 0
- )
- # cache_creation_input_tokens is reported by some providers
- # (e.g. Anthropic native) but not standard OpenAI streaming.
- state.turn_cache_creation_tokens += (
- getattr(ptd, "cache_creation_input_tokens", 0) or 0
- )
+ # Iterate under an inner try/finally so early exits (cancel, tool-call
+ # break, exception) always release the underlying httpx connection.
+ # Without this, openai.AsyncStream leaks the streaming response and
+ # the TCP socket ends up in CLOSE_WAIT until the process exits.
+ try:
+ async for chunk in response:
+ if chunk.usage:
+ state.turn_prompt_tokens += chunk.usage.prompt_tokens or 0
+ state.turn_completion_tokens += chunk.usage.completion_tokens or 0
+ # Extract cache token details when available (OpenAI /
+ # OpenRouter include these in prompt_tokens_details).
+ ptd = getattr(chunk.usage, "prompt_tokens_details", None)
+ if ptd:
+ state.turn_cache_read_tokens += (
+ getattr(ptd, "cached_tokens", 0) or 0
+ )
+ # cache_creation_input_tokens is reported by some providers
+ # (e.g. Anthropic native) but not standard OpenAI streaming.
+ state.turn_cache_creation_tokens += (
+ getattr(ptd, "cache_creation_input_tokens", 0) or 0
+ )
- delta = chunk.choices[0].delta if chunk.choices else None
- if not delta:
- continue
+ delta = chunk.choices[0].delta if chunk.choices else None
+ if not delta:
+ continue
- if delta.content:
- emit = state.thinking_stripper.process(delta.content)
- if emit:
- if not state.text_started:
+ if delta.content:
+ emit = state.thinking_stripper.process(delta.content)
+ if emit:
+ if not state.text_started:
+ state.pending_events.append(
+ StreamTextStart(id=state.text_block_id)
+ )
+ state.text_started = True
+ round_text += emit
state.pending_events.append(
- StreamTextStart(id=state.text_block_id)
+ StreamTextDelta(id=state.text_block_id, delta=emit)
)
- state.text_started = True
- round_text += emit
- state.pending_events.append(
- StreamTextDelta(id=state.text_block_id, delta=emit)
- )
- if delta.tool_calls:
- for tc in delta.tool_calls:
- idx = tc.index
- if idx not in tool_calls_by_index:
- tool_calls_by_index[idx] = {
- "id": "",
- "name": "",
- "arguments": "",
- }
- entry = tool_calls_by_index[idx]
- if tc.id:
- entry["id"] = tc.id
- if tc.function and tc.function.name:
- entry["name"] = tc.function.name
- if tc.function and tc.function.arguments:
- entry["arguments"] += tc.function.arguments
+ if delta.tool_calls:
+ for tc in delta.tool_calls:
+ idx = tc.index
+ if idx not in tool_calls_by_index:
+ tool_calls_by_index[idx] = {
+ "id": "",
+ "name": "",
+ "arguments": "",
+ }
+ entry = tool_calls_by_index[idx]
+ if tc.id:
+ entry["id"] = tc.id
+ if tc.function and tc.function.name:
+ entry["name"] = tc.function.name
+ if tc.function and tc.function.arguments:
+ entry["arguments"] += tc.function.arguments
+ finally:
+ # Release the streaming httpx connection back to the pool on every
+ # exit path (normal completion, break, exception). openai.AsyncStream
+ # does not auto-close when the async-for loop exits early.
+ try:
+ await response.close()
+ except Exception:
+ pass
# Flush any buffered text held back by the thinking stripper.
tail = state.thinking_stripper.flush()
@@ -940,13 +953,14 @@ async def stream_chat_completion_baseline(
graphiti_supplement = get_graphiti_supplement() if graphiti_enabled else ""
system_prompt = base_system_prompt + get_baseline_supplement() + graphiti_supplement
- # Warm context: pre-load relevant facts from Graphiti on first turn
+ # Warm context: pre-load relevant facts from Graphiti on first turn.
+ # Stored here but injected into the user message (not the system prompt)
+ # after openai_messages is built — keeps system prompt static for caching.
+ warm_ctx: str | None = None
if graphiti_enabled and user_id and len(session.messages) <= 1:
from backend.copilot.graphiti.context import fetch_warm_context
warm_ctx = await fetch_warm_context(user_id, message or "")
- if warm_ctx:
- system_prompt += f"\n\n{warm_ctx}"
# Compress context if approaching the model's token limit
messages_for_context = await _compress_session_messages(
@@ -996,6 +1010,20 @@ async def stream_chat_completion_baseline(
else:
logger.warning("[Baseline] No user message found for context injection")
+ # Inject Graphiti warm context into the first user message (not the
+ # system prompt) so the system prompt stays static and cacheable.
+ # warm_ctx is already wrapped in <temporal_context>.
+ # Appended AFTER user_context so <user_context> stays at the very start.
+ if warm_ctx:
+ for msg in openai_messages:
+ if msg["role"] == "user":
+ existing = msg.get("content", "")
+ if isinstance(existing, str):
+ msg["content"] = f"{existing}\n\n{warm_ctx}"
+ break
+ # Do NOT append warm_ctx to user_message_for_transcript — it would
+ # persist stale temporal context into the transcript for future turns.
+
# Append user message to transcript.
# Always append when the message is present and is from the user,
# even on duplicate-suppressed retries (is_new_message=False).
@@ -1253,8 +1281,16 @@ async def stream_chat_completion_baseline(
if graphiti_enabled and user_id and message and is_user_message:
from backend.copilot.graphiti.ingest import enqueue_conversation_turn
+ # Pass only the final assistant reply (after stripping tool-loop
+ # chatter) so derived-finding distillation sees the substantive
+ # response, not intermediate tool-planning text.
_ingest_task = asyncio.create_task(
- enqueue_conversation_turn(user_id, session_id, message)
+ enqueue_conversation_turn(
+ user_id,
+ session_id,
+ message,
+ assistant_msg=final_text if state else "",
+ )
)
_background_tasks.add(_ingest_task)
_ingest_task.add_done_callback(_background_tasks.discard)
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/_format.py b/autogpt_platform/backend/backend/copilot/graphiti/_format.py
index fb4a93e393..c6975c5c39 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/_format.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/_format.py
@@ -18,15 +18,24 @@ def extract_temporal_validity(edge) -> tuple[str, str]:
return str(valid_from), str(valid_to)
-def extract_episode_body(episode, max_len: int = 500) -> str:
- """Extract the body text from an episode object, truncated to *max_len*."""
- body = str(
+def extract_episode_body_raw(episode) -> str:
+ """Extract the full body text from an episode object (no truncation).
+
+ Use this when the body needs to be parsed as JSON (e.g. scope filtering
+ on MemoryEnvelope payloads). For display purposes, use
+ ``extract_episode_body()`` which truncates.
+ """
+ return str(
getattr(episode, "content", None)
or getattr(episode, "body", None)
or getattr(episode, "episode_body", None)
or ""
)
- return body[:max_len]
+
+
+def extract_episode_body(episode, max_len: int = 500) -> str:
+ """Extract the body text from an episode object, truncated to *max_len*."""
+ return extract_episode_body_raw(episode)[:max_len]
def extract_episode_timestamp(episode) -> str:
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/client.py b/autogpt_platform/backend/backend/copilot/graphiti/client.py
index 9710354915..65fcdb3abb 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/client.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/client.py
@@ -3,6 +3,7 @@
import asyncio
import logging
import re
+import weakref
from cachetools import TTLCache
@@ -13,8 +14,36 @@ logger = logging.getLogger(__name__)
_GROUP_ID_PATTERN = re.compile(r"^[a-zA-Z0-9_-]+$")
_MAX_GROUP_ID_LEN = 128
-_client_cache: TTLCache | None = None
-_cache_lock = asyncio.Lock()
+
+# Graphiti clients wrap redis.asyncio connections whose internal Futures are
+# pinned to the event loop they were first used on. The CoPilot executor runs
+# one asyncio loop per worker thread, so a process-wide client cache would
+# hand a loop-1-bound connection to a task running on loop 2 → RuntimeError
+# "got Future attached to a different loop". Scope the cache (and its lock)
+# per running loop so each loop gets its own clients.
+class _LoopState:
+ __slots__ = ("cache", "lock")
+
+ def __init__(self) -> None:
+ self.cache: TTLCache = _EvictingTTLCache(
+ maxsize=graphiti_config.client_cache_maxsize,
+ ttl=graphiti_config.client_cache_ttl,
+ )
+ self.lock = asyncio.Lock()
+
+
+_loop_state: "weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, _LoopState]" = (
+ weakref.WeakKeyDictionary()
+)
+
+
+def _get_loop_state() -> _LoopState:
+ loop = asyncio.get_running_loop()
+ state = _loop_state.get(loop)
+ if state is None:
+ state = _LoopState()
+ _loop_state[loop] = state
+ return state
def derive_group_id(user_id: str) -> str:
@@ -88,13 +117,8 @@ class _EvictingTTLCache(TTLCache):
def _get_cache() -> TTLCache:
- global _client_cache
- if _client_cache is None:
- _client_cache = _EvictingTTLCache(
- maxsize=graphiti_config.client_cache_maxsize,
- ttl=graphiti_config.client_cache_ttl,
- )
- return _client_cache
+ """Return the client cache for the current running event loop."""
+ return _get_loop_state().cache
async def get_graphiti_client(group_id: str):
@@ -113,9 +137,10 @@ async def get_graphiti_client(group_id: str):
from .falkordb_driver import AutoGPTFalkorDriver
- cache = _get_cache()
+ state = _get_loop_state()
+ cache = state.cache
- async with _cache_lock:
+ async with state.lock:
if group_id in cache:
return cache[group_id]
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/config.py b/autogpt_platform/backend/backend/copilot/graphiti/config.py
index 94a452165a..08b533b6fc 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/config.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/config.py
@@ -20,8 +20,10 @@ class GraphitiConfig(BaseSettings):
"""Configuration for Graphiti memory integration.
All fields use the ``GRAPHITI_`` env-var prefix, e.g. ``GRAPHITI_ENABLED``.
- LLM/embedder keys fall back to the platform-wide OpenRouter and OpenAI keys
- when left empty so that operators don't need to manage separate credentials.
+ LLM/embedder keys fall back to the AutoPilot-dedicated keys
+ (``CHAT_API_KEY`` / ``CHAT_OPENAI_API_KEY``) so that memory costs are
+ tracked under AutoPilot, then to the platform-wide OpenRouter / OpenAI
+ keys as a last resort.
"""
model_config = SettingsConfigDict(env_prefix="GRAPHITI_", extra="allow")
@@ -42,7 +44,7 @@ class GraphitiConfig(BaseSettings):
)
llm_api_key: str = Field(
default="",
- description="API key for LLM — empty falls back to OPEN_ROUTER_API_KEY",
+ description="API key for LLM — empty falls back to CHAT_API_KEY, then OPEN_ROUTER_API_KEY",
)
# Embedder (separate from LLM — embeddings go direct to OpenAI)
@@ -53,7 +55,7 @@ class GraphitiConfig(BaseSettings):
)
embedder_api_key: str = Field(
default="",
- description="API key for embedder — empty falls back to OPENAI_API_KEY",
+ description="API key for embedder — empty falls back to CHAT_OPENAI_API_KEY, then OPENAI_API_KEY",
)
# Concurrency
@@ -96,7 +98,9 @@ class GraphitiConfig(BaseSettings):
def resolve_llm_api_key(self) -> str:
if self.llm_api_key:
return self.llm_api_key
- return os.getenv("OPEN_ROUTER_API_KEY", "")
+ # Prefer the AutoPilot-dedicated key so memory costs are tracked
+ # separately from the platform-wide OpenRouter key.
+ return os.getenv("CHAT_API_KEY") or os.getenv("OPEN_ROUTER_API_KEY", "")
def resolve_llm_base_url(self) -> str:
if self.llm_base_url:
@@ -106,7 +110,9 @@ class GraphitiConfig(BaseSettings):
def resolve_embedder_api_key(self) -> str:
if self.embedder_api_key:
return self.embedder_api_key
- return os.getenv("OPENAI_API_KEY", "")
+ # Prefer the AutoPilot-dedicated OpenAI key so memory costs are
+ # tracked separately from the platform-wide OpenAI key.
+ return os.getenv("CHAT_OPENAI_API_KEY") or os.getenv("OPENAI_API_KEY", "")
def resolve_embedder_base_url(self) -> str | None:
if self.embedder_base_url:
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/config_test.py b/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
index 7c7a90d7bc..efe36c8586 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/config_test.py
@@ -8,6 +8,8 @@ _ENV_VARS_TO_CLEAR = (
"GRAPHITI_FALKORDB_HOST",
"GRAPHITI_FALKORDB_PORT",
"GRAPHITI_FALKORDB_PASSWORD",
+ "CHAT_API_KEY",
+ "CHAT_OPENAI_API_KEY",
"OPEN_ROUTER_API_KEY",
"OPENAI_API_KEY",
)
@@ -31,7 +33,15 @@ class TestResolveLlmApiKey:
cfg = GraphitiConfig(llm_api_key="my-llm-key")
assert cfg.resolve_llm_api_key() == "my-llm-key"
- def test_falls_back_to_open_router_env(
+ def test_falls_back_to_chat_api_key_first(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ monkeypatch.setenv("CHAT_API_KEY", "autopilot-key")
+ monkeypatch.setenv("OPEN_ROUTER_API_KEY", "platform-key")
+ cfg = GraphitiConfig(llm_api_key="")
+ assert cfg.resolve_llm_api_key() == "autopilot-key"
+
+ def test_falls_back_to_open_router_when_no_chat_key(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setenv("OPEN_ROUTER_API_KEY", "fallback-router-key")
@@ -59,7 +69,15 @@ class TestResolveEmbedderApiKey:
cfg = GraphitiConfig(embedder_api_key="my-embedder-key")
assert cfg.resolve_embedder_api_key() == "my-embedder-key"
- def test_falls_back_to_openai_api_key_env(
+ def test_falls_back_to_chat_openai_api_key_first(
+ self, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ monkeypatch.setenv("CHAT_OPENAI_API_KEY", "autopilot-openai-key")
+ monkeypatch.setenv("OPENAI_API_KEY", "platform-openai-key")
+ cfg = GraphitiConfig(embedder_api_key="")
+ assert cfg.resolve_embedder_api_key() == "autopilot-openai-key"
+
+ def test_falls_back_to_openai_when_no_chat_openai_key(
self, monkeypatch: pytest.MonkeyPatch
) -> None:
monkeypatch.setenv("OPENAI_API_KEY", "fallback-openai-key")
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/context.py b/autogpt_platform/backend/backend/copilot/graphiti/context.py
index 46f9855ab7..29d4e95f47 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/context.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/context.py
@@ -6,6 +6,7 @@ from datetime import datetime, timezone
from ._format import (
extract_episode_body,
+ extract_episode_body_raw,
extract_episode_timestamp,
extract_fact,
extract_temporal_validity,
@@ -68,7 +69,7 @@ async def _fetch(user_id: str, message: str) -> str | None:
return _format_context(edges, episodes)
-def _format_context(edges, episodes) -> str:
+def _format_context(edges, episodes) -> str | None:
sections: list[str] = []
if edges:
@@ -82,12 +83,35 @@ def _format_context(edges, episodes) -> str:
if episodes:
ep_lines = []
for ep in episodes:
+ # Use raw body (no truncation) for scope parsing — truncated
+ # JSON from extract_episode_body() would fail json.loads().
+ raw_body = extract_episode_body_raw(ep)
+ if _is_non_global_scope(raw_body):
+ continue
+ display_body = extract_episode_body(ep)
ts = extract_episode_timestamp(ep)
- body = extract_episode_body(ep)
- ep_lines.append(f" - [{ts}] {body}")
- sections.append(
- "<RECENT_EPISODES>\n" + "\n".join(ep_lines) + "\n</RECENT_EPISODES>"
- )
+ ep_lines.append(f" - [{ts}] {display_body}")
+ if ep_lines:
+ sections.append(
+ "<RECENT_EPISODES>\n" + "\n".join(ep_lines) + "\n</RECENT_EPISODES>"
+ )
+
+ if not sections:
+ return None
body = "\n\n".join(sections)
return f"<temporal_context>\n{body}\n</temporal_context>"
+
+
+def _is_non_global_scope(body: str) -> bool:
+ """Check if an episode body is a MemoryEnvelope with a non-global scope."""
+ import json
+
+ try:
+ data = json.loads(body)
+ if not isinstance(data, dict):
+ return False
+ scope = data.get("scope", "real:global")
+ return scope != "real:global"
+ except (json.JSONDecodeError, TypeError):
+ return False
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/context_test.py b/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
index 616fefa218..ce419b11ff 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/context_test.py
@@ -1,12 +1,15 @@
"""Tests for Graphiti warm context retrieval."""
import asyncio
+from types import SimpleNamespace
from unittest.mock import AsyncMock, patch
import pytest
from . import context
-from .context import fetch_warm_context
+from ._format import extract_episode_body
+from .context import _format_context, _is_non_global_scope, fetch_warm_context
+from .memory_model import MemoryEnvelope, MemoryKind, SourceKind
class TestFetchWarmContextEmptyUserId:
@@ -52,3 +55,212 @@ class TestFetchWarmContextGeneralError:
result = await fetch_warm_context("abc", "hello")
assert result is None
+
+
+# ---------------------------------------------------------------------------
+# Bug: extract_episode_body() truncation breaks scope filtering
+# ---------------------------------------------------------------------------
+
+
+class TestFetchInternal:
+ """Test the internal _fetch function with mocked graphiti client."""
+
+ @pytest.mark.asyncio
+ async def test_returns_none_when_no_edges_or_episodes(self) -> None:
+ mock_client = AsyncMock()
+ mock_client.search.return_value = []
+ mock_client.retrieve_episodes.return_value = []
+
+ with (
+ patch.object(context, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ context,
+ "get_graphiti_client",
+ new_callable=AsyncMock,
+ return_value=mock_client,
+ ),
+ ):
+ result = await context._fetch("test-user", "hello")
+
+ assert result is None
+
+ @pytest.mark.asyncio
+ async def test_returns_context_with_edges(self) -> None:
+ edge = SimpleNamespace(
+ fact="user likes python",
+ name="preference",
+ valid_at="2025-01-01",
+ invalid_at=None,
+ )
+ mock_client = AsyncMock()
+ mock_client.search.return_value = [edge]
+ mock_client.retrieve_episodes.return_value = []
+
+ with (
+ patch.object(context, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ context,
+ "get_graphiti_client",
+ new_callable=AsyncMock,
+ return_value=mock_client,
+ ),
+ ):
+ result = await context._fetch("test-user", "hello")
+
+ assert result is not None
+ assert "<temporal_context>" in result
+ assert "user likes python" in result
+
+ @pytest.mark.asyncio
+ async def test_returns_context_with_episodes(self) -> None:
+ ep = SimpleNamespace(
+ content="talked about coffee",
+ created_at="2025-06-01T00:00:00Z",
+ )
+ mock_client = AsyncMock()
+ mock_client.search.return_value = []
+ mock_client.retrieve_episodes.return_value = [ep]
+
+ with (
+ patch.object(context, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ context,
+ "get_graphiti_client",
+ new_callable=AsyncMock,
+ return_value=mock_client,
+ ),
+ ):
+ result = await context._fetch("test-user", "hello")
+
+ assert result is not None
+ assert "talked about coffee" in result
+
+
+class TestFormatContextWithContent:
+ """Test _format_context with actual edges and episodes."""
+
+ def test_with_edges_only(self) -> None:
+ edge = SimpleNamespace(
+ fact="user likes coffee",
+ name="preference",
+ valid_at="2025-01-01",
+ invalid_at="present",
+ )
+ result = _format_context(edges=[edge], episodes=[])
+ assert result is not None
+ assert "<FACTS>" in result
+ assert "user likes coffee" in result
+ assert "<temporal_context>" in result
+
+ def test_with_episodes_only(self) -> None:
+ ep = SimpleNamespace(
+ content="plain conversation text",
+ created_at="2025-01-01T00:00:00Z",
+ )
+ result = _format_context(edges=[], episodes=[ep])
+ assert result is not None
+ assert "<RECENT_EPISODES>" in result
+ assert "plain conversation text" in result
+
+ def test_with_both_edges_and_episodes(self) -> None:
+ edge = SimpleNamespace(
+ fact="user likes coffee",
+ valid_at="2025-01-01",
+ invalid_at=None,
+ )
+ ep = SimpleNamespace(
+ content="talked about coffee",
+ created_at="2025-06-01T00:00:00Z",
+ )
+ result = _format_context(edges=[edge], episodes=[ep])
+ assert result is not None
+ assert "<FACTS>" in result
+ assert "<RECENT_EPISODES>" in result
+
+ def test_global_scope_episode_included(self) -> None:
+ envelope = MemoryEnvelope(content="global note", scope="real:global")
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ result = _format_context(edges=[], episodes=[ep])
+ assert result is not None
+ assert "<RECENT_EPISODES>" in result
+
+ def test_non_global_scope_episode_excluded(self) -> None:
+ envelope = MemoryEnvelope(content="project note", scope="project:crm")
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ result = _format_context(edges=[], episodes=[ep])
+ assert result is None
+
+
+class TestIsNonGlobalScopeEdgeCases:
+ """Verify _is_non_global_scope handles non-dict JSON without crashing."""
+
+ def test_list_json_treated_as_global(self) -> None:
+ assert _is_non_global_scope("[1, 2, 3]") is False
+
+ def test_string_json_treated_as_global(self) -> None:
+ assert _is_non_global_scope('"just a string"') is False
+
+ def test_null_json_treated_as_global(self) -> None:
+ assert _is_non_global_scope("null") is False
+
+ def test_plain_text_treated_as_global(self) -> None:
+ assert _is_non_global_scope("plain conversation text") is False
+
+
+class TestIsNonGlobalScopeTruncation:
+ """Verify _is_non_global_scope handles long MemoryEnvelope JSON.
+
+ extract_episode_body() truncates to 500 chars. A MemoryEnvelope with
+ a long content field serializes to >500 chars, so the truncated string
+ is invalid JSON. The except clause falls through to return False,
+ incorrectly treating a project-scoped episode as global.
+ """
+
+ def test_long_envelope_with_non_global_scope_detected(self) -> None:
+ """Long MemoryEnvelope JSON should be parsed with raw (untruncated) body."""
+ envelope = MemoryEnvelope(
+ content="x" * 600,
+ source_kind=SourceKind.user_asserted,
+ scope="project:crm",
+ memory_kind=MemoryKind.fact,
+ )
+ full_json = envelope.model_dump_json()
+ assert len(full_json) > 500, "precondition: JSON must exceed truncation limit"
+
+ # With the fix: _is_non_global_scope on the raw (untruncated) body
+ # correctly detects the non-global scope.
+ assert _is_non_global_scope(full_json) is True
+
+ # Truncated body still fails — that's expected; callers must use raw body.
+ ep = SimpleNamespace(content=full_json)
+ truncated = extract_episode_body(ep)
+ assert _is_non_global_scope(truncated) is False # truncated JSON → parse fails
+
+
+# ---------------------------------------------------------------------------
+# Bug: empty <temporal_context> wrapper when all episodes are non-global
+# ---------------------------------------------------------------------------
+
+
+class TestFormatContextEmptyWrapper:
+ """When all episodes are non-global and edges is empty, _format_context
+ should return None (no useful content) instead of an empty XML wrapper.
+ """
+
+ def test_returns_none_when_all_episodes_filtered(self) -> None:
+ envelope = MemoryEnvelope(
+ content="project-only note",
+ scope="project:crm",
+ )
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ result = _format_context(edges=[], episodes=[ep])
+ assert result is None
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/ingest.py b/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
index e36f521a35..58d086e55c 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/ingest.py
@@ -7,17 +7,45 @@ ingestion while keeping it fire-and-forget from the caller's perspective.
import asyncio
import logging
+import weakref
from datetime import datetime, timezone
from graphiti_core.nodes import EpisodeType
from .client import derive_group_id, get_graphiti_client
+from .memory_model import MemoryEnvelope, MemoryKind, MemoryStatus, SourceKind
logger = logging.getLogger(__name__)
-_user_queues: dict[str, asyncio.Queue] = {}
-_user_workers: dict[str, asyncio.Task] = {}
-_workers_lock = asyncio.Lock()
+
+# The CoPilot executor runs one asyncio loop per worker thread, and
+# asyncio.Queue / asyncio.Lock / asyncio.Task are all bound to the loop they
+# were first used on. A process-wide worker registry would hand a loop-1-bound
+# Queue to a coroutine running on loop 2 → RuntimeError "Future attached to a
+# different loop". Scope the registry per running loop so each loop has its
+# own queues, workers, and lock. Entries auto-clean when the loop is GC'd.
+class _LoopIngestState:
+ __slots__ = ("user_queues", "user_workers", "workers_lock")
+
+ def __init__(self) -> None:
+ self.user_queues: dict[str, asyncio.Queue] = {}
+ self.user_workers: dict[str, asyncio.Task] = {}
+ self.workers_lock = asyncio.Lock()
+
+
+_loop_state: (
+ "weakref.WeakKeyDictionary[asyncio.AbstractEventLoop, _LoopIngestState]"
+) = weakref.WeakKeyDictionary()
+
+
+def _get_loop_state() -> _LoopIngestState:
+ loop = asyncio.get_running_loop()
+ state = _loop_state.get(loop)
+ if state is None:
+ state = _LoopIngestState()
+ _loop_state[loop] = state
+ return state
+
# Idle workers are cleaned up after this many seconds of inactivity.
_WORKER_IDLE_TIMEOUT = 60
@@ -37,6 +65,10 @@ async def _ingestion_worker(user_id: str, queue: asyncio.Queue) -> None:
Exits after ``_WORKER_IDLE_TIMEOUT`` seconds of inactivity so that
idle workers don't leak memory indefinitely.
"""
+ # Snapshot the loop-local state at task start so cleanup always runs
+ # against the same state dict the worker was registered in, even if the
+ # worker is cancelled from another task.
+ state = _get_loop_state()
try:
while True:
try:
@@ -63,20 +95,25 @@ async def _ingestion_worker(user_id: str, queue: asyncio.Queue) -> None:
raise
finally:
# Clean up so the next message re-creates the worker.
- _user_queues.pop(user_id, None)
- _user_workers.pop(user_id, None)
+ state.user_queues.pop(user_id, None)
+ state.user_workers.pop(user_id, None)
async def enqueue_conversation_turn(
user_id: str,
session_id: str,
user_msg: str,
+ assistant_msg: str = "",
) -> None:
"""Enqueue a conversation turn for async background ingestion.
This returns almost immediately — the actual graphiti-core
``add_episode()`` call (which triggers LLM entity extraction)
runs in a background worker task.
+
+ If ``assistant_msg`` is provided and contains substantive findings
+ (not just acknowledgments), a separate derived-finding episode is
+ queued with ``source_kind=assistant_derived`` and ``status=tentative``.
"""
if not user_id:
return
@@ -117,6 +154,35 @@ async def enqueue_conversation_turn(
"Graphiti ingestion queue full for user %s — dropping episode",
user_id[:12],
)
+ return
+
+ # --- Derived-finding lane ---
+ # If the assistant response is substantive, distill it into a
+ # structured finding with tentative status.
+ if assistant_msg and _is_finding_worthy(assistant_msg):
+ finding = _distill_finding(assistant_msg)
+ if finding:
+ envelope = MemoryEnvelope(
+ content=finding,
+ source_kind=SourceKind.assistant_derived,
+ memory_kind=MemoryKind.finding,
+ status=MemoryStatus.tentative,
+ provenance=f"session:{session_id}",
+ )
+ try:
+ queue.put_nowait(
+ {
+ "name": f"finding_{session_id}",
+ "episode_body": envelope.model_dump_json(),
+ "source": EpisodeType.json,
+ "source_description": f"Assistant-derived finding in session {session_id}",
+ "reference_time": datetime.now(timezone.utc),
+ "group_id": group_id,
+ "custom_extraction_instructions": CUSTOM_EXTRACTION_INSTRUCTIONS,
+ }
+ )
+ except asyncio.QueueFull:
+ pass # user canonical episode already queued — finding is best-effort
async def enqueue_episode(
@@ -126,12 +192,18 @@ async def enqueue_episode(
name: str,
episode_body: str,
source_description: str = "Conversation memory",
+ is_json: bool = False,
) -> bool:
"""Enqueue an arbitrary episode for background ingestion.
Used by ``MemoryStoreTool`` so that explicit memory-store calls go
through the same per-user serialization queue as conversation turns.
+ Args:
+ is_json: When ``True``, ingest as ``EpisodeType.json`` (for
+ structured ``MemoryEnvelope`` payloads). Otherwise uses
+ ``EpisodeType.text``.
+
Returns ``True`` if the episode was queued, ``False`` if it was dropped.
"""
if not user_id:
@@ -145,12 +217,14 @@ async def enqueue_episode(
queue = await _ensure_worker(user_id)
+ source = EpisodeType.json if is_json else EpisodeType.text
+
try:
queue.put_nowait(
{
"name": name,
"episode_body": episode_body,
- "source": EpisodeType.text,
+ "source": source,
"source_description": source_description,
"reference_time": datetime.now(timezone.utc),
"group_id": group_id,
@@ -170,18 +244,19 @@ async def _ensure_worker(user_id: str) -> asyncio.Queue:
"""Create a queue and worker for *user_id* if one doesn't exist.
Returns the queue directly so callers don't need to look it up from
- ``_user_queues`` (which avoids a TOCTOU race if the worker times out
+ the state dict (which avoids a TOCTOU race if the worker times out
and cleans up between this call and the put_nowait).
"""
- async with _workers_lock:
- if user_id not in _user_queues:
+ state = _get_loop_state()
+ async with state.workers_lock:
+ if user_id not in state.user_queues:
q: asyncio.Queue = asyncio.Queue(maxsize=100)
- _user_queues[user_id] = q
- _user_workers[user_id] = asyncio.create_task(
+ state.user_queues[user_id] = q
+ state.user_workers[user_id] = asyncio.create_task(
_ingestion_worker(user_id, q),
name=f"graphiti-ingest-{user_id[:12]}",
)
- return _user_queues[user_id]
+ return state.user_queues[user_id]
async def _resolve_user_name(user_id: str) -> str:
@@ -195,3 +270,58 @@ async def _resolve_user_name(user_id: str) -> str:
except Exception:
logger.debug("Could not resolve user name for %s", user_id[:12])
return "User"
+
+
+# --- Derived-finding distillation ---
+
+# Phrases that indicate workflow chatter, not substantive findings.
+_CHATTER_PREFIXES = (
+ "done",
+ "got it",
+ "sure, i",
+ "sure!",
+ "ok",
+ "okay",
+ "i've created",
+ "i've updated",
+ "i've sent",
+ "i'll ",
+ "let me ",
+ "a sign-in button",
+ "please click",
+)
+
+# Minimum length for an assistant message to be considered finding-worthy.
+_MIN_FINDING_LENGTH = 150
+
+
+def _is_finding_worthy(assistant_msg: str) -> bool:
+ """Heuristic gate: is this assistant response worth distilling into a finding?
+
+ Skips short acknowledgments, workflow chatter, and UI prompts.
+ Only passes through responses that likely contain substantive
+ factual content (research results, analysis, conclusions).
+ """
+ if len(assistant_msg) < _MIN_FINDING_LENGTH:
+ return False
+
+ lower = assistant_msg.lower().strip()
+ for prefix in _CHATTER_PREFIXES:
+ if lower.startswith(prefix):
+ return False
+
+ return True
+
+
+def _distill_finding(assistant_msg: str) -> str | None:
+ """Extract the core finding from an assistant response.
+
+ For now, uses a simple truncation approach. Phase 3+ could use
+ a lightweight LLM call for proper distillation.
+ """
+ # Take the first 500 chars as the finding content.
+ # Strip markdown formatting artifacts.
+ content = assistant_msg.strip()
+ if len(content) > 500:
+ content = content[:500] + "..."
+ return content if content else None
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py b/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
index 3aebd283a5..6cb9c5fbaf 100644
--- a/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
+++ b/autogpt_platform/backend/backend/copilot/graphiti/ingest_test.py
@@ -8,21 +8,9 @@ import pytest
from . import ingest
-
-def _clean_module_state() -> None:
- """Reset module-level state to avoid cross-test contamination."""
- ingest._user_queues.clear()
- ingest._user_workers.clear()
-
-
[email protected](autouse=True)
-def _reset_state():
- _clean_module_state()
- yield
- # Cancel any lingering worker tasks.
- for task in ingest._user_workers.values():
- task.cancel()
- _clean_module_state()
+# Per-loop state in ingest.py auto-isolates between tests: pytest-asyncio
+# creates a fresh event loop per test function, and the WeakKeyDictionary
+# forgets the previous loop's state when it is GC'd. No manual reset needed.
class TestIngestionWorkerExceptionHandling:
@@ -75,7 +63,7 @@ class TestEnqueueConversationTurn:
user_msg="hi",
)
# No queue should have been created.
- assert len(ingest._user_queues) == 0
+ assert len(ingest._get_loop_state().user_queues) == 0
class TestQueueFullScenario:
@@ -106,7 +94,7 @@ class TestQueueFullScenario:
# Replace the queue with one that is already full.
tiny_q: asyncio.Queue = asyncio.Queue(maxsize=1)
tiny_q.put_nowait({"dummy": True})
- ingest._user_queues[user_id] = tiny_q
+ ingest._get_loop_state().user_queues[user_id] = tiny_q
# Should not raise even though the queue is full.
await ingest.enqueue_conversation_turn(
@@ -162,6 +150,149 @@ class TestResolveUserName:
assert name == "User"
+class TestEnqueueEpisode:
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_returns_true_on_success(self) -> None:
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ result = await ingest.enqueue_episode(
+ user_id="abc",
+ session_id="sess1",
+ name="test_ep",
+ episode_body="hello",
+ is_json=False,
+ )
+ assert result is True
+ assert not q.empty()
+
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_returns_false_for_empty_user(self) -> None:
+ result = await ingest.enqueue_episode(
+ user_id="",
+ session_id="sess1",
+ name="test_ep",
+ episode_body="hello",
+ )
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_returns_false_on_invalid_user(self) -> None:
+ with patch.object(ingest, "derive_group_id", side_effect=ValueError("bad id")):
+ result = await ingest.enqueue_episode(
+ user_id="bad",
+ session_id="sess1",
+ name="test_ep",
+ episode_body="hello",
+ )
+ assert result is False
+
+ @pytest.mark.asyncio
+ async def test_enqueue_episode_json_mode(self) -> None:
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ result = await ingest.enqueue_episode(
+ user_id="abc",
+ session_id="sess1",
+ name="test_ep",
+ episode_body='{"content": "hello"}',
+ is_json=True,
+ )
+ assert result is True
+ item = q.get_nowait()
+ from graphiti_core.nodes import EpisodeType
+
+ assert item["source"] == EpisodeType.json
+
+
+class TestDerivedFindingLane:
+ @pytest.mark.asyncio
+ async def test_finding_worthy_message_enqueues_two_episodes(self) -> None:
+ """A substantive assistant message should enqueue both the user
+ episode and a derived-finding episode."""
+ long_msg = "The analysis reveals significant growth patterns " + "x" * 200
+
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ patch(
+ "backend.copilot.graphiti.ingest._resolve_user_name",
+ new_callable=AsyncMock,
+ return_value="Alice",
+ ),
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ await ingest.enqueue_conversation_turn(
+ user_id="abc",
+ session_id="sess1",
+ user_msg="tell me about growth",
+ assistant_msg=long_msg,
+ )
+ # Should have 2 items: user episode + derived finding
+ assert q.qsize() == 2
+
+ @pytest.mark.asyncio
+ async def test_short_assistant_msg_skips_finding(self) -> None:
+ with (
+ patch.object(ingest, "derive_group_id", return_value="user_abc"),
+ patch.object(
+ ingest, "_ensure_worker", new_callable=AsyncMock
+ ) as mock_worker,
+ patch(
+ "backend.copilot.graphiti.ingest._resolve_user_name",
+ new_callable=AsyncMock,
+ return_value="Alice",
+ ),
+ ):
+ q: asyncio.Queue = asyncio.Queue(maxsize=100)
+ mock_worker.return_value = q
+
+ await ingest.enqueue_conversation_turn(
+ user_id="abc",
+ session_id="sess1",
+ user_msg="hi",
+ assistant_msg="ok",
+ )
+ # Only 1 item: the user episode (no finding for short msg)
+ assert q.qsize() == 1
+
+
+class TestDerivedFindingDistillation:
+ """_is_finding_worthy and _distill_finding gate derived-finding creation."""
+
+ def test_short_message_not_finding_worthy(self) -> None:
+ assert ingest._is_finding_worthy("ok") is False
+
+ def test_chatter_prefix_not_finding_worthy(self) -> None:
+ assert ingest._is_finding_worthy("done " + "x" * 200) is False
+
+ def test_long_substantive_message_is_finding_worthy(self) -> None:
+ msg = "The quarterly revenue analysis shows a 15% increase " + "x" * 200
+ assert ingest._is_finding_worthy(msg) is True
+
+ def test_distill_finding_truncates_to_500(self) -> None:
+ result = ingest._distill_finding("x" * 600)
+ assert result is not None
+ assert len(result) == 503 # 500 + "..."
+
+
class TestWorkerIdleTimeout:
@pytest.mark.asyncio
async def test_worker_cleans_up_on_idle(self) -> None:
@@ -169,9 +300,10 @@ class TestWorkerIdleTimeout:
queue: asyncio.Queue = asyncio.Queue(maxsize=10)
# Pre-populate state so cleanup can remove entries.
- ingest._user_queues[user_id] = queue
+ state = ingest._get_loop_state()
+ state.user_queues[user_id] = queue
task_sentinel = MagicMock()
- ingest._user_workers[user_id] = task_sentinel
+ state.user_workers[user_id] = task_sentinel
original_timeout = ingest._WORKER_IDLE_TIMEOUT
ingest._WORKER_IDLE_TIMEOUT = 0.05
@@ -181,5 +313,5 @@ class TestWorkerIdleTimeout:
ingest._WORKER_IDLE_TIMEOUT = original_timeout
# After idle timeout the worker should have cleaned up.
- assert user_id not in ingest._user_queues
- assert user_id not in ingest._user_workers
+ assert user_id not in state.user_queues
+ assert user_id not in state.user_workers
diff --git a/autogpt_platform/backend/backend/copilot/graphiti/memory_model.py b/autogpt_platform/backend/backend/copilot/graphiti/memory_model.py
new file mode 100644
index 0000000000..d8105cb731
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/graphiti/memory_model.py
@@ -0,0 +1,118 @@
+"""Generic memory metadata model for Graphiti episodes.
+
+Domain-agnostic envelope that works across business, fiction, research,
+personal life, and arbitrary knowledge domains. Designed so retrieval
+can distinguish user-asserted facts from assistant-derived findings
+and filter by scope.
+"""
+
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class SourceKind(str, Enum):
+ user_asserted = "user_asserted"
+ assistant_derived = "assistant_derived"
+ tool_observed = "tool_observed"
+
+
+class MemoryKind(str, Enum):
+ fact = "fact"
+ preference = "preference"
+ rule = "rule"
+ finding = "finding"
+ plan = "plan"
+ event = "event"
+ procedure = "procedure"
+
+
+class MemoryStatus(str, Enum):
+ active = "active"
+ tentative = "tentative"
+ superseded = "superseded"
+ contradicted = "contradicted"
+
+
+class RuleMemory(BaseModel):
+ """Structured representation of a standing instruction or rule.
+
+ Preserves the exact user intent rather than relying on LLM
+ extraction to reconstruct it from prose.
+ """
+
+ instruction: str = Field(
+ description="The actionable instruction (e.g. 'CC Sarah on client communications')"
+ )
+ actor: str | None = Field(
+ default=None, description="Who performs or is subject to the rule"
+ )
+ trigger: str | None = Field(
+ default=None,
+ description="When the rule applies (e.g. 'client-related communications')",
+ )
+ negation: str | None = Field(
+ default=None,
+ description="What NOT to do, if applicable (e.g. 'do not use SMTP')",
+ )
+
+
+class ProcedureStep(BaseModel):
+ """A single step in a multi-step procedure."""
+
+ order: int = Field(description="Step number (1-based)")
+ action: str = Field(description="What to do in this step")
+ tool: str | None = Field(default=None, description="Tool or service to use")
+ condition: str | None = Field(default=None, description="When/if this step applies")
+ negation: str | None = Field(
+ default=None, description="What NOT to do in this step"
+ )
+
+
+class ProcedureMemory(BaseModel):
+ """Structured representation of a multi-step workflow.
+
+ Steps with ordering, tools, conditions, and negations that don't
+ decompose cleanly into fact triples.
+ """
+
+ description: str = Field(description="What this procedure accomplishes")
+ steps: list[ProcedureStep] = Field(default_factory=list)
+
+
+class MemoryEnvelope(BaseModel):
+ """Structured wrapper for explicit memory storage.
+
+ Serialized as JSON and ingested via ``EpisodeType.json`` so that
+ Graphiti extracts entities from the ``content`` field while the
+ metadata fields survive as episode-level context.
+
+ For ``memory_kind=rule``, populate the ``rule`` field with a
+ ``RuleMemory`` to preserve the exact instruction. For
+ ``memory_kind=procedure``, populate ``procedure`` with a
+ ``ProcedureMemory`` for structured steps.
+ """
+
+ content: str = Field(
+ description="The memory content — the actual fact, rule, or finding"
+ )
+ source_kind: SourceKind = Field(default=SourceKind.user_asserted)
+ scope: str = Field(
+ default="real:global",
+ description="Namespace: 'real:global', 'project:<name>', 'book:<title>', 'session:<id>'",
+ )
+ memory_kind: MemoryKind = Field(default=MemoryKind.fact)
+ status: MemoryStatus = Field(default=MemoryStatus.active)
+ confidence: float | None = Field(default=None, ge=0.0, le=1.0)
+ provenance: str | None = Field(
+ default=None,
+ description="Origin reference — session_id, tool_call_id, or URL",
+ )
+ rule: RuleMemory | None = Field(
+ default=None,
+ description="Structured rule data — populate when memory_kind=rule",
+ )
+ procedure: ProcedureMemory | None = Field(
+ default=None,
+ description="Structured procedure data — populate when memory_kind=procedure",
+ )
diff --git a/autogpt_platform/backend/backend/copilot/permissions.py b/autogpt_platform/backend/backend/copilot/permissions.py
index cc01a124c4..a30ee282f7 100644
--- a/autogpt_platform/backend/backend/copilot/permissions.py
+++ b/autogpt_platform/backend/backend/copilot/permissions.py
@@ -89,6 +89,8 @@ ToolName = Literal[
"get_mcp_guide",
"list_folders",
"list_workspace_files",
+ "memory_forget_confirm",
+ "memory_forget_search",
"memory_search",
"memory_store",
"move_agents_to_folder",
diff --git a/autogpt_platform/backend/backend/copilot/sdk/service.py b/autogpt_platform/backend/backend/copilot/sdk/service.py
index d76f2ece80..19f151f008 100644
--- a/autogpt_platform/backend/backend/copilot/sdk/service.py
+++ b/autogpt_platform/backend/backend/copilot/sdk/service.py
@@ -2370,6 +2370,7 @@ async def stream_chat_completion_sdk(
turn_cache_creation_tokens = 0
turn_cost_usd: float | None = None
graphiti_enabled = False
+ pre_attempt_msg_count = 0
# Defaults ensure the finally block can always reference these safely even when
# an early return (e.g. sdk_cwd error) skips their normal assignment below.
sdk_model: str | None = None
@@ -2788,6 +2789,9 @@ async def stream_chat_completion_sdk(
if attachments.hint:
query_message = f"{query_message}\n\n{attachments.hint}"
+ # warm_ctx is injected via inject_user_context above (warm_ctx= kwarg).
+ # No separate injection needed here.
+
# When running without --resume and no prior transcript in storage,
# seed the transcript builder from compressed DB messages so that
# upload_transcript saves a compact version for future turns.
@@ -2937,6 +2941,8 @@ async def stream_chat_completion_sdk(
)
if attachments.hint:
state.query_message = f"{state.query_message}\n\n{attachments.hint}"
+ # warm_ctx is already baked into current_message via
+ # inject_user_context — no separate injection needed.
state.adapter = SDKResponseAdapter(
message_id=message_id, session_id=session_id
)
@@ -3341,8 +3347,21 @@ async def stream_chat_completion_sdk(
if graphiti_enabled and user_id and message and is_user_message:
from ..graphiti.ingest import enqueue_conversation_turn
+ # Extract last assistant message from THIS TURN only (not all
+ # session history) to avoid distilling stale content from prior
+ # turns when the current turn errors before producing output.
+ _this_turn_msgs = (
+ session.messages[pre_attempt_msg_count:] if session else []
+ )
+ _assistant_msgs = [
+ m.content or "" for m in _this_turn_msgs if m.role == "assistant"
+ ]
+ _last_assistant = _assistant_msgs[-1] if _assistant_msgs else ""
+
_ingest_task = asyncio.create_task(
- enqueue_conversation_turn(user_id, session_id, message)
+ enqueue_conversation_turn(
+ user_id, session_id, message, assistant_msg=_last_assistant
+ )
)
_background_tasks.add(_ingest_task)
_ingest_task.add_done_callback(_background_tasks.discard)
diff --git a/autogpt_platform/backend/backend/copilot/tools/__init__.py b/autogpt_platform/backend/backend/copilot/tools/__init__.py
index c4913a9411..75a0a8f4e4 100644
--- a/autogpt_platform/backend/backend/copilot/tools/__init__.py
+++ b/autogpt_platform/backend/backend/copilot/tools/__init__.py
@@ -26,6 +26,7 @@ from .fix_agent import FixAgentGraphTool
from .get_agent_building_guide import GetAgentBuildingGuideTool
from .get_doc_page import GetDocPageTool
from .get_mcp_guide import GetMCPGuideTool
+from .graphiti_forget import MemoryForgetConfirmTool, MemoryForgetSearchTool
from .graphiti_search import MemorySearchTool
from .graphiti_store import MemoryStoreTool
from .manage_folders import (
@@ -66,6 +67,8 @@ TOOL_REGISTRY: dict[str, BaseTool] = {
"find_block": FindBlockTool(),
"find_library_agent": FindLibraryAgentTool(),
# Graphiti memory tools
+ "memory_forget_confirm": MemoryForgetConfirmTool(),
+ "memory_forget_search": MemoryForgetSearchTool(),
"memory_search": MemorySearchTool(),
"memory_store": MemoryStoreTool(),
# Folder management tools
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py
new file mode 100644
index 0000000000..c3a30a583e
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget.py
@@ -0,0 +1,349 @@
+"""Two-step tool for targeted memory deletion.
+
+Step 1 (memory_forget_search): search for matching facts, return candidates.
+Step 2 (memory_forget_confirm): delete specific edges by UUID after user confirms.
+"""
+
+import logging
+from typing import Any
+
+from backend.copilot.graphiti._format import extract_fact, extract_temporal_validity
+from backend.copilot.graphiti.client import derive_group_id, get_graphiti_client
+from backend.copilot.graphiti.config import is_enabled_for_user
+from backend.copilot.model import ChatSession
+
+from .base import BaseTool
+from .models import (
+ ErrorResponse,
+ MemoryForgetCandidatesResponse,
+ MemoryForgetConfirmResponse,
+ ToolResponseBase,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class MemoryForgetSearchTool(BaseTool):
+ """Search for memories to forget — returns candidates for user confirmation."""
+
+ @property
+ def name(self) -> str:
+ return "memory_forget_search"
+
+ @property
+ def description(self) -> str:
+ return (
+ "Search for stored memories matching a description so the user can "
+ "choose which to delete. Returns candidate facts with UUIDs. "
+ "Use memory_forget_confirm with the UUIDs to actually delete them."
+ )
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "query": {
+ "type": "string",
+ "description": "Natural language description of what to forget (e.g. 'the Q2 marketing budget')",
+ },
+ },
+ "required": ["query"],
+ }
+
+ @property
+ def requires_auth(self) -> bool:
+ return True
+
+ async def _execute(
+ self,
+ user_id: str | None,
+ session: ChatSession,
+ *,
+ query: str = "",
+ **kwargs,
+ ) -> ToolResponseBase:
+ if not user_id:
+ return ErrorResponse(
+ message="Authentication required.",
+ session_id=session.session_id,
+ )
+
+ if not await is_enabled_for_user(user_id):
+ return ErrorResponse(
+ message="Memory features are not enabled for your account.",
+ session_id=session.session_id,
+ )
+
+ if not query:
+ return ErrorResponse(
+ message="A search query is required to find memories to forget.",
+ session_id=session.session_id,
+ )
+
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError:
+ return ErrorResponse(
+ message="Invalid user ID for memory operations.",
+ session_id=session.session_id,
+ )
+
+ try:
+ client = await get_graphiti_client(group_id)
+ edges = await client.search(
+ query=query,
+ group_ids=[group_id],
+ num_results=10,
+ )
+ except Exception:
+ logger.warning(
+ "Memory forget search failed for user %s", user_id[:12], exc_info=True
+ )
+ return ErrorResponse(
+ message="Memory search is temporarily unavailable.",
+ session_id=session.session_id,
+ )
+
+ if not edges:
+ return MemoryForgetCandidatesResponse(
+ message="No matching memories found.",
+ session_id=session.session_id,
+ candidates=[],
+ )
+
+ candidates = []
+ for e in edges:
+ edge_uuid = getattr(e, "uuid", None) or getattr(e, "id", None)
+ if not edge_uuid:
+ continue
+ fact = extract_fact(e)
+ valid_from, valid_to = extract_temporal_validity(e)
+ candidates.append(
+ {
+ "uuid": str(edge_uuid),
+ "fact": fact,
+ "valid_from": str(valid_from),
+ "valid_to": str(valid_to),
+ }
+ )
+
+ return MemoryForgetCandidatesResponse(
+ message=f"Found {len(candidates)} candidate(s). Show these to the user and ask which to delete, then call memory_forget_confirm with the UUIDs.",
+ session_id=session.session_id,
+ candidates=candidates,
+ )
+
+
+class MemoryForgetConfirmTool(BaseTool):
+ """Delete specific memory edges by UUID after user confirmation.
+
+ Supports both soft delete (temporal invalidation — reversible) and
+ hard delete (remove from graph — irreversible, for GDPR).
+ """
+
+ @property
+ def name(self) -> str:
+ return "memory_forget_confirm"
+
+ @property
+ def description(self) -> str:
+ return (
+ "Delete specific memories by UUID. Use after memory_forget_search "
+ "returns candidates and the user confirms which to delete. "
+ "Default is soft delete (marks as expired but keeps history). "
+ "Set hard_delete=true for permanent removal (GDPR)."
+ )
+
+ @property
+ def parameters(self) -> dict[str, Any]:
+ return {
+ "type": "object",
+ "properties": {
+ "uuids": {
+ "type": "array",
+ "items": {"type": "string"},
+ "description": "List of edge UUIDs to delete (from memory_forget_search results)",
+ },
+ "hard_delete": {
+ "type": "boolean",
+ "description": "If true, permanently removes edges from the graph (GDPR). Default false (soft delete — marks as expired).",
+ "default": False,
+ },
+ },
+ "required": ["uuids"],
+ }
+
+ @property
+ def requires_auth(self) -> bool:
+ return True
+
+ async def _execute(
+ self,
+ user_id: str | None,
+ session: ChatSession,
+ *,
+ uuids: list[str] | None = None,
+ hard_delete: bool = False,
+ **kwargs,
+ ) -> ToolResponseBase:
+ if not user_id:
+ return ErrorResponse(
+ message="Authentication required.",
+ session_id=session.session_id,
+ )
+
+ if not await is_enabled_for_user(user_id):
+ return ErrorResponse(
+ message="Memory features are not enabled for your account.",
+ session_id=session.session_id,
+ )
+
+ if not uuids:
+ return ErrorResponse(
+ message="At least one UUID is required. Use memory_forget_search first.",
+ session_id=session.session_id,
+ )
+
+ try:
+ group_id = derive_group_id(user_id)
+ except ValueError:
+ return ErrorResponse(
+ message="Invalid user ID for memory operations.",
+ session_id=session.session_id,
+ )
+
+ try:
+ client = await get_graphiti_client(group_id)
+ except Exception:
+ logger.warning(
+ "Failed to get Graphiti client for user %s", user_id[:12], exc_info=True
+ )
+ return ErrorResponse(
+ message="Memory service is temporarily unavailable.",
+ session_id=session.session_id,
+ )
+
+ driver = getattr(client, "graph_driver", None) or getattr(
+ client, "driver", None
+ )
+ if not driver:
+ return ErrorResponse(
+ message="Could not access graph driver for deletion.",
+ session_id=session.session_id,
+ )
+
+ if hard_delete:
+ deleted, failed = await _hard_delete_edges(driver, uuids, user_id)
+ mode = "permanently deleted"
+ else:
+ deleted, failed = await _soft_delete_edges(driver, uuids, user_id)
+ mode = "invalidated"
+
+ return MemoryForgetConfirmResponse(
+ message=(
+ f"{len(deleted)} memory edge(s) {mode}."
+ + (f" {len(failed)} failed." if failed else "")
+ ),
+ session_id=session.session_id,
+ deleted_uuids=deleted,
+ failed_uuids=failed,
+ )
+
+
+async def _soft_delete_edges(
+ driver, uuids: list[str], user_id: str
+) -> tuple[list[str], list[str]]:
+ """Temporal invalidation — mark edges as expired without removing them.
+
+ Sets ``invalid_at`` and ``expired_at`` to now, which excludes them
+ from default search results while preserving history.
+
+ Matches the same edge types as ``_hard_delete_edges`` so that edges of
+ any type (RELATES_TO, MENTIONS, HAS_MEMBER) can be soft-deleted.
+ """
+ deleted = []
+ failed = []
+ for uuid in uuids:
+ try:
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:MENTIONS|RELATES_TO|HAS_MEMBER {uuid: $uuid}]->()
+ SET e.invalid_at = datetime(),
+ e.expired_at = datetime()
+ RETURN e.uuid AS uuid
+ """,
+ uuid=uuid,
+ )
+ if records:
+ deleted.append(uuid)
+ else:
+ failed.append(uuid)
+ except Exception:
+ logger.warning(
+ "Failed to soft-delete edge %s for user %s",
+ uuid,
+ user_id[:12],
+ exc_info=True,
+ )
+ failed.append(uuid)
+ return deleted, failed
+
+
+async def _hard_delete_edges(
+ driver, uuids: list[str], user_id: str
+) -> tuple[list[str], list[str]]:
+ """Permanent removal — delete edges and clean up back-references.
+
+ Uses graphiti's ``Edge.delete()`` pattern (handles MENTIONS,
+ RELATES_TO, HAS_MEMBER in one query). Does NOT delete orphaned
+ entity nodes — they may have summaries, embeddings, or future
+ connections. Cleans up episode ``entity_edges`` back-references.
+ """
+ deleted = []
+ failed = []
+ for uuid in uuids:
+ try:
+ # Use WITH to capture the uuid before DELETE so we don't
+ # access properties of deleted relationships (FalkorDB #1393).
+ # Single atomic query avoids TOCTOU between check and delete.
+ records, _, _ = await driver.execute_query(
+ """
+ MATCH ()-[e:MENTIONS|RELATES_TO|HAS_MEMBER {uuid: $uuid}]->()
+ WITH e.uuid AS uuid, e
+ DELETE e
+ RETURN uuid
+ """,
+ uuid=uuid,
+ )
+ if not records:
+ failed.append(uuid)
+ continue
+ # Edge was deleted — report success regardless of cleanup outcome.
+ deleted.append(uuid)
+ # Clean up episode back-references (best-effort).
+ try:
+ await driver.execute_query(
+ """
+ MATCH (ep:Episodic)
+ WHERE $uuid IN ep.entity_edges
+ SET ep.entity_edges = [x IN ep.entity_edges WHERE x <> $uuid]
+ """,
+ uuid=uuid,
+ )
+ except Exception:
+ logger.warning(
+ "Edge %s deleted but back-ref cleanup failed for user %s",
+ uuid,
+ user_id[:12],
+ exc_info=True,
+ )
+ except Exception:
+ logger.warning(
+ "Failed to hard-delete edge %s for user %s",
+ uuid,
+ user_id[:12],
+ exc_info=True,
+ )
+ failed.append(uuid)
+ return deleted, failed
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py
new file mode 100644
index 0000000000..94bbeb5d4f
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_forget_test.py
@@ -0,0 +1,77 @@
+"""Tests for graphiti_forget delete helpers."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from backend.copilot.tools.graphiti_forget import _hard_delete_edges, _soft_delete_edges
+
+
+class TestSoftDeleteOverReportsSuccess:
+ """_soft_delete_edges always appends UUID to deleted list even when
+ the Cypher MATCH found no edge (query succeeds but matches nothing).
+ """
+
+ @pytest.mark.asyncio
+ async def test_reports_failure_when_no_edge_matched(self) -> None:
+ driver = AsyncMock()
+ # execute_query returns empty result set — no edge matched
+ driver.execute_query.return_value = ([], None, None)
+
+ deleted, failed = await _soft_delete_edges(
+ driver, ["nonexistent-uuid"], "test-user"
+ )
+ # Should NOT report success when nothing was actually updated
+ assert deleted == [], f"over-reported success: {deleted}"
+ assert failed == ["nonexistent-uuid"]
+
+
+class TestSoftDeleteNoMatchReportsFailure:
+ """When the query returns empty records (no edge with that UUID exists
+ in the database), _soft_delete_edges should report it as failed.
+ """
+
+ @pytest.mark.asyncio
+ async def test_soft_delete_handles_non_relates_to_edge(self) -> None:
+ driver = AsyncMock()
+ # Simulate: RELATES_TO match returns nothing (edge is MENTIONS type)
+ driver.execute_query.return_value = ([], None, None)
+
+ deleted, failed = await _soft_delete_edges(
+ driver, ["mentions-edge-uuid"], "test-user"
+ )
+ # With the bug, this reports success even though nothing was updated
+ assert "mentions-edge-uuid" not in deleted
+
+
+class TestHardDeleteBasicFlow:
+ """Verify _hard_delete_edges calls the right queries."""
+
+ @pytest.mark.asyncio
+ async def test_hard_delete_calls_both_queries(self) -> None:
+ driver = AsyncMock()
+ # First call (delete) returns a matched record, second (cleanup) returns empty
+ driver.execute_query.side_effect = [
+ ([{"uuid": "uuid-1"}], None, None),
+ ([], None, None),
+ ]
+
+ deleted, failed = await _hard_delete_edges(driver, ["uuid-1"], "test-user")
+ assert deleted == ["uuid-1"]
+ assert failed == []
+ # Should call: 1) delete edge, 2) clean episode back-refs
+ assert driver.execute_query.call_count == 2
+
+ @pytest.mark.asyncio
+ async def test_hard_delete_reports_failure_when_no_edge_matched(self) -> None:
+ driver = AsyncMock()
+ # Delete query returns no records — edge not found
+ driver.execute_query.return_value = ([], None, None)
+
+ deleted, failed = await _hard_delete_edges(
+ driver, ["nonexistent-uuid"], "test-user"
+ )
+ assert deleted == []
+ assert failed == ["nonexistent-uuid"]
+ # Only the delete query should run — cleanup skipped
+ assert driver.execute_query.call_count == 1
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_search.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_search.py
index 27f47a6b29..0aef554bbf 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_search.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_search.py
@@ -7,6 +7,7 @@ from typing import Any
from backend.copilot.graphiti._format import (
extract_episode_body,
+ extract_episode_body_raw,
extract_episode_timestamp,
extract_fact,
extract_temporal_validity,
@@ -52,6 +53,15 @@ class MemorySearchTool(BaseTool):
"description": "Maximum number of results to return",
"default": 15,
},
+ "scope": {
+ "type": "string",
+ "description": (
+ "Optional scope filter. When set, only memories matching "
+ "this scope are returned (hard filter). "
+ "Examples: 'real:global', 'project:crm', 'book:my-novel'. "
+ "Omit to search all scopes."
+ ),
+ },
},
"required": ["query"],
}
@@ -67,6 +77,7 @@ class MemorySearchTool(BaseTool):
*,
query: str = "",
limit: int = 15,
+ scope: str = "",
**kwargs,
) -> ToolResponseBase:
if not user_id:
@@ -122,7 +133,14 @@ class MemorySearchTool(BaseTool):
)
facts = _format_edges(edges)
- recent = _format_episodes(episodes)
+
+ # Scope hard-filter: if a scope was requested, filter episodes
+ # whose MemoryEnvelope JSON contains a different scope.
+ # Skip redundant _format_episodes() when scope is set.
+ if scope:
+ recent = _filter_episodes_by_scope(episodes, scope)
+ else:
+ recent = _format_episodes(episodes)
if not facts and not recent:
return MemorySearchResponse(
@@ -132,9 +150,10 @@ class MemorySearchTool(BaseTool):
recent_episodes=[],
)
+ scope_note = f" (scope filter: {scope})" if scope else ""
return MemorySearchResponse(
message=(
- f"Found {len(facts)} relationship facts and {len(recent)} stored memories. "
+ f"Found {len(facts)} relationship facts and {len(recent)} stored memories{scope_note}. "
"Use BOTH sections to answer — stored memories often contain operational "
"rules and instructions that relationship facts summarize."
),
@@ -160,3 +179,35 @@ def _format_episodes(episodes) -> list[str]:
body = extract_episode_body(ep)
results.append(f"[{ts}] {body}")
return results
+
+
+def _filter_episodes_by_scope(episodes, scope: str) -> list[str]:
+ """Filter episodes by scope — hard filter on MemoryEnvelope JSON content.
+
+ Episodes that are plain conversation text (not JSON envelopes) are
+ included by default since they have no scope metadata and belong
+ to the implicit ``real:global`` scope.
+
+ Uses ``extract_episode_body_raw`` (no truncation) for JSON parsing
+ so that long MemoryEnvelope payloads are parsed correctly.
+ """
+ import json
+
+ results = []
+ for ep in episodes:
+ raw_body = extract_episode_body_raw(ep)
+ try:
+ data = json.loads(raw_body)
+ if not isinstance(data, dict):
+ raise TypeError("non-dict JSON")
+ ep_scope = data.get("scope", "real:global")
+ if ep_scope != scope:
+ continue
+ except (json.JSONDecodeError, TypeError):
+ # Not JSON or non-dict JSON — plain conversation episode, treat as real:global
+ if scope != "real:global":
+ continue
+ display_body = extract_episode_body(ep)
+ ts = extract_episode_timestamp(ep)
+ results.append(f"[{ts}] {display_body}")
+ return results
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_search_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_search_test.py
new file mode 100644
index 0000000000..99e2de78ea
--- /dev/null
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_search_test.py
@@ -0,0 +1,64 @@
+"""Tests for graphiti_search helper functions."""
+
+from types import SimpleNamespace
+
+from backend.copilot.graphiti.memory_model import MemoryEnvelope, MemoryKind, SourceKind
+from backend.copilot.tools.graphiti_search import (
+ _filter_episodes_by_scope,
+ _format_episodes,
+)
+
+
+class TestFilterEpisodesByScopeTruncation:
+ """extract_episode_body() truncates to 500 chars. A MemoryEnvelope
+ with a long content field exceeds that limit, producing invalid JSON.
+ _filter_episodes_by_scope then treats it as a plain-text episode
+ (real:global), leaking project-scoped data into global results.
+ """
+
+ def test_long_envelope_filtered_by_scope(self) -> None:
+ envelope = MemoryEnvelope(
+ content="x" * 600,
+ source_kind=SourceKind.user_asserted,
+ scope="project:crm",
+ memory_kind=MemoryKind.fact,
+ )
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ # Requesting real:global scope — this project:crm episode should be excluded
+ results = _filter_episodes_by_scope([ep], "real:global")
+ assert (
+ results == []
+ ), f"project-scoped episode leaked into global results: {results}"
+
+ def test_short_envelope_filtered_correctly(self) -> None:
+ """Short envelopes (under 500 chars) are parsed correctly."""
+ envelope = MemoryEnvelope(
+ content="short note",
+ scope="project:crm",
+ )
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ results = _filter_episodes_by_scope([ep], "real:global")
+ assert results == []
+
+
+class TestRedundantFormatting:
+ """_format_episodes is called even when scope filter will overwrite it.
+ Not a correctness bug, but verify the scope path doesn't depend on it.
+ """
+
+ def test_scope_filter_independent_of_format_episodes(self) -> None:
+ envelope = MemoryEnvelope(content="note", scope="real:global")
+ ep = SimpleNamespace(
+ content=envelope.model_dump_json(),
+ created_at="2025-01-01T00:00:00Z",
+ )
+ from_format = _format_episodes([ep])
+ from_scope = _filter_episodes_by_scope([ep], "real:global")
+ assert len(from_format) == 1
+ assert len(from_scope) == 1
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
index 6e75eb2ed4..3112820e54 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_store.py
@@ -5,6 +5,15 @@ from typing import Any
from backend.copilot.graphiti.config import is_enabled_for_user
from backend.copilot.graphiti.ingest import enqueue_episode
+from backend.copilot.graphiti.memory_model import (
+ MemoryEnvelope,
+ MemoryKind,
+ MemoryStatus,
+ ProcedureMemory,
+ ProcedureStep,
+ RuleMemory,
+ SourceKind,
+)
from backend.copilot.model import ChatSession
from .base import BaseTool
@@ -26,7 +35,7 @@ class MemoryStoreTool(BaseTool):
"Store a memory or fact about the user for future recall. "
"Use when the user shares preferences, business context, decisions, "
"relationships, or other important information worth remembering "
- "across sessions."
+ "across sessions. Supports optional metadata for scoping and classification."
)
@property
@@ -47,6 +56,94 @@ class MemoryStoreTool(BaseTool):
"description": "Context about where this info came from",
"default": "Conversation memory",
},
+ "source_kind": {
+ "type": "string",
+ "enum": [e.value for e in SourceKind],
+ "description": "Who asserted this: user_asserted (default), assistant_derived, or tool_observed",
+ "default": "user_asserted",
+ },
+ "scope": {
+ "type": "string",
+ "description": "Namespace for this memory: 'real:global' (default), 'project:<name>', 'book:<title>'",
+ "default": "real:global",
+ },
+ "memory_kind": {
+ "type": "string",
+ "enum": [e.value for e in MemoryKind],
+ "description": "Type of memory: fact (default), preference, rule, finding, plan, event, procedure",
+ "default": "fact",
+ },
+ "rule": {
+ "type": "object",
+ "description": (
+ "Structured rule data — use when memory_kind=rule to preserve "
+ "exact operational instructions. Example: "
+ '{"instruction": "CC Sarah on client communications", '
+ '"actor": "Sarah", "trigger": "client-related communications"}'
+ ),
+ "properties": {
+ "instruction": {
+ "type": "string",
+ "description": "The actionable instruction",
+ },
+ "actor": {
+ "type": "string",
+ "description": "Who performs or is subject to the rule",
+ },
+ "trigger": {
+ "type": "string",
+ "description": "When the rule applies",
+ },
+ "negation": {
+ "type": "string",
+ "description": "What NOT to do, if applicable",
+ },
+ },
+ "required": ["instruction"],
+ },
+ "procedure": {
+ "type": "object",
+ "description": (
+ "Structured procedure data — use when memory_kind=procedure "
+ "for multi-step workflows with ordering, tools, and conditions."
+ ),
+ "properties": {
+ "description": {
+ "type": "string",
+ "description": "What this procedure accomplishes",
+ },
+ "steps": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "properties": {
+ "order": {
+ "type": "integer",
+ "description": "Step number",
+ },
+ "action": {
+ "type": "string",
+ "description": "What to do",
+ },
+ "tool": {
+ "type": "string",
+ "description": "Tool or service to use",
+ },
+ "condition": {
+ "type": "string",
+ "description": "When this step applies",
+ },
+ "negation": {
+ "type": "string",
+ "description": "What NOT to do",
+ },
+ },
+ "required": ["order", "action"],
+ },
+ },
+ },
+ "required": ["description", "steps"],
+ },
},
"required": ["name", "content"],
}
@@ -63,6 +160,11 @@ class MemoryStoreTool(BaseTool):
name: str = "",
content: str = "",
source_description: str = "Conversation memory",
+ source_kind: str = "user_asserted",
+ scope: str = "real:global",
+ memory_kind: str = "fact",
+ rule: dict | None = None,
+ procedure: dict | None = None,
**kwargs,
) -> ToolResponseBase:
if not user_id:
@@ -83,12 +185,53 @@ class MemoryStoreTool(BaseTool):
session_id=session.session_id,
)
+ rule_model = None
+ if rule and memory_kind == "rule":
+ try:
+ rule_model = RuleMemory(**rule)
+ except Exception:
+ logger.warning("Invalid rule data, storing as plain fact")
+ memory_kind = "fact"
+
+ procedure_model = None
+ if procedure and memory_kind == "procedure":
+ try:
+ steps = [ProcedureStep(**s) for s in procedure.get("steps", [])]
+ procedure_model = ProcedureMemory(
+ description=procedure.get("description", content),
+ steps=steps,
+ )
+ except Exception:
+ logger.warning("Invalid procedure data, storing as plain fact")
+ memory_kind = "fact"
+
+ try:
+ resolved_source = SourceKind(source_kind)
+ except ValueError:
+ resolved_source = SourceKind.user_asserted
+ try:
+ resolved_kind = MemoryKind(memory_kind)
+ except ValueError:
+ resolved_kind = MemoryKind.fact
+
+ envelope = MemoryEnvelope(
+ content=content,
+ source_kind=resolved_source,
+ scope=scope,
+ memory_kind=resolved_kind,
+ status=MemoryStatus.active,
+ provenance=session.session_id,
+ rule=rule_model,
+ procedure=procedure_model,
+ )
+
queued = await enqueue_episode(
user_id,
session.session_id,
name=name,
- episode_body=content,
+ episode_body=envelope.model_dump_json(),
source_description=source_description,
+ is_json=True,
)
if not queued:
diff --git a/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py b/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
index 3742355d76..21224d39c0 100644
--- a/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
+++ b/autogpt_platform/backend/backend/copilot/tools/graphiti_store_test.py
@@ -1,5 +1,6 @@
"""Tests for MemoryStoreTool."""
+import json
from datetime import UTC, datetime
from unittest.mock import AsyncMock, patch
@@ -153,13 +154,14 @@ class TestMemoryStoreTool:
assert "queued for storage" in result.message
assert result.session_id == "test-session"
- mock_enqueue.assert_awaited_once_with(
- "user-1",
- "test-session",
- name="user_prefers_python",
- episode_body="The user prefers Python over JavaScript.",
- source_description="Direct statement",
- )
+ mock_enqueue.assert_awaited_once()
+ call_kwargs = mock_enqueue.await_args.kwargs
+ assert call_kwargs["name"] == "user_prefers_python"
+ assert call_kwargs["source_description"] == "Direct statement"
+ assert call_kwargs["is_json"] is True
+ envelope = json.loads(call_kwargs["episode_body"])
+ assert envelope["content"] == "The user prefers Python over JavaScript."
+ assert envelope["memory_kind"] == "fact"
@pytest.mark.asyncio
async def test_store_success_uses_default_source_description(self):
@@ -187,10 +189,132 @@ class TestMemoryStoreTool:
)
assert isinstance(result, MemoryStoreResponse)
- mock_enqueue.assert_awaited_once_with(
- "user-1",
- "test-session",
- name="some_fact",
- episode_body="A fact worth remembering.",
- source_description="Conversation memory",
- )
+ mock_enqueue.assert_awaited_once()
+ call_kwargs = mock_enqueue.await_args.kwargs
+ assert call_kwargs["name"] == "some_fact"
+ assert call_kwargs["source_description"] == "Conversation memory"
+ assert call_kwargs["is_json"] is True
+ envelope = json.loads(call_kwargs["episode_body"])
+ assert envelope["content"] == "A fact worth remembering."
+
+ @pytest.mark.asyncio
+ async def test_store_invalid_source_kind_falls_back(self):
+ """Invalid enum values should fall back to defaults, not crash."""
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ mock_enqueue = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ mock_enqueue,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="some_fact",
+ content="A fact.",
+ source_kind="INVALID_SOURCE",
+ memory_kind="INVALID_KIND",
+ )
+
+ assert isinstance(result, MemoryStoreResponse)
+ envelope = json.loads(mock_enqueue.await_args.kwargs["episode_body"])
+ assert envelope["source_kind"] == "user_asserted"
+ assert envelope["memory_kind"] == "fact"
+
+ @pytest.mark.asyncio
+ async def test_store_valid_enum_values_preserved(self):
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ mock_enqueue = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ mock_enqueue,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="rule_1",
+ content="Always CC Sarah.",
+ source_kind="user_asserted",
+ memory_kind="rule",
+ )
+
+ assert isinstance(result, MemoryStoreResponse)
+ envelope = json.loads(mock_enqueue.await_args.kwargs["episode_body"])
+ assert envelope["source_kind"] == "user_asserted"
+ assert envelope["memory_kind"] == "rule"
+
+ @pytest.mark.asyncio
+ async def test_store_queue_full_returns_error(self):
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ new_callable=AsyncMock,
+ return_value=False,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="pref",
+ content="likes python",
+ )
+
+ assert isinstance(result, ErrorResponse)
+ assert "queue" in result.message.lower()
+
+ @pytest.mark.asyncio
+ async def test_store_with_scope(self):
+ tool = MemoryStoreTool()
+ session = _make_session()
+
+ mock_enqueue = AsyncMock()
+
+ with (
+ patch(
+ "backend.copilot.tools.graphiti_store.is_enabled_for_user",
+ new_callable=AsyncMock,
+ return_value=True,
+ ),
+ patch(
+ "backend.copilot.tools.graphiti_store.enqueue_episode",
+ mock_enqueue,
+ ),
+ ):
+ result = await tool._execute(
+ user_id="user-1",
+ session=session,
+ name="project_note",
+ content="CRM uses PostgreSQL.",
+ scope="project:crm",
+ )
+
+ assert isinstance(result, MemoryStoreResponse)
+ envelope = json.loads(mock_enqueue.await_args.kwargs["episode_body"])
+ assert envelope["scope"] == "project:crm"
diff --git a/autogpt_platform/backend/backend/copilot/tools/models.py b/autogpt_platform/backend/backend/copilot/tools/models.py
index bf211e2da7..90aa3d51db 100644
--- a/autogpt_platform/backend/backend/copilot/tools/models.py
+++ b/autogpt_platform/backend/backend/copilot/tools/models.py
@@ -84,6 +84,8 @@ class ResponseType(str, Enum):
# Graphiti memory
MEMORY_STORE = "memory_store"
MEMORY_SEARCH = "memory_search"
+ MEMORY_FORGET_CANDIDATES = "memory_forget_candidates"
+ MEMORY_FORGET_CONFIRM = "memory_forget_confirm"
# Base response model
@@ -712,3 +714,18 @@ class MemorySearchResponse(ToolResponseBase):
type: ResponseType = ResponseType.MEMORY_SEARCH
facts: list[str] = Field(default_factory=list)
recent_episodes: list[str] = Field(default_factory=list)
+
+
+class MemoryForgetCandidatesResponse(ToolResponseBase):
+ """Response with candidate memories to forget."""
+
+ type: ResponseType = ResponseType.MEMORY_FORGET_CANDIDATES
+ candidates: list[dict[str, str]] = Field(default_factory=list)
+
+
+class MemoryForgetConfirmResponse(ToolResponseBase):
+ """Response after deleting specific memory edges."""
+
+ type: ResponseType = ResponseType.MEMORY_FORGET_CONFIRM
+ deleted_uuids: list[str] = Field(default_factory=list)
+ failed_uuids: list[str] = Field(default_factory=list)
diff --git a/autogpt_platform/backend/backend/util/architecture_test.py b/autogpt_platform/backend/backend/util/architecture_test.py
new file mode 100644
index 0000000000..b3cf457911
--- /dev/null
+++ b/autogpt_platform/backend/backend/util/architecture_test.py
@@ -0,0 +1,134 @@
+"""
+Architectural tests for the backend package.
+
+Each rule here exists to prevent a *class* of bug, not to police style.
+When adding a rule, document the incident or failure mode that motivated
+it so future maintainers know whether the rule still earns its keep.
+"""
+
+import ast
+import pathlib
+
+BACKEND_ROOT = pathlib.Path(__file__).resolve().parents[1]
+
+
+# ---------------------------------------------------------------------------
+# Rule: no process-wide @cached(...) around event-loop-bound async clients
+# ---------------------------------------------------------------------------
+#
+# Motivation: `backend.util.cache.cached` stores its result in a process-wide
+# dict for ttl_seconds. Async clients (AsyncOpenAI, httpx.AsyncClient,
+# AsyncRabbitMQ, supabase AClient, ...) wrap connection pools whose internal
+# asyncio primitives lazily bind to the first event loop that uses them. The
+# executor runs two long-lived loops on separate threads; once the cache is
+# populated from loop A, any subsequent call from loop B raises
+# `RuntimeError: ... bound to a different event loop`, surfaced as an opaque
+# `APIConnectionError: Connection error.` and poisons the cache for a full
+# TTL window.
+#
+# Use `per_loop_cached` (keyed on id(running loop)) or construct per-call.
+
+LOOP_BOUND_TYPES = frozenset(
+ {
+ "AsyncOpenAI",
+ "LangfuseAsyncOpenAI",
+ "AsyncClient", # httpx, openai internal
+ "AsyncRabbitMQ",
+ "AClient", # supabase async
+ "AsyncRedisExecutionEventBus",
+ }
+)
+
+# Pre-existing offenders tracked for future cleanup. Exclude from this test
+# so the rule can still catch NEW violations without blocking unrelated PRs.
+_KNOWN_OFFENDERS = frozenset(
+ {
+ "util/clients.py get_async_supabase",
+ "util/clients.py get_openai_client",
+ }
+)
+
+
+def _decorator_name(node: ast.expr) -> str | None:
+ if isinstance(node, ast.Call):
+ return _decorator_name(node.func)
+ if isinstance(node, ast.Name):
+ return node.id
+ if isinstance(node, ast.Attribute):
+ return node.attr
+ return None
+
+
+def _annotation_names(annotation: ast.expr | None) -> set[str]:
+ if annotation is None:
+ return set()
+ if isinstance(annotation, ast.Constant) and isinstance(annotation.value, str):
+ try:
+ parsed = ast.parse(annotation.value, mode="eval").body
+ except SyntaxError:
+ return set()
+ return _annotation_names(parsed)
+ names: set[str] = set()
+ for child in ast.walk(annotation):
+ if isinstance(child, ast.Name):
+ names.add(child.id)
+ elif isinstance(child, ast.Attribute):
+ names.add(child.attr)
+ return names
+
+
+def _iter_backend_py_files():
+ for path in BACKEND_ROOT.rglob("*.py"):
+ if "__pycache__" in path.parts:
+ continue
+ yield path
+
+
+def test_known_offenders_use_posix_separators():
+ """_KNOWN_OFFENDERS must use forward slashes since the comparison key
+ is built from pathlib.Path.relative_to() which uses OS-native separators.
+ On Windows this would be backslashes, causing false positives.
+
+ Ensure the key construction normalises to forward slashes.
+ """
+ for entry in _KNOWN_OFFENDERS:
+ path_part = entry.split()[0]
+ assert "\\" not in path_part, (
+ f"_KNOWN_OFFENDERS entry uses backslash: {entry!r}. "
+ "Use forward slashes — the test should normalise Path separators."
+ )
+
+
+def test_no_process_cached_loop_bound_clients():
+ offenders: list[str] = []
+ for py in _iter_backend_py_files():
+ try:
+ tree = ast.parse(py.read_text(encoding="utf-8"), filename=str(py))
+ except SyntaxError:
+ continue
+ for node in ast.walk(tree):
+ if not isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+ continue
+ decorators = {_decorator_name(d) for d in node.decorator_list}
+ if "cached" not in decorators:
+ continue
+ bound = _annotation_names(node.returns) & LOOP_BOUND_TYPES
+ if bound:
+ rel = py.relative_to(BACKEND_ROOT)
+ key = f"{rel.as_posix()} {node.name}"
+ if key in _KNOWN_OFFENDERS:
+ continue
+ offenders.append(
+ f"{rel}:{node.lineno} {node.name}() -> {sorted(bound)}"
+ )
+
+ assert not offenders, (
+ "Process-wide @cached(...) must not wrap functions returning event-"
+ "loop-bound async clients. These objects lazily bind their connection "
+ "pool to the first event loop that uses them; caching them across "
+ "loops poisons the cache and surfaces as opaque connection errors.\n\n"
+ "Offenders:\n " + "\n ".join(offenders) + "\n\n"
+ "Fix: construct the client per-call, or introduce a per-loop factory "
+ "keyed on id(asyncio.get_running_loop()). See "
+ "backend/util/clients.py::get_openai_client for context."
+ )
diff --git a/autogpt_platform/frontend/src/app/api/openapi.json b/autogpt_platform/frontend/src/app/api/openapi.json
index e5ad3bf296..ef775cf92b 100644
--- a/autogpt_platform/frontend/src/app/api/openapi.json
+++ b/autogpt_platform/frontend/src/app/api/openapi.json
@@ -1346,7 +1346,15 @@
{
"$ref": "#/components/schemas/MCPToolsDiscoveredResponse"
},
- { "$ref": "#/components/schemas/MCPToolOutputResponse" }
+ { "$ref": "#/components/schemas/MCPToolOutputResponse" },
+ { "$ref": "#/components/schemas/MemoryStoreResponse" },
+ { "$ref": "#/components/schemas/MemorySearchResponse" },
+ {
+ "$ref": "#/components/schemas/MemoryForgetCandidatesResponse"
+ },
+ {
+ "$ref": "#/components/schemas/MemoryForgetConfirmResponse"
+ }
],
"title": "Response Getv2[Dummy] Tool Response Type Export For Codegen"
}
@@ -11525,6 +11533,103 @@
"title": "MarketplaceListingCreator",
"description": "Creator information for a marketplace listing."
},
+ "MemoryForgetCandidatesResponse": {
+ "properties": {
+ "type": {
+ "$ref": "#/components/schemas/ResponseType",
+ "default": "memory_forget_candidates"
+ },
+ "message": { "type": "string", "title": "Message" },
+ "session_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Session Id"
+ },
+ "candidates": {
+ "items": {
+ "additionalProperties": { "type": "string" },
+ "type": "object"
+ },
+ "type": "array",
+ "title": "Candidates"
+ }
+ },
+ "type": "object",
+ "required": ["message"],
+ "title": "MemoryForgetCandidatesResponse",
+ "description": "Response with candidate memories to forget."
+ },
+ "MemoryForgetConfirmResponse": {
+ "properties": {
+ "type": {
+ "$ref": "#/components/schemas/ResponseType",
+ "default": "memory_forget_confirm"
+ },
+ "message": { "type": "string", "title": "Message" },
+ "session_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Session Id"
+ },
+ "deleted_uuids": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Deleted Uuids"
+ },
+ "failed_uuids": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Failed Uuids"
+ }
+ },
+ "type": "object",
+ "required": ["message"],
+ "title": "MemoryForgetConfirmResponse",
+ "description": "Response after deleting specific memory edges."
+ },
+ "MemorySearchResponse": {
+ "properties": {
+ "type": {
+ "$ref": "#/components/schemas/ResponseType",
+ "default": "memory_search"
+ },
+ "message": { "type": "string", "title": "Message" },
+ "session_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Session Id"
+ },
+ "facts": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Facts"
+ },
+ "recent_episodes": {
+ "items": { "type": "string" },
+ "type": "array",
+ "title": "Recent Episodes"
+ }
+ },
+ "type": "object",
+ "required": ["message"],
+ "title": "MemorySearchResponse",
+ "description": "Response when memories are searched."
+ },
+ "MemoryStoreResponse": {
+ "properties": {
+ "type": {
+ "$ref": "#/components/schemas/ResponseType",
+ "default": "memory_store"
+ },
+ "message": { "type": "string", "title": "Message" },
+ "session_id": {
+ "anyOf": [{ "type": "string" }, { "type": "null" }],
+ "title": "Session Id"
+ },
+ "memory_name": { "type": "string", "title": "Memory Name" }
+ },
+ "type": "object",
+ "required": ["message", "memory_name"],
+ "title": "MemoryStoreResponse",
+ "description": "Response when a memory is stored."
+ },
"Message": {
"properties": {
"query": { "type": "string", "title": "Query" },
@@ -12921,7 +13026,9 @@
"feature_request_search",
"feature_request_created",
"memory_store",
- "memory_search"
+ "memory_search",
+ "memory_forget_candidates",
+ "memory_forget_confirm"
],
"title": "ResponseType",
"description": "Types of tool responses."