# https://github.com/Vahlame/create-vkm-kit Project Manual

Generated at: 2026-07-21 17:06:23 UTC

## Table of Contents

- [Overview & Installation](#page-1)
- [Vault Memory & Hybrid Retrieval Architecture](#page-2)
- [Skills, Discipline Doctrine & Token Economy](#page-3)
- [Web Tools, Sync Daemon, Doctor & Operations](#page-4)

<a id='page-1'></a>

## Overview & Installation

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/Vahlame/create-vkm-kit/blob/main/README.md)
- [README.en.md](https://github.com/Vahlame/create-vkm-kit/blob/main/README.en.md)
- [CHANGELOG.md](https://github.com/Vahlame/create-vkm-kit/blob/main/CHANGELOG.md)
- [packages/create-vkm-kit/src/index.js](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/index.js)
- [packages/create-vkm-kit/package.json](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/package.json)
- [packages/create-obsidian-memory-shim/src/index.js](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-obsidian-memory-shim/src/index.js)
- [packages/create-vkm-kit/src/installers/mcp.js](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/installers/mcp.js)
- [config/mcp/obsidian-memory-hybrid.json](https://github.com/Vahlame/create-vkm-kit/blob/main/config/mcp/obsidian-memory-hybrid.json)
</details>

# Overview & Installation

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:

```bash
# 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`:

```jsonc
// 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:

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

---

<a id='page-2'></a>

## Vault Memory & Hybrid Retrieval Architecture

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [ARCHITECTURE.md](https://github.com/Vahlame/create-vkm-kit/blob/main/ARCHITECTURE.md)
- [packages/obsidian-memory-mcp/src/hybrid-mcp.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/hybrid-mcp.mjs)
- [packages/obsidian-memory-mcp/src/context-assemble.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/context-assemble.mjs)
- [packages/obsidian-memory-mcp/src/vault-fs.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/vault-fs.mjs)
- [packages/obsidian-memory-mcp/src/vault-git.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/vault-git.mjs)
- [packages/obsidian-memory-mcp/src/vault-lint.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/src/vault-lint.mjs)
- [packages/obsidian-memory-mcp/README.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obsidian-memory-mcp/README.md)
- [packages/create-vkm-kit/src/install/mcp-config.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/src/install/mcp-config.mjs)
</details>

# Vault Memory & Hybrid Retrieval Architecture

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.

```mermaid
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]()

---

<a id='page-3'></a>

## Skills, Discipline Doctrine & Token Economy

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/skills/vkm-discipline/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/skills/vkm-spec/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-design/SKILL.md](https://github.com/Vahlame/create-vkm-kit/templates/skills/vkm-design/SKILL.md)
- [packages/create-vkm-kit/templates/skills/vkm-research/SKILL.md](https://github.com/Vahlame/create-vkm-kit/templates/skills/vkm-research/SKILL.md)
- [packages/create-vkm-kit/templates/agents/vkm-implementer.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/agents/vkm-implementer.md)
- [packages/create-vkm-kit/templates/output-styles/vkm-terse.md](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/create-vkm-kit/templates/output-styles/vkm-terse.md)
</details>

# Skills, Discipline Doctrine & Token Economy

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.

| Layer | File | Role | Token cost |
|---|---|---|---|
| Doctrine | `vkm-discipline/SKILL.md` | Sets the trust + behavior contract | ~440 tok/session (post-ADR-0036) |
| Method skills | `vkm-spec`, `vkm-design`, `vkm-research` | Shape the artifact under the contract | On-demand activation only |
| Agent | `vkm-implementer.md` | Executes against the contract | Per-turn context |
| Output style | `vkm-terse.md` | Trims the prose the user actually reads | Per-turn, negative cost |

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.

---

<a id='page-4'></a>

## Web Tools, Sync Daemon, Doctor & Operations

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [packages/obscura-web/src/obscura-mcp.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/obscura-mcp.mjs)
- [packages/obscura-web/src/deep-research.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/deep-research.mjs)
- [packages/obscura-web/src/research.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/research.mjs)
- [packages/obscura-web/src/ensure-searxng.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/ensure-searxng.mjs)
- [packages/obscura-web/src/serp.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/serp.mjs)
- [packages/obscura-web/src/untrusted-web.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/obscura-web/src/untrusted-web.mjs)
- [packages/doctor/src/doctor.mjs](https://github.com/Vahlame/create-vkm-kit/blob/main/packages/doctor/src/doctor.mjs)
</details>

# Web Tools, Sync Daemon, Doctor & Operations

## 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.

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

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: Vahlame/create-vkm-kit

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://github.com/Vahlame/create-vkm-kit

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/Vahlame/create-vkm-kit

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/Vahlame/create-vkm-kit

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/Vahlame/create-vkm-kit

<!-- canonical_name: Vahlame/create-vkm-kit; human_manual_source: deepwiki_human_wiki -->