Metadata-Version: 2.4
Name: memall-os
Version: 0.1.3
Summary: Multi-agent collaborative memory OS
Project-URL: Homepage, https://github.com/j19800/MemALL
Project-URL: Repository, https://github.com/j19800/MemALL
Project-URL: BugTracker, https://github.com/j19800/MemALL/issues
Project-URL: Changelog, https://github.com/j19800/MemALL/releases
Author: MemALL Contributors
License: MIT
License-File: LICENSE
Keywords: agent-memory,ai-agents,knowledge-base,llm,mcp,memory,multi-agent,semantic-search,vector-database
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: fastapi>=0.100.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: sqlite-vec>=0.1.9
Requires-Dist: uvicorn>=0.20.0
Requires-Dist: win10toast>=0.9; sys_platform == 'win32'
Provides-Extra: dev
Requires-Dist: autoflake>=2.0.0; extra == 'dev'
Requires-Dist: flake8>=7.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Provides-Extra: faiss
Requires-Dist: faiss-cpu>=1.14.0; extra == 'faiss'
Provides-Extra: full
Requires-Dist: memall[faiss,viz]; extra == 'full'
Provides-Extra: rerank
Requires-Dist: sentence-transformers>=3.0.0; extra == 'rerank'
Provides-Extra: viz
Requires-Dist: matplotlib>=3.0.0; extra == 'viz'
Requires-Dist: networkx>=3.0; extra == 'viz'
Requires-Dist: pyvis>=0.3.0; extra == 'viz'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT License">
  <img src="https://img.shields.io/badge/python-3.9%2B-blue" alt="Python 3.9+">
  <img src="https://img.shields.io/badge/MCP-2025--03--26-purple" alt="MCP">
  <img src="https://img.shields.io/github/stars/j19800/MemALL?style=social" alt="GitHub stars">
</p>

<h1 align="center">MemALL</h1>
<p align="center"><strong>Multi-agent Memory OS</strong> — 本地优先的 AI Agent 持久化记忆系统</p>

<p align="center">
  <i>38 MCP tools · 10-layer memory lifecycle · Self-evolving pipeline · Knowledge graph · Multi-agent shared memory</i>
</p>

<p align="center">
  <b>English</b> · <a href="README.zh-CN.md">中文</a>
</p>

---

## ✨ What is MemALL?

MemALL gives AI Agents **memory that persists across sessions, tools, and agents**. Install it, connect it to Claude Desktop / Cursor / Cline / any MCP client, and your agents stop starting from scratch every conversation.

```bash
pip install memall-os          # install (lightweight, no AI models)
pip install memall-os[full]    # install + viz + FAISS
pip install memall-os[rerank]  # install + cross-encoder reranking (HEAVY: ~1.8GB, requires PyTorch)
memall init                    # initialize
memall start                   # start services
# → MCP ready at http://127.0.0.1:9876/mcp
# → MCP ready at stdio (add to your mcp.json)
```

Then in any MCP client:

```json
{
  "mcpServers": {
    "memall": {
      "command": "memall",
      "args": ["serve"]
    }
  }
}
```

```python
# /capture "Decided to go open-source: MIT license, GitHub-first distribution"
# /retrieve "pricing decision"
# → finds the memory above, plus its context, timestamp, and relations
```

---

## 🔥 Why MemALL?

### 🧠 10-Layer Memory Lifecycle

Not just "store and retrieve". Every memory has a semantic level:

| Level | Meaning | Example |
|-------|---------|---------|
| P0/P1/P2 | Planning | "Ship v0.1.0 by June 23" |
| L1 | Raw fact | "User reported login bug" |
| L3 | Business idea | "MemPort — cross-platform memory migration" |
| L4 | Decision | "Use FastAPI, not Flask" |
| L5 | Discussion | Multi-agent debate with convergence |
| **L6** | **Self-reflection** | "What went well/badly this session" |
| **L9** | **Distillation** | "10k conversations → 200 knowledge nodes" |
| **L10** | **System insight** | Cross-domain pattern detection |

**22-step auto pipeline** enriches → classifies → time-slices → reflects → distills → integrates. No manual CRUD needed.

### 🔗 Knowledge Graph

Memories are connected by typed edges (`refines`, `cites`, `contradicts`, `supersedes`). Traverse from "bug #123" to "fix PR #456" to "retrospective L6 reflection" in one hop.

```
/capture "Bug #123: OOM on large datasets"
/connect 123 456 --relation "resolved_by"
/traverse 123
→ finds #456 (fix), #789 (regression test), #912 (L6 reflection)
```

### 🤝 Multi-Agent Shared Memory

Claude, opencode, Codex, WorkBuddy — all reading from and writing to the same memory base. Cross-agent queries are a single MCP call.

```
/fed_query "architecture decision last week" agent_name="claude"
→ returns cross-agent results with source attribution
```

### 🔄 Self-Evolving Pipeline

MemALL doesn't just store — it **improves itself**:

1. **L6 Reflection** — auto-reviews work quality, identifies patterns, corrects mistakes
2. **L9 Distillation** — compresses raw conversations into structured knowledge
3. **Forget & Adaptive** — TTL-based decay, low-value cleanup, automatic re-indexing
4. **OODA Loop** — Observe → Orient → Decide → Act, no human intervention

### 🏠 100% Local

SQLite + FTS5 + vector search. Zero cloud dependency. Your data stays on your machine.

---

## 🛠️ 38 MCP Tools

| Category | Tools |
|----------|-------|
| **Memory CRUD** | `capture`, `retrieve`, `update`, `smart_store`, `store_batch` |
| **Knowledge Graph** | `connect`, `traverse`, `timeline` |
| **Search** | `vector_search`, FTS5 full-text search, `hybrid_search` (FTS5+vec0 RRF, optional cross-encoder[¹]) |
| **Session** | `session_start`, `session_end`, `session_summary` |
| **Identity & Persona** | `persona`, `persona_profile`, `identity`, `ask` |
| **Discussion & Decision** | `discussion_create`, `discussion_respond`, `discussion_status`, `trace` |
| **Federation** | `fed_query`, `fed_publish`, `fed_conflicts`, `fed_inject`, `fed_extract` |
| **Hub Sync** | `hub_connect`, `hub_sync` |
| **Pipeline & Evolution** | `run_pipeline`, `reflect_interact`, `forget`, `adaptive`, `index_rebuild` |
| **Security & Ops** | `security`, `ops`, `gateway`, `db` |
| **Onboarding** | `onboarding` |
| **Export/Import** | `export`, `import`, `sync` |

---

## 🚀 Quick Start

```bash
# 1. Install
pip install memall-os

# 2. Initialize
memall init
memall start

# 3. Connect your MCP client
# Add to your mcp.json:
# {
#   "mcpServers": {
#     "memall": { "command": "memall", "args": ["serve"] }
#   }
# }

# 4. Start remembering
/capture "Project X: decided to use FastAPI, reason: async support"
/capture "Fixed OOM bug in NLP pipeline — root cause: vector dimension mismatch"
/retrieve "FastAPI decision"
```

Or clone from source:
```bash
git clone https://github.com/j19800/MemALL
cd memall
pip install -e .
```

---

## 📊 Why Not Competitors?

| Feature | MemALL | Mem0 | Letta | Zep |
|---------|--------|------|-------|-----|
| **Memory model** | 10 layers (P0-L10) | user/session | agent/memory-block | session/summary |
| **Knowledge graph** | ✅ Native + traversal | ❌ | ❌ | ❌ |
| **Self-evolving pipeline** | ✅ 22-step auto | ❌ | ❌ | ❌ |
| **Multi-agent shared** | ✅ Federation | ❌ | Same agent only | ❌ |
| **Decision tracking** | ✅ Arc lifecycle | ❌ | ❌ | ❌ |
| **Discussion convergence** | ✅ Multi-agent auto | ❌ | ❌ | ❌ |
| **Protocol** | **MCP (native)** | REST API | REST + gRPC | REST API |
| **Local-first** | ✅ SQLite | ❌ Cloud | PostgreSQL | ❌ Cloud |
| **Open source** | ✅ MIT | ⚠️ Partial | ✅ | ⚠️ Partial |

---

## 📁 Project Structure

```
src/memall/
├── cli/          # CLI (40+ commands)
├── core/         # SQLite / NLP / vector search
├── api/          # FastAPI REST (35 routes)
├── mcp/          # MCP adapter (38 tools)
├── pipeline/     # 22-step auto pipeline
├── graph/        # Knowledge graph
├── federation/   # Cross-device memory sync
├── plugins/      # Dashboard / export / scheduler
└── migrations/   # DB migrations
```

---

## 📝 Roadmap

- [x] **v0.1.0** — Core MCP server, 38 tools, CLI, PyPI package
- [ ] **v0.2.0** — Web dashboard, user system, Pro tier gating
- [ ] **v0.3.0** — Cloud sync, team collaboration, API gateway

---

## 🤝 Contributing

PRs welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

- Report bugs → [Issues](https://github.com/j19800/MemALL/issues)
- Ask questions → [Discussions](https://github.com/j19800/MemALL/discussions)
- Browse the code → [Repository](https://github.com/j19800/MemALL)

---

## 📄 License

MIT License. See [LICENSE](LICENSE) for details.

> [¹] Cross-encoder reranking requires `pip install memall-os[rerank]` (downloads PyTorch + ~560MB model on first use). Core search works without it using RRF fusion of FTS5 + vec0.
