Metadata-Version: 2.4
Name: mandol
Version: 0.1.0
Summary: Agent memory system with hierarchical, episodic, and entity-relation retrieval.
Author: Mandol Team
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/AgentCombo/Mandol
Project-URL: Repository, https://github.com/AgentCombo/Mandol
Project-URL: Issues, https://github.com/AgentCombo/Mandol/issues
Project-URL: Documentation, https://agentcombo.github.io/Mandol/docs
Project-URL: Paper, https://arxiv.org/abs/2606.29778
Project-URL: PyPI, https://pypi.org/project/mandol/
Project-URL: Changelog, https://github.com/AgentCombo/Mandol/releases/tag/v0.1.0
Keywords: memory,agent,rag,retrieval,llm,knowledge-graph
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: <3.13,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<2.0,>=1.26
Requires-Dist: numba<0.62,>=0.60
Requires-Dist: scipy>=1.13
Requires-Dist: pandas>=2.1
Requires-Dist: pyarrow>=15
Requires-Dist: openpyxl>=3.1
Requires-Dist: orjson>=3.10
Requires-Dist: tqdm>=4.66
Requires-Dist: colorlog>=6.8
Requires-Dist: requests>=2.32
Requires-Dist: httpx[socks]>=0.27
Requires-Dist: pydantic<3.0,>=2.9
Requires-Dist: pydantic-settings<3.0,>=2.6
Requires-Dist: fastapi<1.0,>=0.115
Requires-Dist: uvicorn[standard]<1.0,>=0.30
Requires-Dist: networkx>=3.2
Requires-Dist: rustworkx>=0.15
Requires-Dist: igraph>=0.11
Requires-Dist: leidenalg>=0.10
Requires-Dist: rocksdict==0.3.29
Requires-Dist: faiss-cpu>=1.8
Requires-Dist: torch==2.8.0
Requires-Dist: torchvision==0.23.0
Requires-Dist: torchaudio==2.8.0
Requires-Dist: transformers<5.0,>=4.40
Requires-Dist: sentence-transformers<6.0,>=5.2
Requires-Dist: safetensors>=0.4
Requires-Dist: pillow>=10.0
Requires-Dist: huggingface_hub[cli]>=0.23.0
Requires-Dist: openai>=1.40
Requires-Dist: tenacity>=9.1
Requires-Dist: tiktoken>=0.7
Requires-Dist: dashscope>=1.20
Requires-Dist: nltk>=3.9
Requires-Dist: regex>=2023.12
Requires-Dist: jieba>=0.42
Requires-Dist: json-repair>=0.30
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: scikit-learn>=1.4
Requires-Dist: spacy==3.8.14
Requires-Dist: langchain>=0.3
Requires-Dist: langchain-text-splitters>=0.3
Requires-Dist: bert-score>=0.3.13
Requires-Dist: rouge>=1.0.1
Requires-Dist: rouge-score>=0.1.2
Requires-Dist: tabulate>=0.9
Requires-Dist: python-dotenv>=1.0
Requires-Dist: gdown>=5.2
Requires-Dist: zep-cloud>=2.22
Requires-Dist: pymilvus>=2.5
Requires-Dist: neo4j>=5.20
Requires-Dist: python-pptx>=1.0
Requires-Dist: llmlingua>=0.2.2
Provides-Extra: cuda
Requires-Dist: flash-attn==2.8.3; extra == "cuda"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: datasets>=2.20; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: matplotlib>=3.8; extra == "dev"
Requires-Dist: pre-commit>=4.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Requires-Dist: sphinxcontrib-mermaid; extra == "docs"
Requires-Dist: sphinx-autobuild; extra == "docs"
Dynamic: license-file

# Mandol

Mandol is an agent memory system with hierarchical, episodic, and
entity-relation retrieval over a unified semantic graph.

[English](https://github.com/AgentCombo/Mandol/blob/v0.1.0/README.md) |
[中文](https://github.com/AgentCombo/Mandol/blob/v0.1.0/README_CN.md)

![Mandol Overview](https://raw.githubusercontent.com/AgentCombo/Mandol/v0.1.0/README.assets/Mandol-overview-v2.png)

## Installation

Mandol 0.1.0 requires Python `>=3.12,<3.13` and currently targets Linux.

```bash
python -m pip install mandol
```

Use an explicit pin for a reproducible package environment:

```bash
python -m pip install "mandol==0.1.0"
```

## Package Scope

The package provides:

- `MemoryUnit`, `MemorySpace`, `SemanticMap`, and `SemanticGraph` core APIs;
- dense, BM25, SPLADE, graph-expansion, fusion, and reranking paths;
- hierarchical, entity-relation, and episodic triple-tower retrieval;
- query routing, semantic quantification, and high-level memory builders; and
- RocksDB-backed automatic tiered paging for cold `MemoryUnit` payloads.

The package does not include benchmark datasets, generated graphs, model
caches, or provider credentials. Models may be downloaded on first use, and
complete benchmark reproduction requires external model services.

## Quick Start

The following example uses a compact sentence-transformers model and disables
realtime SPLADE generation. The embedding model may be downloaded on first use.

```python
from mandol import MemoryUnit, SemanticGraph, SemanticMap

semantic_map = SemanticMap(
    embedding_model_name="all-MiniLM-L6-v2",
    use_flash_attention=False,
)
graph = SemanticGraph(semantic_map_instance=semantic_map)

graph.add_unit(
    MemoryUnit(
        uid="msg_001",
        raw_data={"text_content": "Zhang San travelled to Beijing today."},
        metadata={"timestamp": "2026-06-21T09:00:00"},
    ),
    space_names=["demo"],
    generate_sparse_embedding=False,
)

results = graph.search_similarity_in_graph(
    query_text="Where did Zhang San go?",
    top_k=3,
    ms_names=["demo"],
    return_score=True,
)

for unit, score in results:
    print(score, unit.uid, unit.text_cached)
```

## Paper Reproduction

The published LoCoMo, LongMemEval, and performance results were produced with
the frozen [paper-repro artifact](https://github.com/AgentCombo/Mandol/tree/paper-repro),
not from the package alone. Follow the benchmark-specific guides in that branch
for datasets, model roles, configurations, and commands.

Mandol 0.1.0 is a research artifact and early public release. It is not a
production-ready service, and APIs may evolve during the `0.x` series.

## Links

- [Repository](https://github.com/AgentCombo/Mandol/tree/v0.1.0)
- [Documentation](https://agentcombo.github.io/Mandol/docs)
- [Paper](https://arxiv.org/abs/2606.29778)
- [Issues](https://github.com/AgentCombo/Mandol/issues)
- [Release notes](https://github.com/AgentCombo/Mandol/blob/v0.1.0/release-notes/v0.1.0.md)

## Citation

```bibtex
@misc{zhang2026mandol,
  title={Mandol: An Agglomerative Agent Memory System for Long-Term Conversations},
  author={Yuhan Zhang and Zhiyuan Guo and Ziheng Zeng and Wei Wang and Wentao Wu and Lijie Xu},
  year={2026},
  eprint={2606.29778},
  archivePrefix={arXiv},
  primaryClass={cs.DB},
  doi={10.48550/arXiv.2606.29778},
  url={https://arxiv.org/abs/2606.29778}
}
```

Mandol is distributed under the [Apache License 2.0](https://github.com/AgentCombo/Mandol/blob/v0.1.0/LICENSE).
