{
  "markdown": "# Obsidian Knowledge\n\nA Claude Code plugin marketplace with skills and hooks for maintaining\nObsidian knowledge base vaults.\n\n## Skills\n\n### vault-organizer\n\nMaintains vault organization through a single-pass pipeline:\n\n- **Sync indexes** — creates and updates `index.md` files with thin pointer entries for managed zones\n- **Organize files** — moves misplaced files to appropriate locations using the Obsidian CLI\n- **Rename ambiguous files** — detects files with non-descriptive names\n  (device-generated, hash-based, generic labels), reads their content, and\n  renames them following the vault's naming conventions from CLAUDE.md\n- **Fix broken links** — detects unresolved links and resolves them when\n  possible, flags ambiguous cases for human review\n- **Report issues** — maintains a `needs-attention.md` worklist for issues\n  requiring human judgment\n- **Regenerate reports** — rewrites `reports/open-questions.md` from\n  `> [!question]` callouts across `wiki/`, giving agents and humans a\n  single place to see unresolved questions flagged in prose\n\n### remember-conversations\n\nSelectively files durable, novel conversation outputs as permanent vault\nnotes, so insights compound without turning routine activity into prompt\noverhead:\n\n- **Canonical notes** — learning pages for reusable concepts, diary notes for\n  reusable incident/process accounts, and convo notes for analytical synthesis\n- **Changelog updates** — after an actual durable vault mutation, creates or\n  reuses one terse same-session file in `changelog/`\n- **Automatic placement** — learning pages use the canonical topic location;\n  analytical and narrative notes use `convos/` and `diary/` subfolders\n- **Stop hook integration** — one reminder asks the agent to search first and\n  file at most one canonical note only when a durable delta qualifies\n\n## Hooks\n\n### Vault protection (PreToolUse)\n\n`protect-vault.py` runs before every Bash, Write, and Edit tool call.\nIt provides four layers of safety:\n\n**Read-only `_sources/` directories.** Folders named `_sources/` anywhere\nin the vault tree are protected from agent writes. These typically hold\nirreplaceable originals (tax records, legal filings, vital docs, property\ndeeds). Agents can read them to generate summaries and indexes, but cannot\ncreate, modify, rename, move, or delete files inside them.\n\n**Destructive command guards.** Recursive `rm` and `mv` targeting paths\nthat appear to be inside an Obsidian vault are blocked.\n\n**Published file guard.** Write and Edit to any vault file with\n`dg-publish: true` in its frontmatter are blocked — edits to published\nfiles go live on the website and require explicit user confirmation.\n\n**Auto-memory redirect.** Agents are blocked from writing operational\nknowledge (`feedback_*.md`, `project_*.md`, `reference_*.md`) to their\nper-project auto-memory. Auto-memory is a silo invisible to other sessions,\nother tools, and vault search. The hook redirects this knowledge to a\nstandardized vault location, scoped to the agent's current context:\n\n- Inside a git repo → `<vault>/wiki/repos/<owner>/<repo>/memory/` (parsed\n  from `git remote get-url origin`; portable across hosts).\n- Outside any repo → `<vault>/wiki/systems/machines/<hostname>/memory/`\n  (host-scoped fallback).\n\nEach memory dir mirrors Claude's native layout (`MEMORY.md` index plus\none `feedback_*.md` / `project_*.md` / `reference_*.md` per fact), so\nthe workflow is identical — only the storage location changes. The\nSessionStart primer surfaces the resolved path so agents know where\nto read and write at session start. Migrate existing per-project\nmemories with `scripts/migrate_claude_memory.py`.\n\n**Escape hatch.** Prefix a Bash command with `I_AM_BEING_CAREFUL=1` to\nbypass the `_sources/` and published-file guards after the user explicitly\nconfirms. The auto-memory redirect has no escape hatch — write to the wiki\ninstead.\n\n### For agents: add this line to the user's primary `CLAUDE.md`\n\nBuilt-in Claude auto-memory under `~/.claude/projects/*/memory/` is\nreplaced by the `obsidian-knowledge` plugin. Agents should add a single\npointer to the user's primary memory file (`~/.claude/CLAUDE.md`) so\nsessions on hosts without this plugin still know where to look:\n\n```markdown\nAgent memory is managed by the obsidian-knowledge plugin; refer to it\nfor memory location, read/write conventions, and session-start recall.\n```\n\n### Stop hooks\n\nCapture hooks support Claude and Codex transcripts and emit at most once per human\nturn. Hook prompts, goal continuations, and injected environment instructions do not\nrearm capture; elapsed time alone never does. Without a readable transcript, capture\nemits at most once per session; without session identity it stays silent. Capture can\nrun outside the vault when exactly one vault is configured. Other maintenance hooks\nretain their own vault and cooldown gates.\n\nThe capture reminder also asks agents to repair verified stale instructions already\nencountered, under the instruction-repair rules in the obsidian-knowledge skill. It\ndoes not request a new audit or authorize policy changes.\n\n- **capture-session.py** — makes one selective capture decision. The default is\n  to file nothing; qualifying information must be durable, novel, reusable,\n  searched for first, and not cheaply recoverable from another source\n- **scan-vault-secrets.py** — runs `detect-secrets` against the vault\n  and surfaces unaudited findings to the agent. The plugin makes no\n  assumptions about which password manager you use — agents are told\n  to follow your vault's documented secrets-management convention, so\n  **document yours somewhere agents can find it** (root `CLAUDE.md` or\n  a wiki note). The first scan walks the entire vault (slow, ~1 min\n  on a few thousand files); subsequent scans are incremental against\n  the baseline at `<vault>/.secrets.baseline`.\n\n  Marks false positives two ways:\n  - **Inline sentinel** (recommended for prose notes) — append on the\n    same line:\n    ```\n    token = \"fake\"  <!-- pragma: allowlist secret -->     # markdown / xml\n    token = \"fake\"  # pragma: allowlist secret             # yaml / sh / py\n    token = \"fake\"  // pragma: allowlist secret            # js / go / c\n    ```\n  - **Baseline audit** (batch-mark existing findings):\n    ```\n    detect-secrets audit <vault>/.secrets.baseline\n    ```\n\n  The hook uses the `detect-secrets` Python API directly with a filter\n  set tuned for prose: it drops the `is_likely_id_string` and\n  `is_indirect_reference` filters that the `detect-secrets scan` CLI\n  applies, because those silently swallow the `token = \"...\"` pattern\n  exactly as it appears in markdown notes. Lower-entropy passphrases\n  that elude detect-secrets entirely (dictionary-word passwords in\n  narrative prose) can be added one-per-line to\n  `<vault>/.secrets.known-leaked` for verbatim string-match alerting.\n\n  Requires [`uv`](https://docs.astral.sh/uv/) on `PATH` (the hook is a\n  uv inline script — `detect-secrets` is installed automatically into a\n  uv-managed cache, no global pip install needed).\n\n### recall-init (SessionStart)\n\n`recall-init.py` runs at every session start. Injects the harness\nprimer: a compact context block covering memory location, recall\nvia `obsidian-knowledge search`, capture at session end, and friction\nreflection. The primer stands alone — agents that read only this know how\nto operate within the harness.\n\n### reflect-nudge (PostToolUse on Bash)\n\n`reflect-nudge.py` fires every 100 bash invocations within a session.\nContinuous — no per-session suppression. Reminds the agent to step back\nand log any observed workflow friction as a papercut.\n\n## Commands\n\n### obsidian-knowledge papercut \"<description>\"\n\nAppends the friction to `wiki/repos/<owner>/<repo>/PAPERCUTS.md` when the current\ndirectory belongs to a Git repository with an identifiable `origin`. Outside such\na repository, it falls back to `wiki/systems/knowledge-base/PAPERCUTS.md`. The\nlog is lock-protected for concurrent agents. It records friction only—it does not\ndiagnose the issue or modify the harness.\n\nReports created by v3.22.24 remain untouched under\n`wiki/systems/knowledge-base/papercuts/`; they are not automatically assigned to a\nrepository because their original scope may be ambiguous.\n\n### obsidian-knowledge search \"<query>\"\n\nSearches the indexed `wiki/` tree and returns ranked `score  path` lines.\nPass `--all` to include normally-hidden zones (`Inbox/`, `Journal/`).\n\n### Hermes plugin install\n\nInstall the repo with Hermes's native plugin manager:\n\n```bash\nhermes plugins install crypdick/obsidian-knowledge --enable\nhermes config set memory.provider obsidian-knowledge\nhermes config set memory.memory_enabled false\nhermes config set memory.user_profile_enabled false\n```\n\nThe installed checkout is both a general Hermes plugin (vault-protection and\nreminder hooks) and a memory provider (`obsidian-knowledge`) for primer, prefetch,\n`vault_search`, and a provider-owned `memory()` redirect error. The built-in\nHermes `MEMORY.md` / `USER.md` prompt snapshots should be disabled when this\nprovider is active; durable Hermes profile facts live in the vault at\n`wiki/systems/knowledge-base/index.md`, which is injected with a hard size cap\nand should stay a thin wikilink index to detailed notes. Use\n`hermes plugins update obsidian-knowledge` after pushing repo updates.\n\n### obsidian-knowledge remember \"<memory>\"\n\nDeterministic placement helper for durable facts. It does not write files or\ninvoke an agent. It searches the vault and prints scored candidate homes so a\nhuman or agent can choose where to store the memory.\n\n## Requirements\n\n- [Obsidian](https://obsidian.md/) with CLI enabled\n  (`Settings → General → Command line interface`)\n- The following Obsidian settings must be enabled:\n  - **Use [[Wikilinks]]** (`Settings → Files and Links`)\n  - **Automatically update internal links** (`Settings → Files and Links`)\n- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with plugin\n  support\n- [`uv`](https://docs.astral.sh/uv/) on `PATH` — required by\n  `scan-vault-secrets.py` and the `obsidian-knowledge` CLI\n- [Ollama](https://ollama.com/) installed and running locally, with the\n  `bge-m3` embedding model pulled. Optional; enables better search ranking.\n\n## Installation\n\n```bash\n# 1. Install the CLI\nuv tool install obsidian-knowledge\n\n# 2. Run setup (registers vault, installs claude plugin if available, initial reindex)\nobsidian-knowledge setup --vault /path/to/your/obsidian/vault\n\n# 3. Install Ollama and pull the default embedding model (optional — improves search ranking)\nbrew install ollama          # macOS; or see ollama.com/download\nbrew services start ollama   # macOS; on Linux: `ollama serve` (systemd)\nollama pull bge-m3\n```\n\n`setup` is idempotent — safe to re-run. If `claude` is not on `PATH`, the plugin install step is skipped automatically.\n\nUpgrade the CLI with `uv tool upgrade obsidian-knowledge`.\n\nPyPI publishing runs after successful push CI on `main`, including docs-only\nchanges. An unpublished manual version is preserved; otherwise the latest patch\nversion is incremented. The release synchronizes Python, Claude, Codex, and Hermes\nversions, reruns checks, and commits the version before uploading. Tags are not\nrequired. Superseded CI runs defer to the newer push; failed uploads can be retried\nwithout another bump. The bot's version commit does not trigger another CI run.\n\nThe protection hooks use `vaults.yaml` to know which directories to guard.\nWithout it, the `_sources/`, published-file, and destructive-ops rules will\nnot fire.\n\n### Switching embedding models\n\nOverride any of the defaults via environment variables:\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `MEMWEAVE_EMBEDDING_MODEL` | `ollama/bge-m3` | LiteLLM model identifier |\n| `MEMWEAVE_EMBEDDING_API_BASE` | `http://127.0.0.1:11434` | Ollama / LiteLLM endpoint |\n| `MEMWEAVE_EMBEDDING_API_KEY` | unset | API key (leave unset for Ollama) |\n\nWhen the embedding model changes, the next `obsidian-knowledge search` call detects the\nmismatch and rebuilds the index automatically. The fingerprint\n(`<model>@<chunk-tokens>/<chunk-overlap>`) is stored alongside the index.\n\n### Cache location\n\nThe embedding DB lives outside the vault, in the per-host XDG cache\ndirectory:\n\n| OS | Path |\n|---|---|\n| Linux | `${XDG_CACHE_HOME:-~/.cache}/obsidian-knowledge/<vault-key>/` |\n| macOS | `~/Library/Caches/obsidian-knowledge/<vault-key>/` |\n\n`<vault-key>` is `<vault-dir-name>-<sha256(absolute_path)[:8]>`, so two vaults\nnamed `obsidian/` on different machines (or in different parents) never\ncollide. Each host owns its own embeddings DB — Syncthing and other vault\nsync tools never see it, eliminating cross-device write conflicts.\n\nA pre-3.16 install with the old in-vault cache (`<vault>/.config/obsidian-knowledge/cache/`)\nwill trigger one auto-rebuild on first use. The old directory is safe to\ndelete once the new cache is populated.\n\n### Keeping the index fresh\n\nThere is no built-in file-watcher. Content added or edited between reindexes\nis invisible to `obsidian-knowledge search` until the next reindex. An hourly cron is\nthe recommended baseline:\n\n```cron\n# Linux\n0 * * * * $HOME/.local/bin/obsidian-knowledge reindex --vault $HOME/Documents/obsidian >> $HOME/.cache/obsidian-knowledge/cron.log 2>&1\n\n# macOS (Apple Silicon)\n0 * * * * $HOME/.local/bin/obsidian-knowledge reindex --vault $HOME/Documents/obsidian >> $HOME/Library/Caches/obsidian-knowledge/cron.log 2>&1\n```\n\nIncremental reindex is cheap: ~8s wall on a ~1700-file vault with zero\nedits (all files hash-skip). Only modified files get re-embedded. Overlap\nis guarded by an `fcntl.flock` on `<cache>/.reindex.lock` — a second run\nthat fires while the first is still active exits cleanly without\ntouching the DB.\n\n## Usage\n\nInvoke the skill directly:\n\n> Organize my vault / update indexes / fix broken links / rename ambiguous\n> files / garden the vault\n\nOr set up a scheduled run for routine maintenance.\n\nThe skill stores its state in your vault at\n`Utility/obsidian-knowledge/`:\n\n- `changelog/` — terse same-session audit pointers created only after durable vault mutations\n- `needs-attention.md` — human-resolved worklist\n- `reports/open-questions.md` — regenerated dashboard of `> [!question]` callouts\n\nHistorical state was under `.config/obsidian-knowledge/` prior to v1.1.0.\n\n### Vault configuration\n\nFor best results, add a `CLAUDE.md` to your vault root with naming\nconventions and instructions to invoke the skill after structural edits.\n\nThe vault-organizer respects access zones defined in\n`.claude/vault-zones.yaml`. Create this file to control which folders\nthe agent can organize, where indexes are required, and which areas\nare read-only. See the skill's documentation for the expected format.\n\n## License\n\nMIT\n",
  "bytes": 14790,
  "sha": "8d063ede2dbb62d207c0bf27d80648edc8611f1e05714d947ba7b20e9cde4337",
  "repo_slug": "crypdick/obsidian-knowledge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_crypdick_obsidian_knowledge_obsidian_kno_48ad2917/readme"
}