NoteConnection

[](https://www.npmjs.com/package/noteconnection) [](https://github.com/Jacobinwwey/NoteConnection/blob/main/LICENSE) [](https://github.com/Jacobinwwey/NoteConnection/releases/latest) [](https://jacobinwwey.github.io/NoteConnection/) **A local-first knowledge graph, learning workspace, and RAG runtime for Markdown knowledge bases.** [Root README](https://github.com/Jacobinwwey/NoteConnection/blob/main/README.md) | [中文文档](../zh/README.md) | [中文根 README](https://github.com/Jacobinwwey/NoteConnection/blob/main/README_zh.md) | [Quick Start](#quick-start) | [Feature Tour](#feature-tour) | [Architecture](#architecture) | [CLI](#cli-reference) | [Documentation](#documentation) | [Acknowledgments](#acknowledgments)

What It Is

Unlock the structure of your knowledge.

NoteConnection is a high-performance standalone system that transforms unstructured Markdown knowledge bases into directed knowledge graphs, learning paths, and grounded answers.

Unlike traditional network views that show a dense web of links, NoteConnection focuses on hierarchy, learning paths, dependency structure, and source-grounded exploration. It is designed for large local knowledge bases, works independently of any specific note-taking app, and now ships as a browser/server runtime, Tauri desktop app, Godot Path Mode renderer, and Tauri Android build.

Homepage Guide

Need	Start here
Install or run the app	Quick Start
Understand the main product surfaces	Three Ways to Use NoteConnection
See the restored detailed feature walkthrough	Feature Tour
Understand the code owners and runtime flow	Architecture
Configure a knowledge base	Configuration
Use the command line	CLI Reference
Read long-form docs	Documentation
Check recent releases	Release Notes

Current Architecture Snapshot

This README is intentionally not the mainline architecture ledger. The previous dated architecture-status blocks were removed from the front page so the README stays useful as a product and contributor entry point.

Current state in brief:

• Knowledge Workspace uses scoped retrieval, grouped knowledge hits, right-pane source focus, matched-span highlighting, conversation status visibility, and graph-aware answer composition.
• RAG path is TypeScript-native: retrieval, bounded graph context assembly, sufficiency/release review, citations, memory actions, and public-answer contraction stay inside the local runtime.
• Graph substrate is real code: KnowledgeAtom, RelationEdge, TemporalEdge, path queries, mastery paths, session state, and export bundles are part of the implementation.
• Compatibility is preserved through legacy assistantMessage, typed assistantBlocks, app_config.toml migration, Markdown reader fallback, and runtime-first packaging.
• Architecture pressure remains in large owners such as src/server.ts, src/learning/KnowledgeLearningPlatform.ts, src/frontend/workspace_panes.js, and src/frontend/agent_workspace.js. Future work should extract around real invariants, not import another broad orchestration framework.

Detailed progress tracking belongs in:

• Development Progress Dashboard
• Agent Knowledge Workspace Graph Preview and Review Closure
• Knowledge Workspace and DAG Alignment Plan

Quick Start

Desktop system dependencies

Platform	Required dependencies
Linux	libwebkit2gtk-4.1-dev, libgtk-3-dev, libsoup3.0, libjavascriptcoregtk-4.1-0 (Ubuntu/Debian: sudo apt install libwebkit2gtk-4.1-dev libgtk-3-dev libsoup-3.0-dev patchelf)
macOS	No additional dependencies; system WebKit is included
Windows	Edge WebView2 Runtime (pre-installed on Windows 11; Windows 10 may need manual install)

Linux Wayland users: Godot Path Mode requires GDK_BACKEND=x11 on pure Wayland compositors. The launcher sets this automatically when XDG_SESSION_TYPE=wayland is detected.

Option 1: install a desktop release

Download the latest installer or package from Releases.

Release assets currently include Windows installers, macOS DMG, Linux AppImage/deb, and Android APK.

Option 2: run from npm

npx noteconnection

Option 3: install globally

npm install -g noteconnection
noteconnection

Option 4: develop locally

git clone https://github.com/Jacobinwwey/NoteConnection.git
cd NoteConnection
npm install
npm start

The development server runs at http://localhost:3000.

For GPU-enabled Tauri development on Windows:

npm run tauri:dev:mini:gpu

Use that script instead of appending --gpu to another npm command.

Option 5: Android

NoteConnection supports Android through Tauri Android. The older Capacitor APK path is deprecated and retained only as historical reference.

Prerequisites:

• Node.js LTS
• Java JDK 21 or newer
• Android SDK configured through ANDROID_HOME or Android Studio

npm run tauri:android:init
npm run tauri:android:dev
npm run tauri:android:build

For a universal APK:

npm run tauri:android:build:universal

Three Ways to Use NoteConnection

1. Knowledge Graph Workspace

Load a Markdown folder, build a graph, switch between force-directed and DAG views, inspect focus neighborhoods, and open matching source documents.

Basic workflow:

1. Choose a folder from Knowledge_Base or configure your own vault path.
2. Click Load.
3. Use DAG layout for hierarchy, force-directed layout for clusters, and Canvas for large graphs.
4. Click a node to enter Focus Mode and inspect its context.

2. Knowledge Workspace RAG

Ask scoped questions against the current knowledge base. The answer path uses grouped knowledge points, citations, graph context, sufficiency checks, and release review while keeping the public response to one user-facing answer.

The current implementation is designed around RSE-style evidence shaping and document augmentation: matched nodes are not treated as isolated snippets; they can be enriched by bounded neighboring context, source spans, graph paths, and review gates before an answer is released.

3. Path Mode and Guided Learning

Generate structured learning paths from graph topology. Path Mode can run through the web UI and through the Godot desktop renderer via PathBridge on ws://localhost:9876.

Why A Knowledge Graph?

Plain keyword search retrieves documents. NoteConnection tries to expose structure:

• prerequisite and successor relationships;
• relation paths between concepts;
• temporal and scoped evidence;
• focus neighborhoods around a selected node;
• learning routes reusable by the UI and agent workflows.

This makes the graph useful both for visual exploration and for grounded answer construction.

Feature Tour

1. Visualization and layout

• Structure over chaos: Switch between Force-Directed physics and DAG hierarchical layouts. The DAG layout identifies prerequisites and next steps so concepts are arranged in logical layers.
• Dual rendering engine: Switch between SVG for high-fidelity interaction and Canvas for large graphs with 10,000+ nodes.
• Interactive Focus Mode: Click a node to isolate it and its context. Focus Mode supports freeze-on-select behavior, adjustable vertical/horizontal spacing, stable exit behavior, and random focus discovery.
• Offline-first assets: D3, KaTeX, Marked, Mermaid, JSZip, and related frontend libraries are served from local assets so the core graph reader remains usable without internet access.

2. Intelligence and inference

• Hybrid inference engine: Combines statistical probability (P(A|B)) and vector similarity (TF-IDF) to infer hidden dependencies without requiring external AI APIs.
• Scalable clustering: Aggregates thousands of nodes into high-level concept bubbles based on folder structure or tags.
• Graph-aware retrieval: Knowledge Workspace ranking can use local hybrid signals, vector signals, bounded graph distance, path confidence, temporal invalidity, and relation intent.

3. Path Mode: structured learning

• Curriculum generation: Transform a graph into a linear learning path.
• Domain learning: Master an entire concept cluster through topological ordering.
• Diffusion learning: Find an efficient path toward a specific target using shortest-path and prerequisite context.
• Hybrid rendering: Connect the TypeScript graph runtime to a Godot 4.3 desktop renderer through WebSocket while retaining web compatibility.
• Learning strategies: Choose foundational/base-first or core/importance-first sorting based on learning style.

4. Performance and control

• Parallel processing: Uses Node.js worker_threads to distribute keyword matching and graph-related heavy work.
• Simulation controls: Speed/damping sliders and freeze-layout controls keep large graph views inspectable.
• Hover lock: Hovering over a node temporarily locks its position so connections can be inspected without drift.

5. NoteMD AI Document Workbench

• Integrated NoteMD module: src/notemd/* provides an Obsidian-decoupled processing stack: LLM provider abstraction, prompt manager, batch/file processors, translation, Mermaid/formula fixers, and duplicate detection.
• One-Click Extract workflow: The embedded NoteMD window can chain concept extraction, title-based batch generation, and batch Mermaid repair. Generated files land in a KB subfolder named after the source file.
• TOML-backed API profile: Embedded NoteMD reads and writes API settings through app_config.toml under [notemd] and [notemd.api].
• CLI compatibility: Core workflows are available through noteconnection notemd ..., including settings show, settings set-api, one-click-extract, batch-generate, batch-mermaid-fix, and fix-mermaid.
• API surface: /api/notemd/* covers settings, file/folder processing, workflow orchestration, translation, content generation, concept extraction, duplicate checks, and cancellation.
• Desktop and bridge access: Tauri menu/IPC and bridge routing open NoteMD from web/Tauri/Godot-connected workflows.
• Safety defaults: File operations are constrained by KB-root sandbox checks, with SSE progress and cancellation support for long-running work.

Architecture

flowchart LR
  A["Markdown knowledge base"] --> B["Graph build pipeline"]
  B --> C["Knowledge graph store"]
  C --> D["Graph visualization"]
  C --> E["Scoped retrieval"]
  E --> F["Graph context assembly"]
  F --> G["Answer sufficiency and release review"]
  G --> H["One public answer with citations"]
  C --> I["Path Mode and mastery workflows"]

Core owners:

Layer	Main paths	Responsibility
Server and routes	src/server.ts, src/routes/	HTTP API, static serving, diagnostics, modular route dispatch
Graph core	src/core/, src/backend/	graph construction, layout/path engines, workers, bridge contracts
Learning runtime	src/learning/	scoped retrieval, conversation, graph context, mastery, quality, memory policy
Frontend workspace	src/frontend/	graph UI, Knowledge Workspace panes, source focus, runtime bridge
Desktop/mobile shell	src-tauri/, path_mode/	Tauri packaging, sidecars, Godot Path Mode, Android runtime
Documentation	docs/	Diataxis docs, release notes, bilingual guides, architecture records

Backend

• GraphBuilder manages the pipeline from file reading to graph construction.
• Worker threads offload keyword matching and text analysis so the main thread stays responsive.
• StatisticalAnalyzer, VectorSpace, and HybridEngine combine co-occurrence, TF-IDF, cosine similarity, and directed edge inference.

Frontend

• D3/SVG handles high-fidelity interaction.
• Canvas handles large graph rendering.
• Web workers keep path/layout work off the UI thread.
• Knowledge Workspace panes keep source focus, evidence rendering, learning paths, and graph previews in one workspace.

Desktop bridge

• PathBridge exposes internal graph state over WebSocket (ws://localhost:9876).
• Godot Path Mode acts as a renderer and interaction surface; heavy graph logic remains in the TypeScript runtime.
• Godot paths must keep PNG/materialized render boundaries and avoid direct SVG assumptions.

CLI Reference

npm start -- --path "<path_to_knowledge_base>" [options]

Option	Description	Default
--path	Absolute path to the folder containing Markdown files	Knowledge_Base
--gpu	Enable GPU/WebGL acceleration for layout and vector calculations	auto when supported
--no-gpu	Disable GPU acceleration and force CPU	false
--static	Enable backend-only static mode with frozen frontend layout	false
--workers	Worker thread count	numCPUs - 1

Examples:

npm start -- --path "C:/Users/MyName/Documents/MyNotes"
npm start -- --path "E:/Knowledge/ObsidianVault" --gpu
npm start -- --path "E:/Knowledge/ObsidianVault" --no-gpu

CLI runs generate unique data files such as data_cli_{kb_name}_{time}.js to preserve the original data.js. When the server starts, it automatically serves those files to the frontend.

Configuration

Runtime configuration is stored in app_config.toml.

Default Windows path:

%LOCALAPPDATA%/NoteConnection/app_config.toml

Minimal example:

knowledge_base_path = "E:/Knowledge_project/NoteConnection_app/Knowledge_Base"
user_language = "en"

[multi_window]
single_window_mode = true
hide_tauri_when_pathmode_opens = true
restore_tauri_when_pathmode_exits = true
confirm_before_full_shutdown_from_godot = true
sync_language = true

[frontend_settings.reading]
mode = "window"
markdown_engine = "auto" # "legacy" | "pulldown" | "auto"
chunk_block_size = 36
prefetch_blocks = 8
index_cache_ttl_sec = 1800
max_doc_bytes = 100663296

More configuration details:

• English app_config guide
• Config template

Markdown Reader Protocol

• markdown_engine = "auto" prefers pulldown-cmark and falls back to the legacy renderer on failure.
• Tauri reader and Godot reader consume the same sidecar Markdown protocol: index, chunk, resolve-node, and resolve-wiki.
• Large files are loaded incrementally instead of requiring one full Markdown payload.
• Mermaid fences must start on their own line. Use npm run verify:markdown:mermaid:fence -- Knowledge_Base/testconcept before release-sensitive changes.

Build And Test

npm install
npm run build
npm run build:vite
npm test
npm run docs:diataxis:check
npm run docs:site:build

Desktop and mobile builds:

npm run tauri:dev
npm run tauri:build
npm run tauri:android:init
npm run tauri:android:dev
npm run tauri:android:build

Build notes:

• Electron desktop packaging was removed on 2026-03-01.
• npm run tauri:build is the default desktop package path.
• npm run tauri:build:full is explicit opt-in for packaging generated graph assets.
• npm run verify:lfs:policy, npm run verify:sidecar:supply, and SBOM gates protect release packaging.

Documentation

• Documentation hub: ../index.md
• Root English README: README.md
• Root Chinese README: README_zh.md
• Chinese docs mirror: ../zh/README.md
• User manual: User_Manual.md / ../zh/User_Manual.md
• Interface document: Interface Document.md / ../zh/Interface Document.md
• Release notes: ../release_notes_v1.8.0.md
• GitHub Pages docs: jacobinwwey.github.io/NoteConnection

Security And Privacy

• Graph building and local retrieval run on the user's machine.
• LLM-backed features use user-configured providers and should be treated as optional runtime integrations.
• Do not commit local vaults, app_config.toml, provider keys, generated private evidence, or machine-specific sidecar overrides.
• Release workflows include SBOM, sidecar, LFS, migration, docs, mobile, and runtime evidence gates.

Release Notes

README keeps only a compact release summary. Full release history belongs in GitHub Releases and docs/release_notes_*.md.

Recent releases:

• v1.8.0 - Knowledge Workspace RSE/document-augmented RAG, graph-conditioned answer composition, Agent Workspace UI/status improvements, runtime probes, release governance, and multi-platform assets.
• v1.7.0 - Startup acceleration closure, multi-platform validation, and learning roadmap foundation.
• v1.6.7 - Docs governance cleanup and GitHub Pages stabilization.
• v1.6.6 - Unified provider runtime and TOML settings consolidation.

Acknowledgments

NoteConnection has benefited from many open-source projects and local reference mirrors. These acknowledgments mean design influence, implementation reference, runtime dependency, or tooling inspiration depending on the project; they do not imply endorsement by the listed maintainers.

• GitNexus - README information architecture, repo context, staleness, and agent-consumable knowledge graph ideas.
• obsidian-NotEMD - NoteMD workflows, provider settings, and Markdown enhancement UX.
• Obsidian Smart Connections - vault-aware semantic retrieval and local knowledge interaction patterns.
• DeepTutor - tutor/workspace concepts and agent-native learning product references.
• AnythingLLM - local RAG workspace and document-chat product references.
• Cherry Studio - desktop AI workspace, provider configuration, and user-facing model operations.
• Fast-GraphRAG - graph-RAG ingestion/query design input.
• Graphiti - temporal knowledge graph and evolving context design input.
• Neo4j GraphRAG Python - graph-backed retrieval and explainable query contracts.
• OpenAI Codex - agent workspace, local execution, and tool-bound development workflow references.
• enterprise_agent_platform - enterprise agent runtime and pipeline separation references.
• AhaDiff - diff learning, review, and repository intelligence references.
• DSPy - typed LM programs, evaluation, and optimizer-loop design ideas.
• Guidance - constrained generation and structured output contract ideas.
• Semantic Kernel - plugin/orchestration boundary references.
• LangChain - orchestration, tool, and evaluation surface references.
• LiteLLM - provider routing and gateway design references.
• Tauri - desktop and Android application shell.
• Godot Engine - Path Mode renderer foundation.
• Readest - cross-platform reader and Tauri product references.
• Lorien - Godot canvas/whiteboard interaction reference.
• D3, Mermaid, KaTeX, Marked, and JSZip - frontend rendering and document-processing foundations.

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0-only).