# 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 `.claude/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 ```text 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` - `.claude/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: ```text .claude/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: 1. project config in `.claude/project-memory/registry.yaml` 2. environment variable `OBSIDIAN_NOTE_LANGUAGE` 3. 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: ```json { "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 `.claude/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 `.claude/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: 1. Use an Obsidian desktop build that supports CLI registration. 2. In Obsidian Desktop, open `Settings -> General -> Advanced`. 3. Turn on **Command line interface**. 4. Ensure `/Applications/Obsidian.app/Contents/MacOS` is on your `PATH` on macOS (for example via `~/.zprofile`). 5. Restart your terminal, then verify: ```bash 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 ### Archive - **note archive** moves a canonical note into `Research/{project-slug}/Archive/` - **project archive** moves the whole project into `Research/_archived/{project-slug}-{date}/` - archive keeps history and disables syncing for project-level archive ### 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: - URI docs: Examples: ```bash obsidian help obsidian search query="diffusion" limit=10 obsidian daily:append content="- [ ] Follow up on experiment" ``` ```text 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 `.claude/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 `/obsidian-vault`) - keep a Windows-local mirror directory mounted in WSL (for example ``) - open the mirrored Windows-local directory in Windows Obsidian Sync with: ```bash bash scripts/sync_obsidian_to_windows.sh --windows-path ``` Preview first if needed: ```bash bash scripts/sync_obsidian_to_windows.sh --windows-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.