Skip to main content
mnemo pixel-art clownfish

mnemo

Your AI has goldfish memory. 🐠 mnemo gives it an elephant's. 🐘

Persistent, portable, cross-AI memory over a plain markdown vault — with push-based auto-recall so the model remembers your past work without being asked.

Python MCP License: MIT Tests PRs welcome Vibe


🫧 The problem (you've lived this)

You:  "remember we decided X yesterday"
AI:   "i have no memory of that, what is X"
You:  *re-explains the entire project for the 9th time*

New chat → instant amnesia. The decision from yesterday? Gone. The bug you already killed? It's back, baby. The contract two repos share? Never heard of her.

Most "memory" tools only solve storage — they save notes the model never reads back. Cool, you wrote down Nemo's address on a fridge he can't reach. 🧲 The actual hard part is retrieval: getting the right memory into context at the right moment.

Storage was never the hard part. Retrieval is. 🎯

🐠 How mnemo keeps finding Nemo

Two currents. Same ocean.

🌊 PUSH — the rescue a SessionStart hook injects the relevant notes into context before you type a word the AI starts every session already knowing your history
🪝 PULL — the net an MCP server lets any MCP-capable AI search the same vault mid-chat Claude Code, Cursor, whatever — same brain

Nemo never stays lost. He just keeps swimming back.

✨ Why it actually slaps

  • 🗂️ Vault = source of truth. Plain markdown + YAML frontmatter. Edit it in Obsidian, your editor, or a cave with a stick. The index (SQLite FTS5 + vectors) is derived and rebuildable — never committed.
  • 🧮 Map, then expand. Search returns summaries + paths, not full bodies. Token cost stays flat whether your vault has 10 notes or 10,000. Your context window stays unbothered.
  • 🧠 Store only what can't be re-derived. File trees and function signatures? The AI can find those itself. Decisions, gotchas, contracts, why-the-hell-did-we-do-it-this-way? Saved.
  • 🔍 Hybrid search. Keyword (FTS5) + semantic (local embeddings, RRF-fused) — catches the paraphrase keyword search fumbles. Runs 100% local: offline, private, zero API spend.
  • 🚚 Portable AF. Your vault is a private git repo. New machine, new AI? mnemo clone <url> → reindex → it knows everything. Memory that survives a laptop death.
  • 🔗 Shared across repos. Drop a .mnemo-project marker and many repos feed one project brain.

🚀 Quick start

# zero-install run (recommended)
uvx mnemofish --vault ./my-vault init

# or install it (ships the `mnemo` command)
pip install "mnemofish[embed,mcp]"    # everything: semantic search + MCP server
pip install mnemofish                  # core only (FTS5 keyword search)

📦 PyPI package is mnemofish; the CLI command is mnemo (the alias mnemofish also works).

From source (dev)
uv venv
uv pip install -e ".[dev]"            # core (FTS5 keyword search)
uv pip install -e ".[dev,embed,mcp]"  # + semantic search + MCP server
uv run mnemo --vault ./my-vault init
uv run mnemo --vault ./my-vault write \
  --type decision --title "RF update is sequential" \
  --summary "Devices update one at a time, not concurrently — prevents system lockup."
uv run mnemo --vault ./my-vault search "rf update order"
uv run mnemo --vault ./my-vault daily "what I shipped today"

🪝 Auto-recall in 30 seconds

Wire the SessionStart hook and your AI greets you with the relevant Map of Content + recent decisions — automatically, every time.

// .claude/settings.json  (full example: hooks/settings.example.json)
{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup", "hooks": [{
        "type": "command",
        "command": "mnemo --vault \"/path/to/my-memory\" recall --hook --reindex --project-dir \"$CLAUDE_PROJECT_DIR\""
      }]}
    ]
  }
}

For MCP clients, run the server and point your client at it:

uv run mnemo --vault ./my-vault serve   # exposes memory_search / get / moc / write

🧭 How it works

        ┌──────────────────────────────────────────┐
        │  Vault (markdown + frontmatter)          │  ← single source of truth (Obsidian-friendly)
        └───────────────────┬──────────────────────┘
                            │ parse (incremental: mtime/hash)
                 ┌──────────▼───────────┐
                 │   CORE LIBRARY       │   index.sqlite (FTS5 + vectors)
                 │  parse / index /     │   ← derived, .gitignored, rebuildable
                 │  search / write      │
                 └─────┬───────────┬────┘
          ┌────────────▼──┐    ┌───▼─────────────────┐
          │  CLI + hook    │    │   MCP server         │
          │  (PUSH)        │    │   (PULL)             │
          │  session-start │    │   any MCP-capable AI │
          │  auto-recall   │    │   in-chat tool calls │
          └────────────────┘    └─────────────────────┘

A task = 1 MOC + a few atomic notes, no matter how big the vault gets. Flat tokens. 📉

📓 A note looks like this

---
id: 20260623-rf-uid-sequential
type: decision           # decision | lesson | daily | project | reference | note
title: RF update is sequential
project: stm32-rf-ota
tags: [rf, protocol, stm32]
summary: Devices update one at a time, not concurrently — prevents system lockup.
links: [20260623-rf-uid-identity]
---

Sequential update: id1 finishes, id2 begins. All devices don't drop into the
bootloader at once, so the system stays alive...

summary is required and short — the index shows that, not the body. That's where the token discipline comes from. (No summary = bad note. The fish judges you. 🐠)

🛠️ Commands

Command What it does
init / sync / clone manage the vault as a private git repo
write / daily add notes (deduped) / append journal entries
search / get hybrid search (summaries) / fetch one full note
reindex rebuild the derived index from scratch
recall --hook emit the SessionStart recall block (push)
serve run the MCP server (pull, cross-AI)
export / import zip the vault for one-shot transfer (Drive, etc.)

📊 Status

Working. F1–F6 shipped, 28 tests green. ✅ See DESIGN.md for architecture and roadmap.

  • F1 — core: markdown/frontmatter parse, FTS5, incremental index
  • F2 — recall + write + SessionStart hook (push auto-recall) — hooks/
  • F3 — MCP server (memory_search/get/moc/write) — docs/mcp.md
  • F4 — portability: init / sync / clone / export / import
  • F5 — semantic hybrid search (fastembed + sqlite-vec, RRF), content dedup, daily journaling
  • F6 — .mnemo-project marker for shared cross-repo project memory

🔒 Privacy

Two repos, never mixed: the public one is this software (generic, zero personal data); your private one is your vault. Embeddings run locally, so your notes never leave your machine. 🏠 (API embeddings are opt-in only.)

🤝 Contributing

PRs and issues welcome. Small Python codebase — core library + two frontends. Run the suite with pytest, keep notes atomic, and just keep swimming. 🐠

License

MIT © Emir Furkan Sarı

mnemo /ˈniːmoʊ/ — from Mnemosyne (memory) ⋅ also a small orange fish who refuses to be forgotten.

Metadata

Release files for mnemofish 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mnemofish 0.2.0
File Size Uploaded Provenance Actions
mnemofish-0.2.0.tar.gz 168.4 kB Without provenance Details for mnemofish-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mnemofish 0.2.0
File Interpreter ABI Platform Actions
mnemofish-0.2.0-py3-none-any.whl Python 3 none any Details for mnemofish-0.2.0-py3-none-any.whl

Total release size: 191.9 kB

Release files / mnemofish-0.2.0.tar.gz

Download URL mnemofish-0.2.0.tar.gz
Size 168.4 kB
Tags Source
SHA-256 checksum
How to use checksums
bf9bdb655c88e1584a4d7141f599c7015d8bdb3fefdc771093000f2b5d568d58
BLAKE2b-256 checksum
How to use checksums
2fcb9c36f1169287160ab27aed6260cbe3aec018afb5afd5cf9a83b404443314
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.5 {"installer":{"name":"uv","version":"0.11.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / mnemofish-0.2.0-py3-none-any.whl

Download URL mnemofish-0.2.0-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7b5255271718bc7996185e6eecd89aa7ef7d9d5487443b64bb1db9c0d213f45d
BLAKE2b-256 checksum
How to use checksums
99185506063132638abcad95baf025afcf8014a9a2c2bb1e44b16fab1c2af48f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.5 {"installer":{"name":"uv","version":"0.11.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for mnemofish 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page