Edunotes NotebookLM Bridge

Bring NotebookLM-style research notebooks into Obsidian without abandoning the vault-first workflow. The Edunotes bridge plugin now delivers a complete tag-scoped notebook experience with offline-friendly summaries, conversation, and export tooling so you can explore and study directly inside your vault.

Current functionality (milestones 1–8)

• ✅ Modular foundation – Source lives under src/ with dedicated modules for lifecycle (core/), indexing (indexing/), notebooks (notebooks/), AI helpers (ai/), UI (ui/), and utilities.
• ✅ Persistent data store – PluginDataStore wraps loadData/saveData, merges defaults, and remembers the last active notebook when configured.
• ✅ Tag-scoped notebooks – NotebookRepository persists notebook metadata, auto-suggests unique tags, tracks the active notebook, and previews which files match the notebook tag.
• ✅ Creation workflow – A modal flow lets users name a notebook, accept or tweak the suggested tag, and capture optional description context.
• ✅ Workspace view – The custom Notebook workspace view lists notebooks, shows sources, renders summaries/study aids, and embeds a conversation panel that stays in sync with the active notebook.
• ✅ Offline AI pipeline – A local-extractive model gateway builds overviews, study guides, questions, and flashcards from tagged notes using the context builder and cached hashes to avoid unnecessary recomputation.
• ✅ Conversational Q&A – Ask grounded questions inside the workspace view; answers surface inline citations and the conversation history persists with the notebook.
• ✅ Export tooling – One-click exports save Markdown or JSON bundles (summaries, study aids, conversation) to NotebookLM/exports/, with an audit trail stored alongside the notebook.
• ✅ Live tag monitoring – Vault listeners watch for tagged note edits, renames, and deletions and automatically refresh study materials for affected notebooks.
• ✅ Audio overviews – Optional TTS integration synthesises spoken summaries via a user-provided endpoint and saves the audio inside the vault.
• ✅ Source management dashboard – Inspect tagged sources, reorder prioritised notes, exclude noisy files without touching tags, and remove notebook tags directly from the workspace view.
• ✅ Import workflows – Bring back exported Markdown or JSON bundles (including Python-backed responses) and merge them into existing notebooks or create new ones with tag remapping safeguards.
• ✅ Detailed import previews & scoped refresh – Preview incoming bundle citations and study guides before merging, confirm tag removals, and selectively regenerate summaries, questions, flashcards, study guides, or audio from the command palette or workspace view.
• ✅ Generation progress & automation hooks – Track per-artifact progress within the workspace header, get slow-run notices, and respond to workspace events for regenerations and exports.
• ✅ Run history & status monitoring – Review a timeline of generation/export runs with durations and failure markers while the status bar surfaces live progress or alerts at a glance.
• ✅ Analytics dashboard – Slice run history by time range or notebook, compare average durations per artifact, and highlight notebooks with repeated failures.
• ✅ Automation cookbook – Reference scripts demonstrate how to trigger regenerations, exports, and follow-up automations (docs/automation-cookbook.md).

Commands

Command ID	Name	Description
notebooklm-create-notebook	Create notebook from tag	Launches the creation modal with tag suggestions derived from the configured prefix.
notebooklm-preview-active-membership	Preview active notebook membership	Displays the tagged files currently belonging to the active notebook.
notebooklm-cycle-active-notebook	Cycle active notebook	Rotates through stored notebooks and sets the new active notebook.
notebooklm-open-workspace-view	Open Notebook workspace	Opens the Notebook workspace view in the right pane.
notebooklm-generate-study-materials	Generate study materials for active notebook	Runs the summarisation/study aid pipeline for the active notebook.
notebooklm-regenerate-selected-materials	Regenerate selected study materials	Opens a modal to regenerate only the chosen notebook artefacts (overview, questions, flashcards, study guide, audio).
notebooklm-export-active-markdown	Export active notebook (Markdown)	Exports the active notebook to Markdown under NotebookLM/exports/.
notebooklm-export-active-json	Export active notebook (JSON)	Exports the active notebook to JSON under NotebookLM/exports/.
notebooklm-import-bundle	Import NotebookLM bundle	Imports a Markdown/JSON export and creates or merges a notebook with tag collision checks.
notebooklm-copy-last-export-path	Copy last export path	Copies the most recent export path for the active notebook to the clipboard for automation workflows.

Importing notebooks

Use the Import NotebookLM bundle command to round-trip exported study materials or Python-generated summaries back into Obsidian:

1. Save the exported Markdown or JSON bundle (the plugin writes them to NotebookLM/exports/ by default) or copy a bundle produced by the Python Edunotes service into your vault.
2. Run Import NotebookLM bundle from the command palette. Pick the file to import from the dropdown preview.
3. Choose whether to create a new notebook or merge the contents into an existing one. When creating a new notebook, the modal validates tag collisions and can suggest a unique replacement automatically.
4. Review the preview counts (overview, questions, flashcards, study guide sections) and finish the import. The workspace view opens on the imported notebook so you can regenerate study materials or continue asking questions immediately.
5. Conversation previews list the most recent turns with their citations so collaborators can verify shared Q&A before merging.

Automation hooks

Automation tools or companion plugins can listen for NotebookLM events or trigger regenerations directly through Obsidian’s workspace event bus.

See docs/automation-cookbook.md for copy-and-paste snippets that respond to these events or chain commands together.

• Regeneration lifecycle
  • notebooklm:regeneration-started – fired with { notebookId, artifacts, scope, timestamp, contextHash } before AI work begins.
  • notebooklm:regeneration-completed – emitted after persistence with { notebookId, artifacts, scope, timestamp, contextHash, notebook }.
  • notebooklm:regeneration-failed – raised when a run errors, adding error to the payload.
• Export lifecycle
  • notebooklm:export-started – emitted before writing files.
  • notebooklm:export-completed – provides { notebookId, format, path, timestamp, notebook } on success.
  • notebooklm:export-failed – includes an error string when an export cannot be written.
• Triggering regenerations
  • Fire app.workspace.trigger('notebooklm:regenerate-request', { notebookId, scope }) to queue a regeneration from scripts or plugins. Omit scope to run the full pipeline or pass a StudyMaterialScope object (e.g., { questions: true, flashcards: false, studyGuide: true }).
• Clipboard helpers
  • The Copy last export path command copies the latest export path for the active notebook so shell scripts or community plugins can pick up the generated files immediately.

Notebook analytics dashboard

Open the Run history section inside the workspace view to explore aggregated metrics:

• Use the time range dropdown to switch between the last 7, 30, or 90 days (or all history). The plugin persists your choice in settings so the dashboard reopens with the same scope.
• Pick a notebook filter to compare the active notebook against vault-wide averages or focus on another notebook entirely. Highlighted bars show which series matches the selected notebook.
• Horizontal bar charts surface average durations per artifact (overview, questions, flashcards, study guide, audio, exports) and per notebook. When durations are unavailable the charts fall back to run counts.
• A health panel lists notebooks with repeated failures so you can prioritise troubleshooting. Success percentages are derived from the same aggregated run data.

The filters update immediately without leaving the workspace, and all analytics rely on the run history already stored alongside each notebook—no additional indexing or network calls are required.

Manual QA checklist

Before publishing a build, run through the QA checklist to confirm notebook creation, tag syncing, regeneration scopes, automation hooks, analytics dashboards, audio playback, and Python endpoint fallbacks all behave as expected. The list is designed for clean vaults so regressions surface quickly.

Known limitations & troubleshooting

• Python backend availability – Remote model and audio features depend on the external Edunotes service. If the endpoint is offline, the plugin falls back to local extractive summaries and records failures in run history. Check the status bar indicator and run history health panel when diagnosing outages.
• Large-notebook performance – Vaults with hundreds of tagged files can trigger longer regeneration times. Use scoped regeneration to refresh only the required artefacts and monitor analytics for notebooks that routinely exceed expected durations.
• Audio storage – Generated audio files live under NotebookLM/audio/. Deleting them outside the plugin leaves stale metadata until the next regeneration; run Regenerate selected study materials with the audio option enabled to rebuild them.
• Mobile support – The workspace view is optimised for desktop panes. Mobile devices render the view but complex drag-and-drop interactions (source reordering) degrade gracefully into button controls.
• Import provenance – Imported bundles trust the provided citations. Review previews carefully when accepting third-party exports and regenerate artefacts to recalc citations inside your vault if accuracy is critical.

Document additional caveats discovered during QA so early adopters can self-diagnose issues without waiting for a patch.

Release packaging

Follow the release guide when preparing a GitHub release. It covers version bumps, bundle assembly (manifest.json, main.js, styles.css), tagging, and announcement steps to keep releases reproducible.

Support & contributions

• File issues with reproduction steps, screenshots, and relevant run history excerpts so we can triage failures quickly.
• Pull requests should pass npm run build, include documentation updates for new settings or commands, and extend the QA checklist when they add new flows.
• Share automation scripts or notebooks in the community forum; notable examples can be added to docs/automation-cookbook.md.
• Security vulnerabilities or data-leak concerns should be reported privately before disclosure.

Next steps

1. Post-launch monitoring – Gather feedback from early adopters, refine the QA checklist with edge cases they encounter, and expand known limitations as needed.
2. Ecosystem integrations – Explore community plugin integrations (Dataview surfacing run history, templater snippets for exports) once the release stabilises.

Architecture overview

src/
  ai/
    audio-overview.ts    # Calls remote TTS endpoints to synthesise spoken summaries
    cache.ts             # Context hashing helpers for caching
    context-builder.ts   # Builds prompt-ready chunks from tagged notes
    model-gateway.ts     # AI gateway (local extractive + remote Edunotes endpoint)
  core/
    data-store.ts        # Persistence wrapper + settings helpers
    exporter.ts          # Markdown/JSON exporter with audit trail recording
    notebook-engine.ts   # Orchestrates context building, caching, and repository updates
    plugin.ts            # Plugin entry point, commands, and view registration
    settings.ts          # Settings schema and defaults (AI + notebook behaviour)
    state.ts             # Shared state/events (active notebook tracking)
  indexing/
    tag-indexer.ts       # Finds and previews notes by tag via metadataCache
  notebooks/
    notebook-repository.ts  # CRUD + tag suggestion + previews + AI artefact persistence
    types.ts                # Notebook interfaces (analysis, conversation, exports)
  ui/
    conversation-panel.ts   # Conversation UI component with grounding controls
    create-notebook-modal.ts # Modal for tag-scoped notebook creation
    notebook-view.ts        # Workspace view rendering notebooks, sources, and AI output
  utils/
    tags.ts               # Tag normalization helpers
    types.ts              # Utility TypeScript helpers

styles.css styles both the notebook creation modal and the workspace components so they respect Obsidian theming.

Connecting to the Python Edunotes backend

The plugin defaults to a local, extractive summariser so it works entirely offline. To leverage the richer NotebookLM models from the Python edunotes package:

1. Run the Python service (for example, the FastAPI server exposed by the edunotes project) and note the HTTPS endpoint it exposes for NotebookLM requests.
2. In Obsidian, open Settings → Community plugins → Edunotes NotebookLM → Settings.
3. Change Model provider to Custom endpoint (Python Edunotes).
4. Enter the service URL and optional bearer token. The plugin POSTs notebook context, questions, and regeneration requests to this endpoint using the configured credentials.
5. (Optional) Enable spoken summaries by switching Audio provider to Custom endpoint and supplying the audio synthesis URL/API key exposed by your Python service.

Whenever tagged notes change, the plugin rebuilds context and sends it to the remote endpoint, persisting the returned summaries, questions, flashcards, and study guides alongside the notebook.

NotebookLM feature reference

To guide future iterations, the following list captures the NotebookLM capabilities we aim to mirror within Obsidian:

• Notebook-centric document organization – Create notebooks that bundle together multiple source files for focused research workstreams.
• Automated document ingestion & grounding – Track tagged sources and normalise them into contextual chunks that feed downstream summaries and answers.
• AI-generated summaries – Produce concise takeaways for each notebook, including section-level highlights and overall briefs.
• Question answering with citations – Ask free-form questions and receive grounded responses that cite originating document excerpts.
• Multi-document synthesis – Combine insights across several sources to surface relationships, comparisons, and thematic overlaps.
• Saved insights & flashcards – Capture key answers or highlights as persistent notes, flashcards, or follow-up prompts within the notebook.
• Outline & brief generation – Automatically create outlines, briefs, or study guides tailored to the selected sources.
• Conversation history – Maintain a running chat log that remembers prior questions and context for iterative exploration.
• Audio overview – Generate spoken summaries ("Audio Overview") via user-configured TTS services and store them in the vault.
• Notebook sharing & collaboration – Share notebooks with collaborators by exporting/importing JSON or Markdown bundles.
• Export & publishing options – Export insights, summaries, or citations to common formats for use in external documents or presentations.
• Source management dashboard – Provide UI to view, reorder, or remove notebook sources while monitoring ingestion status and metadata.

Implementation plan for an Obsidian-native NotebookLM experience

The roadmap aligns NotebookLM functionality with the Obsidian plugin platform while honouring the file-first philosophy. Items marked ✅ are now live.

1. Core plugin foundation ✅

• Rebrand & scaffold: Rename the plugin, relocate sources to src/, and establish a modular architecture (core/, indexing/, ui/, ai/).
• Settings service: Implement loadData/saveData wrappers with a settings tab for feature toggles, model credentials, and notebook defaults.
• Event lifecycle hygiene: Centralise registration via this.registerEvent, this.registerInterval, and this.registerDomEvent to ensure clean unloads.

2. Vault-aware notebook model ✅

• Notebook registry: Persist notebooks in plugin data (NotebookRepository) with metadata for linked files, generated summaries, conversation history, and exports.
• Tag-scoped membership: Prompt for (or auto-generate) a dedicated tag—e.g., #notebook/research-ml. Any note carrying that tag is treated as part of the notebook, letting users curate membership by editing tags directly in their notes.
• Tag management UX: Provide commands to create notebooks with tags, preview membership, and cycle between notebooks.

3. Document ingestion & indexing pipeline ✅ (first pass)

• Vault scanning: Use metadataCache to resolve tagged Markdown files for each notebook and build previews.
• Chunking & normalization: Normalise headings and paragraphs into prompt-friendly segments with configurable character limits.
• Change tracking: Vault listeners monitor create/modify/rename/delete events and trigger automatic study material refreshes whenever tagged content shifts.

4. Workspace surfaces & user interface ✅

• Dedicated view: Register the notebooklm-view workspace leaf listing notebooks, sources, summaries, study aids, and exports.
• Conversation pane: Embed a chat panel with citation rendering and history controls.
• Global commands: Provide commands to open the notebook view, regenerate summaries, and export notebooks.
• Theming compliance: Style via styles.css, respecting Obsidian theme variables and dark/light modes.

5. AI integration & summarization ✅ (offline extractive)

• Model gateway: Abstract AI providers (offline extractive or a remote Edunotes endpoint) behind a unified interface that produces summaries, Q&A responses, and study materials.
• Context builder: Assemble prompts by combining notebook chunks, respecting configurable context budgets.
• Caching layer: Persist generated summaries with context hashes to avoid redundant runs.
• Offline fallback: Default to the local extractive mode until external providers are wired up.

6. Advanced insights & study aids ✅

• Outline & flashcards: Generate outlines, briefs, and spaced-repetition cards, storing them with the notebook for reuse.
• Study guide generation: Build sectioned study guides summarising key bullet points from tagged files.
• Audio overview: Synthesize spoken summaries through the configured audio provider and surface playback controls in the workspace view.

7. Collaboration & export ✅ (Markdown/JSON)

• Notebook export: Support exporting summaries, Q&A, and citations as Markdown or JSON bundles saved directly in the vault.
• Sharing workflows: Leverage the file-based nature to share exported bundles with collaborators, and re-import bundles with merge or create flows.

8. Quality, privacy, and extensibility ✅ (initial pass)

• Transparency: Keep processing local by default and surface errors via notices/console logs.
• Extensibility: Architect services (NotebookRepository, NotebookEngine, ModelGateway) with dependency injection to support future providers or community contributions.

Future work will iterate on richer AI providers, collaborative workflows (including imports), and deeper indexing for non-Markdown sources.

Development

• Install dependencies with npm install.
• Run npm run dev to start esbuild in watch mode (entry point: src/main.ts).
• Run npm run build for a production bundle (main.js).
• To test locally, copy main.js, manifest.json, and styles.css into <Vault>/.obsidian/plugins/edunotes-notebooklm/ and reload Obsidian.

Releasing

• Update manifest.json, package.json, and versions.json with the new version number and minimum Obsidian version.
• Run npm run build to produce main.js before packaging.
• Create a GitHub release with manifest.json, main.js, and styles.css attached individually.

Funding URL

You can include funding URLs where people who use your plugin can financially support it. Set the fundingUrl field in manifest.json to either a string or a key/value map of funding providers.

API documentation

See https://github.com/obsidianmd/obsidian-api for official type documentation and guidance.