CogniTree

AI-powered branching knowledge trees for Obsidian. Type a single concept ("democracy", "tree", "consciousness") and a polymathic-taxonomist LLM grows it into a deep, interconnected tree of notes — one branch at a time, up to tens of thousands of nodes.

Built around a prompt system (Discovery, Expansion, Connection Discovery, Deep Dive, Review Cards, Vault Cartography, plus a Batch Generation builder) and designed for large-scale scalability: incremental growth, Markdown+frontmatter storage, response caching, background indexing via Obsidian's metadataCache, and virtualized rendering.

Features

Tree interaction

Quick start

1. Install — copy main.js, manifest.json, styles.css into <vault>/.obsidian/plugins/cognitree/ and enable the plugin. (Or git clone and run npm run build.)
2. Set your API key — ribbon icon 🕸 Open CogniTree → ⚙ in the header → paste your key (defaults to DeepSeek + deepseek-v4-flash). To use another provider, pick it from the Provider dropdown — the endpoint and model list switch automatically (Ollama / LM Studio need no key).
3. Generate a tree — type democracy in the input and press Generate. The Discovery prompt creates the root + domain children as notes under CogniTree/Democracy/.
4. Explore — click a row to select (or use ↑ / ↓ to navigate with the keyboard and a live preview tooltip); use Expand (Expansion prompt), 💬 (Ask about this concept), 🔗 (Find connections), 💡 (write/refresh the note's deep dive), Batch expand (subtree to a depth), hover for the description preview, right-click for the context menu (ask, deep dive, review cards, copy, export, stats, duplicates, safe delete), double-click to open the note, and ⛶ Expand all / ⛁ Collapse / ♺ Index / 🧠 Review from the toolbar.
5. Fill the notes in and remember them — 💡 Deep dive or Deep dive subtree… writes real substance into each note; 🧠 Review (or right-click → Create review cards) turns them into spaced-repetition cards.
6. Or start from what you already have — run Grow a tree from existing vault notes and pick the note you're reading or one of your tags: CogniTree arranges those notes into a tree and links them (🔗) instead of copying them.

Example flow: democracy → Discovery → Political Science / Direct Democracy / Referendums → click Referendums → Expansion → Mandatory / Optional / Popular Initiative → 🔗 Find connections → link to Elections, Switzerland, Popular Sovereignty.

Settings

Mirrors the spec's PluginSettings:

Also: Clear cache (N cached generations), Build / Clear semantic index, and tree folder relocation.

The prompt system

The prompts from the spec are implemented verbatim in src/prompts.ts — plus follow-up, deep-dive, review-card and cartography prompts:

1. Discovery Prompt — "You are a polymathic taxonomist and knowledge graph engineer…" — 3–7 domains, 3–5 children each, complexity ratings, connection hints, suggested_starting_branch. Strict JSON schema.
2. Expansion Prompt — "You are a knowledge graph engineer specializing in deep taxonomic expansion…" — 5–10 granular children, sibling de-duplication context, can_expand + estimated_depth depth indicators.
3. Connection Discovery Prompt — "You are a knowledge graph analyst…" — ranked candidate vault notes, relationship_type (parent-of / related-to / contrast-with…), High/Medium/Low priority, suggestions for concepts to create.
4. Batch Generation Prompt — "You are a batch knowledge expansion specialist…" — complete subtree to a depth within a node budget (path-based hierarchical output). Builder only: no UI action sends it today — ⚡ Batch generates the subtree with repeated Expansion prompts, one branch at a time (ConceptGenerator.batch), which is what keeps the node budget and progress bar honest.
5. Follow-up (Ask) Prompt — "You are CogniTree Ask…" — a grounded tutor over the focused node's branch digest. Answers stay anchored in the digest (plus linked vault notes), keep Markdown short, and — when the answer proposes new sub-concepts — end with a ### Suggested children bullet list that the chat can adopt into the tree.
6. Deep Dive Prompt — "You are CogniTree Deep Dive…" — plain Markdown, not JSON: mechanism, examples, precise contrasts, open questions and next concepts for one node, written into the note's ## Deep dive region.
7. Review Cards Prompt — "You are CogniTree Review…" — 1–N flashcards per node (recall / cloze / application) with one fact per card and answers that stand alone.
8. Vault Cartography Prompt — "You are CogniTree Cartographer…" — arranges existing vault notes into domains and children, marking each slot that maps to a real note via source (validated before it becomes a link).

Responses are parsed tolerantly (markdown-fence stripping, trailing-comma repair, balanced-brace extraction) in src/parser.ts.

Scalability design (tens of thousands of nodes)

• Incremental growth — one branch per API call; the tree only exists where you've explored it.
• Lazy loading — tree models are rebuilt from metadataCache frontmatter (no full-file reads); a raw YAML parse is the fallback for notes Obsidian hasn't indexed yet.
• Virtualized rendering — fixed 34px rows, windowed DOM (src/treeView.ts), ~50 rows in the DOM regardless of tree size.
• Prompt caching — keyed kind|model|prompt, LRU-capped, persisted in the plugin data file.
• Background indexing — VaultIndexer subscribes to metadataCache changed/deleted/resolved (debounced) and ranks candidate note names by token overlap.
• Semantic index (optional) — SemanticIndex embeds note titles, tags and the head of each body via /embeddings, keeps vectors in <plugin>/embeddings.json, skips notes whose mtime is unchanged, and caps memory at 20 000 vectors. Runs are budgeted (embeddingMaxNotes) and resumable.
• Bounded batch concurrency — 3 parallel expansion requests per level, node budget enforced, progress done/total reported to the UI.

Note format

Every concept is one Markdown note, e.g. CogniTree/Democracy/Direct Democracy.md:

---
concept: "Direct Democracy"
tree: "Democracy"
parent: "Democracy"
domain: "Political Science"
description: "Citizens vote directly on laws and policies rather than through representatives."
complexity: "Beginner"
can_expand: true
estimated_depth: 4
connections: ["Athenian Democracy", "Referendums", "Citizen Assemblies"]
children: ["Referendums", "Citizen Assemblies"]
path: "/democracy/political_science/direct_democracy"
deepened: "2025-01-02T09:15:00.000Z"
source: "Notes/Greek Democracy.md"
created: "2025-01-01T00:00:00.000Z"
---

# Direct Democracy

> Source note: [[Notes/Greek Democracy]]

Citizens vote directly on laws and policies rather than through representatives.

## Deep dive
<!-- cognitree:deep-dive -->
### How it works
…

## Connections
- [[Athenian Democracy]]
- [[Referendums]]

This stays fully Obsidian-native: the graph view, backlinks, and search all work on generated trees. Three optional extras:

• deepened — set when a ## Deep dive region exists, so the tree view can badge notes (💡) and skip them in a batch without reading any file.
• source + the > Source note: line — a reference node created by Grow a tree from your vault: it points at a note you already own (🔗 badge, Open source note). Deleting the node deletes only the pointer, never your note.
• .cognitree-review.json — hidden per-tree store holding review cards and their SM-2-lite schedule. It lives inside the tree folder, travels with the tree, and is invisible to Obsidian's search and file explorer.

The deep-dive region is delimited by the <!-- cognitree:deep-dive --> marker and ends at the next ## heading: the plugin rewrites the rest of the note body freely, but everything inside those markers — including your own edits — is carried over on every write.

Development

npm install          # dev deps (esbuild, typescript, obsidian types)
npm run dev          # watch mode → main.js
npm run build        # typecheck + production bundle
npm test             # pure-logic suite + store/generator suite (in-memory vault stub)

tests/smoke.ts covers the obsidian-free helpers (parser, note regions, providers, branch digest, semantic math, SRS scheduling, vault graph). tests/store.test.ts runs the real ConceptStore / ConceptGenerator against tests/stub-obsidian.ts — an in-memory vault, metadataCache and fileManager — so note writing, deep-dive preservation, subtree deletes/undo, merges, review stores and reference-node trees are testable without an Obsidian install.

Keyboard shortcuts

In a review session: Space reveals the answer, 1 / 2 / 3 / 4 grade it again / hard / good / easy, Esc ends the session (grades are saved as you go).

Click any node once to grab keyboard focus for the list. The toolbar actions (⚡ Batch, ♺ Index, 🧠 Review) act on the currently selected node.

Commands

• Open panel
• Create concept tree from selection — uses the current editor selection as the root concept
• Refresh from vault — reload trees if you edited notes by hand
• Reindex vault notes — rebuild the lexical connection index on demand
• Build semantic index (embeddings) — embed new/changed vault notes for semantic matching
• Ask about selected concept — grounded Q&A chat on the selected node (or the tree root)
• Review due cards — study the cards that are due in the open tree
• Grow a tree from existing vault notes — arrange notes you already have into a new tree (linked, not copied)

Screenshots

License

MIT © 2026 Kerekes Stefan