better-dontforget 1.0.0__tar.gz

better_dontforget-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install just
+        uses: extractions/setup-just@v2
+
+      - name: Sync dependencies
+        run: uv sync
+
+      - name: Run quality gate (just check)
+        run: just check

better_dontforget-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,83 @@
+# Publish to PyPI. Supports a TestPyPI dry run via manual dispatch.
+# Uses PyPI Trusted Publishing (OIDC) — no token secret required.
+# One-time setup in PyPI: Account settings -> Publishing -> add pending publisher
+#   (project: better-dontforget, owner: vaproh, repo: dontforget,
+#    workflow: publish.yml, environment: pypi).
+# For TestPyPI: register an equivalent publisher on test.pypi.org with environment "testpypi".
+
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      target:
+        description: "Publish target"
+        required: true
+        default: "pypi"
+        type: choice
+        options:
+          - pypi
+          - testpypi
+
+permissions:
+  # Required for PyPI trusted publishing (OIDC).
+  id-token: write
+  contents: read
+
+jobs:
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release' || inputs.target == 'pypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to PyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  publish-testpypi:
+    name: Publish to TestPyPI (dry run)
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish to TestPyPI (trusted publishing)
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/

better_dontforget-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.idea/
+
+# Virtual environments
+.venv
+.env
+app.log
+agents.db
+aisys_cli.egg-info
+service_account.json
+key.json
+dontforget.db
+memory.db
+*.db

better_dontforget-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

better_dontforget-1.0.0/AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md — Engineering Operating Manual
+
+This file is the operating manual for autonomous coding agents working on
+**Better Dontforget** (`better-dontforget`). Follow it precisely.
+
+## Read first
+
+Before editing anything, read in order:
+
+1. `PRD.md` — product requirements and scope (source of truth for *what*).
+2. `ROADMAP.md` — implementation progress and dependency order.
+3. `docs/docs.md` and `docs/config.md` — documented user behavior.
+4. The relevant source under `better_dontforget/` — inspect before changing.
+
+## Golden rules
+
+* Preserve upstream behavior unless intentionally changing it (document why).
+* Prefer the smallest coherent change: **extend → refactor → replace (justified)**.
+* Avoid speculative abstractions and unnecessary dependencies.
+* Keep reminders **optional** and encryption **optional + explicit**.
+* Respect XDG conventions; never dump files into `$HOME` directly.
+* Never turn the project into a calendar, task manager, or full notes app.
+* Never silently expand scope beyond `PRD.md`.
+
+## Workflow
+
+1. Inspect relevant code before editing.
+2. Implement the smallest coherent solution for the milestone in `ROADMAP.md`.
+3. Add/update tests for behavioral changes.
+4. Update affected docs alongside behavior changes.
+5. Run focused tests during development.
+6. Before declaring done: run the canonical quality gate.
+
+## Quality gate
+
+The single canonical full-project verification command is:
+
+```text
+just check
+```
+
+`just check` runs formatting verification, linting, static analysis, the test
+suite, and build verification. Never claim completion while `just check` fails.
+
+## Testing discipline
+
+* Tests must not require real API keys, paid services, network, or a graphical
+  desktop notification server.
+* Mock external AI providers (inject a fake `AIProvider`).
+* Mock/abstract the notifier (`Notifier`) for notification tests.
+* Use temp XDG dirs and temp DB files in tests.
+* Do not overmock pure internal logic into meaningless tests.
+* Cover: capture, provider selection, provider failure, malformed responses,
+  config persistence, XDG env + fallback, reminder persistence, due/overdue
+  detection, duplicate prevention, notification success/failure state,
+  encryption round-trip, wrong-passphrase, CLI behavior, migration.
+
+## Reliability invariants (must hold)
+
+1. A quick note is never silently lost.
+2. AI failure does not destroy user input.
+3. A normal note needs no reminder.
+4. A normal note needs no encryption.
+5. Encryption only when explicitly requested.
+6. Reminder state persists across exits/restarts.
+7. A reminder missed while the machine is off stays pending.
+8. A notification counts as delivered only after delivery succeeds.
+9. Delivered reminders are not re-notified without cause.
+10. Config persists in an XDG-compliant location.
+11. User data is not silently discarded during migration.
+12. API keys never appear in ordinary displayed config output.
+13. Tests never depend on external paid services.
+14. The project stays a focused improvement of `dontforget`.
+
+## Compatibility / secrets
+
+* Preserve upstream `memory.db` via migration; never silently destroy data.
+* Document intentional compatibility breaks in `ROADMAP.md` and PRD.
+* Never print secrets; `config show` masks keys as `configured`.
+* Never send encrypted note content to external AI.
+
+## ROADMAP maintenance
+
+Keep `ROADMAP.md` updated continuously. A task is complete only when
+implementation exists, tests pass, docs are updated, and no known regression
+remains in scope. Use status markers: `[ ]` not started, `[~]` in progress,
+`[x]` complete, `[!]` blocked.
+
+## Justfile workflow
+
+Use `just` recipes: `just build`, `just run`, `just fmt`, `just lint`,
+`just test`, `just check`. See `Justfile` for details.

better_dontforget-1.0.0/Justfile

@@ -0,0 +1,43 @@
+# Justfile — Better Dontforget development workflow
+#
+# Canonical quality gate: `just check`
+
+# Show available recipes.
+default:
+    @just --list
+
+# Install dependencies (uv-managed virtual environment).
+install:
+    uv sync
+
+# Build a distributable wheel/sdist.
+build:
+    uv build
+
+# Run the application (opens TUI when no arguments are given).
+run *ARGS:
+    uv run better-dontforget {{ARGS}}
+
+# Format all Python sources.
+fmt:
+    uv run ruff format .
+
+# Lint (ruff check).
+lint:
+    uv run ruff check .
+
+# Type-check (mypy) on the package.
+type:
+    uv run mypy better_dontforget
+
+# Run the test suite.
+test:
+    uv run pytest
+
+# Canonical full-project verification.
+check:
+    uv run ruff format --check .
+    uv run ruff check .
+    uv run mypy better_dontforget
+    uv run pytest
+    uv build

better_dontforget-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: better-dontforget
+Version: 1.0.0
+Summary: AI-assisted terminal tool for quick personal memory dumps: better TUI, multiple AI providers, optional reminders with desktop notifications, optional per-note encryption, XDG storage, CLI/TUI config.
+Requires-Python: >=3.11
+Requires-Dist: cryptography>=42.0.0
+Requires-Dist: google-genai>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: textual>=8.0.0
+Requires-Dist: tomli-w>=1.0.0
+Description-Content-Type: text/markdown
+
+# 🧠 Better Dontforget
+
+> 🍴 **A fork of [`bugswriter/dontforget`](https://github.com/bugswriter/dontforget).**
+
+**Better Dontforget** is a focused improvement of the upstream `dontforget`
+project: an AI-assisted terminal tool for quickly capturing and retrieving small
+personal memory dumps, enhanced with a better TUI, configurable AI providers,
+optional reminders with persistent desktop notifications, optional per-note
+encryption, XDG-compliant storage, and CLI/TUI-based configuration.
+
+> It is a quick personal memory-dump tool. Reminders and encryption are optional
+> and per-note. It is **not** a calendar, task manager, or full notes application.
+
+## 📦 Install
+
+From [PyPI](https://pypi.org/project/better-dontforget/):
+
+```bash
+pip install better-dontforget
+better-dontforget config set provider gemini
+better-dontforget config set api_key "$GEMINI_API_KEY"
+```
+
+Or, for development from source:
+
+```bash
+uv sync
+better-dontforget "anything"
+```
+
+## ✨ Features
+
+* **⚡ Zero-friction capture:** `better-dontforget "anything"`. Works offline; AI
+  tagging is best-effort and never loses your input.
+* **🔍 Search & AI recall:** full-text search (`search`) and AI-assisted answers
+  (`remind`) over your memories (SQLite + FTS5).
+* **🤖 Multiple AI providers:** Gemini (default) and OpenAI-compatible
+  (OpenAI, OpenRouter, self-hosted), behind a small provider abstraction.
+* **🖥️ Improved TUI:** view/add/edit/delete/search, reminders, encryption, and
+  settings — all keyboard-driven.
+* **⏰ Optional reminders:** attach a due time to a note via `--remind` or natural
+  language ("remind me tomorrow to …").
+* **🔔 Desktop notifications:** due reminders notify via `notify-send` (libnotify),
+  with a one-shot `notify-pending` command and optional systemd user timer that
+  survives restarts.
+* **🔐 Optional per-note encryption:** authenticated (Fernet + PBKDF2), passphrase
+  based, explicit per note; encrypted content is never sent to AI.
+* **📁 XDG-compliant storage** and **CLI/TUI configuration** (no manual file editing).
+
+## 🚀 Quick start
+
+```bash
+uv sync
+better-dontforget config set provider gemini
+better-dontforget config set api_key "$GEMINI_API_KEY"
+
+better-dontforget "ratatui was that rust tui library"
+better-dontforget "remind me tomorrow 9am to check that library"
+better-dontforget search "rust tui"
+better-dontforget tui
+```
+
+The short alias **`bdf`** is also installed (`bdf "ratatui was that rust tui library"`, `bdf search "rust tui"`, …).
+
+See [`docs/docs.md`](docs/docs.md) for full usage and
+[`docs/config.md`](docs/config.md) for configuration.
+
+## 🛠️ Development
+
+```bash
+just install     # uv sync
+just check       # format + lint + type + tests + build (canonical gate)
+just test
+just lint
+just fmt
+just type
+```
+
+## 📄 License
+
+GPL-3. Upstream `dontforget` by Suraj Kushwah; legacy server/client retained under
+`legacy/` for attribution.
+
+## 🙏 Credits
+
+Better Dontforget is a fork of [`bugswriter/dontforget`](https://github.com/bugswriter/dontforget)
+by **Suraj Kushwah**. The original SQLite + FTS5 storage engine and AI-assisted
+capture/recall concept are carried over and extended; the legacy FastAPI
+server and bash `curl` client are preserved under `legacy/` for reference.
+

better_dontforget-1.0.0/PRD.md

@@ -0,0 +1,234 @@
+# PRD — Better Dontforget
+
+## Project name
+
+**Better Dontforget** (repository: `better-dontforget`)
+
+## Project summary
+
+Better Dontforget is a focused improvement of the upstream `bugswriter/dontforget`
+(author Suraj Kushwah) project. It is an AI-assisted terminal tool for quickly
+capturing and retrieving small personal memory dumps, enhanced with a better TUI,
+configurable AI providers, optional reminders with persistent desktop
+notifications, optional per-note encryption, XDG-compliant storage, and
+CLI/TUI-based configuration.
+
+## Relationship to upstream `dontforget`
+
+The upstream project is a Python **FastAPI server** (`main.py`) plus a bash
+**curl client** (`mem-cli`). It stores raw notes in SQLite with an FTS5 full-text
+index, uses Google Gemini to auto-generate search tags on capture and to
+synthesize answers on query, and requires a long-running server plus a secret key.
+
+Better Dontforget **preserves**:
+
+* the SQLite + FTS5 storage engine and its data (with backward-compatible migration);
+* the quick-capture + AI-assisted-tagging workflow;
+* the AI-assisted retrieval / synthesis workflow;
+* the Gemini provider (kept as a first-class provider).
+
+Better Dontforget **changes the runtime shape** with demonstrated justification:
+the upstream client/server model forces a running server and makes capture
+synchronously dependent on AI (a failed AI call loses the note). The requested
+improvements — reliable notifications while the CLI/TUI is closed, an interactive
+TUI, per-note encryption, XDG storage, and config without manual file editing —
+are a poor fit for a required-running HTTP server driven by a bash `curl` script.
+Better Dontforget is therefore a **self-contained CLI + TUI application** that
+talks directly to local storage and to AI providers, while keeping the storage
+format and useful AI behavior intact. The legacy server/client files are retained
+under `legacy/` for reference and attribution; they are not part of the shipped
+application.
+
+## Product philosophy
+
+> The primary product is a quick personal memory-dump tool. Reminders are an
+> optional capability attached to a note, not the primary abstraction. Encryption
+> is also optional and explicitly selected per note. Better Dontforget must not
+> evolve into a calendar, task manager, project manager, full notes application,
+> knowledge base, or second-brain system.
+
+> The goal is to improve the existing upstream project with the smallest coherent
+> changes. A ground-up rewrite is not desired unless repository inspection
+> demonstrates that preserving the existing implementation would make the
+> requirements substantially harder, less reliable, or less maintainable.
+
+## Target use case
+
+Fast, low-friction capture and later retrieval of small personal facts:
+
+```text
+the rust tui library was called ratatui
+wifi password is written behind the router
+John recommended Severance
+remind me tomorrow to check that library
+```
+
+## Existing upstream behavior being preserved
+
+* SQLite + FTS5 storage and schema (`memories` + `memories_idx`).
+* AI-assisted capture tags.
+* AI-assisted query synthesis over retrieved memories.
+* The `remember` / `remind` / `delete` conceptual operations.
+
+## Improvements introduced by Better Dontforget
+
+1. Improved TUI.
+2. Multiple configurable AI/LLM providers (Gemini + OpenAI-compatible).
+3. Optional reminders attached to quick notes.
+4. Desktop notifications for due reminders.
+5. Reliable background notification processing.
+6. Persistent reminders that survive application exits and machine restarts.
+7. Optional per-note encryption.
+8. XDG-compliant application paths.
+9. Configuration through CLI and TUI rather than manual file editing.
+10. Better project documentation and agentic development infrastructure.
+
+## v1 requirements
+
+* Self-contained CLI + TUI (no required server).
+* Quick capture works without AI; AI failure never loses user input.
+* Multiple AI providers behind a small abstraction; OpenAI-compatible covers
+  OpenAI and OpenRouter via a configurable base URL.
+* Optional reminders persisted per note; due/overdue detection.
+* Desktop notifications via the platform mechanism (`notify-send`/libnotify).
+* One-shot `notify-pending` command + optional systemd user timer/service for
+  reliable processing while the interactive app is closed and after restarts.
+* Optional per-note encryption (authenticated, passphrase-derived key).
+* XDG-compliant config/data paths.
+* CLI `config` subcommand and TUI settings; no manual file editing required.
+* Backward-compatible migration of existing upstream `memory.db`.
+
+## Explicit non-goals
+
+* Calendar, task manager, project manager, to-do app, document editor.
+* Personal wiki, knowledge graph, second-brain, kanban, Markdown knowledge base.
+* Cloud sync, collaboration, user accounts, team features, mobile apps.
+* Vector databases, embeddings, semantic-search/RAG pipelines.
+* Recurring reminder engines / complex recurrence rules (v1).
+* Custom daemons, IPC, RPC, socket servers, or service frameworks.
+* Telegram/ntfy/email/SMS/mobile push/webhook notification transports (v1).
+
+## Quick-note behavior
+
+* `better-dontforget "anything"` captures a note instantly.
+* Capture is synchronous and local; AI tagging is best-effort and failures are
+  non-fatal (note is still saved, possibly without tags).
+* A normal note never requires a reminder or encryption.
+* Optional flags: `--encrypt` (encrypted note), `--remind "<when>"` (attach
+  reminder). Encrypted notes are not sent to AI.
+
+## AI behavior
+
+* On capture: AI generates search tags (best-effort).
+* On query (`remind`/`ask`): AI extracts keywords, FTS retrieves candidates, AI
+  synthesizes an answer. If AI is unavailable, falls back to raw FTS listing.
+* On `search`: direct FTS listing (no AI).
+* Only the content needed for the requested operation is sent to the provider.
+
+## Multiple-provider behavior
+
+* Providers: `gemini` (default), `openai` (OpenAI-compatible: OpenAI, OpenRouter),
+  `groq` (OpenAI-compatible: Groq).
+* Selected via `config set provider <name>`.
+* Credentials read from config or environment (`GEMINI_API_KEY`, `OPENAI_API_KEY`).
+* `openai` provider supports a configurable `base_url` for OpenRouter/self-hosted.
+* Provider calls are mockable; tests never use real keys.
+
+## Optional-reminder behavior
+
+* A reminder is an optional `reminder_at` timestamp on a note.
+* Set via `--remind "<spec>"` or from natural-language intent ("remind me
+  tomorrow to …") parsed by a deterministic heuristic.
+* Ordinary notes remain ordinary notes.
+* No calendar semantics, recurrence, or task-completion workflow in v1.
+
+## Desktop-notification behavior
+
+* When a reminder becomes due, a local desktop notification is sent via
+  `notify-send` (libnotify), the established Linux mechanism.
+* Notification is attempted only for due, not-yet-delivered reminders.
+* Marked delivered only after successful delivery; duplicates avoided.
+
+## Persistent missed-reminder behavior
+
+* Reminders are persisted in the database.
+* A reminder due while the machine is off cannot notify at that instant.
+* On next `notify-pending` run (e.g. after login via systemd timer), due and
+  unnotified reminders (including overdue ones) are detected and notified.
+* Policy: all due unnotified reminders are notified; no recurrence, so volume is
+  naturally bounded. No silent discarding.
+
+## Optional per-note encryption
+
+* Explicit only: `--encrypt` flag or TUI explicit action.
+* Uses `cryptography` Fernet (authenticated) with PBKDF2 key derivation from a
+  passphrase (prompted at runtime, never stored).
+* Encrypted content is not sent to external AI.
+* Plaintext is never persisted; decrypted content is never logged.
+* Incorrect passphrase fails closed (decryption error surfaced, no leak).
+
+## TUI requirements
+
+* View, add, edit, delete notes; search/filter; inspect reminder state; attach/
+  remove reminder; create encrypted note; unlock/decrypt; access settings.
+* Keyboard-driven; handles resize and ordinary errors gracefully.
+* Not a full notes editor: no analytics, kanban, calendar, nested trees.
+
+## CLI requirements
+
+* `better-dontforget "text"` quick capture; `--encrypt`, `--remind`.
+* Subcommands: `remind`/`ask`, `search`, `list`, `delete`, `tui`, `config`,
+  `notify-pending`.
+* Backward-compatible intent with upstream `mem` (remember/remind/delete).
+
+## Configuration behavior
+
+* Stored as TOML in `$XDG_CONFIG_HOME/better-dontforget/config.toml`.
+* Managed via `config show|set|reset` and TUI settings.
+* `config show` masks secrets ("API key: configured").
+* No manual file editing required.
+
+## XDG requirements
+
+* Config: `$XDG_CONFIG_HOME/better-dontforget/`
+* Data (DB): `$XDG_DATA_HOME/better-dontforget/`
+* State/cache/runtime only if actually needed (not created speculatively).
+* Fallbacks to `~/.config`, `~/.local/share` when base vars unset.
+* Existing `./memory.db` is migrated into the XDG data dir on first run.
+
+## Reliability requirements
+
+See "Reliability invariants" in the mission. Key: capture never lost; AI failure
+non-fatal; reminder/encryption optional and explicit; notification success gated
+on delivery; config + data in XDG; no secret leakage.
+
+## Error-handling expectations
+
+* Missing/invalid credentials: clear message; capture and local search still work.
+* AI rate limits/timeouts/malformed responses: degrade gracefully, never lose input.
+* Notification failure: leave reminder unnotified, retry next run.
+* Wrong encryption passphrase: fail closed.
+
+## Compatibility expectations
+
+* Existing upstream `memory.db` data is preserved via migration.
+* Upstream behavior (tags, FTS retrieval) preserved.
+* Legacy `mem`/server retained under `legacy/` for attribution only.
+
+## Acceptance criteria
+
+1. Quick capture works offline and without AI.
+2. `just check` passes (fmt, lint, type, tests, build).
+3. Multiple providers work; tests mock providers, no real keys.
+4. Reminders persist; due + overdue detection works; no duplicate notify.
+5. `notify-pending` works while app closed; systemd user unit documented.
+6. Per-note encryption round-trips; wrong passphrase fails closed.
+7. XDG paths used; config via CLI/TUI; secrets masked.
+8. TUI supports required operations.
+9. Docs match implementation; scope not expanded.
+
+## Definition of done
+
+All items in the mission's Definition of Done are satisfied: `just check` passes,
+PRD/AGENTS/ROADMAP/docs consistent, features implemented and tested, scope
+preserved as a focused improvement of `dontforget`.