Metadata-Version: 2.4
Name: langchain-memoryrouter
Version: 0.1.1
Summary: Persistent user memory for LangChain and LangGraph agents, backed by MemoryRouter
Keywords: ai,agent-memory,langchain,langgraph,long-term-memory,memoryrouter,persistent-memory
Author: MemoryRouter
Author-email: MemoryRouter <hello@memoryrouter.ai>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
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 :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.25
Requires-Dist: langchain-core>=0.3.0
Requires-Dist: langgraph>=0.2.0
Requires-Dist: pytest>=8 ; extra == 'test'
Requires-Dist: pytest-asyncio>=0.23 ; extra == 'test'
Requires-Dist: respx>=0.21 ; extra == 'test'
Requires-Dist: ruff>=0.8 ; extra == 'test'
Requires-Dist: mypy>=1.10 ; extra == 'test'
Maintainer: John Rood
Maintainer-email: John Rood <hello@memoryrouter.ai>
Requires-Python: >=3.9
Project-URL: API reference, https://docs.memoryrouter.ai/api-reference
Project-URL: Company, https://www.linkedin.com/company/memoryrouter/
Project-URL: Documentation, https://docs.memoryrouter.ai
Project-URL: Get a Memory Key, https://app.memoryrouter.ai
Project-URL: Homepage, https://memoryrouter.ai
Project-URL: Public SDK repository, https://github.com/John-Rood/memoryrouter-sdk
Project-URL: Security, https://memoryrouter.ai/security
Provides-Extra: test
Description-Content-Type: text/markdown

# langchain-memoryrouter

Persistent, user-scoped memory for LangChain and LangGraph agents, backed by [MemoryRouter](https://memoryrouter.ai).

MemoryRouter gives each user in an AI product a private memory vault. This package connects that memory layer to LangChain through tools, LangGraph nodes, and a `BaseStore` implementation.

- [Documentation](https://docs.memoryrouter.ai)
- [API reference](https://docs.memoryrouter.ai/api-reference)
- [Get a Memory Key](https://app.memoryrouter.ai)
- [Security](https://memoryrouter.ai/security)
- [Public SDK repository](https://github.com/John-Rood/memoryrouter-sdk)

## Install

```bash
pip install langchain-memoryrouter
```

Python 3.9–3.13 is supported. The package requires `langchain-core>=0.3.0`, `langgraph>=0.2.0`, and `httpx>=0.25`.

Create a Memory Key at [app.memoryrouter.ai](https://app.memoryrouter.ai). In multi-user products, map each app user to a separate Memory Key so each user has a separate vault.

## Choose an integration pattern

| Pattern | Best for | Memory behavior |
| --- | --- | --- |
| Tools | Agents that should decide when to retain or recall | The model calls `memoryrouter_retain` or `memoryrouter_recall` |
| LangGraph nodes | Automatic memory on graph turns | Your graph runs recall/retain nodes directly |
| `MemoryRouterStore` | LangGraph code that expects a `BaseStore` | Semantic retain/search rather than literal key-value storage |

## Pattern 1: tools

Works with LangChain `bind_tools()` and LangGraph `create_react_agent()`.

```python
from langchain_memoryrouter import create_memory_tools

retain, recall = create_memory_tools(memory_key="mk_user_123")
model_with_tools = model.bind_tools([retain, recall])
```

The package exposes two tool primitives:

- `memoryrouter_retain` stores sanitized conversation text with `/v1/memory/ingest`
- `memoryrouter_recall` searches memory with `/v1/memory/search`

MemoryRouter is retain and recall; this package does not add a separate `reflect` tool.

## Pattern 2: LangGraph nodes

Use nodes when you want memory to run automatically in the graph.

```python
from langchain_memoryrouter import create_recall_node, create_retain_node

recall_node = create_recall_node(memory_key_config_key="memory_key")
retain_node = create_retain_node(memory_key_config_key="memory_key")

result = graph.invoke(
    {"messages": messages},
    config={"configurable": {"memory_key": "mk_user_123", "thread_id": "chat_abc"}},
)
```

`create_recall_node` calls `/v1/memory/prepare` and returns a ready-to-inject memory context block. `create_retain_node` sanitizes conversation messages before calling `/v1/memory/ingest`.

## Pattern 3: BaseStore

Use `MemoryRouterStore` when a LangGraph integration expects a LangChain `BaseStore`.

```python
from langchain_memoryrouter import MemoryRouterStore

store = MemoryRouterStore(memory_key="mk_user_123")
graph = builder.compile(store=store)
```

MemoryRouter is semantic memory, not a literal key-value database. `mset` retains text into the user's vault. `mget` searches by key and returns the best matching memory content. The public MemoryRouter API does not expose arbitrary LangChain store-key listing or deletion, so `yield_keys` returns an empty iterator and `mdelete` is a documented no-op.

## Storage hygiene

Every write path sanitizes messages before ingest. The integration stores conversation text only:

- Keeps `HumanMessage` text as `user`
- Keeps `AIMessage` text as `assistant`
- Drops `SystemMessage` and `ToolMessage` content
- Drops tool calls, tool-call IDs, and function-call arguments
- Drops AI messages that contain only tool calls and no text

This behavior is enforced in tools, nodes, and store writes; it is not a configuration option.

Never commit a Memory Key, paste one into an issue, or share private memory content in a support request. See the [MemoryRouter security page](https://memoryrouter.ai/security) and this package's [SECURITY.md](SECURITY.md).

## API targeted

Base URL: `https://api.memoryrouter.ai`

Auth: `Authorization: Bearer mk_xxx`

Retain:

```http
POST /v1/memory/ingest
{
  "messages": [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}],
  "session_id": "optional",
  "model": "optional",
  "embeddings": "optional"
}
```

Recall:

```http
POST /v1/memory/search
{"query": "what does the user prefer", "limit": 10}
```

Graph recall context:

```http
POST /v1/memory/prepare
{
  "messages": [{"role": "user", "content": "..."}],
  "session_id": "optional",
  "density": "default",
  "context_limit": 10
}
```

For the current API surface, use the live [API reference](https://docs.memoryrouter.ai/api-reference).

## Support and package history

- Product and account help: [hello@memoryrouter.ai](mailto:hello@memoryrouter.ai)
- Package changes: [CHANGELOG.md](CHANGELOG.md)
- Security reporting: [SECURITY.md](SECURITY.md)
- MemoryRouter company profile: [LinkedIn](https://www.linkedin.com/company/memoryrouter/)

The package is maintained by MemoryRouter and available under the MIT License.
