Hierarchical memory model
Sessions hold conversations, conversations hold topics, topics hold exchanges. Four levels of grouping so retrieval scopes to the right slice instead of dumping the whole history.
Alpha on PyPI · MCP server included
Give your LLM a memory that actually works.
Memorg is a Python library that stores, organises, and retrieves context for LLM apps. Sessions and topics on top of SQLite, semantic search via USearch and OpenAI embeddings, token-budget-aware retrieval, and an MCP server out of the box.
quickstart.py
# pip install memorg (Python 3.11+)
from memorg import MemorgSystem
from memorg.storage.sqlite_storage import SQLiteStorageAdapter
from memorg.vector_store.usearch_vector_store import USearchVectorStore
from openai import AsyncOpenAI
system = MemorgSystem(
storage=SQLiteStorageAdapter("memory.db"),
vector_store=USearchVectorStore("memory.db"),
openai_client=AsyncOpenAI(),
)
session = await system.create_session("user_123", {})
conversation = await system.start_conversation(session.id)
results = await system.search_context("what did we discuss about the API?")4 levels
session · conversation · topic · exchange
SQLite + USearch
one file. no managed services.
MIT
pip install memorg · Python 3.11+
What is Memorg?
An external memory layer for LLM apps.
Memorg is a pip-installable Python library (MIT, Python 3.11+) that gives an LLM app durable, structured memory. It combines a four-level hierarchy — session → conversation → topic → exchange — with a USearch vector index and OpenAI embeddings, all in a single SQLite file. Retrieval blends semantic similarity, recency, and importance, then trims results to a per-session token budget so the model gets the most useful context that still fits its window.
The problem
A vector store gives you neighbours, not memory.
Without a memory layer
- ✕Stuff more tokens in and hope — the transcript outgrows the window and gets truncated.
- ✕Bolt on a bare vector DB: no ownership, no scoping, no recency, no importance.
- ✕A returning user starts cold — nothing survives the session.
With Memorg
- ✓Store exchanges once; retrieve only the relevant slice back into the window.
- ✓A hierarchy that scopes retrieval, plus a deterministic similarity + recency + importance blend.
- ✓Sessions keyed to a user persist in one SQLite file — reopen and the memory is there.
What you get
A memory layer, not a framework
Semantic search over OpenAI embeddings
Every exchange is embedded with an OpenAI model and stored in a USearch index alongside SQLite. Searches return the most semantically relevant context, not the most recent.
Importance + recency scoring
Results are ranked by a deterministic blend of semantic similarity, recency, and importance, so a decision from yesterday outweighs an aside from last week.
Token-budget aware
A built-in token counter fits returned context to the model window you set when creating the session, so the LLM gets the most useful payload that still fits.
Store anything, not just chat
Memory items can be documents, notes, or arbitrary tagged blobs. Search across types or scope to one kind. The chat hierarchy is the default, not the cage.
Local-first by default
SQLite for persistence, USearch for the vector index — both in a single file you can copy. No managed service required to develop or ship.
MCP server included
A FastMCP server ships with the package so Claude, Cursor, and other MCP-aware clients can read and write Memorg without bespoke glue code.
Architecture
One library. One file.
Your app calls Memorg; Memorg persists to a single file that combines SQLite storage and a USearch index, embeds text with OpenAI, and can expose an MCP server. No separate vector database.
Use cases
Where teams reach for it
Conversation continuity for LLM chat
Keep a chat coherent across turns, sessions, and days without stuffing the whole history into every prompt.
→Upgrade naive RAG to structured recall
Move past a bare vector store to retrieval that understands users, sessions, recency, and importance.
→A memory layer for your agent
Drop deterministic recall next to any orchestrator without adopting a whole agent runtime.
→Support bots that remember the customer
Give a support assistant per-customer recall so it stops asking for context the customer already gave.
→Notes and documents as memory
Store documents, notes, and arbitrary items alongside conversations and search across them.
→Honest comparisons
Where Memorg fits in your stack
Memory is a crowded space. These are the projects teams ask about most — read the trade-offs, including where the other tool is the better answer.
Memorg vs Mem0
→The best-known managed memory layer with a hosted offering and an LLM-driven extraction pipeline. Memorg is library-first, deterministic, and runs entirely on your machine.
Memorg vs Letta (formerly MemGPT)
→A full agent runtime with a memory abstraction baked in. Memorg is just the memory layer; bring whatever agent loop you already use.
Memorg vs Zep
→A memory service built on a temporal knowledge graph, with a hosted cloud offering. Memorg is a local-first, single-file SQLite library with deterministic retrieval and no separate service to run.
FAQ
Before you pip install
+ Is Memorg a vector database?
No. It is a Python library that uses a vector index (USearch) and a relational store (SQLite) together. The vector index handles similarity search; SQLite holds the hierarchy, metadata, and the source-of-truth content. You get vector recall without running a vector DB.
+ What retrieval strategy does it use?
A blended one. Queries are embedded with OpenAI, USearch returns nearest neighbours, and results are re-scored with importance and recency before being trimmed to the session token budget. There is no LLM reranker by default — the scoring is deterministic.
+ Which LLM clients are supported?
Memorg ships with an OpenAI client integration for embeddings and chat. The MCP server exposes Memorg to any MCP-aware client (Claude Desktop, Cursor, etc.). For other providers you can use Memorg as a library and feed the retrieved context into whatever generation call you already make.
+ Does it work offline?
Storage and vector search are local. Embedding and generation call OpenAI, which requires a network and an OPENAI_API_KEY. Swapping in another embedder is a contained change because the vector store interface is small.
+ How big can the memory get?
USearch keeps the index small and fast even at millions of items, and SQLite handles the metadata fine at that scale. The practical limit is your embedding budget and how aggressively you prune low-importance items.
+ What is the install footprint?
pip install memorg. Python 3.11+. Dependencies include openai, tiktoken, aiosqlite, numpy, usearch, and fastmcp. No native services to run.
+ Is it production-ready?
The package is published on PyPI and the project is in alpha (per its own classifier). The data model, retrieval API, and MCP server are stable enough to build on; expect refinements at the edges.
+ How does Memorg compare to LangChain memory or LlamaIndex?
Those frameworks include memory as one feature among many. Memorg is just the memory layer — a small surface area you can drop next to any orchestrator. It does not own your prompts, your tools, or your agent loop.
Explore Memorg
Everything, one click away
The rest of the site: the full feature set, the architecture, the reasoning behind the design, and reference material.
Features
→The full feature set — hierarchy, semantic search, blended ranking, token budget, single-file SQLite, and the MCP server.
How it works
→The architecture end to end: the four-level hierarchy, SQLite + USearch storage, embeddings, and the retrieval path.
Quickstart
→Install with pip, create a session, store exchanges, and call search_context() — a copy-paste walkthrough.
Use cases
→Where Memorg fits: chat continuity, upgrading naive RAG, agent memory, support-bot recall, and documents as memory.
Comparisons
→Honest trade-offs against Mem0, Letta (MemGPT), and Zep — including where the other tool is the better answer.
FAQ
→Answers grouped by basics, retrieval, operations, and integration — read before you pip install.
Glossary
→Plain-language definitions of the core concepts: sessions, topics, exchanges, memory items, blended retrieval, and more.
About
→The design thesis — why memory should be infrastructure, not a framework, and why Memorg is built the way it is.
Blog
→Engineering essays on memory design: forgetting as a feature, agents vs chatbots, and the 50-line-bandage problem.
Stop bandaging context windows.
Drop Memorg next to your LLM client, point it at a SQLite file, and call search_context() when you need recall. That is the whole API.