Skip to main content

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 with MNEMOLITE_EMBED_MODEL), so a Chinese query can recall an English memory. Extraction itself stays English-only via en_core_web_sm.
  • Hybrid Retrieval — Combines vector similarity (episodic memory) with graph traversal (semantic memory).
  • Honest retrieval — A max_distance threshold (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 mnemolite package (or an editable checkout) and a running mnemolite-server over stdio.
  • No external LLM API is called by the server or the skill.

How it works

  1. Episodic Memory — Raw texts are embedded with intfloat/multilingual-e5-small and stored in ChromaDB.
  2. 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.
  3. 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.
  4. 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)

Source distribution for mnemolite 0.1.0
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)

Table of built distributions (wheels) for mnemolite 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page