Knowledge Vault v2.6.0

Knowledge Vault 2.6.0 is a cross-platform integrity and host-compatibility release for Codex and Claude Code.

Highlights

• Consolidates both hosts on one canonical knowledge-vault skill while retaining 13 manual Claude Code slash commands.
• Adds a Python 3.10+ vault CLI with locking, atomic ingestion, recovered-original attachment, compile-state transitions, and rollback.
• Makes pending indexing idempotent and treats missing summaries, malformed state, and raw/manifest drift as explicit lint failures.
• Keeps untrusted source metadata out of shell syntax through structured JSON requests, validated downloads, safe manifest paths, and escaped generated Markdown.
• Adds cross-platform PageIndex, MCP detection, PDF extraction, and source-recovery helpers; legacy shell entry points remain as adapters.
• Pins optional arXiv, Paper Search, Zotero, Sci-Hub, and PageIndex dependencies/revisions and documents Codex Consensus OAuth.
• Ignores new .vault/ contents from Git by default, with an explicit init --track opt-in.
• Adds Linux, macOS, and Windows runtime tests plus Codex install and Claude manifest validation in CI.

Existing vault data remains compatible. Re-run initialization to repair missing directories or host guidance without replacing vault content.

See CHANGELOG.md for the full change list.

Knowledge Vault v2.5.1

Highlights

• One concise, lazily routed Codex skill covers all vault workflows.
• Claude Code slash commands use the same shared workflow definitions.
• Codex and Claude MCP setup paths are host-aware and credential-safe.
• Initialization is idempotent and adds both AGENTS.md and CLAUDE.md guidance.
• Ingestion now validates manifests first, tracks Zotero full-text state, and registers inbox clippings correctly.
• Optional PageIndex installs a pinned upstream revision instead of shipping a large vendored source tree.
• Cross-host validation covers Codex marketplace installation, Claude strict manifests, special-character paths, corrupt manifests, and runtime helpers.

See CHANGELOG.md for the full audit summary.

v2.4.2 — Claude Code regression fixes + audit hardening

Why this release matters

v2.4.1 was broken on Claude Code — upgrade immediately. Its Codex-compatibility rewrite replaced ${CLAUDE_PLUGIN_ROOT} with a bash-fallback form that Claude Code's template substitution does not recognize, which broke every scripted step of every command. v2.4.2 restores full Claude Code operation and completes the marketplace rename that v2.4.1 started.

Fixed — v2.4.1 regressions

• ${CLAUDE_PLUGIN_ROOT} restored in all commands, agents, and skills. hooks/hooks.json keeps the Codex fallback form (hooks receive the variable as an environment variable, so it resolves safely there).
• Marketplace rename completed: the root manifest now declares name: knowledge-vault / 2.4.2 (it was left at claude-knowledge-vault / 2.4.0, so the README's install commands pointed at a marketplace that didn't exist and update checks never surfaced 2.4.1). The duplicate in-plugin marketplace.json is gone.
• Codex MCP detection now reads the real Codex config (~/.codex/config.toml [mcp_servers]) instead of files Codex never writes.

Fixed — hardening from the full v2.4.0 audit

• /process clippings now enter raw/.manifest.json — previously they were silently skipped by /compile and erased by the next index rebuild.
• /enrich-references can actually find candidates: ingest-zotero.sh now writes has_fulltext (and accepts a type param instead of hardcoding paper).
• PageIndex setup no longer writes an empty .env when ANTHROPIC_API_KEY is unset — the old behavior made detection report PageIndex as configured while every tree build silently failed.
• Shell-into-Python injection removed from update-frontmatter.sh / index-append.sh / vault-status.sh — paths and slugs with apostrophes are now safe.
• Manifest is validated before raw files are written (no more orphaned raw files after a corrupt manifest).
• init.sh creates the documented inbox/ drop location; /init stops instead of overwriting preferences.md on re-run.
• build-tree.sh probes all required Python deps (PyPDF2, yaml) and matches PageIndex's output naming for non-lowercase .PDF files.
• detect-mcp-sources.sh scans .mcp.json (fixes Sci-Hub never being detected), deduplicates, and tolerates malformed config files.
• /cleanup backfill verifies every recovered file is a real PDF; Zotero fulltext (text, not bytes) is no longer saved as a fake .pdf.
• /ingest no longer double-builds (or impossibly pre-builds) PageIndex trees; /process confirms before batch tree-building >3 PDFs; /query tier 4 preflights pdftotext.
• Friendlier one-line errors replace Python tracebacks in render-tree-outline.sh, rebuild-index.sh, update-state.sh, and the session hook.
• Docs: retracted the stale "No PDFs are stored in the vault" claim (v2.4 deliberately preserves originals), real tree.json shape shown, repo-root LICENSE added, VENDORED.md update recipe excludes the user's .env.

Migration

Added the marketplace before the rename? One-time re-add:

/plugin marketplace remove claude-knowledge-vault
/plugin marketplace add psypeal/knowledge-vault
/plugin install knowledge-vault@knowledge-vault

Known limitations (vendored PageIndex, upstream)

No page cap / concurrency limit on very large PDFs; retry exhaustion can yield empty summaries; scanned image-only PDFs still spend tokens producing a junk tree. Tracked for a future vendored update.

🤖 Generated with Claude Code

Knowledge Vault v2.4.1

What's Changed

• Added marketplace compatibility so the plugin can be installed and managed in Codex while retaining Claude Code compatibility.
• Normalized plugin registration and marketplace identifiers to knowledge-vault (including install and marketplace IDs).
• Added Codex-specific plugin manifest (.codex-plugin/plugin.json) and updated repo/package metadata paths for cross-host compatibility.
• Added a dedicated marketplace metadata entry for distribution (.claude-plugin/marketplace.json).
• Bumped plugin version to 2.4.1 for this compatibility and packaging release.

Note

The release keeps existing plugin behavior and extends installability via third-party marketplaces, including the Codex marketplace flow.

v2.4.0 — PageIndex tree indexing + preserved originals

Highlights

• Preserved originals — every ingested PDF (and EPUB / HTML clip) is now kept under .vault/originals/<slug>.<ext>, renamed to a bibliographic slug for long-term audit and re-reading.
• Bibliographic slugs: papers → <first-author>-<year>-<keyword> (e.g. vaswani-2017-attention); reports / manuals / filings / guidelines → <org-abbrev>-<year>-<keyword> (e.g. who-2023-tuberculosis); other types keep title-based slugs from v2.3. Disambiguation suffixes -2, -3 are added automatically.
• PageIndex tree indexing — vendored VectifyAI/PageIndex (MIT) routes through Claude Sonnet 4.6 via LiteLLM. Every PDF gets a hierarchical "table of contents" tree at raw/<slug>.tree.json, and the markdown body becomes a tree-derived outline.
• 4-tier query routing — /knowledge-vault:query now cascades: index.md → wiki/concepts + wiki/summaries → tree.json reasoning → page-range pdftotext extraction from the original. Compiled knowledge handles the easy 80%; trees route the hard 20% straight to the relevant pages instead of dumping the whole document into context.
• v2.3 → v2.4 backfill — /knowledge-vault:cleanup now offers an opt-in, idempotent backfill that recovers PDFs for legacy items via Zotero MCP, Unpaywall/Sci-Hub, or direct URL — preserving the existing slug so wikilinks don't break.
• Lint picked up two new checks (originals integrity + tree integrity) — 10 checks total.

Setup

PageIndex is bundled but opt-in. To enable:

/knowledge-vault:setup-sources

Select PageIndex. The command runs pip3 install -r vendor/PageIndex/requirements.txt, verifies ANTHROPIC_API_KEY, writes a .env for the runner, and smoke-tests it.

If PageIndex isn't set up, the plugin works exactly as in v2.3 (flat condense). If a tree build fails on a particular PDF, that item silently falls back to flat condense — has_tree: false records this so a future retry can rebuild.

Migration

Existing v2.3 vaults work unchanged. To opportunistically backfill old items:

/knowledge-vault:cleanup

It scans the manifest, categorizes recoverable items (Zotero / DOI / direct URL), and walks through them with your approval. The body is left alone — only originals/ and tree.json are filled in.

Credits

VectifyAI/PageIndex — vectorless reasoning-based RAG, vendored under plugins/knowledge-vault/vendor/PageIndex/ (pinned commit dcda565).

v2.3.0 — Sci-Hub as peer source; relaxed install confirmation

What's new

Two user-facing fixes for the PDF enrichment flow, driven by feedback that v2.2.x was too rigid when using Sci-Hub.

1. Sci-Hub is now a peer source, not just a fallback

/knowledge-vault:enrich-references now works with either Unpaywall or Sci-Hub on its own — no need to configure Unpaywall if you only want to use Sci-Hub.

Configured sources	Behavior
Unpaywall only	Same as before — OA-only lookup
Sci-Hub only	New — Sci-Hub handles every candidate directly
Both Unpaywall + Sci-Hub	Unpaywall runs first per item; Sci-Hub picks up the misses
Neither	Command stops with a helpful message listing how to enable at least one

2. Relaxed install confirmation for Sci-Hub

/knowledge-vault:setup-sources step 4a no longer requires a verbatim yes — any affirmative reply works (yes, y, ok, sure, proceed, go, continue — case-insensitive). Only a clearly negative reply (no, cancel, stop) cancels. The legal disclosure is still shown once so users know what they're opting into.

Migration

• No user action required. Your existing .vault/.scihub-enabled marker files continue to work. If you had Unpaywall configured as the sole source, your workflow is unchanged.
• If you want Sci-Hub standalone on a fresh project: skip the UNPAYWALL_EMAIL export and run /knowledge-vault:setup-sources → select Sci-Hub.

Other changes

• README "Advanced: Sci-Hub fallback" renamed to "Advanced: Sci-Hub (opt-in, per-project)". Anchors updated.
• Per-item status key no-oa-found + unpaywall-miss unified to no-pdf-found.
• Flowchart and sample output reflect dual-source logic.
• Stale reference to removed /knowledge-vault:setup-scihub command fixed.

Install / update

If you already have the marketplace configured:

/plugin update knowledge-vault

Otherwise: see the Install section in the README.

---

Full changelog: v2.2.1...v2.3.0

v2.2.1 — Fold Sci-Hub install into setup-sources

Simplification

The dedicated /knowledge-vault:setup-scihub command is removed. Sci-Hub now installs through the same /knowledge-vault:setup-sources flow as every other recommended MCP — selecting it triggers a Sci-Hub-specific sub-procedure (disclaimer + explicit consent + uv tool install + claude mcp add scihub -s project + per-vault marker file).

Why

Having one MCP with its own dedicated install command was inconsistent with how Zotero, arXiv, Consensus, Paper Search, and Unpaywall are all configured. setup-sources is the canonical entry point for MCP setup; Sci-Hub belongs there too.

What stays the same

All the safeguards from v2.2.0 are preserved:

• Explicit yes required after the disclaimer.
• Project-scope MCP registration (-s project) — Sci-Hub never enabled user-globally.
• Per-vault marker file .vault/.scihub-enabled as the opt-in gate.
• Disable: rm .vault/.scihub-enabled && claude mcp remove scihub.

What changes

	v2.2.0	v2.2.1
Install command	/knowledge-vault:setup-scihub	/knowledge-vault:setup-sources (select Sci-Hub)
enrich-references trailing tip	"run /knowledge-vault:setup-scihub"	"run /knowledge-vault:setup-sources and select Sci-Hub"
README Supported servers row	Setup column = /knowledge-vault:setup-scihub	Setup column = run /knowledge-vault:setup-sources
Number of slash commands	+1 (setup-scihub)	unchanged from v2.1.x

Migration

If you already enabled Sci-Hub via v2.2.0's /knowledge-vault:setup-scihub, nothing breaks — the MCP is still registered and the marker file still exists. You just won't be able to re-run setup-scihub (it's gone). Re-running would be redundant anyway since the marker check skips already-enabled vaults.

v2.2.0 — Unpaywall PDF enrichment + opt-in Sci-Hub fallback

New: Unpaywall PDF enrichment

/knowledge-vault:enrich-references finds open-access PDFs for reference-only raw items (those with has_fulltext: false and a doi: field — typically Zotero items imported from PubMed/Crossref without an attached PDF). For each candidate it queries the Unpaywall API, downloads the OA PDF if available, runs pdftotext, condenses the result into the same Metadata / Abstract / Key Findings / Methods / Quantitative Data structure used by /knowledge-vault:ingest-zotero, and flips has_fulltext: true so the next compile picks it up.

Setup

export UNPAYWALL_EMAIL=you@example.com   # add to ~/.bashrc or ~/.zshrc to persist
sudo apt install poppler-utils           # provides pdftotext (optional but recommended)

Then:

/knowledge-vault:enrich-references            # scan all reference-only items
/knowledge-vault:enrich-references <slug>     # target a single item

Unpaywall is free, requires no signup, and indexes ~40-50% of all DOIs.

New: Optional, per-project Sci-Hub fallback

For papers Unpaywall can't find, an opt-in fallback routes the lookup through the community riichard/Sci-Hub-MCP-Server. It is strictly opt-in and per-project — never enabled by default and never installed user-globally.

Enable

/knowledge-vault:setup-scihub

This command:

1. Prints a legal disclaimer and requires explicit yes to proceed.
2. Installs the MCP via uv tool install "sci-hub-mcp-server @ git+https://github.com/riichard/Sci-Hub-MCP-Server".
3. Registers it at project scope only: claude mcp add scihub -s project -- sci-hub-mcp --transport stdio.
4. Writes a per-vault marker file .vault/.scihub-enabled.

After restart, /knowledge-vault:enrich-references automatically falls through to Sci-Hub when both the marker exists and the mcp__scihub__* tools are visible.

Disable

rm .vault/.scihub-enabled
claude mcp remove scihub

Both are local to the current project. The plugin neither hosts, mirrors, nor distributes any Sci-Hub content — it only invokes a third-party community MCP.

What's in this release

• New command /knowledge-vault:enrich-references — Unpaywall enrichment with optional Sci-Hub fallback
• New command /knowledge-vault:setup-scihub — opt-in installer with disclaimer + per-project MCP registration
• New script scripts/enrich-references.sh — scans raw/ for has_fulltext:false + doi candidates
• scripts/detect-mcp-sources.sh — Unpaywall detection by UNPAYWALL_EMAIL + scihub keyword match
• commands/setup-sources.md — Unpaywall line + footer tip pointing to /knowledge-vault:setup-scihub
• README: new PDF Enrichment (Unpaywall) and Advanced: Sci-Hub fallback sections, Sci-Hub row in the Supported servers table, updated mermaid, credits, and poppler-utils in requirements

Credits

• Unpaywall — open-access PDF discovery API powering /knowledge-vault:enrich-references
• riichard/Sci-Hub-MCP-Server — community MCP server (a fork of JackKuo666's original) used by the optional fallback

v2.1.1 — Concept-link robustness check

Robustness: warn on summaries missing wikilinks

`rebuild-index.sh` now validates that every compiled summary has at least one `[[wikilink]]` in its body. If a summary lacks wikilinks, a warning prints to stderr after the index rebuild — non-fatal, exit code is preserved.

Why

During compile, Claude can take shortcuts that populate `concepts_extracted:` in the YAML frontmatter without adding the corresponding `[[concept]]` links in the summary body. These summaries end up disconnected from the concept graph — they're technically "compiled" but contribute nothing to cross-referencing or queries that depend on wikilink traversal.

The check parses each summary's body only (frontmatter is stripped), so `concepts_extracted: [foo, bar]` metadata does not satisfy the check. A real `[[foo]]` link in the body is required.

Example output

```
Index rebuilt: 8 sources, 12 concepts, 3 outputs

Warning: 2 compiled summaries have no wikilinks to concepts:

• wiki/summaries/shortcut-paper-a.md
• wiki/summaries/shortcut-paper-b.md
  These summaries are disconnected from the concept graph.
  Fix: re-run /knowledge-vault:compile or /knowledge-vault:cleanup.
  ```

Behavior

• Warning only — exit code remains 0, no pipeline break
• Runs on every rebuild (compile, lint, cleanup, post-ingest) — wikilink drift is caught immediately
• Cost is negligible — regex scan over summary bodies, ~microseconds per file

v2.1.0 — Zotero integration

New: Zotero integration

/knowledge-vault:ingest-zotero <collection> batch-ingests papers from a Zotero collection via the zotero-mcp server. Each Zotero item becomes one raw/<slug>.md with Zotero-specific frontmatter (zotero_key, citekey, doi, year, authors). Downstream /knowledge-vault:compile handles Zotero-sourced files identically to PubMed/Scholar-sourced ones.

Setup

```bash
uv tool install zotero-mcp-server && zotero-mcp setup
claude mcp add zotero -s project -e ZOTERO_LOCAL=true -- zotero-mcp serve
```

Then in any project with a .vault/:

```
/knowledge-vault:ingest-zotero
```

Abstract-only handling

Many Zotero collections contain reference-only items — metadata and abstract but no attached PDF. v2.1.0 explicitly handles this case by synthesizing structured Key Findings / Methods / Quantitative Data sections from the abstract itself, producing usable raw files even without fulltext. No stub placeholders.

Validation

• Unit-tested against 4 synthetic fixtures (full metadata, minimal metadata, duplicate slug, YAML escaping) — all pass
• End-to-end validated against a real 63-item Zotero collection (Air-Pollution-Dementia): 3-item batch ingest → manual compile → index rebuild, 100% clean

What's in this release

• New command /knowledge-vault:ingest-zotero — batch ingest from Zotero collection
• New script scripts/ingest-zotero.sh — Zotero-aware raw file creation with extended frontmatter
• scripts/detect-mcp-sources.sh — detects zotero-mcp and adds it to the recommended list
• commands/setup-sources.md — mentions zotero-mcp install
• README: new Zotero Integration section, architecture diagram updated, commands table, credits

Credits

• 54yyyu/zotero-mcp — the Zotero MCP server powering this integration
• Galaxy-Dawn/claude-scholar — inspiration for the Zotero → knowledge-base workflow