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.

Related MCP server: Vault MCP Server

Documentation

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.

Specs

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.