M-flow Cognitive Memory Engine
A graph-driven RAG paradigm that scores evidence paths for human-like associative recall.
- Source repo
- FlowElement-xinliuyuansu/m_flow
- Stars
- ★ 4.5k
- Last updated
- 2mo ago
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 36/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- AI assistants that need to remember user preferences and workflows across sessions for later reference.
- Not a fit if
- Individuals unwilling to run Docker, databases, and multiple services
- Users wanting face-aware memory without a camera or the extra face service
- Source review
- 36/100 · Major gaps 8 safety controls not found
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.
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.
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 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.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| M-flow Cognitive Memory Engine This agent | 36 · Major gaps | CLIFree + model costs | ★ 4.5k | 2mo ago | Python | OpenAI API · Claude API |
| Mnemosyne | 59 · Major gaps | CLIFree | ★ 3.5k | today | Python | Codex · Claude Code |
| SimpleMem: Efficient Lifelong Memory for LLM Agents | 43 · Major gaps | Library / SDKFree + model costs | ★ 3.8k | 2mo ago | Python | ChatGPT · Claude Code |
| Yuxi – Self-Hosted Multi-Tenant Knowledge Agent Platform | 41 · Major gaps | Self-hosted serviceFree + model costs | ★ 7.4k | 2d ago | Python | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
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.
- Not found in source: least-privilege scopingGrant only what the task needs: a dedicated account or read-only token, scoped to specific directories and repos.
- Not found in source: confirmation before actingTurn on (or add) a confirmation step before it acts, and try it in a sandbox or test environment before real data.
- Not found in source: data-flow disclosureWatch which external services it contacts (proxy or firewall logs) and keep sensitive data out until you know where it goes.
- Not found in source: sensitive-data handlingUse dedicated, low-privilege, revocable API keys — never production credentials — and keep secrets out of logs.
- Not found in source: dependency securityPin versions and run a dependency audit (npm audit, pip-audit) before installing; prefer running it in a container.
- Not found in source: disclosed external effectsEstablish which external systems it writes to, sends to or changes, and verify with test accounts or repos before production.
- Not found in source: rollback or recovery pathBack up first, or work on a git branch or snapshot, so its changes can be undone.
- Not found in source: verifiable attributionInstall from the official repo or registry and check the publisher and URL to avoid look-alike packages.
- 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.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.3.4 M-flow v0.3.4
Release notes excerpt
M-flow v0.3.4 Critical Fixes - Remove max_tokens parameter incompatible with GPT-5 series — all LLM calls were failing - Fix session/conversation history crash — compress_text(str) type mismatch replaced with correct summarize_text(str) High Priority Fixes - Fix audio processing (create_transcript → transcribe_audio method name) - Fix image processing (transcribe_image → describe_image method name) - Fix UUID serialization in search results, cache adapters, and graph property encoding - Fix _hash_sensitive dead code causing telemetry data corruption …View on GitHub ↗
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.