Zettel Memory

v0.0.1 - Local-first persistent memory MCP server

로컬 퍼시스턴트 메모리를 MCP 서버로 노출하여, Claude 등 MCP 호환 AI 에이전트가 당신의 지식 베이스를 활용할 수 있게 합니다.

✨ Features

• 📝 Markdown + YAML Front Matter - 표준 포맷으로 노트 저장

• 🗂️ PARA Organization - Projects/Areas/Resources/Archives 분류

• 🔗 Zettelkasten Linking - UID 기반 노트 연결 및 백링크

• 🔍 SQLite FTS5 Search - 빠른 전문 검색 (P95 < 1ms)

• 🤖 AI-Powered Organization - Ollama 통합으로 자동 노트 정리

• 🏠 Local-first - 모든 데이터를 로컬에 안전하게 보관

• 🔐 Privacy - 네트워크 송출 없음, 원자적 쓰기

🚀 Quick Start

Installation

Or use with npx:

Claude Desktop Setup

Add to your Claude Desktop config (~/.config/claude/claude_desktop_config.json):

Create a Test Note

📚 Available Tools (v0.0.1)

Zettel Memory provides 14 MCP tools for complete note management:

Core CRUD Tools

create_note

Create a new Markdown note with Front Matter.

Input:

Output: Note ID (UID), file path, and metadata

read_note

Read a note by its unique ID.

Input:

Options:

• includeMetadata: Add file size, word count, character count

• includeLinks: Add backlink analysis and broken link detection

Output: Full note content with metadata

list_notes

List notes with filtering, sorting, and pagination.

Input:

Filters (all optional):

• category: Filter by PARA category (Projects/Areas/Resources/Archives)

• tags: Filter by tags (OR logic - matches any tag)

• project: Filter by project name

Sorting:

• sortBy: created, updated, or title

• sortOrder: asc or desc

Pagination:

• limit: Max results (default 100, max 1000)

• offset: Skip first N results

Output: List of notes with metadata, total count, and pagination info

search_memory

Full-text search powered by SQLite FTS5.

Input:

Features:

• FTS5 full-text search with ranking

• Category and tag filtering

• Performance metrics (search time, result count)

• Snippet generation with query highlighting

Output: Ranked search results with snippets, scores, and metadata

update_note

Update an existing note's title, content, metadata, or links.

Input:

Features:

• Partial updates (only provide fields you want to change)

• Auto-updates updated timestamp

• Syncs with search index automatically

• At least one field required (besides uid)

Output: Updated note metadata and list of modified fields

delete_note

Delete a note permanently (requires explicit confirmation).

Input:

Safety:

• confirm: true required to prevent accidental deletion

• Returns note info before deletion

• Removes from search index automatically

• ⚠️ Cannot be undone

Output: Deleted note information with confirmation

Analytics & Organization Tools

• get_vault_stats - Get statistics about your vault (note count, categories, tags)

• get_backlinks - Find all notes linking to a specific note

• get_metrics - Get performance metrics (JSON or Prometheus format)

• find_orphan_notes - Find notes without any incoming or outgoing links

• find_stale_notes - Find notes that haven't been updated recently

• get_organization_health - Get overall health score and recommendations

• archive_notes - Batch archive old or unused notes

• suggest_links - Get AI-powered link suggestions based on content similarity

🗂️ Note Structure

Each note follows this structure:

File naming: {sanitized-title}-{uid}.md

• Example: my-project-notes-20250101T120000Z.md

🛠️ Development

Prerequisites

• Node.js 18+

• npm 8+

Setup

Project Structure

Running Locally

Direct Execution (Recommended):

Subcommand (Backward Compatible):

Healthcheck:

Available Options:

📖 Documentation

• docs/ROADMAP.md - Epic/feature tree structure

• docs/TECHNICAL_SPEC.md - Technical stack & KPIs

• docs/GOALS.md - Project goals & milestones

• docs/DEVELOPMENT_GUIDELINES.md - Development principles (SOLID, TDD, SDD)

• docs/VALIDATION_STRATEGY.md - Validation strategy and methodology

• docs/ARCHITECTURE.md - System architecture

• docs/USAGE_GUIDE.md - Usage guide and CLI reference

🗺️ Roadmap

v0.0.1 (Current) ✅

• Complete CRUD operations (create/read/update/delete/list/search)

• Markdown + Front Matter storage

• PARA categorization

• FTS5 full-text search with ranking

• Link analysis & backlinks

• CLI interface

• MCP server integration

• Test coverage: 498 tests passing

v0.1.0 (Next)

• Comprehensive unit tests (50%+ coverage)

• Performance benchmarks & KPI validation

• Zettelkasten link auto-suggestions

• File watcher for real-time sync

• Production error handling & logging

v1.0.0 (Future)

• Vector embedding search

• Olima Context-Aware Ranking Engine ⚠️ Planned Feature

  • Semantic similarity-based note recommendations

  • Session context-aware re-ranking

  • Automatic link suggestions based on content analysis

• Advanced link graph queries

• Docker image

• Production-ready CI/CD

Note on Olima: The "Olima" context-aware ranking engine is a planned feature for future releases. Currently, the project uses Ollama (local LLM platform) for AI-powered note organization via the organize_notes tool.

🤝 Contributing

Contributions are welcome! Please follow the guidelines below.

Development Workflow

1. Follow DEVELOPMENT_GUIDELINES.md

2. Write tests for new features

3. Ensure npm run build succeeds

4. Use Conventional Commits for commit messages

5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Model Context Protocol (MCP) - For the standardized protocol

• Zettelkasten - For the note-taking methodology

• PARA Method - For the organizational framework

📞 Support

• 🐛 Report a bug

• 💡 Request a feature

• 💬 Discussions

Status: 🚧 Alpha - Under active development

Note: This is an alpha release. APIs may change. Feedback and contributions are greatly appreciated!