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

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!