# M-flow: A Four-Layer Cone Graph That Scores Evidence Paths Instead of Chunks

> M-flow is a Python memory engine for LLM applications that replaces similarity ranking with graph-routed path-cost retrieval over an Episode, Facet, FacetPoint, Entity hierarchy. It is promising for episodic memory and agent recall, but it is a beta project with a heavy dependency footprint and no documented rollback story.

**FlowElement-xinliuyuansu/m_flow** — A bio-inspired cognitive memory engine — a new paradigm for Graph RAG.

- Repository: https://github.com/FlowElement-xinliuyuansu/m_flow
- Website: https://flowelement.ai
- Stars: 4,511 · Forks: 260
- Language: Python
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/flowelement-xinliuyuansu-m-flow

## The Problem M-flow Targets: Similarity Is Not Relevance

Most retrieval stacks rank text units by vector distance. The README argues this conflates two different things: similarity is proximity in representation space, relevance is whether the system can connect a query to an answer through a coherent structure of evidence. The worked example is a query like "Why was Maria upset at Monday's standup?" A document about how to run effective daily standups has high keyword overlap with that query and no causal connection to it. A vector ranker will happily return it.

M-flow is aimed at developers building agent memory, episodic recall and reasoning over accumulated conversation or incident records. It is not a drop-in replacement for a document QA pipeline over a static corpus. The README frames the intended distinction bluntly: "RAG matches chunks. GraphRAG structures context. M-flow scores evidence paths." That framing tells you the target user is someone who already has a graph-shaped problem and finds that vector search keeps returning plausible-looking neighbours instead of the actual cause.

## How the Cone Graph Turns Retrieval into Path Scoring

Knowledge is stored in four levels. Episode is a bounded semantic focus such as an incident or a decision process. Facet is one dimension of that Episode. FacetPoint is an atomic assertion derived from a Facet. Entity is a named thing (a person, a tool, a metric) linked across all Episodes. A query first lands on the layer matching its granularity: a precise cue anchors on a FacetPoint, a broader theme anchors on a Facet or an Episode summary.

From that anchor, evidence propagates along typed, semantically weighted edges. Each hop widens the semantic field and adds cost, so association is a controlled propagation rather than an unrestricted graph walk. Only paths with coherent, low-cost connections stay competitive. Each returned bundle is one Episode, scored by its strongest chain of evidence, and the downstream LLM composes the answer from the Episode together with its Facets and FacetPoints. The README's own analogy is recall: thinking of a classmate brings up California, which opens a neighbourhood in which the Lakers become the next low-cost association. The full path-cost mechanism lives in docs/RETRIEVAL_ARCHITECTURE.md, and the README does not reproduce the cost formula.

## Installing M-flow and Running a First Episodic Smoke Test

The repository ships a quickstart script and a Makefile target that calls it. The Makefile defines quickstart as ./quickstart.sh, and the repository also contains quickstart.ps1 for Windows. The Docker path is documented in docker-compose.yml comments: docker compose up runs the backend only, and profiles add the frontend, Neo4j, Postgres, MCP server or playground.

```bash
docker compose up                      # backend only
docker compose --profile ui up         # backend + frontend
docker compose --profile mcp up        # backend + MCP server
```

The backend container is named m_flow, exposes port 8000 and a debugpy port 9230, and has a healthcheck against http://localhost:8000/health. The compose file sets HOST to 0.0.0.0, ENVIRONMENT to local and LOG_LEVEL to INFO, and limits the service to 4 CPUs and 8GB of memory. If you prefer the Makefile, make up is equivalent to docker compose --profile ui up -d and make logs tails the last 100 lines.

For a local Python install, the package name in pyproject.toml is mflow-ai and requires Python >=3.10. The repository keeps its runnable checks under examples/, including episodic stage smoke tests named examples/episodic_stage1_smoke_test.py through examples/episodic_stage5_smoke_test.py. Those are the files to open first: they are the project's own staged verification scripts rather than a documented public API. The README does not give a pip install line, so treat the Docker and quickstart paths as the documented entry points.

## Where M-flow Is the Wrong Tool

The four-layer model is an ingestion contract, not just a storage format. Something has to decide what an Episode is, which Facets belong to it, and which FacetPoints are atomic enough to anchor a query. The README describes the structure and the retrieval behaviour but does not document how those boundaries are chosen or what happens when a document does not decompose cleanly into an Episode. If your corpus is flat (FAQ pages, reference manuals, changelogs), you are paying for hierarchy you will not use.

The dependency list in pyproject.toml is heavy for a retrieval layer: FastAPI, fastapi-users with SQLAlchemy, uvicorn, websockets, aiohttp, openai, litellm, instructor, tiktoken, SQLAlchemy, aiosqlite, Alembic, LanceDB, Kuzu, pylance, diskcache, pydantic, pydantic-settings, numpy, pypdf, filetype, jinja2, tenacity, aiolimiter and limits. That is a web service plus an LLM provider abstraction plus two storage engines. If you wanted a library you import into an existing FastAPI app, you are adopting a service. The Dockerfile also carries an ARG UV_EXTRAS default of "debug deploy api postgres neo4j llama-index ollama mistral groq anthropic langchain", which is a wide default surface for a project at version 0.3.x.

There is no documented rollback or migration-reversal procedure in the README. Alembic is present and the Dockerfile copies alembic.ini and alembic/ into the image, so schema migrations exist, but the README is silent on downgrade paths. Treat that as an open question before you point it at data you cannot rebuild.

## M-flow and the GraphRAG Alternatives

The README positions M-flow against two other approaches rather than naming a single competitor. The first is plain RAG, where retrieval is dominated by similarity and structure, if present, mainly helps organize, summarize or expand context. The second is GraphRAG systems that add entities, relations and community structure but leave the graph supportive rather than decisive in scoring. M-flow's claim is that the graph becomes the scoring engine: vector search only casts the net for entry points, and path cost decides the final ranking.

That is a real architectural difference, not a wording difference. In a community-summary GraphRAG, an entity graph improves the context you hand to the model. In M-flow, the graph determines which Episode wins. The practical consequence is that retrieval quality depends on edge typing and weighting, which means your ingestion quality matters more than your embedding choice. If you have already invested in a managed vector database and a chunking pipeline, M-flow asks you to replace the chunk as the unit of retrieval with the Episode bundle.

## Maintenance, Licence and the Upgrade Surface

The repository is not archived and the last push was on 2026-09-01. The most recent release listed is v0.3.4 from 2026-04-12, while pyproject.toml declares version 0.3.6, so the published release tags and the working tree version are not in step. The classifier in pyproject.toml is "Development Status :: 4 - Beta", which matches the 0.3.x numbering.

Licensing is Apache-2.0 per pyproject.toml and the LICENSE file, with a NOTICE and NOTICE.md at the repository root and a licenses/ directory. Apache-2.0 includes a patent grant and requires attribution via the NOTICE file when you redistribute. The repository also contains a coreference/ directory and the Dockerfile removes a chinese-coref file dependency from pyproject.toml with a sed command, installing the coreference package separately via pip. If you vendor this stack, that split dependency is the first thing to trace. This is not legal advice; read the LICENSE and NOTICE files yourself.

Upgrade cost concentrates in three places: the Alembic migration chain, the pinned Kuzu range of >=0.11.0,<0.12 and LanceDB range of >=0.22.0,<1.0.0, and the wide UV_EXTRAS default in the Dockerfile. The README does not document a version compatibility matrix.

## Testing and Verification in the Repository

The Makefile defines test as PYTHONPATH=. pytest m_flow/tests/unit/ -v --tb=short, so unit tests live under m_flow/tests/unit/. The README badge states 963 tests passed, which is a claim from the project's own badge rather than an independently reproduced result. The examples/ directory is more useful for evaluation than the badge: it contains staged episodic smoke tests, retrieval tests such as examples/test_retrieval_15events.py and examples/test_retrieval_fast.py, and a UI example at examples/start_ui_example.py.

```bash
make test
make lint
```

make lint runs ruff check m_flow/ --fix followed by ruff format m_flow/, so the project standardizes on Ruff. The docs targets assume a separate virtualenv at .venv-docs and run mkdocs build --strict, which means the documentation build fails on warnings. If you are evaluating M-flow, read docs/RETRIEVAL_ARCHITECTURE.md alongside the episodic smoke tests; those two together are the closest thing to a specification in the repository.

## Conclusion

Adopt M-flow if you are building long-term episodic memory for an agent and you can accept a beta-stage project with Kuzu, LanceDB, SQLAlchemy and Alembic in the stack. Do not adopt it if you need a stable retrieval API or you are running on a managed vector database only. Before committing, verify how the four layers are populated for your own documents, check the pyproject.toml extras against your Python version, and confirm the retrieval path-cost code in docs/RETRIEVAL_ARCHITECTURE.md matches what you need.

## FAQ

### What is M-flow?

M-flow is a Python cognitive memory engine that stores knowledge in a four-layer cone graph (Episode, Facet, FacetPoint, Entity) and scores retrieved Episodes by their strongest path of evidence rather than by vector similarity. The package name in pyproject.toml is mflow-ai and it requires Python 3.10 or newer.

### How do I use M-flow?

The documented entry points are the quickstart script (make quickstart, which runs ./quickstart.sh) and Docker Compose, where docker compose up starts the backend and profiles add the UI, Neo4j, Postgres or MCP server. The repository's examples/ directory holds staged episodic smoke tests to run against your own data.

### What is the purpose of M-flow?

Its stated purpose is to make the graph the scoring engine at retrieval time, so that a query anchors on the layer matching its granularity and evidence propagates along typed, weighted edges to a coherent Episode bundle. The README frames this as the difference between matching chunks and scoring evidence paths.

### How do I check whether M-flow is running?

The Docker Compose service mflow-api defines a healthcheck that runs curl against http://localhost:8000/health every 30 seconds. The Makefile also provides make status, which runs docker compose ps.

## Sources

- [FlowElement-xinliuyuansu/m_flow on GitHub](https://github.com/FlowElement-xinliuyuansu/m_flow)
- [License: Apache-2.0](https://github.com/FlowElement-xinliuyuansu/m_flow/blob/main/LICENSE)
- [Project website](https://flowelement.ai)
- [README](https://github.com/FlowElement-xinliuyuansu/m_flow/blob/main/README.md)
- [Releases](https://github.com/FlowElement-xinliuyuansu/m_flow/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/flowelement-xinliuyuansu-m-flow