Module cache 

Machine-local SQLite cache for fast entry lookups.

The cache lives at $XDG_CACHE_HOME/archelon/{journal_id}/cache.db — outside the journal directory so it is never synced by git, Syncthing, or Nextcloud.

Sync strategy

On each invocation, all .md files are stat()-ed (O(n), syscalls only). Per-file mtime comparison is used rather than a global last_synced_at timestamp: syncing tools such as Syncthing preserve the original mtime, so a global watermark would miss files changed or deleted on another machine.

The sync:

• New / modified files (mtime changed or path not in DB): re-parsed and upserted.
• Deleted files (path in DB but gone from disk): removed from cache. Handles Syncthing/Nextcloud propagated deletions transparently.

Explicit deletion after archelon entry remove is handled by remove_from_cache, which avoids a full sync round-trip in that hot path.

Schema

• files: tracks every .md file ever scanned (path + mtime). Covers both managed entries and non-managed files (e.g. README.md). A file whose mtime is unchanged is skipped entirely on subsequent syncs — preventing repeated parse-failure warnings for unmanaged files.
• entries: managed-entry metadata. id INTEGER PRIMARY KEY uses CarettaId as i64. path has an FK to files(path) ON DELETE CASCADE so removing a row from files automatically removes the corresponding entry.
• tags: many-to-many tag index for efficient tag filtering.
• entries_fts: FTS5 virtual table (trigram tokenizer) over title + body for full-text search. Trigram enables substring search and CJK text with no spaces.

Schema versioning

SCHEMA_VERSION is stored in SQLite’s PRAGMA user_version.

• DB version = 0 (fresh file): schema is applied and version is set.
• DB version < app version: schema changed; cache is wiped and rebuilt automatically.
• DB version > app version: the cache was created by a newer archelon; an error is returned instructing the user to update archelon or run archelon cache rebuild.

Structs

CacheInfo

Summary information about the current cache state.

SearchResult

A result returned by search_fts_entries.

Constants

SCHEMA_VERSION

Stored in PRAGMA user_version. Increment whenever the schema changes.

Functions

cache_info

Collect cache statistics for display.

db_path

Compute the path to the current-version SQLite cache file within cache_dir.

find_entry_by_id

Look up an entry by its CarettaId.

find_entry_by_title

Look up an entry by its exact title.

list_entries_from_cache

Read all entries from the cache as [EntryHeader] structs (no body).

open_cache

Open (or create) the SQLite cache for journal.

open_cache_vec

Open (or create) the cache with the sqlite-vec extension loaded.

rebuild_cache

Delete the current-version cache file and create a fresh one.

remove_from_cache

Remove an entry row from the cache by file path.

search_fts_entries

Full-text search using the FTS5 trigram index.

sync_cache

Incrementally sync the cache against the journal’s .md files.

upsert_entry_from_path

Upsert a single entry into the cache by re-reading its file.