How it works
A small surface area, deliberately.
Memorg is one library and one file. Text comes in, gets embedded and stored under a hierarchy, and comes back ranked by a deterministic blend and trimmed to fit your model window.
The four layers
Session → conversation → topic → exchange
A session belongs to a user and sets the retrieval token budget. Conversations group topics; topics group exchanges — the message pairs that make up a dialogue. This gives retrieval a natural scope at every level.
SQLite via aiosqlite
Hierarchy, metadata, tags, and source content persist in one async-friendly SQLite file. It is portable — copy it, version it, back it up with cp. No server to run.
USearch index, in the same file
Each exchange and memory item is embedded with an OpenAI model and stored in a USearch nearest-neighbour index that lives alongside SQLite. There is no separate vector database.
Blend, then trim
A query embeds, USearch returns nearest neighbours, and results are re-scored by a deterministic blend of semantic similarity, recency, and importance — then trimmed to the session token budget so the payload fits the model window.
The retrieval path
- 1 · embed
The query is embedded with an OpenAI embedding model — the same model family used to embed stored exchanges and items.
- 2 · search
USearch returns the nearest neighbours from the in-file vector index, scoped to the level you queried.
- 3 · re-score
Candidates are re-scored with a deterministic blend of semantic similarity, recency, and importance.
- 4 · trim
The ranked list is trimmed to the session token budget so the returned context always fits the model window.
Architecture FAQ
+ What happens when I call search_context()?
Your query is embedded with OpenAI, USearch returns nearest neighbours, those results are re-scored with a deterministic blend of similarity, recency, and importance, and the top of the list is trimmed to the session token budget before it is returned.
+ Where does the data live?
In a single SQLite file. It holds the hierarchy, metadata, tags, source content, and the USearch vector index — so the whole memory store is one portable file you own.
+ Is there an LLM in the retrieval path?
Only for embeddings. The ranking itself is deterministic — there is no LLM reranker by default — so retrieval is reproducible.
Ready to try it? Head to the quickstart, or see the full feature set.
One library. One file.
No separate vector DB, no control plane, no service to operate.