mor

[!WARNING] This is a personal project. I maintain it for my own use and share it because others might find it useful. Feature PRs are unlikely to be merged — if you have an idea, start a discussion first. Fork freely — it's MIT licensed.

AI-accessible knowledge you actually own. Plain markdown files on your disk, searchable by AI via MCP.

Your notes live on your disk as plain markdown with YAML frontmatter — readable without mor, portable to any tool, git-syncable across machines. The MCP server gives AI assistants (Claude Code, Claude Desktop, Cursor, etc.) persistent memory that survives context windows. You also get a CLI and HTTP API.

Install

npm install -g mor

Requires Node.js 20+.

Quick start

# Add notes
echo "Always use snake_case for Python variables" | mor add -t "Python naming"
mor add notes.md -t "Meeting notes" --tags "meeting,project-x"
mor add https://raw.githubusercontent.com/owner/repo/main/config.ts

# Search (FTS5 — tokenized, stemmed)
mor find python naming

# Grep (literal substring or regex)
mor grep snake_case
mor grep -i todo
mor grep -E "async\s+function"
mor grep -w Beer -n -C 2

# Read, edit, copy, remove
mor cat python naming
mor edit python naming
mor cp -o ./out.md python naming
mor rm python naming

# List
mor ls
mor ls -l

Commands

| Command | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------- | | find <query> | Full-text search (--limit, -s threshold, --json) | | grep <pattern> | Substring or regex search (-i, -E regex, -w word, -n line numbers, -l files only, -A/-B/-C context) | | add [file\|url] | Add from file, URL, stdin, or $EDITOR (-t title, -d description, --tags, --type) | | cat <query> | Print content (--raw for frontmatter, --links for cross-references) | | cp <query...> | Copy content to file (-o <dest>) | | edit <query> | Open in $EDITOR (--raw to edit frontmatter) | | update <query> | Update metadata or content (-t title, -d description, --tags, --type, --content-from) | | patch <query> | Apply a str_replace patch to a note's content (--old, --new) | | rm <query> | Remove a note | | links [query] | Show cross-references for a note (--broken to find dangling links) | | ls | List all (--limit, -l long, --tags, --types) | | sync | Pull, commit, and push the notes folder via git | | reindex | Rebuild search index | | import <dir> | Import .md files from a directory | | mcp | Start MCP server (stdio) | | serve | Start HTTP server (-p port, -H host, --token, --mcp) | | login | Authenticate with a remote server via OAuth (-s server URL) |

Queries resolve in order: full UUID, UUID prefix (8+ chars), filename, FTS search. Multi-word queries don't need quoting — options go before the query: mor find --limit 5 python naming.

find, grep, and ls support shared filters: --type, --tag, --repo, --ext (all support glob patterns).

MCP server

Add to your Claude Code or Claude Desktop config:

{
  "mcpServers": {
    "mor": {
      "command": "mor",
      "args": ["mcp"]
    }
  }
}

Tools: notes_search, notes_read, notes_create, notes_update, notes_patch, notes_remove, notes_list, notes_grep.

To make sure Claude Code checks mor first when you ask it to recall something, add this to ~/.claude/CLAUDE.md:

## Notes

When the user asks to recall, find, check, or reuse something they previously saved
or remembered — use the `mor` MCP server tools (`notes_search`, `notes_read`,
`notes_list`). This is the user's primary note store containing code snippets,
files, and reference notes. Always check mor before saying something wasn't found.

Remote access

Run the server on one machine, access from anywhere:

# Server
mor serve --port 7677 --token mypassphrase --mcp

MCP clients (Claude Code, Claude Desktop, etc.)

Point your MCP client at the server URL — no secret in the config:

{
  "mcpServers": {
    "mor": {
      "type": "url",
      "url": "http://mybox.tail1234.ts.net:7677/mcp"
    }
  }
}

The client discovers auth via WWW-Authenticate → OAuth metadata → browser passphrase flow, all automatic.

CLI client

# OAuth login — saves server URL to config and credentials to credentials.json
mor login -s http://mybox.tail1234.ts.net:7677

# All commands now proxy to the remote server
mor find "python naming"

Or configure a direct token instead:

// ~/.config/mor/config.json
{
  "server": {
    "url": "http://mybox.tail1234.ts.net:7677",
    "token": "mypassphrase",
  },
}

OAuth tokens auto-refresh on expiry.

Authentication

When --token is set, all routes require auth. Two methods work everywhere:

• Bearer token: Authorization: Bearer <passphrase> or ?token=<passphrase>
• OAuth access token: obtained via the OAuth flow (mor login or MCP client auto-discovery)

Unauthenticated requests get a 401 with a WWW-Authenticate header pointing to the OAuth discovery endpoint.

HTTP API

| Method | Path | Description | | -------- | --------------------------------------------------------- | -------------------------------------------------------------------- | | GET | /health | Health check | | GET | /notes?limit=N&offset=N | List all | | GET | /notes/search?q=...&limit=N&offset=N | FTS search | | GET | /notes/grep?q=...&limit=N&offset=N&ignoreCase=1&regex=1 | Substring or regex search | | GET | /notes/:query | Read one | | GET | /notes/:query/links | Get forward and backlinks | | POST | /notes | Create ({title, content, description?, tags?, type?, repository?}) | | PUT | /notes/:query | Update ({title?, description?, content?, tags?, type?}) | | POST | /notes/:query/patch | Patch content ({old_str, new_str}) | | DELETE | /notes/:query | Remove | | POST | /reindex | Rebuild the search index | | POST | /sync | Git pull, commit, push | | POST | /mcp | MCP protocol (streamable HTTP) |

Embeddings

Optionally augment FTS search with vector similarity. Configure in config.json:

{
  "embedding": {
    "provider": "openai",
    "model": "text-embedding-3-small",
    "dimensions": 1536
  }
}

Providers: openai (or compatible API via baseUrl), azure-openai, ollama. Run mor reindex after configuring.

Azure OpenAI uses AZURE_OPENAI_API_KEY (or apiKey in config) and requires a deployment name (defaults to model name).

Storage

Notes are markdown files with YAML frontmatter, split across XDG directories. Set MOR_HOME for a single flat directory.

~/.config/mor/                # config
  config.json
~/.local/share/mor/           # data
  notes/
    python-naming-a1b2.md
    meeting-notes-c3d4.md
~/.local/state/mor/           # state
  index.db                    # search index
  credentials.json            # OAuth tokens (mor login)
  oauth.db                    # OAuth server tokens

Files are human-readable and git-friendly. Use mor sync to pull, commit, and push if the notes folder is a git repo. Enable autosync to sync automatically after every add, update, or remove:

{
  "autosync": true
}

License

MIT