💬 zk-chat: AI-Powered Chat for Your Zettelkasten

Transform your Zettelkasten into an intelligent knowledge assistant. zk-chat lets you have natural conversations with your notes using AI—whether you run models locally with Ollama or use OpenAI's cloud API.

🎯 Why zk-chat?

• 🔒 Privacy First: Run everything locally with Ollama—no data leaves your machine
• 🤖 AI-Powered RAG: Semantic search with vector embeddings finds exactly what you need
• 📊 Visual Analysis: Analyze diagrams, charts, and images in your notes
• 🔗 Graph Traversal: Discover connections through wikilinks, backlinks, and forward links
• 🧠 Smart Memory: AI remembers context across conversations
• 🔌 Extensible: MCP server support and plugin architecture
• ⚡ Fast: Efficient local indexing and incremental updates
• 💻 CLI & GUI: Choose your interface—powerful command-line or experimental GUI

📚 Documentation

Full documentation: https://vetzal.com/zk-chat/

• Installation Guide - Get started in minutes
• Quick Start Tutorial - Your first conversation
• Model Selection Guide - Choose the right model for your hardware
• Command Reference - Complete CLI documentation
• Plugin Development - Extend zk-chat with custom tools

🚀 Quick Start

Installation

# Install with pipx (recommended)
pipx install zk-chat

# Install Ollama and a model
brew install ollama
ollama pull qwen3:8b

# For visual analysis (optional)
ollama pull gemma3:27b

Your First Chat

# Start interactive session
zk-chat interactive --vault /path/to/your/notes

# Ask a question
zk-chat query "What are my main ideas about productivity?"

# Single query with visual model
zk-chat query "Analyze diagram.png" --visual-model gemma3:27b

✨ Key Features

🔍 Intelligent Search & Retrieval

• Semantic Search: Vector embeddings find conceptually similar content
• Excerpt Retrieval: Extract relevant passages from your documents
• Full Document Access: AI can read complete notes when needed
• Graph Traversal: Explore connections via wikilinks, backlinks, and forward links
• Link Path Finding: Discover how concepts connect through your knowledge graph

🤖 AI Capabilities

• RAG (Retrieval Augmented Generation): AI answers using your actual notes
• Smart Memory: Persistent context across conversations
• Visual Analysis: Understand diagrams, charts, and images
• Multi-Model Support: Choose from dozens of Ollama models or use OpenAI
• Autonomous Agent Mode: AI can plan and execute complex multi-step tasks

🛠️ Content Management

• Read-Only by Default: Safe exploration of your knowledge base
• Optional Writing: Enable --unsafe mode for AI-assisted content creation
• Git Integration: Track all AI changes with automatic commits
• Wikilink Support: Full understanding of [[wikilink]] syntax
• Markdown Native: Works seamlessly with Obsidian and other markdown tools

🔌 Extensibility

• MCP Server Support: Connect external tools via Model Context Protocol
• Plugin Architecture: Extend with custom Python plugins
• Available Plugins:
  • Wikipedia Integration - Research and create notes from Wikipedia
  • Image Generation - Generate images with Stable Diffusion 3.5

📦 What's New in v3.5.0

🔖 Bookmark Management

# List all vault bookmarks
zk-chat bookmarks list

# Remove a bookmark
zk-chat bookmarks remove /path/to/vault

🔍 Index Diagnostics

# Check index health
zk-chat diagnose index

# Run test query to verify search
zk-chat diagnose index --query "test"

🔌 MCP Server Integration

# Register external tools
zk-chat mcp register figma stdio "figma-mcp"

# List and verify servers
zk-chat mcp list
zk-chat mcp verify

🤖 Updated Model Recommendations (2025)

Choose based on your RAM:

RAM Available	Text Model	Visual Model
64GB+	gpt-oss:120b, qwen3:32b	gemma3:27b
36-48GB	gpt-oss:20b, qwen3:14b	gemma3:27b
16-32GB	qwen3:8b, qwen2.5:7b	gemma3:9b
8-16GB	qwen3:1.5b, qwen2.5:3b	gemma3:2b

See the Model Selection Guide for detailed recommendations by task and hardware.

💡 Usage Examples

Interactive Chat

# Start a conversation
zk-chat interactive

# With specific model
zk-chat interactive --model qwen3:14b

# Allow AI to edit files (with git tracking)
zk-chat interactive --unsafe --git

# With visual analysis
zk-chat interactive --visual-model gemma3:27b

Single Queries

# Direct question
zk-chat query "What are my thoughts on AI?"

# From file or stdin
cat question.txt | zk-chat query

# Complex multi-step query
zk-chat query "Find all notes about productivity and create a summary"

Bookmark Management

# Save current vault
zk-chat interactive --vault ~/notes --save

# List bookmarks
zk-chat bookmarks list

# Remove bookmark
zk-chat bookmarks remove ~/old-notes

Index Management

# Quick incremental update
zk-chat index update

# Full rebuild
zk-chat index update --full

# Check status
zk-chat index status

This is the beginning of the README. Read the rest at the original. Read the full README ↗