M-flow is a Python-based memory engine that uses a graph-structured memory (Episode → Facet → FacetPoint → Entity) to drive retrieval and reasoning for RAG-like workflows. It supports multi-DB backends, LLM-agnostic operation, and both episodic and procedural memory features.
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 memory with retrieval across multiple granularities. It structures knowledge into a four-level cone graph: Episode, Facet, FacetPoint, Entity. Retrieval is graph-routed, scoring results by the strongest evidence path rather than by flat similarity.
How it works
Knowledge is stored in a four-level graph. Retrieval starts from granularity anchors (Episode, Facet, FacetPoint, or Entity) and propagates along typed edges with associated costs to produce Episode bundles that best explain a query. Edges carry natural-language signals (edge_text) and retrieval is described as path-cost optimization over the graph. The system supports multi-granularity search, semantic edges as first-class signals, and controlled propagation to avoid naive graph walks. It includes coreference resolution at ingestion to link pronouns to concrete entities and a face-aware memory partitioning feature for real-time routing by biometric identity.
Getting started
- One-Command Setup (Docker):
git clone https://github.com/FlowElement-ai/m_flow.git && cd m_flow
./quickstart.sh
- 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-ai/m_flow.git && cd m_flow
pip install -e . # editable install for development
- Run example/snippet:
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
Getting started (continued)
The repository describes a Quick Start pipeline, installation options, and a Run section for interacting with the memory engine.
Recent releases
- v0.3.4 M-flow v0.3.4 (2026-04-12):
- Critical Fixes: Remove
max_tokensparameter incompatible with GPT-5 series — all LLM calls were failing - Fix session/conversation history crash —
compress_text(str)type mi
- Critical Fixes: Remove
Traction
- Stars: 4432
- Forks: 255
- Open issues: 17
Caveats
- License: Apache-2.0
- Language: Python
- Created: 2026-03-31
- Last push: 2026-06-01
- Latest release notes indicate a fix for incompatible max_tokens with GPT-5 series and a history/crash fix, but no additional usage caveats are listed in the provided material.