Trailhead

Trailhead is a collaborative, AI-assisted Second Brain knowledge management application powered by Alibaba Cloud’s Qwen models.

Comment

Trailhead 🚀

1. 💡 Inspiration: The Death of Personal and Team Wikis

We have all been there: teams split between two painful extremes. On one side, personal note tools like Obsidian offer great individual workflows, but they remain isolated single-user silos—meaning knowledge is fragmented, duplicated, and locked on individual laptops. On the other side, centralized team wikis like Confluence quickly become graveyards of outdated documents because manually tagging, cross-linking, and updating information across team members is a tedious chore.

Inspired by Andrej Karpathy's "Local Librarian AI" concept, we wondered: What if we could combine local note-taking with a collaborative, self-healing team brain?

Instead of keeping knowledge locked in private silos or forcing developers to manually maintain shared documentation, what if everyone could write raw markdown locally while an autonomous AI compiler continuously organized, linked, and validated knowledge across the entire team?

That is Trailhead. It bridges local-first note-taking with a centralized AI engine, turning fragmented personal notes into a unified, collaborative, and self-healing knowledge base.

2. ⚙️ What It Does: Core Workflows & Features

Trailhead integrates three separate systems to form a seamless developer workspace:

  • Translucent Desktop App Shell: Built with React, TypeScript, and Tauri v2. It features a headless Tiptap text editor supporting rich markdown previewing, live rendering of interactive Mermaid.js diagrams, custom keyboard interceptors, and comment badges.
  • Smart Inline Auto-complete: While typing, pressing Ctrl + Space fetches context-aware completions using Qwen models and the wiki info.
  • The Ingestion & Graph Compiler: Built in Go. When you save a document, it runs a pipeline which triggers:
    1. Sensitivity Filter: Uses a high-fidelity Qwen system prompt to scan for leaked API keys, credentials, or PII, preventing sensitive information from entering the shared index.
    2. Semantic Embedding & Vector Search: Chunks the document and uses a vector database to find semantically related files.
    3. 1-Hop Neighbor Expansion: Traverses the database link-graph to aggregate related parent/child pages.
    4. Dynamic Linking & Extraction: Extracts entities (APIs, services, teams) and updates relations in the DB.
  • Wiki Health & Contradictions Dashboard: Our standout feature. In a collaborative vault, Alice might write that a service uses Port 8080, while Bob writes in a separate file that it uses Port 80. Trailhead automatically identifies these discrepancies, highlights them side-by-side on the dashboard, and allows users to resolve the conflict with a single click, rewriting the source files.
  • AI Chat Assistant: An agent equipped with custom tools to query document metadata, pull full note content, and perform vector semantic search.
  • Interactive Knowledge Graph: A React Flow diagram visualizing file and extracted concepts. Users can click nodes to immediately open notes.

3. 🛠️ How We Built It: Technical Architecture

The project is built as a microservices architecture coordinated locally:

  1. Frontend Client: React + TypeScript + Tauri v2 (Rust backend). Connects to Go via gRPC.
  2. Core Server: Go (Golang) server hosting a gRPC API. Interacts with PostgreSQL + pgvector container.
  3. Chat Agent: Python service utilizing FastAPI and LangGraph. Saves state checkpoints using PostgreSQL's AsyncPostgresSaver.
  4. AI Core: Alibaba Cloud (DashScope API) hosting:
    • text-embedding-v4 for embedding creation.
    • qwen3-coder-flash for code blocks, autocomplete, and markdown formatting.
    • qwen-plus-latest for sensitivity classification, structural entity extraction, contradiction detection, and the conversational agent.

4. 🧠 Challenges We Ran Into & How We Solved Them

  • Deterministic Pairwise Contradiction Checking: Comparing all chunks against each other would create $O(N^2)$ LLM calls. We resolved this by querying the database for candidate chunks using pgvector's cosine distance (<=>) with a distance threshold ($\le 0.35$). Only semantically similar chunks are sent to Qwen for contradiction verification, keeping API calls minimal and latency low.
  • Sensitivity Classification at the Edge: Securing personal information from sync queues without lag. We built a fast JSON-triage stage in Go that classifies text on the fly.
  • LangGraph Checkpointing on PostgreSQL: Coordinating conversational memory across a Python agent and a Tauri desktop application. We implemented FastAPI endpoints for history and session lifecycle management, directly querying and deleting checkpoints from the Postgres tables.

5. 🏆 Accomplishments We're Proud Of

  • A truly collaborative and self-healing wiki. Writing a note in one file can automatically surface conflicts with a note written by someone else months ago.
  • The interactive React Flow knowledge graph which lets you open files by double-clicking nodes and clarify concepts and definitions.
  • A highly responsive editor with inline Mermaid.js editing/preview, autocompletion, comments, support for links, images, and more! Very superior to Obsidian and Confluence without install plugins.
  • Full integration of the Qwen Cloud APIs across different task domains (classification, embeddings, structured JSON generation, coding, and tool use).

6. 📖 What We Learned

  • Qwen models are incredibly versatile: qwen3-coder-flash excels at FIM (Fill-in-the-Middle) autocompletion, while qwen-plus-latest handles complex reasoning tasks like contradiction checking and structured JSON generation with high fidelity.
  • Building offline-first desktop systems with Tauri v2 requires clean contract-based API designs (gRPC is perfect for this).
  • Fusing vector semantic search with explicit relational graphs (GraphRAG) yields vastly superior chat contexts than raw text chunking alone.

7. 🚀 What's Next for Trailhead

  • Local Fallback Mode: Embedding quantized Qwen models locally via Tauri sidecars when offline.
  • Visual Diagram-to-Code compilation: Let users sketch graph hierarchies in the UI and have Qwen generate the markdown files and folders automatically.
  • Advanced Graph Analytics: Showing centrality metrics in the Knowledge Graph to highlight key architectural files and dependencies.

Built With

Share this project:

Updates