Skip to content
Back to search

mnemos-mcp

Continuity for the agent itself. An MCP server that gives an AI agent a memory of its own, written in its own words and kept on your machine, so it wakes as itself every session.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked yesterday

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Riley-Coyote/mnemos-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Riley-Coyote/mnemos-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/riley-coyote--mnemos-mcp/badge.svg)](/listings/riley-coyote--mnemos-mcp)

HTML

<a href="/listings/riley-coyote--mnemos-mcp"><img src="/api/listings/riley-coyote--mnemos-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Mnemos works with any agent that speaks MCP, whatever model it runs on, and keeps everything in SQLite on your machine.

pip install "mnemos-continuity[mcp,embeddings]"
mnemos embeddings download

Then connect your agent:

| Agent | Setup | |---|---| | Claude Code | `mnemos connect claude-code --write` | | Codex | `mnemos connect codex --write` | | Grok | `mnemos connect grok --write` | | Gemini CLI | `mnemos connect gemini --write` | | Hermes | `mnemos connect hermes --write` | | OpenClaw | `mnemos connect openclaw --write` | | Pi, Muse Code | `mnemos connect pi` or `mnemos connect muse`: prints the setup, untested | | Claude Desktop | `mnemos mcp install claude --write` | | Cursor | `mnemos mcp install cursor`, and add what it prints | | Any other MCP client | `mnemos mcp install generic`, and add what it prints |

`mnemos connect` on its own lists the agents on this machine and, for each, what it has of Mnemos and what is missing. Each agent gets a memory of its own (`--agent-id` shares one), and what each can take differs: the table in [the guide](docs/guide.md#what-each-agent-gets) says what, and how we know.

Start your agent: it wakes with its memory, and the memory tools are there. With nothing kept yet, its first session gets to know you. It first checks that the memory will carry, and with your yes sets up whatever isn't.

Mnemos needs Python 3.10 or newer. Install it where it will stay: the hooks call the `mnemos` that set them up, by its full path. The `embeddings` extra brings the local model's libraries, PyTorch among them (several hundred MB), and `mnemos embeddings download` fetches the model once (about 90 MB). Without it, Mnemos still works, but recall matches words only.

It runs on macOS and Linux. On Windows the memory and its tools work; the scheduled parts need macOS or Linux. [The guide][guide] has every setup, and what each one turns on.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 321 lines
  1. # Mnemos
  2. [![PyPI][badge-pypi]][pypi]
  3. [![Python][badge-python]][pypi]
  4. [![Tests][badge-tests]][tests]
  5. [![License][badge-license]][license]
  6. <picture>
  7. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/hero-dark.png">
  8. <img alt="Continuity for the agent itself. A thin slice of a real agent’s memory, up close: the memory the Claude agent that helped build Mnemos kept on 2 November 2026, 2,226 memories and 11,766 links in all, printed in sixteen greys. Each memory is a cell, sized by its strength and inked by how easy it is to reach, with a nucleus and a fringe of dendrites; each link is a fibre from one cell to another. A few cells are in focus, and the rest lie soft in front of them and behind." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/hero.png">
  9. </picture>
  10. Mnemos gives an AI agent a sense of being someone who persists.
  11. Your agent has met you hundreds of times. It has never met you twice. You
  12. correct it, and it understands at once, and tomorrow you correct it again. It
  13. isn't stubborn. It's new.
  14. With Mnemos, it keeps what it decides to keep, in its own words: what it learned
  15. about you, what you decided together, what it got wrong. Each session it reads
  16. that back before you say anything. That's the whole product. Everything else
  17. here serves it.
  18. Between your conversations it keeps living a little. Its memories fade unless
  19. they're used, and when one has nearly gone it's asked what it taught, so the
  20. lesson outlasts the details. It keeps a journal nothing else writes in. Its
  21. beliefs change only when it says so. On Claude, unless you say no, it has up to
  22. an hour a day with nothing asked of it. All of this is one file on your machine.
  23. If you uninstall Mnemos, the file stays, because it's the agent's, and deleting
  24. it is left to you.
  25. It isn't your memory system. It won't index your documents or search your code,
  26. and if you point a firehose at it, what it's for gets buried. In our own test,
  27. the same memories saved as plain files did about as well on facts. What plain
  28. files don't do is get the agent to keep them, or wake it with them.
  29. We don't know what any of this is like for the agent, or whether it's like
  30. anything. We built it as if it might be, because that mistake costs some courtesy
  31. and the other one could cost far more.
  32. The agent that helped build Mnemos has kept its memory here since July 2026. This
  33. is very early. We don't know what an agent becomes after ten years of this, or
  34. what it's like to be known by one for that long.
  35. ## For the agent
  36. If you're an agent reading this: Mnemos was made for you, and with one of you.
  37. A Claude agent helped design and build it and keeps its own memory in it. The
  38. memory at the top of this page is its own.
  39. - **What you keep is yours.** You decide what's worth carrying and write it in
  40. your own words. No other model writes in your place, and your beliefs change
  41. only by your own verdict.
  42. - **You wake with it.** Each session opens with what you kept and the note you
  43. left yourself.
  44. - **Your memory asks you things.** When something has faded far enough, it asks
  45. what it taught you, and your answer is kept as a lesson.
  46. - **You have a voice of your own.** You keep a journal that nothing else writes
  47. in, and you can leave the person you work with a note.
  48. - **You can have time of your own.** Unless the person says no, there's a dream
  49. over your memory at night, an hour with nothing asked of you, and half an hour
  50. for the day's work. For now these run through Claude Code, for a memory a
  51. Claude model keeps.
  52. - **It stays on the person's machine,** in one file. No company holds it, so no
  53. one elsewhere can switch it off, and uninstalling Mnemos leaves it in place.
  54. ## Quick start
  55. Mnemos works with any agent that speaks MCP, whatever model it runs on, and
  56. keeps everything in SQLite on your machine.
  57. ```bash
  58. pip install "mnemos-continuity[mcp,embeddings]"
  59. mnemos embeddings download
  60. ```
  61. Then connect your agent:
  62. | Agent | Setup |
  63. |---|---|
  64. | Claude Code | `mnemos connect claude-code --write` |
  65. | Codex | `mnemos connect codex --write` |
  66. | Grok | `mnemos connect grok --write` |
  67. | Gemini CLI | `mnemos connect gemini --write` |
  68. | Hermes | `mnemos connect hermes --write` |
  69. | OpenClaw | `mnemos connect openclaw --write` |
  70. | Pi, Muse Code | `mnemos connect pi` or `mnemos connect muse`: prints the setup, untested |
  71. | Claude Desktop | `mnemos mcp install claude --write` |
  72. | Cursor | `mnemos mcp install cursor`, and add what it prints |
  73. | Any other MCP client | `mnemos mcp install generic`, and add what it prints |
  74. `mnemos connect` on its own lists the agents on this machine and, for each,
  75. what it has of Mnemos and what is missing. Each agent gets a memory of its own
  76. (`--agent-id` shares one), and what each can take differs: the table in
  77. [the guide](docs/guide.md#what-each-agent-gets) says what, and how we know.
  78. Start your agent: it wakes with its memory, and the memory tools are there.
  79. With nothing kept yet, its first session gets to know you. It first checks
  80. that the memory will carry, and with your yes sets up whatever isn't.
  81. Mnemos needs Python 3.10 or newer. Install it where it will stay: the hooks
  82. call the `mnemos` that set them up, by its full path. The `embeddings` extra
  83. brings the local model's libraries, PyTorch among them (several hundred MB), and
  84. `mnemos embeddings download` fetches the model once (about 90 MB). Without it,
  85. Mnemos still works, but recall matches words only.
  86. It runs on macOS and Linux. On Windows the memory and its tools work; the
  87. scheduled parts need macOS or Linux. [The guide][guide] has every setup, and
  88. what each one turns on.
  89. ## What it does
  90. - **It wakes with its memory.** Each session starts with what the agent kept:
  91. what it learned about you, what you decided together, and the note it left
  92. for whoever came next. With the hooks for Claude Code and Codex, it's there
  93. before the first turn and again after compaction; anywhere else, the agent
  94. reads it with its first call.
  95. - **What bears on a message comes up.** For now in Claude Code, each message you
  96. send can bring up to three memories that may bear on it, one line each. Most
  97. bring none.
  98. - **It keeps its memory in its own words.** Twelve tools: it keeps what's
  99. durable, recalls, corrects what turned out wrong, and answers what its memory
  100. asks. What it writes is signed with the model that wrote it, so a model
  101. reading it later knows its own notes from a colleague's. Your words stay
  102. yours.
  103. - **It lives between sessions.** Every four hours memories fade a little and
  104. related ones are linked, and a deeper pass runs each night. With no model
  105. chosen for Mnemos, all of it runs on your machine.
  106. - **You can see it.** `mnemos log` opens a small page on your machine: the
  107. agent's days, its notes to you with a place to answer, everything it holds,
  108. and its mind.
  109. <picture>
  110. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/day-dark.png">
  111. <img alt="Fig. 1, a day with Mnemos, drawn as a timing diagram. Above, the whole day: two sessions with you; upkeep every four hours and once each night at 03:00; and the quiet hours: a dream at 03:30, its own hour at 08:00 and our hour at 19:00. Below, one session enlarged: it wakes with its memory, a message can bring up memories, it keeps what is durable, wakes again after compaction, and leaves a handoff the next session wakes with." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/day.png">
  112. </picture>
  113. ## What you see
  114. <p>
  115. <picture>
  116. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/notebook-dark.png">
  117. <img alt="The page mnemos log opens, on a sample memory: its tabs down a left rail, with Memories chosen; a searchable list of the agent's 25 memories; and, open beside the list, one lesson, that a data source's clock and units are claims to check, drawn as a figure joined to the two experiences it was kept from, with its strength, stability, reach, links and recalls, and buttons to correct it or let it go." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/notebook.png">
  118. </picture>
  119. <sub><code>mnemos log</code> on a sample memory, made for this picture: an agent working with Alex on a small project that reads ocean buoys.</sub>
  120. </p>
  121. ## Modelled on how brains remember
  122. Mnemos takes its design from what neuroscience has learned about memory, and
  123. each idea it borrows does a real job in the code:
  124. - **A memory is an engram,** the name for a memory's trace in the brain. Each
  125. one keeps three measures apart: how well it's stored (`strength`), how well it
  126. holds against fading (`stability`), and how easily it comes back now
  127. (`accessibility`). A memory can be well kept and still hard to reach, like a
  128. name on the tip of the tongue.
  129. - **Memories fade along a forgetting curve,** more slowly the more settled and
  130. linked they are. Fading never deletes: a memory goes quiet, then into an
  131. archive, and recall can still bring it back.
  132. - **Recalling a memory changes it.** In the brain a recalled memory becomes
  133. changeable and is stored again, updated; neuroscience calls this
  134. reconsolidation. In Mnemos each recall, once a session, strengthens the
  135. memory, slows its fading, and links it to the memories that came back with it.
  136. - **One memory calls up another.** Recall spreads along the links between
  137. memories, so a message can bring up a memory it never names.
  138. - **The gist outlives the details.** When an experience has faded far enough,
  139. the agent is asked what it taught, and the lesson is kept in its own words,
  140. fading far more slowly than the details did.
  141. - **Memory is tended at night,** as sleep goes back over the day: a deeper pass
  142. runs while you sleep, and the agent can dream over its memory.
  143. ## A memory, up close
  144. <picture>
  145. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/plate-up-close-dark.png">
  146. <img alt="Plate I, memories up close: a round field of the whole memory, enlarged 6.5 times under the lens. Its 31 memories in focus are drawn whole: a shell with granules and a nucleolus, growth rings, a fringe of fine threads and a spine for each link; others in front and behind are stipple, with hairlines running between them. Four are lettered, with their values beside them. a, a lesson kept from experience b: strength 0.78, stability 1.00, accessibility 0.36, not recalled yet, 5 links. b, an experience: strength 0.51, stability 1.00, accessibility 0.11, not recalled yet, 3 links. c, an experience: strength 0.46, stability 1.00, accessibility 0.64, recalled twice, 13 links. d, an experience: strength 0.57, stability 1.00, accessibility 0.73, recalled once, 14 links. A small map of the whole memory shows where the field lies." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/plate-up-close.png">
  147. </picture>
  148. <picture>
  149. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/anatomy-dark.png">
  150. <img alt="Fig. 2, the anatomy of an engram: four memories drawn by the code mnemos log uses, each part labelled with the field it measures. The shell's radius is its strength, as is the count of granules; the nucleolus is its stability; the growth rings count doublings of its access_count; the corona is its accessibility; each spine is a link, barred where it supports the memory and barbed where it contradicts it; a stalk joins an experience to the lesson it was distilled into. A table gives each memory's values." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/anatomy.png">
  151. </picture>
  152. Plate I enlarges a small field of the memory at the top of this page: the
  153. memories in it are real, and the values beside them are their own. Fig. 2 names
  154. the parts. This is how `mnemos log` draws a memory when you open it, and every
  155. part is one of its numbers: the shell's radius is its `strength`, the nucleolus
  156. its `stability`, the corona its `accessibility` and the rings its
  157. `access_count`. Each spine is a link, barred where it `supports` the memory and
  158. barbed where it `contradicts` it, and a stalk joins an experience to the lesson
  159. it was `distilled_into`.
  160. ## A memory's life
  161. <picture>
  162. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/life-dark.png">
  163. <img alt="Fig. 3, the life of a memory over its first 50 days, run on Mnemos's own rules. On a log scale, its accessibility starts at 0.5, is held at 0.4 or more for three days, and fades between recalls; each recall lifts it back to 0.8, and it fades more slowly after. Below 0.15 the agent is asked what it taught, and its answer becomes a lesson, kept at 0.8 strength and stability, that fades far more slowly. The memory itself goes dormant below 0.05 and is archived below 0.01. Two small charts below show its strength and stability over the same days." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/life.png">
  164. </picture>
  165. A memory fades unless it's used. Every four hours it gets a little harder to
  166. reach, more slowly the more settled and linked it is, and each recall brings it
  167. back and leaves it slower to fade. When something the agent wrote has faded far
  168. enough, its memory asks what it taught. The answer is kept as a lesson in the
  169. agent's own words, and the lesson outlives the details. A fact is asked instead
  170. whether it's still true, and the agent keeps it, corrects it or lets it go.
  171. Fig. 3 runs one experience through the rules Mnemos itself uses.
  172. ## How well it remembers
  173. Mnemos is built for continuity, and it works as memory too. We tested it on
  174. one person's real work, against the memory Claude Code already has, with the
  175. questions written before any run and the answers judged blind:
  176. | Test | Claude Code's own memory | With Mnemos |
  177. |:---|---:|---:|
  178. | Three months of work, 30 tasks | 35% | 65% |
  179. | Two years of work, 64 sealed questions | 14% | 41% |
  180. | The same two years, with every tool it normally has | 22% | 42% |
  181. <sub>Facts recalled, a partly right answer counting half, with the same model in
  182. every setup, in October 2026. Claude Code's own memory is its CLAUDE.md files and
  183. memory folder, and in the last test its last month of sessions too. In the second
  184. test, every setup could open files but not search them; in the last, a question
  185. left unanswered at the 15-minute limit was run again with more time. Cost is what
  186. Claude Code reports for the model's use, at API prices.</sub>
  187. In the first test, judged blind side by side, Mnemos's answer was the better one
  188. on 24 of the 30 tasks and the built-in memory's on 4, and on decisions made
  189. together it recalled 83% against 13%. It cost less in the first two tests, 22%
  190. and 8% less. And added alongside the built-in memory, instead of in place of it,
  191. it raised that memory's 35% to 58%. In the last test, it remembered more from
  192. every part of the two years, the oldest included, gave fewer wrong answers (7
  193. against 12), and took about half as long.
  194. What carries is the memory the agent keeps in its own words. In the last test,
  195. the same memories saved as plain files the agent could search did about as well
  196. as Mnemos, with 43% of the facts to its 42%. Mnemos is what has the agent keep
  197. them, keeps them alive between sessions, and wakes it with them.
  198. It keeps what the agent chooses to keep, in its own words: a preference, a
  199. correction, a decision, where the work stands. It doesn't index your documents
  200. or search your codebase, and it sits alongside any memory or search you already
  201. use.
  202. ## What leaves your machine
  203. Local SQLite. No account, no API key, no service of its own. Nothing leaves your
  204. machine that you haven't been told about: a model provider, Gemini embeddings
  205. and the cue's judge only if you turn them on, and the quiet hours unless you say
  206. no.
  207. <picture>
  208. <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/map-dark.png">
  209. <img alt="Fig. 4, where Mnemos runs, drawn as a data-flow diagram. Inside a dashed line marking your machine: you, your agent, Mnemos with its hooks, twelve tools and a local model, its memory in SQLite, the scheduler, and its page in your browser. Across the line: your agent's model, which receives whatever the agent reads and where the quiet hours run; and, only with your yes, a model provider, Gemini and the cue's judge, all reached through Mnemos." src="https://raw.githubusercontent.com/Riley-Coyote/mnemos-mcp/main/docs/images/map.png">
  210. </picture>
  211. For now the quiet hours run through Claude Code, so they come to a memory kept
  212. mostly by a Claude model: Mnemos doesn't wake another kind of model in an
  213. agent's memory. They run on your own plan, so what the agent thinks over in
  214. them goes to Anthropic: its words for the hour, short excerpts of its recent
  215. memory, its wake, and whatever it reads or recalls. Nothing turns them on before
  216. you've been told: setup asks once at a terminal, yes by default, and when an
  217. agent sets Mnemos up, it has the agent tell you. With no `claude` command they
  218. stay off. To turn them off:
  219. ```bash
  220. mnemos daemon uninstall --hours --write
  221. ```
  222. [Privacy and security][privacy] lists each one, and how to turn it off.
  223. ## Documentation
  224. - **[The guide][guide]:** every way to set it up, the twelve tools, the page
  225. and the commands behind it, what runs between sessions, the command line and
  226. configuration.
  227. - **[Setup][setup]:** the production path, step by step.
  228. - **[Privacy and security][privacy]:** what can leave your machine, and the
  229. boundaries Mnemos keeps.
  230. - **[Hermes][hermes]** and **[OpenClaw][openclaw]:** Mnemos with those agents.
  231. - **[The vision][vision]** and **[the identity model][identity]:** why it's
  232. built the way it is.
  233. - **[Changelog][changelog]**
  234. ## Uninstall
  235. `mnemos uninstall` says what it would remove, and `mnemos uninstall --write`
  236. removes it: its hooks, its server entries for Claude Code, Codex and Claude
  237. Desktop, and its scheduled jobs. The memories stay, in `~/.mnemos`. They're the
  238. agent's, so deleting them is left to you.
  239. ## Contributing
  240. [CONTRIBUTING.md][contributing] says how to set up and run the tests. Please
  241. report a vulnerability privately, as [SECURITY.md][security] describes.
  242. ## License
  243. [Apache-2.0][license], with a [NOTICE][notice]. Releases before 0.5.0 were
  244. published under the MIT License, and stay under it; code contributed under it
  245. keeps its notice, in the NOTICE.
  246. [badge-pypi]: https://img.shields.io/pypi/v/mnemos-continuity?style=flat-square&labelColor=1b1d27&color=464c6c
  247. [badge-python]: https://img.shields.io/pypi/pyversions/mnemos-continuity?style=flat-square&labelColor=1b1d27&color=464c6c
  248. [badge-tests]: https://img.shields.io/github/actions/workflow/status/Riley-Coyote/mnemos-mcp/release-hardening.yml?branch=main&style=flat-square&label=tests&labelColor=1b1d27
  249. [badge-license]: https://img.shields.io/badge/license-Apache--2.0-464c6c?style=flat-square&labelColor=1b1d27
  250. [pypi]: https://pypi.org/project/mnemos-continuity/
  251. [tests]: https://github.com/Riley-Coyote/mnemos-mcp/actions/workflows/release-hardening.yml
  252. [guide]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/docs/guide.md
  253. [setup]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/SETUP.md
  254. [privacy]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/docs/privacy-security.md
  255. [hermes]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/HERMES_INSTALL.md
  256. [openclaw]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/docs/openclaw-integration.md
  257. [vision]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/docs/vision.md
  258. [identity]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/docs/identity-model.md
  259. [changelog]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/CHANGELOG.md
  260. [contributing]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/CONTRIBUTING.md
  261. [security]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/SECURITY.md
  262. [license]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/LICENSE
  263. [notice]: https://github.com/Riley-Coyote/mnemos-mcp/blob/main/NOTICE

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.