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.
- 🔒 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
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
# 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# 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- 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
- 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
- Read-Only by Default: Safe exploration of your knowledge base
- Optional Writing: Enable
--unsafemode 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
- 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
# List all vault bookmarks
zk-chat bookmarks list
# Remove a bookmark
zk-chat bookmarks remove /path/to/vault# Check index health
zk-chat diagnose index
# Run test query to verify search
zk-chat diagnose index --query "test"# Register external tools
zk-chat mcp register figma stdio "figma-mcp"
# List and verify servers
zk-chat mcp list
zk-chat mcp verifyChoose 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.
# 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# 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"# Save current vault
zk-chat interactive --vault ~/notes --save
# List bookmarks
zk-chat bookmarks list
# Remove bookmark
zk-chat bookmarks remove ~/old-notes# Quick incremental update
zk-chat index update
# Full rebuild
zk-chat index update --full
# Check status
zk-chat index statusAsk natural questions about images in your vault:
- "What's in the diagram at architecture.png?"
- "Describe the chart in sales-data.jpg"
- "Extract text from screenshot.png"
--vault PATHor-v- Path to your Zettelkasten--gateway {ollama,openai}or-g- Choose AI provider--model NAMEor-m- Specify chat model--visual-model NAME- Specify visual analysis model--save- Bookmark the current vault--no-index- Skip indexing on startup (faster start)
--unsafe- Allow AI to create/edit files⚠️ --git- Enable git integration (recommended with --unsafe)--store-prompt/--no-store-prompt- Control system prompt storage--reset-memory- Clear smart memory
⚠️ Safety: The--unsafeflag allows AI to modify your notes. Always use with--gitfor tracking changes.
- Ollama installed and running
- Sufficient RAM for your chosen model (8GB minimum, 16GB+ recommended)
- Compatible with macOS (M1/M2/M3 recommended), Linux, and Windows
- OpenAI API key set in
OPENAI_API_KEYenvironment variable - Internet connection
- API credits
- Markdown notes (
.mdfiles) - Works with Obsidian, Logseq, or any markdown-based system
- Supports wikilinks (
[[Note Name]])
zk-chat uses a modern RAG architecture:
- Indexing: Creates vector embeddings of your notes using ChromaDB
- Retrieval: Semantic search finds relevant content for queries
- Generation: LLM generates responses using retrieved context
- Tools: AI can use 15+ tools to explore and interact with your vault
The AI agent has access to:
- Document search and retrieval
- Wikilink graph traversal
- Visual analysis (with vision models)
- Smart memory storage
- Git version control
- External tools via MCP servers
Create custom tools for your specific needs:
from zk_chat.services import ZkChatPlugin, ServiceProvider
class MyPlugin(ZkChatPlugin):
def __init__(self, service_provider: ServiceProvider):
super().__init__(service_provider)
def run(self, input_text: str) -> str:
# Access zk-chat services
fs = self.filesystem_gateway
zk = self.zettelkasten
llm = self.llm_broker
# Your plugin logic
return resultSee the Plugin Development Guide for complete documentation.
- Use smaller models (qwen3:1.5b, qwen2.5:3b)
- Increase concurrency:
export OLLAMA_NUM_PARALLEL=4 - Skip indexing on startup:
--no-index
- Use larger models (gpt-oss:20b, qwen3:14b)
- Increase context window:
export OLLAMA_NUM_CTX=16384 - Enable visual analysis for image-heavy vaults
# Check running models
ollama ps
# Monitor system resources
htop # or Activity Monitor on Mac
# Remove unused models
ollama list
ollama rm unused-modelzk-chat stores its data in your vault:
.zk_chat- Configuration file.zk_chat_db/- Vector database (ChromaDB)ZkSystemPrompt.md- System prompt (customizable)
Add these to .gitignore:
.zk_chat_db/
.zk_chat
# Start Ollama
ollama serve
# Verify model installed
ollama list# Diagnose index health
zk-chat diagnose index
# Force full rebuild
zk-chat index update --full- Try a smaller model
- Close other applications
- Increase system resources
- Use OpenAI instead of local models
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
MIT License - Copyright (c) 2024-2025 Stacey Vetzal
- Documentation: https://vetzal.com/zk-chat/
- PyPI: https://pypi.org/project/zk-chat/
- GitHub: https://github.com/svetzal/zk-chat
- Issues: https://github.com/svetzal/zk-chat/issues
- Discussions: https://github.com/svetzal/zk-chat/discussions
If you find zk-chat useful, please consider starring the repository on GitHub!
Made with ❤️ for the Zettelkasten community
This project uses Ruff for linting and auto-fixes (including removing unused imports/variables and sorting imports).
python -m pip install -e ".[dev]"# Lint with Ruff (fails on errors; uses pyproject.toml configuration)
ruff check zk_chat# Apply safe fixes (remove unused imports/variables, sort imports, etc.)
ruff check zk_chat --fixOptional formatting (if desired):
# Ruff can also format code
ruff format zk_chatNotes:
- Line length is enforced at 120 characters via Ruff (
pyproject.toml). - CI runs Ruff in the validation workflow; Flake8 and Autoflake are no longer used.