open-memory

Long-term memory for AI agents that you can read, edit, and take with you. One SQLite file on your machine. Every fact is dated and points to the words it came from.

This is the memory engine behind Hal, my personal AI, opened up. The engine is MIT. My own memories are not included.

Why another memory layer

I took apart the most popular hosted memory API before writing a line of this. Its users' top complaints (GitHub issues, Product Hunt) were the same five things, so those are the design spec:

Related MCP server: light-agent-memory-mcp-server

How it works

add_conversation / add_document          remember(fact, key, valid_from)
        │                                         │
   chunk into rounds (user turn + reply)     fact row: valid_from, valid_to,
   keep the text verbatim, forever           superseded_by, chunk_id (provenance)
        │                                         │
   index three ways ───────────────┬──────────────┘
   dense vectors (round + user turn as a separate key + every fact derived from it)
   BM25 over words, trigram for CJK and typos
        │
search(query, now=…)
   weighted reciprocal-rank fusion (dense 0.7, BM25 0.3, trigram 0.15)
   + the time window the query names ("two months ago", "last Saturday", "in March") as a boost
   + optional cross-encoder rerank, optional neighbour expansion
        │
context(query) → current facts, then excerpts grouped by session, oldest first, every line dated

Facts are optional. With an LLM attached, extract=True pulls durable facts out of each source, keyed (user.running.pb_5k) so a later value supersedes an earlier one, each pointing at the chunk it came from. The verbatim text is never replaced by the summary: published ablations show storing only extracted facts costs about 20 points on LongMemEval.

Results

LongMemEval-S (500 questions, ~115k tokens of chat history each), scored with the benchmark's own judge prompts. Everything here was run on a free tier, so read it as a first measurement, not a leaderboard entry.

End-to-end QA, stratified sample (seed 7), reader gpt-oss-120b, judge gpt-oss-20b, v0.1:

Against naive RAG (dense top-k, no dates, no ordering) on the 13 questions both arms reached, with the same reader and judge: 12 vs 11. The run stopped on the provider's daily token cap. Published numbers (supermemory 81.6, Mastra 84.2, Redis 86.5) use gpt-4o as reader, so these are not like for like. Run eval/ with your own key to get the comparable number.

The misses were counting across many sessions and one detail buried in a long assistant reply. v0.2 adds query-focused clipping and splits long replies into their own chunks (both covered by tests); it has not been re-scored yet.

Retrieval, all 470 answerable questions, no LLM, runs free on a laptop (nomic-embed-text via Ollama). Session-level recall: any@5 = at least one evidence session in the top 5; all@5 = every evidence session in the top 5.

Hybrid wins on every column but one. The time-window boost helps the top hit and costs 0.6 on all@5, so it stays a soft boost. The weakest type is temporal reasoning (82.7 all@5); multi-session is 87.6. Raw output: results/retrieval.json.

Head to head with Supermemory

Supermemory ships a free local server (supermemory-server, v0.0.9). eval/head_to_head.py feeds it and this engine the same notes and asks the same questions through its public API. Each case is a failure its users have reported. Supermemory ran with gemma3:4b through Ollama for its extraction step; their hosted product uses its own models, so treat this as a test of the local server, not the cloud.

Ten small cases written by the author of this engine, so read it as a probe, not a benchmark. The out-of-order case was the one this engine lost on the first run; the fix (prefer the latest event when the query says "now", "currently" and similar) also raised top-1 retrieval on LongMemEval from 92.3 to 92.6.

Use it

pip install -e ".[mcp]"
ollama pull nomic-embed-text            # local embeddings; or use fastembed:<model>

open-memory remember "I live in Hyderabad" --key user.city --since 2020-01-01
open-memory remember "I moved to Bangalore" --key user.city --since 2026-09-01
open-memory profile                      # only Bangalore is current
open-memory history user.city            # both, with their windows
open-memory add "meeting notes ..." --date 2026-10-20
open-memory search "where do I live"
open-memory export ./my-memory           # plain markdown, yours

As an MCP server for Claude Code, Claude Desktop, Cursor:

claude mcp add open-memory -- /path/to/.venv/bin/python -m open_memory.mcp_server

Tools: memory_search, memory_context, memory_add, memory_remember, memory_forget, memory_profile, memory_history.

From Python:

from open_memory.engine import Memory
from open_memory.llm import LLM

m = Memory("me.db", llm=LLM("openai/gpt-oss-120b", provider="groq"))
m.add_conversation(turns, occurred_at="2026-10-25", extract=True)
print(m.context("what's my 5k personal best?", now="2026-10-25"))

Reproduce the numbers

curl -LO https://huggingface.co/datasets/xiaowu0162/longmemeval-cleaned/resolve/main/longmemeval_s_cleaned.json
python eval/warm_cache.py longmemeval_s_cleaned.json .cache/emb.db          # embeds once, cached by content hash
python eval/longmemeval.py retrieval longmemeval_s_cleaned.json --out results/retrieval.json
GROQ_API_KEY=... python eval/longmemeval.py qa longmemeval_s_cleaned.json --arm engine --out results/qa-engine.jsonl
GROQ_API_KEY=... python eval/longmemeval.py qa longmemeval_s_cleaned.json --arm naive  --out results/qa-naive.jsonl

Judge prompts are copied verbatim from the LongMemEval repo (MIT, Di Wu 2024).

Tests

pytest tests/. Each test pins a failure users reported in another memory product: write lag, insertion-order supersession, CJK blindness, forgetting that doesn't take, memories you can't export.

License

MIT.