{
  "markdown": "# Claude Obsidian Vault Skill\n\n![Banner](docs/assets/banner.jpg)\n\n**English** | [Türkçe](README.tr.md)\n\n> Give Claude Code a persistent memory. Every session is archived into a searchable markdown wiki — so past decisions, bugs, and patterns are always in context, never re-explained.\n\n---\n\n## Why bother?\n\nWithout a vault, every Claude Code session starts from zero. You re-explain the same architectural decisions, Claude rediscovers bugs you already fixed, and patterns from three months ago are as invisible as if they never happened.\n\nWith a vault:\n\n- **Past decisions are in context before your first message** — Claude reads them automatically at session start\n- **Bugs stay fixed** — root causes and fixes are recorded and surfaced\n- **Knowledge compounds** — every session makes the next one better\n\n---\n\n## Install\n\nPick one method. Both install the same skill, commands, and hook.\n\n### Option A — Claude Code plugin (recommended)\n\nType these two commands inside Claude Code:\n\n```\n/plugin marketplace add mehmetcakoglu/claude-obsidian-vault-skill\n/plugin install vault@claude-obsidian-vault-skill\n```\n\nThen **restart your Claude Code session**.\n\n### Option B — Standalone (macOS / Linux)\n\n```bash\ngit clone https://github.com/mehmetcakoglu/claude-obsidian-vault-skill.git\ncd claude-obsidian-vault-skill\n./install.sh\n```\n\n### Option C — Standalone (Windows PowerShell)\n\n```powershell\ngit clone https://github.com/mehmetcakoglu/claude-obsidian-vault-skill.git\ncd claude-obsidian-vault-skill\n.\\install.ps1\n```\n\n> **Requires Python 3.7+** in PATH on all platforms.\n\n**Custom vault location** — set `CLAUDE_VAULT` before installing:\n\n```bash\nCLAUDE_VAULT=/my/path ./install.sh          # macOS / Linux\n$env:CLAUDE_VAULT = \"D:\\my-vault\"; .\\install.ps1  # Windows\n```\n\nAfter a standalone install, **restart your Claude Code session** for the `SessionStart` hook to activate.\n\n> **Plugin install (Option A):** The global vault (`~/Global Claude Vault/`) is created automatically on the first session start — no extra step needed.\n\n---\n\n## First-time setup (5 minutes)\n\n**1. Verify the install**\n\nIn a new Claude Code session, run:\n```\n/vault:status\n```\nYou should see your vault path, plugin version, and config — all green. If anything is wrong, it tells you what to fix.\n\n**2. Bootstrap a project vault** _(optional but recommended)_\n\nNavigate to a project and run:\n```\n/vault:init\n```\nAuto-detects your project name and stack, creates `docs/vault/` instantly — no questions asked. Edit `docs/vault/CLAUDE.md` afterwards to add domain terms. Pass `--interactive` if you want to fill in details upfront.\n\n**3. Archive your first session**\n\n```\n/vault:scan          # see what's waiting in the queue\n/vault:ingest        # archive the top session\n```\n\nThat's it. From here, the `SessionStart` hook scans automatically every time Claude Code starts. Just run `/vault:ingest` when you're ready to archive.\n\n---\n\n## Commands\n\n| Command | What it does | Docs |\n|---|---|---|\n| `/vault:help` | Quick-reference card for all commands | [→](docs/commands/vault-help.md) |\n| `/vault:status` | Health check — vault path, version, queue size, config | [→](docs/commands/vault-status.md) |\n| `/vault:doctor` | Scan both vaults for structural, frontmatter, link, and lint issues — then offer to fix them | [→](docs/commands/vault-doctor.md) |\n| `/vault:init` | Bootstrap `docs/vault/` for the current project | [→](docs/commands/vault-init.md) |\n| `/vault:scan` | Refresh + display the pending-ingest queue | [→](docs/commands/vault-scan.md) |\n| `/vault:ingest [id]` | Archive the next (or a specific) pending session | [→](docs/commands/vault-ingest.md) |\n| `/vault:batch-ingest [N\\|all]` | Archive up to N sessions in one run (default 5) | [→](docs/commands/vault-batch-ingest.md) |\n| `/vault:skip <id>` | Permanently remove a session from the queue | [→](docs/commands/vault-skip.md) |\n| `/vault:auto-ingest [on\\|off\\|status]` | Toggle automatic archiving at session start | [→](docs/commands/vault-auto-ingest.md) |\n| `/vault:auto-ingest [on\\|off] [max N]` | Also set the per-session maximum | [→](docs/commands/vault-auto-ingest.md) |\n| `/vault:update` | Pull latest version from GitHub and reinstall | [→](docs/commands/vault-update.md) |\n\n**Full technical documentation:** [docs/index.md](docs/index.md) — architecture, file layout, data flow, and per-command reference.\n\n---\n\n## Everyday use\n\n### Archiving sessions\n\nSessions appear in the queue ~10 minutes after they end. Process them whenever it suits you:\n\n> **Privacy note:** The queue (`state/pending.md`) stores the first ~120 characters of your first prompt per session as a plain-text preview. This snippet is written verbatim and is not secret-filtered. Avoid storing API keys or passwords in your first message if you share the vault directory.\n\n```\n/vault:scan              # check the queue\n/vault:ingest            # archive one session (biggest first)\n/vault:batch-ingest 3    # archive up to 3 at once\n/vault:skip a1b2c3d4     # skip a session you don't want archived\n```\n\nEach ingested session is routed automatically:\n- If the project has `docs/vault/CLAUDE.md` → **project vault**\n- Otherwise → **global vault** at `~/Global Claude Vault/`\n\n### Asking questions\n\nJust ask naturally. The `vault` skill activates on phrases like:\n- _\"what did we decide about X?\"_\n- _\"have we seen this bug before?\"_\n- _\"why did we choose Y?\"_\n\nClaude reads the right `index.md`, follows the links, and cites its sources.\n\n### Vault hygiene\n\nRun `/vault:doctor` to scan both vaults for structural and content issues ([full reference](docs/commands/vault-doctor.md)):\n\n```\n/vault:doctor\n```\n\nIt checks four categories, reports what it finds, then asks whether to fix everything automatically, interactively, or just save the report:\n\n| Check | What it catches | Auto-fixable |\n|---|---|---|\n| **Structure** | Missing folders (`bugs/`, `state/`, …) and required files | ✓ |\n| **Frontmatter** | Missing fields, invalid `status:` values (e.g. `ingested` → `archived`) | ✓ |\n| **Links** | Dead links in `index.md`, broken wikilinks in reports, pages missing from index | ✓ partial |\n| **LINT** | Stale pages (>90 days `active`), `source:manuel` without a `## Sources` section | ✓ |\n\nNon-fixable issues (orphan pages, broken links in source files, `CLAUDE.md` placeholder links) are listed for manual review.\n\nFor a freeform lint pass — orphan pages, stale claims, dead code references, duplicate entities — ask naturally:\n\n```\ncheck the vault\n```\n\nClaude writes the findings to `syntheses/lint-YYYY-MM-DD.md`.\n\n---\n\n## Configuration\n\nSettings live in `~/Global Claude Vault/vault-config.json`. The easiest way to change them is via slash commands:\n\n```\n/vault:auto-ingest status       # check current state\n/vault:auto-ingest on           # enable automatic archiving\n/vault:auto-ingest on max 3     # enable, process at most 3 sessions per start\n/vault:auto-ingest off          # disable (manual mode, the default)\n```\n\n**When to enable auto-ingest:** you trust Claude's judgment on what to archive and want zero maintenance.\n\n**When to leave it off (default):** you want to review each session before it's written, or archiving would interrupt your flow.\n\n---\n\n## How it works\n\n> For a deeper dive — session lifecycle, update system, file layout — see the [technical documentation](docs/index.md).\n\n```\n~/.claude/projects/*/*.jsonl        (Claude Code session transcripts)\n          │\n          │  vault-context.py runs at every session start (synchronous)\n          │    ├─ scans the pending queue\n          │    ├─ auto-creates a project entity if none exists\n          │    └─ injects vault index + recent sessions → Claude context\n          ▼\n   ~/Global Claude Vault/state/pending.md\n          │\n          │  /vault:ingest (user-triggered, or automatic with auto_ingest=true)\n          ▼\n    ┌─────┴──────────────────────────────────┐\n    │                                        │\n    ▼                                        ▼\nGlobal vault                         Project vault\n~/Global Claude Vault/               <repo>/docs/vault/\n · cross-project decisions            · domain-specific rules\n · Claude Code patterns               · architectural decisions\n · lessons learned                    · bug/fix history\n                                      · entities & concepts\n    │                                        │\n    └──────────── shared ingested.txt ───────┘\n           (a session is never archived twice)\n```\n\nThe scan and context injection happen automatically. Ingesting (writing pages) is user-triggered by default, because it filters secrets, decides routing, and writes permanent files — that deserves a human in the loop.\n\nWhen opened in Obsidian, the vault becomes a navigable knowledge graph:\n\n![Obsidian graph view of a vault](docs/assets/obsidian-graph.png)\n\n_Each node is a page (session, decision, entity, concept, bug). Larger nodes have more inbound links — these are the most-referenced pieces of knowledge in your archive._\n\n---\n\n## Token savings\n\n`/vault:status` shows how many tokens the vault has saved. Here's how that number is calculated — and why it's meaningful.\n\n### How Claude Code sessions actually work\n\nEvery time you send a message, Claude Code sends the **entire conversation history up to that point** to the API. A session with 10 prompts sends context cumulatively:\n\n```\nTurn 1:   30K tokens sent\nTurn 2:   60K tokens sent   ← full history resent\nTurn 3:   90K tokens sent\n...\nTurn 10: 300K tokens sent\n─────────────────────────\nTotal:   ~1.65M tokens sent to the API during the session\n```\n\nThe session JSONL file on disk stores each message **once** — so a 3 MB file represents ~600K tokens of unique content, not the 1.65M actually sent.\n\n### What \"savings\" means here\n\nThe vault doesn't reduce tokens spent *during* a session. What it eliminates is the **cold-start cost** at the beginning of every *future* session — the tokens that would otherwise be spent re-reading files and re-explaining past decisions.\n\n```\nWithout vault — future session:\n  Read key files to reconstruct context  ~50–600K tokens\n  User re-explains past decisions        ~300 tokens\n  Claude re-discovers known patterns     (and sometimes gets them wrong)\n\nWith vault — future session:\n  Inject pre-digested summary            ~800–2,000 tokens\n```\n\n### How savings are measured\n\nThe JSONL file size is the ground truth for \"how much information was in this session.\" To understand that session's content in a future conversation without a vault, you'd need to read some or all of that transcript. The vault condenses it to a small summary injected at session start.\n\n```\nsavings per session ≈ (JSONL bytes ÷ 4) − injection tokens\n```\n\n_1 token ≈ 4 characters — a consistent estimate used throughout the codebase and token log. All numbers are estimates; actual tokenization varies by model and content._\n\nA 3 MB session contains ~750K tokens of information. The vault injects ~1,200 tokens of its essence. The compression ratio is typically **200–500×**.\n\n---\n\n## Compatibility\n\n| Platform | Status |\n|---|---|\n| macOS | Full support |\n| Linux | Full support |\n| Windows (Git Bash / WSL) | Full support via `install.sh` |\n| Windows (PowerShell) | Full support via `install.ps1` |\n| Claude.ai web / Claude Work | Not supported (no local filesystem) |\n\n---\n\n## Credits\n\nBuilt on the **LLM-Wiki pattern** (`RAW → WIKI ← SCHEMA`) by\n[Selma Kocabıyık](https://github.com/selmakcby) —\n[knowledge-pipeline](https://github.com/selmakcby/knowledge-pipeline).\n\nClaude Code packaging (slash commands, auto-scan, hybrid scoping, session registry) by\n[Mehmet Çakoğlu](https://github.com/mehmetcakoglu).\n\nSee [`docs/ATTRIBUTION.md`](docs/ATTRIBUTION.md) for the full attribution.\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| [Technical docs](docs/index.md) | Architecture, file layout, data flow, update system |\n| [Command reference](docs/commands/) | Detailed per-command docs with files read/written |\n| [Examples](docs/EXAMPLES.md) | Worked examples: ingest, query, doctor, cross-project |\n| [Concepts](docs/CONCEPTS.md) | LLM-Wiki pattern, hybrid vault design |\n\n---\n\nMIT License — see [`LICENSE`](LICENSE).\n",
  "bytes": 12172,
  "sha": "542f866ec00e6d228bc698ffac4386d9cbb7f29630c73d367c11ce9f442cd61f",
  "repo_slug": "mehmetcakoglu/claude-obsidian-vault-skill",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_mehmetcakoglu_claude_obsidian_vault_skil_3b01ec3c/readme"
}