Mnemolite
A local-first, zero-LLM memory engine for AI agents.
Why Mnemolite?
Most AI memory solutions (Mem0, Zep) use LLM calls on every message to extract facts. This is expensive, slow, and requires an API key.
Mnemolite takes a different approach: cognitive consolidation. It uses local NLP and embeddings to build a semantic knowledge graph entirely on your machine.
- No API costs
- No data leaks
- No latency from external calls
Features
- Zero-LLM Extraction — spaCy NER plus dependency-based triples with lemmatized endpoints and negation-aware predicates (
not_like,is_not_a) build the graph. No clustering, no second encoder, no OpenAI call, ever. - Multilingual by default — Vectors come from
intfloat/multilingual-e5-small(override withMNEMOLITE_EMBED_MODEL), so a Chinese query can recall an English memory. Extraction itself stays English-only viaen_core_web_sm. - Hybrid Retrieval — Combines vector similarity (episodic memory) with graph traversal (semantic memory).
- Honest retrieval — A
max_distancethreshold (0.5 by default, cosine >= 0.75) cuts weak matches, so "nothing relevant" is a valid answer instead of noise; typed facts are deduplicated and capped. - Local-First — SQLite and ChromaDB on your disk.
- Lightweight — Runs on consumer hardware, no GPU required.
- Forgetting (Decay) — Old, unreinforced connections fade away and are archived, preventing database bloat and keeping only the most relevant memories.
- Idempotent Consolidation — Each episode is consolidated once; re-running
consolidate()never inflates edge weights. - Crash-safe and forgetful — Deleting an episode removes the facts only it supported, and a consolidation pass interrupted mid-way resumes without double-counting weights.
- Agent brief — After consolidation, Mnemolite writes
.mnemolite/AGENT_CONTEXT.md, a human- and agent-readable summary of the current graph. Any agent (MCP or not) can read it at session start.
Installation
pip install mnemolite
From a checkout:
pip install -e ".[dev]"
The spaCy pipeline (en_core_web_sm) and the embedding model (intfloat/multilingual-e5-small) download automatically on first run. The first start therefore needs network access and enough disk space for the model cache.
Quick Start
from mnemolite.core import Mnemolite
# Initialize
mnemolite = Mnemolite(db_path="my_agent.db", chroma_path="./chroma_db")
# 1. Add memories (episodic layer)
episode_id = mnemolite.add("Alice is a software engineer based in London.")
mnemolite.add("Bob is working on a project using PyTorch.")
# 2. Consolidate (builds the graph; only new episodes are processed)
mnemolite.consolidate()
# 3. Recall (hybrid search)
results = mnemolite.recall("What technologies is Bob using?")
print(results["episodes"]) # Raw texts from vector search
print(results["facts"]) # Graph relations (Bob -> pytorch)
# 4. Tighten recall: drop anything past the distance cutoff
# (0.5 squared-L2 = cosine 0.75 on normalized embeddings)
results = mnemolite.recall("What technologies is Bob using?", k=3, max_distance=0.5)
# 5. Delete a memory (episode, vector and its graph contributions)
mnemolite.delete([episode_id])
MCP server
python -m mnemolite.server
# or, after an editable install:
mnemolite-server
The server exposes add_memory, recall_memory, consolidate_memory,
delete_memory and decay_memory over stdio. It opens the store in an MCP
lifespan and closes Chroma on shutdown.
By default the store lives in the checkout root (when running from a checkout)
or ~/.mnemolite; override it with MNEMOLITE_DATA_DIR, MNEMOLITE_DB_PATH or
MNEMOLITE_CHROMA_PATH. This keeps the memory location independent of the
directory the MCP client launches the server from.
Agent skill
skill/mnemolite-memory/ is a self-contained Agent Skills package that
teaches an agent when and how to call the Mnemolite MCP tools. Build the
upload-ready archive from that directory with the command in
docs/skill.md; the ZIP is a generated artifact and is not
committed.
- Packaging contract and release checklist: docs/skill.md.
- The skill requires the
mnemolitepackage (or an editable checkout) and a runningmnemolite-serverover stdio. - No external LLM API is called by the server or the skill.
How it works
- Episodic Memory — Raw texts are embedded with
intfloat/multilingual-e5-smalland stored in ChromaDB. - Semantic Memory — Consolidation processes only episodes it has not seen yet (
consolidated_at), extracts entities and triples with spaCy, and builds a weighted graph in SQLite. - Retrieval — A query triggers a vector search filtered by
max_distance(with salience and recency as small tie-breakers) plus a graph lookup, giving the agent both the original context and structured facts. Vectors whose episode row no longer exists are ignored and pruned at startup. - Deletion & durability —
delete()removes the episode, its vectors and its recorded edge contributions; edges still supported by other episodes remain. Each consolidation pass marks episodes inside their write transaction, so a crash resumes instead of inflating weights.
Roadmap
- Core memory engine (episodic + semantic)
- Zero-LLM consolidation
- Decay & forgetting algorithm
- MCP (Model Context Protocol) server
- Multilingual embeddings (
intfloat/multilingual-e5-small) - [~] Multi-language support — partial: retrieval is multilingual, spaCy extraction is still English-only
- Phase 2 — Agent context brief
- Reliability hardening and negation-aware extraction
- MCP server hardening and graph lifecycle
- Packaging, CI and hermetic MCP smoke
- Agent skill package and installable distribution
- Phase 2b — RAG adapters
See docs/status.md for the current status, recent changes and the detailed roadmap, and docs/extraction.md for the extraction rules. Release notes are in CHANGELOG.md.
License
MIT
Metadata
Release files for mnemolite 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mnemolite-0.1.0.tar.gz | 67.4 kB | Without provenance | Details for mnemolite-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mnemolite-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for mnemolite-0.1.0-py3-none-any.whl |
Total release size: 95.8 kB
Release files / mnemolite-0.1.0.tar.gz
| Download URL | mnemolite-0.1.0.tar.gz |
|---|---|
| Size | 67.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4fa60d7f57a1897efd04d493c8b50a134c0c39e9be9fb853f2bfe5a58ea16918
|
|
BLAKE2b-256 checksum How to use checksums |
d8735826aa3ae72e509fca130198b59510750bbf0d8d877bc721c5e98225bee4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / mnemolite-0.1.0-py3-none-any.whl
| Download URL | mnemolite-0.1.0-py3-none-any.whl |
|---|---|
| Size | 28.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
aa92db50def9aa0fd14a6c52a5bdb0dde716a5ecb75991dac364e5d88eeb0e2f
|
|
BLAKE2b-256 checksum How to use checksums |
f696b958c5e05da17857639a3c36958791781f1912a33dd70158ef2ebd0793d4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for mnemolite 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.