Twig CLI

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

Features

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

Prerequisites

- Bun 1.3.3 or higher (install)
- Ollama with nomic-embed-text model (install)

$3

``bash


Install Ollama (macOS/Linux)

curl -fsSL https://ollama.ai/install.sh | sh

Start Ollama service

ollama serve

Pull the embedding model

ollama pull nomic-embed-text
`

Installation

`bash
npm install -g @thallograph/twig


or


bun install -g @thallograph/twig
`

Quick Start

`bash


Navigate to your markdown notes directory

cd ~/notes

Initialize Thallograph project

twig init

Sync markdown files (generates embeddings, extracts links and tags)

twig sync

Query 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 doctor

Validate 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 sync

Quick sync without embeddings

twig sync --no-embeddings

Watch mode for continuous updates

twig sync --watch
`

$3

#### twig query [options]

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 scripting

Examples:
`bash


Interactive query

twig query "How to configure embeddings?"

JSON output for scripting

twig query "setup instructions" --json

Adjust 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 format

Example:
`bash
twig links list --broken
`

#### twig links stats

Display link statistics and graph metrics.

Example:
`bash
twig links stats
`

$3

#### twig tags list

List 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 migrate

Run pending database migrations.

Example:
`bash
twig db migrate
`

#### twig db reset

Reset database (WARNING: destroys all data).

Options:
- --force - Skip confirmation prompt

Example:
`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 only

Example:
`bash


Generate missing embeddings

twig embeddings generate

Regenerate all embeddings

twig embeddings generate --force
`

#### twig embeddings stats

Display 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 serve

Start 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
``

License

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

$3

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

Contributing

See GitHub repository for source code and issue tracking.

Support

- Documentation: https://github.com/thallograph/twig
- Issues: https://github.com/thallograph/twig/issues