fix(research): mount read-only Obsidian tools instead of rag for vault KBs - #756
Merged
pancacake merged 2 commits intoAug 6, 2026
Merged
Conversation
…t KBs When the selected knowledge base is a connected Obsidian vault, the research block loop now: - resolves KB metadata at construction and records the server-side vault path (no RAG usage audit); - suppresses the rag auto-mount (has_kb=False) and exposes the three read-only Obsidian tools obsidian_search / obsidian_read / obsidian_list; - injects _vault_path server-side, overwriting any model-supplied value; - treats the Obsidian tools as citable so their evidence feeds the citation manager and Phase 4 reporting; - renders an Obsidian-specific system note (en/zh) instructing read-only vault retrieval instead of rag. Indexed KBs, no-KB, and unresolvable references keep their existing behaviour. Closes HKUDS#752
Closed
20 tasks
evan188199-tech
pushed a commit
to evan188199-tech/DeepTutor
that referenced
this pull request
Aug 15, 2026
…ridge
Add MarginNote 4 as a connected knowledge base type that syncs study data
(notes, excerpts, cards, mindmap nodes) from MN4 via the official Add-on API
into a dedicated SQLite store, then exposes it to the chat loop through seven
read-only tools.
New package: deeptutor/capabilities/marginnote4/
- models.py: MarginNoteObject, SyncBatch, PairedDevice, LearningEvent
- store.py: SQLite CRUD + search + device pairing with hashed tokens
- binding.py: per-turn resolution of the selected MN4 library
- tools.py: search, read, list, documents, links, tags, cards
- capability.py: KnowledgeCapability (exclusive turn ownership)
- prompts/{en,zh}/system.md
HTTP bridge: deeptutor/api/routers/marginnote4.py
- POST /pair (session auth) -- register a device, get one-time token
- POST /sync (device-token auth) -- incremental upsert + tombstones
- POST /heartbeat (device-token auth) -- liveness + object count
- GET /devices, DELETE /devices/{id}, GET /status (session auth)
Integration points:
- kb_types.py: MARGINNOTE4_KB_TYPE added to CONNECTED_KB_TYPES
- manager.py: db_path surfaced in get_metadata allowlist
- registry.py: MarginNoteCapability registered in LOOP_CAPABILITIES
- builtin/__init__.py: MARGINNOTE_TOOL_TYPES in BUILTIN_TOOL_TYPES
- api/main.py: router mounted at /api/v1/marginnote4
Phase 1 scope: device pairing, read-only sync, tool navigation.
Write-back (propose/apply/verify), learning events, and mastery bridge
are planned for Phase 2-3.
Refs: HKUDS#756 (Obsidian external knowledge source pattern), HKUDS#180
pancacake
added a commit
that referenced
this pull request
Aug 21, 2026
* feat(marginnote4): add connected KB type, read-only tools, and sync bridge
Add MarginNote 4 as a connected knowledge base type that syncs study data
(notes, excerpts, cards, mindmap nodes) from MN4 via the official Add-on API
into a dedicated SQLite store, then exposes it to the chat loop through seven
read-only tools.
New package: deeptutor/capabilities/marginnote4/
- models.py: MarginNoteObject, SyncBatch, PairedDevice, LearningEvent
- store.py: SQLite CRUD + search + device pairing with hashed tokens
- binding.py: per-turn resolution of the selected MN4 library
- tools.py: search, read, list, documents, links, tags, cards
- capability.py: KnowledgeCapability (exclusive turn ownership)
- prompts/{en,zh}/system.md
HTTP bridge: deeptutor/api/routers/marginnote4.py
- POST /pair (session auth) -- register a device, get one-time token
- POST /sync (device-token auth) -- incremental upsert + tombstones
- POST /heartbeat (device-token auth) -- liveness + object count
- GET /devices, DELETE /devices/{id}, GET /status (session auth)
Integration points:
- kb_types.py: MARGINNOTE4_KB_TYPE added to CONNECTED_KB_TYPES
- manager.py: db_path surfaced in get_metadata allowlist
- registry.py: MarginNoteCapability registered in LOOP_CAPABILITIES
- builtin/__init__.py: MARGINNOTE_TOOL_TYPES in BUILTIN_TOOL_TYPES
- api/main.py: router mounted at /api/v1/marginnote4
Phase 1 scope: device pairing, read-only sync, tool navigation.
Write-back (propose/apply/verify), learning events, and mastery bridge
are planned for Phase 2-3.
Refs: #756 (Obsidian external knowledge source pattern), #180
* fix(marginnote4): search scope, store caching, prompts, KB registration
Testing and experience improvements:
- Search now includes document_title in scope: searching for a textbook
name returns results instead of zero hits
- Store instances cached by db_path so schema init runs once, not per
tool call within a turn
- object_type parameters carry enum constraints so the LLM knows valid
types without guessing
- System prompts (en/zh) rewritten with domain context: explains the
five object types, link traversal strategy, and citation guidance
- KB registration: register_marginnote4_kb manager method +
/connect-marginnote4 API endpoint, mirroring the Obsidian connect flow
- Fix indentation inconsistencies in manager.py and main.py
- New tests: document_title search scope, KB registration (create,
default path, duplicate rejection)
65 tests pass, 0 regressions, ruff clean.
* style(marginnote4): apply repository formatter
* fix(marginnote4): keep MN4 libraries out of the rag_search sweep
``MARGINNOTE4_KB_TYPE`` joined ``CONNECTED_KB_TYPES`` but not
``NON_RETRIEVABLE_KB_TYPES``, so ``supports_rag_retrieval`` answered true
for a library that has no index and no retrieval API — its objects live
in ``mn4_objects`` and are reachable only through the seven
``marginnote_*`` tools. Book's source explorer would have swept it,
gotten nothing back, and reported it as a source with no relevant
content rather than one that needs its own tools.
MN4 belongs with ``obsidian`` and ``subagent``, not with ``linked`` /
``lightrag_server`` / ``ima``, which do resolve to an index or an HTTP
retrieval API. Tests pin both halves of that split, since collapsing it
the other way has cost Book its connected sources before.
---------
Co-authored-by: XZH <cto@xzh.ai>
Co-authored-by: evan <evan@dazongguandeMac-mini.local>
Co-authored-by: Bingxi Zhao (Frank) <13051345080@163.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
When a connected Obsidian vault is selected as the knowledge base, the deep-research pipeline auto-mounts the
ragtool even though the vault has no index, producing spurious warnings and misleading evidence. This PR makesResearchPipelinevault-aware:resolve_kb_metadata) and record_is_obsidian_kb/_vault_path(pure read, no RAG usage audit).ragauto-mount for Obsidian KBs (has_kb=False) and expose the three read-only Obsidian toolsobsidian_search/obsidian_read/obsidian_listin the research block loop.vault_pathavailability, so malformed metadata never falls back to index-backedrag; read tools are mounted only when a trusted path exists._vault_pathserver-side in_augment_tool_kwargs, overwriting any model-supplied value so the path cannot be forged to read outside the vault.CITABLE_TOOLSso their evidence is summarised, recorded by theCitationManager, and reaches Phase 4 reporting.query,note, orfolder), using/for a vault-root listing.rag.Indexed KBs, no-KB, and unresolvable references keep their existing behaviour.
Related Issues
Module(s) Affected
agentsapiconfigcoreknowledgeloggingservicestoolsutilsweb(Frontend)docs(Documentation)scriptstests...Checklist
pre-commit run --all-filesand fixed any issues.Additional Notes
tests/agents/research/test_research_obsidian_tools.pycover metadata resolution, tool-composition matrix, vault-path injection/forging, real citation locators, and system-note selection.devbaseline, unrelated to this change).pre-commit run --all-fileswas not executed in this environment; the modified files passruff check,ruff format --check, andgit diff --checklocally.