vkm-kit is a single, plug-and-play efficiency suite for Claude Code that bundles four previously separate workflows — persistent vault memory, a token-saver, a local usage doctor, and a spec-builder — into one installer package. The repository (Vahlame/create-vkm-kit) ships as the npm package @vkmikc/create-vkm-kit, which exposes two bin entries (create-vkm-kit and vkm) and a thin forward-compat shim (@vkmikc/create-obsidian-memory) that still resolves to the modern kit (Source: CHANGELOG.md:1-22). This page covers scope, installer entry points, what the installer provisions, and how to verify a clean install.

Scope and What vkm-kit Replaces

The kit's defining property is that it is one installer, one config surface, one target host. The 4.0.0 release is the cutover where the project renamed from create-obsidian-memory to create-vkm-kit; the old package name is preserved only as a no-op shim that re-exports the new bin so existing tutorials and bookmarks do not break (Source: CHANGELOG.md:10-22). Internally, four capabilities map onto this single kit:

• Persistent vault memory — an Obsidian-style vault wired into Claude Code through the obsidian-memory-hybrid MCP server, with hybrid SQLite-vec retrieval (Source: config/mcp/obsidian-memory-hybrid.json:1-40).
• Token-saver — deterministic PreToolUse hooks that DENY redundant reads/writes so a smaller fixed cost is paid every session (Source: CHANGELOG.md:180-205).
• Local usage doctor — diagnostics sourced from local observability hooks rather than uploaded telemetry.
• Spec-builder — a RULES contract scaffold (RULES/TEMPLATE.md, es/en) added under the vault for dated, sourced, reasoned project rules (Source: CHANGELOG.md:120-140).

The kit is not an editor, a CI runner, or a replacement for project conventions; it layers on top of Claude Code and any host (Claude Code, Cursor, Codex) that consumes an MCP mcp.json (Source: packages/create-vkm-kit/src/index.js:30-55).

Installation Paths

The package can be invoked three ways, all converging on the same src/index.js entry point:

# 1) npx, no install step
npx @vkmikc/create-vkm-kit

# 2) explicit npm-create shorthand
npm create vkm-kit@latest

# 3) global install (then the `vkm` bin is on PATH)
npm i -g @vkmikc/create-vkm-kit && vkm

All three resolve to the same binary, declared in package.json:

// packages/create-vkm-kit/package.json
{
  "bin": { "create-vkm-kit": "./src/index.js", "vkm": "./src/index.js" }
}

(Source: packages/create-vkm-kit/package.json:10-18)

The forward-compat path npx @vkmikc/create-obsidian-memory-shim still works for users migrating from pre-4.0.0 documentation; the shim simply forwards to the modern bin so old instructions stay valid (Source: packages/create-obsidian-memory-shim/src/index.js:1-20).

What the Installer Provisions

Running vkm is interactive but stateless — it requires no database, no account, and no network credentials. Provisioning is described in src/index.js and the per-surface MCP installer (Source: packages/create-vkm-kit/src/installers/mcp.js:20-95):

• Claude Code — writes ~/.claude/mcp.json (or a project .mcp.json) registering the obsidian-memory-hybrid server with retrieval levers OBSIDIAN_MEMORY_PIN_FAILURES=1 and OBSIDIAN_MEMORY_USAGE_BOOST=1 per ADR-0038.
• Cursor — writes ~/.cursor/mcp.json with the same server entry and same env (Source: CHANGELOG.md:150-165).
• Codex — writes ~/.codex/mcp.json with the same server entry and same env (Source: CHANGELOG.md:150-165).
• Vault scaffold — creates ./vkm-vault/ (or a user-chosen path) containing RULES/TEMPLATE.md, .obsidian/ config, and the managed memory-rules block (Source: CHANGELOG.md:120-140).
• Hooks — under Claude Code, installs guard-native-memory-write.mjs, a PreToolUse hook that DENY-locks Write/Edit/MultiEdit/NotebookEdit calls targeting the native-memory path, so the ADR-0029 doctrine holds for any model, old or new (Source: CHANGELOG.md:180-205).

The obsidian-memory-hybrid server definition is shipped as static JSON so every host sees the exact same capabilities:

flowchart LR
  A[vkm installer] --> B[~/.claude/mcp.json]
  A --> C[~/.cursor/mcp.json]
  A --> D[~/.codex/mcp.json]
  A --> E[Vault scaffold]
  A --> F[PreToolUse hook]
  B & C & D --> S["obsidian-memory-hybrid<br/>SQLite-vec + pin_failures + usage_boost"]
  E --> R["RULES/TEMPLATE.md"]

(Sources: packages/create-vkm-kit/src/installers/mcp.js:20-95, config/mcp/obsidian-memory-hybrid.json:5-40, CHANGELOG.md:150-205)

Verifying the Install

A correct install leaves four observable traces:

1. A vkm-vault/ directory containing RULES/TEMPLATE.md and a populated memory-rules block (Source: CHANGELOG.md:120-140).
2. The obsidian-memory-hybrid server listed in the MCP config your host reads, with both retrieval-lever env vars set on every surface (Source: CHANGELOG.md:150-165).
3. A PreToolUse hook wired into Claude Code that DENY-locks writes into the native-memory path (Source: CHANGELOG.md:180-205).
4. The token-saver permissions.deny rules from older versions absent — v4.3.0 retires them and the installer sweeps them away on upgrade, since hard-blocks such as Read(**/*.lock) blocked legitimate reads (e.g. Flutter's pubspec.lock) with no manual override path (Source: CHANGELOG.md:60-80).

Re-running vkm is safe at any time: the installer is idempotent and detects already-provisioned surfaces rather than duplicating entries.

The Vault Memory subsystem is the persistence spine of vkm-kit: an Obsidian-style Markdown vault that lives alongside a project, exposed to coding agents (Claude Code, Cursor, Codex) through the obsidian-memory-hybrid MCP server. Its job is to give every agent session the same long-lived, project-aware memory — domain contracts, deliberate traps, prior decisions, and user mandates that are invisible from the repo itself — without re-paying retrieval cost on every turn. Source: ARCHITECTURE.md

Storage Layer: Vault FS, Git, and Concurrency

The vault is a plain directory of Markdown notes, addressed and mutated through three cooperative modules:

• vault-fs.mjs — the read/write/edit surface that agents call as MCP tools (vault_read_file, vault_write_file, vault_edit_file, plus vault_list, vault_search). It treats the vault as ordinary files so notes remain git-portable and human-editable.
• vault-git.mjs — keeps the vault under version control so the memory itself has history, blame, and the ability to revert a corrupted note.
• vault-lint.mjs — a guardrail pass that enforces the note contract (frontmatter, sections, link hygiene) before writes are accepted, preventing drift across sessions.

Writes are protected by optimistic concurrency introduced in ADR-0037: vault_read_file returns a content etag (plus mtime) outside the untrusted envelope, and vault_write_file / vault_edit_file accept an opt-in ifMatch parameter that fails the write with a retryable precondition failed error when the note has changed since the read. This closes the lost-update window when multiple agents or a human edits the same note concurrently. Source: packages/obsidian-memory-mcp/src/vault-fs.mjs, packages/obsidian-memory-mcp/src/vault-git.mjs, packages/obsidian-memory-mcp/src/vault-lint.mjs

Retrieval Layer: Hybrid MCP and Context Assembly

The obsidian-memory-hybrid server (hybrid-mcp.mjs) is the single entry point agents use. Rather than a single ranking algorithm, it composes a *hybrid* pipeline that the rest of the system can tune without code changes:

• Lexical / structural recall over the note corpus.
• Semantic recall via the optional sqlite-vec backend.
• Ranking-only levers added in ADR-0038: OBSIDIAN_MEMORY_PIN_FAILURES=1 keeps previously surfaced failures sticky in the top-K, and OBSIDIAN_MEMORY_USAGE_BOOST=1 rewards notes that have demonstrably helped past sessions. Both are wired into the MCP env by the installer across all three agent surfaces (mcp.json, claude mcp add, codex mcp add), on the same "ranking-only levers over telemetry" rationale as sqlite-vec itself.

context-assemble.mjs is responsible for taking the ranked candidate set and shaping it into the bounded prompt block actually injected into the agent — budget-aware truncation, de-duplication, ordering by pin_failures / usage signals, and an opt-in reflect: true flag that lets the agent request a self-critique pass over its own memory rules. Recall telemetry surfaces hits, misses, and promoted notes back to the vault so the boost signals stay grounded. Source: packages/obsidian-memory-mcp/src/hybrid-mcp.mjs, packages/obsidian-memory-mcp/src/context-assemble.mjs, packages/create-vkm-kit/src/install/mcp-config.mjs

Governance: Rules Block, Drift Gate, and Enforcement Hooks

Memory is only useful if it is *kept* useful. Three mechanisms police that:

1. Managed memory-rules block — every wired agent pays for the same concise rules block each session (ADR-0036 trimmed it ES 9,746 → 7,979 chars / EN 9,484 → 7,743 chars, ~440 tokens saved per session, zero rules dropped, two rescued from silent drift).
2. RULES contract (ADR-0039) — the vault scaffold creates RULES/TEMPLATE.md (es/en) so every project rule carries an explicit *date · source · reason* triple, keeping rules auditable rather than folklore.
3. Deterministic enforcement hooks (ADR-0030) — guard-native-memory-write.mjs is a PreToolUse hook that DENIES Write / Edit / MultiEdit / NotebookEdit calls targeting the vault when the agent tries to use its native memory primitives instead of the MCP tools. This makes the "memory goes through the vault, not the chat client" doctrine hold for any model, not just ones that reliably read prose rules.

flowchart LR
  Agent[Agent session] -->|tools| Hybrid[hybrid-mcp.mjs]
  Hybrid --> Recall[Lexical + sqlite-vec + ranking levers]
  Recall --> Assemble[context-assemble.mjs]
  Assemble -->|budgeted block| Agent
  Agent -->|write/edit| VFS[vault-fs.mjs]
  VFS -->|ifMatch etag| VFS
  VFS --> Lint[vault-lint.mjs]
  VFS --> Git[vault-git.mjs]
  Guard[guard-native-memory-write.mjs] -. DENIES native writes .-> Agent

The installer (packages/create-vkm-kit) is what binds this together for end users: it scaffolds the vault, drops the rules template, wires the MCP env (including the v3.14 retrieval levers by default), and registers the enforcement hook — so a single create-vkm-kit run leaves a project with a working, governed, hybrid-retrieval memory layer. Source: packages/obsidian-memory-mcp/README.md, packages/obsidian-memory-mcp/src/vault-fs.mjs, packages/obsidian-memory-mcp/src/context-assemble.mjs

vkm-kit ships a coordinated layer of Skills, agents, and output styles that together define *how* the assistant is allowed to behave in a Claude Code session. The discipline doctrine is the contract; the token economy is the cost model that makes the contract affordable to keep paying every session.

Skills Layer: Discipline as an Installable Capability

The templates/skills/ directory holds the four canonical skill manifests that the installer copies into a target project. Each SKILL.md declares when the skill activates and what behavior it binds.

• vkm-discipline — the root doctrine. Establishes the rules every other skill and agent must obey: trust the user, never invent API shapes, surface uncertainty, and never bypass the vault as the system of record. Source: packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md
• vkm-spec — the spec-building skill invoked when the user asks for a plan, RFC, or ADR. It channels the discipline doctrine into a dated, sourced, reasoned document template so every artifact carries its provenance. Source: packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md
• vkm-design — design thinking companion; pairs with vkm-spec to keep diagrams and decision tables inside the same evidence envelope as the prose they explain. Source: packages/create-vkm-kit/templates/skills/vkm-design/SKILL.md
• vkm-research — research methodology skill that constrains how an agent may browse, search, and cite; refuses to fabricate citations and prefers vault-resident knowledge first. Source: packages/create-vkm-kit/templates/skills/vkm-research/SKILL.md

Skills are activated by description-matching against the user's prompt; they are not a hidden system prompt. The discipline skill is meant to be co-resident with the others so any spec, design, or research artifact inherits the contract for free.

Discipline Doctrine: The Rules the Suite Will Not Negotiate

The doctrine is encoded as a small, dated, sourced block of rules that is paid once per session in every project wired to vkm-kit. ADR-0036 ("rules-block diet + drift gate") trimmed the block to roughly 8k chars per language without dropping any rule from the Trust section, saving ~440 tokens per session while keeping two rules that had silently diverged. Source: packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md

Enforcement is dual-layered. The prose rules cover agents that faithfully read their context. For models that don't, v3.11.0 added deterministic hooks (ADR-0030) — a PreToolUse guard (guard-native-memory-write.mjs) that DENIES Write/Edit/MultiEdit/NotebookEdit calls targeting disallowed paths, making the doctrine hold for any model, old or new. Source: packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md

The vkm-implementer agent is the canonical execution surface for the doctrine: it must read CLAUDE.md, consult the vault, and never duplicate memory that the vault already owns. Source: packages/create-vkm-kit/templates/agents/vkm-implementer.md

Token Economy: Paying Less for the Same Discipline

Three levers keep the discipline affordable:

1. Rules-block diet (ADR-0036). The managed memory-rules block was trimmed from 9,746 → 7,979 chars (ES) and 9,484 → 7,743 (EN), a ~440 token per session saving with zero rules dropped from the Trust section. Source: packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md
2. Terse output style (vkm-terse). A registered Claude Code output style that trims pleasantries, restating-the-question framing, and meta-commentary, so the same discipline contract costs less per turn. Source: packages/create-vkm-kit/templates/output-styles/vkm-terse.md
3. Retired token-saver denials (ADR-0043 amendment). The installer now actively sweeps permissions.deny rules that auto-block small read files (e.g. pubspec.lock) because a prompt-less hard block turned out to be indistinguishable from a manual one — a cost the user paid without consent. Source: packages/create-vkm-kit/templates/output-styles/vkm-terse.md

The economy is ranking-only, not telemetry-based: ADR-0038 retrieval levers (OBSIDIAN_MEMORY_PIN_FAILURES=1, OBSIDIAN_MEMORY_USAGE_BOOST=1) sharpen recall without spending extra context on diagnostic output. Source: packages/create-vkm-kit/templates/agents/vkm-implementer.md

How the Layers Compose

A single user request flows through the layers in order: the discipline skill sets the contract, the matched skill (vkm-spec, vkm-design, or vkm-research) shapes the artifact, the implementer agent executes, and the vkm-terse output style compresses the answer. The rules-block is paid once at session start; everything downstream inherits it.

The doctrine does not scale by being more verbose; it scales by being *enforced* (ADR-0030 hooks) and *compressed* (ADR-0036 diet + terse style), so a project can keep the full rule set without paying for it twice.

Scope and Purpose

The Web Tools, Sync Daemon, Doctor & Operations layer is the runtime substrate that turns vkm-kit from a memory vault into a usable efficiency suite for Claude Code. It exposes three operational concerns:

1. Web tools — obscura_search and obscura_research, MCP tools that give the model safe, structured access to the public web without leaking untrusted bytes into the prompt envelope (Source: packages/obscura-web/src/obscura-mcp.mjs:1-120).
2. Sync daemon & doctor — a background service that reconciles the on-disk vault with the wired agents and surfaces actionable diagnostics through the local usage doctor (Source: packages/doctor/src/doctor.mjs:1-80).
3. Lifecycle management — on-demand provisioning of a local SearXNG instance via ensureSearxng(), which starts when a search is needed and stops after an idle window (Source: packages/obscura-web/src/ensure-searxng.mjs:1-40).

Together they keep the agent productive (web access), consistent (sync), and observable (doctor) without forcing the user to manage a long-running server.

Web Tools

`obscura_search` and the SearXNG backend

obscura_search is the entry point for one-shot web queries. Per the v4.2.0 release (ADR-0052), the tool gained a local SearXNG structured backend so free SERP scraping no longer has to choose between speed, volume, and relevance. The backend is started on demand by ensureSearxng() only when the tool is invoked, aggregated across engines, returns structured JSON, and bypasses anti-bot walls (Source: packages/obscura-web/src/ensure-searxng.mjs:20-60).

The actual fetcher lives in serp.mjs, which normalizes engine-specific result blobs into a single { title, url, snippet } shape consumable by the model. Because the returned text comes from the open web, every payload is funneled through untrusted-web.mjs before it is exposed to the MCP envelope — opaque sandboxing, escaping, and provenance tagging happen here (Source: packages/obscura-web/src/untrusted-web.mjs:1-90).

`obscura_research` and deep research

obscura_research is the multi-round cousin of obscura_search. The v4.4.0 release (ADR-0060) added three new tools and a background deep-research mode: obscura_research_start(objective, topics, topic, …) launches a job that runs INSIDE the MCP server process for up to 30 minutes, and each round reuses the lower-level deepResearch primitive (Source: packages/obscura-web/src/obscura-mcp.mjs:140-220).

The job is implemented as an asynchronous loop in research.mjs, which the documentation summarizes as "the way a human researcher iterates on a hard question": each round issues a fresh query, inspects what is missing, and queues follow-up searches — the same pattern repeated across engines. On completion, a per-run report is persisted alongside the vault so a later session can recall what was learned (Source: packages/obscura-web/src/research.mjs:40-160).

Sync Daemon and Lifecycle

The sync daemon is what keeps the vault and the wired agents coherent. When the installer wires an MCP client, it sets MCP env variables (see ADR-0038) that are read at server boot; the daemon itself is a small supervisor inside obscura-mcp.mjs that:

• monitors writes from any wired surface (Claude Code, Cursor, Codex),
• applies the optimistic-concurrency ifMatch precondition introduced in v3.13.0 (ADR-0037),
• and emits a heartbeat that the doctor can read (Source: packages/obscura-mcp/src/obscura-mcp.mjs:260-340).

Below is the high-level data flow that ties web access, sync, and doctor together.

flowchart LR
  A[Claude Code / Cursor / Codex] -->|tool call| B[obscura-mcp.mjs]
  B --> C[ensure-searxng.mjs]
  C -->|on demand| D[(local SearXNG)]
  B --> E[serp.mjs / deep-research.mjs]
  E --> F[untrusted-web.mjs]
  F -->|clean payload| A
  B --> G[(Vault on disk)]
  B --> H[doctor.mjs]
  H -->|diagnostics report| A

Doctor & Operations

The local usage doctor lives in packages/doctor/src/doctor.mjs. It is what the v4.0.0 release called "one plug-and-play efficiency suite" — the doctor is the lens through which a user inspects token-saver hits, retrieval-stack behavior, recall telemetry, and the pin_failures / usage_boost levers added in v3.14.0 (ADR-0038) (Source: packages/doctor/src/doctor.mjs:30-110).

Operationally, the doctor is invoked manually via vkm doctor (the binary introduced in v4.0.0 alongside create-vkm-kit) and emits a per-session report covering:

• which rules block was injected and its character count (the v3.12.0 diet + drift gate trimmed EN/ES blocks by ~18% without dropping any rule),
• recall telemetry and reflect: true traces surfaced by the retrieval stack,
• SearXNG start/stop events from ensure-searxng.mjs,
• and any precondition failed rejections from vault_write_file so users notice the lost-update window closing (ADR-0037).

Because the doctor reads only local state, it has no network dependency and runs even when the web tools are disabled.

Cross-Cutting Notes

• Safety boundary. All web payloads traverse untrusted-web.mjs; no HTML string from serp.mjs ever lands directly in the model context (Source: packages/obscura-web/src/untrusted-web.mjs:1-90).
• On-demand provisioning. SearXNG is a paid resource (CPU, memory); ensureSearxng() is designed to start it lazily and shut it down after an idle window, keeping day-to-day usage close to zero overhead (Source: packages/obscura-web/src/ensure-searxng.mjs:20-60).
• Bounded research. obscura_research caps runs at 30 minutes inside the MCP process — long enough to be useful, short enough that a stuck job cannot wedge the agent (Source: packages/obscura-web/src/obscura-mcp.mjs:140-220).
• Compatability. The legacy @vkmikc/create-obsidian-memory package remains a forwarded alias, so callers of either name land on the same doctor + sync + web layer introduced in v4.0.0.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://github.com/Vahlame/create-vkm-kit

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://github.com/Vahlame/create-vkm-kit

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://github.com/Vahlame/create-vkm-kit

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://github.com/Vahlame/create-vkm-kit

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using create-vkm-kit with real data or production workflows.

• v4.4.0 - github / github_release
• v4.3.0 - github / github_release
• v4.2.0 - github / github_release
• v4.0.0 - github / github_release
• v3.15.0 - github / github_release
• v3.14.0 - github / github_release
• v3.13.1 - github / github_release
• v3.13.0 - github / github_release
• v3.12.0 - github / github_release
• v3.11.0 - github / github_release
• Configuration risk requires verification - GitHub / issue