convez.ai
MCP ServerProdutividadeIntermediário
labyrinth-analytics

LoreDocs

labyrinth-analytics/loredocs

Base de conhecimento searchable para seus projetos com Claude

Ver no GitHub
InicialPluginScore · de 0 a 100

Base de conhecimento persistente e pesquisável para projetos de IA, integrada ao Claude via MCP server. Organiza documentação, especificações e decisões arquiteturais em vaults versionados, permitindo que Claude mantenha contexto entre sessões sem perder informações.

Instalação

$npx convez-ai labyrinth-analytics/loredocs

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 6 dias
Versão
—
Issues abertas
0
Contribuidores
5

Casos de uso

  • Manter documentação de projeto acessível ao Claude entre sessões
  • Organizar specs, guias arquiteturais e decisões técnicas em vaults
  • Buscar e injetar contexto de projeto automaticamente em conversas

Veredito

Ferramenta sólida para persistência de conhecimento em fluxos com Claude, resolvendo o problema real de contexto perdido entre sessões. Implementação bem pensada com fallback automático e integração MCP nativa, embora requeira configuração inicial e compreensão de vaults.

README

A tradução para o português deste README ainda está na fila.

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 (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 (including Cowork plugin setup), see INSTALL.md.

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

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

ToolWhat it does
vault_createCreate a new vault with name and description
vault_listList all vaults with doc counts and sizes
vault_infoGet detailed vault information
vault_archiveArchive a vault (preserves data, hides from listing)
vault_deletePermanently delete a vault and all its documents
vault_link_projectLink a vault to a project directory
vault_open_workspaceOpen or create the vault scoped to a directory path
loredocs_onboardSet up workspace with starter vaults on first install

Document Operations (9 tools)

ToolWhat it does
vault_add_docAdd a new document to a vault
vault_update_docUpdate document content (creates version history)
vault_remove_docRemove a document from a vault
vault_get_docRetrieve a document with full content
vault_list_docsList documents in a vault with filtering and sorting
vault_copy_docCopy a document to another vault
vault_move_docMove a document to another vault
vault_doc_historyView version history of a document
vault_doc_restoreRestore a document to a previous version

Search and Discovery (5 tools)

ToolWhat it does
vault_searchFull-text search across all vaults
vault_search_by_tagFind documents by tag across all vaults
vault_find_relatedDiscover documents related to a given doc (Pro only)
vault_suggestProactive suggestions for relevant docs to load
vault_rebuild_indexRebuild the LanceDB semantic search index (Pro only; run once after installing Pro deps)

Organization (5 tools)

ToolWhat it does
vault_tag_docAdd tags to a document
vault_bulk_tagTag multiple documents at once
vault_categorizeSet document category (spec, guide, decision, etc.)
vault_set_prioritySet document priority level
vault_add_noteAdd a note or annotation to a document

Context Injection (4 tools)

ToolWhat it does
vault_injectLoad specific documents into Claude's context
vault_inject_by_tagLoad all documents matching a tag
vault_inject_summaryLoad a vault summary with doc titles and descriptions
vault_primePre-load vault context into current session (convenience wrapper for vault_inject_summary)

Import/Export (3 tools)

ToolWhat it does
vault_import_dirImport a directory of files into a vault
vault_exportExport a document to a file on disk
vault_export_manifestExport vault metadata as a JSON manifest

Document Links (2 tools)

ToolWhat it does
vault_link_docCreate a link between two documents
vault_unlink_docRemove a link between documents

Administration (3 tools)

ToolWhat it does
vault_tier_statusCheck current tier limits and usage
vault_set_tierSet the active tier (free, pro, team)
get_license_tierCheck current tier and license key status

Cross-product Session Links (3 tools, Pro)

ToolWhat it does
vault_link_sessionCreate a manual link from a LoreConvo session to a LoreDocs document
vault_get_session_linksReturn LoreConvo sessions linked to a LoreDocs document
vault_get_linked_sessionsReturn 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 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 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:

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

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

Ver o original no GitHub

Bom para

Relacionados