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.
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 14 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 September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE 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, which is not included in the cleaned README, so the exact cost function is not verifiable from the supplied material.
Getting It Running: Commands and Configuration
The README provides a Quick Start link but the cleaned content does not include the actual commands. The repository layout shows a Python project with a default branch main and a release v0.3.4 from 2026-04-12. The badge indicates Python 3.10 to 3.13 support. 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. Because the README is truncated, installation steps, configuration keys, and CLI usage are not present in the supplied material. A reader should check the Quick Start section in the full README or the examples/ directory in the repository. The testing badge claims 963 passed tests, but that number is not a quality measure on its own.
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. The README gives no indication of automatic extraction; it is not clear whether the graph is built by hand, by an LLM pipeline, or by some other process. 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 does not provide benchmark numbers, so you cannot assume it will meet real-time constraints. The project claims an advantage in 'reported benchmarks', but no benchmark data is included in the supplied material.
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. There is no mention of a migration path between versions. 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.
Community notes