Model or dataset
FlowElement-xinliuyuansu/m_flow avatar
FlowElement-xinliuyuansu/m_flow

M-flow: A Graph RAG Engine That Scores Evidence Paths Instead of Text Similarity

A bio-inspired cognitive memory engine — a new paradigm for Graph RAG.

4,515 stars259 forksPythonApache-2.0

At a glance

What is it?
M-flow is an Apache-2.0 Python framework that turns a four-layer knowledge graph into the retrieval scorer. It targets agent memory and Graph RAG use cases where relevance depends on chains of evidence, not keyword overlap.
Who is it for?
Adopt M-flow if you need retrieval for agent memory or Graph RAG where the answer depends on connecting a query to a specific past event through typed associations, and where you can invest in modeling Episodes, Facets, FacetPoints, and Entities. Do not use it if your queries are simple keyword lookups or if you cannot maintain a structured graph of your domain.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository last received commits 75 days ago.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • FlowElement-xinliuyuansu/m_flow4,515 ★ · +20
Star history
Repository2026-09-102026-11-15
FlowElement-xinliuyuansu/m_flow4.5k4.5k

20 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The Problem: Similarity Is Not Relevance

Standard RAG retrieves by embedding similarity: the query is turned into a vector and ranked against text chunks. GraphRAG systems add entities and relations, but the graph often only organizes context; the final ranking still leans on vector distance. M-flow starts from a different premise: a document can share many words with a query and still miss the point. The README gives the example of asking why Maria was upset at Monday's standup. A generic article on running effective standups contains the words 'standup', 'upset', and 'team', so it scores high on keyword overlap, yet it says nothing about the actual cause. M-flow is built for cases where the answer is a specific event or chain of events, not a topic match. The intended users are developers building agent memory systems, long-term memory for LLM agents, or Graph RAG pipelines that must answer questions about specific incidents, decisions, or workflows.

The Cone Graph: Four Layers of Memory

M-flow organizes knowledge into a four-level hierarchy it calls the Cone Graph. The top level is the Episode, a bounded semantic focus such as an incident, a decision process, or a workflow. Below that is the Facet, one dimension of that Episode, like performance targets or deadline communication. The third level is the FacetPoint, an atomic assertion or fact derived from a Facet, for example 'the P99 target was under 500ms'. The fourth level is the Entity, a named thing like a person, tool, or metric, and entities link across all Episodes. The key idea is that a query lands on the layer that matches its granularity. A precise cue like 'I wasn't told about the deadline' hits a FacetPoint. A broader theme like 'the tech stack decision' hits an Episode summary. This granularity alignment is what separates M-flow from flat chunk retrieval. The README calls this an 'inverted-cone view': each hop outward from a precise cue moves toward a wider semantic cross-section.

Path-Cost Retrieval: The Graph as Scorer

The retrieval mechanism is described as graph-routed bundle search. First, vector search casts a wide net across all four levels to find entry points. Then the graph takes over. Evidence propagates along typed, semantically weighted edges, and each edge adds a cost. This is not a random graph walk; only paths with coherent, low-cost connections remain competitive. The system scores each Episode by the strongest chain of evidence that connects it to the query. One strong path is enough, the way a single association can trigger an entire memory. The output is a bundle: one Episode together with its Facets and FacetPoints. The downstream LLM composes the final answer from that bundle. The README stresses that relevance is not a score but a path. This is a fundamental departure from candidate matching. The repository points to docs/RETRIEVAL_ARCHITECTURE.md for the full path-cost mechanism.

Getting It Running: Commands and Configuration

The repository root carries quickstart.sh and quickstart.ps1, and `make quickstart` runs ./quickstart.sh; `docker compose up` starts the backend alone, and the ui, neo4j, postgres, mcp and playground profiles add the other services. The repository layout shows a Python project with a default branch main and a release v0.3.4 from 2026-04-12. pyproject.toml requires Python 3.10 or newer. The README mentions an OpenClaw Skill available at clawhub.ai, which suggests integration with the OpenClaw agent framework. The homepage is flowelement.ai, and there is a separate m-flow.ai site. The license is Apache-2.0. A reader should check the Quick Start section of the README or the examples/ directory in the repository.

Where M-flow Is the Wrong Tool

M-flow is not a drop-in replacement for every RAG pipeline. If your queries are simple fact lookups where a single vector match is sufficient, the overhead of building and maintaining a four-layer graph is unjustified. The system requires that your data be decomposable into Episodes, Facets, FacetPoints, and Entities. That modeling effort is significant. If your domain lacks clear episodes or recurring entities, the cone graph becomes an arbitrary structure. Another failure mode is retrieval latency: graph propagation along typed edges with cost accumulation is more expensive than a single vector search. The README credits M-flow's advantage to 'our reported benchmarks', and the Makefile syncs benchmark write-ups into docs/benchmarks/; read them before assuming it will meet real-time constraints.

Alternatives: Vector RAG and Standard GraphRAG

The most direct alternative is plain vector RAG, where you embed chunks and rank by cosine similarity. That approach is simpler to implement and does not require a graph. It fails on the Maria example because it cannot distinguish a generic how-to article from a specific event. Another alternative is standard GraphRAG, which builds a knowledge graph of entities and relations and uses community detection or graph traversal to expand context. The difference is that standard GraphRAG typically uses the graph to augment the context window, not to score the final relevance. M-flow makes the graph the scoring engine. If you already have a knowledge graph and only need to enrich prompts, standard GraphRAG may be sufficient. If you need to retrieve a specific episode based on a precise cue, M-flow's path-cost approach is designed for that. The choice depends on whether relevance in your domain is a path or just a proximity.

Maintenance, Upgrade Cost, and License

The project is under Apache-2.0, which permits commercial use, modification, and redistribution with attribution. This is a permissive license with no copyleft obligations for your own code, though you should keep the license notice. The repository has a release v0.3.4 from April 2026, and the last push to the default branch was September 2026, indicating active development. The README references a separate documentation file for retrieval architecture, which suggests the design is evolving. The maintenance cost includes keeping the graph structure accurate as new episodes are added. The presence of an OpenClaw skill suggests integration points that may change as the project evolves. Before adopting, verify the upgrade notes between releases and whether the graph schema is stable.

Editorial conclusion

Adopt M-flow if you need retrieval for agent memory or Graph RAG where the answer depends on connecting a query to a specific past event through typed associations, and where you can invest in modeling Episodes, Facets, FacetPoints, and Entities. Do not use it if your queries are simple keyword lookups or if you cannot maintain a structured graph of your domain. Before adopting, verify that your data can be cleanly decomposed into the four-layer hierarchy and that the retrieval latency of graph propagation meets your service-level targets. M-flow is a deliberate design choice that trades the simplicity of vector-only ranking for a more complex, but more explainable, path-cost mechanism.

Frequently asked questions

What is M-flow?

A memory engine for retrieval over structured knowledge graphs, described as a bio-inspired cognitive memory engine and a new paradigm for Graph RAG. It stores knowledge in a four level cone graph of Episode, Facet, FacetPoint and Entity, and the package is named mflow-ai under Apache-2.0.

How does M-flow retrieval differ from plain vector search?

Vector search casts a wide net across multiple granularities to find entry points, and then the graph takes over: evidence propagates along typed, semantically weighted edges, and each knowledge unit is scored by the strongest chain of reasoning that connects it to the query.

What does M-flow return for a query?

One Episode bundle per answer, scored by its strongest path of evidence and containing the Episode together with its Facets and FacetPoints. The downstream LLM composes the final answer from that bundle's content, rather than from a set of independent chunks.

What does the M-flow Docker stack include?

A backend API on port 8000 with a debugpy port at 9230, plus compose profiles for the frontend, Neo4j, Postgres, the MCP server and a playground profile that adds face recognition. The backend declares four CPUs and 8GB of memory and healthchecks /health.

How do I run the M-flow tests and linters?

make test runs pytest against m_flow/tests/unit/ with PYTHONPATH set to the repository root. The lint target runs ruff check with fix followed by ruff format on m_flow/, and documentation is built with mkdocs in strict mode from the .venv-docs environment.

Official sources

  1. FlowElement-xinliuyuansu/m_flow on GitHub
  2. License: Apache-2.0
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/flowelement-xinliuyuansu-m-flow.svg)](https://hysenlabs.com/projects/flowelement-xinliuyuansu-m-flow)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/flowelement-xinliuyuansu-m-flow.svg)](https://hysenlabs.com/projects/flowelement-xinliuyuansu-m-flow)

Was this useful?