M-flow is a Python-based memory engine for Graph RAG that uses a cone graph to route retrieval evidence and score Episodic bundles. It supports multi-granularity retrieval, multiple LLM integrations, and various storage backends.
Collecting history — the radar snapshots this repo daily. The trend line appears after 3 days of data (1 so far).
What it is
M-flow is a bio-inspired cognitive memory engine that combines graph-based retrieval with RAG. It structures context as a four-layer Cone Graph: Episode → Facet → FacetPoint → Entity, and uses graph propagation to score knowledge units along evidence paths. It emphasizes retrieval driven by path cost and multi-granularity anchors rather than pure similarity.
How it works
Knowledge is stored in a four-level Cone Graph (Episode, Facet, FacetPoint, Entity). Retrieval is graph-routed: vector/hybrid search opens entry points, then the graph propagates and scores episodes by the strongest evidence path. Edges carry semantic signals (edge_text) and retrieval is designed as path-cost optimization over the graph. The system supports multi-granularity entry points and unified traversal across layers; coreference resolution is used during ingestion to link pronouns to entities. Optional face-aware memory partitions map individuals to separate memory datasets. Procedural memory captures reusable abstract patterns beyond factual data.
Getting started
Quick Start options include:
- One-Command Setup (Docker):
git clone https://github.com/FlowElement-xinliuyuansu/m_flow.git && cd m_flow
./quickstart.sh
On Windows, use . quickstart.ps1.
- Install via pip:
pip install mflow-ai # or: uv pip install mflow-ai
export LLM_API_KEY="sk-..."
- Install from Source:
git clone https://github.com/FlowElement-xinliuyuansu/m_flow.git && cd m_flow
pip install -e .
- Run example:
import asyncio
import m_flow
async def main():
await m_flow.add("M-flow builds persistent memory for AI agents.")
Recent releases
Latest release: v0.3.4 M-flow v0.3.4 (2026-04-12). Critical fixes include removing the max_tokens parameter incompatible with GPT-5 series and a session/history crash fix in compress_text(str) type handling.
Traction
The repository has 4424 stars and 255 forks. There are 18 open issues.
Behind the repo
Not provided in the README facts.
Caveats
- License: Apache-2.0
- Language: Python
- Created: 2026-03-31
- Last push: 2026-08-03
- Supports multiple databases: LanceDB, Neo4j, PostgreSQL/pgvector, ChromaDB, KùzuDB, Pinecone
- Python version compatibility: 3.10–3.13
- Tests: 963 passed