Docs · Mneme

Overview

Mneme runs on your machine and indexes the things you already produce. Mail, calendars, messages, notes, files. It builds a small graph of people, threads, and promises, then exposes a single query interface that any agent can call.

Two ways to think about it. One, a private search across everything you've ever done. Two, the long-term memory your agent doesn't come with by default.

Install

Requires Python 3.10 or newer.

install

$ pip install mneme

$ mneme --version

mneme 0.2.0a0

Prefer pipx or uv? Either works. Mneme is a single Python package with no native build step.

Wizard

The first run is interactive. The wizard asks what you want Mneme to remember, sets scopes, and authorizes sources.

setup

$ mneme wizard

Welcome. Let's connect your first source.

[1/4] Email · [2/4] Calendar · [3/4] Files · [4/4] Done

You can rerun the wizard any time to add sources or revoke them. Nothing leaves your machine.

Sources

A source is any place your life produces a record. Mneme reads from each one, normalizes it into entries, and links them.

Email: Gmail, IMAP. Threads, attachments, contacts.
Calendar: Google Calendar, ICS. Events and attendees.
Files: Local folders. Notes, docs, screenshots.
Chat: Slack, iMessage exports. Threads and DMs.

Each source has its own scope and refresh cadence. You can pause or remove any source from mneme sources.

Query

Ask in plain language. Mneme picks the right retrieval strategy and returns short, cited answers.

query

$ mneme query "who introduced me to Maya?"

→ Maya Park, March 4th, over a thread about the Athens trip.

source: gmail · thread · 3 messages

$ mneme query "what did I promise Alex on Monday?"

→ To send the revised deck by Thursday and loop in Sarah.

source: gmail · 2 messages · calendar · 1 event

Pass --json for structured output, or --limit to widen the response set.

CLI

mneme wizard: Interactive setup.
mneme query <text>: Ask a question.
mneme sources: List, add, remove sources.
mneme stats: Index size, last sync, coverage.
mneme eval: Run the local eval harness.

Every command supports --help. The CLI is the surface area. There is no daemon by default.

Use with agents

Mneme exposes a single endpoint, mneme.query(). Anything that can shell out or speak HTTP can use it.

agent.py

from mneme import query

context = query("recent threads with Sarah")

agent.run(task, memory=context)

Works with Claude, Cursor, and any custom loop. The agent does not need to know how Mneme stores anything.

Storage and privacy

Everything sits in ~/.mneme. SQLite for the graph, a local vector store for embeddings, plain files for raw records.

No telemetry. No cloud sync. Embeddings run locally by default with a small on-device model. You can opt into a remote model per query, never per index.

Eval

Mneme ships with a small eval harness so you can compare retrieval strategies on your own data.

eval

$ mneme eval --baseline bm25 --candidate vector

recall@10 bm25 0.62 · vector 0.71

mrr bm25 0.41 · vector 0.49

Add your own labeled queries in ~/.mneme/eval/queries.jsonl.

FAQ

Does anything leave my machine?

No, unless you explicitly enable a remote model for a query. The index, the graph, and your records stay local.

What languages are supported?

English, Spanish, French, German, Italian, Portuguese. Other languages work; quality varies.

Can I use Mneme without an agent?

Yes. The CLI is fully usable on its own. Many people use it as a private search engine for their life.

How big does the index get?

Roughly 5 to 15 percent of the source data on disk, depending on embeddings and how much text you index.

Is there a hosted version?

No, and there are no plans for one. Mneme is local-first by design.

Still stuck? Open an issue on GitHub or read the source. Mneme is small enough to fit in your head.

End of docs

Read. Install. Remember.