Metadata-Version: 2.5
Name: llamaindex-memorysync
Version: 1.0.0
Summary: MemorySync memory for LlamaIndex: a Memory subclass with durable server-side long-term memory, a recall memory block, a retriever, and agent memory tools.
Project-URL: Homepage, https://memorysync.io
Project-URL: Documentation, https://docs.memorysync.io/guides/llamaindex
Project-URL: API Reference, https://docs.memorysync.io/api/overview
Project-URL: Changelog, https://docs.memorysync.io/release-notes
Project-URL: Support, https://docs.memorysync.io/debugging/support
Project-URL: Status, https://status.memorysync.io
Author: MemorySync
License: MIT
Keywords: agent-memory,ai,llama-index,llamaindex,llm,long-term-memory,memory,memory-block,memorysync,rag,retriever
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx<1.0,>=0.25
Requires-Dist: llama-index-core<0.15,>=0.13
Requires-Dist: memorysync>=1.9
Description-Content-Type: text/markdown

# llamaindex-memorysync

Long-term memory for [LlamaIndex](https://www.llamaindex.ai), backed by [MemorySync](https://memorysync.io) — 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`.

```bash
pip install llamaindex-memorysync
```

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

## The upgraded Memory

```python
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

```python
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

```python
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

```python
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

```python
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

| Package | Requires | Runtime |
| --- | --- | --- |
| `llamaindex-memorysync` 1.0.0 | `llama-index-core` >=0.13 <0.15 | Python 3.10+ |

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](https://docs.memorysync.io/guides/llamaindex)
- [MemorySync docs](https://docs.memorysync.io)
- [Get an API key](https://app.memorysync.io)
