Shelfmark

shelfmark

Give AI agents the right context, not your entire filesystem.

Shelfmark turns years of scattered documents into a governed context map for AI agents. An agent can discover what exists, understand what kind of material it is, and select the documents relevant to a task — before spending context opening files.

No document migration. No duplicated content store. No need for a perfect folder structure.

uv tool install shelfmark          # or: pipx install shelfmark

*Local by design · metadata only · governed discovery · built for MCP*

Your best knowledge is probably sitting in your folders

Reports, presentations, models, research, proposals and working documents accumulate over years. Some are carefully organised. Others sit inside crowded project folders, old archives, download directories, or collections that made sense only at the time.

The value is still there. The problem is that agents cannot use what they cannot discover — and giving an agent unrestricted filesystem access does not solve that. It transfers the work of finding, interpreting and filtering thousands of files into the context window.

Shelfmark gives the agent a map first.

Context is the scarce resource

An agent does not need every document. It needs to know what exists, what is likely to matter, where it came from, and whether it should be used at all.

Shelfmark is a discovery layer between the agent and your files. The agent searches the catalogue, narrows the field, and requests only the material the task actually needs — so an existing document estate becomes working context without turning the filesystem into one enormous prompt.

A catalogue of pointers, not another document store

Shelfmark builds a local SQLite catalogue of references and derived metadata: paths, filenames, formats, sizes, document types, authors, dates, classifications, selected Office properties, presentation titles, and optional content hashes.

It does not copy your documents into the catalogue. It does not index document body text. It does not create a second repository to govern, synchronise and maintain. Your files stay where they are; the catalogue points at them and describes what can be established from their metadata.

Finding a document does not expose its contents.

Turn messy folders into usable agent context

Shelfmark does not require a designed information architecture. Point it at accumulated project files, forgotten archives, or folders where documents have simply been dropped over the years.

It builds an inventory from signals that already exist — filenames, extensions, paths, authorship, dates, Office properties, and your own classification rules — creating a virtual structure across the material. Agents can then search by document type, client, project, purpose, author, year or location without anything being moved or renamed.

A messy folder can become navigable even when it never becomes tidy.

Shelfmark also stays honest about the limits of metadata. A file called final7.pdf with no useful properties cannot reveal its meaning without someone reading it. Shelfmark reports what is known rather than inventing certainty — the same reason it drops placeholder slide titles instead of listing twelve headings a deck does not have.

Built for selective context

• Discover before opening. Search thousands of references before deciding which few files deserve attention.
• Preserve the context window. Concise catalogue results instead of whole documents that may not be relevant.
• Build on previous work. Reports, models, proposals, research and methods stay discoverable across new tasks and future engagements.
• Keep provenance visible. Path, date, author, document type and surrounding context help an agent judge relevance.
• Reduce blind exploration. Structured search instead of repeatedly walking directories and inspecting files one at a time.
• Separate discovery from access. Shelfmark helps identify material; opening the original remains a separate, controllable decision.

Your roots are the trust boundary

Shelfmark walks only the roots you configure.

Symlinks are not followed. A link inside a root reads as an ordinary file and would otherwise walk straight out of the tree you configured — and hash opens files. Skipped links are reported, never silently dropped. To index another tree, add it as an extra root: the boundary widens by saying so in config, not by planting a link.

The catalogue is refused inside *any* root, because a database that indexes itself grows on every refresh. Both checks compare resolved paths, so .. and a symlinked root cannot slip past them.

Governance belongs in the retrieval layer

Not every useful document should be treated the same way. Shelfmark separates two questions that usually get confused:

• Who owns or may reuse this? → rights: OWN / REFERENCE / RESTRICTED
• May this document leave its current context? → confidential: 0 / 1

A method may belong to you while the client deliverable containing it stays confidential. Modelling the two separately lets agents discover reusable knowledge without treating everything discoverable as freely shareable.

Files matching your private/secret patterns become RESTRICTED: no tool returns their path, name, metadata or content, no argument overrides it, they are never opened for hashing, and the database is opened read-only. corpus_stats() reports a single corpus-wide count of sealed files and nothing else about them — not which root, not which folder. That count is the one thing disclosed, deliberately: silence about it would misrepresent the size of the corpus.

Governance is applied by the catalogue, not left to the wording of a prompt.

Know whether the map can be trusted

A search result is only useful if the agent knows the catalogue is current.

The MCP server keeps its own index current while it runs, so nothing has to be scheduled and no agent has to remember. When it cannot — never built, stale, a failed refresh, a clock it cannot reason from, or an index that no longer agrees with the filesystem — every tool says so above its answer, and corpus_stats() compares index against disk in full.

An old snapshot is never presented as complete knowledge.

Designed for knowledge-intensive work

How it works

1. Point Shelfmark at your existing folders. One or more roots. Files stay where they are.
2. Build the local catalogue. It walks the permitted roots, extracts available metadata, applies classification rules, and writes references into SQLite.
3. Review ownership and confidentiality. shelfmark review asks a few questions about your own folders and writes the answers to config.
4. Connect an MCP-compatible agent. It searches, browses and inspects catalogue records through structured tools.
5. Retrieve only what matters. The agent identifies the relevant artefacts before any separate content access takes place.

Install

uv tool install shelfmark          # or: pipx install shelfmark

from a checkout:

uv tool install /path/to/shelfmark

Python ≥ 3.11. macOS, Linux and Windows — the full suite runs on all three in CI, including the Windows-specific behaviours (OneDrive placeholder detection, junction refusal at the root boundary).

Codex plugin

Install the MCP server and its catalogue-management, context-finding, and archive-research skills as one versioned plugin:

codex plugin marketplace add Dankaro-projects/shelfmark

codex plugin add shelfmark@shelfmark

Then create the local catalogue once with uvx shelfmark init followed by uvx shelfmark refresh. The plugin starts the pinned Shelfmark MCP server over stdio; document paths and metadata stay on the local machine.

To install the three companion skills without the MCP configuration:

pnpm dlx skills add Dankaro-projects/shelfmark --full-depth

Email ingestion is optional, and the extra you want depends on the format you have. .msg resolves to wheels everywhere; .pst needs libpff-python, which publishes no wheels and compiles from C source, so it requires a build toolchain (Visual C++ Build Tools, build-essential, or the Xcode command line tools):

uv tool install "shelfmark[msg]"      # .msg — no compiler needed

uv tool install "shelfmark[pst]" # .pst — compiles from C source uv tool install "shelfmark[email]" # both

Quickstart

Three commands, and init finds your documents for you — when the default root misses, it sweeps for the folders that do hold documents and one keypress fixes the config:

$ shelfmark init

Wrote ~/.config/shelfmark/config.toml

WARNING: ~/Documents does not exist on this machine.

These folders do hold documents:

1. ~/Paperwork (~6 document files)
2. ~/Downloads (~1 document file)

Index which folder? [1] — a number, a path, or 'k' to keep ~/Documents: Root set to ~/Paperwork. Edit ~/.config/shelfmark/config.toml any time.

$ shelfmark refresh cataloguing ~/Paperwork -> ~/.local/share/shelfmark/catalog.db seen 6 new 6 updated 0 unchanged 0 rematerialised 0 evicted 0 corrupt 0 restricted 0

$ claude mcp add shelfmark -s user -- shelfmark-mcp

That's install to connected. The agent's first call then looks like this (a real corpus_stats() answer over the corpus above):

# shelfmark corpus

6 files · 0.0 GB ✓ index fresh — matches disk, last refresh 0 min ago

Roots

root files own+shareable Clients 4 0 Decks 2 0

Rights × confidential

REFERENCE may leave 5 UNKNOWN unreviewed → held 1

doc_type (what files ARE)

report 4, deck 2

Optional but worth the five minutes: shelfmark review asks a few questions about your biggest unclassified subtrees and writes the answers to config, so rights stop being UNKNOWN; shelfmark stats prints the census any time; shelfmark config shows every rights rule in the order it is checked, with the number of files each one currently claims.

Then in a session: corpus_stats() to orient, browse_folder() to navigate, search_docs() / get_file() to find and inspect.

MCP tools

Result lists always say when they are cut (showing 100 of 195 …), unknown filter values a