ztlctl 1.6.0

ZettelControl — CLI utility for managing a Zettelkasten note-taking system

ZettelControl (ztlctl)

ZettelControl (ztlctl) is a local knowledge operating system for human users and AI agents. It separates agent-assisted capture and synthesis from human-led enrichment, so research capture, durable notes, and garden work can coexist without sharing the same workflow.

ztlctl manages durable knowledge artifacts as structured markdown files backed by a SQLite index and a weighted knowledge graph. Operational state such as sessions, logs, generated self/ documents, and event dispatch is internal and rebuildable rather than part of the file-first durability contract.

Installation

pip install ztlctl

Or with uv:

uv tool install ztlctl

Optional extras: pip install ztlctl[mcp] (MCP server), pip install ztlctl[semantic] (vector search), pip install ztlctl[community] (advanced graph algorithms).

See the Installation Guide for details.

Quick Start

# 1. Initialize a new vault
ztlctl init my-vault --topics "python,architecture,devops"

# 2. Enter the vault directory
cd my-vault

# 3. Start a research session
ztlctl agent session start "Learning Python async patterns"

# 4. Create notes as you learn
ztlctl create note "Asyncio Event Loop" --tags "lang/python,concept/concurrency"
ztlctl create note "Async vs Threading" --tags "lang/python,concept/concurrency"

# 5. Create references to external sources
ztlctl create reference "Python asyncio docs" --url "https://docs.python.org/3/library/asyncio.html"

# 6. Track tasks that emerge
ztlctl create task "Refactor API to use async" --priority high --impact high

# 7. Let the graph grow — reweave discovers connections
ztlctl reweave --auto-link-related

# 8. Search your knowledge
ztlctl query search "async patterns" --rank-by relevance

# 9. Build a topic packet and draft from it
ztlctl query packet --topic architecture --mode review
ztlctl query draft --topic architecture --target note

# 10. Close the session when done
ztlctl agent session close --summary "Mapped async patterns, identified refactoring task"

Features

• Two explicit working layers: capture/synthesis for agent-assisted research and enrichment for garden work (Knowledge Paradigms)
• File-first durable artifacts for notes, references, and tasks, with rebuildable indexes and operational state (Core Concepts)
• Knowledge graph with 4-signal reweave scoring (BM25, tag overlap, graph proximity, topic match) for automated link discovery (Tutorial)
• Session-based agentic workflows with token-budgeted 5-layer context assembly (Agentic Workflows)
• Digital garden maturity tracking — seed, budding, and evergreen stages (Knowledge Paradigms)
• Text-first ingestion for raw text, markdown files, and provider-backed URL capture (Command Reference)
• Durable source bundles for agent-fetched web and multimodal captures, persisted beside ingested references for later packet/export reuse (Agentic Workflows)
• Full-text + semantic search with BM25/vector hybrid ranking, explainable review/garden modes, and topic packets (Command Reference)
• Conversational enrichment workflows with packet-to-draft note/task/decision generation (Agentic Workflows)
• Dashboard and dossier export for review queues, garden backlog, and topic workbenches (Tutorial)
• MCP server with discovery-first tooling, portable prompts, capture-spec resources, and exported client assets for AI integration (MCP Server)
• Generated Claude and Codex workflow assets via ztlctl workflow export for portable agent setup
• Export to markdown, indexes, graph formats, and dashboard artifacts (Tutorial)
• Plugin system via pluggy event bus with built-in git integration (Development)
• Structured JSON output on every command for scripting and agent consumption (--json flag)
• Vault integrity checking, auto-fix, full rebuild, and rollback (Troubleshooting)

Documentation

Guide	Description
Installation	Install via pip/uv, optional extras
Quick Start	Your first vault in 9 commands
Tutorial	Step-by-step vault building guide
Core Concepts	Content types, lifecycle, vault structure, graph
Command Reference	All CLI commands, options, and filters
Configuration	ztlctl.toml settings and environment variables
Agentic Workflows	Sessions, context assembly, batch, scripting
Knowledge Paradigms	Capture/synthesis and enrichment, mapped to note-taking paradigms
MCP Server	Model Context Protocol integration
Development	Contributing, architecture, local setup
Troubleshooting	Common issues and solutions

Full documentation is also available at thatdevstudio.github.io/ztlctl.

Architecture

ztlctl follows a strict 6-layer package structure where dependencies flow downward:

src/ztlctl/
├── domain/          # Types, enums, lifecycle rules, ID patterns
├── infrastructure/  # SQLite/SQLAlchemy, NetworkX graph, filesystem
├── config/          # Pydantic config models, TOML discovery
├── services/        # Business logic (create, query, graph, reweave, ...)
├── output/          # Rich/JSON formatters
├── commands/        # Click CLI commands
├── plugins/         # Pluggy hook specs and built-in plugins
├── mcp/             # MCP server adapter
└── templates/       # Jinja2 templates for content creation

See Development for details and DESIGN.md for the complete internal design specification.

Contributing

This project uses conventional commits. See CONTRIBUTING.md for the full guide.

1. Branch from develop: git checkout -b feature/<name> develop
2. Make changes and commit with conventional messages
3. Open a PR targeting develop
4. Releases are automated when version-bumping commits (feat:, fix:) merge to develop

Community

• Code of Conduct
• Security Policy
• Support

License

MIT