OpenMemory Documentation

Unlike standard Vector Databases that store flat embeddings and rely solely on cosine similarity, OpenMemory uses a multi-sector cognitive engine (HMD v2).

Key architectural features include:

• Memory Sectors: Information is categorized into episodic, semantic, procedural, emotional, and reflective sectors.
• Single-Waypoint Graph: Automatically creates a single, strongest connection between related memories to enable explainable recall.
• Composite Similarity: Retrieval uses both similarity and activation spreading across sectors.
• Temporal Awareness: Built-in recency and salience scoring for memory decay and reinforcement.
• Local-First: Uses SQLite and FAISS/Chroma locally, making it highly efficient and private.

OpenMemory treats time as a first-class citizen via a Temporal Graph. It tracks the following metadata to enable time-based querying:

• Creation Time: When the memory was first recorded.
• Last Access: The last time the memory was retrieved (used to calculate decay).
• Sequence: The causal chain of events (e.g., Chat History).

This enables temporal queries such as retrieving information from a specific timeframe or determining the sequence of events leading up to a specific interaction.

OpenMemory implements a cognitive architecture with three distinct memory types:

1. Episodic Memory: Stores specific events and individual interactions.
2. Semantic Memory: Stores generalized facts and knowledge extracted from episodic data.
3. Procedural Memory: (Planned) Intended for storing "how-to" knowledge and tool usage instructions.

OpenMemory is model-agnostic. It can be integrated with any Large Language Model (LLM), including:

• Cloud providers (e.g., OpenAI, Anthropic)
• Local models (e.g., Llama 3 via Ollama)

OpenMemory is designed as an agentic memory layer rather than a standard vector database. Unlike Chroma or Pinecone, OpenMemory provides built-in management for:

• User separation: Keeping memories isolated between different users.
• Temporal tracking: Managing the timeline of information.
• Memory dynamics: Handling automated processes like memory decay and reinforcement.

OpenMemory utilizes Hierarchical Memory Decomposition combined with a Temporal Graph.

Key architectural components include:

• Sector Classifier: Routes inputs into specific memory sectors (Episodic, Semantic, Procedural, Emotional, or Reflective).
• Recall Engine: Performs retrieval using Vector Search, Waypoint Graphs, Composite Scoring, and a Decay Engine.
• Temporal KG (Knowledge Graph): Manages Facts and Timelines.
• Storage: Uses SQLite or Postgres to store memories, vectors, and waypoints.
• Processes: Includes Embedding, Consolidation, and Reflection to refine memory and output recall traces.

OpenMemory organizes data using a Hierarchical Storage Graph (HSG) rather than a flat vector index. This structure allows for domain-specific organization and relationship mapping:

• Sectors: High-level domains used to categorize memory (e.g., Personal, Work, Code).
• Nodes: Individual memory units.
• Edges: Relationships between memories, which can be temporal, semantic, or based on explicit entities.

Install the openmemory-py package to use OpenMemory locally with Python. The SDK is local-first and uses SQLite by default. Note that add, search, get, and delete are asynchronous methods and must be awaited in async contexts.

pip install openmemory-py

from openmemory.client import Memory

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

Install openmemory-js for use in Node.js backends, CLIs, or local tools. The SDK is local-first and supports asynchronous operations.

npm install openmemory-js

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")