LoreDocs v0.1.26

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 (one time)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 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 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.

Cowork (Desktop App)

1. Click + next to the prompt box
2. Select Plugins > Add plugin
3. Browse to the loredocs source folder

Shared Database Access: Cowork runs in a sandboxed VM. To access docs saved from Claude Code, ask Claude:

"Mount my ~/.loredocs folder"

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_list and 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.

Upgrade to Pro -- $9/month

After checkout, your license key is emailed to the address you used at checkout, usually within one business day. 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_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.
• 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 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:

Vault Management (8 tools)

Document Operations (10 tools)

Search and Discovery (5 tools)

Organization (5 tools)

Context Injection (9 tools)

Import/Export (5 tools)

Document Links (2 tools)

Administration (4 tools)

Cross-product Session Links (3 tools, Pro)

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.10+
• macOS or Linux
• uv package manager
• mcp and pydantic (auto-installed by uv sync)

Supported Storage Substrates

LoreDocs stores document content as plain files on disk. The durability guarantee depends on the filesystem substrate:

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 divergence field flagging the issue.
• Per-version sidecars: history/v{N}.meta.json records 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-upgrade before 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 the LOREDOCS_ROOT environment 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
echo "# Quick Note" | python scripts/query_loredocs.py --add-doc \
    --vault "My Project Docs" \
    --name "Quick Note" \
    --stdin

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.26 (2026-09-08)

Fixed: a rejected update no longer costs you your document history

When an update to a document was turned away -- because it would have exceeded the history storage budget, because another process held the document lock, or because the stored copy had diverged from what was expected -- the earlier versions of that document had already been deleted by the time the rejection happened. The update failed and the history went with it.

Rotation now happens only after the new content has been validated and written, so a rejected update leaves your previous versions exactly where they were. The history budget also counts the right thing: it charges the bytes actually being archived rather than the size of the incoming replacement, and it credits space that the rotation itself is about to free, so updates that comfortably fit are no longer refused. If a rotation is interrupted partway through, it now completes cleanly the next time instead of leaving the document in a half-rotated state.

Fixed: viewing a document's history works again

Asking for a document's version history through the MCP tool raised an error instead of returning anything. It now renders the full result -- the list of versions, any divergence between them, and how much history is being retained.

Fixed: clearing a document's content is saved as a version

Updating a document to empty text is now treated as a real edit: the content clears and the previous version is kept in history, so you can get it back. Leaving the content field out of an update still means "don't touch the content", as before.

Fixed: loading context twice in a row respects settings you changed in between

Repeated context-loading calls were served from a cache that ignored the selection settings and token limits you passed, so changing them had no effect on the second call, and the report of which documents had been left out could disagree with what was actually loaded. The cache now accounts for those settings, and reconsiders every eligible document each time, so what you asked for is what you get and the omission report matches it.

Fixed: Notion imports no longer stop partway through

Importing from Notion silently dropped content past the first page of results -- both for a page's own blocks and for blocks nested inside them -- so large pages arrived incomplete with nothing to indicate anything was missing. Pagination is now followed to the end.

Importing with a page limit also lost track of which pages remained, so there was no way to continue where you left off. The remaining page IDs are now retained in order, including when the import stops because it reached the end of the workspace and when databases are still pending. A malformed or looping cursor from Notion now fails with an explicit error rather than importing partial content quietly.

Fixed: semantic search stops returning documents you have cleared

Clearing a document's content left its old text in the semantic index, so searches kept matching and returning it. Blank content now removes the stale entries, and rebuilding an index that has nothing to index clears it rather than leaving the previous contents in place.

Fixed: automatically discovered relationships now meet the documented similarity bar

Auto-discovered related documents were being linked at a weaker similarity than the documented 0.75 minimum, so the "related documents" list included pairs that were not meaningfully related. New links now apply the documented threshold.

This governs links created from now on. Relationship records already stored do not retain the scores needed to identify which of them fell below the corrected bar, so existing weak links are not removed automatically -- a rebuild will regenerate them at the correct threshold.

Documentation: what "portable data" actually means

The description of LoreDocs storage promised more portability than it delivered, implying a single file could be moved on its own. It now distinguishes the SQLite metadata and keyword index from your vault's content and version history, and states that moving your data means moving the complete data directory.

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.