Skip to content

feedback.md

Latest commit

 

History

History
53 lines (40 loc) · 2.59 KB

feedback.md

File metadata and controls

53 lines (40 loc) · 2.59 KB

HelixDB Feedback

What we built

Syncyphus - an Obsidian vault to HelixDB sync tool that parses Markdown notes, extracts wikilinks/tags, generates Gemini embeddings, and syncs to HelixDB.

Experience

Positives

  • Graph + Vector in one DB - Nice having Note nodes and LinksTo edges alongside embeddings in same system
  • Query compilation - HQL queries compile at deploy time, catching errors early
  • Dev workflow - helix push dev handles container/image rebuild cleanly
  • Python SDK quality - Better documented than Go SDK

Friction points

  1. Go SDK missing Content-Type header

    • The SDK sends requests without Content-Type: application/json, causing 415 errors with fresh HelixDB instances
    • Workaround: Use curl with explicit -H "Content-Type: application/json"
    • Fix: Add header in SDK or document the requirement

  2. Array vs object response ambiguity

    • Queries like getNoteByPath return {"note": [...]} - an array wrapped in object
    • Hard to know schema from debugging - need clearer docs or consistent wrapper format
    • Example: getAllNotes returns {"notes": [...]} but getNoteByPath returns {"note": [...]}

  3. Upsert semantics unclear

    • UpsertN requires existing node to update; throws "No value found" when not present
    • Documentation doesn't explain how to handle "create or update" pattern
    • Workaround: Use AddN (creates new) + separate update query

  4. Port conflicts on restart

    • helix push dev sometimes binds to 6970 instead of 6969 when port is in use
    • No way to force specific port - adds friction in dev workflow

  5. Default embedding generation

    • Notes created without explicit embedding field fail
    • No default value or optional field support in HQL schema types
    • Workaround: Only add embedding when embedder is available, accept null in code

  6. .obsidian folder included by default

    • Obsidian internal files synced as notes - should filter
    • No built-in ignore patterns

Suggestions for improvement

  1. SDK consistency - Ensure Go/Python/JS SDKs handle Content-Type header identically
  2. Response schema docs - Document whether queries return arrays or objects
  3. Upsert documentation - Better explain create-or-update pattern with code examples
  4. Dev experience - Add --force-port flag or clearer port allocation feedback
  5. Optional fields - Support nullable/optional fields in schema so embeddings can be omitted

Would we use it?

For a knowledge graph use case, yes - having graph + vector in one place is valuable. Need the SDK friction resolved first for production use.