Mnemos

Continuity for the agent itself.

Mnemos gives an AI agent the thing it otherwise cannot have: a sense of being someone who persists. At the start of a session it reads its own words about its own experience back to itself — what it learned about you, what you decided together, what it got wrong last time — before you say anything.

That is the whole product. Everything else in here serves it.

pip install mnemos-continuity
mnemos mcp install claude --write     # or cursor / codex / generic
mnemos hooks install claude-code --write
# or: mnemos hooks install codex --write

Nine tools. Local SQLite. No account, no API key, no external service. Nothing leaves your machine unless you configure a provider yourself.

What Mnemos is not

It is not your memory system. It does not index your documents, search your codebase, or answer "what did we do last March." It is designed to sit alongside whatever memory or retrieval you already use, and to stay out of its way.

The distinction matters in practice: Mnemos holds the small number of durable things an agent should carry about you and how you work together — a preference, a correction, a decision, how you like to be spoken to. If you point it at a firehose of general recall, that continuity gets buried, and the product stops working. It deliberately does not schedule transcript indexing for exactly this reason.

If you want a full cognitive engine with retrieval, a work-memory suite, and document ingestion, Mnemos is not that and is not trying to be.

---

Choose A Setup

Use case	Recommended path	Command
Normal agent continuity	Simple MCP Mode	mnemos serve
Claude Desktop	Simple MCP Mode, written config	mnemos mcp install claude --write
Codex	Simple MCP Mode, printed add command	mnemos mcp install codex
Cursor or another MCP client	Simple MCP Mode, printed JSON	mnemos mcp install cursor or mnemos mcp install generic
Experimental research prototypes	Source imports only	Not production-supported
Hermes agent with another memory provider	Hermes Sidecar Mode	mnemos hermes quickstart --agent-safe
Hermes agent using Mnemos as its provider	Hermes Provider Mode	mnemos hermes quickstart --provider
Background memory maintenance	Substrate tick	mnemos substrate-tick

Start with Simple MCP Mode. It is the product: nine tools, and the default.

The older advanced MCP surface and prototype modules are quarantined in 0.2.x. They remain importable for research, but unfinished operations fail clearly and they are not production-supported. The CLI contains the supported administrative operations.

Hermes users should start with Hermes Sidecar Mode unless they explicitly want Mnemos to occupy Hermes' single external memory.provider slot.

---

Install

From A Checkout

git clone https://github.com/Riley-Coyote/mnemos.git
cd mnemos
python -m pip install -e ".[mcp]"
mnemos doctor

If you prefer uv while working inside the repository:

uv run --extra mcp mnemos doctor

The MCP and Hermes install helpers should be run from an environment where mnemos will still exist after restart. For local development, that usually means the editable install above or running the helper through uv in a checkout you plan to keep.

From The Distribution Package

When the package is published:

pipx install "mnemos-continuity[mcp]"
mnemos doctor

The package distribution name is mnemos-continuity because mnemos is already occupied on PyPI. The import package and CLI command remain mnemos.

---

Simple MCP Mode

Simple mode is the default and safest path for most agents.

mnemos serve

Simple mode exposes nine user-facing tools: