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) forshelf.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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.