Mneme

Every modern chatbot loses its mind the moment a session ends. Mneme is a small open-source layer that sits between you and any large language model and gives it a real memory: four kinds of it, modelled after how the human brain holds on to things — working, episodic, semantic, and procedural. Plug it into Ollama for fully local inference, or point it at OpenAI, Anthropic, OpenRouter, LM Studio, vLLM — anything OpenAI-compatible.

   ┌──────────────┐    ┌────────────────────┐    ┌──────────────┐
   │  your input  │ →  │  Mneme: retrieve   │ →  │   any LLM    │
   └──────────────┘    │  → answer → store  │    └──────────────┘
                       └────────────────────┘
                                  │
                                  ▼
                        ┌──────────────────┐
                        │  durable memory  │
                        │  (4 types)       │
                        └──────────────────┘

Watch it remember

Why Mneme

Install

pip install mneme
# faster vector search on large stores (optional, needs C/C++ toolchain):
pip install "mneme[fast]"
# from source
git clone https://github.com/vladimir120307-droid/mneme
cd mneme && pip install -e ".[dev]"

60-second quick start

1. CLI chat (local-first)

ollama pull llama3.1
mneme chat --provider ollama --model llama3.1

Tell it your name on Monday. Come back on Friday — it still knows.

2. Python

import asyncio
from mneme import Agent
from mneme.agent import AgentConfig

async def main():
    agent = Agent(AgentConfig(provider="ollama", model="llama3.1"))
    agent.remember("I live in Berlin and write Rust.", importance=0.9)
    print(await agent.chat("Where do I live and what do I code in?"))
    agent.close()

asyncio.run(main())

3. REST (OpenAI-compatible)

mneme serve --port 8077

curl http://localhost:8077/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"messages":[{"role":"user","content":"hello"}]}'

Any tool that speaks the OpenAI API — openai SDK, LangChain, your own client — just point base_url at http://localhost:8077/v1.

The four kinds of memory

A background consolidator turns repeated episodic experiences into semantic facts, and low-value old episodes decay away on a half-life. Full spec: docs/memory-model.md.

Configuration

Everything is overridable by env vars or CLI flags.

CLI reference

mneme chat                    interactive REPL with streaming
mneme ask "question..."       one-shot
mneme serve                   start the REST server
mneme remember "fact..."      add an episodic memory
mneme memory list             list memories
mneme memory search "..."     hybrid vector + recency + importance search
mneme memory stats            counts by kind
mneme memory forget <id>      delete (id prefix accepted)
mneme memory decay            prune low-value old memories

Architecture

src/mneme/
├── agent.py              top-level Agent
├── consolidation.py      episodic → semantic
├── config.py             env-based settings
├── memory/
│   ├── types.py          pydantic models
│   ├── store.py          SQLite + vector index
│   ├── index.py          numpy / hnswlib backends
│   ├── embeddings.py     sentence-transformers
│   └── retrieval.py      hybrid scoring + context block
├── providers/
│   ├── ollama.py
│   ├── openai_compat.py
│   ├── anthropic.py
│   └── registry.py
├── api/server.py         FastAPI REST (OpenAI-compatible)
└── cli.py                Typer

Performance

Single-threaded brute force on the pure-Python (numpy) backend, dim=384, k=10, on a developer laptop:

The hybrid scoring kernel is vectorised; with the native C++ backend present it dispatches to a SIMD + OpenMP implementation transparently. Reproduce: python benchmarks/vector_search.py. Full numbers in docs/benchmarks.md (RU).

Native acceleration (optional)

A C++17 core (native/, header-only-friendly, OpenMP-parallel, auto-vectorised with AVX2) is available as a drop-in faster backend. Build it once and Mneme picks it up automatically:

python -m mneme.build_native

See native/README.md for details. Without it the pure Python path is used — everything still works.

Roadmap

• Working / Episodic / Semantic / Procedural memory split
• Hybrid retrieval (similarity + recency + importance + access)
• OpenAI-compatible REST server
• Ollama / OpenAI / Anthropic / OpenRouter / LM Studio / vLLM providers
• Native C++ memory core (drop-in faster backend)
• MCP server (Cursor / Claude Desktop / Windsurf integration)
• Tool use and structured function calling
• Multi-user sessions and per-user namespacing
• Cross-platform desktop UI (Flutter)
• Browser extension
• Memory import from Markdown, journals, chat exports

Documentation

Contributing

Issues and PRs welcome. Run the test suite:

pip install -e ".[dev]"
pytest
ruff check src/ tests/ benchmarks/

License

MIT — see LICENSE.