M-flow Cognitive Memory Engine
A graph-driven RAG paradigm that scores evidence paths for human-like associative recall.
Evidence shows: the repository provides no explicit permission model, user confirmation mechanism, data flow transparency, sensitive data handling, dependency security audit, external effects control, rollback mechanism, or source attribution. All trust-related criteria are unsupported, hence score 0.
Evidence shows: README and pyproject.toml are largely consistent in feature description and dependency declarations, but there are inconsistencies, e.g., README claims support for multiple databases, but pyproject.toml does not list all database dependencies. Dependency availability is partial as some dependencies like chinese-coref require source installation. Failure messages are not explicitly provided.
Evidence shows: README clearly identifies target audience (developers, researchers) and multiple use cases (RAG, GraphRAG, memory systems). Capability boundaries are described in feature list, but trigger precision (e.g., query types) is only briefly mentioned. Environment fit is addressed with Docker, pip, and source install options, but platform-specific support is not detailed.
Evidence shows: Information architecture is clear with README, docs, examples. Install notes are detailed including Docker, pip, source. Naming stability is consistent between project and package names, but version numbers are not explicitly matched between README and pyproject.toml. Examples and FAQ are provided, but known limitations are not explicitly listed. License is Apache-2.0, but versioning changelog is not provided. Maintenance responsibility is indicated in SECURITY.md, but update path is not explicit.
Evidence shows: Output usability is addressed with CLI and API, but output format details are not provided. Marginal value is claimed in benchmarks, but reproduction details are not fully provided. Cost-benefit is not addressed with performance or cost data.
Evidence shows: README claims benchmark reproduction scripts and raw data, but specific links or methodology details are not provided. Cross-source corroboration is not provided from independent sources. Fact-inference separation is not clear as design philosophy and benchmark results are mixed.
- The repository provides no permission model or user confirmation mechanism, potentially running with high privileges by default.
- Dependency security audit is missing, and some dependencies require source installation, posing supply chain risks.
- Benchmark claims mention reproduction scripts but no specific links are provided, making verification impossible.
- Known limitations are not explicitly listed, potentially hiding issues.
What does this agent do, and when should you use it?
M-flow is a bio-inspired cognitive memory engine that organizes knowledge in a four-layer cone graph (Episode → Facet → FacetPoint → Entity) and retrieves via graph-routed Bundle Search. Unlike traditional RAG relying on vector similarity, M-flow makes the graph itself the scoring engine: vector search only opens entry points, and final relevance is determined by evidence propagation along typed, semantically weighted edges, with each knowledge unit scored by the strongest chain of reasoning connecting it to the query. The repository includes the core Python library (m_flow), a FastAPI backend, a CLI (mflow), a Next.js web console, an MCP server, and adapters for multiple databases (LanceDB, Neo4j, PostgreSQL/pgvector, ChromaDB, KùzuDB, Pinecone) and LLM providers (OpenAI, Anthropic, Mistral, Groq, Ollama, etc.). It is released under Apache 2.0 and comes with 963 passing tests.
M-flow ingests data from 50+ file formats (PDFs, DOCX, HTML, Markdown, images, audio), performs chunking, parsing, coreference resolution (resolving pronouns to concrete antecedents before indexing), and builds a knowledge graph with embeddings. Queries are served via the query() method or mflow search command, using graph-routed Bundle Search: vector search casts a wide net across granularities (Episode, Facet, FacetPoint, Entity), then graph propagation traverses edges with semantic descriptions (edge_text) in a cost-aware manner, finally scoring each Episode by its strongest evidence path. It also offers face-aware memory partitioning through integration with a face-recognition service, procedural memory extraction, and an MCP server to expose memory as tools.
- AI assistants that need to remember user preferences and workflows across sessions for later reference.
- Team knowledge bases answering specific event questions like "Why was Maria upset at Monday's standup?".
- Developers wanting to augment existing RAG systems with graph structure beyond vector similarity.
- Multi-user environments (e.g., home or office) needing per-user memory partitioned by speaker and routed automatically.
- Researchers evaluating GraphRAG approaches on benchmarks like LoCoMo and LongMemEval.
What are this agent's strengths and limitations?
- Graph-routed Bundle Search outperforms traditional RAG in benchmarks (81.8% on LoCoMo-10 vs Supermemory's 64.4%).
- Unified multi-granularity retrieval in one graph avoids user burden of choosing a memory layer.
- Semantic edges (edge_text) carry natural-language meaning, enhancing interpretability.
- Supports multiple databases and LLM providers, offering flexibility.
- Coreference resolution improves retrieval accuracy in conversational memory.
- Higher complexity in end-to-end retrieval pipeline compared to simple vector retrieval.
- Benchmarks depend on specific models (gpt-5-mini/gpt-4o-mini); actual performance may vary.
- Face recognition integration requires an additional service (fanjing-face-recognition) and a camera.
- Some features (e.g., Playground) require extra configuration for production deployment (Docker, networking).
How do you install or deploy this agent?
One-command Docker setup: git clone https://github.com/FlowElement-xinliuyuansu/m_flow.git && cd m_flow && ./quickstart.sh (Windows users use quickstart.ps1). Or install via pip: pip install mflow-ai then set export LLM_API_KEY="sk-...". From source: git clone ... && cd m_flow && pip install -e ..
How do you use this agent?
In Python:
import asyncio, m_flow
async def main():
await m_flow.add("M-flow builds persistent memory for AI agents.")
await m_flow.memorize()
results = await m_flow.query("How does M-flow work?")
for item in results.context:
print(item)
asyncio.run(main())Or via CLI: mflow add "...", mflow memorize, mflow search "query" --query-type EPISODIC, mflow -ui starts the web console.
How does this agent compare with similar options?
In LoCoMo-10 and LongMemEval benchmarks, M-flow is compared against memory/GraphRAG systems like Cognee, Zep, Supermemory, and Mem0, showing higher LLM-Judge scores.
FAQ
Is M-flow compatible with my existing database?
Do I need a GPU?
How can I integrate M-flow into my IDE?
cd m_flow-mcp && uv run python src/server.py --transport sse) to expose memory as MCP tools.