Kaydet — Capture • Query • Remember

Your personal memory database. Capture anything. Query everything. Let AI remember.

Plain text storage · SQLite search · MCP integration

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

pipx install kaydet

With MCP support for AI integration:

pipx install kaydet[mcp]

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

Also available via:

uv tool install kaydet    # uv

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"

# List all tags
kaydet --tags

# Open in editor
kaydet --editor

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

# Attach files
kaydet "Meeting notes" --attach notes.pdf
kaydet "Screenshot attached" --grab screen.png  # also removes original

AI Integration

Kaydet's MCP server connects your personal archive to Claude Desktop and any MCP-compatible AI.

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

Then ask your AI:

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

Your AI assistant grounded in your own data.

Architecture

┌─────────────────────┐
│   Claude Desktop    │
│  or any MCP client  │
└────────┬────────────┘
         │ MCP protocol
┌────────▼────────────┐
│     kaydet-mcp      │
└────────┬────────────┘
         │
    ┌────┴────┐
    │         │
┌───▼───┐ ┌───▼──────────┐
│ daily │ │ SQLite index │
│ .txt  │ │ (local only, │
│ files │ │  rebuilt     │
│       │ │  from text)  │
└───┬───┘ └──────────────┘
    │
    ▼
Google Drive / iCloud / Dropbox

MCP Tools

• suggest_kaydet_tags – Suggest tags by reading .kaydet.tags in the current project or falling back to the directory name.
• 13 tools total: search, filter by metadata, manage todos, get stats, and more.

Why Kaydet?

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

Plain Text Ownership Daily .txt files you can grep, version with git, sync however you like. No proprietary formats, no lock-in. Your data outlives any app.

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

Personal AI Memory Layer Built-in MCP server gives your AI assistant direct access to your archive. It's not a chatbot with generic knowledge—it's an AI that knows your life.

How Kaydet Compares

vs CLI Tools

vs Knowledge Apps

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
• File attachments: Attach files with --attach or move with --grab
• Plain text storage: Human-readable .txt files, one per day
• SQLite indexing: Fast search across thousands of entries
• Git-friendly: Version your journal, sync across devices
• MCP integration: Connect to Claude Desktop and other AI tools

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"

# Attach files
kaydet "Meeting notes" --attach notes.pdf
kaydet "Screenshot" --grab screen.png        # copies + removes original

# Search & Filter
kaydet --filter "#work"
kaydet --filter "project:kaydet status:done"
kaydet --filter "time:>2"
kaydet --list                                # list all entries
kaydet --today                               # today's entries
kaydet --get 42                              # show entry by ID

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

# View
kaydet --tags                                # List all tags with counts
kaydet --stats                               # Show calendar and stats
kaydet --folder                              # Open log directory
kaydet --format json --filter "#work"        # JSON output

# Edit & Delete
kaydet --edit 42                             # Open in editor
kaydet --edit 42 "Updated message"           # Inline update
kaydet --delete 42                           # Delete by ID
kaydet --delete 42 --yes                     # Skip confirmation

# Management
kaydet --doctor                              # Rebuild search index
kaydet --config                              # Edit config file
kaydet --reminder                            # Show writing reminder
kaydet --at "2024-01-15:14:30" "Note"       # Backdated entry

# Version
kaydet --version

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 output colors by adding these to [SETTINGS] in config.ini:

COLOR_HEADER = bold cyan
COLOR_TAG = bold magenta
COLOR_DATE = green
COLOR_ID = yellow

Any Rich color string works (e.g., red, bold green, rgb(255,100,0)).

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

Cloud Sync

Kaydet separates storage (plain text files) from index (SQLite database). Only the plain text files are synced—each device builds its own search index locally. This means zero sync conflicts and no infrastructure cost.

Works with Google Drive, iCloud, Dropbox, Syncthing, or any folder sync tool.

See docs/sync.md for setup instructions.

Development

git clone https://github.com/miratcan/kaydet.git
cd kaydet
pip install -e .[dev]
pytest
ruff check src

Contributing

Bug reports, feature ideas, and pull requests welcome. See docs/CONTRIBUTING.md for guidelines.

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

Star History