From 93561225915cb941d655cc34ce02e36034705c45 Mon Sep 17 00:00:00 2001 From: Cal Corum Date: Wed, 11 Feb 2026 14:54:46 -0600 Subject: [PATCH] docs: add CLAUDE.md, README, and fix desktop Exec path Add project context file for AI agents and a user-facing README covering features, installation, usage, and configuration. Update the desktop file Exec to use the full uv path for autostart. Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 76 +++++++++++++++++++++++++++++++++++++++ README.md | 90 +++++++++++++++++++++++++++++++++++++++++++++++ my-memory.desktop | 2 +- 3 files changed, 167 insertions(+), 1 deletion(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..aae1559 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,76 @@ +# My Memory + +Low-friction capture app for thoughts, text, and voice. Runs as a system tray app on Linux (PySide6). + +## Tech Stack + +- **Language:** Python 3.13+ managed with `uv` +- **UI Framework:** PySide6 (Qt 6) +- **Transcription:** faster-whisper (CTranslate2) with CUDA auto-fallback to CPU +- **Data Format:** Markdown files with YAML frontmatter (`python-frontmatter`) +- **Models:** Pydantic v2 + +## Running + +```bash +uv run my-memory # Launch tray app +uv run my-memory --capture # Open capture window (or signal running instance) +uv run my-memory --board # Open kanban board (or signal running instance) +uv run my-memory --download-model # Pre-download Whisper model +``` + +## Project Structure + +``` +src/my_memory/ + __main__.py # CLI entry point, single-instance dispatch + app.py # QApplication, system tray, IPC via QLocalServer + config.py # Config dataclasses + TOML loading (~/.my-memory/config.toml) + models.py # Pydantic models: Entry, EntrySource, EntryStatus + storage.py # Markdown + YAML frontmatter file I/O + schema.py # Auto-generated schema.md for AI agent discovery + capture_window.py # Frameless popup: text input, voice recording, transcription + board_window.py # Kanban board: On Docket -> In Progress -> Complete + audio_recorder.py # sounddevice recording with RMS level signals + transcriber.py # faster-whisper with QThread worker, CUDA/CPU fallback +``` + +## Data Storage + +Entries live in `~/.my-memory/entries/YYYY-MM-DD/{uuid}.md` with YAML frontmatter. Voice entries have a paired `.wav` file. + +## Entry Statuses + +- `docket` — Newly captured, waiting to be acted on +- `in_progress` — Currently being worked on +- `complete` — Done (column is collapsible with 7d/30d/All date filter) +- `cancelled` — Archived/discarded (hidden from board, file preserved on disk) + +## Key Patterns + +- **Single instance:** Uses `QLocalServer`/`QLocalSocket` IPC so `--capture` and `--board` flags signal the running instance +- **System tray:** App stays resident with `setQuitOnLastWindowClosed(False)`; Ctrl+C is handled via SIGINT + QTimer +- **Lazy model loading:** Whisper model is loaded on first transcription, not at startup +- **File watching:** Board auto-refreshes via `QFileSystemWatcher` with 300ms debounce +- **Collapsible Complete column:** Collapsed by default, shows count badge; when expanded, filters by date (7d default) + +## Configuration + +Optional `~/.my-memory/config.toml`: + +```toml +[whisper] +model_size = "base" # tiny, base, small, medium, large-v3 +device = "auto" # auto, cuda, cpu +compute_type = "float16" + +[audio] +sample_rate = 16000 +channels = 1 +``` + +## Gitea + +- **Repo:** https://git.manticorum.com/cal/my-memory +- **Remote name:** origin +- **Branch:** master diff --git a/README.md b/README.md index e69de29..e69b6c5 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,90 @@ +# My Memory + +A low-friction capture app for thoughts, text, and voice. Lives in your system tray and lets you quickly jot down or dictate ideas, then organize them on a kanban board. + +## Features + +- **Text capture** — Type a thought and save it with Ctrl+Enter +- **Voice capture** — Record audio, auto-transcribed via Whisper +- **Kanban board** — Drag entries through On Docket, In Progress, and Complete +- **Collapsible Complete column** — Collapsed by default with count badge; expand to filter by 7 days, 30 days, or all time +- **Cancel entries** — Archive notes you no longer need without deleting the file +- **System tray** — Stays resident; click the icon to capture, right-click for menu +- **Single instance** — Running `my-memory --capture` or `--board` signals the existing instance +- **Plain files** — Entries are markdown with YAML frontmatter, stored in `~/.my-memory/entries/` + +## Requirements + +- Python 3.13+ +- [uv](https://docs.astral.sh/uv/) for dependency management +- A working audio input device (for voice capture) +- CUDA toolkit (optional, for GPU-accelerated transcription; falls back to CPU) + +## Installation + +```bash +git clone https://git.manticorum.com/cal/my-memory.git +cd my-memory +uv sync +``` + +To pre-download the Whisper model: + +```bash +uv run my-memory --download-model +``` + +## Usage + +```bash +uv run my-memory # Launch (lives in system tray) +uv run my-memory --capture # Open capture window +uv run my-memory --board # Open kanban board +``` + +### Autostart + +Copy or symlink the desktop file to autostart at login: + +```bash +ln -s /path/to/my-memory/my-memory.desktop ~/.config/autostart/ +``` + +## Configuration + +Create `~/.my-memory/config.toml` to override defaults: + +```toml +[whisper] +model_size = "base" # tiny, base, small, medium, large-v3 +device = "auto" # auto, cuda, cpu +compute_type = "float16" + +[audio] +sample_rate = 16000 +channels = 1 +``` + +## Data Format + +Entries are stored as `~/.my-memory/entries/YYYY-MM-DD/{uuid}.md`: + +```yaml +--- +id: "550e8400-e29b-41d4-a716-446655440000" +timestamp: "2026-02-11T14:30:00" +source: "voice" +tags: [] +status: "docket" +audio_file: "550e8400-...440000.wav" +duration_seconds: 12.5 +--- + +The captured thought content here. +``` + +Voice entries have a paired `.wav` file in the same directory. + +## License + +Private project. diff --git a/my-memory.desktop b/my-memory.desktop index 6f21158..f4d27c1 100644 --- a/my-memory.desktop +++ b/my-memory.desktop @@ -2,7 +2,7 @@ Type=Application Name=My Memory Comment=Low-friction thought capture (text + voice) -Exec=my-memory +Exec=/home/cal/.local/bin/uv run --project /mnt/NV2/Development/my-memory my-memory Icon=document-edit Terminal=false Categories=Utility;