smolAmem 1.0.0

Multi-tier long-term memory for LLM agents. Install: pip install smolAmem. Import: import mneme.

Mneme

Multi-tier long-term memory for LLM agents. Working / episodic / semantic tiers, pluggable storage backends, framework-agnostic adapters, and explicit forgetting + consolidation.

Status: 1.0 released. APIs are stable; semver from here. Bug reports welcome.

Why

Every agent framework ships with toy memory: last-N messages, or an LLM-summarised buffer. Real agents need to remember user preferences across weeks, recall specific past interactions, and store semantic facts extracted from many interactions — and they need to forget things that stop being relevant.

Mneme is the library you wish existed.

Install

pip install smolAmem                    # core only
pip install "smolAmem[sqlite,openai]"   # SQLite + OpenAI embeddings
pip install "smolAmem[qdrant,openai]"   # production vector backend

Heads-up on naming: PyPI install name is smolAmem (the mneme slot was already taken). Python import name stays mneme — same dual-name pattern as Pillow / PIL or pyyaml / yaml. So you pip install smolAmem but write import mneme everywhere in your code.

Quickstart

from mneme import MemoryManager, SQLiteBackend, OpenAIEmbeddings

m = MemoryManager(
    agent_id="alice",
    backend=SQLiteBackend(path="mneme.db", dimensions=1536),
    embedder=OpenAIEmbeddings(),
)

m.episodic.add("user mostly works in TypeScript", metadata={"role": "user"})

for r in m.retrieve("what language does the user prefer?", k=3):
    print(r.score, r.record.content)

Full walkthrough: docs/quickstart.

Documentation

The full site lives at ashwinugale.github.io/ashwinugale-mneme.

• Concepts — the three-tier model, retrieval, consolidation, forgetting.
• Backends — InMemory, SQLite, Qdrant, pgvector.
• Adapters — LangChain, LlamaIndex, raw OpenAI.
• Eval harness — reproducible recall@k + token-cost benchmark.
• API reference — autogen from docstrings.

Benchmark snapshot

From the v0.6 eval harness on the 5-conversation starter corpus, k=5:

Strategy	recall@5	tokens / test point
no_memory	0.000	0.0
mneme (hash, deterministic)	0.833	68.0
mneme (OpenAI embeddings)	1.000	67.7
full_history	1.000	141.0
summary_buffer	1.000	165.3

Mneme matches the full-history oracle for accuracy at less than half the token cost. The HashEmbedder row is the cheap deterministic baseline that runs without an API key — useful in CI and for reviewers reproducing numbers.

Reproduce:

uv run python -m evals --runner mneme --embedder openai --output out/mneme.json

License

MIT. See LICENSE.