Metadata-Version: 2.4
Name: kaydet
Version: 0.43.0
Summary: Simple and terminal-based personal diary app for your shell.
Author: Mirat Can Bayrak
Project-URL: Homepage, https://github.com/miratcan/kaydet
Project-URL: Repository, https://github.com/miratcan/kaydet
Project-URL: Issues, https://github.com/miratcan/kaydet/issues
Keywords: diary,terminal,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Utilities
Classifier: Topic :: Database
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pre-commit==4.0.1; extra == "dev"
Requires-Dist: ruff==0.6.1; extra == "dev"
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: mcp>=0.9.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: mcp>=0.9.0; extra == "mcp"
Dynamic: license-file

# Kaydet — Capture • Query • Remember

<div align="center">
  <img src="assets/logo.png" alt="Kaydet Logo" width="400">
  <br><br>
</div>

[![Tests](https://github.com/miratcan/kaydet/workflows/Tests/badge.svg)](https://github.com/miratcan/kaydet/actions)
[![Coverage](https://img.shields.io/badge/coverage-83%25-brightgreen.svg)](https://github.com/miratcan/kaydet/actions/workflows/test.yml)
[![License](https://img.shields.io/github/license/miratcan/kaydet.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Maintained](https://img.shields.io/badge/Maintained%3F-yes-green.svg)](https://github.com/miratcan/kaydet/graphs/commit-activity)
[![GitHub stars](https://img.shields.io/github/stars/miratcan/kaydet?style=social)](https://github.com/miratcan/kaydet/stargazers)
[![Last commit](https://img.shields.io/github/last-commit/miratcan/kaydet)](https://github.com/miratcan/kaydet/commits/master)

> 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.

<p align="center">
  <img src="assets/demo.gif" alt="Kaydet demo" width="720">
</p>

## Install

```bash
pipx install kaydet
```

With MCP support for AI integration:

```bash
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:**

```bash
uv tool install kaydet    # uv
```

## Quick Start

```bash
# 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.

<p align="center">
  <img src="assets/tui-ai-demo.gif" alt="AI querying kaydet for billing hours" width="720">
</p>

```json
// 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

| | kaydet | jrnl | nb | dnote |
|---|---|---|---|---|
| **CLI journal** | ✅ | ✅ | ❌ notebook | ❌ |
| **SQLite FTS5 search** | ✅ | ❌ | ❌ grep | ✅ |
| **Structured metadata** (`time:>2`) | ✅ | ❌ | ❌ | ❌ |
| **Plain text files** | ✅ | ✅ | ✅ | ❌ DB-only |
| **Daily file structure** | ✅ | ❌ | ❌ | ❌ |
| **Todo management** | ✅ | ❌ | ❌ | ❌ |
| **MCP/AI server** | ✅ | ❌ | ❌ | ❌ |
| **Edit/delete by ID** | ✅ | ❌ | ❌ | ❌ |
| **Color output** | ✅ | ✅ | ✅ | ❌ |
| **Language** | Python | Python | Shell | Go |

### vs Knowledge Apps

| | kaydet | Notion | Obsidian |
|---|---|---|---|
| **Offline first** | ✅ | ❌ | ✅ |
| **Plain text ownership** | ✅ | ❌ | ✅ |
| **Git-friendly** | ✅ | ❌ | ❌ |
| **CLI-native workflow** | ✅ | ❌ | ❌ |
| **AI access (MCP)** | ✅ | partial | partial |
| **Structured metadata queries** | ✅ | ❌ | ❌ |
| **Zero friction capture** | ✅ | ❌ | ❌ |

## 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

```bash
# 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`:

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

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

Any [Rich color string](https://rich.readthedocs.io/en/stable/style.html#color-names) works (e.g., `red`, `bold green`, `rgb(255,100,0)`).

## Use Cases

**Work Logging**
```bash
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**
```bash
kaydet "Deep work on ETL pipeline #work time:3h focus:high"
kaydet --filter "time:>2"  # Find long sessions
```

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

**Expense Tracking**
```bash
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](docs/sync.md) for setup instructions.

## Development

```bash
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](docs/CONTRIBUTING.md) for guidelines.

## License

MIT License. See [LICENSE](LICENSE) for details.

## Links

- [GitHub Repository](https://github.com/miratcan/kaydet)
- [Blog: Why plain text + SQLite beat every cloud note app](https://mirat.dev/articles/nine-years-of-kaydet/)
- [docs/AGENTS.md](docs/AGENTS.md) — agents must read this before interacting with the repo

## Star History

<a href="https://www.star-history.com/?repos=miratcan%2Fkaydet&type=date&legend=top-left">
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=miratcan/kaydet&type=date&theme=dark&legend=top-left&sealed_token=LbYJy5zZl4ZwffHJEH0Fvputlu2yci0QE3UqAKAQ2XPgadh-bZVXzdTxWucL3N_ksbRbm3TgQNLJpXKLhzkRMYn-TRyAEbfGQnmNcyqp1je6UpWEf0ukPtMDLseHVNPZAhHtDfbWI12Iw7mth6jcOyVSsZUUltfwQExyoE9noQiDW9VPTIka18B30Hjs" />
   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=miratcan/kaydet&type=date&legend=top-left&sealed_token=LbYJy5zZl4ZwffHJEH0Fvputlu2yci0QE3UqAKAQ2XPgadh-bZVXzdTxWucL3N_ksbRbm3TgQNLJpXKLhzkRMYn-TRyAEbfGQnmNcyqp1je6UpWEf0ukPtMDLseHVNPZAhHtDfbWI12Iw7mth6jcOyVSsZUUltfwQExyoE9noQiDW9VPTIka18B30Hjs" />
   <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=miratcan/kaydet&type=date&legend=top-left&sealed_token=LbYJy5zZl4ZwffHJEH0Fvputlu2yci0QE3UqAKAQ2XPgadh-bZVXzdTxWucL3N_ksbRbm3TgQNLJpXKLhzkRMYn-TRyAEbfGQnmNcyqp1je6UpWEf0ukPtMDLseHVNPZAhHtDfbWI12Iw7mth6jcOyVSsZUUltfwQExyoE9noQiDW9VPTIka18B30Hjs" />
 </picture>
</a>

---

<div align="center">

Built by [Mirat Can Bayrak](https://github.com/miratcan)

</div>
