OpenMemory

VS Code Extension • Report Bug • Request Feature • Discord server

Long‑term memory for AI systems. Self‑hosted. Local‑first. Explainable. Scalable. A full cognitive memory engine — not a vector database. Add Memory to AI/Agents in one line.

🔥 Spread the Word!

    

Why OpenMemory?

Traditional Vector DBs require extensive setup, cloud dependencies, and vendor lock-in:

# The old way: Pinecone + LangChain (12+ lines)
import os
import time
from langchain.chains import ConversationChain
from langchain.memory import VectorStoreRetrieverMemory
from langchain_community.vectorstores import Pinecone
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

os.environ["PINECONE_API_KEY"] = "sk-..."
os.environ["OPENAI_API_KEY"] = "sk-..."
time.sleep(3)  # Wait for cloud initialization

embeddings = OpenAIEmbeddings()
pinecone = Pinecone.from_existing_index(embeddings, index_name="my-memory")
retriever = pinecone.as_retriever(search_kwargs=dict(k=2))
memory = VectorStoreRetrieverMemory(retriever=retriever)
conversation = ConversationChain(llm=ChatOpenAI(), memory=memory)

# Usage (requires explicit chain call)
conversation.predict(input="I'm allergic to peanuts")

OpenMemory needs just 3 lines:

# The new way: OpenMemory (3 lines)
from openmemory import OpenMemory

om = OpenMemory(mode="local", path="./memory.db", tier="deep", embeddings={"provider": "ollama"})
om.add("User allergic to peanuts", userId="user123")
results = om.query("allergies", filters={"user_id": "user123"})
# Returns: [{"content": "User allergic to peanuts", "score": 0.89, ...}]

✅ Zero cloud setup • ✅ Local SQLite • ✅ Works offline • ✅ No vendor lock-in

---

⚡ Standalone Mode (New!)

OpenMemory now works without a backend server. Run the full cognitive engine directly inside your Node.js or Python application.

• Zero Config: npm install and go.
• Local Storage: Data lives in a local SQLite file.
• Privacy: No data leaves your machine.

👉 Read the Standalone Guide

1. Introduction

Modern LLMs forget everything between messages. Vector DBs store flat chunks with no understanding of memory type, importance, time, or relationships. Cloud memory APIs add cost and vendor lock‑in.

OpenMemory solves this. It gives AI systems:

• persistent memory
• multi‑sector cognitive structure
• natural decay
• graph‑based recall
• time‑aware fact tracking
• explainability through waypoint traces
• complete data ownership
• MCP integration
• and much more

OpenMemory acts as the Memory OS for your AI agents, copilots, and applications. On top of this, you can easily migrate from Mem0, Zep, Supermemory to OpenMemory in just one command.

---

Competitor Comparison

Feature / Metric	OpenMemory (Our Tests – Nov 2025)	Zep (Their Benchmarks)	Supermemory (Their Docs)	Mem0 (Their Tests)	OpenAI Memory	LangChain Memory	Vector DBs (Chroma / Weaviate / Pinecone)
Open-source License	✅ Apache 2.0	✅ Apache 2.0	✅ Source available (GPL-like)	✅ Apache 2.0	❌ Closed	✅ Apache 2.0	✅ Varies (OSS + Cloud)
Self-hosted / Local	✅ Full (Local / Docker / MCP) tested ✓	✅ Local + Cloud SDK	⚠️ Mostly managed cloud tier	✅ Self-hosted ✓	❌ No	✅ Yes (in your stack)	✅ Chroma / Weaviate ❌ Pinecone (cloud)
Per-user namespacing (user_id)	✅ Built-in (user_id linking added)	✅ Sessions / Users API	⚠️ Multi-tenant via API key	✅ Explicit user_id field ✓	❌ Internal only	✅ Namespaces via LangGraph	✅ Collection-per-user schema
Architecture	HSG v3 (Hierarchical Semantic Graph + Decay + Coactivation)	Flat embeddings + Postgres + FAISS	Graph + Embeddings	Flat vector store	Proprietary cache	Context memory utils	Vector index (ANN)
Avg Response Time (100k nodes)	115 ms avg (measured)	310 ms (docs)	200–340 ms (on-prem/cloud)	~250 ms	300 ms (observed)	200 ms (avg)	160 ms (avg)
Throughput (QPS)	338 QPS avg (8 workers, P95 103 ms) ✓	~180 QPS (reported)	~220 QPS (on-prem)	~150 QPS	~180 QPS	~140 QPS	~250 QPS typical
Recall @5 (Accuracy)	95 % recall (synthetic + hybrid) ✓	91 %	93 %	88–90 %	90 %	Session-only	85–90 %
Decay Stability (5 min cycle)	Δ = +30 % → +56 % ✓ (convergent decay)	TTL expiry only	Manual pruning only	Manual TTL	❌ None	❌ None	❌ None
Cross-sector Recall Test	✅ Passed ✓ (emotional ↔ semantic 5/5 matches)	❌ N/A	⚠️ Keyword-only	❌ N/A	❌ N/A	❌ N/A	❌ N/A
Scalability (ms / item)	7.9 ms/item @10k+ entries ✓	32 ms/item	25 ms/item	28 ms/item	40 ms (est.)	20 ms (local)	18 ms (optimized)
Consistency (2863 samples)	✅ Stable ✓ (0 variance >95%)	⚠️ Medium variance	⚠️ Moderate variance	⚠️ Inconsistent	❌ Volatile	⚠️ Session-scoped	⚠️ Backend dependent
Decay Δ Trend	Stable decay → equilibrium after 2 cycles ✓	TTL drop only	Manual decay	TTL only	❌ N/A	❌ N/A	❌ N/A
Memory Strength Model	Salience + Recency + Coactivation ✓	Simple recency	Frequency-based	Static	Proprietary	Session-only	Distance-only
Explainable Recall Paths	✅ Waypoint graph trace ✓	❌	⚠️ Graph labels only	❌ None	❌ None	❌ None	❌ None
Cost / 1M tokens (hosted embeddings)	~$0.35 (synthetic + Gemini hybrid ✓)	~$2.2	~$2.5+	~$1.2	~$3.0	User-managed	User-managed
Local Embeddings Support	✅ (Ollama / E5 / BGE / synthetic fallback ✓)	⚠️ Partial	✅ Self-hosted tier ✓	✅ Supported ✓	❌ None	⚠️ Optional	✅ Chroma / Weaviate ✓
Ingestion Formats	✅ PDF / DOCX / TXT / MD / HTML / Audio / Video ✓	✅ API ✓	✅ API ✓	✅ SDK ✓	❌ None	⚠️ Manual ✓	⚠️ SDK specific ✓
Scalability Model	Sector-sharded (semantic / episodic / etc.) ✓	PG + FAISS cloud ✓	PG shards (cloud) ✓	Single node	Vendor scale	In-process	Horizontal ✓
Deployment	Local / Docker / Cloud ✓	Local + Cloud ✓	Docker / Cloud ✓	Node / Python ✓	Cloud only ❌	Python / JS SDK ✓	Docker / Cloud ✓
Data Ownership	100 % yours ✓	Vendor / self-host split ✓	Partial ✓	100 % yours ✓	Vendor ❌	Yours ✓	Yours ✓
Use-case Fit	Long-term AI agents, copilots, journaling ✓	Enterprise RAG assistants ✓	Cognitive agents / journaling ✓	Basic agent memory ✓	ChatGPT personalization ❌	Context memory ✓	Generic vector store ✓

Migration

OpenMemory includes a robust migration tool to import billions of memories from other systems.

Supported Providers

• Mem0 — user-based export
• Zep — sessions/messages API
• Supermemory — document export

Example

cd migrate
node index.js --from zep --api-key ZEP_KEY --verify

---

Installation & Setup (Three Ways)

OpenMemory supports all three usage modes:

• Node.js SDK (local-first)
• Python SDK (local-first)
• Backend Server (web + API)

---

JavaScript SDK (Local-First)

Install:

npm install openmemory-js

Use:

import { OpenMemory } from "openmemory-js"
const mem = new OpenMemory()

• Runs fully locally
• Zero configuration
• Fastest integration path

---

Python SDK (Local-First)

Install:

pip install openmemory-py

Use:

from openmemory import Memory
mem = Memory()

• Same cognitive engine as JS
• Ideal for LangGraph, notebooks, research

---

Backend Server (Web + API)

Use this mode for:

• Multi-user apps
• Dashboards
• Cloud agents
• Centralized org-wide memory

Setup:

``` git clone https://github.