Moneta Notes (mnotes)

A personal notes system built around an Obsidian vault, providing fast full-text and semantic search plus safe, structured note read/write access for Claude via MCP.

Three components, one shared core library:

1. Indexing Subsystem — a background daemon that keeps a SQLite index (FTS5 + sqlite-vec) in sync with the vault on disk.
2. CLI Tools — terminal commands for manual/debug search and note access, used directly and from NeoVim.
3. MCP Server — exposes search, read, and write capabilities to Claude Code / Claude Desktop.

The CLI and MCP server are thin wrappers around one shared core library. Neither implements search, hashing, or file I/O logic itself — that guarantees the two surfaces can never drift out of sync.

Runs on macOS only (Apple Silicon), on either a personal or work machine, never both at once. Each machine gets its own vault, its own index, and its own config.

This file is a maintainer-facing overview — architecture, tech stack, dev conventions. Detailed, binding functional specs live in docs/specs/ and are the actual source of truth for what this project does; if anything here conflicts with a spec, the spec wins.

---

Name

Moneta was an epithet of the Roman goddess Juno — Juno Moneta, "Juno who warns/reminds," from the Latin verb monere (to remind, to warn, to advise). Her temple on the Capitoline Hill also housed Rome's mint, which is why moneta is the root of "money" and "mint" in English and the Romance languages. The reminding/advising sense is the one that gave this project its name.

---

Documentation

Guide	Covers
Installation	Prerequisites, running scripts/install.sh, what it creates, verifying the install
Configuration	Every config.toml option: what it does, its default
Usage	The full mnotes CLI command reference plus the MCP tool surface
Process Management	Starting/stopping/restarting the indexing daemon, log locations, troubleshooting
Uninstallation	Running scripts/uninstall.sh, what it removes, what it leaves alone

---

Prerequisites

Runs on macOS only (Apple Silicon). Required: Node.js, pnpm. Strongly recommended: ripgrep, fswatch, Xcode Command Line Tools. Optional: the Claude Code CLI, for automatic MCP registration. See Installation for what each is for and what happens if it's missing.

---

License & Contributing

Licensed under Apache-2.0. Contributions are welcome — see CONTRIBUTING.md for signed-commit and DCO sign-off requirements, and Architecture § Development for running tests/lint and what the Husky hooks enforce.

---

Specs

Spec	Covers
S001 — Data Model	SQLite schema: notes, FTS5, chunks/vectors, tags, links, index queue, migrations
S002 — Search	Fulltext/semantic/hybrid ranking, RRF merge, chunk collapse
S003 — Notes	Note CRUD, hashing, frontmatter/metadata, the id field, rename (incl. link cascade), backlinks
S004 — Grep & Tags	Ripgrep wrapper, tag extraction and listing
S005 — Indexing Daemon	fswatch loop, embedding pipeline, queue/retry, daemon↔CLI IPC
S006 — CLI	mnotes command surface and output formats
S007 — MCP Server	Tool schemas, transport, error mapping
S008 — Logging	Logger, rotation, audit trail
S009 — Config & Install	config.toml schema, install/uninstall, launchd
S010 — Shared Utilities	Title↔path conversion, line counting, code-region stripping
S011 — Links	Wikilink extraction, backlinks, rename link-cascade, broken-link detection

Specs are numbered (S001, S002, ...) and named with a short kebab-case topic. A spec may amend an earlier one (noted at the top of the file) as later design work surfaces a gap — e.g. S004 amends S001's tags table collation, S005 amends S001 with the index_queue table.

Not yet speced: MCP prompts (weekly review automation, note triage, stale/orphan note detection, weekly note scaffolding — candidates named below, design deferred to a future spec once the core tool set is built and in use).

---

Architecture

Three components share one core/ library — cli/ and mcp/ are thin wrappers that do their own argument parsing / protocol plumbing and then call the same functions underneath, so the two surfaces can never drift out of sync. Plain JS, no build step.

See Architecture for the full directory layout and tech stack table.

---

Note Versioning

Version-controlling the notes vault (as distinct from this code repository) is out of scope for mnotes itself, but strongly recommended — note_write/note_edit's write-safety guards are preventive, not a substitute for being able to recover a prior version of a note. See Note Versioning for a recommended, low-effort setup.

Status

Fully speced (see docs/specs/): data model, search, notes, grep/tags, indexing daemon, CLI, MCP server, logging, config & install.

Not yet speced: MCP prompts (weekly review automation, note triage, stale note detection, weekly note scaffolding, orphan note identification) — candidates identified, design deferred until the core tool set above is built and in use.

Not yet implemented: everything — specs are complete, implementation hasn't started.