joshylchen/zettelkasten

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