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 <noreply@anthropic.com>
This commit is contained in:
Cal Corum 2026-02-11 14:54:46 -06:00
parent d388002fec
commit 9356122591
3 changed files with 167 additions and 1 deletions

76
CLAUDE.md Normal file
View File

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

View File

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

View File

@ -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;