Nesso

An app for building typed knowledge graphs for active learning.

Website · Try it · Docs · Releases

What it does

Nesso is an interactive concept map where nodes are ideas and edges are typed semantic relations. You draw connections between concepts, pick the relation (e.g. causes, requires, subtype-of), and each concept carries spaced-repetition state. Socrates, a Socratic AI mentor, reads the current graph and your selection, then probes your understanding through questions rather than explanations.

Warning

Early alpha. The typed graph and spaced-repetition review work today; the Socratic mentor is still being built and is not usable with the default in-browser model (a stronger model via an OpenAI-compatible endpoint, e.g. Ollama, works far better). Expect breaking changes.

Features

• Typed knowledge graph: 52 semantic relations across 8 categories, with inverse pairs; each type renders with a distinct line style and glyph
• Spaced-repetition review: FSRS scheduling via ts-fsrs; rate Again / Hard / Good / Easy
• Socratic AI mentor: context-aware dialogue that probes rather than explains; runs in-browser on WebGPU (no API key) or against any OpenAI-compatible endpoint (Ollama or cloud)
• Multi-graph workspace: create and switch between graphs; persisted in IndexedDB (web) and mirrored to .json files on disk (desktop)
• Cross-platform: web app at app.nesso.how plus a Tauri v2 macOS desktop build

Quick start

Prerequisites: Node 20+, pnpm 10+ (via corepack enable), and a Rust toolchain for the desktop build.

pnpm install
pnpm dev          # web app at http://localhost:5173
pnpm dev:desktop  # Tauri v2 desktop shell

pnpm install builds the workspace packages automatically (via prepare). To build for production:

pnpm build          # web bundle
pnpm build:desktop  # desktop binary

See CONTRIBUTING.md for commit conventions, branch naming, and the PR workflow.

Project structure

src/
  components/     UI components (read state via useGraphStore)
  store/graph.ts  single Zustand store (nodes, edges, selection, settings)
  llm/            mentor transports (web-llm + OpenAI-compatible fetch)
  data/           edge type registry, seed graphs
  types/graph.ts  shared TypeScript types
src-tauri/        Tauri v2 Rust shell (conf, capabilities, icons)
packages/
  relation-types/ @nesso-how/relation-types: shared semantic vocabulary
  types/          @nesso-how/types: shared TypeScript types
  formats/        @nesso-how/formats: graph JSON serialize/deserialize
  graph/          @nesso-how/graph: embeddable read-only graph React component
  mcp/            @nesso-how/mcp: MCP server for LLM clients
docs/             Starlight docs site, published at nesso.how/docs

Architecture

Nesso is a React 18 + Vite + TypeScript single-page app, optionally wrapped by Tauri v2 for a native desktop shell. All app state lives in a single Zustand store (src/store/graph.ts), and components subscribe via selectors with no prop drilling. Graph data persists to IndexedDB (web) and is dual-written to a workspace folder of .json files on desktop (with file watch for external edits); UI chrome to localStorage.

The canvas is built on React Flow via @nesso-how/graph (NessoEdge, ConceptNodeBody); the app adds an interactive ConceptNode wrapper for inline edit and connection handles. Each edge renders its semantic relation as a distinct line style plus an SVG glyph. Every node carries FSRS scheduling fields (stability, difficulty, due, lastRating) consumed by the Review overlay.

The AI mentor in src/llm/ supports two transports behind a unified message shape: a local WebGPU engine (Qwen2.5 1.5B) and any OpenAI-compatible chat/completions endpoint. On every send the system prompt is rebuilt from the live store, so the model always sees the current graph snapshot, selection, and a focal neighbourhood.

The repo is a pnpm workspace monorepo. Shared semantic vocabulary lives in packages/relation-types and is consumed by both the app and an MCP server in packages/mcp that exposes Nesso's relation types and documentation to MCP-capable LLM clients.

Packages

Package	Purpose
@nesso-how/relation-types	Shared semantic relation vocabulary and TypeScript types
@nesso-how/types	Shared TypeScript types: graph, node, edge, settings, FSRS
@nesso-how/formats	Graph serialization formats: JSON serialize/deserialize
@nesso-how/graph	Embeddable <NessoGraph /> React component for docs and external apps
@nesso-how/mcp	MCP server exposing Nesso's relation vocabulary and docs to LLM clients

Contributing

Bug reports, feature ideas, and PRs are welcome on GitHub Issues. Start with CONTRIBUTING.md.

License

Copyright © 2026 Omar Desogus. Licensed under the MIT License. See LICENSE.