xMemory 4-Layer Architecture · Smart Classification · Auto-Extraction · Multi-IDE Support
Quick Start • Features • Architecture • Supported IDEs • Docs
OpenMemory Plus is a unified memory management framework for AI Agents, featuring xMemory 4-Layer Architecture:
- L3 Theme — Theme clustering layer, auto-aggregates high-level concepts
- L2 Semantic — Semantic memory layer, BGE-M3 vector retrieval
- L1 Episode — Episodic memory layer, conversation context
- L0 Message — Raw message layer
Give any AI Agent persistent memory in 5 minutes.
 Auto Memory Extraction |
 Extraction Result |
Have you experienced these problems?
| 😤 Pain Point | 📖 Scenario |
|---|---|
| Multi-CLI Memory Silos | Using Gemini, Augment, Claude, Cursor simultaneously - each has isolated memory |
| Agent Amnesia | Every new conversation, Agent forgets who you are, where the project is |
| Repeated Self-Introduction | After switching CLI, you have to tell Agent again: I like TypeScript, use pnpm... |
| Fragmented Config | Deploy URL in Slack, API Key in notes, paths in your head |
| Lost Context | Technical decisions discussed in Claude yesterday, Augment doesn't remember today |
🔗 Unified Memory Layer for Multiple CLIs
┌─────────────────────────────────────────────────────────────┐
│ Without OpenMemory Plus │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Gemini │ │ Augment │ │ Claude │ │ Cursor │ │
│ │ CLI │ │ Agent │ │ Code │ │ Agent │ │
│ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ │
│ │Memory A │ │Memory B │ │Memory C │ │Memory D │ │
│ │(isolated)│ │(isolated)│ │(isolated)│ │(isolated)│ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ ❌ Isolated - must repeat preferences everywhere │
│ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ With OpenMemory Plus │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ Gemini │ │ Augment │ │ Claude │ │ Cursor │ │
│ │ CLI │ │ Agent │ │ Code │ │ Agent │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │
│ └─────────────┴──────┬──────┴─────────────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ OpenMemory │ │
│ │ Plus Layer │ │
│ ├───────────────┤ │
│ │ • Preferences │ │
│ │ • Tech Stack │ │
│ │ • Project Config│ │
│ │ • Decisions │ │
│ └───────────────┘ │
│ ✅ One memory, everywhere. Seamless CLI switching │
│ │
└─────────────────────────────────────────────────────────────┘
💬 Real Conversation Comparison
┌─────────────────────────────────────────────────────────────┐
│ [Gemini CLI] Morning │
│ User: I prefer TypeScript and pnpm │
│ Gemini: Got it, preferences saved ✅ │
├─────────────────────────────────────────────────────────────┤
│ [Augment] Afternoon - Switch CLI │
│ User: Initialize a new project │
│ Augment: Sure! Using TypeScript + pnpm based on your prefs │
│ (Auto-loaded from Gemini's saved preferences) ✅ │
├─────────────────────────────────────────────────────────────┤
│ [Claude Code] Evening - Switch again │
│ User: Check code style │
│ Claude: I see you prefer functional style, checking... │
│ (All CLIs share the same memory) ✅ │
└─────────────────────────────────────────────────────────────┘
| User Type | Use Case |
|---|---|
| Solo Developers | Multi-project development, want Agent to remember each project's config |
| Full-Stack Engineers | Frequently switch between frontend/backend, need Agent to remember tech preferences |
| AI Tool Power Users | Use Cursor, Claude, Augment simultaneously, want shared memory |
| Team Tech Leads | Want version-controlled project config, new members' Agents auto-get context |
🔧 Use Case 1: Project Config Management
Scenario: You have 5 projects, each with different deployment configs
Without OpenMemory Plus:
- Must tell Agent project path every time
- Must provide deploy URL every time
- Must explain project structure every time
With OpenMemory Plus:
<!-- _omp/memory/techContext.md (auto-generated) -->
## Deployment Config
- Vercel URL: https://my-app.vercel.app
- Project ID: prj_xxx
## Project Paths
- Root: /Users/me/projects/my-app
- Src: ./src
- Tests: ./testsAgent reads automatically, no need to repeat.
🎨 Use Case 2: Cross-Project Preference Sync
Scenario: You prefer TypeScript, Tailwind, pnpm
Without OpenMemory Plus:
- Must tell Agent your preferences for every new project
- Preferences lost when switching IDE
With OpenMemory Plus:
openmemory (user-level, cross-project):
├── "User preference: Use TypeScript over JavaScript"
├── "User preference: Use pnpm over npm"
├── "User preference: Use Tailwind CSS"
└── "User skill: Familiar with React, Next.js, Node.js"
Any project, any IDE, Agent knows your preferences.
📝 Use Case 3: Tech Decision Tracking
Scenario: Team decided to use PostgreSQL instead of MongoDB
Without OpenMemory Plus:
- Decision recorded in Slack/Notion, Agent doesn't know
- Next time Agent might suggest MongoDB again
With OpenMemory Plus:
<!-- _omp/memory/techContext.md (auto-recorded) -->
## Tech Decisions
### Database Selection (2026-02-01)
- **Choice**: PostgreSQL
- **Alternatives**: MongoDB, MySQL
- **Rationale**: Need complex queries and transaction supportAgent remembers decisions, won't suggest rejected options again.
🔄 Use Case 4: Multi-CLI Memory Sharing (Core Scenario)
Scenario: You use Gemini CLI, Augment, Claude Code, Cursor simultaneously
Without OpenMemory Plus:
😤 Daily pain cycle:
[Morning - Gemini CLI]
User: I like TypeScript, use pnpm
Gemini: Got it!
[Noon - Switch to Augment]
User: Create a component
Augment: JavaScript or TypeScript? ← Have to say again
User: TypeScript...
Augment: npm or yarn? ← Have to say again
User: pnpm... 😤
[Afternoon - Switch to Claude Code]
Claude: Hello! What's your tech stack preference? ← Again...
User: ...... 😭
With OpenMemory Plus:
✅ Tell once, works everywhere:
[Morning - Gemini CLI]
User: I like TypeScript, use pnpm
Gemini: Got it, saved! → Stored in openmemory
[Noon - Switch to Augment]
User: Create a component
Augment: Sure! Creating with TypeScript + pnpm... ← Auto-loaded
(I know your preferences 😊)
[Afternoon - Switch to Claude Code]
User: Check code style
Claude: Checking based on your TypeScript preference... ← Auto-loaded
Found 3 optimizations ✅
[Evening - Switch to Cursor]
Cursor: I see you created new components in other CLIs today,
want me to write tests? ← Even knows what you did today
npx openmemory-plus installThe install wizard will guide you through:
- ✅ Detect system dependencies (Docker, Qdrant, Ollama, BGE-M3)
- ✅ Docker Compose one-click deploy (recommended) or native install
- ✅ Select IDE type
- ✅ Initialize project config
- ✅ Show next steps
Just install Docker, everything else is handled automatically!
# Option 1: Auto-detect and use Docker Compose during install
npx openmemory-plus install
# Option 2: Explicitly use Docker Compose mode
npx openmemory-plus install --compose
# Option 3: Manually manage dependency services
omp deps init # Initialize config
omp deps up # Start services (Qdrant + Ollama + BGE-M3)
omp deps status # Check status
omp deps down # Stop servicesBenefits:
- 🎯 Only need to install Docker
- ⚡ One command starts all services
- 📦 BGE-M3 model auto-downloads
- 💾 Data persists across restarts
After installation, use in your AI Agent conversations:
/memory # Show memory status + quick menu
/mem search <query> # Search memories
/mem sync # Sync and detect conflicts
/mem clean # Clean outdated memories
| Dependency | Version | Purpose |
|---|---|---|
| Node.js | >= 18.0.0 | Run CLI |
| Docker | Latest | Only required dependency (Docker Compose mode) |
| Ollama | Latest | Run BGE-M3 embedding model (native mode only) |
- 🔄 Dual-Layer Memory — Project-level + User-level separated storage
- 🎯 Smart Classification — Auto-determine where to store information
- 🔍 Semantic Search — Multi-language vector search with BGE-M3
- ⚡ Event-Driven Extraction — Auto-trigger memory extraction Skill at conversation end
- 🔐 Sensitive Info Filter — Auto-detect and block API Keys, passwords
Support multiple LLM Providers for memory classification:
| Provider | Model | Notes |
|---|---|---|
| DeepSeek | deepseek-chat | 🔥 Recommended, cost-effective |
| MiniMax | abab6.5s-chat | Chinese optimized |
| ZhiPu | glm-4-flash | Chinese LLM |
| Qwen | qwen-turbo | Alibaba Cloud |
| OpenAI | gpt-4o-mini | International standard |
| Ollama | local model | Offline available |
- 🔀 Conflict Detection — Auto-detect data conflicts between layers
- 🧹 ROT Cleanup — Clean Redundant, Obsolete, Trivial memories
- 📊 Fallback Strategy — Auto-fallback to local storage when MCP unavailable
- 🔧 Progressive Config — Append to existing files instead of overwriting
┌─────────────────────────────────────────────────────────────┐
│ OpenMemory Plus │
├─────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ /memory │ │ /mem xxx │ │ Auto-Extract│ │
│ │ (entry) │ │ (subcommand)│ │ (Skill) │ │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
│ └──────────────────┼──────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Memory Router (Smart Classification) │ │
│ └─────────────────────────────────────────────────────┘ │
│ │ │
│ ┌──────────────────┼──────────────────┐ │
│ ↓ ↓ │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ _omp/memory/ │ │ openmemory │ │
│ │ (project-level)│ │ (user-level) │ │
│ ├─────────────────┤ ├─────────────────┤ │
│ │ • project.yaml │ │ • Vector DB │ │
│ │ • decisions.yaml│ │ • Semantic Search│ │
│ │ • Git versioned │ │ • MCP Protocol │ │
│ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
| Info Type | Storage Location | Examples |
|---|---|---|
| Project Config | _omp/memory/*.md |
Deploy URL, env vars, paths |
| Tech Decisions | _omp/memory/techContext.md |
Framework choices, architecture |
| User Preferences | openmemory (MCP) |
Language preference, code style |
| User Skills | openmemory (MCP) |
Familiar tech stack, experience |
💡 Note: After installation, project-level memory is stored in
_omp/memory/directory, which is added to Git version control.
|
Augment ✅ Full Support
|
Claude Code ✅ Full Support
|
Cursor ✅ Full Support
|
Gemini CLI ✅ Full Support
|
# Interactive install (recommended)
npx openmemory-plus install
# Use Docker Compose one-click deploy (recommended)
npx openmemory-plus install --compose
# Silent install
npx openmemory-plus install -y
# Specify IDE
npx openmemory-plus install --ide augment
# Specify LLM Provider (for memory classification)
npx openmemory-plus install --llm deepseek
# Config only, skip dependency check
npx openmemory-plus install --skip-deps
# Show MCP config
npx openmemory-plus install --show-mcp| Provider | Command | Environment Variable |
|---|---|---|
| DeepSeek | --llm deepseek |
DEEPSEEK_API_KEY |
| MiniMax | --llm minimax |
MINIMAX_API_KEY |
| ZhiPu | --llm zhipu |
ZHIPU_API_KEY |
| Qwen | --llm qwen |
DASHSCOPE_API_KEY |
| OpenAI | --llm openai |
OPENAI_API_KEY |
| Ollama | --llm ollama |
(local, no API Key) |
# Initialize Docker Compose config
omp deps init
# Start all dependency services (Qdrant + Ollama + BGE-M3)
omp deps up
# Pull latest images before starting
omp deps up --pull
# Stop all services
omp deps down
# Check service status
omp deps status
# View service logs
omp deps logs # All services
omp deps logs ollama # Specific service
omp deps logs -f # Follow output
# Manually download BGE-M3 model
omp deps pull-model# Check system status
npx openmemory-plus status
# Diagnose issues
npx openmemory-plus doctor
# Auto-fix
npx openmemory-plus doctor --fix| Command | Description |
|---|---|
/memory |
Show quick status + submenu |
/mem status |
Detailed memory status |
/mem search {query} |
Semantic search memories |
/mem store |
Manually store memories |
/mem sync |
Detect and resolve conflicts |
/mem clean |
Clean ROT memories |
/mem decay |
Time decay analysis |
/mem graph |
Knowledge graph visualization |
openmemory-plus/
├── cli/ # CLI tool source
│ ├── src/
│ │ ├── commands/ # install, status, doctor
│ │ └── lib/ # Core library
│ └── templates/ # Template files
│ └── shared/ # Shared templates
│ └── _omp/ # Core directory template
├── docs/ # Documentation
│ └── architecture.md # Architecture design
├── AGENTS.md # AI Agent config entry
└── README.md # This file
# After installation in your project (Augment example):
your-project/
├── _omp/ # OpenMemory Plus core directory (shared by all IDEs)
│ ├── AGENTS.md # Complete Agent rules file
│ ├── memory/ # Project-level memory storage
│ │ ├── projectbrief.md # Project overview
│ │ ├── productContext.md # Product requirements
│ │ ├── techContext.md # Tech stack
│ │ ├── activeContext.md # Current session context
│ │ ├── systemPatterns.md # Patterns & conventions
│ │ ├── decisions.yaml # Architecture decisions log
│ │ └── progress.md # Task progress
│ ├── commands/ # Agent commands
│ │ └── memory.md # Main command entry
│ ├── workflows/ # Workflows
│ │ └── memory/ # Memory management workflow (7 steps)
│ └── skills/ # Agent Skills
│ └── memory-extraction/ # Memory extraction Skill (auto-trigger)
│
├── AGENTS.md # Entry file (references _omp/AGENTS.md)
└── .augment/ # IDE-specific directory
├── commands/ # Command entries (linked to _omp)
└── skills/ # Skills (linked to _omp)
| Component | Technology | Purpose |
|---|---|---|
| CLI | TypeScript + Commander | Command-line tool |
| Vector DB | Qdrant | Store user memory vectors |
| Embedding | BGE-M3 (via Ollama) | Multi-language text embedding |
| Protocol | MCP (Model Context Protocol) | Agent communication |
| Project Storage | YAML + Git | Version-controlled config files |
| Feature | OpenMemory Plus | Pure openmemory MCP | Native mem0 SDK | Manual .env | Notion/Docs |
|---|---|---|---|---|---|
| Auto Extraction | ✅ Auto-trigger at conversation end | ❌ | ❌ | ||
| Dual-Layer | ✅ Project + User | ❌ User-level only | ❌ User-level only | ❌ Project-level only | ❌ |
| Multi-IDE Sharing | ✅ | ✅ | ✅ | ❌ | ❌ |
| Git Version Control | ✅ Project-level traceable | ❌ | ❌ | ✅ | ❌ |
| Semantic Search | ✅ | ✅ | ✅ | ❌ | ❌ |
| Smart Classification | ✅ Auto 7-type classification | ❌ Requires manual metadata | ❌ Requires manual metadata | ❌ | ❌ |
| Sensitive Info Filter | ✅ Auto-block storage | ❌ | ❌ | ||
| One-Click Install | ✅ npx omp install |
❌ Code integration | ❌ | ❌ | |
| ROT Memory Cleanup | ✅ Auto-detect redundant/obsolete | ❌ | ❌ | ❌ | ❌ |
| Ebbinghaus Decay | ✅ Forgetting curve model | ❌ | ❌ | ❌ | ❌ |
Legend: ✅ Full Support |
⚠️ Partial Support | ❌ Not Supported
| Comparison | OpenMemory Plus | Pure openmemory MCP |
|---|---|---|
| Memory Trigger | Auto-extract at conversation end, no user intervention | Agent must call add_memories tool |
| Project Context | _omp/memory/ stores project decisions & architecture |
No project-level memory, all mixed at user level |
| Memory Classification | Auto-classify into preferences/decisions/patterns | Requires manual metadata parameter |
| Memory Health | ROT detection + health scoring + decay model | None, memories only increase |
| IDE Configuration | Auto-generate AGENTS.md/CLAUDE.md etc. | Manual config for each IDE |
Q: What's the relationship between OpenMemory Plus and mem0?
A: OpenMemory Plus is an enhancement layer for mem0, not a replacement.
- mem0 provides underlying vector storage and semantic search
- OpenMemory Plus adds on top:
- Dual-layer memory architecture (project + user level)
- Smart classification and auto-extraction
- Multi-IDE unified configuration
- Sensitive information filtering
You need to install mem0/openmemory MCP first, then use OpenMemory Plus to enhance it.
Q: Where is my data stored? Is it secure?
A: Data is stored in two places:
| Location | Data Type | Security |
|---|---|---|
_omp/memory/ (local) |
Project config, tech decisions | ✅ Local files, Git versioned |
openmemory (Qdrant) |
User preferences, skills | ✅ Local Docker container |
- All data is on your local machine
- Sensitive info (API Keys, passwords) is auto-filtered, never stored
- Project-level data can be excluded via
.gitignore
Q: Which IDEs/Agents are supported?
A: Currently fully supported:
| IDE | Config File | Status |
|---|---|---|
| Augment | AGENTS.md |
✅ Full Support |
| Claude Code | CLAUDE.md |
✅ Full Support |
| Cursor | .cursorrules |
✅ Full Support |
| Gemini CLI | gemini.md |
✅ Full Support |
Other MCP-compatible Agents can also use it with manual configuration.
Q: How to migrate existing projects?
A: Just run the install command:
cd your-existing-project
npx openmemory-plus installThe wizard will:
- Detect existing config
- Create
_omp/memory/directory - Generate IDE config files
- Won't overwrite your existing files
- 🤝 Multi-Agent team memory architecture (Team Shared + Agent Private)
- 🎭 Agent ID Schema (actor attribution, scope filtering)
- 📋 Team configuration file (
_omp/config.yaml) - 🔄 Handoff workflow (agent-to-agent task transfer protocol)
- 📁 Scoped Memory API (dual-layer scoped memory)
- 🧠 xMemory 4-layer architecture (L3 Theme → L2 Semantic → L1 Episode → L0 Message)
- 🎯 L3 theme layer auto-clustering (attach/split/merge algorithms)
- 🔍 Top-down adaptive retrieval (
--level theme) - ⚡ Theme search CLI options (
--no-expand) - 📊 Connected component clustering (xMemory paper implementation)
- Dual-layer memory architecture
- Smart classification routing
- Multi-IDE support (Augment, Claude, Cursor, Gemini)
- CLI install tool
- Sensitive info filtering
- Multi-LLM Provider support (DeepSeek, MiniMax, ZhiPu, Qwen, OpenAI, Ollama)
- Docker Compose one-click deploy
- Progressive config (append to existing files)
- MCP auto-configuration and verification
- Web UI management interface
- Cloud sync option
- Memory analytics and insights
- AI-driven memory organization
Contributions welcome! Please read the Contributing Guide to get started.
# Clone repo
git clone https://github.com/Alenryuichi/openmemory-plus.git
cd openmemory-plus
# Install dependencies
cd cli && npm install
# Run tests
npm test
# Local development
npm run devMIT License © 2026 TreeRen Chou
- OpenMemory (mem0) — Underlying memory service
- Qdrant — Vector database
- BGE-M3 — Multi-language embedding model
- MCP Protocol — Model Context Protocol
Made with ❤️ for AI Agent developers