.agents / docs
Local markdown docsets with header-aware BM25 search.
Hard tech facts on disk. Shared across every agent that can speak MCP.
Quickstart
pip install agents-docs && agents-docs init
Creates ~/.agents/docs/ (category dirs only), copies skills, and merges MCP into host configs whose directories already exist. Docsets are not seeded. Fetch one with agents-docs sync <name>.
Source checkouts can also be installed and managed with vand.
What it does
Markdown on disk is the store (~/.agents/docs/, override AGENTS_DOCS_PATH). Search is header-aware BM25 in-process. No vector database, no embeddings.
| Layer | Where | What lives there |
|---|---|---|
| Fact sheets | stacks/ models/ apis/ platforms/ custom/ |
Append-mostly notes agents file with write_doc |
| Docsets | one folder per catalog name or ingest | Fetched llms.txt / markdown, or a local folder |
Search. search_docs ranks sections, not whole files. A named catalog docset is fetched when missing and refreshed when stale (7 days, ai-models 1 day).
Catalog sync does not rewrite fact sheets. sync / prune leave stacks|models|apis|platforms|custom alone.
Memory is a different store. User prefs, project decisions, and identity go to agents-memory. Do not dump READMEs or chat logs here. delete_doc is for a wrong, duplicate, or yanked sheet — not because a model is old.
Where it runs
Floor: any MCP client or a terminal. python -m agents_docs serve is enough.
init autowires hosts it finds. It does not install an IDE.
| Layer | What you get | Who |
|---|---|---|
| Vault + MCP/CLI | Full tools, or the CLI mirrors below | Any MCP host / any shell |
| Autowire on init | Merge agents-docs into the host MCP file when that config directory already exists; copy docs-search and docs-sync |
Cursor, Claude Desktop, Zed (context_servers), Antigravity / Gemini, Windsurf, Codex, Roo, Cline. Skills land in ~/.agents/skills, ~/.cursor/skills, ~/.gemini/config/skills |
MCP without autowire: point the host at python -m agents_docs serve.
MCP tools
Primary surface. Agents file and search facts here.
| Tool | What it does |
|---|---|
search_docs |
Header-aware BM25. category is all, a fact category, or a docset name |
get_doc |
Raw markdown of one sheet |
write_doc |
Append a dated section. overwrite=true replaces a wrong sheet |
delete_doc |
Drop a wrong, duplicate, or yanked sheet. No CLI mirror |
list_docs |
Fact sheets with category and size |
list_catalog |
The 21 names sync can fetch with no URL |
sync_external_doc |
Fetch a catalog name or a custom llms.txt / markdown URL |
get_model_playbook |
Model playbook text (model, default auto) |
Eight tools. Full contract: abi/MCP.md.
CLI
Ops / install / batch. Vault writes mirror MCP. Machine-readable catalog: python -m agents_docs --help-json (do not scrape --help).
| Command | Purpose |
|---|---|
agents-docs init |
Categories, skills, MCP merge. No docset download |
agents-docs catalog |
List the 21 catalog names |
agents-docs sync <name> [--url URL] |
Fetch a catalog item or a custom URL |
agents-docs ingest <name> <path> |
Copy a local markdown folder into the store |
agents-docs search "<query>" [--docset NAME] [--top N] |
BM25. CLI flag is --docset (MCP calls it category) |
agents-docs list |
Installed docsets with file and byte counts |
agents-docs write NAME CONTENT [CATEGORY] |
Append a fact. Alias: add. --overwrite replaces |
agents-docs playbook [model] |
Same text as get_model_playbook |
agents-docs prune |
Strip boilerplate in installed docsets |
agents-docs serve |
stdio MCP. Also the default when you pass no command |
agents-docs skills / sync-mcp |
Re-copy skills, or re-merge MCP, without the rest of init |
ABI
Layout and contracts in abi/:
WHY.md— markdown + BM25 instead of a vector databaseLAYOUT.md—~/.agents/docs/taxonomyMCP.md— tool surfaceCLI.md— commandsCATALOG.md— catalog schemaLLMSTXT.md—llms.txtfetch
Tests
python tests/run_all_tests.py
License
MIT. See LICENSE.
Metadata
Release files for agents-docs 0.45.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 |
|---|---|---|---|---|
| agents_docs-0.45.0.tar.gz | 75.0 kB | Without provenance | Details for agents_docs-0.45.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agents_docs-0.45.0-py3-none-any.whl | Python 3 | none | any | Details for agents_docs-0.45.0-py3-none-any.whl |
Total release size: 154.2 kB
Release files / agents_docs-0.45.0.tar.gz
| Download URL | agents_docs-0.45.0.tar.gz |
|---|---|
| Size | 75.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5ff6f8cff661b84de981e1a2396fae203159072ad456799bee39b8b31c59201f
|
|
BLAKE2b-256 checksum How to use checksums |
ce0a44785a952deb28b1ce2ff726cdcf8d9f6ae3aaa4278126ccbf3ba0c9878a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / agents_docs-0.45.0-py3-none-any.whl
| Download URL | agents_docs-0.45.0-py3-none-any.whl |
|---|---|
| Size | 79.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7a64f0e9fe0e32233865e023e27e01eb076102cd2aca71e29606b38ca46e6624
|
|
BLAKE2b-256 checksum How to use checksums |
dcbf0b955a947eeda6ebf76b8a55bd9f54aac6ceb995cb642882bd549eaafbbe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.5 {"installer":{"name":"uv","version":"0.12.5","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for agents-docs 0.45.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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
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.