memU

![MemU Banner](assets/banner.png)

<div align="center">

# memU

### Turn Any Raw Workspace into Agent Memory

[![PyPI version](https://badge.fury.io/py/memu-py.svg)](https://badge.fury.io/py/memu-py)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python 3.13+](https://img.shields.io/badge/python-3.13+-blue.svg)](https://www.python.org/downloads/)
[![Discord](https://img.shields.io/badge/Discord-Join%20Chat-5865F2?logo=discord&logoColor=white)](https://discord.com/invite/hQZntfGsbJ)
[![Twitter](https://img.shields.io/badge/Twitter-Follow-1DA1F2?logo=x&logoColor=white)](https://x.com/memU_ai)

<a href="https://trendshift.io/repositories/17374" target="_blank"><img src="https://trendshift.io/api/badge/repositories/17374" alt="NevaMind-AI%2FmemU | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>

**[English](readme/README_en.md) | [中文](readme/README_zh.md) | [日本語](readme/README_ja.md) | [한국어](readme/README_ko.md) | [Español](readme/README_es.md) | [Français](readme/README_fr.md)**

</div>

---

memU is a **memory harness** for AI agents.
Feed it raw data — conversations, documents, images — and it automatically builds a structured, queryable memory layer your agents can call at any time.

- **Ingest anything**: conversations, files, URLs, multimodal inputs
- **Auto-structure**: no manual tagging — memU extracts, categorizes, and cross-links memories automatically
- **Agent-ready**: retrieve relevant context in one call, reduce token cost by up to 10x

---

## 🤖 [memU Bot — Open Source Agent](https://github.com/NevaMind-AI/memUBot)

<img width="100%" src="https://github.com/NevaMind-AI/memU/blob/main/assets/memUbot.png" />

**[memU Bot](https://github.com/NevaMind-AI/memUBot)** — The enterprise-ready proactive AI assistant built on memU. Remembers everything, acts autonomously.

- One-click install, running in under 3 minutes
- Builds long-term memory and acts on user intent proactively (24/7)
- Reduces LLM token cost with compressed, structured context (~1/10 comparable usage)

Try now: [memu.bot](https://memu.bot) · Source: [memUBot on GitHub](https://github.com/NevaMind-AI/memUBot)

---

## 🔄 How It Works

**Raw Data → Structured Memory → Agent Context**

```
Your Workspace                memU Pipeline               Agent
─────────────────────         ─────────────────────       ──────────────────
chat logs                 →   ingest & parse           →  retrieve()
documents                 →   extract & categorize     →  one call, typed results
images / audio            →   cross-link memories      →  10x less tokens
URLs / APIs               →   build filesystem index   →  always up to date
```

1. **Ingest** — feed memU your raw workspace: chat logs, docs, images, any modality
2. **Extract** — facts, preferences, skills, and relationships are pulled out automatically
3. **Organize** — memories are structured like a filesystem: hierarchical, browsable, linkable
4. **Retrieve** — agents get back only the relevant context, scoped to user or task

---

## 🗃️ Memory as a Filesystem

memU treats memory like a file system — structured, hierarchical, and instantly accessible.

| File System | memU Memory |
|-------------|-------------|
| 📁 Folders | 🏷️ Categories (auto-organized topics) |
| 📄 Files | 🧠 Memory Items (extracted facts, preferences, skills) |
| 🔗 Symlinks | 🔄 Cross-references (related memories linked) |
| 📂 Mount points | 📥 Resources (conversations, documents, images) |

```
memory/
├── preferences/
│   ├── communication_style.md
│   └── topic_interests.md
├── relationships/
│   ├── contacts/
│   └── interaction_history/
├── knowledge/
│   ├── domain_expertise/
│   └── learned_skills/
└── context/
    ├── recent_conversations/
    └── pending_tasks/
```

Just as a file system turns raw bytes into organized data, memU transforms raw interactions into **structured, searchable, proactive intelligence**.

---

## ⭐️ Star the repository

<img width="100%" src="https://github.com/NevaMind-AI/memU/blob/main/assets/star.gif" />

If you find memU useful or interesting, a GitHub Star ⭐️ would be greatly appreciated.

---

## ✨ Core Features

| Capability | Description |
|------------|-------------|
| 🗂️ **Raw Workspace Ingestion** | Automatically ingests conversations, documents, images, and multimodal data from any source |
| 🧠 **Auto Memory Extraction** | Extracts facts, preferences, skills, and relationships without manual tagging |
| 🤖 **Agent-Ready Retrieval** | One-call context loading — scoped, ranked, and ready for injection into any agent |
| 💰 **10x Token Reduction** | Compressed, structured memory eliminates redundant context and cuts LLM costs dramatically |
| 🎯 **Intent Capture** | Continuously understands and updates user goals and preferences across sessions |
| 🔄 **24/7 Proactive Updates** | Memory evolves in the background — agents always have fresh context without re-ingesting |

---

## 🔄 Proactive Memory Lifecycle

```
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│                                         USER QUERY                                               │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘
                 │                                                           │
                 ▼                                                           ▼
┌────────────────────────────────────────┐         ┌────────────────────────────────────────────────┐
│         🤖 MAIN AGENT                  │         │              🧠 MEMU BOT                        │
│                                        │         │                                                │
│  Handle user queries & execute tasks   │  ◄───►  │  Monitor, memorize & proactive intelligence    │
├────────────────────────────────────────┤         ├────────────────────────────────────────────────┤
│                                        │         │                                                │
│  ┌──────────────────────────────────┐  │         │  ┌──────────────────────────────────────────┐  │
│  │  1. RECEIVE USER INPUT           │  │         │  │  1. MONITOR INPUT/OUTPUT                 │  │
│  │     Parse query, understand      │  │   ───►  │  │     Observe agent interactions           │  │
│  │     context and intent           │  │         │  │     Track conversation flow              │  │
│  └──────────────────────────────────┘  │         │  └──────────────────────────────────────────┘  │
│                 │                      │         │                    │                           │
│                 ▼                      │         │                    ▼                           │
│  ┌──────────────────────────────────┐  │         │  ┌──────────────────────────────────────────┐  │
│  │  2. PLAN & EXECUTE               │  │         │  │  2. MEMORIZE & EXTRACT                   │  │
│  │     Break down tasks             │  │   ◄───  │  │     Store insights, facts, preferences   │  │
│  │     Call tools, retrieve data    │  │  inject │  │     Extract skills & knowledge           │  │
│  │     Generate responses           │  │  memory │  │     Update user profile                  │  │
│  └──────────────────────────────────┘  │         │  └──────────────────────────────────────────┘  │
│                 │                      │         │                    │                           │
│                 ▼                      │         │                    ▼                           │
│  ┌──────────────────────────────────┐  │         │  ┌──────────────────────────────────────────┐  │
│  │  3. RESPOND TO USER              │  │         │  │  3. PREDICT USER INTENT                  │  │
│  │     Deliver answer/result        │  │   ───►  │  │     Anticipate next steps                │  │
│  │     Continue conversation        │  │         │  │     Identify upcoming needs              │  │
│  └──────────────────────────────────┘  │         │  └──────────────────────────────────────────┘  │
│                 │                      │         │                    │                           │
│                 ▼                      │         │                    ▼                           │
│  ┌──────────────────────────────────┐  │         │  ┌──────────────────────────────────────────┐  │
│  │  4. LOOP                         │  │         │  │  4. RUN PROACTIVE TASKS                  │  │
│  │     Wait for next user input     │  │   ◄───  │  │     Pre-fetch relevant context           │  │
│  │     or proactive suggestions     │  │  suggest│  │     Prepare recommendations              │  │
│  └──────────────────────────────────┘  │         │  │     Update todolist autonomously         │  │
│                                        │         │  └──────────────────────────────────────────┘  │
└────────────────────────────────────────┘         └────────────────────────────────────────────────┘
                 │                                                           │
                 └───────────────────────────┬───────────────────────────────┘
                                             ▼
                              ┌──────────────────────────────┐
                              │     CONTINUOUS SYNC LOOP     │
                              │  Agent ◄──► MemU Bot ◄──► DB │
                              └──────────────────────────────┘
```

---

## 🎯 Use Cases

### 1. **Customer-Facing AI Agent (B2B)**
*Build agents that remember every customer interaction and act on accumulated context*
```python
# Ingest customer workspace: emails, tickets, chat history
await service.memorize(resource_url="customer_workspace/", modality="conversation", user={"user_id": "acme-corp"})

# Agent retrieves full customer context before responding
context = await service.retrieve(queries=[{"role": "