mlx-memo 0.5.0__tar.gz

mlx_memo-0.5.0/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "memo",
+  "description": "Local MCP memory for AI agents on Apple Silicon. MLX-native, sqlite-vec, markdown-on-disk.",
+  "owner": {
+    "name": "Fernando Ferrari",
+    "url": "https://github.com/jagoff"
+  },
+  "plugins": [
+    {
+      "name": "memo",
+      "description": "Persistent semantic memory. Slash command `/memo` + MCP tools `mcp__memo__memory_*`.",
+      "source": "./",
+      "category": "memory"
+    }
+  ]
+}

mlx_memo-0.5.0/.claude-plugin/plugin.json

@@ -0,0 +1,13 @@
+{
+  "name": "memo",
+  "description": "Local MCP memory for AI agents — MLX-native on Apple Silicon, sqlite-vec store, markdown-on-disk in your Obsidian vault. Zero Ollama, zero cloud APIs.",
+  "version": "0.5.0",
+  "author": {
+    "name": "Fernando Ferrari",
+    "url": "https://github.com/jagoff"
+  },
+  "homepage": "https://github.com/jagoff/memo",
+  "repository": "https://github.com/jagoff/memo",
+  "license": "MIT",
+  "keywords": ["memory", "mcp", "mlx", "obsidian", "rag", "agents", "local-first"]
+}

mlx_memo-0.5.0/.github/workflows/test.yml

@@ -0,0 +1,34 @@
+name: test
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    # Linux runner is enough — `mlx`/`mlx-lm` deps are gated to
+    # `darwin/arm64` in pyproject.toml and the real-MLX smoke tests
+    # auto-skip via the `requires_mlx` marker (see conftest.py) when
+    # `mlx_lm` isn't importable.
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install uv
+        run: pip install uv
+      - name: Install package + dev deps
+        run: |
+          uv venv .venv
+          uv pip install -e '.[dev]'
+      - name: Lint (ruff)
+        run: .venv/bin/ruff check src/ tests/
+      - name: Tests (excluding slow real-MLX smoke)
+        run: .venv/bin/python -m pytest -q -m "not slow"

mlx_memo-0.5.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Build artifacts
+build/
+dist/
+dist.v*/
+
+# Environments
+.venv/
+venv/
+.env
+.env.local
+
+# Local DB / state
+*.db
+*.db-shm
+*.db-wal
+
+# Editor / IDE / OS
+.DS_Store
+.claude/
+.windsurf/
+.idea/
+.vscode/
+
+# Node (integrations)
+node_modules/
+integrations/**/node_modules/
+integrations/**/dist/
+integrations/**/.paperclip-sdk/

mlx_memo-0.5.0/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "memo": {
+      "type": "stdio",
+      "command": "memo-mcp",
+      "args": [],
+      "env": {}
+    }
+  }
+}

mlx_memo-0.5.0/CHANGELOG.md

@@ -0,0 +1,301 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.5.0] - 2026-05-12
+
+PyPI dist rename + TUI follow-ups (q/ESC quit, smaller layout).
+
+### Changed
+
+- **PyPI distribution renamed `memo-mcp` → `mlx-memo`.** The previous
+  name collided with [`milasd/memo-mcp`](https://github.com/milasd/memo-mcp)
+  (a ChromaDB-backed journal MCP) and risked install ambiguity for new
+  users. The Python module (`memo`), CLI binary (`memo`), MCP server
+  binary (`memo-mcp`), and the GitHub repo all keep their names — only
+  the PyPI dist moved. Existing `pip install memo-mcp ≤ 0.4.3` users
+  keep working; new installs use `pip install mlx-memo`. README +
+  CLAUDE.md updated, badges repointed.
+
+### Added (0.4.2 + 0.4.3 follow-ups, merged into 0.5.0)
+
+- **`q` / `ESC` exit** in `memo tui`. Background stdin reader in
+  cbreak mode sets a stop event; main loop polls. Falls back to
+  Ctrl+C-only when stdin isn't a TTY. Footer advertises the keys.
+- **TUI layout shrunk to ~18 rows**. Removed the panel-framed hero
+  (now an inline footer status line); corpus and runtime collapsed
+  to single-line summaries.
+
+### Fixed
+
+- **Legacy-path warning** (`stored path(s) don't resolve…`) now
+  silenced inside `memo tui` via `MEMO_SUPPRESS_LEGACY_WARN=1`. The
+  user can't act on it from inside the alt screen anyway. Outside the
+  TUI the message was rephrased ("heads-up: tu índice apunta a paths
+  antiguos") and explicitly labeled as not-an-error.
+
+## [0.4.1] - 2026-05-12
+
+Adds a live terminal dashboard and the recall-log plumbing that feeds it.
+
+### Added
+
+- **`memo tui`** — live, colored Rich-Live dashboard. Six panels:
+  corpus stats (totals + per-type breakdown + project count), runtime
+  (MLX warm/cold flags for embedder / reranker / chat, vault size,
+  watcher status from `launchctl print`), recent saves (last 10 from
+  `history.db`), recent recalls (last 8 from the new recall log), top
+  tags (project tags highlighted), and 14-day saves/recalls
+  sparklines (`▁▂▃▄▅▆▇█`). Refresh `--refresh N` (default 1.0 s).
+  Ctrl+C to exit. Zero new deps — Rich was already in.
+- **Recall log JSONL** at `~/.local/share/memo/recall.log`. The
+  `memo recall-hook` appends `{ts, prompt, hits[]}` per invocation
+  (best-effort, failures swallowed). Auto-rotates at ~200 KB to the
+  last 200 entries. Powers the TUI's recall panel; failures here can
+  never affect the hook's output.
+- **`/memo tui`** routing in `skills/memo/SKILL.md` (along with
+  `/memo watch`, `/memo install-watcher`, `/memo mine-history`).
+
+### Changed
+
+- New module `memo.dashboard` (~370 lines). Public API:
+  `run_tui`, `render`, `sparkline`, `append_recall_log`,
+  `read_recall_log`.
+
+## [0.4.0] - 2026-05-12
+
+Minor release — five "gamechanger" features land alongside a major
+repo-hygiene pass to make the project public-ready.
+
+### Added
+
+- **Project-scoped recall.** `memo save` now auto-attaches a
+  `project:<repo>` tag derived from the git toplevel of the caller's
+  cwd (or the `MEMO_PROJECT_TAG` env var). The recall hook reads `cwd`
+  from the Claude Code hook payload and additively boosts the score of
+  memorias that share the current project tag by
+  `MEMO_RECALL_PROJECT_BOOST` (default `0.15`). Opt out per-call with
+  `memo save --no-project-tag` or globally with
+  `MEMO_AUTO_PROJECT_TAG=0`. New module: `memo.project`.
+- **Token-budget-aware recall.** `MEMO_RECALL_TOKEN_BUDGET` (default
+  `0` = off) packs memorias greedily by score until the budget is
+  reached; the final memoria gets body-truncated to fit instead of
+  being dropped wholesale. Token estimate is `len(text)//4` — no
+  tiktoken dep.
+- **`memo mine-history`** — bulk-mine past Claude Code transcripts
+  under `~/.claude/projects/<hash>/*.jsonl` for insights, running the
+  same prefilter → helper-LLM extract → embedding-dedup pipeline as
+  the live capture hook. Resumable per-file via
+  `~/.local/share/memo/mine-history.json`. Flags:
+  `--path / --since / --limit / --dry-run / --debug / --json`.
+  New module: `memo.transcript_miner`.
+- **MCP resources** — `memo://recent` (top-20 by `updated` desc, with
+  per-memoria `memo://memory/<id>` links) and `memo://memory/{id}`
+  (full record, accepts prefix ≥4 chars). Clients can pin / drag
+  memorias into context without paying tool-call overhead per access.
+- **`memo watch`** — file-watcher daemon. Watches `cfg.memory_dir`
+  recursively via `watchdog`/FSEvents and triggers a debounced
+  `Memory.reindex()` (`--delay` configurable, default 2 s) when `.md`
+  files are modified. Bundled installer:
+  - `memo install-watcher` writes
+    `~/Library/LaunchAgents/com.fer.memo.watch.plist`, loads it via
+    `launchctl bootstrap`, and verifies. Logs to
+    `~/Library/Logs/memo/`. `KeepAlive=true`.
+  - `memo uninstall-watcher` boots out the job and removes the plist.
+  New module: `memo.watcher`. New dep: `watchdog>=4.0`.
+
+### Changed
+
+- **README rewritten for a public audience.** Cleaner hero, expanded
+  alternatives matrix (mem0 / letta / cognee / supermemory / mem-vault
+  / MCP-memory reference / engram) with the seven differentiators
+  spelled out in plain terms, and an updated `docs/architecture.svg`
+  that covers clients → MCP/CLI → core → MLX → storage rather than
+  just the recall pipeline.
+- **`.gitignore` expanded** to cover `dist.v*/`, `.claude/`,
+  `.windsurf/`, `integrations/**/node_modules/`,
+  `integrations/**/dist/`, `integrations/**/.paperclip-sdk/`, and
+  common IDE dirs.
+- **Test fixture default** now sets `MEMO_AUTO_PROJECT_TAG=0` so tests
+  asserting exact tag sets aren't polluted by the cwd-derived
+  project tag. Tests exercising the auto-tag flow opt back in
+  explicitly via `monkeypatch.setenv`.
+
+### Removed
+
+- Stale `dist.v0.2.0/`, `dist.v0.3.0/`, `dist.v0.3.1/` build snapshots
+  and accumulated `.DS_Store` files from the repo. `dist/` was already
+  gitignored; the dated variants weren't.
+
+## [0.3.3] - 2026-05-08
+
+Patch release — install-from-git fixes surfaced while validating the
+distributed-install flow on a clean machine.
+
+### Fixed
+
+- **`memo --version` crashed** with `RuntimeError: 'memo' is not
+  installed. Try passing 'package_name' instead.` because click's
+  `version_option` defaulted to `package_name="memo"` while the actual
+  PyPI/wheel dist is `memo-mcp`. Pinned the lookup explicitly.
+- **`DEFAULT_MEMORY_SUBDIR` pointed at the deprecated archive path**
+  (`04-Archive/99-obsidian-system/99-AI/memory`). Updated to the
+  current `99-obsidian/99-AI/memory` location, matching the user-facing
+  vault reorganization done on 2026-05-08. Existing installs that
+  override via `MEMO_MEMORY_SUBDIR` are unaffected.
+
+## [0.3.2] - 2026-05-07
+
+Patch release — BM25 recall fix.
+
+### Fixed
+
+- **BM25 search wrapped query in phrase quotes** (`"foo bar"`) which
+  required the words to appear consecutively. This killed recall on
+  natural multi-word Spanish queries:
+  - `"Astor terapia ocupacional"` did NOT match the document titled
+    `"Informe Terapia Ocupacional — Astor Ferrari"` because the words
+    don't appear in that exact consecutive order.
+
+  Fix: tokenize via `\w+` (Unicode-aware), wrap each token in its own
+  phrase quotes, join with whitespace (FTS5's implicit AND). Now the
+  query is `"Astor" "terapia" "ocupacional"` — matches any doc
+  containing all 3 words anywhere, any order.
+
+### Verified
+
+Same query post-fix:
+- BM25: `Astor — Informe Terapia Ocupacional feb 2026` returns first hit ✓
+- Hybrid (vec+BM25 RRF): same doc in top-3 ✓
+
+Other corpus queries that benefit:
+- `MLX migration` → `obsidian-rag: migración Ollama → MLX` (was missing pre-fix)
+- `obsidian-rag bug fix` → `Bug pattern — sqlite3 'database is locked'` (was missing pre-fix)
+
+## [0.3.1] - 2026-05-07
+
+Patch release — bug fixes for the v0.3.0 ingest pipeline.
+
+### Added
+
+- `memo ingest <vault-path>` CLI command — bulk-ingest .md files from any
+  Obsidian vault into the memo index. Synthesizes ids from path hash so
+  user .md files are not modified. Idempotent. See README "Ambient memory"
+  section for usage.
+- `MEMO_INGEST_MIN_CHARS` env var (default 200) — skip notes shorter than
+  this threshold. Tag-only stubs (`#tagA #tagB` + 1-line question)
+  produce noisy embeddings near the corpus centroid that match generic
+  queries with high false-positive rate. Filtering them improves recall
+  precision on queries with proper nouns.
+
+### Fixed
+
+- **Embedder API misuse** in `recall-hook`, `prewarm`, and `ingest`:
+  `MLXEmbedder.embed()` is batched (signature `Sequence[str] →
+  list[list[float]]`); passing a bare string iterated per-char,
+  producing variable-dim outputs (135, 512, 2465...) instead of 1024.
+  Cascade Metal GPU error after several mismatches. Fix: wrap input
+  in `[composed]` and take `[0]`.
+- **Plugin install path** — bumping from 0.3.0 to 0.3.1 so users on the
+  Claude Code plugin marketplace pick up these fixes via `/plugin update`.
+
+## [0.3.0] - 2026-05-07
+
+**Game-changer release**: memo turns into an *ambient* context layer.
+Memorias auto-inject as `additionalContext` on every Claude Code prompt,
+without the user invoking `/memo` at all.
+
+### Added
+
+- `memo recall-hook` CLI command — Claude Code `UserPromptSubmit` hook that
+  embeds the user prompt via the MLX embedder, runs vec-only search against
+  the memo index, and emits relevant memorias as `additionalContext` markdown
+  on stdout. Sub-1.7s warm latency on a 223-doc corpus, well within the
+  default 5s hook timeout.
+- `memo prewarm` CLI command — `SessionStart` hook that pre-loads the MLX
+  embedder so the first `recall-hook` invocation of the session is fast
+  (warm load: ~500ms vs ~2s cold).
+- `hooks/hooks.json` bundled in the plugin — auto-wires the two hooks above
+  when users install via `/plugin install memo@memo`.
+- 6 env vars to tune ambient memory behaviour:
+  - `MEMO_RECALL_DISABLE` — kill switch (default: enabled).
+  - `MEMO_RECALL_TOP_K` — default 3.
+  - `MEMO_RECALL_MIN_SIM` — cosine similarity floor, default 0.6.
+  - `MEMO_RECALL_MIN_PROMPT_CHARS` — default 12.
+  - `MEMO_RECALL_BODY_CHARS` — snippet length, default 240.
+  - `MEMO_RECALL_SKIP_SLASH` — skip recall on `/` prompts, default 1.
+  - `MEMO_RECALL_DEBUG` — print failure reasons to stderr, default 0.
+
+### Why this is the game changer
+
+Before: user types `/memo save 'X'` to save and `/memo search 'Y'` to recall.
+Friction = adoption blocker; memory only helps when remembered to invoke.
+
+After: memo silently consults the user's past on every prompt and injects
+the most relevant 3 memorias if any score above 0.6 cosine similarity.
+Zero `/memo` invocations needed for the recall side. The agent "knows
+your past" automatically.
+
+### Empirical tuning
+
+Threshold 0.6 was picked after testing the 223-doc corpus:
+- "qué decidí sobre MLX vs Ollama" → 3 hits at 0.71-0.74 (all relevant).
+- "how to bake apple pie" (corpus has zero food memorias) → 0 hits at 0.6
+  (3 noise hits at 0.5-0.6 cut by the floor).
+- "qué hice con whatsapp" → 3 hits at 0.6-0.75 (whatsapp work).
+
+### Privacy / local-first
+
+Hot path is 100% MLX in-process. Embedder = `Qwen3-Embedding-0.6B-4bit-DWQ`,
+search = `sqlite-vec`. Zero network calls, zero cloud APIs, zero telemetry.
+The hook input (your prompt) never leaves the machine.
+
+### Save side (Phase B)
+
+Passive memory extraction (auto-`memo save` from chat transcripts) is NOT
+in 0.3.0 — recall side first to validate the architecture, save side in
+0.4.0 once we have signal on whether the recall hook is helpful in real use.
+
+## [0.2.0] - 2026-05-07
+
+First public release. Distribution name on PyPI is `memo-mcp`
+(`memo` was already taken).
+
+### Added
+
+- Public PyPI distribution as [`memo-mcp`](https://pypi.org/project/memo-mcp/).
+- Claude Code plugin format (`.claude-plugin/plugin.json`) — single-step install
+  via `/plugin install memo@jagoff/memo`.
+- `.mcp.json` bundled in repo root so MCP-aware clients can auto-register.
+- `skills/memo/SKILL.md` bundled in repo — slash-command UX layer for Claude
+  Code CLI users (optional).
+- LICENSE file (MIT).
+- README polish: install, quickstart, architecture diagram, comparison vs
+  `mem-vault` / `mem0` / `engram`.
+- Migration script `scripts/migrate-from-mem-vault.py` (already shipped in
+  0.1.0 development; documented in README for this release).
+
+### Changed
+
+- Bumped Development Status from `3 - Alpha` to `4 - Beta` in pyproject classifiers.
+- Author name expanded from "Fer" to "Fernando Ferrari" for PyPI metadata clarity.
+
+## [0.1.0] - 2026-04-28
+
+Initial development release (private — not on PyPI).
+
+### Added
+
+- MLX-native memory MCP for Apple Silicon. Stack: `mlx-lm` + `mlx`
+  (Qwen2.5-7B/3B-Instruct-4bit + Qwen3-Embedding-0.6B-4bit-DWQ),
+  `sqlite-vec` for vectors, markdown files in Obsidian vault for storage.
+- Tools exposed: `memory_save`, `memory_search`, `memory_list`, `memory_get`,
+  `memory_update`, `memory_delete`, `memory_stats`, `memory_reindex`,
+  `memory_ask` (RAG over memorias with inline citations), `memory_consolidate`
+  (cluster + LLM merge proposals), graph queries (entity extraction).
+- CLI (`memo`) with subcommands matching MCP tools.
+- MCP server entry point (`memo-mcp`) using FastMCP framework.
+- History tracking via SQLite for memory edits + accesses.

mlx_memo-0.5.0/CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What this is
+
+`memo` (PyPI dist name: `mlx-memo` as of 0.5.0; previously `memo-mcp`) is a local MCP memory server for Apple Silicon. Two entry points share the same `Memory` API:
+
+- `memo` — Click-based CLI in `src/memo/cli.py` (~25 commands).
+- `memo-mcp` — FastMCP stdio server in `src/memo/server.py` (~13 tools, all prefixed `memory_`).
+
+The Python module, CLI binary, and GitHub repo are all named `memo`. Only the PyPI distribution is `memo-mcp` (because `memo` 0.2.4 was already taken). Don't conflate the two when grepping or renaming.
+
+## Common commands
+
+```bash
+# Dev install (the project requires Python ≥ 3.13; the Linux/x86 path is gated by pyproject markers)
+uv pip install -e '.[dev]'
+
+# Tests — fast suite (skips slow real-MLX smoke)
+.venv/bin/python -m pytest -q -m "not slow"
+
+# Single test
+.venv/bin/python -m pytest tests/test_memory.py::test_save_then_search -q
+
+# Real-MLX smoke (Apple Silicon only — auto-skips elsewhere via conftest)
+.venv/bin/python -m pytest -q -m requires_mlx
+
+# Lint
+.venv/bin/ruff check src/ tests/
+
+# CLI smoke against the real vault
+memo doctor
+memo stats
+```
+
+CI (`.github/workflows/test.yml`) runs ruff + `pytest -m "not slow"` on Ubuntu — this works because `mlx`/`mlx-lm` deps are gated to `darwin`/`arm64` in `pyproject.toml`, and `tests/conftest.py` auto-skips `requires_mlx` tests when `mlx_lm` isn't importable.
+
+Pytest markers (declared in `pyproject.toml`):
+- `requires_mlx` — loads real MLX models. Auto-skipped without `mlx_lm`. Default run includes them on Apple Silicon.
+- `slow` — anything >1s. Default run excludes via `-m "not slow"`.
+
+## Architecture
+
+Layered, with the `.md` file in the Obsidian vault as the storage of record. Three sqlite files intentionally split (different WAL, independent reset).
+
+```
+CLI / MCP server
+       │
+       ▼
+   memory.py  (Memory: save / search / list / get / update / delete / reindex / consolidate / ask)
+       │
+   ┌───┼─────────────┬──────────────┬──────────────┐
+   ▼   ▼             ▼              ▼              ▼
+embedder.py  store.py        history.py      graph.py     llm.py
+ (MLX        (sqlite-vec     (events DB)     (entities    (MLX two-tier:
+  embed)      memvec.db                       graph.db)    Qwen2.5-7B chat
+                                                            + 3B helper)
+       │
+       ▼
+markdown files in <vault>/99-obsidian/99-AI/memory/  ← source of truth
+```
+
+### Storage of record vs index
+
+The `.md` files are authoritative. `memvec.db` (sqlite-vec) is a rebuildable index. The user can edit memorias directly in Obsidian; on next `memo reindex` (or any tool boot), `body_hash` mismatches drive re-embedding. `rm ~/.local/share/memo/memvec.db && memo reindex` is a safe full rebuild — it never touches the `.md` files.
+
+Three separate sqlite files in `~/.local/share/memo/`:
+- `memvec.db` — `meta` table + `vec0` virtual table (sqlite-vec). Hot-path read.
+- `history.db` — append-only audit of save/update/delete events.
+- `graph.db` — entity index (proper-noun NER over memorias).
+
+Splitting them avoids WAL contention between hot vec reads and batch writes (entity extraction, history). Don't merge them back without good reason.
+
+### MLX in-process — Apple Silicon only
+
+`embedder.py` uses `mlx_lm.load()` to load a Qwen3-Embedding model, bypasses `lm_head`, last-token-pools the hidden states, and L2-normalises. `llm.py` runs Qwen2.5-Instruct in two tiers (7B chat / 3B helper) via `mlx_lm.generate()`. Both lazy-load under `_load_lock`.
+
+Key invariants — don't break these:
+- **Asymmetric retrieval.** Queries get a `Instruct: ...\nQuery: ...` prefix prepended in `embedder.py`; documents go raw. Without the prefix, cosine collapses toward 0. The constant lives in `_QUERY_INSTRUCTION_PREFIX`.
+- **`MLXEmbedder.embed()` is batched.** Signature is `Sequence[str] → list[list[float]]`. Passing a bare string iterates per-character (Python's string-as-iterable), produces variable-dim outputs, and cascades into a Metal GPU error. Always wrap: `embedder.embed([text])[0]`. This was the v0.3.1 bug — don't reintroduce it.
+- **`MEMO_EMBEDDER_DIMS` must match the model.** Asserted at load (1024 for 0.6B, 2560 for 4B, 4096 for 8B). The vec0 schema bakes in `FLOAT[1024]`; swapping models requires `rm memvec.db && memo reindex` — see README "Upgrading the embedder".
+- **`mlx`/`mlx-lm` imports are deferred.** Module-level imports would break Linux CI. Defer until `_ensure_loaded()` (already the convention in `embedder.py` / `llm.py`).
+
+### Search modes
+
+`Memory.search(query, mode=...)` supports three modes (default `hybrid`):
+- `vec` — cosine over sqlite-vec embeddings.
+- `bm25` — FTS5 over title + tags + body. Uses unicode61 + diacritic stripping for Spanish. The query tokenizer wraps each `\w+` token in its own phrase quotes so multi-word queries become AND-of-tokens, not phrase-match — see v0.3.2 changelog. If you touch BM25 tokenization, re-run `tests/test_memory.py` BM25 cases against multi-word Spanish queries (`"Astor terapia ocupacional"`).
+- `hybrid` — Reciprocal Rank Fusion of vec + BM25 (default).
+
+### Ambient memory hooks (`hooks/hooks.json`)
+
+When the plugin is installed, two Claude Code hooks are wired:
+- `SessionStart` (matcher `startup|clear`) → `memo prewarm` (async, 30s timeout). Pre-loads MLX so the first recall is fast.
+- `UserPromptSubmit` → `memo recall-hook` (5s timeout). Embeds the prompt, runs vec-only search, prints the top-3 memorias above `MEMO_RECALL_MIN_SIM` (default 0.6) as `additionalContext` markdown on stdout.
+
+The 5s timeout is tight. Cold MLX load is ~2s. If you add work to the hook, measure end-to-end latency against the 5s budget with `MEMO_RECALL_DEBUG=1`.
+
+## Testing conventions
+
+`tests/conftest.py` enforces two rules — preserve them:
+
+- **Never touch the real vault.** The `tmp_cfg` fixture builds a `Config` with `data_dir`, `vault_path`, and `state_dir` under pytest's `tmp_path`, and pins `MEMO_CONFIG_FILE` so `Config.from_env()` doesn't read the dev's real `~/.config/memo/config.toml`. Any new test must depend on `tmp_cfg` (or build its own isolated `Config`) — never call `Config.from_env()` in a test without controlling these env vars.
+- **CliRunner-based tests must set `MEMO_NONINTERACTIVE=1`** in the `env=` arg, otherwise the CLI's first-run gate may try to fire the picker mid-test. Also override `MEMO_DATA_DIR`/`MEMO_STATE_DIR` to keep state under `tmp_path`. If your test exercises the embedder via the stub (`monkeypatch.setattr("memo.embedder.MLXEmbedder.embed", ...)`), also pin `MEMO_EMBEDDER_DIMS` to match the stub's output dim — the dev's shell may have `MEMO_EMBEDDER_DIMS=2560` (4B model) exported and CliRunner inherits it.
+- **`requires_mlx` is auto-applied.** A test marked `@pytest.mark.requires_mlx` skips automatically when `mlx_lm` can't be imported. Use it for anything that does a real forward pass; everything else should monkeypatch `MLXEmbedder.embed` / `MLXChat.chat`.
+
+`tests/test_smoke_mlx.py` is the canonical example of `requires_mlx` smoke tests.
+
+## Versioning + release
+
+Version lives in three places — bump together:
+- `pyproject.toml` `[project] version`
+- `.claude-plugin/plugin.json` `version`
+- `CHANGELOG.md` (Keep-a-Changelog format)
+
+`src/memo/__init__.py:__version__` is currently pinned at `"0.1.0"` and is not the source of truth — `pyproject.toml` is.
+
+## Conventions specific to this repo
+
+- **The memoria storage location is user-configurable.** The default is `~/Documents/memo/` (a standard macOS path so the tool works for users who don't use Obsidian). On first interactive run, `memo` prompts an arrow-key picker (`memo init` re-runs it). The chosen path is persisted in `~/.config/memo/config.toml` `[storage] data_dir`. Tests must override via `tmp_cfg` (which sets `data_dir`, `vault_path`, `state_dir` and pins `MEMO_CONFIG_FILE` to a test-only path so the developer's real config doesn't leak in). Resolution order in `Config.from_env()`: explicit kwargs → `MEMO_*` env vars → config file → legacy `MEMO_VAULT_PATH` + `MEMO_MEMORY_SUBDIR` → default. `vault_path` is now optional and only used by `memo ingest`.
+- **Frontmatter schema is fixed.** `id`, `title`, `type`, `tags`, `created`, `updated`. `type` is one of `decision | fact | bug | feedback | preference | note | manual`. Adding a new type means updating the Click `Choice` in `cli.py:save`/`update` AND the docstring in `server.py:memory_save`.
+- **Filename slug is `<YYYY-MM-DD>-<slug>.md`.** Mirrors obsidian-rag's conversation writer. The slugifier lives in `memory.py`.
+- **No Ollama anywhere.** `pyproject.toml` does not declare it; `doctor` does not probe `:11434`. The README leans on this as a selling point — don't reintroduce it as a dependency.

mlx_memo-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Ferrari
+
+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.