llamaindex-memorysync

Long-term memory for LlamaIndex, backed by MemorySync — a Memory subclass that persists every turn the moment it happens, native memory-block recall, a genuine retriever for RAG, and agent memory tools.

• MemorySyncMemory — LlamaIndex's Memory with durable server-side long-term memory for agent.run(..., memory=...).
• MemorySyncMemoryBlock — the recall/persist block alone, for composing into your own Memory.
• MemorySyncRetriever — memories as a genuine BaseRetriever for query engines and retriever tools.
• Five agent tools + sync helpers — add/search/list/update/delete tools that never raise; get_memory_context, search_memories, save_turn.

pip install llamaindex-memorysync

Set MEMORYSYNC_API_KEY in the environment (create a key at app.memorysync.io), or pass api_key explicitly. Requires llama-index-core >=0.13 <0.15, Python 3.10+.

The upgraded Memory

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

memory = MemorySyncMemory.from_defaults(
    user_id="customer-7",     # per-end-user scoping — required
    session_id="thread-42",   # groups the stored transcript
)

agent = FunctionAgent(tools=[...], llm=llm)

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

# Any later run — same user, any thread, any deploy
response = await agent.run("Book my trip.", memory=memory)
# The model already saw: vegetarian, aisle seat — injected from memory.

The waterfall trap, fixed. LlamaIndex memory blocks only receive messages when the short-term buffer overflows its token budget (~21k tokens on the defaults) — so a block-only integration silently stores NOTHING for most real conversations. MemorySyncMemory persists every user/assistant message the moment it is aput; the flush path still works and converges on the same stored rows via shared idempotency seeds.

Everything Memory does still works — token_limit, insert_method, your own additional blocks — because this IS a Memory, not a wrapper. from_defaults works, async-native end to end, and serialization never leaks the API key. Only user/assistant text reaches long-term memory; system prompts and tool traffic stay in the short-term buffer. Memory failures never break the turn: the buffer write happens first, the MemorySync write degrades through on_error.

Or compose the block

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")],
)

Recall renders into the framework's own <memory> template with query/profile/full modes. Under token pressure, atruncate drops the lowest-value lines — the framework default deletes the whole block.

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")

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

Raises on API failure rather than returning an empty list — "no memories" and "the memory service errored" must never look identical to a RAG pipeline.

Agent tools

from llamaindex_memorysync import create_memorysync_tools

agent = FunctionAgent(
    tools=create_memorysync_tools(user_id="customer-7"),
    llm=llm,
)

# Untrusted agents: search + list only.
create_memorysync_tools(user_id="customer-7", read_only=True)

Same five operations, same response strings as the MemorySync LangChain, AI SDK, CrewAI, Mastra and OpenAI Agents tool sets.

Helpers

from llamaindex_memorysync import get_memory_context, save_turn, search_memories

context = get_memory_context("what should I cook?", user_id="customer-7")
hits = search_memories("dietary preferences", user_id="customer-7")
save_turn(user_id="customer-7", user="I'm vegetarian", assistant="Noted!")

All surfaces share the same idempotency seeds, so mixing styles cannot double-store a turn. save_turn raises on failure.

Version support

CI exercises the real memory machinery — waterfall flush, block template, RetrieverQueryEngine — against the latest core release within the supported range on every push.

Documentation

• LlamaIndex Memory guide
• MemorySync docs
• Get an API key