The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the LoreDocs listing page.
Your AI project's knowledge base. Organized, searchable, version-tracked.
LoreDocs 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.
Install directly from Claude Code's plugin marketplace, or via PyPI:
uvx loredocs
Prerequisites: uv (fast Python package manager).
For detailed installation instructions, see INSTALL.md.
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.
Or inside an existing session:
Once 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.
loredocs source folderShared Database Access: Cowork runs in a sandboxed VM. To access docs saved from Claude Code, ask Claude:
"Mount my ~/.loredocs folder"
LoreDocs 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.
Key concepts:
LoreDocs 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.
After installing, verify LoreDocs is working by asking Claude:
"Run
vault_listand show me the results."
If 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.
For 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.
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.
In multi-agent environments, different tools and agents often create improvised mirrors of shared skill or configuration content -- playbooks, style guides, shared reference docs. Those mirrors drift. One agent updates the source; the other keeps reading the stale copy. Two agents in the same project end up operating from divergent knowledge with no visible signal that anything is wrong.
LoreDocs prevents this by making the vault the single canonical source that every agent
reads. Instead of each agent loading a local file copy, every agent calls
vault_inject_by_tag at session start and gets the same vault-managed version.
Store shared content (playbooks, team guidelines, shared specs) as vault documents rather than as local files that agents copy or mirror.
Agents load the content at session start:
All agents -- regardless of surface (Claude Code, Cowork, CLI, or any future AI tool) -- call the same vault and receive the same current version. Updating the content requires editing the vault document once; all agents pick up the change on their next session start.
Local files (.claude/skills/, .agents/, or any surface-specific config) become
pointers or bootstrap stubs only -- not the authoritative content. The vault is the
source of truth.
To store the shared content in the vault (one time, or on each update):
Any agent that calls vault_inject_by_tag("team-playbook") reads the same document.
No copies, no mirrors, no drift.
LoreDocs is local-first and free to use. Pro ($9/mo) removes the storage limits and unlocks semantic (meaning-based) retrieval. Everything runs on your machine on either plan -- Pro does not add any cloud component.
| Free | Pro ($9/mo) | |
|---|---|---|
| Vaults | 3 | Unlimited |
| Documents per vault | 50 | Unlimited |
| Storage | 500 MB | Unlimited |
| Version history per document | 5 versions | Unlimited |
| Full-text search (FTS5) | Yes | Yes |
| Core MCP tools (create, search, version, tag, inject, import/export) | Yes | Yes |
| Local-first, no cloud, no telemetry | Yes | Yes |
Semantic search (vault_search semantic=true, vault_rebuild_index) | -- | Yes |
Embedding-based document relationships (vault_find_related) | Keyword co-occurrence only | Keyword + embedding auto-links |
Cross-product session linking (vault_link_session + 2 more) | -- | Yes (also requires LoreConvo Pro) |
After checkout, your license key is emailed automatically to the address you used at checkout, usually within a few minutes. Questions: info@labyrinthanalyticsconsulting.com.
Free tier limits are enforced before writes; Pro removes them. Check your current tier
and usage anytime with vault_tier_status. Activate a Pro license with vault_set_tier.
The Pro semantic features use a local embedding model (BGE-small-en-v1.5) and the LanceDB index -- still no data leaves your machine.
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.vault_link_session, vault_get_session_links, vault_get_linked_sessions. Requires both LoreDocs Pro and LoreConvo Pro.LoreDocs 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:
| Tool | What it does |
|---|---|
vault_create | Create a new vault with name and description |
vault_list | List all vaults with doc counts and sizes |
vault_info | Get detailed vault information |
vault_archive | Archive a vault (preserves data, hides from listing) |
vault_delete | Permanently delete a vault and all its documents |
vault_link_project | Link a vault to a project directory |
vault_open_workspace | Open or create the vault scoped to a directory path |
loredocs_onboard | Set up workspace with starter vaults on first install |
| Tool | What it does |
|---|---|
vault_add_doc | Add a new document to a vault (inline content or from file path) |
vault_update_doc | Update document content (creates version history) |
vault_remove_doc | Remove a document from a vault |
vault_get_doc | Retrieve a document with full content |
vault_list_docs | List documents in a vault with filtering and sorting |
vault_copy_doc | Copy a document to another vault |
vault_move_doc | Move a document to another vault |
vault_doc_history | View version history of a document |
vault_doc_restore | Restore a document to a previous version |
| Tool | What it does |
|---|---|
vault_search | Full-text search across all vaults |
vault_search_by_tag | Find documents by tag across all vaults |
vault_find_related | Discover documents related to a given doc (Pro only) |
vault_suggest | Proactive suggestions for relevant docs to load |
vault_rebuild_index | Rebuild the LanceDB semantic search index (Pro only; run once after installing Pro deps) |
| Tool | What it does |
|---|---|
vault_tag_doc | Add tags to a document |
vault_bulk_tag | Tag multiple documents at once |
vault_categorize | Set document category (spec, guide, decision, etc.) |
vault_set_priority | Set document priority level |
vault_add_note | Add a note or annotation to a document |
| Tool | What it does |
|---|---|
vault_inject | Load ranked vault documents into context, packed within a token budget |
vault_inject_by_tag | Load all documents matching a tag, packed within a token budget |
vault_inject_summary | Load a vault summary with doc titles and descriptions |
vault_prime | Pre-load all vault documents by priority order (equivalent to vault_inject with no query) |
vault_get_injection_cap | Get the configured token cap for a vault's injection tools |
vault_set_injection_cap | Set a vault's injection token cap (requires LOREDOCS_ENABLE_CAP_TOOLS=1) |
vault_get_session_token | Generate a per-session cache key for injection tools |
vault_estimate_tokens | Estimate the token count an injection call would use before running it |
vault_get_server_capabilities | Report which injection/token-budget features this server build supports |
| Tool | What it does |
|---|---|
vault_import_dir | Import a directory of files into a vault |
vault_import_notion | Import Notion pages and databases into a vault (one-time, no live sync) |
vault_import_notion_setup | Report Notion import readiness and how to enable it (read-only) |
vault_export | Export a document to a file on disk |
vault_export_manifest | Export vault metadata as a JSON manifest |
| Tool | What it does |
|---|---|
vault_link_doc | Create a link between two documents |
vault_unlink_doc | Remove a link between documents |
| Tool | What it does |
|---|---|
vault_tier_status | Check current tier limits and usage |
vault_set_tier | Set the active tier (free or pro) |
get_license_tier | Check current tier and license key status |
vault_verify | Check document version-history integrity, optionally repair |
| Tool | What it does |
|---|---|
vault_link_session | Create a manual link from a LoreConvo session to a LoreDocs document |
vault_get_session_links | Return LoreConvo sessions linked to a LoreDocs document |
vault_get_linked_sessions | Return LoreDocs documents linked to a given LoreConvo session |
LoreDocs and LoreConvo together form a portable project workspace for all of Claude -- session memory AND structured knowledge, entirely on your machine.
Where cloud AI workspaces tie you to one ecosystem, LoreConvo + LoreDocs works across Claude Code, Cursor, OpenAI Codex, Hermes Agent, and Cowork. Both store data locally in SQLite. Neither sends anything to an external server.
mcp and pydantic (auto-installed by uv sync)LoreDocs stores document content as plain files on disk. The durability guarantee depends on the filesystem substrate:
| Vault root location | Support | Guarantee |
|---|---|---|
| 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. |
| Cloud-sync folder (Dropbox, iCloud Drive, OneDrive, Google Drive) | Best-effort | Newest save may be lost or resurrected by the sync client. |
| Network mount (SMB, NFS, sshfs) | Best-effort | Advisory locks may be no-ops, so concurrent clients can lose an update. |
| Container bind mount / WSL cross-OS path | Best-effort | Same guarantees as the underlying filesystem. |
A one-time warning is emitted when a vault root is detected under a known
cloud-sync directory. Suppress it with LOREDOCS_SUPPRESS_SUBSTRATE_WARNING=1.
The metadata.json file in each document directory is strictly derived from
the SQLite database -- the database is the source of truth. Do not edit
metadata.json directly; changes will be overwritten on the next document
update.
LoreDocs v0.1.21+ includes version-storage integrity features:
divergence field flagging the issue.history/v{N}.meta.json records save time,
author, session ID, change note, and operation type for each version.vault_verify --pre-upgrade before
upgrading LoreDocs to check for legacy vault anomalies.LoreDocs is local-first. All data lives in ~/.loredocs/ on your machine.
~/.loredocs/loredocs.db; document files in ~/.loredocs/vaults/. No cloud storage. Override the root directory with the LOREDOCS_ROOT environment variable.vault_remove_doc, vault_delete, or remove the database files manually. No automatic expiry.Full privacy policy: https://labyrinthanalyticsconsulting.com/privacy
MCP tools not showing up in Claude Code?
Make sure you ran uv sync first. The virtual environment must exist with dependencies installed.
"No module named 'mcp'" error?
The .mcp.json points to the virtual environment's Python. If you moved the folder, re-run uv sync.
Cowork can't see docs saved in Code? Ask Claude to "mount my ~/.loredocs folder" so Cowork can access the shared database.
If 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.
The 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.
doc history and doc restore commands. Both use the same
code the MCP tools use, so results match.See the full changelog for the complete release history.
Business Source License 1.1 (BSL 1.1) - Labyrinth Analytics Consulting
Free for personal/non-commercial use (up to 3 vaults). Commercial use requires a paid license. Converts to Apache 2.0 on 2030-03-31. See LICENSE for details.
mcp-name: io.github.labyrinth-analytics/loredocs