# 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: <https://help.obsidian.md/cli>
- URI docs: <https://help.obsidian.md/uri>

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 `<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
bash scripts/sync_obsidian_to_windows.sh   --windows-path <wsl-mounted-windows-vault-path>
```

Preview first if needed:

```bash
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.
