Provides AI clients with persistent, version-tracked knowledge vaults for project documentation, specifications, and architecture decisions.
Also known as labyrinth-analytics/loredocs
- Stars
- 4
- Tools
- 53
- Downloads, 30 days
- 792
- Latest version
- 0.1.33
- Last commit
- Nov 13, 2026
- License
- —
What is LoreDocs MCP?
LoreDocs provides AI clients with persistent, version-tracked knowledge vaults for project documentation, specifications, and architecture decisions. It exposes 53 tools, such as vault_create, vault_list, vault_info.
Summary generated from the project's README
About LoreDocs MCP server
LoreDocs provides a persistent knowledge base for AI agents to store and retrieve project documentation, architecture decisions, and specifications. It organizes information into named vaults, allowing users to maintain context across different sessions. The system is designed for local-first use, storing all data in a SQLite database at ~/.loredocs/ to ensure privacy and offline availability.
Developers can integrate this server with various clients including Claude Code, Cowork, Hermes Agent, Cursor, and OpenAI Codex. It offers 51 specialized MCP tools for managing vaults, performing full-text searches, and handling document versioning. While the free tier includes core functionality, a Pro subscription removes storage limits and enables semantic search using the BAAI/bge-small-en-v1.5 embedding model.
This tool is particularly useful for multi-agent environments where teams need a single canonical source of truth. By using tools like vault_inject_by_tag, different agents can access the exact same version of a playbook or guide, preventing the knowledge drift that occurs when agents rely on separate local file copies.
What you can do with it
- 1Maintain persistent project contextAn AI client can store and retrieve architecture decisions so it does not lose project details between different chat sessions.
- 2Synchronize knowledge across multiple agentsA developer can ensure that every agent in a team uses the same authoritative version of a project playbook.
- 3Track documentation changes over timeUsers can view the history of a document and roll back to a previous version if an error is introduced.
- 4Perform semantic document discoveryPro users can find documents based on meaning rather than just exact keyword matches.
Written from the project's README. Every use case is checked against a quote from it.
How to install LoreDocs MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall LoreDocs MCP in Claude Code
$ claude mcp add --env 'LOREDOCS_PRO=<YOUR_LOREDOCS_PRO>' loredocs -- uvx loredocsInstall LoreDocs MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"loredocs": {
"command": "uvx",
"args": [
"loredocs"
],
"env": {
"LOREDOCS_PRO": "<YOUR_LOREDOCS_PRO>"
}
}
}
}Install LoreDocs MCP in VS Code
.vscode/mcp.json
{
"servers": {
"loredocs": {
"type": "stdio",
"command": "uvx",
"args": [
"loredocs"
],
"env": {
"LOREDOCS_PRO": "<YOUR_LOREDOCS_PRO>"
}
}
}
}Install LoreDocs MCP in VS Code CLI
$ code --add-mcp '{"name":"loredocs","type":"stdio","command":"uvx","args":["loredocs"],"env":{"LOREDOCS_PRO":"<YOUR_LOREDOCS_PRO>"}}'Install LoreDocs MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"loredocs": {
"command": "uvx",
"args": [
"loredocs"
],
"env": {
"LOREDOCS_PRO": "<YOUR_LOREDOCS_PRO>"
}
}
}
}Install LoreDocs MCP in Codex
$ codex mcp add loredocs --env 'LOREDOCS_PRO=<YOUR_LOREDOCS_PRO>' -- uvx loredocsInstall LoreDocs MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.loredocs] command = "uvx" args = ["loredocs"] [mcp_servers.loredocs.env] LOREDOCS_PRO = "<YOUR_LOREDOCS_PRO>"
Install LoreDocs MCP in Gemini CLI
$ gemini mcp add -s user -e 'LOREDOCS_PRO=<YOUR_LOREDOCS_PRO>' loredocs uvx -- loredocsInstall LoreDocs MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"loredocs": {
"command": "uvx",
"args": [
"loredocs"
],
"env": {
"LOREDOCS_PRO": "<YOUR_LOREDOCS_PRO>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for loredocs 0.1.33 in an isolated container with no network and no keys. It answered and listed 53 tools.
LoreDocs MCP tools 53
Read from the server with tools/listvault_createActionCreate a new knowledge vault for organizing project documents. A vault is a container for related documents -- like a project folder with superpowers (search, tags, versioning). You can link a vault to one or more Claude Projects, but vaults are independent and can serve multiple projects. Returns the new vault's ID and metadata.
vault_listRead-onlyList all knowledge vaults with summary stats (document count, total size, last modified). Use this to see what vaults exist and find the one you need.
vault_infoRead-onlyGet detailed information about a vault, including its full document manifest. Accepts either a vault ID or vault name.
vault_archiveActionArchive a vault (soft delete). Archived vaults are hidden from vault_list by default but can be restored.
vault_deleteActionPermanently delete a vault and ALL its documents. This cannot be undone. You must set confirm=true to proceed. Consider using vault_archive instead.
loredocs_onboardActionSet up or update your LoreDocs workspace configuration. Call once after installing LoreDocs to get a recommended vault structure. Call again to add new domains or agents -- existing data is never modified. Creates: - A Config vault with a 'My LoreDocs Setup' reference doc (tagged authoritative) - One vault per domain in domains - One '[Name] Reports' vault per agent in agents - The reference doc is queryable: vault_search('my setup') Args: name: Workspace or team name domains: Work areas, each becomes a vault (e.g. ['finance', 'research']) agents: Agent names, each gets a '[Name] Reports' vault tag_style: 'simple' (default) or 'detailed' Vault tags: freeform strings on documents for cross-vault retrieval. Categories: reference, report, template, config, archive, general. Priority: authoritative, normal, draft, outdated.
vault_link_projectActionAssociate a Claude Project name with a vault. This is metadata for your organization -- it records which Claude Projects use knowledge from this vault. A vault can be linked to multiple projects.
vault_open_workspaceActionOpen (or create) a vault scoped to a workspace directory. If a vault is already linked to this directory path, returns it. Otherwise, creates a new vault named after the directory and records the workspace_path so future calls return the same vault. This mirrors how MemClaw scopes memory to workspaces -- lower friction than naming vaults manually. Named vaults remain available for users who prefer explicit management.
vault_add_docActionAdd a text document to a vault with metadata (tags, category, priority, notes). The document will be full-text indexed for search and stored with version tracking. Content can be provided inline (content parameter) or from a file path (path parameter). For binary files (PDF, DOCX, etc.), use vault_import_dir to import from a directory.
vault_update_docActionUpdate a document's content or metadata. If content changes, the previous version is saved automatically in the version history. You can restore old versions with vault_doc_restore. The author, session_id, and note params are stored in the version's metadata sidecar for provenance tracking. Unknown parameters are rejected at the MCP dispatch layer (see _forbid_unknown_tool_params below): FastMCP's generated arg model for this tool has extra="forbid", so a client-supplied unknown param never reaches this function body.
vault_remove_docActionSoft-delete a document. The document is hidden but can be recovered. For permanent deletion, use vault_delete to remove the entire vault.
vault_get_docRead-onlyRetrieve a document's metadata and optionally its text content. Use include_content=false to get just the metadata without loading the full text.
Show all 53 toolsShow fewer tools
vault_list_docsRead-onlyList documents in a vault with sorting and filtering options. Supports sorting by name, date, size, or category. Filter by category or tag to narrow results.
vault_searchRead-onlyFull-text or semantic search across document contents. Default (semantic=False): SQLite FTS5 keyword search. Supports FTS5 syntax: - Simple words: depreciation schedule - Phrases: "rental income" - Boolean: depreciation AND schedule - Negation: rental NOT commercial - Prefix: deprec* Semantic (semantic=True, Pro only): hybrid vector + BM25 search via LanceDB. Finds documents by meaning even when exact keywords differ. Requires LoreDocs Pro and `pip install loredocs[pro]`. Falls back to FTS5 if the semantic index has not been built yet (run vault_rebuild_index first).
vault_rebuild_indexActionRebuild the LanceDB semantic search index from all stored documents. Pro only. Run this after first installing the Pro deps (pip install loredocs[pro]) or after restoring from backup. The index is kept in sync automatically for new documents added after install, but existing documents require a one-time rebuild to become searchable semantically.
vault_rebuild_index_statusRead-onlyReturn the current status of a background semantic-index rebuild. Call after vault_rebuild_index to monitor progress. Returns 'idle' when no rebuild has been started or the last rebuild has finished. Returns a JSON dict with: - status: 'idle' | 'running' | 'complete' | 'error' - message: human description - For running: phase, progress, total, progress_pct, elapsed_s, and eta_s when phase != 'finalizing' (no reliable ETA for the untimed table-build/FTS-index step that follows embedding) - For complete: indexed, total_in_db, exclusions {reason: count}, elapsed_s
vault_search_by_tagRead-onlyFind all documents with a specific tag, across one vault or all vaults.
vault_tag_docActionAdd or remove tags on a document. You can add and remove tags in a single operation. Tags are case-sensitive strings. Duplicates are automatically removed.
vault_bulk_tagActionApply tag changes to multiple documents at once. Useful for organizing a batch of documents after import or reclassification.
vault_categorizeActionSet a document's category (general, reference, config, report, template, archive, imported).
vault_set_priorityActionMark a document's priority/status: authoritative, normal, draft, or outdated. 'authoritative' means this document is the source of truth. 'outdated' flags the document as no longer current.
vault_add_noteActionAttach a contextual note to a document. Notes help you and your AI assistant understand when/how to use this document.
vault_doc_historyRead-onlyView the version history for a document. Every time a document's content is updated, the previous version is saved automatically. Use vault_doc_restore to revert to an earlier version.
vault_doc_restoreActionRestore a document to a previous version. The current version is saved to history first, then the specified version becomes the new current version.
vault_verifyRead-onlyVerify version-storage integrity for a vault or specific document. By default, runs a read-only check that reports: - Stale intent journals (crash recovery left incomplete) - Recovery orphan files - Missing, invalid, or too-new version sidecars - Missing versions (no content file and no rotation record) - Version count disagreement between DB and filesystem - History divergence (loss, jump, rollback, or holes) - Unrecognized files under history/ - Conflict files from hash-guarded replay - Per-vault history bytes vs the hard cap - Permissions advisory on the vault root With repair=True, performs additive-only repairs: - Replays stale intent journals - Moves invalid/too-new sidecars aside (renames, never deletes) - Realigns documents.version_count with the filesystem The confirm parameter gates divergence recovery operations. Each confirm value writes one marker file and removes nothing. With pre_upgrade=True, runs a read-only pre-upgrade scan that records .upgrade_scan.json. Safe to run before upgrading LoreDocs.
vault_copy_docActionCopy a document from one vault to another, including all metadata.
vault_move_docActionMove a document to a different vault. Removes it from the source vault.
vault_injectRead-onlyLoad ranked vault documents into conversation context with token-budget enforcement. Documents are ranked by FTS5 relevance (when query is provided) and priority weight, then packed greedily until the effective token cap is reached. Args: vault_name: Vault name or ID. query: Optional FTS5 search query to rank documents by relevance. max_tokens: Hard token budget. Overrides vault DB cap. Effective cap = max_tokens * safety_factor. cap_behavior: 'best_effort' (inject as many docs as fit) or 'strict' (error if any doc exceeds cap). session_token: Optional opaque string used as per-session cache key. max_single_doc_tokens: Truncate individual documents to this many tokens. 0 = no per-doc limit. safety_factor: Fraction of max_tokens to use as effective cap (default 0.60 = 60%).
vault_primeRead-onlyPre-load all vault documents into the current session by priority order. Equivalent to vault_inject with no query: loads all documents ordered by priority weight (authoritative first), then by recency. Use at session start to orient yourself on all knowledge available in a vault. Args: vault_name: Vault name or ID. max_tokens: Hard token budget. Effective cap = max_tokens * safety_factor. cap_behavior: 'best_effort' (inject as many docs as fit) or 'strict' (error if cap exceeded). session_token: Optional opaque string used as per-session cache key. max_single_doc_tokens: Truncate individual documents to this many tokens. safety_factor: Fraction of max_tokens to use as effective cap (default 0.60 = 60%).
vault_inject_by_tagRead-onlyLoad all documents matching any of the given tags into the current conversation context. Documents matching any of the provided tags are fetched, ranked by priority weight and recency, then packed greedily within the token cap. Args: vault_name: Vault name or ID. tags: List of tags to match (OR semantics: any matching tag includes the doc). max_tokens: Hard token budget. Effective cap = max_tokens * safety_factor. cap_behavior: 'best_effort' (inject as many docs as fit) or 'strict'. session_token: Optional opaque string used as per-session cache key. max_single_doc_tokens: Truncate individual documents to this many tokens. safety_factor: Fraction of max_tokens to use as effective cap (default 0.60 = 60%).
vault_inject_summaryRead-onlyGenerate a summary overview of a vault's contents for conversation orientation. Lists all documents with their categories, tags, priorities, and notes. Useful at the start of a conversation to understand what knowledge is available.
vault_get_injection_capRead-onlyReturn the stored per-vault injection token cap (or 'not set' if none). If not set, the server falls back to LOREDOCS_INJECTION_CAP_TOKENS env var, then LOREDOCS_INJECTION_DEFAULT_CAP_TOKENS (default 100000).
vault_get_session_tokenActionGenerate a fresh session token (UUID4) for use with vault_inject / vault_prime. Pass the returned token as session_token in subsequent injection calls so the per-session cache can scope cached results to this conversation. Cache hits are valid until any document in the vault is updated.
vault_estimate_tokensRead-onlyPreview the token count of a vault injection without injecting documents. Returns estimated token counts for each document (up to 500) so you can choose an appropriate max_tokens value before calling vault_inject. Uses tiktoken if available; falls back to char-based estimation.
vault_get_server_capabilitiesRead-onlyReturn a summary of this LoreDocs server's injection capabilities and token estimation settings. Useful for diagnosing injection behavior or verifying which features are active.
vault_import_dirActionBulk import all supported files from a directory into a vault. Imports text files, PDFs, Word docs, Excel files, PowerPoints, and more. Each file becomes a separate document with text extracted for search indexing. Files over 30MB are skipped. Hidden files (starting with .) are skipped. By default skips config files (.css, .js, .json). Supports Obsidian vaults: subdirectories are traversed recursively by default (set recursive=False for single-level import). Markdown files with YAML frontmatter tags (tags: [a, b] or block-list style) have those tags merged into the document. Relative folder paths are preserved in document notes for disambiguation.
vault_exportActionExport all documents from a vault to a local directory. Copies the original files (not extracted text) to the specified directory. Useful for backing up or sharing vault contents.
vault_link_docActionCreate a link between two documents across any vault. Links are bidirectional and labelled (e.g. 'related', 'references', 'supersedes', 'part-of'). If the link already exists, reports it. Use vault_find_related to discover all docs linked to a given document.
vault_unlink_docActionRemove a link between two documents (both directions). By default removes manually-created links only -- an auto-generated link (e.g. 'auto:cooccurrence') on the same pair is left in place. Pass label explicitly to target an auto link. If no matching link exists between the two documents, reports that cleanly.
vault_find_relatedRead-onlyFind all documents linked to a given document. Pro only. Returns each related document with its vault, category, tags, and link label. Use vault_link_doc to create new links.
vault_suggestRead-onlyGet suggestions for documents that may need attention. Surfaces documents that are undocumented (no notes), unorganized (no tags), or isolated (no links to other documents). Use to guide housekeeping work or to discover documents that haven't been connected to the broader graph. Optionally scope to a single vault.
vault_export_manifestRead-onlyExport a complete manifest of a vault's contents. Returns vault metadata, document list with tags and categories, tag frequency index, category counts, and link count. Use the json format for machine-readable output. Use the markdown format for human-readable summaries.
vault_tier_statusRead-onlyShow current tier (Free or Pro) and usage vs. limits. Displays how many vaults and how much storage are in use, with percentages against Free tier limits. Useful before hitting a limit to know how close you are, or to confirm Pro tier is active after upgrading.
vault_set_tierActionActivate a tier (free or pro) for LoreDocs. Pro tier removes all vault, document, storage, and version limits. After purchasing a Pro license, set LOREDOCS_PRO=<your-license-key> in your environment and restart the server, then call this tool with tier='pro' to persist the Pro tier. Reverting to tier='free' re-enables limits (but does not delete any existing data that exceeds the limits -- it only blocks new writes).
get_license_tierReturn the current LoreDocs license tier and status. Use this to confirm whether the Pro license key is loaded and valid. Returns a dict with keys: is_pro -- bool, True if Pro tier is active mode -- "licensed" | "dev_bypass" | "free" | "invalid_key" product -- product name from the license payload (if licensed) exp -- expiry date or "never" (if licensed) email -- customer email (if licensed and present) error -- error message (if mode is "invalid_key") upgrade_url -- Stripe checkout link (present when not already Pro)
vault_link_sessionCreate a manual cross-product link from a LoreConvo session to a LoreDocs doc. Both LoreConvo and LoreDocs must be installed. Manual links are accessible on all tiers. The linked doc must not be in an opt-out vault. Args: session_id -- LoreConvo session UUID doc_id -- LoreDocs document ID vault_id -- LoreDocs vault containing the document Returns dict with: ok -- bool session_id, doc_id on success reason -- failure description (generic; details in debug log)
vault_get_session_linksReturn cross-product LoreConvo sessions linked to a LoreDocs document. Both LoreConvo and LoreDocs must be installed. Requires Pro tier for auto-links. Manual links are always returned. Args: doc_id -- LoreDocs document ID limit -- max results (default 5) Returns dict with: schema_version -- CROSS_LINK_SCHEMA_VERSION for version negotiation cross_product_available -- bool tier_gate -- "satisfied" | "pro_required" links -- list of {target_product, target_id, similarity_score, link_type, created_at, is_stale}
vault_get_linked_sessionsReturn LoreDocs documents linked to a given LoreConvo session. Queries the LoreDocs cross_product_links table for links where the session is the source or target. Returns both auto and manual links. Requires Pro tier for auto-links. Args: session_id -- LoreConvo session UUID limit -- max results (default 5) Returns same structure as vault_get_session_links.
vault_prune_dangling_linksFind and optionally delete dangling auto cross-product links. A dangling link is one where the LoreConvo session (source or target) no longer exists. Only link_type='auto' rows are deleted; manual links are never touched. Dry-run by default (execute=False). A timestamped backup of loredocs.db is taken before any deletion. REFUSES to run if the LoreConvo DB cannot be discovered or if its sessions table is empty -- a wrong path would make every link look dangling and wipe all of them. Args: execute -- if True, delete dangling auto links (default False) Returns dict with: ok -- bool total_auto -- total auto links in the table dangling_auto -- dangling auto links found dangling_manual -- dangling manual links (left alone) over_cap_docs -- docs with > 500 auto links deleted -- rows deleted (0 if dry run) backup_path -- str if a backup was taken error -- str if ok is False
vault_trim_overcap_linksTrim each doc's auto session links to the top 500 by similarity_score. Manual links are never counted against or removed by the trim. Dry-run by default (execute=False). A timestamped backup of loredocs.db is taken before any deletion. REFUSES to run if the LoreConvo DB cannot be discovered or if its sessions table is empty. Args: execute -- if True, trim over-cap docs (default False) Returns dict with: ok -- bool over_cap_docs -- count of docs trimmed total_trimmed -- rows removed (0 if dry run) backup_path -- str if a backup was taken error -- str if ok is False
get_server_infoReturn MCP compatibility status for this LoreDocs server. Returns product version, installed mcp SDK version, tested version, and compatibility status. Useful for diagnosing version mismatches on running servers without requiring a restart. Returns dict with: product_name, product_version, install_kind (wheel|editable), version_from_source (if editable), mcp_installed, mcp_tested, mcp_accepted, status (ok|mismatch|undetermined|disabled|internal_error), note, error_detail (set only on internal_error).
vault_import_notion_setupRead-onlyReport Notion import readiness and how to enable it. Read-only. Does not install or modify any packages.
configure_toolsActionList or set enabled MCP tool groups. Called with no arguments: lists every group name, its tool count, and whether it is currently enabled. Called with a list of group names: validates and persists the selection to config.json. The change takes effect on server restart -- already- connected clients may continue to see removed tools in their cached schema until they reconnect, and calls to a removed tool after restart return a standard 'unknown tool' protocol error. If the LOREDOCS_TOOL_GROUPS environment variable is set, this tool returns an error instead of writing (the env var overrides config).
Configuration
LOREDOCS_PROSecretPro license key. Leave unset for the free tier.
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablePass
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledPass
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubLoreDocs v0.1.33
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
Quick Start
Prerequisites: uv (fast Python package manager).
# Install uv: https://docs.astral.sh/uv/getting-started/installation/
# Clone and install
cd /path/to/loredocs
uv sync
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.
Using LoreDocs
Claude Code (Terminal)
claude --plugin-dir /path/to/loredocs
Or inside an existing session:
/plugin add /path/to/loredocs
Once loaded, Claude has access to all 51 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.
Cowork (Desktop App)
- Click + next to the prompt box
- Select Plugins > Add plugin
- Browse to the
loredocssource folder
Shared Database Access: Cowork runs in a sandboxed VM. To access docs saved from Claude Code, ask Claude:
"Mount my ~/.loredocs folder"
Hermes Agent
For Hermes Agent users, add LoreDocs as an MCP server under mcp_servers: in ~/.hermes/config.yaml (see INSTALL.md for the full entry), then restart Hermes.
All 51 LoreDocs MCP tools are then available in your Hermes sessions.
Hermes Disclosures
When using LoreDocs with Hermes Agent:
- Installation: First run downloads the
loredocsversion you pin from PyPI viauvx. There is no automatic self-update. - Data Storage: All vault data is stored locally at
~/.loredocs/in SQLite format. No data is sent to cloud services or external servers. - Pro License Validation: Pro tier activation uses offline Ed25519 cryptography to validate your license key. No network request is made during validation.
- Telemetry: LoreDocs does not collect or transmit telemetry or usage data.
- Network calls: Pro semantic search downloads the
BAAI/bge-small-en-v1.5embedding model from Hugging Face once, on first use. The optional Notion import calls the Notion API with a token you provide. LoreDocs makes no other network calls.
How It Works
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.
~/.loredocs/loredocs.db <-- SQLite database (metadata, search index)
~/.loredocs/vaults/<vault-id>/ <-- Document files on disk
Key concepts:
- Vaults group related docs by project or topic
- Documents are text files with metadata (tags, categories, priority, notes)
- Version history tracks every change to every document
- Full-text search via SQLite FTS5 finds anything instantly
- Injection loads vault content into Claude's context on demand
Your Data is Always Available
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.
Verify Installation
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.
Recommended CLAUDE.md Setup
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.
## LoreDocs (persistent project knowledge)
At session start:
1. Call `vault_list` to see available knowledge vaults.
2. Call `vault_inject_summary` for any vaults relevant to the current project.
3. Use this context to understand project architecture, decisions, and reference docs.
During the session:
- If you create significant documentation, add it to LoreDocs with `vault_add_doc`.
- Tag documents for easy cross-vault discovery with `vault_tag_doc`.
At session end:
- If new docs were created or updated, ensure they are stored in LoreDocs for future 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.
Canonical Project Knowledge
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.
Recommended pattern
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:
vault_inject_by_tag: team-playbook
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.
Example: sharing a playbook across an agent team
# Session start for any agent on the team:
# 1. Inject the shared playbook by tag
vault_inject_by_tag("team-playbook")
# 2. Inject any project-specific reference docs
vault_inject_by_tag("project-architecture")
# Working context is now current -- no local file copies needed.
To store the shared content in the vault (one time, or on each update):
# Store (or update) the shared playbook:
vault_update_doc(vault="team-knowledge", doc_id="playbook-id", content=open("PLAYBOOK.md").read())
# Or add it fresh (path= reads directly from disk -- no need to load into context):
vault_add_doc(vault="team-knowledge", name="Team Playbook", path="/absolute/path/to/PLAYBOOK.md", tags=["team-playbook"])
Any agent that calls vault_inject_by_tag("team-playbook") reads the same document.
No copies, no mirrors, no drift.
Plans: Free vs Pro
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.
Features
- Vault organization: Group docs by project with linked project metadata
- Document versioning: Full history with rollback to any prior version
- Tagging and categorization: Tag docs for cross-vault discovery
- Priority levels: Mark docs as critical, high, normal, or low priority
- Full-text search: Fast keyword search across all vaults and documents
- Context injection: Load specific docs, tags, or vault summaries into Claude's context
- Bulk operations: Import directories, bulk-tag, export manifests
- Document linking: Connect related docs across vaults
- Embedding-based document relationships (Pro):
vault_find_relatedreturns 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. - 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. - Tier management: Free/Pro tiers with configurable limits
- Local-first: SQLite database, no cloud dependency, zero API costs
MCP Tools
LoreDocs provides 51 MCP tools by default (52 with the notion extra installed; 52 with LOREDOCS_ENABLE_CAP_TOOLS=1 and the notion extra) organized by function:
Vault Management (8 tools)
| 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 |
Document Operations (10 tools)
| 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 |
Search and Discovery (6 tools)
| 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) |
vault_rebuild_index_status |
Return the current status of a background semantic-index rebuild (Pro only) |
Organization and Maintenance (7 tools)
| 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 |
vault_prune_dangling_links |
Remove auto-generated links that reference non-existent documents |
vault_trim_overcap_links |
Remove excess auto-generated links when link count exceeds the configured cap |
Context Injection (9 tools)
| 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 |
Import/Export (5 tools)
| 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 all documents from a vault to a directory under the LoreDocs exports folder |
vault_export_manifest |
Export vault metadata as a JSON manifest |
Document Links (2 tools)
| Tool | What it does |
|---|---|
vault_link_doc |
Create a link between two documents |
vault_unlink_doc |
Remove a link between documents |
Administration (5 tools)
| 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 |
configure_tools |
List or choose which groups of LoreDocs tools the server exposes (takes effect after restart) |
Cross-product Session Links (3 tools, Pro)
| 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 |
Portable Project Workspace
LoreDocs and LoreConvo together form a portable project workspace for all of Claude -- session memory AND structured knowledge, entirely on your machine.
- LoreConvo remembers what you discussed, decided, and left open (episodic + semantic memory)
- LoreDocs stores the reference docs, specs, and guides Claude needs (durable knowledge)
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.
Requirements
- Python 3.11-3.14
- macOS or Linux
- uv package manager
mcpandpydantic(auto-installed byuv sync)
Supported Storage Substrates
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.
Version History Integrity
LoreDocs v0.1.21+ includes version-storage integrity features:
- Atomic writes: Every mutation uses temp + rename, never writing into a destination path. A crash or disk-full leaves existing data untouched.
- Intent journal: Crash recovery via hash-guarded, idempotent replay.
- Five-source allocator: Version numbers are monotonically increasing across content files, sidecars, DB counter, reset marker, and highwater.
- Divergence detection: History loss, jump, rollback, and holes are
detected and reported. Writes refuse on divergence; reads proceed with
a
divergencefield flagging the issue. - Per-version sidecars:
history/v{N}.meta.jsonrecords save time, author, session ID, change note, and operation type for each version. - Retention rotation: Free tier retains 5 versions per document; Pro retains 100. Oldest versions are rotated automatically (never renumbered).
- vault_verify: A diagnostic tool that reports integrity issues and can
perform additive-only repairs. Run
vault_verify --pre-upgradebefore upgrading LoreDocs to check for legacy vault anomalies.
Data and Privacy
LoreDocs is local-first. All data lives in ~/.loredocs/ on your machine.
- Data collected: Document names, content, tags, categories, and vault names you provide when storing documents. No telemetry, usage analytics, or identifiers are collected automatically.
- Storage: SQLite database at
~/.loredocs/loredocs.db; document files in~/.loredocs/vaults/. No cloud storage. Override the root directory with theLOREDOCS_ROOTenvironment variable. - Third-party sharing: None. Data never leaves your machine.
- Retention: Data is retained until you delete it via
vault_remove_doc,vault_delete, or remove the database files manually. No automatic expiry. - Contact: info@labyrinthanalyticsconsulting.com
Full privacy policy: https://labyrinthanalyticsconsulting.com/privacy
Troubleshooting
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.
Fallback Script (Direct DB Access)
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.
# List all vaults
python scripts/query_loredocs.py --list
# Show vault details and document manifest
python scripts/query_loredocs.py --info "My Project Docs"
# Search documents across all vaults
python scripts/query_loredocs.py --search "architecture"
# Add a document to a vault
python scripts/query_loredocs.py --add-doc \
--vault "My Project Docs" \
--name "Architecture Overview" \
--file docs/architecture.md \
--tags '["architecture", "design"]'
# Add a document from stdin (type content, then Ctrl-D)
python scripts/query_loredocs.py --add-doc \
--vault "My Project Docs" \
--name "Quick Note" \
--stdin <<'EOF'
# Quick Note
EOF
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.
What's New
v0.1.33 (2026-11-06)
Added
- New maintenance command
scripts/cleanup_dangling_cross_links.pyremoves cross-product links to LoreConvo sessions that no longer exist. Run it in dry-run mode by default; pass--executeto delete. A timestamped backup ofloredocs.dbis taken before any deletion. Pass--trimto also trim docs whose auto session links exceed 500 (the new lifetime cap) back to the top 500 by similarity. The tool refuses to run if LoreConvo is not installed or its sessions table is empty.
Changed
vault_exportnow writes to LoreDocs' exports folder (~/.loredocs/exports/by default, or$LOREDOCS_ROOT/exports/when set) instead of the program's working directory, and its success message reports the full path. A~path is refused with a clear error.- Vault names are now unique regardless of letter case: creating a vault named "app" when "App" already exists is refused, and opening a workspace whose folder name matches an existing vault (archived or not) creates a "name (2)"-style vault instead of failing.
- The fallback script's
--create-vaultnow refuses duplicate vault names, matching the MCP tools.
Fixed
- Onboarding no longer fails when an archived vault already holds a name it wants to use (for example a "Config" vault); it creates a fresh, uniquely named vault instead.
See the full changelog for the complete release history.
License
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
LoreDocs MCP questions
How do I add LoreDocs MCP to Claude Code?
Run claude mcp add --env 'LOREDOCS_PRO=<YOUR_LOREDOCS_PRO>' loredocs -- uvx loredocs in your terminal. Add --scope user to make it available in every project.
How do I add LoreDocs MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does LoreDocs MCP provide?
It exposes 53 tools, including vault_create, vault_list, vault_info, vault_archive, vault_delete.
Does LoreDocs send my data to the cloud?
No, all vault data is stored locally in SQLite format and no data is sent to cloud services or external servers.
What is the difference between the Free and Pro plans?
The Pro plan removes storage limits, allows unlimited vaults and documents, and unlocks semantic retrieval and embedding-based document relationships.
How can I verify that LoreDocs is installed correctly?
You can verify the installation by asking Claude to run the vault_list tool and show the results.
Does LoreDocs collect telemetry?
No, LoreDocs does not collect or transmit any telemetry or usage data.