Kaydet — Capture • Query • Remember

Your queryable personal database. Plain text storage, SQLite search, zero friction.

Kaydet is not a diary you read—it's a database you query. Capture thoughts, track work, log life—all from your terminal, in plain text.

Install

pip install git+https://github.com/miratcan/kaydet.git

Or with MCP support for AI integration:

pip install "git+https://github.com/miratcan/kaydet.git#egg=kaydet[mcp]"

The kaydet-mcp command is always installed, but requires the [mcp] extra to run (otherwise it fails with an import error).

Quick Start

# Capture a thought
kaydet "Fixed auth bug #work commit:abc123 time:2h status:done"

# Search by metadata
kaydet --filter "status:done"
kaydet --filter "time:>1"
kaydet --filter "commit:abc123"

# List all tags
kaydet --tags

# Open in editor
kaydet --editor

# Edit or delete by ID
kaydet --edit 42
kaydet --delete 42

Why Kaydet?

Zero Friction One command from your terminal. No app windows, no context switching, no loading screens.

Plain Text Forever Daily .txt files you can grep, version with git, sync however you like. No proprietary formats, no lock-in.

Queryable Database SQLite index with full-text search, metadata extraction, and numeric comparisons. Search time:>2 to find long work sessions.

AI-Ready Built-in MCP server exposes your archive to Claude Desktop. Ask your AI about your own life.

Features

• Todo management: Built-in task tracking with --todo and --done commands
• Structured metadata: key:value syntax with numeric comparisons (time:>2, status:done)
• Smart tagging: Hashtags (#work) and metadata in one natural string
• Edit/delete by ID: Stable numeric identifiers for every entry
• Plain text storage: Human-readable .txt files, one per day
• SQLite indexing: Fast search across thousands of entries
• Git-friendly: Version your diary, sync across devices
• MCP integration: Connect to Claude Desktop and other AI tools with todo support

Usage

Basic Commands

# Add an entry
kaydet "Morning standup went well #work"

# Add with metadata
kaydet "Deep work session #focus time:3h intensity:high project:kaydet"

# Search
kaydet --filter "#work"
kaydet --filter "project:kaydet status:done"
kaydet --filter "time:>2"

# Todo Management
kaydet --todo "Write unit tests priority:high"
kaydet --done 42           # Mark todo as done
kaydet --todo              # List todos

# Utility
kaydet --tags              # List all tags with counts
kaydet --stats             # Show calendar and stats
kaydet --folder            # Open log directory
kaydet --doctor            # Rebuild index from text files

Need a literal # in your note? Escape it as \# (e.g., kaydet "Budget was \#1").

Entry Format

Entries are stored as plain text with this format:

14:25 [42]: Fixed auth bug commit:abc123 time:2h status:done #work #urgent

• Timestamp and unique ID
• Message
• Metadata (key:value pairs)
• Tags (hashtags)

File Structure

~/Documents/Kaydet/          → Synced (storage)
├── 2025-10-26.txt
├── 2025-10-27.txt
├── 2025-10-28.txt
└── ...

~/.local/share/kaydet/       → Local only (index)
  └── index.db

Metadata Queries

Kaydet parses key:value pairs and supports:

• Exact match: status:done, project:kaydet
• Numeric comparison: time:>2, time:>=1.5, time:<5
• Ranges: time:1..3 (between 1 and 3 hours)
• Duration parsing: 2h → 2.0, 90m → 1.5, 2.5h → 2.5

Configuration

Settings are in ~/.config/kaydet/config.ini:

[SETTINGS]
DAY_FILE_PATTERN = %Y-%m-%d.txt
DAY_TITLE_PATTERN = %Y/%m/%d - %A
STORAGE_DIR = ~/Documents/Kaydet
EDITOR = nvim
REMIND_AFTER_HOURS = 4
COLOR_HEADER = bold cyan
COLOR_TAG = bold magenta
COLOR_DATE = green
COLOR_ID = yellow

If STORAGE_DIR is omitted, Kaydet picks a sensible default on first run:

• macOS / Windows → ~/Documents/Kaydet
• Linux → ~/Kaydet Prefer hidden/XDG dirs? Change STORAGE_DIR (e.g., ~/.local/share/kaydet) in config.ini and rerun kaydet --config; the CLI offers to move files for you.

Color Customization

You can customize the colors of various elements in the output by adding the following settings under the [SETTINGS] section in config.ini:

[SETTINGS]
# ... existing settings ...
COLOR_HEADER = bold cyan
COLOR_TAG = bold magenta
COLOR_DATE = green
COLOR_ID = yellow

• COLOR_HEADER: Color for date separators and section headers.
• COLOR_TAG: Color for tags (e.g., #work).
• COLOR_DATE: Color for timestamps in search results.
• COLOR_ID: Color for entry IDs and pending todo counts.

You can use any Rich color string (e.g., red, bold green, rgb(255,100,0)).

AI Integration

Connect Kaydet to Claude Desktop via MCP:

// claude_desktop_config.json
{
  "mcpServers": {
    "kaydet": {
      "command": "kaydet-mcp"
    }
  }
}

Then ask Claude:

• "What did I work on this week?"
• "How consistent was my fitness routine last month?"
• "Summarize my accomplishments from last sprint"

Your AI assistant with perfect memory of your own data.

MCP Tools

• suggest_kaydet_tags – Suggest tags for assistants by reading .kaydet.tags in the current project or falling back to the directory name when no override is defined.

Use Cases

Work Logging

kaydet "Shipped analytics feature #work commit:a3f89d pr:142 status:done time:4h"
kaydet "Investigating prod timeout #oncall status:wip time:1.5h"

Time Tracking

kaydet "Deep work on ETL pipeline #work time:3h focus:high"
kaydet --filter "time:>2"  # Find long sessions

Personal Journaling

kaydet "Morning run felt amazing #fitness time:30m distance:5k"
kaydet "Read Atomic Habits chapter 3 #reading"

Expense Tracking

kaydet "Lunch with client #expense amount:850 currency:TRY billable:yes"
kaydet --filter "billable:yes"  # Generate invoice data

Development

git clone https://github.com/miratcan/kaydet.git
cd kaydet
pip install -e .

Run tests:

pip install -e .[dev]
pytest
ruff check src

Cloud Sync & Mobile

Kaydet separates storage (plain text files) from index (SQLite database), making cloud sync simple and safe.

How it works

~/Documents/Kaydet/        → Synced (Google Drive, iCloud, Dropbox)
  ├── 2025-01-15.txt
  ├── 2025-01-16.txt
  └── ...

~/.local/share/kaydet/     → Local only (not synced)
  └── index.db

Why this works:

• Plain text files are the single source of truth
• Each device builds its own search index
• No conflicts, no corruption
• Zero infrastructure cost

Setup for cloud sync

1. First run — Kaydet will ask where to store entries:

   kaydet "First entry"
   
   # Choose your cloud folder:
   Path: ~/Google Drive/Kaydet
   

2. Change location later — Edit config and migrate:

   kaydet --config
   
   # Edit storage_dir in your editor
   # Kaydet will offer to move files automatically
   

3. On other devices — Install Kaydet, set same folder:

   kaydet "First entry on phone"
   Path: ~/Google Drive/Kaydet  # Same path
   

Supported cloud providers

• Google Drive (recommended for Android)
• iCloud Drive (recommended for iOS/macOS)
• Dropbox (cross-platform)
• Any folder sync (Syncthing, Resilio, etc.)

Note: Index is always local. Each device maintains its own index.db for fast search.

Contributing

Bug reports, feature ideas, and pull requests welcome. Open an issue or submit a PR. See docs/CONTRIBUTING.md for guidelines and the full philosophy.

License

MIT License. See LICENSE for details.

Links

• GitHub Repository
• Blog: Why plain text + SQLite beat every cloud note app
• docs/AGENTS.md — agents must read this before interacting with the repo