Metadata-Version: 2.4
Name: mflow-ai
Version: 0.3.2
Summary: M-flow builds semantic memory layers that help LLMs reason over your data with structured knowledge graphs.
Project-URL: Homepage, https://www.mflow.ai
Project-URL: Repository, https://github.com/FlowElement-ai/m_flow
Project-URL: Changelog, https://github.com/FlowElement-ai/m_flow/releases
Author: Junting Hua
Maintainer: Junting Hua
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
License-File: NOTICE.md
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: aiohttp<4.0.0,>=3.10.0
Requires-Dist: aiolimiter>=1.2.0
Requires-Dist: aiosqlite<1.0.0,>=0.19.0
Requires-Dist: alembic<2,>=1.13.0
Requires-Dist: diskcache>=5.6.0
Requires-Dist: fastapi-users[sqlalchemy]<15.0.0,>=14.0.1
Requires-Dist: fastapi<1.0.0,>=0.115.0
Requires-Dist: filetype<2.0.0,>=1.2.0
Requires-Dist: instructor<2.0.0,>=1.8.0
Requires-Dist: jinja2<4,>=3.1.0
Requires-Dist: kuzu<0.12,>=0.11.0
Requires-Dist: lancedb<1.0.0,>=0.22.0
Requires-Dist: limits<5,>=4.4.0
Requires-Dist: litellm>=1.75.0
Requires-Dist: numpy<3.0.0,>=1.26.0
Requires-Dist: openai>=1.80.0
Requires-Dist: pydantic-settings<3,>=2.2.0
Requires-Dist: pydantic<2.12.0,>=2.10.0
Requires-Dist: pylance<=0.36.0,>=0.20.0
Requires-Dist: pypdf<7.0.0,>=4.0.0
Requires-Dist: python-dotenv<2.0.0,>=1.0.0
Requires-Dist: python-magic-bin<0.5; platform_system == 'Windows'
Requires-Dist: python-multipart<1.0.0,>=0.0.18
Requires-Dist: sqlalchemy<3.0.0,>=2.0.30
Requires-Dist: structlog<26,>=25.1.0
Requires-Dist: tenacity>=8.5.0
Requires-Dist: tiktoken<1.0.0,>=0.7.0
Requires-Dist: typing-extensions<5.0.0,>=4.12.0
Requires-Dist: uvicorn<1.0.0,>=0.32.0
Requires-Dist: websockets<16.0.0,>=14.0
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.26; extra == 'anthropic'
Provides-Extra: api
Provides-Extra: aws
Requires-Dist: s3fs[boto3]<2026,>=2025.3.0; extra == 'aws'
Provides-Extra: baml
Requires-Dist: baml-py<0.210,>=0.206.0; extra == 'baml'
Provides-Extra: chromadb
Requires-Dist: chromadb<0.7,>=0.5; extra == 'chromadb'
Requires-Dist: pypika==0.48.9; extra == 'chromadb'
Provides-Extra: codegraph
Requires-Dist: fastembed<=0.6.0; (python_version < '3.13') and extra == 'codegraph'
Requires-Dist: transformers<5,>=4.45.0; extra == 'codegraph'
Requires-Dist: tree-sitter-python<0.24,>=0.23.0; extra == 'codegraph'
Requires-Dist: tree-sitter<0.25,>=0.23.0; extra == 'codegraph'
Provides-Extra: cohere
Requires-Dist: cohere>=5.0; extra == 'cohere'
Provides-Extra: coreference-full
Requires-Dist: spacy<4.0.0,>=3.7.0; extra == 'coreference-full'
Provides-Extra: debug
Requires-Dist: debugpy<2.0.0,>=1.8.0; extra == 'debug'
Provides-Extra: deepeval
Requires-Dist: deepeval<4,>=3.0.0; extra == 'deepeval'
Provides-Extra: deepseek
Provides-Extra: deploy
Requires-Dist: gunicorn<24,>=21.0.0; extra == 'deploy'
Provides-Extra: dev
Requires-Dist: coverage<8,>=7.3.0; extra == 'dev'
Requires-Dist: deptry<0.21,>=0.20.0; extra == 'dev'
Requires-Dist: gitpython<4,>=3.1.40; extra == 'dev'
Requires-Dist: mkdocs-material<10,>=9.5.0; extra == 'dev'
Requires-Dist: mkdocs-minify-plugin<0.9,>=0.8.0; extra == 'dev'
Requires-Dist: mkdocstrings[python]<0.28,>=0.26.0; extra == 'dev'
Requires-Dist: mypy<2,>=1.7.0; extra == 'dev'
Requires-Dist: notebook<8,>=7.0.0; extra == 'dev'
Requires-Dist: pre-commit<5,>=4.0.0; extra == 'dev'
Requires-Dist: pylint<4,>=3.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio<0.26,>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov<7.0.0,>=6.0.0; extra == 'dev'
Requires-Dist: pytest<9,>=7.4.0; extra == 'dev'
Requires-Dist: ruff<=0.14,>=0.9.0; extra == 'dev'
Provides-Extra: distributed
Requires-Dist: modal<2.0.0,>=1.0.0; extra == 'distributed'
Provides-Extra: dlt
Requires-Dist: dlt[sqlalchemy]<2,>=1.8.0; extra == 'dlt'
Provides-Extra: docling
Requires-Dist: docling>=2.50; extra == 'docling'
Requires-Dist: transformers>=4.50; extra == 'docling'
Provides-Extra: docs
Requires-Dist: lxml<5,>=4.9.0; (python_version < '3.13') and extra == 'docs'
Requires-Dist: lxml<6,>=5; (python_version >= '3.13') and extra == 'docs'
Requires-Dist: unstructured[csv,doc,docx,epub,md,odt,org,pdf,ppt,pptx,rst,rtf,tsv,xlsx]<19,>=0.18.0; extra == 'docs'
Provides-Extra: doubao
Provides-Extra: embeddings
Requires-Dist: fastembed<=0.6.0; extra == 'embeddings'
Requires-Dist: onnxruntime<=1.22.1; extra == 'embeddings'
Provides-Extra: evals
Requires-Dist: gdown<6,>=5.1.0; extra == 'evals'
Requires-Dist: matplotlib<4,>=3.8.0; extra == 'evals'
Requires-Dist: pandas<3.0.0,>=2.2.0; extra == 'evals'
Requires-Dist: plotly<7,>=5.18.0; extra == 'evals'
Requires-Dist: scikit-learn<2,>=1.5.0; extra == 'evals'
Provides-Extra: gemini
Requires-Dist: google-genai>=1.0; extra == 'gemini'
Provides-Extra: graphiti
Requires-Dist: graphiti-core<0.8,>=0.7.0; extra == 'graphiti'
Provides-Extra: groq
Requires-Dist: groq<1.0.0,>=0.8.0; extra == 'groq'
Provides-Extra: huggingface
Requires-Dist: transformers<5,>=4.45.0; extra == 'huggingface'
Provides-Extra: langchain
Requires-Dist: langchain-text-splitters<1.0.0,>=0.3.0; extra == 'langchain'
Requires-Dist: langsmith<1.0.0,>=0.2.0; extra == 'langchain'
Provides-Extra: llama-index
Requires-Dist: llama-index-core<0.13,>=0.12.0; extra == 'llama-index'
Provides-Extra: milvus
Requires-Dist: pymilvus>=2.4; extra == 'milvus'
Provides-Extra: mistral
Requires-Dist: mistral-common<2,>=1.5.0; extra == 'mistral'
Provides-Extra: monitoring
Requires-Dist: langfuse<3,>=2.30.0; extra == 'monitoring'
Requires-Dist: sentry-sdk[fastapi]<3,>=2.8.0; extra == 'monitoring'
Provides-Extra: neo4j
Requires-Dist: neo4j<6,>=5.27.0; extra == 'neo4j'
Provides-Extra: neptune
Requires-Dist: langchain-aws>=0.2.20; extra == 'neptune'
Provides-Extra: notebook
Requires-Dist: notebook<8,>=7.0.0; extra == 'notebook'
Provides-Extra: ollama
Requires-Dist: transformers<5,>=4.45.0; extra == 'ollama'
Provides-Extra: pinecone
Requires-Dist: pinecone>=5.0; extra == 'pinecone'
Provides-Extra: postgres
Requires-Dist: asyncpg<1.0.0,>=0.29.0; extra == 'postgres'
Requires-Dist: pgvector<0.4,>=0.3.4; extra == 'postgres'
Requires-Dist: psycopg2<3,>=2.9.9; extra == 'postgres'
Provides-Extra: postgres-binary
Requires-Dist: asyncpg<1.0.0,>=0.29.0; extra == 'postgres-binary'
Requires-Dist: pgvector<0.4,>=0.3.4; extra == 'postgres-binary'
Requires-Dist: psycopg2-binary<3.0.0,>=2.9.9; extra == 'postgres-binary'
Provides-Extra: posthog
Requires-Dist: posthog<4,>=3.5.0; extra == 'posthog'
Provides-Extra: qwen
Provides-Extra: redis
Requires-Dist: redis<6.0.0,>=5.0.0; extra == 'redis'
Provides-Extra: scraping
Requires-Dist: apscheduler<=3.11.0,>=3.10.0; extra == 'scraping'
Requires-Dist: beautifulsoup4>=4.12.0; extra == 'scraping'
Requires-Dist: lxml<5,>=4.9.0; (python_version < '3.13') and extra == 'scraping'
Requires-Dist: lxml<6,>=5; (python_version >= '3.13') and extra == 'scraping'
Requires-Dist: playwright>=1.9.0; extra == 'scraping'
Requires-Dist: protego>=0.1; extra == 'scraping'
Requires-Dist: tavily-python>=0.7.10; extra == 'scraping'
Description-Content-Type: text/markdown

<div align="center">

# M-flow

**A memory engine that focuses on reasoning and association.**

M-flow 是一款重构检索架构、侧重推理与联想的记忆引擎。

[Quick Start](#quick-start) ·
[Architecture](docs/RETRIEVAL_ARCHITECTURE.md) ·
[架构详解（中文）](docs/RETRIEVAL_ARCHITECTURE_ZH.md) ·
[Examples](examples/) ·
[Contact](mailto:contact@xinliuyuansu.com)

[![Tests](https://img.shields.io/badge/tests-963%20passed-brightgreen)](#testing)
[![Python](https://img.shields.io/badge/python-3.10–3.13-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](LICENSE)

</div>

---

## What is M-flow?

M-flow is not a vector database or a RAG framework. It is a **cognitive memory engine** — a system that doesn't just store text, but *understands* it, distilling incoming knowledge into structured layers and weaving them into the right place of a persistent architecture.

Where traditional retrieval matches queries by surface similarity, M-flow **reasons through relationships** — tracing connections, weighing context, and reaching answers the way cognition does.

Most AI memory systems fall into two categories:

- **Context Window** — The model re-reads everything from scratch. Exhaustive, linear, forgetful.
- **Similarity Search** — External memory exists, but retrieval is surface-level — matching by vector shape, blind to structure. Approximate, lossy.

M-flow introduces a third paradigm: a **Cognitive Engine** where memory becomes a mind. A query at any granularity finds a precise anchor, then expands outward — surfacing related context and associative content across different levels of detail.

## How It Works

M-flow organizes knowledge into a four-level **Cone Graph** — a layered hierarchy from abstract summaries to atomic facts:

| Level | What it captures | Query example |
|-------|-----------------|---------------|
| **Episode** | A bounded semantic focus — an incident, decision process, or workflow | *"What happened with the tech stack decision?"* |
| **Facet** | One dimension of that Episode — a topical cross-section | *"What were the performance targets?"* |
| **FacetPoint** | An atomic assertion or fact derived from a Facet | *"Was the P99 target under 500ms?"* |
| **Entity** | A named thing — person, tool, metric — linked across all Episodes | *"Tell me about GPT-4o"* → surfaces all related contexts |

Retrieval is **graph-routed**: the system casts a wide net across all levels, projects hits into the knowledge graph, propagates cost along every possible path, and scores each Episode by its **tightest chain of evidence**. One strong path is enough — the way a single association triggers an entire memory.

> For the full technical deep-dive, see [Retrieval Architecture](docs/RETRIEVAL_ARCHITECTURE.md) | [检索架构详解（中文）](docs/RETRIEVAL_ARCHITECTURE_ZH.md)

## Benchmark

Dataset: [LoCoMo-10](https://github.com/snap-stanford/locomo) (10 conversations, 1540 questions) · Retrieval: EpisodicRetriever · Judge LLM: gpt-4o-mini

| System | LLM-Judge | BLEU-1 | F1 |
|--------|-----------|--------|-----|
| **M-flow** | **76.5%** | **0.422** | **0.503** |
| Mem0 Cloud (tested) | 40.4% | 0.186 | 0.196 |

| Category | M-flow | Mem0 Cloud (tested) |
|----------|--------|---------------------|
| Single-hop (factual) | 68.5% | 44.7% |
| Temporal reasoning | **78.8%** | 7.5% |
| Multi-hop reasoning | 48.0% | 39.6% |
| Open-domain (event detail) | **81.5%** | 49.1% |

Evaluation scripts, methodology details, and reproduction steps: [mflow-benchmarks](https://github.com/FlowElement-ai/mflow-benchmarks/tree/main/benchmarks/locomo)

## Features

| | |
|---------|-------------|
| **Episodic + Procedural memory** | Hierarchical recall for facts and step-by-step knowledge |
| **5 retrieval modes** | Episodic, Procedural, Triplet Completion, Lexical, Cypher |
| **50+ file formats** | PDFs, DOCX, HTML, Markdown, images, audio, and more |
| **Multi-DB support** | LanceDB, Neo4j, PostgreSQL/pgvector, ChromaDB, KùzuDB, Pinecone |
| **LLM-agnostic** | OpenAI, Anthropic, Mistral, Groq, Ollama, LLaMA-Index, LangChain |
| **Precise summarization** | Preserves all factual details (dates, numbers, names) at the cost of lower compression — RAG context will be longer but more accurate |
| **MCP server** | Expose memory as Model Context Protocol tools for any IDE |
| **CLI & Web UI** | Interactive console, knowledge graph visualization, config wizard |

> **Retrieval modes**: **Episodic** is the primary retrieval mode — it uses graph-routed Bundle Search for best accuracy and is used in all benchmarks. **Triplet Completion** is a simpler vector-based mode suited for customization and secondary development. See [Retrieval Architecture](docs/RETRIEVAL_ARCHITECTURE.md) for details.

## Quick Start

### One-Command Setup (Docker)

```bash
git clone https://github.com/FlowElement-ai/m_flow.git && cd m_flow
./quickstart.sh
```

The script checks your environment, configures API keys interactively, and starts the full stack (backend + frontend). On Windows, use `.\quickstart.ps1`.

### Install via pip

```bash
pip install mflow-ai         # or: uv pip install mflow-ai
export LLM_API_KEY="sk-..."
```

### Install from Source

```bash
git clone https://github.com/FlowElement-ai/m_flow.git && cd m_flow
pip install -e .             # editable install for development
```

### Run

```python
import asyncio
import 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.search("How does M-flow work?")
    for r in results:
        print(r)


asyncio.run(main())
```

### CLI

```bash
mflow add "M-flow builds persistent memory for AI agents."
mflow memorize
mflow search "How does M-flow work?"
mflow -ui          # Launch the local web console
```

## Architecture Overview

```
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│  Data Input   │────▶│    Extract    │────▶│   Memorize    │
│  (50+ formats)│     │  (chunking,   │     │  (KG build,   │
│               │     │   parsing)    │     │  embeddings)  │
└───────────────┘     └───────────────┘     └───────┬───────┘
                                                    │
                      ┌───────────────┐     ┌───────▼───────┐
                      │    Search     │◀────│     Load      │
                      │  (graph-routed│     │   (graph +    │
                      │  bundle search│     │  vector DB)   │
                      └───────────────┘     └───────────────┘
```

## Project Layout

```
m_flow/              Core Python library & API
├── api/             FastAPI routers (add, memorize, search, …)
├── cli/             Command-line interface (`mflow`)
├── adapters/        DB adapters (graph, vector, cache)
├── core/            Domain models (Episode, Facet, FacetPoint, …)
├── memory/          Memory processing (episodic, procedural)
├── retrieval/       Search & retrieval algorithms
├── pipeline/        Composable pipeline tasks & orchestration
├── auth/            Authentication & multi-tenancy
├── shared/          Logging, settings, cross-cutting utilities
└── tests/           Unit & integration tests

m_flow-frontend/     Next.js web console
m_flow-mcp/          Model Context Protocol server
mflow_workers/       Distributed execution helpers (Modal, workers)
examples/            Runnable example scripts
docs/                Architecture & design documents
```

## Development

```bash
git clone https://github.com/FlowElement-ai/m_flow.git && cd m_flow
uv sync --dev --all-extras --reinstall

# Test
PYTHONPATH=. uv run pytest m_flow/tests/unit/ -v

# Lint
uv run ruff check . && uv run ruff format .
```

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full contributor guide.

## Deployment

### Docker

```bash
docker compose up                       # Backend only
docker compose --profile ui up          # Backend + frontend
docker compose --profile neo4j up       # Backend + Neo4j
```

### MCP Server

```bash
cd m_flow-mcp
uv sync --dev --all-extras
uv run python src/server.py --transport sse
```

## Testing

```bash
PYTHONPATH=. pytest m_flow/tests/unit/ -v        # ~963 test cases
PYTHONPATH=. pytest m_flow/tests/integration/ -v  # Needs .env with API keys
```

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines, and our [Code of Conduct](CODE_OF_CONDUCT.md) for community standards.

## License

M-flow is licensed under the [Apache License 2.0](LICENSE).

```
Copyright 2026 Junting Hua

Licensed under the Apache License, Version 2.0.
You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
```
