Skip to main content

shelf-spec

shelf-spec — a portable, vendor-neutral memory format for AI agents — plus a thin validator/scaffolder around it.

A shelf is a git repository of human-readable Markdown: categories, an INDEX.md catalog, per-category metadata, an optional journal (ledger.tsv) and policy (POLICY.md). Any MCP client attaches the same shelf; migration between vendors is git clone. The product is the format (spec/SPEC.md); the reference implementation is docshelf-mcp.

Status: v0 (draft, descriptive) — the spec fixes what already works on live shelves. Final name: shelf-spec (decided 2026-07-26, ADR 0007; before the production repo).

What is in this repo

  • spec/SPEC.md — shelf-spec v0 (RFC 2119).
  • spec/shelf.schema.json — JSON Schema (draft 2020-12) for shelf.yml.
  • spec/examples/ — example manifests (memory, document, reserved multi).
  • src/shelf_spec/ — engine (manifest loader, validator, scaffolder, info) with two thin transports: an MCP server and a CLI.
  • docs/advisory-ci.md — drop-in advisory CI stage for shelf repos.
  • docs/shelf-direction-and-channels.md — direction of the shelf family (selection, ownership, provenance; pull vs push) and the outreach channels. In Russian.
  • docs/research/2026-09-30-landscape-recheck.md — landscape re-check before M1 (gate of #45): prior art as of 2026-09-30, deltas to ARCHITECTURE §8 and ADR 0001, go/no-go options. In Russian.

Install

pip install shelf-spec

From a checkout, for development:

pip install -e '.[dev]'

CLI

shelf-spec init [PATH] [--name NAME] [--mode single|multi]
               [--profile memory|document] [--categories a,b,c]
shelf-spec validate [PATH]              # human-readable report
shelf-spec validate --ci [PATH]         # machine JSON on stdout, exit 0/1/2
shelf-spec validate --json [PATH]       # JSON report
shelf-spec validate --manifest MANIFEST.yml [PATH]   # validate a tree against
                                       # an external manifest without touching it
shelf-spec info [PATH]                  # manifest + index summary for a client
shelf-spec serve                        # MCP server on stdio

Exit codes: 0 — shelf conforms (warnings allowed; --strict promotes warnings to failure), 1 — spec violations (error findings), 2 — config-error (manifest missing / unparseable / schema-invalid; checked before any rule).

The default shelf root is $SHELF_SPEC_ROOT, falling back to the current directory.

MCP server

Three tools, same engine as the CLI:

tool type what it does
shelf_init write (local) scaffold a shelf: shelf.yml, docs root and categories, POLICY.md stub, .gitignore; idempotent
shelf_validate read lint a shelf against the spec; report with findings and severities
shelf_info read manifest + index summary for a connecting client

Tools take flat keyword arguments — a hand-written tools/call looks like {"name": "shelf_validate", "arguments": {"shelf_path": "/path/to/shelf"}}, no wrapper object.

Client configuration (stdio):

{
  "mcpServers": {
    "shelf-spec": {
      "command": "shelf-spec",
      "args": ["serve"],
      "env": { "SHELF_SPEC_ROOT": "/path/to/your/shelf" }
    }
  }
}

Validation and info never scaffold a shelf silently: pointing them at a directory without a manifest is a config-error, not an invitation to create one.

Compatibility promise

An existing docshelf/memshelf shelf becomes spec-conformant by adding one file — shelf.yml with mode: single. Nothing is migrated (ADR-0005). .docshelf.json remains a legal implementation detail; shelf.yml is the contract. Ready-to-apply manifests for the shelves named in the roadmap live in docs/adoption/.

License

MIT.

Metadata

Release files for shelf-spec 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for shelf-spec 0.3.0
File Size Uploaded Provenance Actions
shelf_spec-0.3.0.tar.gz 58.3 kB With provenance Details for shelf_spec-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for shelf-spec 0.3.0
File Interpreter ABI Platform Actions
shelf_spec-0.3.0-py3-none-any.whl Python 3 none any Details for shelf_spec-0.3.0-py3-none-any.whl

Total release size: 88.3 kB

Release files / shelf_spec-0.3.0.tar.gz

Download URL shelf_spec-0.3.0.tar.gz
Size 58.3 kB
Tags Source
SHA-256 checksum
How to use checksums
3842c74c92cb29985c4362b21a502afd11aa95ace5ef0f53b04527fefd51498f
BLAKE2b-256 checksum
How to use checksums
67ffdc0f9a9bd22967c7c131edee56d32092be5234375a8de9557b6adf5df68f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Release files / shelf_spec-0.3.0-py3-none-any.whl

Download URL shelf_spec-0.3.0-py3-none-any.whl
Size 30.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
137fc6fa27df7996e17621222b11324cee637f5fb9aaa32b4652ddb66120e453
BLAKE2b-256 checksum
How to use checksums
6abaac57ca6a065afeb6b78707298d112421f742fbb5dd3e3b2cb1d0cbdc2e39
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

Security for shelf-spec 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for shelf_spec-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page