@nesso-how/mcp 0.1.0-alpha.32 → 0.1.0-alpha.33
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -3,8 +3,8 @@
|
|
|
3
3
|
{
|
|
4
4
|
"slug": "guides/ai-mentor",
|
|
5
5
|
"title": "AI mentor (Socrates)",
|
|
6
|
-
"description": "How the Socratic mentor works,
|
|
7
|
-
"markdown": ":::caution\nThis is the part of Nesso with the most potential and the most room to grow. Small models tend to drift out of the Socratic role and start explaining rather than questioning. A larger remote model works noticeably better. Improving the mentor is where most of the future work is headed.\n:::\n\nClick the **Socrates** bubble in the bottom-right of the canvas to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n##
|
|
6
|
+
"description": "How the Socratic mentor works, connecting a model, persona, and graph-aware context.",
|
|
7
|
+
"markdown": ":::caution\nThis is the part of Nesso with the most potential and the most room to grow. Small models tend to drift out of the Socratic role and start explaining rather than questioning. A larger remote model works noticeably better. Improving the mentor is where most of the future work is headed.\n:::\n\nClick the **Socrates** bubble in the bottom-right of the canvas to start a dialogue. The mentor reads your current graph and selection, and replies with **questions rather than explanations**. The goal is to surface what you understand and where the gaps are.\n\n## How it works\n\nEvery send rebuilds a system prompt from the live store: a snapshot of up to ~60 concept nodes, sorted weakest-first via **`nodeStrength()`** ([`context.ts`](https://github.com/nesso-how/nesso/blob/main/src/llm/context.ts)): **FSRS stability** dominates ordering, **Again/Hard** nudge weaker items up, overdue is only a slight tie-break. Each node line lists stability (`s=` days), days since last review, last FSRS rating, and `DUE` when the scheduler says so, plus typed edges (~2× the node allowance), current selection when any, and focal-neighbour context when a node is selected (`Focus:` / `Related:` lines). The conversation history stays in the mentor card and is reset when you switch graphs or click **New chat**.\n\nChat history is **not persisted**. It lives only for the current panel session.\n\n## Connecting a model\n\nThe mentor is **experimental** and runs against any OpenAI-compatible `chat/completions` endpoint. Configure it under **Settings -> AI**: base URL, model, and an optional API key.\n\nThe default targets a local [Ollama](https://ollama.com/) instance (`http://localhost:11434/v1`, model `gemma3:4b`). Install Ollama, pull a model, and the mentor works with nothing leaving your machine. Any hosted OpenAI-compatible endpoint works too; set the API key it expects.\n\nThere is **no built-in in-browser model**. Nesso previously bundled a small WebGPU model, but it was too small and slow to be useful and has been removed. Until a reachable endpoint is configured, the chat input stays disabled and the mentor shows a short setup hint.\n\n### Reaching local Ollama from the hosted app\n\nIf you use the hosted web app over HTTPS, requests to `http://localhost:11434` are allowed (localhost is exempt from mixed-content blocking), but Ollama still rejects the cross-origin request unless you allow the app's origin: start it with `OLLAMA_ORIGINS=https://app.nesso.how` (or run the desktop build, where this does not apply).\n\n## The Socratic persona\n\nThe system prompt (`getMentorBase` in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx)) shapes Socrates:\n\n- One short question per turn by default; explain only enough to frame the question.\n- Replies are soft-capped at ~200 words (hard cap via output tokens).\n- No graph edits proposed in dialogue. Socrates probes; the user edits.\n- No emojis, flattery, JSON, or pseudo-graph markup. Sparse `*asterisks*` on key terms.\n- Replies in the active UI language (English or Italian). Snapshot tokens stay **English-shaped** (`s=…d`, `…d since review`, etc.), with the same spelling in the legend for every locale.\n\nIf you want a more permissive coach, fork the persona. It is plain text in the component and easy to swap.\n\n## Opening message\n\nWhen the panel opens, the mentor sends itself a short synthetic **user** turn so its first message reflects what's selected:\n\n- **A concept node selected:** opens on that concept and one of its relations.\n- **An edge selected (no node):** opens on the typed relation between its endpoints.\n- **Nothing selected:** opens on a weak spot in the graph (low stability plus weak **last reviews** (Again/Hard or a long gap); **DUE** is extra scheduler context).\n\nClick **New chat** in the header to reset history and request a fresh opener.\n\n## Context size\n\nLarge graphs are summarised, not truncated abruptly. The weakest-reviewed nodes appear first (`nodeStrength`), so the verbatim slice emphasises instability and risky last ratings; tail nodes are omitted with a short count only. Edges have a ~2x allowance over node count. These limits live in [`MentorPanel.tsx`](https://github.com/nesso-how/nesso/blob/main/src/components/mentor/MentorPanel.tsx) as `MAX_SNAPSHOT_NODES` and `MAX_SNAPSHOT_EDGES`.\n\n## Privacy\n\n- **Local Ollama:** prompts and responses go only to your own machine; nothing leaves the device.\n- **Hosted endpoint:** the system prompt (graph snapshot) and chat history are sent to whichever endpoint you configured, each turn. The usual provider-side logging applies.\n\nYour graph itself always stays on your device regardless of the endpoint."
|
|
8
8
|
},
|
|
9
9
|
{
|
|
10
10
|
"slug": "guides/concepts-and-inspector",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
"slug": "guides/getting-started",
|
|
23
23
|
"title": "Getting started",
|
|
24
24
|
"description": "How to run Nesso locally or on the web.",
|
|
25
|
-
"markdown": "Nesso is available as a hosted web app, a macOS desktop app, and as open-source code you can run locally. All data is stored in your browser or on your machine; nothing is sent to external servers unless you configure a remote AI endpoint.\n\n## Web app\n\nOpen [app.nesso.how](https://app.nesso.how) in your browser. The app works offline after the first load
|
|
25
|
+
"markdown": "Nesso is available as a hosted web app, a macOS desktop app, and as open-source code you can run locally. All data is stored in your browser or on your machine; nothing is sent to external servers unless you configure a remote AI endpoint.\n\n## Web app\n\nOpen [app.nesso.how](https://app.nesso.how) in your browser. The app works offline after the first load and runs in any modern browser. The AI mentor is optional and needs an OpenAI-compatible endpoint (see [Picking an AI backend](#picking-an-ai-backend)).\n\n## Desktop app (macOS)\n\nA pre-built alpha installer is published on [GitHub Releases](https://github.com/nesso-how/nesso/releases). Download the universal `.dmg` — it runs on both Apple silicon and Intel Macs — and open it.\n\n:::caution\nThe app is not signed with an Apple developer certificate. macOS will block it on first launch. After installing, run this command in the terminal to remove the quarantine flag:\n\n```sh\nxattr -cr /Applications/Nesso.app\n```\n\nThen open the app normally.\n:::\n\nThe desktop app **updates itself**: on launch it checks GitHub Releases and, when a newer build is available, offers to install it and relaunch. Auto-updates begin once you are on a build that ships the updater (`v0.1.0-alpha.25` or later), so that first version still needs a one-time manual download.\n\n## Run from source\n\nRequires [Node.js](https://nodejs.org/) and [pnpm](https://pnpm.io/).\n\n```sh\ngit clone https://github.com/nesso-how/nesso.git\ncd nesso\npnpm install\npnpm dev\n```\n\nFor a desktop build, [Rust](https://rustup.rs/) is required as well:\n\n```sh\npnpm build:desktop\n```\n\n## Picking an AI backend\n\nThe Socratic mentor is **experimental** and uses any OpenAI-compatible `chat/completions` endpoint: a local [Ollama](https://ollama.com/) instance, an OpenAI-compatible proxy, or a hosted provider. There is no built-in in-browser model, so configure an endpoint under **Settings -> AI** (`⌘,` / `Ctrl+,`) or the mentor stays disabled.\n\n:::caution\nAPI keys are stored client-side in `localStorage`. Do not self-host the web app publicly with secrets baked in.\n:::\n\n### Local setup with Ollama\n\nRun [Ollama](https://ollama.com/) locally, then pull a small instruction-tuned model:\n\n```sh\nollama pull gemma3:4b\n```\n\nIn **Settings -> AI**, set:\n\n- Base URL: `http://localhost:11434/v1`\n- Model: `gemma3:4b` (or `llama3.2:3b`, `qwen3:8b`; presets are shown in Settings)\n- API key: leave empty\n\nSettings auto-probes the endpoint and offers a **Pull** button if the model is missing. Prompts and responses stay on your machine.\n\nWhen using the hosted web app over HTTPS, allow its origin in Ollama so the browser request is not blocked by CORS: start Ollama with `OLLAMA_ORIGINS=https://app.nesso.how`. (Requests to `localhost` are exempt from mixed-content blocking, so only CORS needs configuring.)\n\n## Keyboard shortcuts\n\n| Shortcut | Action |\n| ---------------------- | ------------------------------ |\n| `?` | Show shortcuts dialog |\n| `⌘,` / `Ctrl+,` | Settings |\n| `⌘K` / `Ctrl+K` | Search concepts |\n| `N` | Add concept at viewport centre |\n| `R` | Open review mode |\n| `⌘Z` / `Ctrl+Z` | Undo |\n| `⌘⇧Z` / `Ctrl+Shift+Z` | Redo |\n| `Del` / `Backspace` | Delete selection |\n| `⌘A` / `Ctrl+A` | Select all |\n| `⌘X` / `Ctrl+X` | Cut selection |\n| `⌘C` / `Ctrl+C` | Copy selection |\n| `⌘V` / `Ctrl+V` | Paste |\n| `↑` `↓` `←` `→` | Nudge selected concept |\n| `Shift` + arrows | Nudge selected concept (large) |\n| `Esc` | Close dialog |\n\nHold `⌘` / `Ctrl` to add to a selection; drag on empty canvas to marquee-select."
|
|
26
26
|
},
|
|
27
27
|
{
|
|
28
28
|
"slug": "guides/mcp-integration",
|
|
@@ -34,7 +34,7 @@
|
|
|
34
34
|
"slug": "guides/review-mode",
|
|
35
35
|
"title": "Review mode",
|
|
36
36
|
"description": "Spaced-repetition review of your concepts with FSRS, how it queues cards, asks AI recall questions, and reschedules.",
|
|
37
|
-
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts whose **FSRS** state says they are due, asks you a recall question, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Asks a recall question** generated by the AI mentor (local or remote; the same backend you configured in [AI mentor](./ai-mentor/)). The question uses the concept's title, its relations, and the elaboration fields (definition, examples, notes). It is prompted to **not paraphrase the definition** so active recall still works.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's typed relations, examples, and image (the same panel you see in the Inspector).\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g. `< 1d`, `4d`, `2mo`).\n\nFSRS then updates `stability` and `difficulty`, schedules the next `due` date, and Review advances to the next card. Done with the queue, the overlay closes; you're caught up.\n\nIf the AI backend is unavailable (no
|
|
37
|
+
"markdown": "Press `R` (or open the **Review** pill in the top bar) to start a focused study session. Review surfaces concepts whose **FSRS** state says they are due, asks you a recall question, and reschedules them based on how you self-rate.\n\nNesso uses [FSRS](https://github.com/open-spaced-repetition/ts-fsrs), a modern open-source successor to the SM-2 / Anki algorithm.\n\n## What gets reviewed\n\nEach concept node carries its own FSRS state: `stability`, `difficulty`, `due`, `lastReview`, `lastRating`, and friends. A node is **due** when `due <= now`. New, unrated concepts default to `due = 0`, which means they show up immediately the first time you open Review.\n\nThe session queue is built fresh every time you open the overlay: all due nodes, sorted by urgency, in random order within the same due bucket.\n\n## Flow\n\nFor each due concept, Review:\n\n1. **Asks a recall question** generated by the AI mentor (local or remote; the same backend you configured in [AI mentor](./ai-mentor/)). The question uses the concept's title, its relations, and the elaboration fields (definition, examples, notes). It is prompted to **not paraphrase the definition** so active recall still works.\n2. **Waits for you to think**, then click **Reveal** (or press `Space`).\n3. **Reveals** the concept's typed relations, examples, and image (the same panel you see in the Inspector).\n4. **You rate** how it felt: `Again`, `Hard`, `Good`, `Easy`. Each button shows the **predicted next interval** under it (e.g. `< 1d`, `4d`, `2mo`).\n\nFSRS then updates `stability` and `difficulty`, schedules the next `due` date, and Review advances to the next card. Done with the queue, the overlay closes; you're caught up.\n\nIf the AI backend is unavailable (no endpoint configured or unreachable), Review still works. It falls back to showing the concept title without a generated question.\n\n## Tuning FSRS\n\nUnder **Settings -> Review**:\n\n| Setting | What it does | Range |\n| -------------------- | ---------------------------------------------------------------------------------------------------- | ----------- |\n| **Target retention** | Probability of correctly recalling a concept at its next review. Higher means more frequent reviews. | 70% to 97% |\n| **Max interval** | Longest interval FSRS can schedule, in days. Caps how far into the future a card can be pushed. | 1 to 36,500 |\n\nThe defaults (90% retention, 100-year cap) match the FSRS reference defaults. Lower the retention if you're comfortable forgetting more in exchange for fewer reviews; raise the max interval if you want long-term cards to keep stretching out.\n\n## Keyboard shortcuts\n\n| Key | Action |\n| ----------------- | ------------ |\n| `Space` / `Enter` | Reveal |\n| `1` | Again |\n| `2` | Hard |\n| `3` | Good |\n| `4` | Easy |\n| `Esc` | Close review |\n\nNumeric keys only fire after the answer is revealed.\n\n## Tips\n\n- Add a **definition** in the Inspector's Notes tab. Even one short sentence per concept dramatically improves AI question quality, since the model can aim at a specific facet (pitfall, application, contrast) instead of asking something generic.\n- Pair concepts with **at least one typed edge** before reviewing them. Review questions lean on the relation graph for context; isolated nodes get vaguer questions.\n- The session count in the top bar reflects the original queue size. Cards rated `Again` that come back later increase the count past 100%; that is expected."
|
|
38
38
|
},
|
|
39
39
|
{
|
|
40
40
|
"slug": "introduction",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@nesso-how/mcp",
|
|
3
|
-
"version": "0.1.0-alpha.
|
|
3
|
+
"version": "0.1.0-alpha.33",
|
|
4
4
|
"description": "MCP server exposing Nesso knowledge graph tools to LLM clients",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -20,10 +20,9 @@
|
|
|
20
20
|
"dist"
|
|
21
21
|
],
|
|
22
22
|
"dependencies": {
|
|
23
|
-
"@cfworker/json-schema": "^4.1.1",
|
|
24
|
-
"@modelcontextprotocol/server": "^2.0.0-alpha.2",
|
|
25
23
|
"zod": "^4.4.3",
|
|
26
|
-
"@
|
|
24
|
+
"@modelcontextprotocol/server": "^2.0.0-alpha.2",
|
|
25
|
+
"@nesso-how/relation-types": "0.1.0-alpha.33"
|
|
27
26
|
},
|
|
28
27
|
"devDependencies": {
|
|
29
28
|
"@types/node": "^22.0.0",
|