Supertag CLI v2.5.7

Fixed

• Reference-type field values returned empty string — tana_query, tana_tagged, and any code path through FieldResolver returned "" for fields whose value is a reference to another node (e.g., "Context": "" where Context pointed to Pr MB2). Root cause: Tana stores inline references as empty <span data-inlineref-node="NODE_ID"></span> tags; the resolver ran stripHtml() which removed the span, leaving the empty content behind. The resolver now parses those spans, looks up the referenced node's name (batched, single SQL query per unique set), and substitutes the resolved display text before stripping residual HTML. Also resolves data-inlineref-date spans to their dateTimeString value.

Supertag CLI v2.5.6

Fixed

• Delta-sync was silently a no-op after first run (CRITICAL) — Tana Local API interprets edited.since as seconds since epoch, but supertag-cli was passing milliseconds. The API resolved the ms value to a far-future timestamp (~year 58,000) and returned 0 results, so every delta-sync after the initial one did nothing. Fixed by converting ms → seconds at the API boundary in DeltaSyncService.fetchChangedNodes(). The watermark remains in ms internally for backward compat with existing databases. This explains most reported staleness — delta-sync now actually catches Tana-originated edits.

Known limitation (still present after this fix)

• Field-value-only changes may still not surface in delta-sync. Investigation showed that modifying only a field value on a node does not appear to bump the parent's edited.since timestamp in Tana's index. A proper fix requires a per-supertag rescan (planned for v2.6). Until then, a nightly supertag sync index (full reindex) remains required for field-filtered query correctness.

Supertag CLI v2.5.5

Fixed

• Delta-sync hangs indefinitely on Windows 11 — LocalApiClient now wraps every fetch() with an AbortSignal-based timeout (default 30s, override via SUPERTAG_LOCAL_API_TIMEOUT_MS). A wedged Tana Desktop process used to hang the entire sync forever; it now surfaces as a retryable TIMEOUT error after the configured timeout and retries with exponential backoff.

Added

• tana_stats exposes index freshness — Response now includes lastFullSync, lastDeltaSync, lastDeltaNodesCount, secondsSinceLastSync, and isStale (with a staleReason message when stale). Lets AI callers detect a stale index before trusting query results.
• tana_query emits staleness warnings — Responses now include an optional warnings field when the local index is stale or when a field-filtered query runs against a database with no full sync. Thresholds configurable via SUPERTAG_STALE_DELTA_MINUTES (default 60) and SUPERTAG_STALE_FULL_HOURS (default 168).

Documentation

• Field-filtered queries require a recent full sync — Documented that delta-sync clears field_values for touched nodes without repopulating them (by design — delta-sync has no tuple context). Any query filtering on a non-core field must therefore run against a recently full-synced index; delta-sync alone is insufficient for field-value correctness. A proper fix requires a deeper redesign (see #sync-correctness).

Supertag CLI v2.5.4

Fixed

• select with fields.* still returns null/empty — Replaced generic nested-path projection with explicit field extraction that directly reads resolved field values. Field resolution now always uses '*' wildcard (no SQL field-name matching), and projection constructs the output fields object explicitly with case-insensitive key lookup. Eliminates all SQL matching, encoding, and generic-projection fragility.
• tana_query ignores select clause — tana_query never applied projection, returning all core fields (parentId, nodeType, doneAt) regardless of select. Now explicitly filters to requested fields.
• Field name matching now case-insensitive — Both SQL field resolution (COLLATE NOCASE) and field projection match field names case-insensitively, so fields.status correctly resolves Status.
• sync status fails on Windows junctions — findLatestExport() silently returned null when the export directory was a Windows junction (e.g., to Google Drive). Now resolves the canonical path via realpathSync before reading, with improved diagnostic logging.
• Delta sync does not clear stale field values — When field values are changed or cleared in Tana and delta sync detects the node update, the old field values in field_values table were never removed. Delta sync now clears field_values for updated nodes. A subsequent full sync (sync index) re-populates them from the export.

Supertag CLI v2.5.3

Fixed

• select with fields.* still returns null/empty — Root cause: field resolution used exact SQL field_name IN (...) matching which failed silently on case/encoding mismatches. Now resolves ALL fields with wildcard and lets JS projection handle filtering — eliminates any SQL matching fragility.
• tana_query ignores select clause — tana_query never applied projection, returning all core fields (parentId, nodeType, doneAt) regardless of select. Now applies applyProjectionToArray like all other MCP tools.
• Field name matching now case-insensitive — Both SQL field resolution (COLLATE NOCASE) and JS projection (getNestedValue) now match field names case-insensitively, so fields.status correctly resolves Status.
• sync status fails on Windows junctions — findLatestExport() silently returned null when the export directory was a Windows junction (e.g., to Google Drive). Now resolves the canonical path via realpathSync before reading, with improved diagnostic logging.

Supertag CLI v2.5.2

Fixed

• select with fields.* prefix returns null — tana_query and tana_tagged with select: ["fields.Status", ...] returned empty/null field values because the fields. prefix was passed directly to the database query instead of being stripped. Field values now resolve correctly with both "fields.Status" and bare "Status" formats.
• tana_tagged missing field values — tana_tagged tool never loaded field values from the database, so any select referencing fields.* paths found nothing to project. Field values are now resolved via FieldResolver before projection.
• sync status always shows latestExport: null — getStatus() returned a cached null value without ever searching the export directory. Now eagerly calls findLatestExport() so the actual latest export file is reported.
• Silent sync index failure diagnostics — When no matching export files are found, the error now reports which directory was searched and lists any JSON files present that didn't match the expected *@YYYY-MM-DD.json pattern.

Supertag CLI v2.5.0

Added

• MCP idle auto-exit — Server self-terminates after 30 minutes without tool calls, preventing zombie process accumulation across Claude Code sessions. Configurable via SUPERTAG_MCP_IDLE_TIMEOUT env var (set 0 to disable).
• SQLite connection health check — DeltaSyncService tests its database connection before each sync and auto-reconnects if stale, resolving "database or disk is full" errors caused by long-lived processes.
• busy_timeout on all DeltaSyncService connections — PRAGMA busy_timeout = 5000 configured on both initial and reconnected connections for better concurrent access resilience.

Fixed

• Idle timer NaN guard — Invalid SUPERTAG_MCP_IDLE_TIMEOUT values (e.g., non-numeric strings) now fall back to the 30-minute default instead of causing immediate server exit.
• Idle timer sync race — Timer now checks if a sync is in progress before exiting, deferring shutdown until the sync completes.

Supertag CLI v2.4.2

Performance

• 47% faster JSON parse + graph build — Replaced per-node Zod validation with fast structural check, merged 5 iteration passes into single-pass with deferred resolution. 5.3s → 2.8s on 360MB / 1.68M node export.
• 97% faster sync index — Skip all work when 0 changes detected, only upsert checksums for changed nodes, skip full metadata rebuild for small change sets (<5%). 232s → 6s on real database.

Fixed

• Off-by-one day in formatDateISO — toISOString() formatted in UTC, causing dates to shift back one day in UTC+ timezones. Now uses local timezone components. (PR #80, @dalxds)

Supertag CLI v2.4.1

Fixed

• WAL checkpoint on close — SQLite WAL files could grow unbounded (44GB+) because write connections never checkpointed. Added passive WAL checkpoint before every write-connection close in withDatabase, withTransaction, TanaIndexer, and DeltaSyncService.

Supertag CLI v2.4.0

Added

• Watch Mode (F-103) — Continuous monitoring of Tana changes with hook-based automation

  • supertag sync watch polls Tana Local API for changes at configurable intervals (default: 30s)
  • Shell hooks: --on-change, --on-create, --on-modify, --on-delete execute commands on lifecycle events
  • --filter-tag <tag> to watch only specific supertags
  • --event-log <path> for JSONL event audit trail
  • --dry-run to detect changes without executing hooks
  • Exponential backoff on failures, configurable --max-failures limit
  • Pre/post snapshot diffing around delta-sync for reliable change detection

• PAI Memory Integration (F-108) — Tana graph as persistent AI memory store for cross-session learning

• Graph Query DSL (F-102) - Declarative graph query language for traversing typed relationships

  • supertag gquery CLI command with DSL syntax: FIND <type> WHERE <filter> CONNECTED TO <type> RETURN <fields>
  • FIND clause selects nodes by supertag type
  • WHERE clause filters on name or field values with operators: =, !=, >, <, ~ (contains), LIKE
  • CONNECTED TO clause traverses graph relationships to related nodes
  • VIA <field> modifier for traversal through specific typed edges
  • RETURN clause projects specific fields including dot-notation (person.name)
  • Multi-hop traversal: chain CONNECTED TO clauses for complex graph queries
  • --explain flag shows execution plan without running the query
  • --format json|csv|table output formats, --limit for result capping
  • tana_graph_query MCP tool with same capabilities for AI agents
  • Available in all modes (full, slim, lite)
  • 4-stage pipeline: Tokenizer → Parser → Planner (validates tags/fields) → Executor
  • Contextual error messages with fuzzy-matched suggestions for typos

• Embedding Maintenance & Diagnostics (F-106) - Tools for managing embedding health at scale

  • embed maintain compact — merge fragmented LanceDB storage for faster queries
  • embed maintain stale — detect and remove orphaned embeddings for deleted nodes
  • embed maintain rebuild — full reindex from scratch
  • embed stats — detailed embedding statistics (count, staleness, fragmentation, model info)
  • embed stats --format json for machine-readable diagnostics
  • Integrated into embed maintain umbrella command for one-step maintenance

• Graph-Aware Embeddings (F-104) - Enrich embeddings with supertag type and field context

  • embed generate --graph-aware (default: enabled) prepends [Type: #tag] [Field: value] to node text before embedding
  • embed generate --no-graph-aware to use legacy ancestor-based contextualization
  • embed generate --enrichment-preview <nodeId> to preview enriched text for a single node
  • search --semantic --type-hint <tag> enriches queries with type prefix for better typed results
  • tana_semantic_search MCP tool gains typeHint parameter
  • Token-aware truncation keeps enriched text within BGE-M3's 512 token limit
  • Per-supertag customization via ~/.config/supertag/embed-enrichment.json
  • Backward compatible: existing embeddings work, re-generate to benefit from enrichment

• Schema Analysis (F-101) - Detect schema quality issues across supertag definitions

  • supertag schema audit CLI command with --severity, --detector, --tag, --format
  • 7 built-in detectors: orphan-tags, low-usage, duplicate-fields, type-mismatch, unused-fields, fill-rate, missing-inheritance
  • Severity levels: critical, warning, info — filter with --severity warning
  • tana_schema_audit MCP tool for AI-driven schema analysis