mnemofish 0.2.0__tar.gz

mnemofish-0.2.0/.gitignore

@@ -0,0 +1,17 @@
+# Python
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+dist/
+build/
+.venv/
+venv/
+
+# mnemo derived index (rebuildable — never commit)
+.mnemo/
+*.sqlite
+*.sqlite-*
+
+# embedding model cache
+.cache/

mnemofish-0.2.0/DESIGN.md

@@ -0,0 +1,294 @@
+# mnemo — Tasarım Dokümanı
+
+> Çalışma adı: **mnemo** (Mnemosyne — hafıza). Değiştirilebilir.
+> Bu dosya iç tasarım/çalışma dokümanıdır (Türkçe). Public README ayrıca İngilizce yazılacak.
+> Durum: TASLAK v0.1 — scope dondurma aşaması.
+
+Kişisel, projeler-arası, AI-arası **kalıcı hafıza (persistent memory)** sistemi.
+Markdown vault üstünde çalışan bir **MCP memory server** + **CLI** + **Claude Code hook**'ları.
+
+---
+
+## 1. Problem
+
+Mevcut hafıza araçları (ör. claude-mem) **depolamayı** çözüyor ama **geri-çağırmayı (retrieval)** çözmüyor.
+
+> Yaşanan: "Kaydet" deniyor, kaydediliyor — ama AI doğru anıyı doğru anda **okumuyor**.
+
+Asıl darboğaz: bilgiyi yazmak değil, **ilgili alt kümeyi doğru anda modelin context'ine otomatik enjekte etmek.**
+
+İkinci problem: bilgi büyüdükçe token tüketimi ve bilgi kalabalığı artar. Her şeyi yüklemek sürdürülemez.
+
+---
+
+## 2. Temel İlkeler
+
+1. **Retrieval-first.** Sistem "yazma"ya değil, "doğru anıyı otomatik getirme"ye göre tasarlanır.
+2. **Push > Pull.** MCP tool (pull) modelin çağırmasını bekler — claude-mem'in patladığı yer. Gerçek otomasyon **hook** (push) ile: AI sormadan ilgili not context'e enjekte edilir.
+3. **Vault = tek kaynak.** Markdown dosyalar tek gerçek. Index (sqlite/embedding) türetilmiştir, her an silinip yeniden üretilebilir.
+4. **Sadece türetilemeyeni sakla.** Dosya ağacı/fonksiyon imzaları AI tarafından bulunabilir → saklama. Kararlar, ilişkiler, sözleşmeler, hatalar, niyet → sakla.
+5. **Harita önce, düğüm sonra.** Token'ı sabit tutmak için: önce küçük index (MOC) yüklenir, sadece ilgili atomik not genişletilir. Asla "her şey".
+6. **Atomik notlar.** Bir not = bir karar/gerçek/hata. Küçük → tek tek ucuz yüklenir, çakışma minimum, embedding chunking gereksiz.
+
+### Türetilebilir vs türetilemez
+
+| AI kendi bulabilir (SAKLAMA) | AI bulamaz (SAKLA) |
+|---|---|
+| Dosya ağacı (`glob`) | Topoloji: ne nereye konuşuyor |
+| Vendor kod (HAL/CMSIS, node_modules) | Ortak protokol/sözleşmeler |
+| Fonksiyon imzaları | Neden bu karar alındı |
+| Hangi dosya var | Şu an ne yapılıyor / gotcha / hatalar |
+
+---
+
+## 3. Mimari
+
+**Çekirdek kütüphane + iki ön-yüz.** Bu ayrım belkemiğidir — auto-recall'ı mümkün kılar.
+
+```
+            ┌──────────────────────────────────────────┐
+            │  Vault (markdown + frontmatter)          │  ← tek kaynak, Obsidian'da da düzenlenir
+            └───────────────────┬──────────────────────┘
+                                │ parse (incremental, mtime/hash)
+                     ┌──────────▼───────────┐
+                     │  ÇEKİRDEK LİB        │  index.sqlite (FTS5 + vektör)
+                     │  parse / index /     │  ← türetilmiş, .gitignore, rebuild
+                     │  search / write      │
+                     └─────┬───────────┬────┘
+              ┌────────────▼──┐    ┌───▼─────────────────┐
+              │  CLI ön-yüz    │    │  MCP ön-yüz          │
+              │  (PUSH)        │    │  (PULL)              │
+              │  Claude hook   │    │  tüm MCP-uyumlu AI   │
+              │  oturum başı   │    │  konuşma içi tool    │
+              │  recall enjekte│    │  çağrısı             │
+              └────────────────┘    └─────────────────────┘
+```
+
+- **Çekirdek lib:** parse + index + search + write. Tek mantık burada.
+- **CLI ön-yüz:** hook'lardan çağrılır (push). Oturum başında ilgili MOC + top-N notu basıp context'e enjekte eder. `mnemo search/write/init/sync/...`.
+- **MCP ön-yüz:** aynı çekirdeği MCP tool'ları olarak sunar → Claude Code, Cursor ve diğer MCP istemcileri aynı aramayı kullanır.
+
+---
+
+## 4. Vault Yapısı
+
+Vault düz bir klasör (= private GitHub reposu). Önerilen layout:
+
+```
+my-memory/                    ← private repo
+├── daily/                    günlük notlar, todo, "bugün ne yaptım"
+│   └── 2026-06-23.md
+├── projects/
+│   └── <proje>/
+│       ├── _moc.md           proje haritası (Map of Content) — index notu
+│       └── <atomik>.md       tek karar/gerçek
+├── lessons/                  hatalar, dersler (tag'le retrieval)
+├── protocol/                 teknik sözleşmeler (ör. RF v2)
+├── reference/                kalıcı bilgi (URL, dashboard, ticket)
+├── .gitignore                index.sqlite + .cache hariç
+└── .mnemo/                   (gitignore) index.sqlite, embedding cache
+```
+
+`projects/`, `lessons/` vb. **sabit değil** — kullanıcı kendi taksonomisini kurabilir; sistem `type` frontmatter'a göre çalışır, klasör adına değil.
+
+---
+
+## 5. Not Şeması (frontmatter)
+
+Her not = markdown + YAML frontmatter:
+
+```markdown
+---
+id: 20260623-rf-uid-sequential        # kararlı kimlik (tarih-slug)
+type: decision                         # decision | lesson | daily | project | reference | note
+title: RF güncellemesi sıralı yapılır
+project: stm32-rf-ota                  # opsiyonel
+tags: [rf, protocol, stm32]
+created: 2026-06-23
+updated: 2026-06-23
+summary: Cihazlar tek tek güncellenir; eşzamanlı değil — sistem kilitlenmesini önler.
+links: [20260623-rf-uid-identity]      # [[wikilink]] de desteklenir
+---
+
+Sıralı güncelleme: id1 biter, id2 başlar. Avantaj: tüm cihazlar aynı anda
+bootloader'a düşmez, sistem ayakta kalır...
+```
+
+- `summary` zorunlu ve **kısa** → index/MOC bunu gösterir, gövdeyi değil. Token disiplini buradan gelir.
+- `type` retrieval filtresini sağlar (teknik görevde `daily` notları boğmaz).
+- `links` ilişki grafiğini kurar (MOC + backlink + AI traversal).
+
+---
+
+## 6. MOC (Map of Content)
+
+`_moc.md` = bir projenin/konunun **haritası**. Atomiklere link + tek satır özet.
+
+```markdown
+---
+type: project
+title: STM32 RF OTA — MOC
+project: stm32-rf-ota
+---
+# STM32 RF OTA
+
+## Kararlar
+- [[20260623-rf-uid-identity]] — kimlik = 96-bit STM32 UID, hash yok
+- [[20260623-rf-uid-sequential]] — güncelleme sıralı, eşzamanlı değil
+
+## Bileşenler
+- Sender STM32 (RF gateway), PC Uploader (Python/Qt), MobileUploader (Flutter)
+- Alıcılar: stpm, stpm_fc (bootloader) + app'leri
+
+## Açık işler
+- [ ] DISCOVER_ACK 7→18 byte (UID) geçişi
+```
+
+Recall akışı: **MOC önce yüklenir** → AI ilgili linki görür → sadece o atomik notu `get` ile açar. Vault 10.000 nota çıksa bile bir görev = 1 MOC + birkaç atomik.
+
+---
+
+## 7. Index Katmanı
+
+- **Store:** vault markdown. **Index:** `.mnemo/index.sqlite` (atılabilir).
+- **Lexical:** SQLite **FTS5** (keyword/tag araması, deterministik, model gerektirmez).
+- **Semantic:** lokal embedding (sentence-transformers) → `sqlite-vec` ile vektör araması (paraphrase/eşanlam yakalar).
+- **Hybrid:** FTS5 + vektör sonuçları birleştirilir (rerank).
+- **Incremental:** dosya başına mtime/hash → sadece değişeni yeniden parse+embed. Tüm vault'u her seferinde işleme yok.
+- **Embedding lokal:** API yok, offline, gizli. (API opsiyonel eklenebilir.)
+
+---
+
+## 8. Retrieval (token disiplini)
+
+`search` **özet + path + skor** döndürür, **tam gövde değil.** Map-then-expand sözleşme seviyesinde gömülü.
+
+```
+search("rf güncelleme sırası", type=decision, k=5)
+  → [{id, title, summary, path, score}, ...]   # ~5 satır, ucuz
+get(path)                                        # sadece gerekirse tam gövde
+```
+
+Böylece bilgi büyüdükçe görev başına token **sabit** kalır.
+
+---
+
+## 9. MCP Tool API
+
+| Tool | Girdi | Çıktı | Not |
+|---|---|---|---|
+| `memory_search` | query, type?, project?, tags?, k=5 | özet+path+skor listesi | gövde DÖNMEZ |
+| `memory_get` | path/id | tam not | on-demand |
+| `memory_moc` | project | proje haritası | "harita" |
+| `memory_write` | type, title, body, tags, links | yeni/güncellenmiş not | **yazmadan-önce-ara** (dedup) |
+| `memory_link` | id_a, id_b | — | düğümleri bağla |
+
+Notlar MCP **resource** olarak da sunulabilir (opsiyonel).
+
+---
+
+## 10. CLI Komutları
+
+| Komut | İş |
+|---|---|
+| `mnemo init [--remote <github-url>]` | vault'u (git reposu olarak) kur |
+| `mnemo reindex` | index'i sıfırdan kur (taşıma sonrası) |
+| `mnemo search <query> [--type --project -k]` | hook/manuel arama |
+| `mnemo write ...` | not ekle (dedup'lı) |
+| `mnemo recall [--project]` | oturum-başı enjeksiyon bloğu üret (hook bunu basar) |
+| `mnemo sync` | git pull + push |
+| `mnemo clone <github-url>` | yeni makine: klonla + reindex |
+| `mnemo export <file>` / `import <file>` | tek-parça taşıma (Drive vb.) |
+| `mnemo compact` | dedup/çürüme temizliği |
+
+---
+
+## 11. Hook Akışı (Claude Code — PUSH)
+
+Auto-recall'ı mümkün kılan kısım. `settings.json` hook'ları:
+
+- **SessionStart:** `mnemo recall --project <cwd>` → ilgili MOC + son kararlar/dersler context'e enjekte edilir. AI **sormadan** geçmişi bilerek başlar.
+- **UserPromptSubmit (opsiyonel):** prompt'tan keyword/embedding → top-N not enjekte (göreve özel recall).
+- **Stop / SessionEnd:** oturumdan karar/hata/yapılanı çıkar → `mnemo write` (auto-capture, v3).
+
+> Bu, claude-mem'in çözemediği "okuma döngüsü"nü kapatır.
+
+---
+
+## 12. Cross-AI
+
+- **MCP-uyumlu** (Claude Code, Cursor, ...): aynı MCP server'a bağlanır → aynı arama/recall.
+- **MCP-suz** (düz ChatGPT web vb.): MCP kullanamaz → ya `mnemo export` ile parça yapıştırma, ya vault'u elle okutma. Dürüst sınır.
+- Store evrensel (markdown), retrieval-wiring araç-başına.
+
+---
+
+## 13. Taşınabilirlik — GitHub omurgası
+
+- **Vault = private GitHub reposu.** Sadece markdown commit'lenir; `index.sqlite` + embedding cache `.gitignore`.
+- **Yeni makine / yeni AI:** `mnemo clone <github-url>` → klonla + reindex → her şeyi bilerek gelir. ("Hafızayı çek.")
+- **Avantaj:** versiyonlu bilgi (ne zaman öğrendim/değiştirdim), bedava sync, merge, yedek.
+- **Drive/Dropbox:** opsiyonel; vault düz klasör olduğu için çalışır ama versiyon/merge vermez. `export/import` tek-parça taşıma için.
+- Atomik notlar → git merge çakışması minimum.
+
+---
+
+## 14. Çürüme Önleme (claude-mem'in ölüm sebebi)
+
+- **Yazmadan-önce-ara:** `write` önce benzer not arar; varsa yeni açmaz → günceller/ekler.
+- **`compact`:** periyodik dedup + ölü link temizliği.
+- **summary zorunlu:** her not özetlenebilir olmalı; özetlenemeyen not = kötü not.
+
+---
+
+## 15. Gizlilik / Güvenlik
+
+- **İki repo, karıştırma:**
+  - **PUBLIC** (OSS): `mnemo` yazılımı. Generic, vault-path config, kişisel veri YOK.
+  - **PRIVATE**: kullanıcının vault'u (notlar, kararlar, hatalar).
+- Araç remote'un **public** göründüğünü sezerse uyarır (notların yanlışlıkla yayınlanmasını önle).
+- Lokal embedding → veri makineden çıkmaz (API opsiyonel ve açıkça opt-in).
+
+---
+
+## 16. Teknoloji
+
+- **Dil:** Python. Dağıtım: `uvx` (npx kadar kolay).
+- **Bağımlılıklar:** `mcp` (SDK), `python-frontmatter`, `sentence-transformers`, `sqlite-vec`, SQLite FTS5 (stdlib).
+- **Store:** vault markdown + `.mnemo/index.sqlite` (sidecar, atılabilir).
+
+---
+
+## 17. İnşa Yol Haritası (bağımlılık sırası — hepsi tam sürümde)
+
+| Faz | Çıktı | Kanıt | Durum |
+|---|---|---|---|
+| **F1 — Çekirdek** | parse + frontmatter + FTS5 + incremental index | `search` doğru notu döndürür | ✅ |
+| **F2 — CLI + Hook** | `recall/search/write` + Claude SessionStart hook (push) | AI sormadan geçmişi bilerek başlar | ✅ |
+| **F3 — MCP** | `memory_search/get/moc/write` server | Cursor/Claude aynı vault'ta arar | ✅ |
+| **F4 — Taşıma** | `init/sync/clone/export/import` (GitHub) | yeni makinede klonla+reindex çalışır | ✅ |
+| **F5 — Semantic + daily** | fastembed+sqlite-vec hybrid (RRF), içerik dedup, `daily` journaling | paraphrase araması FTS'in kaçırdığını bulur | ✅ |
+
+F2 sonunda **okuma döngüsü kapandı** → claude-mem'i geçer. 24 test geçiyor.
+
+**Embedding backend kararı (çözüldü):** fastembed (ONNX) + `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` (384-dim, çok-dilli, Türkçe). torch yok → hafif/hızlı cold-start. SessionStart hook (`recall`) embedding YÜKLEMEZ (sadece SQL) → hızlı kalır; model yalnız `search/serve/write/reindex`'te lazy yüklenir.
+
+**Sonraki (F5+ / opsiyonel):** transcript'ten otomatik yakalama (rot riski yüksek — bilerek ertelendi; şimdilik recall footer modeli `memory_write`'a yönlendiriyor), `compact` (dedup/ölü-link temizliği), MOC yarı-otomatik üretimi.
+
+---
+
+## 18. Kararlar + Açık Sorular
+
+### Verilen kararlar (2026-06-23)
+1. **Embedding modeli:** hız + kararlılık öncelik. Notlar **Türkçe** → çok-dilli MiniLM (`paraphrase-multilingual-MiniLM-L12-v2`) varsayılan. FTS5 keyword zaten dilden bağımsız; embedding katmanı çok-dilli.
+2. **Proje tespiti:** **git remote slug → yoksa klasör adı** fallback.
+3. **İsim:** `mnemo` kalır.
+
+### Açık (sonra)
+- **Auto-capture tetiği:** her oturum sonu mu, commit'te mi, manuel onaylı mı? (F5)
+- **MOC üretimi:** elle mi, yarı-otomatik mi (atomiklerden link toplama)? (F3+)
+- **Embedding backend:** sentence-transformers (torch, ağır) vs ONNX/fastembed (hızlı cold-start — hook için önemli). F1'de modül pluggable; dağıtımda ONNX'e geçiş değerlendirilecek.
+
+---
+
+> Sonraki adım: bu DESIGN onaylanınca → public repo iskeleti + `pyproject.toml` + F1 çekirdek.

mnemofish-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Emir Furkan Sarı
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mnemofish-0.2.0/PKG-INFO

@@ -0,0 +1,243 @@
+Metadata-Version: 2.4
+Name: mnemofish
+Version: 0.2.0
+Summary: Persistent, portable, cross-AI memory over a markdown vault — with push-based auto-recall (MCP + CLI).
+Project-URL: Homepage, https://github.com/Emirfs/mnemo
+Project-URL: Repository, https://github.com/Emirfs/mnemo
+Project-URL: Issues, https://github.com/Emirfs/mnemo/issues
+Author: Emir Furkan Sarı
+License: MIT
+License-File: LICENSE
+Keywords: ai,auto-recall,claude,claude-code,llm,mcp,memory,model-context-protocol,obsidian,persistent-memory,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.10
+Requires-Dist: python-frontmatter>=1.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Provides-Extra: embed
+Requires-Dist: fastembed>=0.4; extra == 'embed'
+Requires-Dist: sqlite-vec>=0.1.6; extra == 'embed'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2.0; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/Emirfs/mnemo/master/docs/assets/logo.svg" alt="mnemo pixel-art clownfish" width="220" />
+
+# 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](https://img.shields.io/badge/python-3.10+-3776ab?logo=python&logoColor=white)](https://www.python.org/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-7c3aed)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-22c55e.svg)](#license)
+[![Tests](https://img.shields.io/badge/tests-28%20passing-22c55e.svg)](#status)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff8a3d.svg)](#contributing)
+[![Vibe](https://img.shields.io/badge/just%20keep-swimming-1e90ff.svg)](#)
+
+</div>
+
+> [!NOTE]
+> **P. Sherman, 42 Wallaby Way, Sydney.**
+> Dory could *say* the address. She just couldn't *recall* it when it mattered.
+> That's your AI. That's every memory tool that only does storage. mnemo is the one that remembers at the right moment.
+
+---
+
+## 🫧 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
+
+```bash
+# 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).
+
+<details>
+<summary>From source (dev)</summary>
+
+```bash
+uv venv
+uv pip install -e ".[dev]"            # core (FTS5 keyword search)
+uv pip install -e ".[dev,embed,mcp]"  # + semantic search + MCP server
+```
+</details>
+
+```bash
+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.*
+
+```jsonc
+// .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:
+
+```bash
+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
+
+```markdown
+---
+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`](./DESIGN.md) for
+architecture and roadmap.
+
+- **F1** — core: markdown/frontmatter parse, FTS5, incremental index
+- **F2** — `recall` + `write` + SessionStart hook (push auto-recall) — [`hooks/`](./hooks)
+- **F3** — MCP server (`memory_search/get/moc/write`) — [`docs/mcp.md`](./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](#license) © Emir Furkan Sarı
+
+<div align="center"><sub><i>mnemo /ˈniːmoʊ/ — from Mnemosyne (memory) ⋅ also a small orange fish who refuses to be forgotten.</i></sub></div>