{
  "markdown": "# LoreDocs v0.1.25\n\nYour AI project's knowledge base. Organized, searchable, version-tracked.\n\nLoreDocs gives Claude persistent access to your project documentation -- specs, guides, architecture decisions, reference docs -- so it never loses context between sessions. Works with Claude Code, Cowork, Cursor, OpenAI Codex, and Hermes Agent.\n\n> Install directly from Claude Code's plugin marketplace, or via PyPI: `uvx loredocs`\n\n## Quick Start\n\n**Prerequisites:** [uv](https://docs.astral.sh/uv/getting-started/installation/) (fast Python package manager).\n\n```bash\n# Install uv (one time)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Clone and install\ncd /path/to/loredocs\nuv sync\n```\n\nFor detailed installation instructions, see [INSTALL.md](INSTALL.md).\n\n**Using the Claude Agent SDK directly?** `git clone` the public repo and point the SDK's local-directory plugin loader at it -- the repo root is a self-contained plugin directory (`.claude-plugin/plugin.json` + `.mcp.json`). No separate SDK-installable bundle exists or is needed.\n\n## Using LoreDocs\n\n### Claude Code (Terminal)\n\n```bash\nclaude --plugin-dir /path/to/loredocs\n```\n\nOr inside an existing session:\n\n```\n/plugin add /path/to/loredocs\n```\n\nOnce loaded, Claude has access to all 48 LoreDocs MCP tools automatically. Ask Claude to \"create a vault for this project\" or \"find the architecture doc\" and it uses the tools on its own.\n\n### Cowork (Desktop App)\n\n1. Click **+** next to the prompt box\n2. Select **Plugins** > **Add plugin**\n3. Browse to the `loredocs` source folder\n\n**Shared Database Access:** Cowork runs in a sandboxed VM. To access docs saved from Claude Code, ask Claude:\n\n> \"Mount my ~/.loredocs folder\"\n\n## How It Works\n\nLoreDocs organizes knowledge into **vaults** -- named containers for related documents. Each vault can hold specs, guides, decisions, checklists, or any text you want Claude to remember.\n\n```\n~/.loredocs/loredocs.db          <-- SQLite database (metadata, search index)\n~/.loredocs/vaults/<vault-id>/   <-- Document files on disk\n```\n\n**Key concepts:**\n\n- **Vaults** group related docs by project or topic\n- **Documents** are text files with metadata (tags, categories, priority, notes)\n- **Version history** tracks every change to every document\n- **Full-text search** via SQLite FTS5 finds anything instantly\n- **Injection** loads vault content into Claude's context on demand\n\n## Your Data is Always Available\n\nLoreDocs works through MCP tools when they are available and falls back to bundled scripts automatically when they are not. Your vault documents are safe regardless of MCP status -- the same add, search, and retrieve operations work either way. You do not need to configure anything; the plugin skill handles the switch silently.\n\n## Verify Installation\n\nAfter installing, verify LoreDocs is working by asking Claude:\n\n> \"Run `vault_list` and show me the results.\"\n\nIf you see a list of vaults (or an empty list if this is your first time), LoreDocs is connected. If you get an error about missing tools, re-run `uv sync` and reload the plugin.\n\n## Recommended CLAUDE.md Setup\n\nFor the best experience, add the following snippet to your `~/.claude/CLAUDE.md` (global) or your project's `CLAUDE.md`. This tells Claude how to use LoreDocs consistently across sessions.\n\n```markdown\n## LoreDocs (persistent project knowledge)\n\nAt session start:\n1. Call `vault_list` to see available knowledge vaults.\n2. Call `vault_inject_summary` for any vaults relevant to the current project.\n3. Use this context to understand project architecture, decisions, and reference docs.\n\nDuring the session:\n- If you create significant documentation, add it to LoreDocs with `vault_add_doc`.\n- Tag documents for easy cross-vault discovery with `vault_tag_doc`.\n\nAt session end:\n- If new docs were created or updated, ensure they are stored in LoreDocs for future sessions.\n```\n\n**For Cowork users:** Cowork does not run hooks automatically. Add instructions to call `vault_list` and `vault_inject_summary` at session start in your project CLAUDE.md.\n\n## Canonical Project Knowledge\n\nIn multi-agent environments, different tools and agents often create improvised mirrors\nof shared skill or configuration content -- playbooks, style guides, shared reference\ndocs. Those mirrors drift. One agent updates the source; the other keeps reading the\nstale copy. Two agents in the same project end up operating from divergent knowledge\nwith no visible signal that anything is wrong.\n\nLoreDocs prevents this by making the vault the single canonical source that every agent\nreads. Instead of each agent loading a local file copy, every agent calls\n`vault_inject_by_tag` at session start and gets the same vault-managed version.\n\n### Recommended pattern\n\nStore shared content (playbooks, team guidelines, shared specs) as vault documents\nrather than as local files that agents copy or mirror.\n\nAgents load the content at session start:\n\n```\nvault_inject_by_tag: team-playbook\n```\n\nAll agents -- regardless of surface (Claude Code, Cowork, CLI, or any future AI tool)\n-- call the same vault and receive the same current version. Updating the content\nrequires editing the vault document once; all agents pick up the change on their next\nsession start.\n\nLocal files (`.claude/skills/`, `.agents/`, or any surface-specific config) become\npointers or bootstrap stubs only -- not the authoritative content. The vault is the\nsource of truth.\n\n### Example: sharing a playbook across an agent team\n\n```python\n# Session start for any agent on the team:\n# 1. Inject the shared playbook by tag\nvault_inject_by_tag(\"team-playbook\")\n\n# 2. Inject any project-specific reference docs\nvault_inject_by_tag(\"project-architecture\")\n\n# Working context is now current -- no local file copies needed.\n```\n\nTo store the shared content in the vault (one time, or on each update):\n\n```python\n# Store (or update) the shared playbook:\nvault_update_doc(vault=\"team-knowledge\", doc_id=\"playbook-id\", content=open(\"PLAYBOOK.md\").read())\n\n# Or add it fresh (path= reads directly from disk -- no need to load into context):\nvault_add_doc(vault=\"team-knowledge\", name=\"Team Playbook\", path=\"/absolute/path/to/PLAYBOOK.md\", tags=[\"team-playbook\"])\n```\n\nAny agent that calls `vault_inject_by_tag(\"team-playbook\")` reads the same document.\nNo copies, no mirrors, no drift.\n\n## Plans: Free vs Pro\n\nLoreDocs is local-first and free to use. Pro ($9/mo) removes the storage limits and\nunlocks semantic (meaning-based) retrieval. Everything runs on your machine on either\nplan -- Pro does not add any cloud component.\n\n| | Free | Pro ($9/mo) |\n|---|---|---|\n| Vaults | 3 | Unlimited |\n| Documents per vault | 50 | Unlimited |\n| Storage | 500 MB | Unlimited |\n| Version history per document | 5 versions | Unlimited |\n| Full-text search (FTS5) | Yes | Yes |\n| Core MCP tools (create, search, version, tag, inject, import/export) | Yes | Yes |\n| Local-first, no cloud, no telemetry | Yes | Yes |\n| Semantic search (`vault_search semantic=true`, `vault_rebuild_index`) | -- | Yes |\n| Embedding-based document relationships (`vault_find_related`) | Keyword co-occurrence only | Keyword + embedding auto-links |\n| Cross-product session linking (`vault_link_session` + 2 more) | -- | Yes (also requires LoreConvo Pro) |\n\n[Upgrade to Pro -- $9/month](https://buy.stripe.com/00w3cndEw0l5b8fek17N601)\n\nAfter checkout, your license key is emailed to the address you used at checkout, usually within one business day. Questions: info@labyrinthanalyticsconsulting.com.\n\nFree tier limits are enforced before writes; Pro removes them. Check your current tier\nand usage anytime with `vault_tier_status`. Activate a Pro license with `vault_set_tier`.\n\n> The Pro semantic features use a local embedding model (BGE-small-en-v1.5) and the\n> LanceDB index -- still no data leaves your machine.\n\n## Features\n\n- **Vault organization**: Group docs by project with linked project metadata\n- **Document versioning**: Full history with rollback to any prior version\n- **Tagging and categorization**: Tag docs for cross-vault discovery\n- **Priority levels**: Mark docs as critical, high, normal, or low priority\n- **Full-text search**: Fast keyword search across all vaults and documents\n- **Context injection**: Load specific docs, tags, or vault summaries into Claude's context\n- **Bulk operations**: Import directories, bulk-tag, export manifests\n- **Document linking**: Connect related docs across vaults\n- **Embedding-based document relationships (Pro)**: `vault_find_related` returns both keyword co-occurrence and embedding-based auto-links for Pro users. Uses BGE-small-en-v1.5, cosine >= 0.75, same-vault scoped. Embedding links are archived if you downgrade from Pro to Free.\n- **Cross-product session linking (Pro)**: Automatically links vault documents to the most relevant LoreConvo sessions, and vice versa. Three tools: `vault_link_session`, `vault_get_session_links`, `vault_get_linked_sessions`. Requires both LoreDocs Pro and LoreConvo Pro.\n- **Tier management**: Free/Pro tiers with configurable limits\n- **Local-first**: SQLite database, no cloud dependency, zero API costs\n\n## MCP Tools\n\nLoreDocs provides 48 MCP tools by default (49 with the `notion` extra installed; 50 with LOREDOCS_ENABLE_CAP_TOOLS=1 and the notion extra) organized by function:\n\n### Vault Management (8 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_create` | Create a new vault with name and description |\n| `vault_list` | List all vaults with doc counts and sizes |\n| `vault_info` | Get detailed vault information |\n| `vault_archive` | Archive a vault (preserves data, hides from listing) |\n| `vault_delete` | Permanently delete a vault and all its documents |\n| `vault_link_project` | Link a vault to a project directory |\n| `vault_open_workspace` | Open or create the vault scoped to a directory path |\n| `loredocs_onboard` | Set up workspace with starter vaults on first install |\n\n### Document Operations (10 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_add_doc` | Add a new document to a vault (inline content or from file path) |\n| `vault_update_doc` | Update document content (creates version history) |\n| `vault_remove_doc` | Remove a document from a vault |\n| `vault_get_doc` | Retrieve a document with full content |\n| `vault_list_docs` | List documents in a vault with filtering and sorting |\n| `vault_copy_doc` | Copy a document to another vault |\n| `vault_move_doc` | Move a document to another vault |\n| `vault_doc_history` | View version history of a document |\n| `vault_doc_restore` | Restore a document to a previous version |\n\n### Search and Discovery (5 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_search` | Full-text search across all vaults |\n| `vault_search_by_tag` | Find documents by tag across all vaults |\n| `vault_find_related` | Discover documents related to a given doc (Pro only) |\n| `vault_suggest` | Proactive suggestions for relevant docs to load |\n| `vault_rebuild_index` | Rebuild the LanceDB semantic search index (Pro only; run once after installing Pro deps) |\n\n### Organization (5 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_tag_doc` | Add tags to a document |\n| `vault_bulk_tag` | Tag multiple documents at once |\n| `vault_categorize` | Set document category (spec, guide, decision, etc.) |\n| `vault_set_priority` | Set document priority level |\n| `vault_add_note` | Add a note or annotation to a document |\n\n### Context Injection (9 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_inject` | Load ranked vault documents into context, packed within a token budget |\n| `vault_inject_by_tag` | Load all documents matching a tag, packed within a token budget |\n| `vault_inject_summary` | Load a vault summary with doc titles and descriptions |\n| `vault_prime` | Pre-load all vault documents by priority order (equivalent to `vault_inject` with no query) |\n| `vault_get_injection_cap` | Get the configured token cap for a vault's injection tools |\n| `vault_set_injection_cap` | Set a vault's injection token cap (requires `LOREDOCS_ENABLE_CAP_TOOLS=1`) |\n| `vault_get_session_token` | Generate a per-session cache key for injection tools |\n| `vault_estimate_tokens` | Estimate the token count an injection call would use before running it |\n| `vault_get_server_capabilities` | Report which injection/token-budget features this server build supports |\n\n### Import/Export (5 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_import_dir` | Import a directory of files into a vault |\n| `vault_import_notion` | Import Notion pages and databases into a vault (one-time, no live sync) |\n| `vault_import_notion_setup` | Report Notion import readiness and how to enable it (read-only) |\n| `vault_export` | Export a document to a file on disk |\n| `vault_export_manifest` | Export vault metadata as a JSON manifest |\n\n### Document Links (2 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_link_doc` | Create a link between two documents |\n| `vault_unlink_doc` | Remove a link between documents |\n\n### Administration (4 tools)\n| Tool | What it does |\n|------|-------------|\n| `vault_tier_status` | Check current tier limits and usage |\n| `vault_set_tier` | Set the active tier (free or pro) |\n| `get_license_tier` | Check current tier and license key status |\n| `vault_verify` | Check document version-history integrity, optionally repair |\n\n### Cross-product Session Links (3 tools, Pro)\n| Tool | What it does |\n|------|-------------|\n| `vault_link_session` | Create a manual link from a LoreConvo session to a LoreDocs document |\n| `vault_get_session_links` | Return LoreConvo sessions linked to a LoreDocs document |\n| `vault_get_linked_sessions` | Return LoreDocs documents linked to a given LoreConvo session |\n\n## Portable Project Workspace\n\nLoreDocs and [LoreConvo](https://github.com/labyrinth-analytics/loreconvo) together form\na portable project workspace for all of Claude -- session memory AND structured knowledge,\nentirely on your machine.\n\n- **LoreConvo** remembers what you discussed, decided, and left open (episodic + semantic memory)\n- **LoreDocs** stores the reference docs, specs, and guides Claude needs (durable knowledge)\n\nWhere cloud AI workspaces tie you to one ecosystem, LoreConvo + LoreDocs works across\nClaude Code, Cursor, OpenAI Codex, Hermes Agent, and Cowork. Both store data locally in\nSQLite. Neither sends anything to an external server.\n\n## Requirements\n\n- Python 3.10+\n- macOS or Linux\n- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager\n- `mcp` and `pydantic` (auto-installed by `uv sync`)\n\n## Supported Storage Substrates\n\nLoreDocs stores document content as plain files on disk. The durability\nguarantee depends on the filesystem substrate:\n\n| Vault root location | Support | Guarantee |\n|---|---|---|\n| Local disk (APFS, ext4, NTFS on a local volume) | Supported | Guarantee holds: a substrate that misreports writes can lose the most recent save, but can never destroy or corrupt a version already on disk. |\n| Cloud-sync folder (Dropbox, iCloud Drive, OneDrive, Google Drive) | Best-effort | Newest save may be lost or resurrected by the sync client. |\n| Network mount (SMB, NFS, sshfs) | Best-effort | Advisory locks may be no-ops, so concurrent clients can lose an update. |\n| Container bind mount / WSL cross-OS path | Best-effort | Same guarantees as the underlying filesystem. |\n\nA one-time warning is emitted when a vault root is detected under a known\ncloud-sync directory. Suppress it with `LOREDOCS_SUPPRESS_SUBSTRATE_WARNING=1`.\n\nThe `metadata.json` file in each document directory is strictly derived from\nthe SQLite database -- the database is the source of truth. Do not edit\n`metadata.json` directly; changes will be overwritten on the next document\nupdate.\n\n## Version History Integrity\n\nLoreDocs v0.1.21+ includes version-storage integrity features:\n\n- **Atomic writes**: Every mutation uses temp + rename, never writing into\n  a destination path. A crash or disk-full leaves existing data untouched.\n- **Intent journal**: Crash recovery via hash-guarded, idempotent replay.\n- **Five-source allocator**: Version numbers are monotonically increasing\n  across content files, sidecars, DB counter, reset marker, and highwater.\n- **Divergence detection**: History loss, jump, rollback, and holes are\n  detected and reported. Writes refuse on divergence; reads proceed with\n  a `divergence` field flagging the issue.\n- **Per-version sidecars**: `history/v{N}.meta.json` records save time,\n  author, session ID, change note, and operation type for each version.\n- **Retention rotation**: Free tier retains 5 versions per document; Pro\n  retains 100. Oldest versions are rotated automatically (never renumbered).\n- **vault_verify**: A diagnostic tool that reports integrity issues and can\n  perform additive-only repairs. Run `vault_verify --pre-upgrade` before\n  upgrading LoreDocs to check for legacy vault anomalies.\n\n## Data and Privacy\n\nLoreDocs is **local-first**. All data lives in `~/.loredocs/` on your machine.\n\n- **Data collected:** Document names, content, tags, categories, and vault names you provide when storing documents. No telemetry, usage analytics, or identifiers are collected automatically.\n- **Storage:** SQLite database at `~/.loredocs/loredocs.db`; document files in `~/.loredocs/vaults/`. No cloud storage. Override the root directory with the `LOREDOCS_ROOT` environment variable.\n- **Third-party sharing:** None. Data never leaves your machine.\n- **Retention:** Data is retained until you delete it via `vault_remove_doc`, `vault_delete`, or remove the database files manually. No automatic expiry.\n- **Contact:** info@labyrinthanalyticsconsulting.com\n\nFull privacy policy: https://labyrinthanalyticsconsulting.com/privacy\n\n## Troubleshooting\n\n**MCP tools not showing up in Claude Code?**\nMake sure you ran `uv sync` first. The virtual environment must exist with dependencies installed.\n\n**\"No module named 'mcp'\" error?**\nThe `.mcp.json` points to the virtual environment's Python. If you moved the folder, re-run `uv sync`.\n\n**Cowork can't see docs saved in Code?**\nAsk Claude to \"mount my ~/.loredocs folder\" so Cowork can access the shared database.\n\n## Fallback Script (Direct DB Access)\n\nIf the MCP server is unreachable (e.g., in scheduled tasks or automation scripts), `scripts/query_loredocs.py` provides the same core operations directly against the SQLite database.\n\n```bash\n# List all vaults\npython scripts/query_loredocs.py --list\n\n# Show vault details and document manifest\npython scripts/query_loredocs.py --info \"My Project Docs\"\n\n# Search documents across all vaults\npython scripts/query_loredocs.py --search \"architecture\"\n\n# Add a document to a vault\npython scripts/query_loredocs.py --add-doc \\\n    --vault \"My Project Docs\" \\\n    --name \"Architecture Overview\" \\\n    --file docs/architecture.md \\\n    --tags '[\"architecture\", \"design\"]'\n\n# Add a document from stdin\necho \"# Quick Note\" | python scripts/query_loredocs.py --add-doc \\\n    --vault \"My Project Docs\" \\\n    --name \"Quick Note\" \\\n    --stdin\n```\n\nThe script auto-discovers the database at `~/.loredocs/loredocs.db` (or pass `--db-path` explicitly). It writes the same schema as the MCP tools, including FTS indexing and on-disk file storage.\n\n## What's New\n\n<!-- WHATS_NEW:START -->\n\n## v0.1.25 (2026-09-05)\n\n### Added: the fallback script can now do semantic search and fetch a single document, and follows a documented contract\n\nIf the LoreDocs MCP server is unreachable, the fallback command-line script\n(`query_loredocs.py`) can now run a semantic search (Pro) and fetch one\ndocument's full content by ID, matching what the MCP tools already do. If\nyou set `LOREDOCS_ROOT` to point the fallback at a specific vault location\nand that location doesn't actually contain your data, the fallback now\nstops with a clear error instead of silently searching somewhere else. See\n`FALLBACK_CONTRACT.md` in the LoreDocs install for exactly what the\nfallback guarantees and how it's kept in sync with the MCP server.\n\n### Documentation: Pro license key issuance\n\nThe README and install docs now set expectations for how you receive your\nPro license key after checkout.\n\n<!-- WHATS_NEW:END -->\n\nSee the full [changelog](docs/CHANGELOG.md) for the complete release history.\n\n## License\n\nBusiness Source License 1.1 (BSL 1.1) - Labyrinth Analytics Consulting\n\nFree for personal/non-commercial use (up to 3 vaults). Commercial use requires\na paid license. Converts to Apache 2.0 on 2030-03-31. See [LICENSE](LICENSE) for details.\n",
  "bytes": 20565,
  "sha": "acd396b36492030d54a718df547009eb36bda8871abb5a41ec73433f09eea203",
  "repo_slug": "labyrinth-analytics/loredocs",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_labyrinth_analytics_loredocs_loredocs_c6966b02/readme"
}