Metadata-Version: 2.4
Name: loredocs
Version: 0.1.7
Summary: Knowledge management MCP server for AI projects - search, tag, version, and organize your project knowledge
Author: Labyrinth Analytics Consulting
License: Business Source License 1.1
        
        Parameters
        
        Licensor:             Labyrinth Analytics Consulting
        Licensed Work:        LoreDocs v0.1.0
                              The Licensed Work is (c) 2026 Labyrinth Analytics Consulting
        Additional Use Grant: You may make personal, non-commercial use of the Licensed Work,
                              subject to the following limitation: you may create no more than
                              3 vaults in total. Any use that exceeds this limit, or any
                              commercial use, requires a paid license from the Licensor.
        Change Date:          2030-03-31
        Change License:       Apache License, Version 2.0
        
        For information about alternative licensing arrangements for the Licensed Work,
        please contact: info@labyrinthanalyticsconsulting.com
        
        ---
        
        Business Source License 1.1
        
        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
        "Business Source License" is a trademark of MariaDB Corporation Ab.
        
        Terms
        
        The Licensor hereby grants you the right to copy, modify, create derivative
        works, redistribute, and make non-production use of the Licensed Work. The
        Licensor may make an Additional Use Grant, above, permitting limited production
        use.
        
        Effective on the Change Date, or the fourth anniversary of the first publicly
        available distribution of a specific version of the Licensed Work under this
        License, whichever comes first, the Licensor hereby grants you rights under
        the terms of the Change License, and the rights granted in the paragraph
        above terminate.
        
        If your use of the Licensed Work does not comply with the requirements
        currently in effect as described in this License, you must purchase a
        commercial license from the Licensor, its affiliated entities, or authorized
        resellers, or you must refrain from using the Licensed Work.
        
        All copies of the original and modified Licensed Work, and derivative works
        of the Licensed Work, are subject to this License. This License applies
        separately for each version of the Licensed Work and the Change Date may vary
        for each version of the Licensed Work released by Licensor.
        
        You must conspicuously display this License on each original or modified copy
        of the Licensed Work. If you receive a copy of the Licensed Work in
        combination with other programs, as part of a larger work, or packaged by a
        third party, and you receive the Licensed Work under a different license from
        the one described in this License, you are required to comply with the license
        applicable to you.
        
        Any use of the Licensed Work in violation of this License will automatically
        terminate your rights under this License for the current and all other
        versions of the Licensed Work.
        
        This License does not grant you any right in any trademark or logo of
        Licensor or its affiliates (provided that you may use a trademark or logo of
        Licensor as expressly required by this License).
        
        TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
        AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
        EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
        MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
        TITLE.
        
        MariaDB hereby grants you permission to use this License's text to license
        your works, and to refer to it using the trademark "Business Source License",
        as long as you comply with the Covenants of Licensor below.
        
        Covenants of Licensor
        
        In consideration of the right to use this License's text and the "Business
        Source License" name and trademark, Licensor covenants to MariaDB, and to all
        other recipients of the licensed work to be provided under this License:
        
        1. To specify as the Change License the GPL Version 2.0 or any later version,
           or a license that is compatible with GPL Version 2.0 or a later version,
           where "compatible" means that software provided under the Change License can
           be included in a program with software provided under GPL Version 2.0 or a
           later version. Licensor may specify additional Change Licenses without
           limitation.
        
        2. To either: (a) specify an additional grant of rights to use that does not
           impose any additional restriction on the right granted in this License, as
           the Additional Use Grant; or (b) insert the text "None".
        
        3. To specify a Change Date.
        
        4. Not to modify this License in any other way.
        
Keywords: mcp,claude,knowledge-management,ai-tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]==1.27.0
Requires-Dist: click==8.3.1
Requires-Dist: pydantic==2.12.5
Requires-Dist: pdfplumber==0.11.9
Requires-Dist: python-docx==1.2.0
Requires-Dist: openpyxl==3.1.5
Requires-Dist: python-pptx==1.0.2
Requires-Dist: cryptography==46.0.7
Provides-Extra: dev
Requires-Dist: pytest==8.3.4; extra == "dev"
Requires-Dist: pytest-asyncio==1.3.0; extra == "dev"
Provides-Extra: pro
Requires-Dist: lancedb==0.30.2; extra == "pro"
Requires-Dist: sentence-transformers==5.5.0; extra == "pro"
Requires-Dist: pyarrow==24.0.0; extra == "pro"
Dynamic: license-file

# LoreDocs v0.1.7

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

> **Available on the Anthropic Marketplace.** Install directly from Claude, or via PyPI: `uvx loredocs`

## Quick Start

**Prerequisites:** [uv](https://docs.astral.sh/uv/getting-started/installation/) (fast Python package manager).

```bash
# 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 (including Cowork plugin setup), see [INSTALL.md](INSTALL.md).

## Using LoreDocs

### Claude Code (Terminal)

```bash
claude --plugin-dir /path/to/loredocs
```

Or inside an existing session:

```
/plugin add /path/to/loredocs
```

Once loaded, Claude has access to all 42 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.

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

## 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/Team tiers with configurable limits
- **Local-first**: SQLite database, no cloud dependency, zero API costs

## MCP Tools

LoreDocs provides 42 MCP tools 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 (9 tools)
| Tool | What it does |
|------|-------------|
| `vault_add_doc` | Add a new document to a vault |
| `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 (5 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) |

### Organization (5 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 |

### Context Injection (4 tools)
| Tool | What it does |
|------|-------------|
| `vault_inject` | Load specific documents into Claude's context |
| `vault_inject_by_tag` | Load all documents matching a tag |
| `vault_inject_summary` | Load a vault summary with doc titles and descriptions |
| `vault_prime` | Pre-load vault context into current session (convenience wrapper for vault_inject_summary) |

### Import/Export (3 tools)
| Tool | What it does |
|------|-------------|
| `vault_import_dir` | Import a directory of files into a vault |
| `vault_export` | Export a document to a file on disk |
| `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 (3 tools)
| Tool | What it does |
|------|-------------|
| `vault_tier_status` | Check current tier limits and usage |
| `vault_set_tier` | Set the active tier (free, pro, team) |
| `get_license_tier` | Check current tier and license key status |

### 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](https://github.com/labyrinth-analytics/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
every Claude surface you already use -- Code, Cowork, and Chat. Both store data locally in
SQLite. Neither sends anything to an external server.

## Requirements

- Python 3.10+
- macOS or Linux
- [uv](https://docs.astral.sh/uv/getting-started/installation/) package manager
- `mcp` and `pydantic` (auto-installed by `uv sync`)

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

## CLI Reference

After `pip install loredocs` (or `uv sync`), the `loredocs-cli` command is available:

```bash
# List all vaults
loredocs-cli vault list

# Create a vault
loredocs-cli vault create "My Project Docs" --desc "Architecture and specs"

# Show vault details and document list
loredocs-cli vault info "My Project Docs"

# Archive / restore a vault
loredocs-cli vault archive "Old Docs"
loredocs-cli vault restore "Old Docs"

# Add a document from a file
loredocs-cli doc add "My Project Docs" "Architecture Overview" --file docs/architecture.md

# Add a document from stdin
echo "# Quick Note" | loredocs-cli doc add "My Project Docs" "Quick Note" --stdin

# Update a document
loredocs-cli doc update <doc-id> --name "New Title" --priority authoritative

# Delete a document
loredocs-cli doc delete <doc-id>

# Search documents across all vaults
loredocs-cli search "architecture"

# Full help
loredocs-cli --help
loredocs-cli vault --help
loredocs-cli doc --help
```

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

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

## 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](LICENSE) for details.
