M-flow

// Overview

M-flow is a retrieval engine built on the argument that similarity and relevance are not the same thing. In most RAG systems the ranking is done by vector distance and any graph structure is supporting scaffolding — it organises, summarises or expands context but rarely decides the score. M-flow inverts that: vector search is only used to cast a wide net for entry points, and the graph then takes over, propagating evidence along typed, semantically weighted edges and scoring each knowledge unit by the strongest chain of reasoning that connects it to the query.

Knowledge is stored in a four-layer cone graph — Episode, Facet, FacetPoint, Entity — and a query anchors on whichever layer matches its granularity: a precise cue lands on a fine-grained FacetPoint, a broader theme on a Facet or an Episode summary. Propagation then routes up through the graph, and each result comes back as a bundle: one Episode, scored by its strongest evidence path, with the surrounding context that explains the answer rather than the chunk that merely resembles the question. The project frames this as a cognitive memory system, and publishes an agent skill alongside the library.

It ships as a full stack rather than a library alone. The Python package exposes an async API and an `mflow` CLI, with FastAPI routers for add, memorize and search, pluggable graph, vector and cache adapters, a Next.js web console, an MCP server for agent access, and distributed execution helpers. The repository is Apache-2.0, targets Python 3.10 to 3.13, and reports 963 passing tests.

// What it does

• Graph-as-scoring-engine retrieval: evidence propagates along typed, semantically weighted edges and ranks by the strongest reasoning path
• Four-layer cone graph (Episode → Facet → FacetPoint → Entity) so a query anchors at the granularity it was asked at
• Results returned as Episode bundles with surrounding context, not isolated chunks
• Ingestion across 50+ formats through an extract → memorize → load → search pipeline
• Pluggable adapters for graph, vector and cache backends behind one API
• Ships a CLI, FastAPI routers, a Next.js web console and an MCP server for agent access

// Getting started

M-flow can be installed as a Python package or brought up as a full stack with its quickstart script. Either way you need an LLM API key in the environment.

pip install mflow-ai         # or: uv pip install mflow-ai
export LLM_API_KEY="sk-..."

git clone https://github.com/FlowElement-xinliuyuansu/m_flow.git && cd m_flow
./quickstart.sh

import asyncio
import m_flow


async def main():
    await m_flow.add("M-flow builds persistent memory for AI agents.")
    await m_flow.memorize()

    # query() defaults to episodic graph-routed Bundle Search.
    results = await m_flow.query("How does M-flow work?")
    for item in results.context:
        print(item)


asyncio.run(main())

mflow add "M-flow builds persistent memory for AI agents."
mflow memorize
mflow search "How does M-flow work?" --query-type EPISODIC
mflow -ui          # Launch the local web console

Commands and code are distilled from the project's own documentation — always check the official repo for the latest.

// When to use it

• Reach for it when chunk-similarity retrieval keeps surfacing documents that share vocabulary with the question but not the answer
• Reach for it when answers depend on connecting several pieces of evidence rather than finding one passage
• Reach for it to give an agent long-running memory of episodes it can query back at any granularity
• Reach for it when you want retrieval exposed to agents over MCP without writing the server yourself

// How M-flow compares

M-flow alongside other open-source rag frameworks & platforms tools AI/TLDR tracks, ranked by GitHub stars.