GGaorui Zhangfeat(opencode): backport vault-first obsidian kb

Obsidian Project Knowledge Base Setup

Claude Scholar ships with a built-in Obsidian research knowledge-base workflow. It does not require MCP or an API key.

What this provides

Obsidian is treated as the default knowledge base for a research project, not just a paper library. A project knowledge base can store:

stable project background and research questions
paper notes and literature syntheses
experiment runbooks and result summaries
daily research logs, scratch notes, and sync queues
writing assets such as drafts, slides, proposals, and rebuttal material
archived project knowledge that should not stay on the main working surface

Requirements

Required

A local Obsidian vault path
OBSIDIAN_VAULT_PATH set in your environment, or passed explicitly when bootstrapping a project

Optional

Obsidian Desktop installed and open for navigation
obsidian CLI available for open/search/daily actions
OBSIDIAN_VAULT_NAME for cleaner obsidian:// links and CLI targeting

Built-in skills

Claude Scholar includes a project-scoped Obsidian KB workflow.

Most relevant for the default workflow:

obsidian-project-kb-core
obsidian-source-ingestion
obsidian-literature-workflow
obsidian-kb-artifacts
defuddle

Some optional graph-oriented helpers may still exist in the repo, but the default workflow does not depend on .base, MCP, or API services. The main default graph artifact is Maps/literature.canvas; additional .base views or project/experiment canvases are explicit-only.

Default behavior

When Claude Scholar is running inside a repository that contains .opencode/project-memory/registry.yaml, it should treat the repository as bound to an Obsidian project knowledge base and update it by default.

If the repository is not yet bound, but it looks like a research project (for example it contains .git, README.md, docs/, notes/, plan/, results/, outputs/, src/, or scripts/), Claude Scholar should bootstrap a project knowledge base automatically.

Project structure in the vault

Research/{project-slug}/
  00-Hub.md
  01-Plan.md
  02-Index.md
  Sources/
    Papers/
    Web/
    Docs/
    Data/
    Interviews/
    Notes/
  Knowledge/
  Experiments/
  Results/
    Reports/
  Writing/
  Daily/
  Maps/
  Archive/
  _system/
    registry.md
    schema.md
    lint-report.md

Key generated files commonly include:

02-Index.md
_system/registry.md
_system/schema.md
_system/lint-report.md
.opencode/project-memory/{project_id}.md
Maps/literature.canvas when literature workflow needs it

Repository-local memory binding

Each research repo gets a local binding under:

.opencode/project-memory/
  registry.yaml
  {project_id}.md

registry.yaml stores the repo ↔ vault binding
{project_id}.md stores the assistant-facing project memory for incremental syncs

Note language

Generated and synced notes resolve their language with this priority:

project config in .opencode/project-memory/registry.yaml
environment variable OBSIDIAN_NOTE_LANGUAGE
default en

Note: registry.yaml remains a repo-local runtime binding file. The visible project source of truth stays in _system/registry.md.

Supported values:

en
zh-CN

Per-project example:

{
  "projects": {
    "my-project": {
      "project_id": "my-project",
      "vault_root": "/path/to/vault/Research/my-project",
      "note_language": "zh-CN"
    }
  }
}

Existing English and Chinese headings remain compatible during sync, so changing the configured language does not break older notes.

Main commands

/kb-init — initialize the vault-first project KB
/kb-status — summarize the bound KB state
/kb-ingest — route new source material into canonical notes
/kb-log — update the current Daily note and related project surfaces
/kb-sync — run deterministic KB maintenance and resync project surfaces
/kb-links — repair or strengthen wikilinks among canonical notes
/kb-promote — promote durable content into canonical notes
/kb-index — rebuild 02-Index.md
/kb-lint — run deterministic KB health checks and rewrite _system/lint-report.md
/kb-archive — archive, detach, purge, or rename KB objects
/kb-map — generate explicit-only artifact outputs beyond the default literature canvas
/kb-literature-review — synthesize literature from Sources/Papers into Knowledge, Writing, and Maps/literature.canvas

Minimum bound-repo maintenance

When a repo is already bound through .opencode/project-memory/registry.yaml, Claude Scholar should keep automatic maintenance conservative:

always verify Daily/YYYY-MM-DD.md when the turn changes research state,
update 00-Hub.md only when top-level project status actually changes,
update .opencode/project-memory/{project_id}.md whenever project state changes,
keep Knowledge/, Experiments/, Results/, and Writing/ agent-first rather than automatically rewriting them every turn.

Optional Obsidian CLI installation

The official Obsidian CLI is built into newer desktop installers. To use obsidian ... commands:

Use an Obsidian desktop build that supports CLI registration.
In Obsidian Desktop, open Settings -> General -> Advanced.
Turn on Command line interface.
Ensure /Applications/Obsidian.app/Contents/MacOS is on your PATH on macOS (for example via ~/.zprofile).
Restart your terminal, then verify:

obsidian help
obsidian search query="diffusion" limit=5

If you see Command line interface is not enabled, the shell path is fine but the Obsidian in-app toggle is still off.

Lifecycle actions

Detach

stop automatic syncing
keep vault content
keep project memory file

Purge

permanently delete the binding, project memory, and vault project folder
only use when the user explicitly asks for permanent deletion

Optional CLI and URI usage

Claude Scholar can optionally use the official Obsidian CLI and URI scheme:

CLI docs: https://help.obsidian.md/cli
URI docs: https://help.obsidian.md/uri

Examples:

obsidian help
obsidian search query="diffusion" limit=10
obsidian daily:append content="- [ ] Follow up on experiment"

obsidian://open?vault=My%20Vault&file=Research%2Fproject-slug%2F00-Hub
obsidian://search?vault=My%20Vault&query=%23experiment

Troubleshooting

Issue	Solution
Bootstrap fails with missing vault path	Set `OBSIDIAN_VAULT_PATH` or pass a vault path explicitly
Project keeps re-importing	Check `.opencode/project-memory/registry.yaml` exists and points to the correct repo root
The vault still shows older topologies	Those are from older docs or older project generations; the current default workflow uses the structure above and only keeps `Maps/literature.canvas` by default
CLI commands fail	Check that `Settings -> General -> Advanced -> Command line interface` is enabled; otherwise continue with filesystem-only sync
“Remove project knowledge” is too destructive	Use archive or detach; purge is only for permanent deletion

WSL -> Windows mirror workflow

If you run Claude Scholar inside WSL but prefer opening Obsidian through native Windows for more stable window behavior, use a two-copy setup:

keep the WSL vault as the source of truth (for example <repo-root>/obsidian-vault)
keep a Windows-local mirror directory mounted in WSL (for example <wsl-mounted-windows-vault-path>)
open the mirrored Windows-local directory in Windows Obsidian

Sync with:

bash scripts/sync_obsidian_to_windows.sh   --windows-path <wsl-mounted-windows-vault-path>

Preview first if needed:

bash scripts/sync_obsidian_to_windows.sh   --windows-path <wsl-mounted-windows-vault-path>   --dry-run

By default the sync deletes mirror-only files that no longer exist in the WSL source. Add --no-delete if you want to keep extra files in the Windows mirror.