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

npm install -g @inchankang/zettel-memory

Or use with npx:

npx @inchankang/zettel-memory --vault ~/my-vault

Claude Desktop Setup

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

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "@inchankang/zettel-memory",
        "--vault",
        "/Users/yourname/Documents/memory-vault"
      ]
    }
  }
}

Create a Test Note

# Create vault directory
mkdir -p ~/my-vault

# Create a sample note
cat > ~/my-vault/my-first-note-20250101T120000Z.md << 'EOF'
---
id: "20250101T120000Z"
title: "My First Note"
category: "Resources"
tags: ["getting-started"]
created: "2025-01-01T12:00:00Z"
updated: "2025-01-01T12:00:00Z"
links: []
---

# My First Note

This is my first note in Zettel Memory!

## What I can do

- Store knowledge in Markdown
- Link notes together
- Search through my notes
- Let Claude access my knowledge base
EOF

📚 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:

{
  "title": "My Note",
  "content": "Note content...",
  "category": "Resources",
  "tags": ["tag1", "tag2"],
  "project": "optional-project-name"
}

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

`read_note`

Read a note by its unique ID.

Input:

{
  "uid": "20250101T120000Z",
  "includeMetadata": false,
  "includeLinks": false
}

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:

{
  "category": "Projects",
  "tags": ["important"],
  "project": "my-project",
  "limit": 100,
  "offset": 0,
  "sortBy": "updated",
  "sortOrder": "desc"
}

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:

{
  "query": "zettelkasten method",
  "limit": 10,
  "category": "Resources",
  "tags": ["productivity"]
}

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:

{
  "uid": "20250101T120000Z",
  "title": "Updated Title",
  "content": "New content...",
  "category": "Projects",
  "tags": ["updated", "important"],
  "project": "new-project",
  "links": ["other-note-uid"]
}

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:

{
  "uid": "20250101T120000Z",
  "confirm": true
}

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:

---
id: "20250101T120000000000Z"  # Auto-generated UID (timestamp-based)
title: "Note Title"
category: "Resources"          # PARA: Projects|Areas|Resources|Archives
tags: ["tag1", "tag2"]        # Optional tags
project: "project-name"       # Optional project association
created: "2025-01-01T12:00:00Z"
updated: "2025-01-01T12:00:00Z"
links: ["other-note-uid"]     # Links to other notes
---

# Note Title

Your note content in Markdown...

## You can use

- Lists
- **Bold** and *italic*
- [Links](https://example.com)
- [[other-note-uid]] (Zettelkasten-style links)

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

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

🛠️ Development

Prerequisites

Node.js 18+
npm 8+

Setup

# Clone the repository
git clone https://github.com/inchankang/zettel-memory.git
cd zettel-memory

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

Project Structure

zettel-memory/
├── packages/
│   ├── mcp-server/      # MCP server & CLI
│   ├── storage-md/      # Markdown storage & Front Matter
│   ├── index-search/    # FTS5 search & link graph
│   ├── assoc-engine/    # Context-aware ranking (planned for v0.1.0+)
│   └── common/          # Shared utilities & types
└── docs/                # Documentation & specs

Running Locally

Direct Execution (Recommended):

# ✅ Root-level options (Claude Desktop compatible)
node packages/mcp-server/dist/cli.js --vault /tmp/test-vault --index /tmp/test-index.db

# Or with npm
npm start -- --vault /tmp/test-vault --index /tmp/test-index.db

# Using npx (if published)
npx @inchankang/zettel-memory --vault ~/my-vault --index ~/.memory-index.db

Subcommand (Backward Compatible):

# ⚠️ Still works but not recommended
node packages/mcp-server/dist/cli.js server --vault /tmp/test-vault

Healthcheck:

node packages/mcp-server/dist/cli.js healthcheck --vault /tmp/test-vault --index /tmp/test-index.db

Available Options:

--vault <path>      # Vault directory path (default: ./vault)
--index <path>      # Index database path (default: ./.memory-index.db)
--mode <mode>       # Mode: dev | prod (default: dev)
--timeout <ms>      # Tool execution timeout (default: 5000ms)
--retries <count>   # Tool execution retry count (default: 2)
--verbose           # Enable verbose logging
--help              # Show help
--version           # Show version

📖 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

Follow DEVELOPMENT_GUIDELINES.md
Write tests for new features
Ensure npm run build succeeds
Use Conventional Commits for commit messages
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

Status: 🚧 Alpha - Under active development

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

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

npm install -g @inchankang/zettel-memory

Or use with npx:

npx @inchankang/zettel-memory --vault ~/my-vault

Claude Desktop Setup

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

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": [
        "@inchankang/zettel-memory",
        "--vault",
        "/Users/yourname/Documents/memory-vault"
      ]
    }
  }
}

Create a Test Note

# Create vault directory
mkdir -p ~/my-vault

# Create a sample note
cat > ~/my-vault/my-first-note-20250101T120000Z.md << 'EOF'
---
id: "20250101T120000Z"
title: "My First Note"
category: "Resources"
tags: ["getting-started"]
created: "2025-01-01T12:00:00Z"
updated: "2025-01-01T12:00:00Z"
links: []
---

# My First Note

This is my first note in Zettel Memory!

## What I can do

- Store knowledge in Markdown
- Link notes together
- Search through my notes
- Let Claude access my knowledge base
EOF

📚 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:

{
  "title": "My Note",
  "content": "Note content...",
  "category": "Resources",
  "tags": ["tag1", "tag2"],
  "project": "optional-project-name"
}

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

`read_note`

Read a note by its unique ID.

Input:

{
  "uid": "20250101T120000Z",
  "includeMetadata": false,
  "includeLinks": false
}

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:

{
  "category": "Projects",
  "tags": ["important"],
  "project": "my-project",
  "limit": 100,
  "offset": 0,
  "sortBy": "updated",
  "sortOrder": "desc"
}

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:

{
  "query": "zettelkasten method",
  "limit": 10,
  "category": "Resources",
  "tags": ["productivity"]
}

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:

{
  "uid": "20250101T120000Z",
  "title": "Updated Title",
  "content": "New content...",
  "category": "Projects",
  "tags": ["updated", "important"],
  "project": "new-project",
  "links": ["other-note-uid"]
}

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:

{
  "uid": "20250101T120000Z",
  "confirm": true
}

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:

---
id: "20250101T120000000000Z"  # Auto-generated UID (timestamp-based)
title: "Note Title"
category: "Resources"          # PARA: Projects|Areas|Resources|Archives
tags: ["tag1", "tag2"]        # Optional tags
project: "project-name"       # Optional project association
created: "2025-01-01T12:00:00Z"
updated: "2025-01-01T12:00:00Z"
links: ["other-note-uid"]     # Links to other notes
---

# Note Title

Your note content in Markdown...

## You can use

- Lists
- **Bold** and *italic*
- [Links](https://example.com)
- [[other-note-uid]] (Zettelkasten-style links)

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

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

🛠️ Development

Prerequisites

Node.js 18+
npm 8+

Setup

# Clone the repository
git clone https://github.com/inchankang/zettel-memory.git
cd zettel-memory

# Install dependencies
npm install

# Build all packages
npm run build

# Run tests
npm test

# Type check
npm run typecheck

# Lint
npm run lint

Project Structure

zettel-memory/
├── packages/
│   ├── mcp-server/      # MCP server & CLI
│   ├── storage-md/      # Markdown storage & Front Matter
│   ├── index-search/    # FTS5 search & link graph
│   ├── assoc-engine/    # Context-aware ranking (planned for v0.1.0+)
│   └── common/          # Shared utilities & types
└── docs/                # Documentation & specs

Running Locally

Direct Execution (Recommended):

# ✅ Root-level options (Claude Desktop compatible)
node packages/mcp-server/dist/cli.js --vault /tmp/test-vault --index /tmp/test-index.db

# Or with npm
npm start -- --vault /tmp/test-vault --index /tmp/test-index.db

# Using npx (if published)
npx @inchankang/zettel-memory --vault ~/my-vault --index ~/.memory-index.db

Subcommand (Backward Compatible):

# ⚠️ Still works but not recommended
node packages/mcp-server/dist/cli.js server --vault /tmp/test-vault

Healthcheck:

node packages/mcp-server/dist/cli.js healthcheck --vault /tmp/test-vault --index /tmp/test-index.db

Available Options:

--vault <path>      # Vault directory path (default: ./vault)
--index <path>      # Index database path (default: ./.memory-index.db)
--mode <mode>       # Mode: dev | prod (default: dev)
--timeout <ms>      # Tool execution timeout (default: 5000ms)
--retries <count>   # Tool execution retry count (default: 2)
--verbose           # Enable verbose logging
--help              # Show help
--version           # Show version

📖 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

Follow DEVELOPMENT_GUIDELINES.md
Write tests for new features
Ensure npm run build succeeds
Use Conventional Commits for commit messages
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

Status: 🚧 Alpha - Under active development

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

Memory MCP Server

Zettel Memory

✨ Features

🚀 Quick Start

Installation

Claude Desktop Setup

Create a Test Note

📚 Available Tools (v0.0.1)

Core CRUD Tools

create_note

read_note

list_notes

search_memory

update_note

delete_note

Analytics & Organization Tools

🗂️ Note Structure

🛠️ Development

Prerequisites

Setup

Project Structure

Running Locally

📖 Documentation

🗺️ Roadmap

v0.0.1 (Current) ✅

v0.1.0 (Next)

v1.0.0 (Future)

🤝 Contributing

Development Workflow

📄 License

🙏 Acknowledgments

📞 Support

Zettel Memory

✨ Features

🚀 Quick Start

Installation

Claude Desktop Setup

Create a Test Note

📚 Available Tools (v0.0.1)

Core CRUD Tools

create_note

read_note

list_notes

search_memory

update_note

delete_note

Analytics & Organization Tools

🗂️ Note Structure

🛠️ Development

Prerequisites

Setup

Project Structure

Running Locally

📖 Documentation

🗺️ Roadmap

v0.0.1 (Current) ✅

v0.1.0 (Next)

v1.0.0 (Future)

🤝 Contributing

Development Workflow

📄 License

🙏 Acknowledgments

📞 Support

`create_note`

`read_note`

`list_notes`

`search_memory`

`update_note`

`delete_note`

`create_note`

`read_note`

`list_notes`

`search_memory`

`update_note`

`delete_note`