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.
Release files for agents-docs 0.44.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agents_docs-0.44.1.tar.gz | 73.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agents_docs-0.44.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 151.5 kB
Release files / agents_docs-0.44.1.tar.gz
| Download URL | agents_docs-0.44.1.tar.gz |
|---|---|
| Size | 73.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5acba3e5f6ae04f81dae0b1d81f331c2f5d7fb70729839b79858c2e359ceb6b7
|
|
BLAKE2b-256 checksum How to use checksums |
1c9515416b9fae51c13d1cdc0b4865cd74d219701022d3e90a2048a6b4a1a16c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
Release files / agents_docs-0.44.1-py3-none-any.whl
| Download URL | agents_docs-0.44.1-py3-none-any.whl |
|---|---|
| Size | 78.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
349fe485c0e4b4c59610d2a5427b8c0103cd88f57234886e6ec5569549dbd567
|
|
BLAKE2b-256 checksum How to use checksums |
a04e076b094281152af0912a21f5fa2c954d75b6ac6be7f0c7d8c6dae0669443
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.6
|
