Metadata-Version: 2.4
Name: smolAmem
Version: 1.0.0
Summary: Multi-tier long-term memory for LLM agents. Install: pip install smolAmem. Import: import mneme.
Project-URL: Homepage, https://ashwinugale.github.io/ashwinugale-mneme/
Project-URL: Documentation, https://ashwinugale.github.io/ashwinugale-mneme/
Project-URL: Repository, https://github.com/ashwinugale/ashwinugale-mneme
Project-URL: Issues, https://github.com/ashwinugale/ashwinugale-mneme/issues
Author-email: Ashwin Ugale <ugaleashwin@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,llm,memory,rag,vector-search
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Requires-Dist: pymdown-extensions>=10.7; extra == 'docs'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: llamaindex
Requires-Dist: llama-index-core>=0.11; extra == 'llamaindex'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: pgvector
Requires-Dist: pgvector>=0.3; extra == 'pgvector'
Requires-Dist: psycopg[binary]>=3.2; extra == 'pgvector'
Provides-Extra: qdrant
Requires-Dist: qdrant-client>=1.12; extra == 'qdrant'
Provides-Extra: scheduler
Requires-Dist: apscheduler>=3.10; extra == 'scheduler'
Provides-Extra: sqlite
Requires-Dist: sqlite-vec>=0.1.6; extra == 'sqlite'
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.7; extra == 'tokens'
Description-Content-Type: text/markdown

# Mneme

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

[![docs](https://img.shields.io/badge/docs-ashwinugale.github.io%2Fashwinugale--mneme-blue)](https://ashwinugale.github.io/ashwinugale-mneme/)
[![python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
[![license](https://img.shields.io/badge/license-MIT-green)](./LICENSE)

**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

```bash
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

```python
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](https://ashwinugale.github.io/ashwinugale-mneme/quickstart/).

## Documentation

The full site lives at **[ashwinugale.github.io/ashwinugale-mneme](https://ashwinugale.github.io/ashwinugale-mneme/)**.

- [Concepts](https://ashwinugale.github.io/ashwinugale-mneme/concepts/) — the three-tier model, retrieval, consolidation, forgetting.
- [Backends](https://ashwinugale.github.io/ashwinugale-mneme/backends/) — InMemory, SQLite, Qdrant, pgvector.
- [Adapters](https://ashwinugale.github.io/ashwinugale-mneme/adapters/) — LangChain, LlamaIndex, raw OpenAI.
- [Eval harness](https://ashwinugale.github.io/ashwinugale-mneme/eval/) — reproducible recall@k + token-cost benchmark.
- [API reference](https://ashwinugale.github.io/ashwinugale-mneme/api/) — autogen from docstrings.

## Benchmark snapshot

From the v0.6 [eval harness](https://ashwinugale.github.io/ashwinugale-mneme/eval/) 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:

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

## License

MIT. See [LICENSE](./LICENSE).
