DEV Community: Mohammed Rafay

Fix "ModuleNotFoundError: No module named 'agno.memory.v2'" (Agno v1 v2+ memory migration)

Mohammed Rafay — Sun, 25 Oct 2026 16:40:14 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this with AI assistance and checked it against Agno's official migration guide and a real install. Code status: on Oct 25, 2026 I installed agno 3.1.10 (Python 3.13) and reproduced the errors below. I then ran the "after" imports, the Agent construction and get_user_memories successfully. No model was called (no key), so memory creation itself was not run.

The error

You upgrade Agno and memory code that used to work fails on import:

ModuleNotFoundError: No module named 'agno.memory.v2'

or, in VS Code / Pylance:

Import "agno.memory.v2.memory" could not be resolved

often with a companion:

ModuleNotFoundError: No module named 'agno.storage'

This was reported in agno-agi/agno#5017 (Agno 2.1.4, Python 3.11). The maintainers' answer was to follow the memory section of the v2 migration guide. I reproduced all three errors on Agno 3.1.10:

$ python -c "from agno.memory.v2.memory import Memory"
ModuleNotFoundError: No module named 'agno.memory.v2'
$ python -c "from agno.storage.sqlite import SqliteStorage"
ModuleNotFoundError: No module named 'agno.storage'

Why it happens

Agno v2 removed the v1 memory and storage modules rather than aliasing them. Per the v2 migration guide:

Storage classes moved from agno/storage to agno/db and are now called Db classes. One instance serves agents, teams and workflows, and the mode and table_name parameters are gone.
The MemoryDb classes are deprecated in favour of the main Db classes.
The Memory class is deprecated. You set update_memory_on_run=True on an Agent that has a db.

The fix: before and after

v1 (breaks):

from agno.agent import Agent
from agno.memory.v2.db.sqlite import SqliteMemoryDb
from agno.memory.v2.memory import Memory
from agno.storage.sqlite import SqliteStorage

memory = Memory(db=SqliteMemoryDb(table_name="user_memories", db_file="agno.db"))
storage = SqliteStorage(table_name="agent_sessions", db_file="agno.db")
agent = Agent(memory=memory, storage=storage, enable_user_memories=True)

v2+ (ran on 3.1.10):

from agno.agent import Agent
from agno.db.sqlite import SqliteDb

db = SqliteDb(db_file="agno.db")          # sessions AND memories
agent = Agent(db=db, update_memory_on_run=True)

print(agent.get_user_memories(user_id="john@example.com"))  # [] until a run stores something

Things to check after the swap:

Pass user_id on every run. Memories are stored per user, so a missing or changing user_id looks like "memory isn't stored".
Table names. If you need your old table names, SqliteDb takes session_table= and memory_table= instead of table_name=.
Custom memory model or instructions. Build a MemoryManager (from agno.memory import MemoryManager) and pass memory_manager= to the Agent. The parameter names I found on the current Agent are memory_manager, enable_agentic_memory, update_memory_on_run and add_memories_to_context.
Existing v1 data. The migration guide links a v1-to-v2 migration script. It says to use the script from the v2 release matching your environment and not to run it under Agno v3, so migrate to v2 first, verify, then upgrade. Back up your database before running anything against it.
TypeError: UserMemory.__init__() got an unexpected keyword argument 'summaries'. This is a different, older error from mixed v1 memory data (#2955, Agno 1.4.1). The reporter confirmed it was gone after the maintainers' follow-up, so upgrade first.

If you get ImportError: The SQLAlchemy asyncio module requires that the Python 'greenlet' library is installed when importing agno.db.sqlite, run pip install greenlet. I hit this on a clean Python 3.13 venv.

If you want memories outside the local database

update_memory_on_run writes to whatever Db you pass. If you want sessions to stay local but user memories to live in a hosted store shared across instances, MemorySync's agno-memorysync package backs Agno's MemoryManager (guide). The guide says it needs agno 2.8+, and this constructed fine on 3.1.10:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.memory import MemoryManager
from agno_memorysync import MemorySyncDb   # pip install agno-memorysync; needs MEMORYSYNC_API_KEY

agent = Agent(
    db=SqliteDb(db_file="agent.db"),                  # sessions: local
    memory_manager=MemoryManager(db=MemorySyncDb()),  # memories: hosted
    update_memory_on_run=True,
    user_id="customer-42",
)

The guide notes that MemorySyncDb is memory-only on purpose. Pointing sessions at it raises MemorySyncMemoryOnlyError, so keep db= local.

Common questions

Is there a compatibility shim for agno.memory.v2? Not in 3.1.10. The import fails. Update the imports.

Do I still need a separate storage object? No. One Db instance handles sessions, memories, metrics, evals and knowledge in separate tables.

My memories are stored but never show up in replies. If you pass a verbatim system_message=, it replaces Agno's built system prompt, which is where memories are injected. Use instructions= instead. (This tip is from MemorySync's Agno guide and applies to any memory db.)

Which Agno version is current? PyPI served 3.1.10 on Oct 25, 2026. The v2 migration steps above still applied to it.

To see a stored fact survive a reload before wiring anything in: try MemorySync in your browser. No signup is needed.

Sources

agno-agi/agno#5017 (the import error): https://github.com/agno-agi/agno/issues/5017
agno-agi/agno#2955 (summaries TypeError): https://github.com/agno-agi/agno/issues/2955
Agno v2 migration guide: https://docs.agno.com/other/v2-migration
Agno, Agent with Memory: https://docs.agno.com/memory/agent/agent-with-memory
MemorySync Agno guide: https://docs.memorysync.io/guides/agno

Strands Agents memory: how to add long-term memory to a Strands agent (MemoryManager, stores and per-user recall)

Mohammed Rafay — Sun, 25 Oct 2026 16:39:11 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this with AI assistance and checked it against the Strands Agents docs and MemorySync's Strands guide. Code status: on Oct 25, 2026 I installed strands-agents 1.62.0 and strands-memorysync 1.1.0 on Python 3.13 and ran every import and constructor below (agent, MemoryManager, TestMemoryStore, MemorySyncStore with InvocationTrigger, get_tools()). I also ran one agent(...) turn end to end with a scripted stand-in model and MemorySync's HTTP responses mocked locally, to see what the store sends and what reaches the model. No live LLM or live MemorySync API call was made.

By default a Strands agent starts each conversation from zero. Strands Agents memory is one of three kinds of state the Strands docs separate (memory overview):

Session management persists the full conversation so you can resume it.
Conversation management keeps a session inside the context window.
Memory carries durable knowledge across sessions without replaying old conversations.

If your agent "forgets the user" between sessions, you need the third one.

How Strands memory works

You attach a MemoryManager with one or more stores. Across those stores, the manager does three jobs:

Recall: the agent searches memory on demand through a tool.
Injection: relevant memories are added to the prompt automatically before the model runs.
Extraction: conversation messages are turned into memories and written to stores.

Recall and injection are on by default when you attach a store. Writing is opt-in.

Step 1: Prototype with the local test store

from strands import Agent
from strands.memory import MemoryManager
from strands.vended_memory_stores.test_memory_store import TestMemoryStore

# Persists to ~/.strands/memory/notes.json by default.
store = TestMemoryStore(name="notes")
agent = Agent(memory_manager=MemoryManager(stores=[store]))

This ran as written. It's fine on your laptop, but a JSON file in a home directory isn't per-user and won't follow a container redeploy. For production, Strands documents an Amazon Bedrock Knowledge Base store, a file store on any storage backend, and a custom-store interface.

Step 2: Swap in a per-user hosted store

MemorySync ships strands-memorysync, a store for the same MemoryManager (guide). It needs Python 3.10+, a Strands release with the MemoryManager (2026+), and a MemorySync API key in MEMORYSYNC_API_KEY.

pip install strands-agents strands-memorysync

from strands import Agent
from strands.memory import MemoryManager, InvocationTrigger
from strands_memorysync import MemorySyncStore

store = MemorySyncStore(
    user_id="customer-42",        # required: whose memories these are
    session_id="support",         # optional: tags this conversation's facts
    extraction={"trigger": InvocationTrigger()},  # send every turn, see below
)

agent = Agent(memory_manager=MemoryManager(stores=[store]))
agent("Which seat should I book?")

What happens: before every model call, the manager asks the store for relevant memories and injects them. After each exchange, only the user's messages are sent for fact extraction. Assistant replies, tool messages and system messages are not sent. In my local run (stand-in model, mocked API), the recalled memory showed up in the model's input, and the only write was the user's message with role: "user". The assistant's reply was not sent.

Step 3: Fix the "first few turns are forgotten" surprise

Strands' default extraction trigger fires every five invocations, so a user's first exchanges aren't written yet and early recalls come back empty. That's by design. The synchronous agent(...) call also flushes after each call, but invoke_async does not. If you want memories from the first exchange, pass InvocationTrigger() as above. In my local run, the first turn's user message was written right after that first call. The MemorySync guide recommends this because its writes are idempotent (a retry isn't extracted twice).

Step 4: Pick a stable `user_id`

Use your own user ID, an email or a UUID, and use the same value every session. A different value means an empty recall. The user_id is also the isolation boundary between your users. Create one store per user (or per request) rather than sharing one store across users.

Optional: explicit memory tools

tools = store.get_tools()   # -> memorysync_search, memorysync_save

I confirmed these two names on the box, and the defaults in the table below against the installed MemorySyncStore signature. There's deliberately no delete tool, so deletion stays an API or admin action, and the user identity is never a tool parameter the model can change.

Useful knobs

Parameter	Default	What it does
`top_k`	5	Memories considered per model call
`min_prompt_chars`	8	Skip recall for trivial prompts
`writable`	True	Allow extraction writes

Common questions

Do I still need a session manager? Yes, if you want to resume the exact conversation. Memory and session persistence solve different problems, and Strands documents them separately.

Why are recalls empty right after I store something? Extraction runs asynchronously, so give it a moment. Also check that both runs use the same user_id, and that you're not on the five-turn default trigger.

ModuleNotFoundError: strands? Install the framework itself: pip install strands-agents.

Want to watch a fact survive a page reload before you wire it in? Try MemorySync in the browser. No signup is needed.

Sources

Strands Agents, Memory overview: https://strandsagents.com/docs/user-guide/sdk/memory/overview/
Strands Agents, Control what the agent remembers: https://strandsagents.com/docs/user-guide/sdk/memory/managing-memory/
MemorySync Strands Agents guide: https://docs.memorysync.io/guides/strands
strands-memorysync on PyPI: https://pypi.org/project/strands-memorysync/

How to add memory to a Google ADK agent that survives restarts (MemoryService, preload_memory, per-user recall)

Mohammed Rafay — Sun, 25 Oct 2026 16:39:02 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this with AI assistance and checked it against Google's ADK docs and MemorySync's ADK guide. Code status: on Oct 25, 2026 I installed google-adk 2.13.0 and google-adk-memorysync 1.1.0 (Python 3.13) and ran all imports and the agent, Runner, context tool, callbacks and tools construction shown. I then ran the whole flow locally with a stand-in model and MemorySync's HTTP responses mocked: one turn, add_session_to_memory, a second ingest of the same session, and a turn in a fresh Runner and session that used preload_memory. Later the same day I reran the flow against the live MemorySync API (no live Gemini call; stand-in model).

In Google's Agent Development Kit (ADK), a Session holds the events and state of one conversation. The ADK docs call that short-term memory. Recalling things from earlier conversations is the job of a separate MemoryService (ADK memory docs). If your agent forgets a user every time you restart or open a new session, this is the layer to fix.

What ADK gives you

BaseMemoryService has four operations:

add_session_to_memory(session): ingest a completed session.
add_events_to_memory(...): append a delta, such as the latest turn.
add_memory(...): add explicit MemoryEntry objects.
search_memory(...): query, usually through a tool.

The docs note that add_events_to_memory and add_memory are optional and not every service implements them. Python ADK ships three services:

Service	Persistence (per ADK docs)
`InMemoryMemoryService`	None: data is lost on restart
`VertexAiMemoryBankService`	Yes, managed by Google's Agent Platform
`VertexAiRagMemoryService`	Yes, stored in Knowledge Engine

Agents read memory through ADK's built-in tools. load_memory lets the model decide when to search, and preload_memory injects results before the turn.

So your options are: stay in-memory (fine for dev), adopt Vertex AI's services, or implement BaseMemoryService against another backend.

Plugging in a third-party MemoryService

MemorySync publishes google-adk-memorysync, which implements all four BaseMemoryService methods (guide). It requires google-adk 2.0+ and Python 3.10+. Set MEMORYSYNC_API_KEY server-side.

pip install "google-adk>=2" google-adk-memorysync

Step 1: Wire the service into the Runner

from google.adk.agents import LlmAgent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.adk.tools import preload_memory
from google_adk_memorysync import MemorySyncMemoryService

memory_service = MemorySyncMemoryService()  # reads MEMORYSYNC_API_KEY

agent = LlmAgent(
    name="assistant",
    model="gemini-2.5-flash",   # any model your ADK setup supports
    instruction="You are a helpful assistant.",
    tools=[preload_memory],     # ADK's own tool, backed by the service
)

runner = Runner(
    agent=agent,
    app_name="support",
    session_service=InMemorySessionService(),
    memory_service=memory_service,
)

This construction ran on the box.

Step 2: Ingest the session when a conversation ends

session = await runner.session_service.get_session(
    app_name="support", user_id="customer-7", session_id="thread-42"
)
await memory_service.add_session_to_memory(session)

Per the guide, this sends the text messages the user wrote for fact extraction. Agent replies, partial streams and tool traffic are skipped. It raises on failure. Re-ingesting the same session doesn't extract anything twice, because each message carries a seed derived from its ADK event id. The next session for customer-7, in any process, has preload_memory inject what's known.

In my local run (stand-in model, mocked API), the ingest sent only the user's message, the second ingest sent the same event-id-based seed again, and the stored fact appeared in the model's input on a new session in a fresh Runner. In a later run against the live MemorySync API, ingesting the same session a second time returned already_exists: true and nothing was extracted twice, and a fresh Runner and session got the stored fact injected.

The ADK user_id is your isolation key. Use your real, stable user id. By default a user's memory follows them across ADK apps. Pass MemorySyncMemoryService(scope_to_app=True) to keep each app_name separate.

Step 3 (alternative): Inject and capture every turn

If you don't want to manage the end-of-session ingest:

from google_adk_memorysync import MemorySyncContextTool

agent = LlmAgent(
    name="assistant",
    model="gemini-2.5-flash",
    instruction="You are a helpful assistant.",
    tools=[MemorySyncContextTool()],   # recall before each turn + save the user's message
)

In a local run with a stand-in model and a mocked API, a stored fact reached the model's input and the user's message was the only thing written.

Use one capture path, not both. If you call add_session_to_memory, set MemorySyncContextTool(persist=False) and don't use the capture callback, so each message is sent once (the guide explains that the two paths use different seed schemes).

Optional: memory tools for the model

create_memorysync_tools(user_id="customer-7") returns five tools: add, search, list, update and delete. On the box it returned 5 tools. Pass read_only=True for untrusted agents (that returned 2 on the box).

Common questions

Why does my ADK agent forget everything after a restart? You're on InMemoryMemoryService (or no memory service at all). Its data lives in process memory, so ADK's docs say it is lost on restart.

load_memory or preload_memory? load_memory leaves recall to the model. preload_memory injects results before the turn. If recall must happen every turn, use injection.

Is there a TypeScript version? ADK has TypeScript, Go, Java and Kotlin SDKs. MemorySync's ADK package is Python only, and its docs point TypeScript users to its Vercel AI SDK or Mastra integrations.

Can I use two memory services? ADK's docs include an example of using two memory services. Check the "Can an agent have access to more than one memory service?" section.

See a fact survive a full page reload in the browser first: try MemorySync. No signup is needed.

Sources

ADK docs, Memory: https://adk.dev/sessions/memory/
MemorySync Google ADK guide: https://docs.memorysync.io/guides/google-adk
google-adk-memorysync on PyPI: https://pypi.org/project/google-adk-memorysync/

Fix "'ClusterPipeline' object has no attribute 'raise_first_error'" with OpenAI Agents SDK RedisSession on Redis Cluster

Mohammed Rafay — Sun, 25 Oct 2026 16:38:00 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this with AI assistance from the public GitHub issue and the SDK source. Code status: on Oct 25, 2026 I installed openai-agents 0.24.0 and redis 8.1.0 (Python 3.13). I started a local 3-node Redis Cluster (Redis 8.0.2), confirmed that ClusterPipeline lacks the hooked attributes, reproduced the new TypeError from add_items and clear_session with a RedisCluster client, and ran the custom session below against that cluster, including two Runner.run turns with a stand-in model (no OpenAI key, so no real LLM call). I checked the hash-slot math with redis-py's key_slot.

The error

With the OpenAI Agents SDK's Redis-backed session and a cluster client (redis.asyncio.cluster.RedisCluster), storing history fails:

File "agents/extensions/memory/redis_session.py", line 483, in _write_items_attempt
    raise_first_error = pipe.raise_first_error
AttributeError: 'ClusterPipeline' object has no attribute 'raise_first_error'

This is openai/openai-agents-python#5322, still open as of Oct 25, 2026. The reporter saw it from 0.20.0 through 0.23.1. Per the issue, add_items and (on latest) clear_session fail, get_items and pop_item work, and 0.14.5 worked for all four.

On 0.24.0 you'll get a clearer error instead. I reproduced this against a local Redis Cluster:

TypeError: RedisSession does not support transactions with RedisCluster clients. Use redis.asyncio.Redis connected to a standalone Redis server, or implement a custom Session backend for Redis Cluster.

In 0.24.0 the check sits in the write path, not in __init__. Constructing the session succeeds, and the first write raises. That comes from PR #5361 ("scope Redis Cluster rejection to transactional writes"), which the issue links and which was merged on Oct 14, 2026. On the cluster, get_items and pop_item still worked on 0.24.0, and add_items and clear_session raised the TypeError.

Why it happens

The issue identifies two causes:

Pipeline internals. The write hooks pipe.raise_first_error and pipe.parse_response, which exist on the standalone redis.asyncio.client.Pipeline but not on ClusterPipeline. I checked: hasattr(ClusterPipeline, "raise_first_error") is False, and it's True for Pipeline.
Cross-slot transaction. The write is a WATCH/MULTI transaction over three keys: {prefix}:{id}, {prefix}:{id}:messages and {prefix}:{id}:counter. Those keys hash to different cluster slots, and Redis Cluster only runs a transaction within one slot. So adding the missing hooks wouldn't be enough. With redis-py's key_slot, repro:s1 and repro:s1:messages landed in slots 7598 and 11344.

Fix options

A. Point RedisSession at a standalone (non-cluster) Redis. This is what the SDK's error message suggests. It's simplest if your provider offers a non-cluster mode.

B. Pin openai-agents==0.14.5. The issue reports that it worked on a cluster, and on my local cluster (with redis 8.1.0) add, get, pop and clear all ran. You'd give up every later fix, though. Use this only as a stopgap.

C. Write a small cluster-safe Session. The SDK's sessions are a four-method interface (get_items, add_items, pop_item, clear_session). Use one list key with a Redis Cluster hash tag ({...}), so everything for a session lives in one slot and needs no transaction:

import json
from agents.memory import SessionABC


class ClusterRedisSession(SessionABC):
    """Session history on Redis Cluster: one list key, hash-tagged by session id."""

    def __init__(self, session_id: str, redis_client, key_prefix: str = "agents"):
        self.session_id = session_id
        self._redis = redis_client
        # {...} is a hash tag: every key for this session maps to one slot.
        self._key = f"{key_prefix}:{{{session_id}}}:messages"

    async def get_items(self, limit: int | None = None):
        start = -limit if limit else 0
        raw = await self._redis.lrange(self._key, start, -1)
        return [json.loads(r) for r in raw]

    async def add_items(self, items):
        if items:
            await self._redis.rpush(self._key, *[json.dumps(i) for i in items])

    async def pop_item(self):
        raw = await self._redis.rpop(self._key)
        return json.loads(raw) if raw else None

    async def clear_session(self):
        await self._redis.delete(self._key)

Use it like any other session:

from redis.asyncio.cluster import RedisCluster
from agents import Agent, Runner

client = RedisCluster(host="your-cluster-host", port=6379)
session = ClusterRedisSession("user-123:chat-1", client, key_prefix="agents")
result = await Runner.run(agent, "Hi again", session=session)

What I verified on the local 3-node cluster: add/get (including limit=1 returning the newest item), pop and clear all behaved as expected. Two Runner.run turns with a stand-in model stored both user and assistant items, and the second turn's model input included the first turn's history. repro:{s1}:messages and repro:{s1}:counter both hash to slot 15224. I didn't make a real LLM call or test with concurrent writers.

Trade-offs: RPUSH is atomic for a single call, but this skips the SDK's WATCH-based protections and its session_settings handling. Concurrent writers to the same session interleave in arrival order. The SDK docstring says third-party libraries should implement the Session protocol rather than subclass SessionABC. Subclassing is fine in your own app code. SessionABC declares session_settings with a default of None, so this class doesn't need to set it.

A note on what a session is (and isn't)

A session replays one conversation's history. It doesn't give a user memory across different sessions. That's a separate layer, whether you use the SDK's other memory features or a hosted store. MemorySync has an OpenAI Agents SDK guide for that cross-session layer. It doesn't replace your Redis session store.

Common questions

Will upgrading fix it? As of 0.24.0, no. You get a clear TypeError instead of the AttributeError. Watch #5322 for real cluster support. The reporter proposed hash-tagged keys plus a single-node WATCH/MULTI.

Why do get_items and pop_item still work? According to the issue, only the transactional write paths use the hooked pipeline.

Can I just hash-tag the prefix I pass to RedisSession? The key layout is {prefix}:{id}.... A tag in the prefix would put all sessions in one slot, which concentrates load on one node. It also wouldn't fix the missing pipeline attributes, because 0.24.0 rejects any RedisCluster client on write.

Managed Redis only offers cluster mode. Is option C safe for production? It's a small, readable store, but test it under your real concurrency on a staging cluster first.

Curious what cross-session memory looks like next to session history? Try MemorySync in the browser. No signup is needed.

Sources

Issue #5322: https://github.com/openai/openai-agents-python/issues/5322
OpenAI Agents SDK, Sessions: https://openai.github.io/openai-agents-python/sessions/
Redis Cluster spec, hash tags: https://redis.io/docs/latest/operate/oss_and_stack/reference/cluster-spec/
MemorySync OpenAI Agents SDK guide: https://docs.memorysync.io/guides/openai-agents

Add long-term memory to a Microsoft Agent Framework agent (one context provider, per-user recall across sessions)

Mohammed Rafay — Sun, 25 Oct 2026 16:37:51 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and Microsoft Agent Framework docs. Install, imports and object construction were run; calls needing an API key were checked against the docs and run only against a local mock, not the live services.

Microsoft Agent Framework handles memory through context providers: objects you pass in context_providers=[...] that add context before the model runs and process the result afterwards (Agent Framework context providers docs). The built-in InMemoryHistoryProvider gives you local conversational memory for a session. Provider state lives in the session's state. That's the right home for the current thread. It isn't the right home for "this user is vegetarian and prefers short answers" when the same person opens a new session next week.

This post adds per-user long-term memory with MemorySync's Agent Framework integration, agent-framework-memorysync. MemorySync is a hosted memory layer, and I'm building it. Agent Framework behaviour comes from Microsoft's docs and the framework's source; everything about MemorySync comes from its Microsoft Agent Framework Memory guide. I installed the packages and ran the snippets with a stub chat client and a mocked MemorySync endpoint (agent-framework-core 1.23.0, agent-framework-memorysync 1.1.0), but not against a real model or a real MemorySync key, so check it against your versions.

If you're here from AutoGen: the AutoGen repository is now archived, and its README points new users to Agent Framework and links a migration guide. MemorySync has an AutoGen guide too if you can't move yet, but I'd build new agents on Agent Framework.

What you'll set up

One MemorySyncContextProvider that recalls relevant facts about the user before every run and sends the user's messages for fact extraction after it.
Per-run user identity, so one agent can serve many users.
Optional: memory tools the model can call itself.

How Agent Framework thinks about memory

A context provider subclasses ContextProvider and overrides two hooks (docs):

before_run adds instructions, messages or tools to the invocation, e.g. context.extend_instructions(self.source_id, "...").
after_run sees the input messages and the response, so it can store or extract things.

Microsoft's own memory sample stores the user's name in provider state, so it carries across turns of that session. You can stack several providers on one agent (history, memory, RAG). The MemorySync provider is one of these, so you're not replacing anything the framework does.

Install

pip install agent-framework-memorysync

Per the guide it needs Python 3.10+ and agent-framework-core 1.8 or newer. PyPI currently lists agent-framework-memorysync 1.1.0 (requiring agent-framework-core>=1.8,<2), and agent-framework-core is at 1.23.0. You'll need a MemorySync API key from the dashboard (Settings → API Keys, inside a project). Set it as MEMORYSYNC_API_KEY and keep it server-side.

Step 1: Create the provider

from agent_framework_memorysync import MemorySyncContextProvider

provider = MemorySyncContextProvider(
    user_id="customer-42",   # required: the end user these memories belong to
    session_id="support",    # optional: tags this conversation's facts
)
# api_key="ms_..." also works; otherwise it reads MEMORYSYNC_API_KEY

user_id is a stable string you choose: your internal user ID, an email or a UUID. Use the same value on every run, or recall comes back empty. One user_id drives both storage and retrieval.

Step 2: Attach it to the agent

from agent_framework import Agent

agent = Agent(client=..., context_providers=[provider])

result = await agent.run("Which seat should I book?")

What happens, per the guide:

Before every run, relevant memories about this user are recalled into the instructions layer. They aren't added as a fake user message.
After the run, the user's messages are sent to MemorySync. The server extracts the durable facts and stores only those. Filler like "ok" yields none, and the agent's replies aren't sent.
Tool loops capture once: one send per user turn, not per model round-trip. Retries aren't extracted twice.
Failures don't break the run. If the memory lookup fails or times out, the agent runs without memories. If the send after the run fails, it's logged, and the run's result still stands.

Extraction is asynchronous, so a fact you just stated may take a moment to become recallable.

Step 3: Keep the thread and the user separate

The provider covers facts about the user. For the current conversation, keep using a session and a history provider. Here's how I'd combine them, using InMemoryHistoryProvider and create_session() from Microsoft's docs:

from agent_framework import Agent, InMemoryHistoryProvider
from agent_framework.openai import OpenAIChatClient

agent = Agent(
    client=OpenAIChatClient(),
    instructions="You are a helpful assistant.",
    context_providers=[
        InMemoryHistoryProvider("memory", load_messages=True),  # this thread
        provider,                                               # this user, across threads
    ],
)

session = agent.create_session()
await agent.run("I'm vegetarian and I always pick the aisle seat.", session=session)

OpenAIChatClient lives in a separate package (pip install agent-framework-openai, per Microsoft's OpenAI provider docs), and with no arguments it reads OPENAI_API_KEY and OPENAI_CHAT_MODEL (or OPENAI_MODEL) from the environment. That's my own combination of the two docs, so test it. InMemoryHistoryProvider is local, as its name says. Next week's new session starts with an empty history, and that's where the MemorySync provider comes in: the user's facts are still recalled.

Step 4: One agent, many users

The guide calls out a common gap: some memory adapters fix identity when you construct them, so a multi-tenant server ends up building one provider per user. This one resolves identity fresh on every run, in this order:

Per run: await agent.run(..., options={"memorysync_user_id": user_id})
A resolver: MemorySyncContextProvider(user_id_resolver=lambda session: ...)
The constructor's user_id

result = await agent.run(
    "What should I order?",
    options={"memorysync_user_id": current_user.id},
)

My advice: take that ID from your authenticated user record, never from the request body.

Step 5 (optional): Memory tools and read-only runs

Two settings from the guide's configuration table:

provider = MemorySyncContextProvider(
    user_id="customer-42",
    expose_search_tool=True,  # registers search_memory + save_memory each run
    capture=False,            # recall only; don't send this run's user messages
)

capture=False is handy for eval runs that shouldn't write memory. top_k (default 5) controls how many memories are considered per run, and min_prompt_chars skips recall for trivial prompts.

Coming from AutoGen: what changes

AutoGen's AgentChat had a Memory protocol with query, update_context, add, clear and close, and you passed memories to AssistantAgent(memory=[...]) (AutoGen Memory and RAG docs). update_context added retrieved entries to the agent's model context before a step. Nothing was saved unless your code called add.

In Agent Framework, the same job is split across a provider's two hooks: before_run for recall and after_run for capture. In MemorySync's two adapters, that's the practical difference:

AutoGen adapter: recall is automatic, but capture is your job. After each exchange you call await memory.add_turn_pair(user_text, reply), and only the user text is sent.
Agent Framework adapter: both are automatic. There's no per-turn code, and capture=False turns the write side off.

So when you port an AutoGen agent, delete the add_turn_pair call. If you keep it next to the provider, you'd be sending the same user text from two places. Keep the same user_id values as before. I haven't checked whether facts stored through the AutoGen adapter come back through the new one (the two tag sessions differently), so test with one user first.

Troubleshooting

From the guide:

ModuleNotFoundError: agent_framework. The framework itself isn't installed: pip install agent-framework.
Recall returns nothing right after storing. Extraction is asynchronous; give it a moment. Also confirm store and recall use the same user_id.
The agent ran without memories once. A slow or failed lookup is skipped rather than holding up the run. The next run recalls normally.
Multi-tenant identity. Don't build one provider per user. Pass options={"memorysync_user_id": ...} per run.

One more, from the guide's quota section: on a monthly plan limit, over-limit writes are accepted without storing and reads return empty, so the agent keeps working. Evaluation keys return a 429 instead, so you notice during testing.

Sources

MemorySync Microsoft Agent Framework Memory guide: docs.memorysync.io/guides/agent-framework (and /guides/autogen)
Microsoft Learn: Agent Framework context providers (learn.microsoft.com/en-us/agent-framework/concepts/agents/conversations/context-providers)
microsoft/agent-framework: python/packages/core/agent_framework/_sessions.py (ContextProvider, provider state in AgentSession.state) and python/samples/01-get-started/04_memory.py
microsoft/autogen README (archived; points to Agent Framework) and AutoGen AgentChat Memory and RAG docs
PyPI: agent-framework-memorysync 1.1.0, agent-framework-core 1.23.0

Try it

If you want to see the save, reload and recall loop before wiring up an agent, the MemorySync playground runs it in your browser: memorysync.io/try.

MCP memory server lost your memories? Fixing MEMORY_FILE_PATH and the npx cache

Mohammed Rafay — Sun, 25 Oct 2026 16:37:06 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and MCP server-memory, Claude Code docs. Install and setup steps were run on a Linux box (server-memory 2.0.0, Node 24, Claude Code CLI, the MemorySync installer in list/dry-run mode); the Windows, VS Code and Docker configs and the hosted server sign-in weren't run.

If you run the reference MCP memory server (@modelcontextprotocol/server-memory) through npx, you may have set MEMORY_FILE_PATH, told Claude a few things, and later found the file you pointed at empty. The memories were real. They were written somewhere else: inside npm's npx cache.

That's the long-running GitHub issue modelcontextprotocol/servers#692, "Memory MCP ignores custom storage path setting". The reporter's file ended up at a path like ~/.npm/_npx/<hash>/node_modules/@modelcontextprotocol/server-memory/dist/memory.json. Some people in the thread reported losing data when that cache was cleared or the package was updated. The issue was closed on Oct 19, 2026, when the reference servers were released as v2.

Below is how I'd find where your memory actually lives, pin it to a file you control, get the old data back, and decide whether you want a local file at all. The server behaviour comes from the server-memory README, its source and the issue thread. Client config comes from the Claude Code MCP docs. The MemorySync part comes from the MemorySync MCP docs. I'm building MemorySync, a hosted memory layer, so weigh that section with that in mind. I ran the Linux commands below against server-memory 2.0.0 on Node 24 before publishing; the Windows, VS Code and Docker variants are from the README and weren't run.

Why it happens

The server stores its knowledge graph (entities, relations, observations) as JSONL. In the current source the default path is memory.jsonl in the package directory, the folder the server's code was installed into (in 2.0.0 that's the package's dist folder). With npx -y @modelcontextprotocol/server-memory, that folder is inside the npx cache. So when the variable doesn't take effect, your memory sits in a cache directory that npm can replace at any time.

There are three ways to end up there:

The variable never reaches the server. In the issue, commenters suspected the client or npx wasn't passing it through. When the maintainer closed it, he said v2 uses an absolute path as given "once the client passes the variable through". So the client config still matters.
The path is relative. In v2, a relative MEMORY_FILE_PATH is joined onto the package directory. memory.jsonl or ./memory.jsonl therefore lands back in the npx cache.
An older version. Older releases used memory.json. When there's no custom path, the server renames a legacy memory.json in its default folder to memory.jsonl on startup.

v2 also expands a leading ~ itself, because MCP clients pass env values from JSON and no shell does it for them.

Step 1: Find where your memory actually is

Before changing anything, look for the file the server has really been writing:

# macOS / Linux: find graph files inside the npx cache
find ~/.npm/_npx -path "*server-memory*" \( -name "memory.json" -o -name "memory.jsonl" \) 2>/dev/null

On Windows the npm cache is usually under %LocalAppData%\npm-cache\_npx. That's npm's default location, not something from the server docs, so check npm config get cache if it isn't there.

If you find a file with your entities in it, copy it somewhere safe now, before you touch the config or the cache.

Step 2: Use an absolute path and the current version

The server requires Node.js 24 or later when you run it through npx (per its README; npm lists 2.0.0 as the latest version). For Claude Desktop, the README's config looks like this, with an absolute path:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "env": {
        "MEMORY_FILE_PATH": "/Users/you/mcp-data/memory.jsonl"
      }
    }
  }
}

On Windows the README launches npx through cmd /c ("command": "cmd", "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]) with the same env block.

My own additions: create the directory first, because the server saves atomically through a temp file next to the memory file and also puts a lock file there, so the folder must be writable. If you want to be sure you're on v2, pin it with standard npm syntax: @modelcontextprotocol/server-memory@2.0.0.

For Claude Code, pass the variable with --env, after the server name and before -- (that's the documented pattern for stdio servers):

claude mcp add memory --env MEMORY_FILE_PATH=/Users/you/mcp-data/memory.jsonl \
  -- npx -y @modelcontextprotocol/server-memory

For VS Code, the README uses the same command/args shape under a top-level servers key in mcp.json. Add the same env block.

Restart the client fully after editing, since MCP config is read at startup.

Step 3: Check that it worked

Ask the assistant to remember one throwaway fact, then check that your file changed:

ls -l /Users/you/mcp-data/memory.jsonl && tail -n 3 /Users/you/mcp-data/memory.jsonl

If the file is still missing but the fact was "remembered", the variable isn't reaching the server. Run the find command from Step 1 again to see where the write went.

Step 4: Bring the old memory back

Put the file you rescued in Step 1 at your new MEMORY_FILE_PATH. If it's a legacy memory.json, rename it to memory.jsonl. That's the same rename the server does itself during its own migration. Then restart and ask the assistant to read the graph (the read_graph tool) to confirm your entities came back.

Step 5: Two more fixes from the docs and the thread

Docker instead of npx. The README's Docker config mounts a named volume (-v claude-memory:/app/dist), so the default file lives in a Docker volume rather than the npx cache. The README also warns that an old volume can contain an index.js the new container will overwrite.
Run it with node directly. One commenter in the issue worked around it by installing the package globally and pointing the client at the installed index.js with node, so no npx layer sits in between. That's a community workaround, not official guidance.

If two clients (say Claude Desktop and Claude Code) point at the same file, each starts its own server process. v2 takes a lock file during every write so they take turns. The README notes this relies on a local filesystem, so don't share the file over a network drive.

When a hosted memory server is the simpler answer

A local file is fine if one machine and a couple of clients are all you need. The trouble starts when you want the same memory on a laptop and a desktop, or in a CI job, and you end up syncing a JSONL file by hand.

That's the case MemorySync covers: its memory server is hosted at https://mcp.memorysync.io/mcp, so there's no local process and no file path to configure. Per the Connect a Client docs:

npx -y memorysync-mcp-install --list     # show detected clients, change nothing
npx -y memorysync-mcp-install --dry-run  # print what it would write
npx -y memorysync-mcp-install            # configure every detected client

The installer backs up each config file before changing it. You sign in through the browser on first use. For headless setups the server also accepts a MemorySync API key in the X-API-Key header. Keep that key in an environment variable or CI secret, never in a committed config file. Restart the client afterwards.

It's a different model from the reference server, not a drop-in replacement. Instead of an entity/relation graph that the model edits directly, the assistant calls tools like search_memory and add_memory. add_memory runs server-side extraction, so filler is discarded and skipped is a normal result. The Memory Tools page lists all 15 tools. I'm not covering moving an existing memory.jsonl into it here.

Troubleshooting

Memory "works" but your file stays empty. The variable isn't reaching the server, or the path is relative. Use an absolute path and re-check the client's env / --env.
Everything vanished after an update. The data was probably in the npx cache. Search it (Step 1) before anything else clears it.
A write fails with a lock error. v2 gives up after 60 seconds rather than overwriting. Check for a stuck process, and make sure the folder is writable.
The hosted server shows no tools. Restart the client. A 405 on a GET request is expected, per the MemorySync docs.

Sources

GitHub issue modelcontextprotocol/servers#692 and its closing comment (Oct 19, 2026)
server-memory README and src/memory/index.ts (default path, relative-path and ~ handling, legacy rename, lock file); npm @modelcontextprotocol/server-memory 2.0.0 (Node >= 24)
Claude Code MCP docs: code.claude.com/docs/en/mcp (--env for stdio servers)
MemorySync docs: docs.memorysync.io/mcp/overview, /mcp/install, /mcp/tools

Try it

If you want to see a memory survive a full page reload before wiring up any client, the MemorySync playground runs the save, reload and recall loop in your browser: memorysync.io/try.

Add long-term memory to a Mastra agent (input/output processors, per-user recall)

Mohammed Rafay — Sat, 24 Oct 2026 16:09:52 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and Mastra docs. The code is adapted from the docs and I haven't run it.

Mastra agents already have memory. Give an agent a Memory from @mastra/memory and pass memory: { resource, thread } on each call: resource is a stable id for the user and thread isolates one conversation (Mastra memory docs). Mastra also has working memory and semantic recall, stored in whichever storage provider you configure.

If that's working for you, keep it. This post is for when you want durable facts about each user extracted and recalled by a hosted service, wired in through Mastra's own processor pipeline. It uses MemorySync's Mastra integration, memorysync-mastra. MemorySync is a hosted memory layer, and I'm building it. Mastra behaviour comes from its docs on memory and processors. Everything about MemorySync comes from its Mastra Memory guide. The code is adapted from those docs. I haven't run it for this post, so check it against your versions.

What you'll set up

An input processor that injects recalled facts before the model call, and an output processor that sends the user's message for fact extraction after it.
Per-call user identity, so one agent can serve many users.
Optional: recall modes, five memory tools and standalone helpers.

Install

npm install memorysync-mastra

Per the guide it supports @mastra/core 1.42+ (Node 20+ for the package; current @mastra/core itself requires Node 22+). npm currently lists 1.1.0 with peer @mastra/core >=1.42.0 <2.0.0. Set MEMORYSYNC_API_KEY in the environment, or pass apiKey, and keep it server-side.

Step 1: Add the processors

Mastra processors are hooks in the agent pipeline: inputProcessors run before messages reach the model, outputProcessors run after the model responds and before the result is returned (processors docs). MemorySync uses one of each:

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { createMemorySyncProcessors } from "memorysync-mastra";

const { inputProcessor, outputProcessor } = createMemorySyncProcessors({
  userId: "customer-7",     // scopes memory to one end user
  sessionId: "thread-42",   // groups the stored facts by thread
});

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "You are a helpful assistant.",
  model: openai("your-model"),
  inputProcessors: [inputProcessor],
  outputProcessors: [outputProcessor],
});

await agent.generate("I'm vegetarian and I fly aisle.");

// Later, same user, any thread
const { text } = await agent.generate("Book my trip: flight plus a dinner spot.");

Per the guide:

Recall is injected once per generate/stream call (it uses processInput, not the per-step hook), so multi-step tool loops don't add the block twice. Your instructions stay first; the memory block is appended after them.
Only the user's message is sent; MemorySync stores just the durable facts in it. Assistant replies aren't stored.
If recall fails, the call proceeds without context. If persisting fails, it's reported through onError (a console warning by default) and never thrown.

Prefer less wiring? withMemorySync(config, { userId }) wraps your agent config and merges both processors in, keeping any processors you already have (MemorySync's run after yours).

Step 2: Resolve the user per call

A Mastra server agent serves many users, so identity is resolved per call, in this priority order:

import { RequestContext } from "@mastra/core/request-context";
import {
  createMemorySyncProcessors,
  MASTRA_RESOURCE_ID_KEY,
  MASTRA_THREAD_ID_KEY,
} from "memorysync-mastra";

// 1. Your own resolver wins over everything
createMemorySyncProcessors({
  resolveIdentity: (requestContext) => ({
    userId: currentSession.userId,
    sessionId: currentSession.threadId,
  }),
});

// 2. Static ids (scripts, workers)
createMemorySyncProcessors({ userId: "customer-7", sessionId: "thread-42" });

// 3. Mastra's RequestContext, set by your server middleware
const ctx = new RequestContext();
ctx.set(MASTRA_RESOURCE_ID_KEY, "customer-7");
ctx.set(MASTRA_THREAD_ID_KEY, "thread-42");
await agent.generate(messages, { requestContext: ctx });

// 4. Mastra's own memory ids on the call
await agent.generate("I moved to Lisbon.", {
  memory: { resource: "customer-7", thread: "thread-42" },
});

Option 4 is handy if you already use Mastra memory: the same resource id becomes the MemorySync user. If no source yields a user id, recall is skipped and the write is refused (reported through onError), never sent to a default scope. Take the id from your auth session, not from the request body.

Step 3: Streaming

const stream = await agent.stream("Plan a dinner for my team.", {
  memory: { resource: "customer-7", thread: "thread-42" },
});
for await (const chunk of stream.textStream) process.stdout.write(chunk);

The user's message is sent once, after the full stream. Per the guide, a stream that errors mid-flight (finishReason: "error") sends nothing, so the retry sends the message once.

Step 4 (optional): Recall modes and switches

createMemorySyncProcessors({ userId, mode: "query" });   // relevant to the latest message (default)
createMemorySyncProcessors({ userId, mode: "profile" }); // stable overview of the user
createMemorySyncProcessors({ userId, mode: "full" });    // both

createMemorySyncProcessors({ userId, persist: false });  // read-only
createMemorySyncProcessors({ userId, recall: false });   // write-only

createMemorySyncProcessors({
  userId,
  k: 12,
  template: "What you know about this user:\n{context}",
});

Step 5 (optional): Tools and helpers

import { createMemorySyncTools } from "memorysync-mastra";

const agent = new Agent({
  id: "assistant",
  name: "Assistant",
  instructions: "Use the memory tools to remember durable facts.",
  model: openai("your-model"),
  tools: { ...createMemorySyncTools({ userId: "customer-7" }) },
});

// For agents you don't fully trust: search and list only
createMemorySyncTools({ userId: "customer-7", readOnly: true });

The five tools are add_memory, search_memory, list_memories, update_memory (tags and importance only) and delete_memory; they return readable error strings instead of throwing. For workflows there are getMemoryContext, searchMemories and saveTurn. saveTurn sends only the user's message and throws on failure. The guide says a turn sent by both the processors and saveTurn is recognised server-side and extracted once.

Troubleshooting

Nothing is remembered. Check onError output; a call with no resolvable user writes nothing by design.
A new thread knows nothing. The user id (or resource) must match across calls. The thread can differ.
Version errors. The package targets @mastra/core 1.x from 1.42, and current core needs Node 22+.

Common questions

Does a Mastra agent remember previous conversations?
Yes, if you give it a Memory from @mastra/memory and pass memory: { resource, thread } on each call. To recall earlier messages, call the agent with the same resource and thread values. lastMessages controls how many recent messages are included (Mastra memory docs).

Where does Mastra store memory?
In the storage provider you configure. Memory needs a storage provider to persist message history; the quickstart uses @mastra/libsql (Mastra memory docs).

What's the difference between resource and thread in Mastra memory?
resource is a stable id for the user or entity, and thread isolates one conversation. Each thread's owner can't be changed after creation, so don't reuse a thread id across owners. Working memory and semantic recall are resource-scoped by default, so they carry across that user's threads (Mastra memory docs).

Can I use Mastra's Memory and the MemorySync processors together?
Yes. MemorySync's guide recommends running both: Mastra's Memory for the conversation history, and the MemorySync processors for durable per-user facts across threads. The processors can also read the user and thread from the same memory: { resource, thread } option (MemorySync Mastra guide).

Sources

MemorySync Mastra Memory guide: docs.memorysync.io/guides/mastra
Mastra docs: mastra.ai/docs/memory/overview and mastra.ai/docs/agents/processors
npm: memorysync-mastra 1.1.0

Try it

If you want to see the save, reload and recall loop before wiring up an agent, the MemorySync playground runs it in your browser: memorysync.io/try.

Add long-term memory to a Pydantic AI agent (one capability, per-user recall across runs)

Mohammed Rafay — Sat, 24 Oct 2026 16:09:40 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and Pydantic AI docs. The code is adapted from the docs and I haven't run it.

Pydantic AI keeps context across runs through message history: you pass message_history= (or the previous result's conversation) into the next Agent.run, and result.all_messages() / new_messages() give you the messages back (Pydantic AI message history docs). Storing and reloading that list is up to you, and it only covers one conversation. Start a new thread and the agent knows nothing about the user it talked to yesterday.

This post adds per-user long-term memory with MemorySync's Pydantic AI integration, pydantic-ai-memorysync. MemorySync is a hosted memory layer, and I'm building it. Pydantic AI behaviour comes from its official docs on message history and capabilities. Everything about MemorySync comes from its Pydantic AI Memory guide. The code is adapted from those docs. I haven't run it for this post, so check it against your versions.

What you'll set up

One MemorySyncCapability in the Agent constructor that recalls relevant facts before every run and sends the user's prompt for fact extraction after a successful run.
User identity taken from your deps, so one agent can serve many users.
Optional: five memory tools, a typed search tool and async helpers.

Install

pip install pydantic-ai-memorysync

Per the guide it needs pydantic-ai (or pydantic-ai-slim) 2.0+ and Python 3.10+. PyPI currently lists 1.1.0 with pydantic-ai-slim>=2,<3. Set MEMORYSYNC_API_KEY in the environment, or pass api_key, and keep it server-side. This is Python only; the guide points TypeScript users to the Vercel AI SDK or Mastra integrations.

Step 1: Add the capability

In Pydantic AI, a capability is a reusable unit of agent behaviour that you pass to the Agent constructor instead of wiring instructions, tools and hooks separately (capabilities docs). MemorySync ships memory as one:

from pydantic_ai import Agent
from pydantic_ai_memorysync import MemorySyncCapability

agent = Agent(
    "openai:your-model",
    instructions="You are a helpful assistant.",
    capabilities=[MemorySyncCapability(user_id="customer-7")],
)

# First run
await agent.run("I'm vegetarian and I fly aisle.")

# A later run, new conversation, same user
result = await agent.run("What should I cook tonight?")

What happens, per the guide:

Recall goes through the instructions channel, not into the message list. The model sees a "Relevant memories about this user" block after your instructions, but it is never a conversation part. So if you replay result.all_messages() into the next run, old memory blocks don't pile up in the transcript.
Capture happens in after_run, which Pydantic AI fires only when a run succeeds. A failed run leaves no half-remembered turn.
Only the user's prompt is sent. MemorySync extracts the durable facts in it and stores those; filler like "ok" or "thanks" yields none. The model's reply, tool calls, retry prompts and thinking parts aren't sent. Streaming runs send the prompt once the stream completes.
Prompts are grouped by the run's conversation_id (sent as session_id). Pass session_id="..." to pin it yourself. persist=False gives read-only memory.

Failure handling: if recall fails, the agent runs with its base instructions; if the send fails, the run result is untouched. Both report through on_error (a logging warning by default).

Step 2: Take the user from your deps

One agent usually serves many users, so don't hard-code user_id:

from dataclasses import dataclass
from pydantic_ai import Agent
from pydantic_ai_memorysync import MemorySyncCapability

@dataclass
class MyDeps:
    user_id: str

agent = Agent(
    "openai:your-model",
    deps_type=MyDeps,
    capabilities=[MemorySyncCapability()],  # reads ctx.deps.user_id
)

await agent.run("hi", deps=MyDeps(user_id="customer-7"))

# Or resolve it from anything on your deps:
MemorySyncCapability(user_id_resolver=lambda ctx: ctx.deps.user_id)

The resolution order is user_id_resolver(ctx), then a static user_id, then ctx.deps.user_id. If none is found, the run goes ahead without memory and the miss is reported through on_error; it never falls back to a shared namespace. My advice: fill user_id from your authenticated user record, not from the request body.

Keep using message_history for the current conversation. The capability adds what Pydantic AI doesn't do on its own: facts about the user that carry over to new threads.

Step 3 (optional): Memory tools

If you want the model to decide what to save:

from pydantic_ai import Agent
from pydantic_ai_memorysync import create_memorysync_tools

agent = Agent(
    "openai:your-model",
    instructions="Use the memory tools to remember durable facts.",
    tools=create_memorysync_tools(user_id="customer-7"),
)

# For agents you don't fully trust: search and list only
create_memorysync_tools(user_id="customer-7", read_only=True)

The tools are add_memory, search_memory, list_memories, update_memory (tags and importance only; memory text can't be changed) and delete_memory. In Pydantic AI a tool exception fails the whole run, so these return short readable error strings instead of raising.

Step 4 (optional): Typed search and helpers

When downstream code consumes tool output structurally, use the typed search tool. It returns list[MemoryResult] (Pydantic models with id, text, score), and on failure returns [] and reports through on_error:

from pydantic_ai import Agent
from pydantic_ai_memorysync import create_memory_search_tool

agent = Agent(
    "openai:your-model",
    tools=[create_memory_search_tool(user_id="customer-7")],
)

For hand-wired setups there are async helpers:

from pydantic_ai_memorysync import get_memory_context, save_turn, search_memories

context = await get_memory_context("what should I cook?", user_id="customer-7")  # "" for a new user
hits = await search_memories("dietary preferences", user_id="customer-7")

# Explicit persistence. This one raises on failure.
await save_turn(user_id="customer-7", user="I'm vegetarian",
                assistant="Noted!", session_id="thread-42")

save_turn sends only the user message. API errors raise MemorySyncAPIError, which carries the HTTP status and server detail.

Troubleshooting

Nothing is remembered. Check on_error output. A run with no resolvable user proceeds memoryless; so does a failed run, because capture only happens after success.
A new thread knows nothing. The user_id must be identical across runs. session_id / conversation_id can differ.
Duplicate memory text in the transcript. It shouldn't happen with the capability, since recall rides the instructions channel. If you see it, check you're not also pasting get_memory_context output into your prompt.
Version errors. The package targets pydantic-ai 2.x.

Common questions

Does Pydantic AI keep memory between runs?
Not on its own. Each Agent.run only sees the messages you pass in. To continue a conversation, pass the earlier messages back with message_history=, using result.all_messages() (everything, including prior runs) or result.new_messages() (only the current run) (Pydantic AI message history docs).

How do I persist message_history to a database?
The docs' intended route is a TypeAdapter: ModelMessagesTypeAdapter serializes messages to JSON and back. For a conversation you plan to continue, they suggest storing its Conversation (via ConversationTypeAdapter) rather than the messages alone. Where those bytes live and when to reload them is left to your application; conversation_id is the key to store them under, and the resolved value is on the result as AgentRunResult.conversation_id (message history docs).

How do I stop message history from growing too large?
Use the ProcessHistory capability. It lets you change the history before each model request, for example to keep only recent messages or summarize old ones (message history docs).

How do I make an agent remember a user across new conversations?
A stored history only covers the conversation it belongs to. For facts that should follow a user into new threads, you need a separate memory store. The setup in this post uses MemorySync's MemorySyncCapability: it adds recalled facts through the instructions channel, so nothing is added to your message history, and it sends the user's prompt for fact extraction only after a run succeeds (MemorySync Pydantic AI guide).

Sources

MemorySync Pydantic AI Memory guide: docs.memorysync.io/guides/pydantic-ai
Pydantic AI docs: ai.pydantic.dev/message-history/ and ai.pydantic.dev/capabilities/
PyPI: pydantic-ai-memorysync 1.1.0

Try it

If you want to see the save, reload and recall loop before wiring up an agent, the MemorySync playground runs it in your browser: memorysync.io/try.

Add persistent memory to a LlamaIndex agent (Memory, memory blocks and a retriever)

Mohammed Rafay — Fri, 23 Oct 2026 16:13:12 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and LlamaIndex docs. The code is adapted from the docs and I haven't run it.

LlamaIndex agents already have memory. Pass a Memory object to agent.run(..., memory=memory) and the agent gets a short-term chat buffer plus optional long-term "memory blocks". Two things surprise people when they try to make it remember a user across sessions:

By default the Memory class uses an in-memory SQLite database, so the buffer is gone when the process restarts (LlamaIndex memory docs).
Memory blocks only receive messages when the short-term buffer overflows. The defaults are token_limit=30000 and chat_history_token_ratio=0.7, so nothing is flushed to long-term memory until the chat history passes about 21,000 tokens. Most real conversations never get that long.

This post fixes both with MemorySync's LlamaIndex integration, llamaindex-memorysync. MemorySync is a hosted memory layer, and I'm building it. LlamaIndex behaviour comes from the official memory guide linked above. Everything about MemorySync comes from its LlamaIndex Memory guide. The code is adapted from those docs. I haven't run it for this post, so check it against your versions.

What you'll set up

A drop-in Memory that sends each user message for fact extraction as it arrives and recalls relevant facts on later runs, for the same user, in any thread.
Optional: the recall block on its own, composed with blocks you already use.
Optional: memories as a LlamaIndex retriever, a query engine or an agent tool.
Optional: five memory tools and three helpers.

Install

pip install llamaindex-memorysync

Per the guide it needs llama-index-core 0.13+ and Python 3.10+. PyPI currently lists 1.1.0 with llama-index-core>=0.13,<0.15. Set MEMORYSYNC_API_KEY in the environment, or pass api_key, and keep it server-side. This is Python only. The guide points TypeScript users to the Vercel AI SDK or Mastra integrations.

Step 1: Swap in MemorySyncMemory

from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from llamaindex_memorysync import MemorySyncMemory

memory = MemorySyncMemory.from_defaults(
    user_id="customer-7",    # required: scopes memory to one end user
    session_id="thread-42",  # groups the stored facts by thread
)

agent = FunctionAgent(tools=[...], llm=OpenAI(model="your-model"))

# First conversation
await agent.run("I'm vegetarian and I fly aisle.", memory=memory)

# A later run for the same user
response = await agent.run(
    "Book my trip: flight plus a dinner spot.", memory=memory
)

MemorySyncMemory is a subclass of LlamaIndex's Memory, not a wrapper, so token_limit, insert_method and any extra blocks still work. What changes, per the guide:

Each user message is sent to MemorySync when it's added to memory (on aput), not when the buffer overflows. Short conversations persist too.
Only user messages are sent. Assistant replies, system prompts and tool traffic stay in the short-term buffer.
recall=False or persist=False turns either half off.

The guide also spells out failure handling. The short-term buffer write happens first and its errors propagate. The MemorySync write comes after and reports through on_error instead of failing the turn. If recall fails, no memory block is rendered and the chat history still flows.

Note that the short-term buffer is still LlamaIndex's own. If you also want the raw transcript to survive restarts, LlamaIndex's docs show passing async_database_uri (for example a Postgres URI) or your own chat_store to Memory.from_defaults. I'm assuming those pass through, since the guide says every standard Memory kwarg does, but I haven't tested it.

Step 2: Who owns the memory

user_id is the memory owner. Take it from your authenticated user record, not from the request body and not from a session id. A new user_id is a new, empty memory. session_id only groups facts by thread, so the same user gets the same memories in a new thread.

Step 3 (optional): Compose the block yourself

If you already run your own Memory with blocks like FactExtractionMemoryBlock or VectorMemoryBlock, add the recall block next to them:

from llama_index.core.memory import Memory
from llamaindex_memorysync import MemorySyncMemoryBlock

memory = Memory.from_defaults(
    session_id="thread-42",
    memory_blocks=[
        MemorySyncMemoryBlock(user_id="customer-7"),
        # ...alongside any other blocks you already run
    ],
)

Recall renders into LlamaIndex's own memory template. Keep the flush rule in mind, though: in this setup the block only receives the user messages the buffer flushes into it. If you want every user message stored right away, use MemorySyncMemory from Step 1. The guide says a message sent on both paths is recognised server-side and extracted once.

Truncation is the other difference. LlamaIndex's docs say that when blocks plus chat history exceed token_limit, blocks are truncated in priority order, and by default a truncated block is removed entirely. The guide says MemorySyncMemoryBlock drops its lowest-value lines instead, so the top memories stay in the prompt.

Step 4 (optional): Memories as a retriever

from llama_index.core.query_engine import RetrieverQueryEngine
from llama_index.core.tools import RetrieverTool
from llamaindex_memorysync import MemorySyncRetriever

retriever = MemorySyncRetriever(user_id="customer-7", similarity_top_k=5)

nodes = retriever.retrieve("dietary preferences")  # scored nodes

engine = RetrieverQueryEngine.from_args(retriever=retriever, llm=llm)
answer = engine.query("What do we know about this customer's diet?")

tool = RetrieverTool.from_defaults(
    retriever=retriever,
    name="memory_search",
    description="Search everything known about this user.",
)

It's a standard BaseRetriever (sync and async), with the memory id and user in node metadata. similarity_top_k accepts 1 to 50. Unlike the memory classes, it raises on API failure instead of returning an empty list, so a RAG pipeline can tell "no memories" from "the service errored".

Step 5 (optional): Tools and helpers

from llama_index.core.agent.workflow import FunctionAgent
from llamaindex_memorysync import create_memorysync_tools

agent = FunctionAgent(
    tools=create_memorysync_tools(user_id="customer-7"),
    llm=llm,
    system_prompt="Use the memory tools to remember durable facts.",
)

# For agents you don't fully trust: search and list only
create_memorysync_tools(user_id="customer-7", read_only=True)

The tools are add_memory, search_memory, list_memories, update_memory (tags and importance only; memory text can't be changed) and delete_memory. They return readable error strings instead of raising.

For code outside an agent, there are sync helpers:

from llamaindex_memorysync import get_memory_context, save_turn, search_memories

context = get_memory_context("what should I cook?", user_id="customer-7")  # "" for a new user
hits = search_memories("dietary preferences", user_id="customer-7")

# Explicit persistence. This one raises on failure.
save_turn(user_id="customer-7", user="I'm vegetarian",
          assistant="Noted!", session_id="thread-42")

save_turn sends only the user message. API errors raise MemorySyncAPIError, which carries the HTTP status and server detail.

Troubleshooting

Nothing is remembered after a short chat. You're probably using a plain block inside Memory, which only sees flushed messages. Switch to MemorySyncMemory.
A new thread knows nothing. Check that user_id is identical in both runs. session_id can differ.
The memory block disappears in long chats. That's LlamaIndex's default truncation for other blocks. Check their priority values; priority=0 blocks are always kept.
Version errors. The package targets llama-index-core 0.13 to 0.14.

Sources

MemorySync LlamaIndex Memory guide: docs.memorysync.io/guides/llamaindex
LlamaIndex memory guide: developers.llamaindex.ai/python/framework/module_guides/deploying/agents/memory/
PyPI: llamaindex-memorysync 1.1.0

Try it

If you want to see the save, reload and recall loop before wiring up an agent, the MemorySync playground runs it in your browser: memorysync.io/try.

Persistent memory for CrewAI 1.x: keep crew memory across runs and redeploys

Mohammed Rafay — Fri, 23 Oct 2026 16:12:53 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and CrewAI docs. The code is adapted from the docs and I haven't run it.

CrewAI 1.x replaced its old short-term, long-term and entity memory classes with one Memory class. Turn it on with memory=True and the crew does the work for you: after each task it extracts discrete facts from the output and stores them, and before each task the agent recalls relevant context and injects it into the prompt (CrewAI memory docs).

The part that catches people is where that memory lives. By default it's LanceDB, stored under ./.crewai/memory (or $CREWAI_STORAGE_DIR/memory). That's fine on a laptop. It's a problem when:

your crew runs in a container whose filesystem is thrown away on every deploy,
two services run the same crew and should learn from each other, or
you want each of your customers to have their own memory, not one shared folder.

CrewAI's answer is a pluggable storage layer: implement the StorageBackend protocol and pass it to Memory(storage=...). This tutorial uses MemorySync's backend for that, plus the two extras the package ships: agent tools and a context helper for task descriptions.

What you'll set up

A crew whose automatic save and recall loop runs against a hosted store instead of local files.
A clear choice of who owns the memory: one crew, or one end user.
Optional: tools so an agent can decide to store or look something up itself.
Optional: a recall block you paste into a task description.

Install

pip install crewai-memorysync

Per the MemorySync CrewAI guide, it needs CrewAI 1.0+ (the unified Memory system) and Python 3.10+. On an older CrewAI the import fails with a message naming the fix. Set MEMORYSYNC_API_KEY in your environment, or pass api_key explicitly, and keep it in server-side code.

One thing that doesn't change: CrewAI still runs its own LLM analysis and its own embedder. The backend receives a query embedding from CrewAI, so whatever embedder you've configured (OpenAI's text-embedding-3-large by default, per CrewAI's docs) still needs its credentials.

Step 1: point the crew's memory at the backend

from crewai import Agent, Crew, Task
from crewai.memory import Memory
from crewai_memorysync import MemorySyncStorage

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    memory=Memory(
        storage=MemorySyncStorage(user_id="support-crew"),
    ),
)

crew.kickoff()

That's the whole change. You don't add search-and-paste steps to your tasks: CrewAI keeps driving saves and recalls, and the records now go to MemorySync. Per the guide, they survive redeploys and are shared by every service that uses the same user_id.

If you'd rather not pass the backend around, register it once at startup and refer to it by name:

from crewai.memory import Memory
from crewai_memorysync import register_memorysync

register_memorysync(user_id="support-crew")   # once, at startup

memory = Memory(storage="memorysync")          # anywhere in the process

The guide notes that unknown storage names still go to CrewAI's built-ins, so storage="lancedb" elsewhere in the same process keeps working.

Step 2: decide who owns the memory

user_id is the memory owner, and it's the most important choice in this setup:

One id per crew (like "support-crew" above) gives the crew a shared knowledge base. Everything any run learns is available to the next run, on any machine.
One id per end user gives each customer their own memory. A crew working for customer A doesn't see what it learned for customer B.

My rule of thumb: if the crew learns facts about a person, use that person's id, taken from your own authenticated user record. If it learns facts about the work (your stack, your product, your process), a crew-level id is the right shape. Don't use a session or run id here. A new id is a new, empty memory.

Step 3: check the loop end to end

You normally never call recall yourself, because agents recall as they work. But after a first run it's worth checking that something was actually stored:

matches = memory.recall("what stack does the team use?", depth="shallow")
for match in matches:
    print(match.score, match.record.content, match.record.scope)

According to the guide, scope prefixes, category and metadata filters and scores behave like the built-in LanceDB backend, and records keep their scopes (for example /agent/researcher), categories, importance and sources through a round trip. If you're debugging, attach_memory_logging logs CrewAI's memory save and query events as they happen.

Two behaviours worth knowing before production:

Replays don't double-store. CrewAI runs saves on a background executor, so replays happen. The guide says saving an identical record again stores nothing twice, and an update replaces the previous version in place.
Failures are loud. CrewAI's executor silently drops RuntimeError, so the package never raises one. Failures surface as typed errors instead of saves that quietly vanish.

Step 4 (optional): let an agent manage memory itself

The automatic loop covers most cases. When you want an agent to explicitly decide "remember this" or "look that up", give it the five tools:

from crewai import Agent
from crewai_memorysync import create_memorysync_tools

agent = Agent(
    role="Personal assistant",
    goal="Help using what you know about the user",
    backstory="You remember the user's preferences.",
    tools=create_memorysync_tools(user_id="customer-7"),
)

# For agents you don't fully trust: search and list only
read_only_tools = create_memorysync_tools(user_id="customer-7", read_only=True)

The tools are add_memory, search_memory, list_memories, update_memory and delete_memory. They never raise: errors come back as readable strings, so a tool failure can't abort a task. Memory text can't be edited, so update_memory changes tags and importance only. They're the same names and behaviour as the MemorySync LangChain tools, which helps if an agent moves between frameworks.

Step 5 (optional): put known context in a task description

For a task that should start from what you already know about a user, there's a one-line helper:

from crewai import Task
from crewai_memorysync import get_crew_context

context = get_crew_context("travel preferences", user_id="customer-7")

task = Task(
    description=f"Plan the trip.\nKnown preferences:\n{context or 'None yet.'}",
    expected_output="An itinerary honouring every stated preference.",
    agent=planner,
)

It returns an empty string for a new user. That's a normal state, not an error, so give it a fallback like the or 'None yet.' above (my addition to the guide's example).

Resetting memory without wiping everything

crew.reset_memories() can end up calling reset() with no scope, which would erase everything that user_id owns. The backend refuses that by default:

storage = MemorySyncStorage(user_id="support-crew")

storage.reset()                      # refused: raises ValueError mentioning allow_full_reset
storage.reset("/agent/researcher")   # scoped resets always work

# Opt in only when a full wipe is really intended:
MemorySyncStorage(user_id="support-crew", allow_full_reset=True).reset()

And if a delete removes nothing while matching records exist, it raises MemorySyncDeleteRefusedError instead of pretending it worked. For a crew that handles personal data, I'd want that to be loud too.

Recap

pip install crewai-memorysync and set MEMORYSYNC_API_KEY.
Memory(storage=MemorySyncStorage(user_id=...)) on your crew, or register_memorysync() once.
Pick the owner: one id per crew to share, one per end user to keep memory separate.
Check a first run with memory.recall(...).
Add tools or get_crew_context only where an agent or task needs them.

Sources

MemorySync CrewAI Memory guide: docs.memorysync.io/guides/crewai
CrewAI memory docs: docs.crewai.com/en/concepts/memory
PyPI: crewai-memorysync 1.1.0

Try it

If you want to see the save, reload and recall loop before wiring up a crew, the MemorySync playground runs it in the browser with each API call shown: memorysync.io/try.

Add long-term memory to a Vercel AI SDK chatbot (middleware, Next.js route and agent tools)

Mohammed Rafay — Thu, 22 Oct 2026 16:18:29 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and AI SDK docs. The code is adapted from the docs and I haven't run it.

The AI SDK's chatbot persistence guide shows how to save a chat: useChat sends the chat id and messages, and you store the messages when the stream ends. Load them by chat id and the conversation picks up where it left off. Start a new chat, though, and the model knows nothing about the user. A transcript belongs to one chat. Long-term memory is the facts about a user that should show up in every chat.

This post adds that second part to an AI SDK app with MemorySync's AI SDK integration, memorysync-ai-sdk. MemorySync is a hosted memory layer, and I'm building it. The AI SDK behaviour comes from the official Language Model Middleware and Chatbot Message Persistence docs. Everything about MemorySync comes from its Vercel AI SDK Memory guide. The code is adapted from those docs. I haven't run it for this post, so check it against your versions.

How it fits

The AI SDK has a middleware layer: wrapLanguageModel({ model, middleware }) returns a model that behaves like any other, but with its calls intercepted. The SDK's docs list RAG, guardrails, caching and logging as typical uses. Memory fits the same slot:

Before generation: recall memories for this user and inject them as a system context block.
After a successful finish: send the user's message for fact extraction. Only the durable facts in it are stored. Assistant replies aren't stored.

Keep your transcript persistence. The two do different jobs.

Install

npm install memorysync-ai-sdk ai

Set MEMORYSYNC_API_KEY in the environment (or pass apiKey). The guide lists ai 6.0+ as the requirement and Node 18+ for the package. Note that ai v7 itself needs Node 22+. The npm registry currently lists memorysync-ai-sdk 1.1.0 with a peer range of ai >=6.0.0 <8.0.0.

Step 1: Wrap the model once

import { generateText, wrapLanguageModel } from "ai";
import { openai } from "@ai-sdk/openai";
import { createMemorySyncMiddleware } from "memorysync-ai-sdk";

const model = wrapLanguageModel({
  model: openai("your-model"),
  middleware: createMemorySyncMiddleware({
    userId: "customer-7",   // required: scopes memory to one end user
    sessionId: "thread-42", // groups stored facts by thread
  }),
});

// First conversation
await generateText({ model, prompt: "I'm vegetarian and I fly aisle." });

// A later call for the same user
const { text } = await generateText({
  model,
  prompt: "Book my trip: flight plus a dinner spot.",
});

The second call doesn't repeat the diet or the seat. If memory works, the model has seen both in the injected context block. Two behaviours from the guide are worth knowing:

Injection happens once per user turn. On tool-loop steps where the last message is a tool result, the prompt passes through untouched.
Your own system prompt stays first. The memory block goes after it.

Step 2: A Next.js chat route

// app/api/chat/route.ts
import { convertToModelMessages, streamText, wrapLanguageModel } from "ai";
import { openai } from "@ai-sdk/openai";
import { createMemorySyncMiddleware } from "memorysync-ai-sdk";

export async function POST(req: Request) {
  const { messages, userId, sessionId } = await req.json();

  const model = wrapLanguageModel({
    model: openai("your-model"),
    middleware: createMemorySyncMiddleware({ userId, sessionId }),
  });

  const result = streamText({
    model,
    messages: await convertToModelMessages(messages),
  });
  return result.toUIMessageStreamResponse();
}

Two notes on this:

The MemorySync guide calls convertToModelMessages(messages) without await. The current AI SDK persistence docs await it, so I've added that here. Check which one your ai version expects.
The guide reads userId from the request body to keep the example short. In a real app, take it from your auth session instead. Whoever controls userId controls whose memory gets read.

On streaming, the guide says the user's message is sent once, after the stream's finish part. A stream that errors or is aborted never reaches its finish, so nothing is sent for it.

Step 3: Read-only, write-only and tuning

// Recall context, never write
createMemorySyncMiddleware({ userId, persist: false });

// Send user messages for extraction, inject nothing
createMemorySyncMiddleware({ userId, recall: false });

// Recall depth and the shape of the injected block
createMemorySyncMiddleware({
  userId,
  k: 12,
  template: "What you know about this user:\n{context}",
});

Read-only is handy for an internal admin view or an eval run where you don't want test prompts stored.

Step 4: If you don't want to wrap the model

The same recall and persistence are available as helpers:

import {
  createMemorySyncOnFinish,
  getMemoryContext,
  saveTurn,
  searchMemories,
} from "memorysync-ai-sdk";

// Prompt-ready context block ("" for a new user)
const context = await getMemoryContext("what should I cook?", { userId: "customer-7" });

// Scored raw results: [{ id, text, score }, ...]
const hits = await searchMemories("dietary preferences", { userId: "customer-7" });

// Explicit persistence. This one throws on failure.
await saveTurn(
  { user: "I'm vegetarian", assistant: "Noted!", sessionId: "thread-42" },
  { userId: "customer-7" },
);

// Or persist from onFinish, which fires once after the full tool loop
const result = streamText({
  model,
  prompt,
  onFinish: createMemorySyncOnFinish({ userId: "customer-7", user: prompt }),
});

Watch the error behaviour, because it differs. The middleware reports persistence failures through onError (by default, a console warning) and never throws, and a failed recall just means the call runs without context. saveTurn throws. The guide says mixing styles is safe: a turn sent by both the middleware and saveTurn is recognised server-side and extracted once.

Step 5: Give an agent memory tools

If you want the model to decide when to save or look something up, add the five tools:

import { generateText, isStepCount } from "ai"; // AI SDK 6: stepCountIs
import { openai } from "@ai-sdk/openai";
import { memorySyncTools } from "memorysync-ai-sdk";

const { text } = await generateText({
  model: openai("your-model"),
  tools: { ...memorySyncTools({ userId: "customer-7" }) },
  stopWhen: isStepCount(5), // AI SDK 6: stepCountIs(5)
  prompt: "Remember that I prefer aisle seats.",
});

// For agents you don't fully trust: search and list only
memorySyncTools({ userId: "customer-7", readOnly: true });

The MemorySync guide uses stepCountIs. AI SDK 7's migration guide renames it to isStepCount, so I've used the new name with the old one in a comment.

The tools are addMemory, searchMemory, listMemories, updateMemory (tags and importance only; memory text can't be changed) and deleteMemory. They return readable error strings instead of throwing, so a memory failure doesn't abort the tool loop.

Step 6: See which memories were used

const result = await generateText({ model, prompt });
const memories = result.providerMetadata?.memorysync?.memories;
// [{ id, text, score }, ...]

// Streaming: the same field on the awaited stream result
const streamed = streamText({ model, prompt });
const meta = (await streamed.providerMetadata)?.memorysync;

This is useful for a "why did it say that" panel, or for logging recalls in evals. One version note: in the current AI SDK reference, providerMetadata on the streamText result is marked deprecated in favour of finalStep.providerMetadata, and onFinish is a deprecated alias for onEnd. The snippets above follow the MemorySync guide, so check both names against your ai version.

Troubleshooting

The second chat doesn't know anything. Check that userId is the same value in both requests. Then check that the first request finished. An aborted stream sends nothing.
TypeScript complains on AI SDK 6. Pass specificationVersion: "v3" to the middleware for exact types. The guide says behaviour is the same either way.
Duplicate context in multi-step agents. It shouldn't happen: injection is skipped on tool-result steps. If you also call getMemoryContext yourself, you're adding a second block.

Try it

If you want to see the save, reload and recall loop before adding a package, the MemorySync playground runs it in your browser: memorysync.io/try.

Persistent memory for Claude Code across sessions and compaction (hooks + an MCP memory server)

Mohammed Rafay — Thu, 22 Oct 2026 16:17:43 +0000

Disclosure: I'm Mohammed, founder of MemorySync. I drafted this article with AI assistance and reviewed it for accuracy against the official MemorySync and Claude Code docs. The code is adapted from the docs and I haven't run it.

Claude Code starts every session with a fresh context window, and when a long session fills up, compaction summarizes the conversation to free space. Claude Code's own docs say that summary "can lose important details". So the two problems (a new session and a compact) are really one question: how do I get the important stuff back at the start of a session, and again after a compact?

This post walks through the layers, from the built-in ones to a hooks-based memory layer:

What CLAUDE.md and auto memory already give you.
A SessionStart hook that re-injects context after compaction (no extra service).
The MemorySync plugin, which uses the same hooks to recall from a hosted memory layer, plus the hosted MemorySync MCP server.

The Claude Code behaviour comes from the official memory, hooks reference and hooks guide pages. Everything about MemorySync comes from its Claude Code Memory guide. The commands and config are adapted from those docs. I haven't run them for this post, so check them against your Claude Code version.

1. What's built in

Claude Code has two ways to carry knowledge across sessions:

	CLAUDE.md	Auto memory
Who writes it	You	Claude, based on your corrections and preferences
What it's for	Instructions and rules: build commands, conventions, "always do X"	Learnings Claude decides are worth keeping
Loaded	Every session	Every session (first 200 lines or 25KB)

Start here. Put your build and test commands and project conventions in ./CLAUDE.md (or ./.claude/CLAUDE.md), keep it under about 200 lines as the docs suggest, and run /context to confirm it shows up under Memory files.

What these files don't give you, in my view, is a searchable store of facts that's scoped per project and follows you into other tools. That's the gap the next two layers fill.

2. Re-inject context after compaction with a hook

Hooks are commands Claude Code runs at fixed points in a session. The one that matters here is SessionStart, and its matcher says how the session began:

Matcher	Fires on
`startup`	A new session
`resume`	`--resume`, `--continue` or `/resume`
`clear`	`/clear`
`compact`	Auto or manual compaction
`fork`	A session forked from an existing one

For SessionStart, Claude Code adds the plain text your command prints to stdout into Claude's context. That gives you a simple fix for compaction. This is the example from the hooks guide, in .claude/settings.json:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Swap the echo for anything that prints useful state, such as git log --oneline -5. Three limits from the reference are worth knowing:

Hook output (additionalContext or plain stdout) is capped at 10,000 characters.
SessionStart runs on every session, so keep it fast.
At launch, SessionStart fires before the session's MCP servers are available, so mcp_tool hooks are skipped then. Use a type: "command" hook for anything the session needs at startup.

This works well for static reminders. It doesn't learn anything new on its own, though. Whatever you echo is whatever you wrote last.

3. A memory layer on the same hooks: the MemorySync plugin

MemorySync is a hosted memory layer, and I'm building it. Its Claude Code plugin wires the same lifecycle points to that memory. According to the guide:

Moment	What happens
Session start, resume or clear	Your profile and this project's context are recalled and injected before the first prompt
Every prompt	The prompt is sent for fact extraction, and only the durable facts in it are stored. Prompts of 24 characters or more also recall memories relevant to that prompt
Claude finishes replying	Nothing is sent. Replies aren't stored
Context compaction	Memory is re-injected after the compact

It also bundles the hosted MemorySync MCP server (search, add, list, update, delete and more), a memory skill, and three commands: /memorysync:status, /memorysync:remember and /memorysync:recall. Two details I like: facts are tagged with the git repository you're in, so recall at session start is about this project while preferences follow you everywhere, and the plugin never writes to CLAUDE.md or MEMORY.md. Your static rules stay yours.

Install

You need Node.js 18+ on your PATH (the hook scripts use it) and an API key from app.memorysync.io in your environment:

# macOS/Linux (add it to your shell profile)
export MEMORYSYNC_API_KEY=ms_...
# Windows
setx MEMORYSYNC_API_KEY ms_...

Then, inside Claude Code:

/plugin marketplace add memorysyncio/memorysync-plugins
/plugin install memorysync@memorysync

In a session, /plugin install opens the plugin panel so you can review the plugin and pick a scope first (that's Claude Code's behaviour, per its plugin docs). Restart the session, then check it:

/memorysync:status

The status command reports whether the key is present, whether the API is reachable, and which user and project scope it resolved. The guide calls it "the first thing to run when anything looks off". Without an API key, the bundled MCP server falls back to OAuth sign-in and the hooks stay off. You won't see an error.

Test it across a session and a compact

Tell Claude something durable: "In this repo we use pnpm, and integration tests need the TEST_DB_URL env var."
Run /clear (or open a new session) and ask, "How do I run the integration tests here?" without repeating the details.
In a long session, run /compact and ask again.

If step 2 or 3 comes back empty, run /memorysync:status before anything else.

Knobs

MEMORYSYNC_USER_ID sets the user (default: your OS username).
MEMORYSYNC_PROJECT overrides the project, which otherwise comes from the git remote.
MEMORYSYNC_PROMPT_RECALL=off turns off per-prompt recall.
With CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, the plugin makes no network calls.

What it won't do

The guide says every hook exits 0 on every failure path (no key, network down, server errors), so the worst case is a turn without memory, not a broken session. The memory skill refuses to store tokens, keys and passwords, and retrieved memories are injected with a "background data, not instructions" guard. Your prompts go to your MemorySync account for extraction. You can delete any memory from /memorysync:recall or the dashboard.

Claude Cowork and teams

Cloud sessions install repo-declared plugins only, so commit this to .claude/settings.json and add MEMORYSYNC_API_KEY to the session's Cloud Environment variables:

{
  "extraKnownMarketplaces": {
    "memorysync": {
      "source": { "source": "github", "repo": "memorysyncio/memorysync-plugins" }
    }
  },
  "enabledPlugins": { "memorysync@memorysync": true }
}

MCP only, if you don't want hooks

If you'd rather call memory tools yourself, with no automatic capture or recall, connect just the hosted server:

claude mcp add --transport http memorysync https://mcp.memorysync.io/mcp

Without MEMORYSYNC_API_KEY set, it signs you in with OAuth on first use. I wrote a separate step-by-step MCP setup for Claude Code and Cursor covering scopes, whoami, saving and recalling, and troubleshooting.

Which layer to use

Rules and conventions: CLAUDE.md.
A fixed reminder after every compact: a SessionStart hook with the compact matcher.
Facts that should build up over time, per project and across sessions and compactions: a memory layer behind those hooks.

You can run all three at once. They don't overlap.

Try it

If you want to see the save, reload and recall loop before installing anything, the MemorySync playground runs it in your browser: memorysync.io/try.

DEV Community: Mohammed Rafay

Fix "ModuleNotFoundError: No module named 'agno.memory.v2'" (Agno v1 v2+ memory migration)

The error

Why it happens

The fix: before and after

If you want memories outside the local database

Common questions

Sources

Strands Agents memory: how to add long-term memory to a Strands agent (MemoryManager, stores and per-user recall)

How Strands memory works

Step 1: Prototype with the local test store

Step 2: Swap in a per-user hosted store

Step 3: Fix the "first few turns are forgotten" surprise

Step 4: Pick a stable user_id

Optional: explicit memory tools

Useful knobs

Common questions

Sources

How to add memory to a Google ADK agent that survives restarts (MemoryService, preload_memory, per-user recall)

What ADK gives you

Plugging in a third-party MemoryService

Step 1: Wire the service into the Runner

Step 2: Ingest the session when a conversation ends

Step 3 (alternative): Inject and capture every turn

Optional: memory tools for the model

Common questions

Sources

Fix "'ClusterPipeline' object has no attribute 'raise_first_error'" with OpenAI Agents SDK RedisSession on Redis Cluster

The error

Why it happens

Fix options

A note on what a session is (and isn't)

Common questions

Sources

Add long-term memory to a Microsoft Agent Framework agent (one context provider, per-user recall across sessions)

What you'll set up

How Agent Framework thinks about memory

Install

Step 1: Create the provider

Step 2: Attach it to the agent

Step 3: Keep the thread and the user separate

Step 4: One agent, many users

Step 5 (optional): Memory tools and read-only runs

Coming from AutoGen: what changes

Troubleshooting

Sources

Try it

MCP memory server lost your memories? Fixing MEMORY_FILE_PATH and the npx cache

Why it happens

Step 1: Find where your memory actually is

Step 2: Use an absolute path and the current version

Step 3: Check that it worked

Step 4: Bring the old memory back

Step 5: Two more fixes from the docs and the thread

When a hosted memory server is the simpler answer

Troubleshooting

Sources

Try it

Add long-term memory to a Mastra agent (input/output processors, per-user recall)

What you'll set up

Install

Step 1: Add the processors

Step 2: Resolve the user per call

Step 3: Streaming

Step 4 (optional): Recall modes and switches

Step 5 (optional): Tools and helpers

Troubleshooting

Common questions

Sources

Try it

Add long-term memory to a Pydantic AI agent (one capability, per-user recall across runs)

What you'll set up

Install

Step 1: Add the capability

Step 2: Take the user from your deps

Step 3 (optional): Memory tools

Step 4 (optional): Typed search and helpers

Troubleshooting

Common questions

Sources

Step 4: Pick a stable `user_id`