Core Analysis¶

Problem Focus: Determine when to choose hashcards and which use cases it is not suited for.

Recommended scenarios¶

• Technical users: You manage cards in Markdown within your editor and want learning integrated into a code-like workflow (Makefile, scripts).
• Data ownership & audit: You need diffs, traceability, and local-only data storage—no cloud lock-in.
• Scriptable workflows: You want to automate card generation, validation, and export in CI or hooks.

Scenarios to avoid¶

• Need built-in cloud/mobile: hashcards has no official cloud sync or mobile client; cross-device sync is manual.
• Complex templates/multi-field notes: Only front-back and cloze types are supported—unsuitable if you rely on Anki-style templates.
• Multi-user/high-concurrency: SQLite/local design assumes single-user usage; concurrent writes introduce consistency/lock issues.

Alternatives (brief)¶

• Anki/AnkiConnect: Better for rich templates and mobile/plug-in ecosystems, but sacrifices plain-text auditability.
• Server-backed SRS: Use when you need centralized sync/collaboration; requires hosting and more complexity.

Important: Weigh your priority between “auditability/scriptability” vs “mobile/sync/template richness”; hashcards favors the former.

Summary: Choose hashcards if you are a single-user, tech-oriented person who prioritizes control and automation. For cross-device sync or complex card types, prefer a more feature-rich GUI/service solution.

Core Analysis¶

Project Positioning: hashcards addresses the need to run spaced repetition (SRS) in a plain-text-first, auditable, and scriptable way, avoiding lock-in to closed GUIs or proprietary storage.

Technical Features¶

• Plain-text storage: Flashcards are authored as Markdown/plain-text files, editable in any editor and trackable with VCS.
• Content-addressable IDs: Each card ID is the hash of its text; editing a card explicitly resets its progress and preserves traceability.
• Local state store: Uses a local SQLite database (hashcards.db) for performance and history; no cloud dependency.
• Modern scheduling: Uses FSRS algorithm for more nuanced review scheduling than SM-2.

Usage Recommendations¶

1. Getting started: Put cards under git, author Markdown cards, run hashcards drill <DIR> to open the local review UI (default http://localhost:8000).
2. Organization: Use TOML frontmatter for deck names and keep consistent file/directory layout for discoverability.

Caveats¶

• Edit resets progress: Any text change changes the hash and resets progress—export or backup hashcards.db before bulk edits.
• Session persistence: Progress is saved only at session end; browser crashes or premature close can lose progress.

Important: Targeted at users comfortable with CLI and VCS; non-technical users will face a higher onboarding cost.

Summary: hashcards provides a traceable, scriptable, and efficient local SRS suited for users who prioritize data control and plain-text workflows.

Core Analysis¶

Problem Focus: New users mainly struggle with build/runtime setup, the session save semantics, and resource path management. Users comfortable with CLI and text tools will ramp up faster.

Technical Analysis¶

• Getting started essentials:
• Requires Rust cargo or a prebuilt binary to build/install (make, sudo make install).
• Run reviews with hashcards drill <DIR>, which serves a local web UI at http://localhost:8000.
• Common issues:
• Session not saved immediately: Progress is saved only when the session ends—browser crashes lose unsaved grades.
• Resource path mistakes: Images/audio are relative to the deck; use @/ or maintain consistent directory layout.
• Edit resets progress: Frequent tweaks change the hash and reset progress.

Recommended Onboarding¶

1. Prep environment: Install rustup/cargo or obtain a binary; confirm hashcards --help works.
2. Use example repo: Clone the author’s example to observe drill behavior.
3. Version control: Put your card directory under git and commit before big changes.
4. Backup: Back up hashcards.db or export JSON before bulk edits (hashcards export).
5. Path conventions: Standardize image/audio paths or adopt the @/ convention.

Important: Always back up DB before major edits and close sessions properly to ensure progress is saved.

Summary: For technical users, the learning cost centers on environment setup and workflow conventions; example repos, VCS, and backup practices reduce early mistakes and stabilize usage.

Core Analysis¶

Problem Focus: Content-addressing (card ID = text hash) improves traceability and determinism but makes edits directly affect learning progress, introducing practical friction.

Technical Analysis¶

• Advantages:
• Determinism: Any change alters the hash, avoiding hidden inconsistencies.
• Auditability: With VCS, you can trace exactly when text and thus progress changed.
• Challenges:
• Frequent resets: Minor formatting or auto-wraps trigger progress resets and disrupt review continuity.
• DB churn: Deletions/renames create orphan DB entries that require cleanup.

Practical Recommendations¶

1. Adopt editing conventions: Standardize whitespace, line breaks, and Markdown style to avoid meaningless hash changes.
2. Prepare before bulk edits: git commit and backup hashcards.db or export JSON before large rewrites.
3. Scripted migrations: For bulk changes, compute old->new hash mappings and either migrate SQLite records or keep an external mapping for restoring progress.
4. Regular cleanup: Use hashcards orphans list/delete to reconcile DB and source.

Important: If you frequently tweak cards but want to preserve progress, prefer appending new cards or export history before rewriting to enable re-association.

Summary: Content-addressing gives auditability and determinism at the cost of edit friction; conventions, backups, and scripted migrations make it practical in day-to-day use.

Core Analysis¶

Problem Focus: How to integrate hashcards into a git + Makefile automation workflow to enable repeatable maintenance, backups, and deployments?

Technical Analysis¶

• Available building blocks: hashcards exposes CLI commands (drill, check, orphans, export) that Makefile/CI scripts can call; cards are plain-text and work with standard Unix tools.
• Common automation tasks: validation, backup/export, starting drill sessions, cleaning orphans.

Recommended Practices (Makefile pattern)¶

1. Basic targets:
   - make check → hashcards check cards/
   - make export → hashcards export cards/ > exports/$(date).json
   - make orphans-clean → hashcards orphans delete cards/
2. Backup strategy: Stop active drill sessions or detect port usage before make export to ensure consistent exports; store JSON export alongside hashcards.db backups off-repo.
3. Git integration: Run make check in a pre-commit hook to avoid committing malformed cards.
4. Templates/new-card flow: Provide make new to create standard Markdown templates and optionally git add to enforce consistency.

Caveats¶

• Session conflicts: Simultaneous drill sessions and automated scripts writing to SQLite can cause locks—handle mutual exclusion in scripts.
• Bulk edits: Before bulk changes, make export and verify orphans after edits.

Important: Treat the text directory as the single source of truth and orchestrate validation/export steps in Makefile to reduce manual errors and improve auditability.

Summary: hashcards’ CLI is naturally composable with git + Makefile. Encapsulate checks, exports, and cleanups into Make targets to build a reliable, auditable automation pipeline.

Core Analysis¶

Problem Focus: How to keep hashcards.db consistent with the plain-text source, manage orphan entries, and maintain large collections?

Technical Analysis¶

• Built-in tools: hashcards check, hashcards orphans list/delete, and hashcards export are the main primitives for maintenance.
• Common issues: DB retains deleted-card history (orphans); bulk edits produce many new hashes; concurrent writes can cause SQLite lock contention.

Maintenance & Operational Flow (recommended)¶

1. Before/after edits:
   - git commit the text changes;
   - hashcards export to a timestamped JSON as a hot backup;
2. Consistency checks: Run hashcards check in CI or scheduled tasks to surface syntax/parse issues early;
3. Orphan management: Periodically run hashcards orphans list, review results, and use orphans delete to clean up;
4. Bulk edit strategy: Backup hashcards.db and compute old->new hash mappings to migrate performance records if needed;
5. Large collections: Partition by deck/topic and archive older history (store archived DBs read-only) to limit growth.

Concurrency & automation caveats¶

• Avoid concurrent writes: Implement file locks or check for active drill sessions before performing exports or DB writes.
• Backup-first: Always export JSON and back up DB before migrations or bulk operations.

Important: Orphan entries are not inherently erroneous but require policy—delete or migrate—so the DB and source remain meaningful.

Summary: Use the built-in CLI plus git and scripted processes to keep single-user and mid-sized collections consistent. For high-scale or concurrent use, add partitioning, archiving, or a centralized state service.