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:
parent
d388002fec
commit
9356122591
76
CLAUDE.md
Normal file
76
CLAUDE.md
Normal 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
|
||||
90
README.md
90
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.
|
||||
@ -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;
|
||||
|
||||
Loading…
Reference in New Issue
Block a user