🧠 Zettelkasten AI Assistant

A comprehensive, AI-powered Zettelkasten (slip-box) knowledge management system that helps you capture, refine, and connect atomic ideas. Built with modern Python and designed for both personal use and integration with AI systems via the Model Context Protocol (MCP).

Created by JoshChen

🎯 Problem & Solution Scope

The Knowledge Management Challenge

Managing knowledge effectively is hard when our brains are constrained by limited working memory and high cognitive load. Traditional note-taking or Zettelkasten tools often become just dumping grounds for information, adding extraneous cognitive load (effort spent managing the tool itself) on top of the intrinsic load (the difficulty of the content). This leaves little room for germane load – the actual learning and schema-building that leads to understanding. The result is lots of notes but little insight, as the user is overwhelmed by organizing mechanics instead of focusing on knowledge processing.

Our Solution: An Active Conversational Partner

Zettelkasten LLM Assistant is designed as an active conversational partner rather than a passive note archive. It guides the user through capturing ideas, refining them (using the Feynman Technique), and integrating them into a knowledge network. By doing so, it:

Reduces extraneous load: The system automates organizing, linking, and summarizing
Maximizes germane load: Users spend effort on understanding and explaining concepts
Acts as a Socratic partner: The LLM plays a curious 12-year-old student, prompting clarity through questions
Transforms tacit to explicit knowledge: Converts intuitive understanding into clear, shareable notes
Builds your "second brain": Creates an external cognitive system that enhances your thinking

This approach shifts the cognitive burden from tool management to knowledge processing, enabling deeper learning and insight generation.

🎯 Core Philosophy

This system implements the Zettelkasten method digitally with AI assistance:

Atomic Notes: One idea per note, uniquely identified and timestamped
Bi-directional Linking: Typed relationships between notes create a knowledge graph
AI-Enhanced Workflow: Optional LLM assistance for refinement, summarization, and connections
Future-Proof Storage: Plain Markdown files with YAML frontmatter as the source of truth
MCP Integration: Expose your knowledge base to AI assistants and agents

✨ Key Features

📝 Note Management

Atomic Notes: Each note contains a single concept with unique ID, title, body, and summary
Smart Summaries: AI-generated summaries (280 char limit) for quick scanning
YAML Frontmatter: Rich metadata including tags, links, status, and timestamps
Multiple Interfaces: CLI, Web API, Streamlit UI, and MCP tools

🔍 Advanced Search

Full-Text Search: SQLite FTS5 searches across titles, bodies, and summaries
Semantic Queries: Support for proximity search (NEAR/N), phrase matching
Tag Filtering: Combine text search with tag-based filtering
Snippet Highlights: Search results show highlighted matching text

🤖 AI-Powered Workflows

CEQRC Pipeline: Capture → Explain → Question → Refine → Connect
Auto-Summarization: Generate concise summaries with configurable length limits
Metadata Suggestions: AI suggests better titles, tags, and relationships
Link Discovery: Automatic suggestion of connections between related notes

🌐 Multiple Interfaces

FastAPI REST API: Full CRUD operations with OpenAPI documentation
CLI Tools: Command-line interface for power users and automation
Streamlit Web UI: User-friendly interface with real-time features
MCP Server: Expose tools to AI assistants and agents

🚀 Quick Start

Prerequisites

Python 3.11+
pip or conda

Installation

# 1) Clone the repository
git clone https://github.com/joshylchen/zettelkasten
cd zettelkasten

# 2) Create and activate virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# 3) Install dependencies
pip install -r requirements.txt

# 4) Configure environment
cp .env.example .env
# Edit .env with your preferences (API keys, paths, etc.)

# 5) Initialize data directories
mkdir -p data/notes data/db

Choose Your Interface

🌐 Web API (Recommended for integrations)

python -m zettelkasten.server.api
# Access at: http://127.0.0.1:8088/docs

🖥️ Streamlit UI (Best for interactive use)

streamlit run ui_streamlit.py
# Access at: http://localhost:8501

⌨️ Command Line

# Create your first note
python -m zettelkasten.cli new "Machine Learning" \
  -c "The field of study focused on algorithms that improve through experience" \
  -t ai,learning,algorithms

# Search your notes
python -m zettelkasten.cli search "machine learning"

# See all commands
python -m zettelkasten.cli --help

Your First Note

Using the Streamlit UI:

Open http://localhost:8501
Go to "Create / Edit" tab
Enter title: "My First Zettel"
Add content and let AI generate a summary
Add relevant tags
Click "Create"

🏗️ Architecture Overview

Storage Layer

data/
├── notes/           # Markdown files (source of truth)
│   ├── 20250915064516.md
│   └── 20250915064517.md
└── db/
    └── zettelkasten.db  # SQLite index + FTS

Note Structure:

---
id: '20250915064516'
title: 'Machine Learning Fundamentals'  
summary: 'Core concepts of ML including supervised, unsupervised learning and model evaluation techniques'
tags: [ai, learning, algorithms]
links: 
  - {to: '20250915064517', type: 'supports'}
created_at: '2025-09-15T06:45:16Z'
updated_at: '2025-09-15T06:45:50Z'
status: 'PERMANENT'
---

# Machine Learning Fundamentals

Machine learning is a subset of artificial intelligence...

System Components

graph TB
    UI[Streamlit UI] --> API[FastAPI REST API]
    CLI[CLI Tools] --> API
    MCP[MCP Server] --> API
    
    API --> WF[Workflow Engine<br/>CEQRC]
    API --> REPO[Note Repository<br/>Markdown Files]
    API --> DB[SQLite Database<br/>FTS5 Index]
    
    WF --> LLM[LLM Service<br/>OpenAI/Stub]
    WF --> META[Metadata Service]
    
    REPO <--> DB

Database Schema

zettel: Core note data (id, title, body, summary, timestamps)
tag: Tag definitions
zettel_tag: Note-tag relationships
link: Typed relationships between notes
zettel_fts: Full-text search index (FTS5)

CEQRC Workflow

Capture: Create seed notes with initial thoughts
Explain: Add detailed explanations and context
Question: AI generates probing questions (Feynman technique)
Refine: Improve content based on questions
Connect: Discover and create links to related notes

🔧 Configuration

Key environment variables in .env:

# Paths
ZK_NOTES_DIR=./data/notes
ZK_DB_PATH=./data/db/zettelkasten.db

# Server
ZK_HOST=127.0.0.1
ZK_PORT=8088

# AI Integration
OPENAI_API_KEY=your_key_here
ZK_LLM_PROVIDER=openai  # or 'stub' for testing

# Summary Settings  
ZK_SUMMARY_MAX_LENGTH=280

# UI
ZK_STREAMLIT_PORT=8501

📚 API Reference

Core Endpoints

Notes

POST /notes - Create note (auto-generates summary if not provided)
GET /notes/{id} - Retrieve note with all metadata
PUT /notes/{id} - Update note (regenerates summary if body changed)
DELETE /notes/{id} - Delete note and relationships

Search & Discovery

GET /search?q={query}&tag={tag} - Full-text search across title, body, summary
GET /notes/{id}/backlinks - Find notes linking to this one
POST /generate-summary - Generate AI summary for text

Workflows

POST /notes/{id}/ceqrc - Run complete CEQRC workflow
POST /notes/{id}/links - Create typed relationship

Links

POST /notes/{source}/links - Create relationship

{"target_id": "20250915064517", "type": "supports", "description": "optional"}

Link Types

supports / supported_by - Evidence or justification
refines / refined_by - More specific version
extends / extended_by - Builds upon concept
contradicts / contradicted_by - Opposing viewpoint
is_example_of / has_example - Concrete instance
related - General association

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=zettelkasten_assistant

# Run specific test file
pytest tests/test_notes.py

# Verbose output
pytest -v

Test coverage includes:

Note CRUD operations with summaries
Full-text search across all fields
API endpoint functionality
CEQRC workflow execution
Link relationship management

🤖 AI Integration

LLM Providers

OpenAI: Full AI features (requires API key)
Stub: Testing mode with deterministic responses

AI-Powered Features

Smart Summaries: Generate concise summaries within character limits
Metadata Suggestions: Improve titles, tags, and categorization
Content Refinement: Polish and improve note content
Link Discovery: Find relationships between notes
Feynman Probing: Generate questions to test understanding

MCP (Model Context Protocol) Integration

Expose your Zettelkasten to AI assistants like Claude Desktop:

Quick MCP Setup

python setup_mcp.py  # Automated setup and config generation

Available MCP Tools

zk_create_note: Create atomic notes with AI summaries
zk_search_notes: Full-text search with FTS5 syntax
zk_get_note: Retrieve notes with metadata and backlinks
zk_run_ceqrc_workflow: Execute AI-powered learning workflow
zk_suggest_links: Discover connections between notes
zk_create_link: Create typed relationships (supports, refines, extends, etc.)
zk_generate_summary: Generate AI summaries for any text

Claude Desktop Configuration

{
  "mcpServers": {
    "zettelkasten": {
      "command": "python", 
      "args": ["path/to/mcp_server.py"],
      "env": {"OPENAI_API_KEY": "your_key_here"}
    }
  }
}

See docs/MCP_SETUP.md for complete integration guide.

🎯 Use Cases

Research & Learning

Capture research findings as atomic notes
Build concept maps through typed links
Use AI to generate study questions
Create summary views of complex topics

Content Creation

Organize ideas for articles, books, courses
Track sources and evidence
Build argument structures through links
Generate outlines from connected notes

Knowledge Management

Personal wiki with AI assistance
Meeting notes with automatic summaries
Documentation with smart cross-references
Project knowledge base

AI Assistant Integration

Let ChatGPT/Claude access your knowledge base
Automated note creation from conversations
AI-powered content suggestions
Intelligent information retrieval

📖 Documentation

Document	Description
`docs/USER_GUIDE.md`	Complete user manual with examples
`docs/USE_CASES.md`	Real-world usage scenarios
`docs/DESIGN.md`	Architecture and design decisions
`docs/MCP_INTEGRATION.md`	AI assistant integration guide
`docs/SPECS.md`	Technical specifications and API reference

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Add tests for new functionality
Run the test suite (pytest)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🔗 Related Projects

Model Context Protocol - AI assistant integration
Obsidian - Popular note-taking with linking
Logseq - Block-based knowledge management
Roam Research - Networked thought

⚖️ License

MIT License - see LICENSE file for details.

Built with ❤️ for knowledge workers, researchers, and AI enthusiasts.

Zettelkasten