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
|
Type=Application
|
||||||
Name=My Memory
|
Name=My Memory
|
||||||
Comment=Low-friction thought capture (text + voice)
|
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
|
Icon=document-edit
|
||||||
Terminal=false
|
Terminal=false
|
||||||
Categories=Utility;
|
Categories=Utility;
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user