🧠 MemOS — Universal AI Agent Memory & Context Operating System

The First Persistent Memory Layer for AI Agents

Never lose context again. Your AI agents remember everything.

---

🔥 The Problem

AI agents suffer from Context Amnesia — they forget everything between sessions. According to LangChain's 2025 report, 70% of AI agent failures are caused by context-related issues:

• ❌ Lost project knowledge after each session
• ❌ Repeatedly explaining the same architecture
• ❌ No persistent memory across agent instances
• ❌ Manual skill maintenance becomes a death march
• ❌ Token budgets exploding with verbose context

✅ The Solution: MemOS

MemOS is a universal memory operating system for AI agents. It gives agents a persistent brain — tracking everything they learn about your project across sessions, auto-generating Claude Code/Cursor skills from your codebase, compressing context by 60-95%, and enabling cross-agent knowledge sharing.

🎯 Core Capabilities

Capability	Description	Impact
🧠 Persistent Knowledge Graph	SQLite + ChromaDB hybrid store. Agents remember every file, function, session, and decision.	Never re-explain your architecture
⚡ Smart Context Compression	Content-type-aware compression: JSON minification, code comment stripping, log pattern extraction, Markdown deduplication.	60-95% token reduction
🔄 AutoSkill Extraction	Reverse-engineers your codebase into Claude Code SKILL.md, Cursor rules, and Gemini CLI skills.	Skills auto-sync with code
🔗 Cross-Agent Bus	Publish/subscribe shared context between Claude, Gemini, Cursor, Codex — any MCP-compatible agent.	Multi-agent collaboration
📡 MCP Server	Full Model Context Protocol integration. 7 tools available to any MCP client.	Drop-in for Claude Desktop / Codex CLI
📊 Project Intelligence	Comprehensive reports: knowledge graph stats, skill coverage, bus activity, compression savings.	Data-driven optimization

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      MemOS Engine                           │
├───────────────┬───────────────┬──────────────┬──────────────┤
│   Ingest      │   Compress    │   Remember   │    Recall    │
│   Indexes     │   Reduces     │   Persists   │   Queries    │
│   codebase    │   tokens by   │   session    │   knowledge  │
│               │   60-95%      │   context    │   graph      │
├───────────────┼───────────────┼──────────────┼──────────────┤
│ Extract       │    Share      │   Receive    │   Report     │
│ Skills        │   Cross-      │   Shared     │   Project    │
│ Auto-gen      │   Agent Bus   │   Context    │   Intel      │
└───────────────┴───────────────┴──────────────┴──────────────┘
         │              │              │
    ┌────▼────┐   ┌────▼────┐   ┌────▼────┐
    │ SQLite  │   │ ChromaDB│   │ NetworkX│
    │ Graph   │   │ Vectors │   │ Traversal│
    └─────────┘   └─────────┘   └─────────┘

Subsystems

Subsystem	File	Role
Config	memos/config.py	4-layer configuration (Compression, Knowledge Graph, Skills, Bus)
Engine	memos/core/engine.py	Central orchestrator — ingest(), compress(), remember(), recall()
ContentRouter	memos/compress/router.py	6-mode smart compressor with CCR reversible format
MemGraph	memos/graph/knowledge.py	Persistent graph with FTS, vector search, and traversal
SkillExtractor	memos/skills/extractor.py	Code → Skill.md auto-generator for Claude Code/Gemini/Cursor
CrossAgentBus	memos/bus/shared.py	Pub/sub bus with TTL, agent registry, capability discovery
MCP Server	memos/mcp/server.py	7-tool MCP server for Claude Desktop / Codex CLI
CLI	memos/cli.py	Click-based CLI with 6 commands

🚀 Quick Start

Installation

pip install memos

Or with all optional dependencies:

pip install "memos[all]"

Basic Usage

# Index your project — creates .memos/knowledge.db
memos ingest /path/to/your/project

# Recall relevant context
memos recall "how does authentication work" /path/to/your/project

# Compress context
memos compress "$(cat huge_file.py)" --type code

# Auto-extract skills for Claude Code
memos extract-skills /path/to/your/project --output-dir .claude/skills

# Generate project intelligence report
memos report /path/to/your/project

# Start MCP server for Claude Desktop
memos mcp

MCP Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "memos": {
      "command": "memos",
      "args": ["mcp"]
    }
  }
}

Then use these MCP tools in Claude: memos_remember, memos_recall, memos_compress, memos_extract_skills, memos_share, memos_receive, memos_report.

Python API

from memos import MemOSEngine, MemOSConfig

config = MemOSConfig(
    project_path="/path/to/project",
    data_dir="/path/to/project/.memos",
)
engine = MemOSEngine(project_path="/path/to/project", config=config)

# Ingest project
stats = await engine.ingest()

# Compress context
result = await engine.compress(large_text, content_type="code")
print(f"Saved {result.savings_percent}% tokens")

# Query knowledge graph
nodes = await engine.recall("database connection pooling")
for n in nodes:
    print(f"[{n.type}] {n.title}: {n.content[:200]}")

# Extract skills
skills = await engine.extract_skills()
await engine.extractor.export_skills(skills, output_dir=".claude/skills")

# Persist session
session = engine.create_session()
session.add_message("user", "Fixed auth bug in login.py")
await engine.remember(session)

# Cross-agent sharing
from memos.bus.shared import SharedContext
ctx = SharedContext(
    agent_id="claude_1",
    topic="auth",
    title="Auth Fix",
    content="Fixed race condition in token refresh",
)
await engine.share("claude_1", ctx)

await engine.close()

📊 Compression Algorithms

Content Type	Algorithm	Typical Savings	Reversible
JSON	Structure-preserving minification	40-60%	✅
Code	Comment stripping, whitespace removal	30-55%	✅ (CCR format)
Logs	Pattern extraction, deduplication	70-95%	❌
Markdown	Heading-preserving compaction	40-60%	⚠️ Partial
Shell Output	Path normalization, ANSI stripping	50-80%	❌
Generic Text	Sentence-level dedup + truncation	20-40%	❌

🧪 Testing

# Install dev dependencies
pip install "memos[dev]"

# Run tests
pytest

# With coverage
pytest --cov=memos --cov-report=term-missing

🗺️ Roadmap

• v1.1: Stream real-time context ingestion via file watchers
• v1.2: Graph visualization with memos viz command
• v1.3: Remote knowledge graph sync (MemOS Cloud)
• v1.4: LLM-powered skill refinement (auto-improve extracted skills)
• v2.0: Multi-project federation — share knowledge across projects

📖 Documentation

• Full Documentation
• 5W1H Analysis
• API Reference
• Contributing Guide

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📝 License

MIT License — see LICENSE for details.

🔬 Research Basis

MemOS is built on research from:

• LangChain Context Engineering Report (2025): 70% agent failures from context issues
• Headroom (29K⭐): Multi-agent memory and context compression patterns
• Claude Skills Ecosystem: SKILL.md specification and runtime design
• Cognee / Mem0: Dual-engine memory architectures for AI agents

---

Built with ❤️ for the AI agent ecosystem
GitHub · PyPI · Issues