---
id: graph-retriever
version: "0.8.0"
license: Apache-2.0
license_treatment: permissive
maintenance: aging
---

# graph-retriever — Retriever combining unstructured similarity and structured document traversal.

License: permissive · Maintenance: aging · Downloads: 187.1K/mo

## What it is and what it does

Graph Retriever is a Python library that extends vector stores with graph-based retrieval capabilities. It wraps existing vector stores to enable traversal of metadata relationships—such as following mentions or entity links—alongside traditional similarity search. This hybrid approach lets you retrieve documents based on both semantic similarity and structured connections in your metadata.

The library is designed for Retrieval-Augmented Generation (RAG) applications where you want to combine the strengths of vector search (finding semantically similar content) with graph traversal (following explicit relationships between documents). It supports Python 3.10 and later and depends on immutabledict, numpy, pytest, and typing-extensions. A separate LangChain integration package is available for applications already using LangChain.

Use it for:

- Retrieve documents by following entity mentions and relationships in knowledge graphs alongside semantic similarity.
- Build RAG systems that navigate document metadata hierarchies to surface contextually related content.
- Combine vector search with structured metadata properties to refine retrieval results in domain-specific applications.
- Extend existing vector stores with graph traversal without replacing the underlying store infrastructure.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Combines vector similarity search with graph traversal over metadata to retrieve documents from existing vector stores, enabling both unstructured and structured retrieval in a single query.

Yes, if you need hybrid retrieval combining vector similarity with metadata graph traversal. The low install friction, permissive license, and active repository make it a reasonable choice for RAG applications. However, the package is in Beta with limited recent activity (last release April 2025), so verify that your vector store is supported and test thoroughly before production use.

## Install

pip install graph-retriever
uv add graph-retriever
poetry add graph-retriever

## Installing graph-retriever

Before you install: Low friction installation with a small, stable dependency footprint: immutabledict, numpy, pytest, and typing-extensions. The package is in Beta status and has not released since April 2025, so maintenance activity is limited but the repository remains active.

License in practice: Apache-2.0 permissive license allows commercial and private use with minimal restrictions; you must include a copy of the license and state significant changes, but no reciprocal licensing is required.

Quickstart:

pip install graph-retriever

from graph_retriever import GraphRetriever

retriever = GraphRetriever(
    store=your_vector_store,
    edges=[("mentions", "id"), "entities"]
)
results = retriever.invoke("your query")

Requires Python 3.10 or later; you must have an existing vector store instance to wrap.

Verify before relying:

- Which vector store implementations are currently supported beyond the examples shown in the description.
- Whether the package works with vector stores outside the LangChain ecosystem.
- Performance characteristics and scalability limits for large graphs or high-cardinality metadata.

## Package facts

- License: Apache-2.0 (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 187.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

graph RAG retrieval, vector store metadata traversal, hybrid similarity and graph search, structured document retrieval, RAG with relationship navigation, vector search with metadata edges, rag, graph-traversal, vector-retrieval

[View on SkillFed](https://skillfed.io/packages/graph-retriever) · [View on PyPI](https://pypi.org/project/graph-retriever/)