CLI for Thallograph knowledge management system with graph-RAG
npm install @thallograph/twig> Knowledge management system with graph-RAG for markdown notes
twig is a command-line tool for managing markdown-based knowledge bases with semantic search, wiki-link graph traversal, and tag-based organization powered by local embeddings via Ollama.
- π Semantic search across markdown files using vector embeddings
- πΈοΈ Wiki-link graph traversal for discovering connected knowledge
- π·οΈ Tag-based organization with automatic tag extraction
- π€ Ollama-powered embeddings using nomic-embed-text (local, private)
- π Link analysis and broken link detection
- β‘ Fast local database with PGlite (PostgreSQL in-process)
- π Real-time sync with file watching
- π Graph-RAG combining vector similarity, keyword search, and graph proximity
- π MCP Server for AI assistant integration (Claude Desktop, Cline, Continue, etc.)
- Bun 1.3.3 or higher (install)
- Ollama with nomic-embed-text model (install)
``bashInstall Ollama (macOS/Linux)
curl -fsSL https://ollama.ai/install.sh | sh
Installation
`bash
npm install -g @thallograph/twig
or
bun install -g @thallograph/twig
`Quick Start
`bash
Navigate to your markdown notes directory
cd ~/notesInitialize Thallograph project
twig initSync markdown files (generates embeddings, extracts links and tags)
twig syncQuery your knowledge base
twig query "How do I configure embeddings?"Check system health
twig doctor
`Commands
$3
####
twig init [directory]Initialize Thallograph project in current or specified directory.
Options:
-
--force - Overwrite existing .thallograph directory
- --skip-ollama-check - Skip Ollama validation (for CI/CD)Example:
`bash
twig init
twig init ~/my-notes --force
`####
twig doctorValidate environment and dependencies: Ollama service, database, migrations, and runtime.
Example:
`bash
twig doctor
`$3
####
twig sync [options]Sync markdown files to database: extract links, tags, and generate embeddings.
Options:
-
--no-embeddings - Skip embedding generation (faster, links/tags only)
- --dry-run - Show what would be synced without making changes
- --watch - Continuous sync mode (monitors file changes)
- --concurrency - File processing concurrency (default: 10)Examples:
`bash
Full sync with embeddings
twig syncQuick sync without embeddings
twig sync --no-embeddingsWatch mode for continuous updates
twig sync --watch
`$3
####
twig query Retrieve relevant context using Graph-RAG: hybrid search with vector similarity, full-text, and graph traversal.
Options:
-
--max-docs - Maximum documents to return (default: 20)
- --depth - Graph traversal depth (default: 2)
- --semantic-weight - Semantic search weight (default: 0.4)
- --keyword-weight - Keyword search weight (default: 0.3)
- --graph-weight - Graph proximity weight (default: 0.2)
- --min-score - Minimum relevance score (default: 0.3)
- --json - Output JSON format for scriptingExamples:
`bash
Interactive query
twig query "How to configure embeddings?"JSON output for scripting
twig query "setup instructions" --jsonAdjust scoring weights
twig query "architecture" --semantic-weight 0.6 --graph-weight 0.3
`$3
####
twig links list [options]List all wiki-links in the project.
Options:
-
--broken - Show only broken links
- --ambiguous - Show only ambiguous links (multiple targets)
- --file - Filter by source file
- --json - Output JSON formatExample:
`bash
twig links list --broken
`####
twig links statsDisplay link statistics and graph metrics.
Example:
`bash
twig links stats
`$3
####
twig tags listList all tags in the project with document counts.
Example:
`bash
twig tags list
`####
twig tags show Show all documents with a specific tag.
Example:
`bash
twig tags show "#architecture"
`$3
####
twig db migrateRun pending database migrations.
Example:
`bash
twig db migrate
`####
twig db resetReset database (WARNING: destroys all data).
Options:
-
--force - Skip confirmation promptExample:
`bash
twig db reset --force
`$3
####
twig embeddings generate [options]Generate embeddings for documents.
Options:
-
--force - Regenerate embeddings for all documents (even if already generated)
- --file - Generate embeddings for specific file onlyExample:
`bash
Generate missing embeddings
twig embeddings generateRegenerate all embeddings
twig embeddings generate --force
`####
twig embeddings statsDisplay embedding generation statistics.
Example:
`bash
twig embeddings stats
`$3
####
twig mcp serve [options]Start the MCP server for AI assistant integration. Exposes your knowledge base via the Model Context Protocol, enabling AI assistants like Claude Desktop, Cline, and Continue to query your notes.
Options:
-
--project-dir - Thallograph project directory (default: current directory)Example:
`bash
Start MCP server
twig mcp serveStart with specific project
twig mcp serve --project-dir ~/my-notes
`Claude Desktop Configuration:
Add to
~/Library/Application Support/Claude/claude_desktop_config.json:`json
{
"mcpServers": {
"thallograph": {
"command": "twig",
"args": ["mcp", "serve", "--project-dir", "/path/to/your/notes"]
}
}
}
`Cline Configuration:
Add to VS Code settings (
.vscode/settings.json or user settings):`json
{
"cline.mcpServers": {
"thallograph": {
"command": "twig",
"args": ["mcp", "serve", "--project-dir", "/path/to/your/notes"]
}
}
}
`The MCP server provides two tools to AI assistants:
- query_knowledge_base: Semantic search with graph-RAG
- get_document: Retrieve full document content by path
$3
####
twig config get Get configuration value.
Example:
`bash
twig config get embeddings.model
`####
twig config set Set configuration value.
Example:
`bash
twig config set embeddings.model "nomic-embed-text"
`Configuration File
Thallograph uses
.thallograph/config.json for configuration:`json
{
"embeddings": {
"model": "nomic-embed-text",
"baseUrl": "http://localhost:11434",
"dimensions": 768
},
"sync": {
"concurrency": 10,
"includePatterns": ["*/.md"],
"excludePatterns": ["node_modules/", ".git/"]
},
"retrieval": {
"maxDocs": 20,
"traversalDepth": 2,
"semanticWeight": 0.4,
"keywordWeight": 0.3,
"graphWeight": 0.2,
"bm25Weight": 0.1
}
}
`Project Structure
`
your-notes/
βββ .thallograph/ # Thallograph project directory
β βββ db/ # PGlite database
β βββ config.json # Configuration
βββ docs/ # Your markdown files
βββ notes/
βββ *.md
`Troubleshooting
$3
Ensure Ollama is running:
`bash
ollama serve
`$3
Pull the embedding model:
`bash
ollama pull nomic-embed-text
`$3
Reset and reinitialize:
`bash
twig db reset --force
twig init
``This software is licensed under the PolyForm Shield License 1.0.0.
Required Notice: Copyright 2026 Craft Effect LLC (https://github.com/thallograph/twig)
See the LICENSE file for complete terms, or visit:
https://polyformproject.org/licenses/shield/1.0.0
- β
You can use this software for any purpose
- β
You can modify and distribute it
- β You cannot use it to compete with Thallograph or Craft Effect LLC products
- β No liability or warranty provided
See the Noncompete section in the license for full details.
See GitHub repository for source code and issue tracking.
- Documentation: https://github.com/thallograph/twig
- Issues: https://github.com/thallograph/twig/issues