🚧 This project is currently being rewritten.

Expect breaking changes and potential bugs.

Contributers needed

To contribute, visit https://github.com/CaviraOSS/OpenMemory/tree/rewrite branch. If you find an issue, please open a GitHub issue with details so it can be tracked and resolved.

OpenMemory

Real long-term memory for AI agents. Not RAG. Not a vector DB. Self-hosted, Python + Node.

OpenMemory is a cognitive memory engine for LLMs and agents.

• 🧠 Real long-term memory (not just embeddings in a table)
• 💾 Self-hosted, local-first (SQLite / Postgres)
• 🐍 Python + 🟦 Node SDKs
• 🧩 Integrations: LangChain, CrewAI, AutoGen, Streamlit, MCP, VS Code
• 📥 Sources: GitHub, Notion, Google Drive, OneDrive, Web Crawler
• 🔍 Explainable traces (see why something was recalled)

Your model stays stateless. Your app stops being amnesiac.

---

1. TL;DR – Use It in 10 Seconds

🐍 Python (local-first)

Install:

pip install openmemory-py

Use:

from openmemory.client import Memory

mem = Memory()
mem.add("user prefers dark mode", user_id="u1")
results = mem.search("preferences", user_id="u1")
await mem.delete("memory_id")

Note: add, search, get, delete are async. Use await in async contexts.

🔗 OpenAI

mem = Memory()
client = mem.openai.register(OpenAI(), user_id="u1")
resp = client.chat.completions.create(...)

🧱 LangChain

from openmemory.integrations.langchain import OpenMemoryChatMessageHistory

history = OpenMemoryChatMessageHistory(memory=mem, user_id="u1")

🤝 CrewAI / AutoGen / Streamlit

OpenMemory is designed to sit behind agent frameworks and UIs:

• Crew-style agents: use Memory as a shared long-term store
• AutoGen-style orchestrations: store dialog + tool calls as episodic memory
• Streamlit apps: give each user a persistent memory by user_id

See the integrations section in the docs for concrete patterns.

---

🟦 Node / JavaScript (local-first)

Install:

npm install openmemory-js

Use:

import { Memory } from "openmemory-js"

const mem = new Memory()
await mem.add("user likes spicy food", { user_id: "u1" })
const results = await mem.search("food?", { user_id: "u1" })
await mem.delete("memory_id")

Drop this into:

• Node backends
• CLIs
• local tools
• anything that needs durable memory without running a separate service.

---

📥 Connectors

Ingest data from external sources directly into memory:

# python
github = mem.source("github")
await github.connect(token="ghp_...")
await github.ingest_all(repo="owner/repo")

// javascript
const github = await mem.source("github")
await github.connect({ token: "ghp_..." })
await github.ingest_all({ repo: "owner/repo" })

Available connectors: github, notion, google_drive, google_sheets, google_slides, onedrive, web_crawler

---

2. Modes: SDKs, Server, MCP

OpenMemory can run inside your app or as a central service.

2.1 Python SDK

• ✅ Local SQLite by default
• ✅ Supports external DBs (via config)
• ✅ Great fit for LangChain / LangGraph / CrewAI / notebooks

Docs: https://openmemory.cavira.app/docs/sdks/python

---

2.2 Node SDK

• Same cognitive model as Python
• Ideal for JS/TS applications
• Can either run fully local or talk to a central backend

Docs: https://openmemory.cavira.app/docs/sdks/javascript

---

2.3 Backend server (multi-user + dashboard + MCP)

Use when you want:

• org‑wide memory
• HTTP API
• dashboard
• MCP server for Claude / Cursor / Windsurf

Run from source:

git clone https://github.com/CaviraOSS/OpenMemory.git
cd OpenMemory
cp .env.example .env

cd packages/openmemory-js
npm install
npm run dev   # default :8080

Or with Docker (API + MCP):

docker compose up --build -d

Optional: include the dashboard service profile:

docker compose --profile ui up --build -d

Using Doppler-managed config (recommended for hosted dashboard/API URLs):

cd OpenMemory
tools/ops/compose_with_doppler.sh up -d --build

Check service status:

docker compose ps
curl -f http://localhost:8080/health

The backend exposes:

• /api/memory/* – memory operations
• /api/temporal/* – temporal knowledge graph
• /mcp – MCP server
• dashboard UI (when ui profile is enabled)

---

3. Why OpenMemory (vs RAG, vs “just vectors”)

LLMs forget everything between messages.
Most “memory” solutions are really just RAG pipelines:

• text is chunked
• embedded into a vector store
• retrieved by similarity

They don’t understand:

• whether something is a fact, event, preference, or feeling
• how recent / important it is
• how it links to other memories
• what was true at a specific time

Cloud memory APIs add:

• vendor lock‑in
• latency
• opaque behavior
• privacy problems

OpenMemory gives you an actual memory system:

• 🧠 Multi‑sector memory (episodic, semantic, procedural, emotional, reflective)
• ⏱ Temporal reasoning (what was true when)
• 📉 Decay & reinforcement instead of dumb TTLs
• 🕸 Waypoint graph (associative, traversable links)
• 🔍 Explainable traces (see which nodes were recalled and why)
• 🏠 Self‑hosted, local‑first, you own the DB
• 🔌 SDKs + server + VS Code + MCP

It behaves like a memory module, not a “vector DB with marketing copy”.

---

4. The “Old Way” vs OpenMemory

Vector DB + LangChain (cloud-heavy, ceremony):

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)  # cloud warmup

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

conversation.predict(input="I'm allergic to peanuts")

OpenMemory (3 lines, local file, no vendor lock-in):

from openmemory.client import Memory

mem = Memory()
mem.add("user allergic to peanuts", user_id="user123")
results = mem.search("allergies", user_id="user123")

✅ Zero cloud config • ✅ Local SQLite • ✅ Offline‑friendly • ✅ Your DB, your schema

---

5. Features at a Glance

• Multi-sector memory
  Episodic (events), semantic (facts), procedural (skills), emotional (feelings), reflective (insights).

• Temporal knowledge graph
  valid_from / valid_to, point‑in‑time truth, evolution over time.

• Composite scoring
  Salience + recency + coactivation, not just cosine distance.

• Decay engine
  Adaptive forgetting per sector instead of hard TTLs.

• Explainable recall
  “Waypoint” traces that show exactly which nodes were used in context.

• Embeddings
  OpenAI, Gemini, Ollama, AWS, synthetic fallback.

• Integrations
  LangChain, CrewAI, AutoGen, Streamlit, MCP, VS Code, IDEs.

• Connectors
  Import from GitHub, Notion, Google Drive, Google Sheets/Slides, OneDrive, Web Crawler.

• Migration tool
  Import memories from Mem0, Zep, Supermemory and more.

If you’re building agents, copilots, journaling systems, knowledge workers, or coding assistants, OpenMemory is the piece that turns them from “goldfish” into something that actually remembers.

---

6. MCP & IDE Workflow

OpenMemory ships a native MCP server, so any MCP‑aware client can treat it as a tool.

Claude / Claude Code

claude mcp add --transport http openmemory http://localhost:8080/mcp

Cursor / Windsurf

.mcp.json:

{
  "mcpServers": {
    "openmemory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

Available tools include:

• openmemory_query
• openmemory_store
• openmemory_list
• openmemory_get
• openmemory_reinforce

Your IDE assistant can query, store, list, and reinforce memories without you wiring every call manually.

---

7. Temporal Knowledge Graph

OpenMemory treats time as a first‑class dimension.

Concepts

• valid_from / valid_to – truth windows
• auto‑evolution – new facts close previous ones
• confidence decay – old facts fade gracefully
• point‑in‑time queries – “what was true on X?”
• timelines – reconstruct an entity’s history
• change detection – see when something flipped

Example

POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Alice",
  "valid_from": "2021-01-01"
}

Then later:

POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Bob",
  "valid_from": "2024-04-10"
}

Alice’s term is automatically closed; timeline queries stay sane.

---

8. CLI (opm)

The opm CLI talks directly to the engine / server.

Install

cd packages/openmemory-js
npm install
npm run build
npm link   # adds `opm` to your PATH

Usage

# Start the API server
opm serve

# In another terminal:
opm health
opm add "Recall that I prefer TypeScript over Python" --tags preference
opm query "language pref