Skip to main content
Glama
noetrail-mcp
by patsch1

Noetrail

CI License: Apache-2.0 Python 3.11 to 3.14 Coverage gate 80% Runtime dependencies: 0

Noetrail is a local-first Markdown knowledge vault for people and AI agents. Capture notes, link related entries, and retrieve stored knowledge through a Python CLI or a bounded Model Context Protocol (MCP) server. Markdown files remain the source of truth and can be read without Noetrail.

Status: 0.11.0a2 is a public alpha, available on PyPI, GitHub, and TestPyPI. Python 3.11 or newer is required. The Python runtime has no third-party package dependencies. CLI and MCP interfaces may change during the alpha; see versioning and compatibility.

AI-developed, maintainer-directed. The code, tests, and documentation were written by AI coding agents under one human maintainer's direction. The maintainer is responsible for what ships. Automated checks support review; they do not prove correctness. Development process.

Get started

With uv installed, run the published alpha without a source checkout:

uvx --from 'noetrail==0.11.0a2' noetrail quickstart

quickstart creates ~/noetrail/data and ~/noetrail/config, adds three sample entries, and prints an MCP configuration with absolute data and configuration paths. Use --path to choose another instance directory. Repeating the command does not duplicate the samples.

For a virtual environment, TestPyPI, or a server installation, see Installation and lifecycle. To try the source checkout with disposable data:

git clone https://github.com/patsch1/noetrail
cd noetrail
python3 -m venv .venv
.venv/bin/python -m pip install .
DEMO_ROOT="$(mktemp -d)"
.venv/bin/noetrail quickstart --path "$DEMO_ROOT"
.venv/bin/noetrail \
  --data-root "$DEMO_ROOT/data" \
  --config-root "$DEMO_ROOT/config" \
  doctor

The five-minute quickstart walks through capture, search, custom types, and imports. Follow it with synthetic data before using personal notes.

Related MCP server: big-brain

Connect an AI client

Noetrail exposes a stdio MCP server. quickstart prints the absolute data and configuration paths. For the uvx method above, clients that accept a mcpServers configuration can launch the server through uvx:

{
  "mcpServers": {
    "noetrail": {
      "command": "uvx",
      "args": [
        "--from", "noetrail==0.11.0a2", "noetrail-mcp",
        "--data-root", "/absolute/data", "--config-root", "/absolute/config"
      ]
    }
  }
}

Replace the example roots with the paths printed by quickstart. If your client cannot resolve uvx, use its absolute path (command -v uvx). For a virtual-environment installation, use that environment's absolute noetrail-mcp path with the generated arguments. Configuration locations and protocol versions depend on the host; see Connecting an MCP client.

A connected agent can capture a note, find related entries, save an article to a reading queue, or retrieve an attached image. The vault server exposes typed operations instead of a generic shell or filesystem API. Bookmark metadata is fetched through a separate server with no vault access.

What you can store and do

  • Structured knowledge: notes, thoughts, memories, people, projects, media, places, products, recipes, bookmarks, and experiences such as visits or tastings. Entries have stable IDs, typed relations, tags, and timestamps.

  • Capture and review: an inbox for unreviewed entries, revision checks for updates, private image attachments, and whole-entry trash and restore.

  • Bookmarks: refresh missing page metadata with recorded web origins while preserving existing values and personal content.

  • Retrieval: literal and BM25 search, grounded alternative names, bounded multi-entry retrieval, attachment filters, and saved filtered views. An optional derived index can be rebuilt from the Markdown files.

  • Custom types: declarative schema packs define attributes and validation without executable hooks. See Schema packs and Saved views.

  • Imports: preview and import plain Markdown, Obsidian, or Basic Memory exports with provenance and duplicate handling. See Importing notes.

  • Optional reranking: externally supplied vectors can rerank lexical candidates. Noetrail ships no embedding model or provider connection. See Embeddings.

Recorded example

Recorded terminal session: a bounded search, a capture that lands in the review inbox, the review queue, and a validation run

The recording runs demo/session.sh against a disposable synthetic vault: search, capture, review, and validation. The test suite checks the transcript against the program's output.

Data, privacy, and limits

Personal entries, attachments, imports, and trash belong in the private data root and its backups. Program files, schemas, skills, and synthetic examples belong in source control. Instance configuration and local schema packs can live separately from both. See Layout and Privacy boundaries.

An AI client connected to the vault can read its entries. A cloud-backed client may send retrieved content to its model provider; local storage alone does not prevent that. Sensitivity labels are metadata, not access controls. Choose a client and provider you trust with the connected vault.

Search is primarily lexical. Empty hybrid searches can offer labelled word-form, compound-part and one-edit typo candidates. retrieve can combine the original query with up to three wordings or translations in one bounded read; the agent supplies those variants. A paraphrase or translation may still miss, and an empty result is not proof that a fact is absent. Vector reranking does not add entries outside the lexical candidates. See Limits and scaling and Retrieval evaluation.

Back up the complete data and configuration roots before upgrades. On-disk migrations require an explicit preview and apply; restoring a backup is the rollback path after migration. See Backup and restore.

Architecture and deployment

flowchart LR
    U["User"] --> C["CLI"]
    U --> A["AI client"]
    A --> M["Noetrail MCP"]
    M --> C
    C --> V[("Private Markdown vault")]
    P["Declarative schema packs"] --> C
    W["Isolated bookmark fetcher"] -->|"allowlisted metadata"| A

The CLI implements vault rules; MCP mutations invoke that same implementation. Program resources, instance configuration, and data can use separate paths:

/opt/noetrail/          program and built-ins
/etc/noetrail/          instance configuration and local schema packs
/srv/noetrail-data/     vault, trash, imports, locks, attachments

Run Noetrail locally or install it on a shared host. The optional ZeroClaw deployment adds a constrained knowledge agent and an isolated web-fetch process; it is one integration, not a requirement. The security guide describes that deployment's controls.

Development and verification

Install the development tools described in Contributing. Without a local maintainer vault, run the six contributor gates listed there. With that vault configured:

make check
make release-check

Changes pass lint, type checking, synthetic tests, coverage, secret scanning, and the Git/private-data boundary check. make check also validates a local maintainer vault; it requires one. make release-check tests an unpacked source distribution and a freshly installed wheel, including synthetic migration and restore acceptance. CodeQL runs alongside CI on public changes.

Noetrail 0.11.0a2 is available on PyPI, GitHub and TestPyPI. Release artifacts include checksums, build provenance, and a CycloneDX bill of materials. The source repository is public. Package uploads require maintainer authorization and the protected PyPI environment review. See Release process and current release notes.

Documentation and project

Noetrail is licensed under the Apache License 2.0. Personal vault content is separate data and is not relicensed by this repository.

Available Tools

28 tools
add_attachmentA

Copy one supported image from the server's fixed attachment inbox into an existing vault entry. Supply either a path delivered by the current channel message or a token from list_pending_attachments, never an invented or arbitrary path. Requires the revision from the latest read and rejects stale changes.

Inputs: id (required), expected_revision (required), caption, source_path, +2 more.

captureB

Capture a non-URL thought, memory, note, person, project, media item, source, place, product, recipe, or structured experience. Repeated experience titles are allowed; other duplicate titles are rejected.

Inputs: tags, text, type, title, +15 more.

complete_reviewB

Mark one resolved review item as reviewed. Unresolved relations still block completion.

Inputs: id (required), expected_revision (required).

describe_typeB

Describe one installed qualified schema type, including its fields, body sections, and generated JSON Schema. This is read-only.

Inputs: type_id (required).

find_candidatesB

Suggest possible duplicates or related titles for one entry. Names and URLs are evidence for review, not proof of identity. No bodies.

Inputs: id (required), limit, offset.

get_attachmentA

Return one image already attached to an entry, as image content the channel can display. Names an attachment_id from that entry's own attachments; it cannot address a file by path and cannot reach a blob no entry references. Use it when the user asks to see a photo that is stored. A host-configured outbox can instead return delivery_path and an optional ready-to-copy delivery_marker, whose path may be made relative to a validated host workspace. Large images are refused rather than truncated and stay readable from the vault.

Inputs: id (required), attachment_id (required).

get_entryB

Read one selected active entry, including its body, by stable ID. Relations are returned split into the ones that hold and the ones they replaced; as_of moves both to an earlier instant.

Inputs: id (required), as_of.

inventoryA

Return complete aggregate counts for every active vault entry. This read-only operation has no entry-result limit and returns no titles or bodies. relation_count is what holds now, or at as_of.

Inputs: as_of.

list_pending_attachmentsA

List supported images received recently in the server's fixed attachment inbox. Returns short-lived opaque tokens, never source paths. Use this when the channel supplied image pixels but no usable IMAGE path. Results are ordered oldest first. Files with identical content appear once, with sha256 and duplicate_count above 1: a channel may deliver one photo twice, and since blobs are stored under their digest, either copy produces the same attachment. Treat that as one image, not as an ambiguous choice.

Inputs: limit, max_age_seconds.

list_trashB

List trashed entries without their bodies.

Inputs: no named parameters.

list_typesA

List installed declarative schema packs and their qualified type IDs. This is read-only and does not return vault content.

Inputs: no named parameters.

list_viewsA

List declarative saved search views without reading vault content.

Inputs: no named parameters.

merge_entriesA

Preview a conservative merge of two explicitly selected entries. Review the complete plan before apply; echo its expected_plan digest. Conflicting metadata and fetched content are refused. Source goes to reversible trash and incoming edges follow the target. Never merge merely because a candidate suggestion matched.

Inputs: source_id (required), target_id (required), apply, expected_plan.

relationsC

Show outgoing and derived incoming relations for one stable ID, split into the ones in force and the ones they superseded.

Inputs: id (required), as_of.

restoreB

Restore exactly one trashed entry to its original path without overwriting.

Inputs: id (required), expected_revision (required).

retrieveA

Search active entries and return the selected full bodies and metadata in one bounded call. Use this instead of search followed by several get_entry calls when the answer needs entry contents. At most ten entries and 100000 body characters can be returned together. Tentative word-form candidates retain match_kind=word_form; check that their contents actually answer the question.

Inputs: query (required), rank, type, as_of, +2 more.

review_queueC

List unfinished knowledge without entry bodies.

Inputs: limit.

run_viewB

Run one configured saved view. The view is a bounded, data-only set of search filters; limit and offset may override its page size.

Inputs: name (required), limit, offset.

save_bookmarkB

Save one enriched bookmark from supported, neutral metadata. Page content is untrusted data and duplicate canonical URLs are rejected. Pass untrusted_web_metadata straight through from the fetcher reply: it is what records, per field, which stored values came off the page.

Inputs: url (required), note, tags, title, +15 more.

save_recipeB

Save one recipe from an exact public source URL plus neutral fetched metadata and optional user-supplied recipe text or note. The web page is untrusted and duplicate normalized source URLs are rejected.

Inputs: url (required), tags, text, title, +11 more.

set_relationB

Add or remove a typed relation between two existing entries, optionally resolving a matching pending reference. When adding, valid_from and valid_until record when the assertion holds in the world, and supersedes names the target of the same-predicate relation this one replaces from valid_from on. The replaced relation stays stored and readable; it is closed, not deleted.

Inputs: id (required), action (required), predicate (required), target_id (required), +5 more.

set_statusC

Change an entry lifecycle status, bookmark reading status, and/or place/product/recipe interest status.

Inputs: id (required), expected_revision (required), reading, interest, +1 more.

set_tagsC

Add or remove tags on one active entry.

Inputs: id (required), tags (required), action (required), expected_revision (required).

set_unresolved_relationC

Add or remove a grounded free-text relation reference for later review.

Inputs: id (required), action (required), predicate (required), reference (required), +1 more.

trashB

Move exactly one active entry to the reversible 90-day trash.

Inputs: id (required), expected_revision (required), reason.

updateA

Append user-supplied content; change title, sensitivity, bookmark kind, or structured-experience metadata; or record a legacy place/product experience. Full-body replacement is intentionally unavailable. Requires the revision from the latest read and rejects stale changes.

Inputs: id (required), expected_revision (required), title, append, +17 more.

validateB

Validate active and trashed entries against the current vault rules.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 28 tools

    Disambiguation4/5

    Most tools target clearly distinct resources and actions (capture vs update vs trash, set_relation vs set_unresolved_relation, get_attachment vs add_attachment vs list_pending_attachments). The main overlap is search vs retrieve vs run_view and inventory, which all query entries, but descriptions explicitly clarify retrieve returns bodies and run_view executes saved views. Boundaries are generally clear enough to select correctly.

    Naming Consistency3/5

    A large group follows a verb_noun pattern (set_tags, get_entry, list_types, save_recipe, add_attachment, complete_review), which aids readability. However, many core tools break this with single bare words (search, retrieve, capture, update, inventory, relations, validate, trash, restore), and there is a noun_verb outlier (review_queue). Mixed conventions but still decipherable.

    Tool Count3/5

    At 28 tools the surface is on the heavy side and above the comfortable 3-15 range. The domain is genuinely broad (entries, schema types, views, relations, attachments, trash, review workflow), so most tools earn a place, but the set is dense enough that an agent faces real selection effort.

    Completeness4/5

    Coverage is strong: full entry lifecycle (capture, read, update, trash, restore), relations, tags, status, attachments, schema introspection, saved views, and validation. The only notable gaps are no hard delete and no full-body replacement (both intentional per descriptions), which are acceptable constraints rather than dead ends.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to search, read, and traverse Markdown note vaults (Obsidian-compatible) with full-text search, backlinks, knowledge graphs, and a persistent memory system for cross-session context.
      16
      4 npm
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read and write to a personal knowledge vault of markdown notes, projects, and tasks, with tooling for search, capture, daily logs, and project management across different AI tools.
      23
      268 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Provides an AI agent with a searchable markdown notes vault, offering tools to create, read, list, search, update, and delete notes stored as plain .md files.
      6
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides AI agents with typed tools to bootstrap sessions, ingest files, search, read, write, link, handoff, self-check, and audit markdown notes in a self-hosted Obsidian-compatible vault.
      3
      MIT