KnowledgeRail

KnowledgeRail is a local-first MCP server that turns project documentation and source code into durable, evidence-backed context for AI agents.

It is designed for agents that need to understand, change, review, or document a codebase without loading the whole repository into the model context. Retrieval is bounded, provenance is preserved, missing evidence is reported explicitly, and difficult queries widen progressively instead of silently losing relevant information.

Current status: stable release 2.9.1. The server uses MCP SDK 2.x and protocol 2026-07-28. It supports explicitly bound or safely inferred local stdio, a self-hosted loopback HTTP gateway, and a local desktop-chat adapter. KnowledgeRail operates no hosted service and does not upload project data. See SELF_HOSTING.md.

What it provides

• Eight domain-oriented tools with validated actions and machine-readable next steps.

• Task-aware hybrid retrieval with lexical, graph, passage, and optional semantic evidence.

• Progressive widening with explicit coverage signals and GAP/unknown reporting.

• Complete source ingestion through bounded segments, a coverage ledger, and durable Evidence IR.

• A deterministic multi-language code index with symbol, reference, route, test, configuration, and database lookup.

• Incremental graph, retrieval, and semantic indexes stored beside the project wiki.

• Contract-driven Markdown deliverables with terminal review, content hashes, and optional caller-authored diagrams.

• Conservative migration of existing v1/v2/v3 wikis and pre-rebrand .llm-wiki metadata.

• Deterministic project binding through explicit Cursor workspace configuration, cwd-aware IDE processes, and terminal agents.

• A local HTTP gateway that keeps concurrent clients and projects isolated per request.

• A desktop-chat workspace catalog with opaque, expiring per-chat bindings.

KnowledgeRail does not call an LLM itself. The connected MCP client chooses and calls the tools. OCR and HTTP embeddings are optional external providers configured by the user; static embeddings can also run locally from explicitly installed model assets.

Deterministic code-evidence languages

Code evidence is extracted locally without tree-sitter, native binaries, downloaded grammars, or runtime parser dependencies. Each file is owned by exactly one versioned adapter, so upgrading one language reparses only that language's files. Unsupported or deliberately skipped constructs remain visible through recorded raw-fallback demand rather than being assigned an unreliable anchor.

In the table below, imports means extracted specifiers. Incoming import relations additionally resolve project-local declarations or paths: JS/TS, Python, Java/Kotlin, C#, PHP, Go and Rust, C/C++ headers, and supported LWC virtual imports. Ruby retains stem matching. Ambiguities and unsupported conventions remain visible limitations; see module reference coverage.

The extractors are intentionally conservative. LWC HTML templates, Java anonymous classes, dynamic Apex query object names, Rust macro expansion, PHP eval()/string callables and Blade/Twig templates, K&R C definitions, macro-generated C/C++ declarations, complex C++ operator/template metaprogramming, Python lambdas/dynamic definitions/metaclass-generated members, indirect or qualified decorator-generated routes, calls inside f-string interpolations, and notebooks are not guessed. Kotlin computed Ktor paths and string-named Kotest cases are not emitted independently. Salesforce metadata is limited to the explicit SFDX suffix roster; malformed XML falls back to a file module. Ruby metaprogramming, inferred ActiveRecord tables, individual RSpec it blocks, operator methods, and ambiguous plain command-form heredocs or regex literals remain best-effort or out of scope. Headers use the C++ superset adapter. Python uses a separate indentation engine with CPython-compatible tab stops; Ruby uses its own keyword-block engine. Qualified knowledge_code action="symbol" lookups treat ., #, ::, PHP namespace backslashes, and -> as equivalent separators, while returned names retain the language-native form. The pinned golden corpus contains 52 source files, 1,429 source lines, and 199 hand-labeled symbols across twelve language adapters; the mixed-repository benchmark adds two LWC files for 54 files and 1,446 lines overall. Its perfect in-corpus score is a deterministic regression guarantee, not a claim of universal parser accuracy. Code anchors are line-based: trailing-whitespace edits remain fresh, while formatting that inserts or removes lines is deliberately reported as drift because it shifts the cited range. knowledge_admin action="status" reports the extension histogram supplied with recorded grep fallbacks, allowing later language priorities to follow real repository demand.

Interpreting module references

Use knowledge_code action="references" with the indexed module's symbol_id to retrieve import edges. The adapter's imports list records source specifiers; a returned import relation is the resolver's connection to a module in this project. The current release includes declared Python backend layouts, JS/TS project ownership and local package exports, Rust module attributes and workspace globs, and literal build-tool boundaries. Common manifest readers and bounded lookup structures are reused across adapters; build tools and installed dependencies are never executed or loaded.

LWC links Apex, schema, labels, static resources, message channels and local bundles within declared Salesforce project boundaries. Platform modules are counted separately. Literal trigger and Visualforce/Aura references reach indexed objects and Apex classes; inactive/deleted Apex remains searchable with its deployment status. unresolvedImports distinguishes verified unindexed paths and unsupported syntax, while declared external dependencies have a separate inventory count. These counts are separate from the observed request/fallback rate. See the supported declarations and limits.

Known manifests refresh on reference queries. New nested manifests, workspace members and Apex status companions require an explicit code update or rebuild. Projects without discovered Go manifests retain the diagnosed suffix fallback. Custom adapters without a resolver retain legacy stem matching. An empty reference list does not prove that a module is unused. Inspect the extracted specifier and use a qualified symbol lookup or read the source when an import edge is missing; treat heuristic edges as candidates to verify. See the import resolution contract for supported cases and limitations.

When a knowledge claim explains code, record its indexed code://repo/...#symbol-... resource as the Evidence IR target.codeResourceUri. Synthesis then places a direct code link and line range on the wiki page if anchor capture succeeds; claims without code evidence do not receive a fabricated link. The stored hash and parser version support drift checks. See the workflow and verified examples.

Related MCP server: memory-mcp

Requirements

• Node.js 22.12.0 or newer

• npm

• macOS, Windows, or Linux

KnowledgeRail ships no browser or document renderer. Mermaid source remains ordinary Markdown and is rendered only by viewers that support it.

Quick start with npx

Run this from any directory inside the project in a terminal or another client that launches stdio servers with the project as its working directory:

npx -y knowledge-rail@2.9.1

No project path is needed when the MCP client guarantees a project-scoped process cwd or supplies one unambiguous legacy MCP Root. Cursor project setup is explicit because its global MCP process may be shared across windows.

The reviewed package is published to npm. Pin an exact version in persistent configurations; reserve @latest for one-time trials.

Install and run from source

From source

git clone https://github.com/Deviank88/KnowledgeRail.git
cd KnowledgeRail
npm ci
npm run build

Start it from any directory inside the project whose knowledge you want to manage:

cd /path/to/your-project
node /absolute/path/to/KnowledgeRail/dist/index.js

Cursor configuration

Run this once from the project root or any nested directory:

npx -y knowledge-rail@2.9.1 setup cursor

The command discovers the project upward and safely creates or merges .cursor/mcp.json. It preserves other MCP servers and pins an explicit ${workspaceFolder} binding. Re-running it is idempotent.

The equivalent manual project configuration is:

{
  "mcpServers": {
    "knowledge-rail": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "knowledge-rail@2.9.1",
        "--root",
        "${workspaceFolder}"
      ]
    }
  }
}

Keep this file at <project>/.cursor/mcp.json, not in the global ~/.cursor/mcp.json. Recent Cursor releases can reuse a global stdio MCP process whose cwd is the user home or an empty window, so global cwd-based project inference is not a supported bound-workspace configuration. Cursor documents type: "stdio", project configuration, and ${workspaceFolder} interpolation in its MCP guide.

For a source checkout, use the compiled entry point while retaining the explicit workspace root:

{
  "mcpServers": {
    "knowledge-rail": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/absolute/path/to/KnowledgeRail/dist/index.js",
        "--root",
        "${workspaceFolder}"
      ]
    }
  }
}

For a Cursor multi-root workspace, install one project configuration in every root that should expose KnowledgeRail. The server never selects the first open root silently.

Claude Code configuration

From the project, add KnowledgeRail at project scope:

claude mcp add --transport stdio --scope project knowledge-rail -- npx -y knowledge-rail@2.9.1

Claude Code writes the shared project entry to .mcp.json and launches the local server in project context. Use claude mcp list to verify the connection. The command shape and project scope follow the official Claude Code MCP guide.

Other IDE and terminal clients

For a client that explicitly guarantees one stdio process per project with the project as cwd, the minimal server configuration remains:

{
  "mcpServers": {
    "knowledge-rail": {
      "command": "npx",
      "args": ["-y", "knowledge-rail@2.9.1"]
    }
  }
}

If the client does not guarantee that cwd contract, pass an absolute --root in its project-scoped configuration. Do not place a repository-specific absolute root in a global configuration.

The workspace precedence is explicit --root; one unambiguous legacy MCP Root; WIKI_ROOT for compatibility; the nearest existing KnowledgeRail marker; the nearest project/VCS marker; finally a safe non-empty cwd. Filesystem roots, the user home, package caches, and known Claude/Cursor application directories fail closed.

Inspect the exact choice without starting MCP:

npx -y knowledge-rail@2.9.1 doctor
npx -y knowledge-rail@2.9.1 doctor --root /absolute/project/path

The command prints the canonical root and its resolution source, or exits non-zero with corrective guidance.

Claude Desktop and other context-free desktop chats

A desktop chat does not open a filesystem folder, so it cannot safely infer a project from its process cwd. The preferred installation is the self-contained MCP Bundle (.mcpb): it avoids npm/network resolution on every Claude launch and follows Claude Desktop's current local-extension path.

For a source/release checkout, build the deterministic bundle:

npm run mcpb:build

Then install artifacts/knowledge-rail-2.9.1.mcpb from Claude Desktop → Settings → Extensions → Advanced settings → Install Extension. The bundle contains the compiled server and its production dependencies, starts the desktop adapter directly, and does not require a project path. See Anthropic's local MCP server guide and the MCP Bundle specification.

The manual local-development configuration remains available for hosts that have not adopted MCP Bundles:

{
  "mcpServers": {
    "knowledge-rail": {
      "command": "npx",
      "args": ["-y", "knowledge-rail@2.9.1", "desktop"]
    }
  }
}

For a source checkout, use node /absolute/path/to/KnowledgeRail/dist/index.js desktop. The adapter discovers or starts the protected loopback gateway automatically and exposes knowledge_workspace in addition to the eight domain tools.

In a new chat, ask KnowledgeRail to list workspaces, choose one entry, and confirm read or write access. The returned opaque binding belongs to that conversation and must accompany its later domain calls. For compatibility with desktop hosts that expose only textual tool results, knowledge_workspace returns the same binding in both its declared structured output and a workspace_binding: ... text line. Two chats can select different customers/projects concurrently. Start a new chat when changing customer workspace: filesystem access is isolated, but information already present in conversation history cannot be removed by the server.

Projects opened successfully by an IDE/terminal are added to the local catalog automatically without changing their clean eight-tool workflow. Operators can also manage catalog metadata locally:

npx -y knowledge-rail@2.9.1 workspace list
npx -y knowledge-rail@2.9.1 workspace register
npx -y knowledge-rail@2.9.1 workspace register /absolute/project/path
npx -y knowledge-rail@2.9.1 workspace unregister ws_example

Registration never copies, uploads, scans the disk, or deletes project files. workspace register without a path discovers only upward from cwd.

Local self-hosted HTTP gateway

Start one gateway for many concurrent local clients and workspaces:

npx -y knowledge-rail@2.9.1 --transport http

The default endpoint is http://127.0.0.1:3333/mcp; liveness only is available at /healthz. MCP requests require the random credential stored in the OS-protected per-user KnowledgeRail state directory. The desktop adapter reads it automatically, so it never belongs in project configuration or a repository.

The gateway does not have a current root. Every filesystem-capable request must resolve a valid opaque binding before the first path access. Bindings are scoped, expiring, revocable, and invalidated on gateway restart. Resource links are workspace-qualified and revalidated when read.

The shipped gateway deliberately rejects non-loopback binding. It is local self-hosting, not public OAuth or hostile-user multi-tenancy. claude.ai and Claude remote custom connectors cannot use a localhost endpoint because those connections originate from the provider cloud; Claude Desktop local MCP uses the desktop adapter above.

Platform state locations are %LOCALAPPDATA%\KnowledgeRail on Windows, ~/Library/Application Support/KnowledgeRail on macOS, and ${XDG_STATE_HOME:-~/.local/state}/knowledge-rail on Linux. Set KNOWLEDGE_RAIL_STATE_DIR only for controlled testing or an intentional custom local installation. Docker/devcontainers and WSL have separate filesystems and therefore separate catalogs unless their state and project mounts are explicitly shared.

Operating-system notes

• Windows: if an MCP host does not resolve npm command shims, use "command": "npx.cmd"; escape backslashes in JSON paths (C:\\Tools\\KnowledgeRail\\dist\\index.js). PowerShell operator commands use the same CLI arguments shown above. Drive-letter case and junction/real paths are canonicalized before binding.

• macOS: the state directory is inside Library/Application Support, not the opened repository.

• Linux: XDG_STATE_HOME is honored. No browser sandbox configuration is required.

• WSL and containers: run the MCP process in the same filesystem environment as the project. A Windows Claude Desktop process and a WSL-only localhost/state directory are distinct unless an explicit bridge is configured.

Agent workflow

KnowledgeRail exposes eight stable tools. Agents choose a domain directly and use its mode or action; no menu, profile, session scope, or legacy alias is required.

Every successful operation returns a machine-readable state and either one nextAction or null. nextAction identifies the next tool, action, required arguments, and safe suggested arguments. Optional guidance and resultText complete the shared output envelope. Clients that only render text also receive concise Next: and Guidance: lines when applicable.

How it works

KnowledgeRail separates context retrieval, durable memory, source ingestion, code evidence, and document production so an agent can enter at the operation it needs without learning an internal menu or carrying session state:

task objective
    ↓
knowledge_context ──→ ranked evidence links + coverage gaps
    ↓                              ↓
resources/read              bounded widening, if needed
    ↓
agent reasoning and project work
    ├──→ knowledge_page / knowledge_code
    ├──→ knowledge_ingest ──→ Evidence IR ──→ canonical wiki
    └──→ knowledge_document_context ──→ knowledge_document

For a normal task, the agent calls knowledge_context mode="task" with a concrete objective. KnowledgeRail searches the canonical wiki and its derived lexical, graph, passage, code, and optional semantic indexes, ranks the available evidence, and returns a compact context envelope. Large page bodies are exposed as knowledge-rail:// links instead of being inserted wholesale into the response; the client reads only the selected passages. Coverage is assessed over both the full retrieved candidate set and the smaller display set. The full pool distinguishes truly missing evidence from evidence that is merely budget_limited; progressive widening stops only when the evidence returned to the model is sufficient. If the token budget alone excluded relevant evidence, the returned nextAction proposes one bounded widening step. Missing, stale, contradictory, or unresolved evidence remains an explicit gap and is never filled by guessing.

Decision pages are ordinary canonical wiki knowledge and already participate in that retrieval. Each page stays bounded to one coherent flow, component, or project context. Candidate prior choices are exposed in the structured decisions and changeImpact.decisions fields, but the agent inspects their metadata and materializes only a resource link that actually matches the task—normally the selected passage, or that single bounded page when no reliable passage exists. Detailed retrieval safeguards are included in the task response only when decision candidates exist, avoiding a large fixed instruction cost for unrelated sessions. The agent never loads every decision page, and the absence of a matching decision is normal rather than a coverage gap. When the human-model discussion reaches a clearly accepted, durable project choice, the agent closes the loop at task completion: it rereads and reuses the decision page for the same context (or creates a separate page for a different one), updates the current choice and concise rationale, appends a dated history note describing what changed and why, and writes one DECISION log entry. Proposals, unresolved options, incidental implementation details, raw conversation, hidden chain-of-thought, and secrets are never decision memory. The page remains valid if the independent log append must be retried. No decision means no write; an analysis-only or otherwise unauthorized session reports the proposed update instead of mutating the wiki.

Durable knowledge lives as Markdown under wiki/. Page-tool paths are relative to that root (concepts/RAG.md); a redundant leading wiki/ is accepted and removed, while a wiki directory deeper in the path is blocked so page writes cannot create wiki/wiki/.... Page directories remain open-ended and are created lazily, so projects can add domain-specific groupings without changing the catalog. Legacy nested pages are reported by lint; knowledge_admin action="lint" force=true dry_run=true previews a collision-safe repair and dry_run=false moves them to canonical paths while updating relative links. Direct page operations preserve caller-owned content byte-for-byte. Larger source sets use knowledge_ingest: normalized sources are processed in bounded segments, claims are recorded in durable Evidence IR, coverage is reconciled, and finalization is blocked until every segment is represented or explicitly classified. Derived retrieval and graph indexes are refreshed from this canonical state rather than replacing it.

Normalized sources originating in docs/transcripts/ activate the required stakeholder-memory contract; docs/client/ and docs/reports/ activate lightweight discovery when explicit stakeholder evidence is present. Each unambiguous participant, role, group, organization, or affected party is recorded under wiki/stakeholders/. Later sources update the current role, organization, email domain, and affiliation while the Evidence IR block retains prior observations and provenance. The local user domain comes first from KNOWLEDGE_RAIL_USER_EMAIL, then project-root git config user.email, otherwise it is unknown. Only domains are persisted: equal domains classify as internal and different domains as client; without a comparable domain, an explicit source declaration of client or internal is retained, otherwise the value is unknown; partner always requires explicit evidence. Complete participant addresses are redacted from durable claims; unsupported attributes are not inferred and ambiguous identities are not merged. Identity resolution is cached for the server lifetime, so changing the environment variable or project Git email requires a KnowledgeRail server restart.

Verified warm start and phrase-aware retrieval

KnowledgeRail resumes from project-local lexical and graph checkpoints, but never treats them as authority. Before a checkpoint can serve evidence, canonical Markdown is reconciled and the graph checkpoint must match the verified lexical corpus revision and its own builder version. A missing, stale, truncated, corrupt, oversized, symlinked, or incompatible artifact—or a symlinked/non-directory .knowledge-rail boundary—is discarded as one candidate generation; KnowledgeRail rebuilds from canonical pages and exposes a stable fallback reason through knowledge_admin action="status". Read-only requests may consume valid derived files but do not rewrite them. Authorized mutations append revision-bound lexical and graph journals under one cross-process lock; either journal is compacted into its snapshot after 100 deltas or 4 MiB, preventing unbounded growth.

The default integrity policy is metadata: path, size, modification/change timestamps, and portable file identity select which pages must be reread and hashed. content fingerprints every canonical page before accepting the generation and is intended for higher-assurance environments where the extra startup I/O is appropriate. Set KNOWLEDGE_RAIL_INTEGRITY_MODE=content, or use integrity_mode="content" with the admin status/checkpoint actions. To explicitly verify and persist a clean generation, run knowledge_admin action="checkpoint"; add force=true for an oracle rebuild from canonical Markdown.

Ordered word bigrams positively rerank only a bounded BM25 pool and select the best canonical passage; a missing phrase never filters a unigram candidate. Compound identifiers such as REQ-123, Asset__c, Retry-After, and /v2/invoices remain single ordered tokens. Pages matching every strong identifier are protected, and queries containing three or more strong identifier tokens retain exact lexical passage selection instead of applying a phrase boost. The channel is enabled by default after its held-out quality gate; KNOWLEDGE_RAIL_PHRASE_RERANK=off provides an internal soak/diagnostic rollback. Trigrams and a persistent n-gram table are intentionally absent because the controlled A/B test found no additional quality gain and the bounded scorer meets the latency gate.

Search scores are relative ranking signals within one result set, not probabilities or stable values to compare across queries or releases.

Document production is a separate evidence-backed workflow. knowledge_document_context first creates a plan and a bounded evidence pack for each section. knowledge_document then writes and reviews the Markdown against the selected contract. A passing review is terminal and returns the SHA-256 of the exact inspected content; conversion or branded rendering belongs to the user's own LLM and tooling. This keeps generated documents traceable to project memory without treating the deliverable itself as canonical memory.

All public actions validate their own required arguments before reading or mutating state. The shared state/nextAction envelope makes progress explicit, but a suggested next action never grants permission to perform a consequential write: the connected client retains its normal approval policy. Compatibility with older MCP clients changes only the transport adapter, not these eight tool names or their behavior.

A normal context request starts directly with:

knowledge_context {
  "mode":"task",
  "intent":"understand",
  "objective":"Explain how lease renewal and expiry work",
  "response_detail":"compact",
  "heuristic_token_budget":2000
}

On MCP 2026-07-28, knowledge_context returns selected knowledge-rail:// resource links. The client materializes only the passages it needs with resources/read; clients that do not expose resource reads can use knowledge_page action="read" with the exact URI. The envelope always reports retrieval.coverageMode as lexical, semantic-partial or semantic, plus any progress or graceful-degradation warning. When evidence was omitted only because of the budget, nextAction provides the next bounded widening request. Semantic, stale, or unresolved gaps are returned without a futile widening loop and must remain explicit unknowns.

For source changes, changed_paths also accepts repository-relative indexed code files. Task context can return changeImpact.codeRoots, incoming codeRelations and related codeWikiPages from active anchored claims. Expansion uses the existing code snapshot, with at most three roots and twelve candidates per root, further reduced by the token budget. Context does not rebuild missing or invalid code indexes. Read only relevant code links and verify freshness: lexical calls/references and heuristic imports remain candidates, and an empty result does not prove non-use. See the code evidence guide for scope and limits.

The consolidated catalog is deliberately action-oriented, but validation remains action-specific. For example, knowledge_page action="edit" is rejected without path, old_string, and new_string; ingestion cannot finalize before complete coverage; document review reports blockers and delivery readiness for the exact inspected Markdown.

Caller-owned page, file, and code bodies are never rewritten to modernize historical tool names. If a canonical SCHEMA.md still refers to a retired operation, knowledge_admin action="migrate" can propose the corresponding current operation for explicit review; reads remain byte-preserving.

A normalized-source loop is explicit and machine-guided:

start → next → apply_claims or record_segment → next
      → source_status → finalize

Use evidence_status for claims and recovery debt; it is intentionally separate from per-source source_status. The old overloaded apply and status ingestion actions are rejected.

Why context has a token budget

The budget bounds evidence sent to the model; it does not declare omitted knowledge irrelevant. If coverage is insufficient because of the budget, the guided read workflow widens both max_evidence (up to 20) and the heuristic token allowance from 2,000 to 4,000, 8,000, and at most 12,000. Widening stops as soon as no evidence is budget-omitted; any remaining semantic or freshness gap is exposed rather than guessed.

response_detail="compact" is recommended for normal agent use. full keeps the complete historical TaskContext payload for diagnostics and integrations that need it.

Code-backed claims and drift detection

Evidence IR claims can cite a symbol returned by knowledge_code action="search" or action="symbol". Pass that exact code://repo/...#symbol-... URI as the claim target's code_resource_uri during knowledge_ingest action="apply_claims". If the symbol resolves against the current deterministic code index, KnowledgeRail stores a repository-relative line range, a trailing-whitespace-insensitive SHA-256 range hash, the parser version, and the capture time. A missing or stale symbol produces an explicit anchor warning; KnowledgeRail never fabricates an anchor.

Run a complete read-only check through the MCP tool:

knowledge_admin {
  "action":"drift"
}

For a bounded pre-commit or CI check, pass repository-relative files or directory prefixes:

knowledge_admin {
  "action":"drift",
  "scope":"paths",
  "paths":["src/payments.ts","src/invoices"]
}

The same detector is available without an MCP server for agent hooks and CI. Hook mode reports non-fresh anchors but never blocks the calling tool; it is silent when everything checked is fresh:

npx -y knowledge-rail@2.9.1 drift --no-ledger
npx -y knowledge-rail@2.9.1 drift --no-ledger --path src/payments.ts --path src/invoices

An absolute event path is accepted only when it is confined to the discovered project. For pre-commit or CI, --check exits 2 on any non-fresh anchor or timeout; operational failures exit 1. JSON mode returns the complete shared-core result:

npx -y knowledge-rail@2.9.1 drift --check --no-ledger
npx -y knowledge-rail@2.9.1 drift --format json --no-ledger

Text output is capped at 20 affected anchors. Its stale count is the aggregate of drift_suspected and anchor_unresolvable, not a fourth detector verdict. The default timeout is three seconds: ordinary hook mode reports a timeout on stderr and exits 0, while --check exits 2. Omit --no-ledger only when the disposable freshness ledger should be updated for later context compilation.

The action reads current code and writes only disposable state to wiki/.knowledge-rail/drift/ledger.json; it never edits claim text, canonical pages, or source code. A changed range, missing file, or invalidated line range becomes drift_suspected. An unreadable path, a non-file target, or a symlink that escapes the repository becomes anchor_unresolvable without aborting checks for other anchors. Trailing-whitespace-only edits and a parser-version change with identical range content stay fresh. knowledge_context keeps affected evidence visible for provenance, marks it stale with the corresponding reason, excludes it from clean evidence buckets, and returns an explicit stale_evidence gap even when stale evidence was retrieved but omitted from the display. Re-verification and correction remain normal Evidence IR work—there is intentionally no automatic fix.

Project client hooks integration

Claude Code, Codex and Cursor can receive project-scoped KnowledgeRail rules and read-only drift hooks directly. Preview with npx -y knowledge-rail@2.9.1 setup clients; apply only after review with the same command plus --apply. From an MCP client, ask the model to call knowledge_admin action="client_setup" setup_mode="preview", then explicitly request setup_mode="apply". Applying through the desktop/catalog profile requires a write-scoped workspace binding; preview and status remain read-only. Ordinary initialization never installs hooks implicitly.

The full guide, generated files, client trust steps and security boundaries are in docs/guides/claude-code-hooks.md.

The CLI hook bridge is harness-neutral and emits the native output contract for Claude Code, Codex or Cursor. All generated files and recovery manifests remain inside the selected project. Before a changed configuration is applied, exact existing bytes are copied under .knowledge-rail/backups/client-setup/<run-id>/; a no-op reapply creates no backup. KnowledgeRail retains the newest 20 successfully applied transactions while preserving incomplete, rolled-back, failed and unrecognized recovery evidence.

Project data

knowledge_admin action="init" creates this structure inside the selected project. The roots are intentionally stable: wiki/ is canonical agent memory; docs/ is the document plane for sources, normalized copies, durable evidence state, and deliverables.

project/
├── wiki/
│   ├── index.md
│   ├── log.md
│   ├── SCHEMA.md
│   ├── .knowledge-rail/     # derived indexes, drift ledger, manifests and migration state
│   └── <page-type>/         # created lazily when the first typed page is written
└── docs/
    ├── client/
    ├── transcripts/
    ├── reports/
    ├── changelogs/
    ├── normalized/
    ├── evidence-ir/         # durable Evidence IR and knowledge-recovery state
    ├── deliverables/
    └── assets/

Markdown pages are canonical knowledge. Files below wiki/.knowledge-rail/ are derived or operational state and can be rebuilt where the corresponding workflow supports it. Source documents remain under docs/; normalization never overwrites the original.

knowledge_admin action="migrate" also recognizes the pre-rebrand wiki/.llm-wiki/ namespace. It backs up both namespaces, assesses the legacy manifest, imports valid source-coverage ledgers, and rebuilds manifests and indexes from the current checkout instead of copying stale sizes, mtimes, or hashes. The internal manifest v2 is deterministic across Windows, macOS, and Linux: paths use / and Unicode NFC, Markdown line endings are normalized to LF before size and SHA-256 are computed, entries have a stable order, and the serialized file contains neither timestamps nor filesystem mtimes. Trees that differ only in platform path representation, CRLF/LF line endings, or timestamps therefore produce byte-identical manifest files and the same manifest hash; case-insensitive path collisions are rejected as non-portable. Existing manifest v1 files remain readable and are upgraded when rebuilt or invalidated. The old namespace remains untouched after a successful migration and is retained in the migration backup; ambiguous partial state in both namespaces is blocked for explicit operator review.

These directories may contain private project information. Decide deliberately whether the consuming project should commit them.

Document memory and deliverables

Document generation starts with knowledge_document_context action="plan". Follow its nextAction to compile a separate bounded evidence pack for every section, then use knowledge_document action="write" and action="review". Review is terminal when no blocker remains and returns contentSha256 so the caller can bind the verdict to the exact Markdown bytes inspected. It writes no manifest or sidecar and makes no certification claim.

Built-in presets cover functional specifications and analyses, technical analyses, architecture documents, project briefs, user manuals, onboarding guides, API references, ADRs, runbooks, test plans, incident reports, and release notes. They are not a closed taxonomy: any non-empty document_type is valid, and required_sections lets the user or their LLM define the outline. Each preset supplies a purpose, default language and audience, minimum useful content, and type-specific checks; callers can override the outline, language, and client-facing status.

Diagrams are opt-in. Omitting diagram_mode means that review applies no diagram-mode constraint; clients that want an explicit choice must propagate none, mermaid, or external_asset through planning and review. With mermaid, the user's LLM writes a fenced Mermaid block directly in the Markdown; Obsidian supports Mermaid code blocks, as do other compatible viewers. With external_asset, the caller supplies an SVG/PNG in docs/assets/ and links it from the deliverable as ../assets/name.svg or ../assets/name.png; review validates confinement, signature, size, and active SVG content. Remote images and other local image formats receive portability warnings instead of security blockers. Because KnowledgeRail has no asset-write action, chat-only clients without filesystem access should offer only none and mermaid.

The generated document is an output of agent memory, not its replacement. Confirmed facts belong in wiki/; source artifacts remain in docs/; delivery-ready Markdown belongs in docs/deliverables/.

KnowledgeRail keeps its MCP catalog, prompts, stable identifiers, operational messages, and generated control files in English. This is an internal interoperability choice, not an output-language restriction: human-readable wiki pages and deliverables follow the language of the user's current request, an explicit language override takes precedence, and edits preserve the existing page language unless translation is requested. The policy has no locale allowlist.

Optional OCR and semantic retrieval

Text, Markdown, JSON, YAML, CSV/TSV, XLSX, and PPTX normalization works locally. Images and PDFs require either an Ollama-compatible OCR service or a configured native OCR endpoint.

Common OCR variables:

Semantic retrieval and semantic-aware coverage are optional. Without an embedding provider, deterministic lexical/graph/passage retrieval and delimiter-, stemming-, and artifact-equivalence-aware coverage remain fully available offline. With a provider, query facets and entities are additionally checked against indexed passage embeddings, which improves GAP precision. Page coverage uses the strongest indexed passage, while displayed-passage coverage is scored only against the excerpt actually selected; a relevant page therefore cannot hide a weak displayed excerpt. If the configured provider is unavailable, times out, or returns incompatible vectors, knowledge_context falls back to lexical coverage and reports the warning instead of failing.

The recommended local-first setup is an OpenAI-compatible Ollama endpoint; choose a pinned local model and use its declared vector dimensions:

KNOWLEDGE_RAIL_EMBEDDING_BASE_URL=http://localhost:11434/v1
KNOWLEDGE_RAIL_EMBEDDING_MODEL=<pinned-local-embedding-model>
KNOWLEDGE_RAIL_EMBEDDING_MODEL_VERSION=<pinned-version>
KNOWLEDGE_RAIL_EMBEDDING_DIMENSIONS=<model-dimensions>

A remote OpenAI-compatible endpoint is also supported when explicitly configured:

KNOWLEDGE_RAIL_EMBEDDING_BASE_URL=https://provider.example/v1
KNOWLEDGE_RAIL_EMBEDDING_MODEL=embedding-model
KNOWLEDGE_RAIL_EMBEDDING_DIMENSIONS=1536

Optional embedding variables are KNOWLEDGE_RAIL_EMBEDDING_API_KEY, KNOWLEDGE_RAIL_EMBEDDING_MODEL_VERSION, and KNOWLEDGE_RAIL_EMBEDDING_TIMEOUT_MS.

Persisted vectors use int8 by default. Set KNOWLEDGE_RAIL_SEMANTIC_DTYPE=f32 for Float32 storage. Quantization changes storage and similarity computation, not the configured embedding model: Ollama still computes document and query embeddings. See memory evolution for the measured quality, memory tradeoff and complete startup timings that include Ollama.

KNOWLEDGE_RAIL_EMBEDDING_QUERY_PREFIX optionally prepends a model-specific instruction to queries only. Changing it changes provider identity and triggers a full document re-embedding on the next semantic-index synchronization, even though document inputs are unchanged. See the prefix contract and measured model limits.

The 2.9.0 implementation persists vectors and per-batch progress automatically. A page edit regenerates all embeddings for that page; a model/provider change regenerates the entire corpus. Restarting with unchanged pages reuses the persisted vectors. See memory evolution for lifecycle, optional static models, usage-based ranking, task repository maps, historical claims and measured limits.

In the 2.9.2 development checkout, KNOWLEDGE_RAIL_SEMANTIC_ENGINE=hnsw selects the experimental persisted HNSW index; LSH remains the default. HNSW creates its graph when absent, maintains it incrementally as passages change, and reloads a valid checkpoint plus journal changes after restart. Queries use current vectors through exact search while maintenance runs. The ANN topology and knowledge graph remain separate. See lifecycle and limits.

Optional reranking through Ollama (2.9.2 development checkout)

Configured means active: setting the reranker base URL and model in the MCP server's env automatically enables reranking, like embeddings. Without them, KnowledgeRail works normally. Errors, unsupported models, invalid scores and timeouts preserve retrieval without the reranker. It reorders candidates; it does not certify evidence validity or remove additional evidence and continuations. This feature is in the development checkout, not the published 2.9.1 package.

Use the compact multilingual BGE Reranker v2 M3 Q8: 568M parameters, about 636 MB of weights. Its Ollama conversion needs a one-time metadata correction. From this checkout, with local Ollama 0.34.3 and Python 3 installed:

ollama pull qllama/bge-reranker-v2-m3:q8_0
python3 scripts/prepare-ollama-reranker.py
npm run build

On Windows, py -3 can replace python3. The preparation script verifies the source checksum, adds the missing RANK pooling metadata without changing tensor bytes, verifies the result and imports knowledgerail-bge-reranker-v2-m3:q8_0 into Ollama. It refuses different source weights or an occupied target name with different weights. The source and prepared models each occupy about 636 MB on disk; a temporary copy during preparation is deleted afterwards. Run preparation on the Ollama host. No separate inference server or mandatory Metal dependency is required.

After building, configure your MCP client and restart its KnowledgeRail process:

{
  "mcpServers": {
    "knowledge-rail": {
      "command": "node",
      "args": ["/absolute/path/to/KnowledgeRail/dist/index.js", "--root", "/absolute/project/path"],
      "env": {
        "KNOWLEDGE_RAIL_EMBEDDING_BASE_URL": "http://localhost:11434/v1",
        "KNOWLEDGE_RAIL_EMBEDDING_MODEL": "qwen3-embedding:0.6b",
        "KNOWLEDGE_RAIL_EMBEDDING_DIMENSIONS": "1024",
        "KNOWLEDGE_RAIL_RERANK_BASE_URL": "http://localhost:11434",
        "KNOWLEDGE_RAIL_RERANK_MODEL": "knowledgerail-bge-reranker-v2-m3:q8_0"
      }
    }
  }
}

The reranker base URL is Ollama's native root, without /v1 or /api. KNOWLEDGE_RAIL_RERANK_PROVIDER=ollama is optional: the base URL selects Ollama already. KNOWLEDGE_RAIL_RERANK_API_KEY optionally supplies a bearer token. Do not combine RERANK_BASE_URL with the older RERANK_ENDPOINT setting. Models must be installed in advance; the MCP process never downloads models. Ollama loads the configured model on demand and manages its residency (5-minute keep-alive requested). Embeddings and reranker can coexist when memory permits.

Reranking has no KnowledgeRail time limit by default. Once configured, it waits for scoring to finish. The separate 1,500 ms semantic deadline excludes reranker time, so inference latency does not invalidate successful embeddings. Errors and invalid responses still preserve base retrieval. Client or Ollama connection limits remain outside KnowledgeRail's control.

KNOWLEDGE_RAIL_RERANK_BUDGET_MS=0 explicitly selects this unlimited behavior; omitting the variable has the same effect. A positive value (1–30,000 ms) is an optional administrative override for deployments that deliberately want a deadline, not part of the configuration above. The earlier 500 ms experiment is retained only as historical latency evidence, not as the activation policy. No relevance threshold is derived from elapsed time.

Compatibility is deliberately narrow: the adapter verifies Ollama 0.34.3 and the prepared BGE weights before scoring. Ollama currently has no native /api/rerank contract; this integration uses the verified, unnormalised classifier output from its legacy /api/embeddings route. Arbitrary embedding or generative models and unverified Ollama versions fall back safely. Do not substitute /api/embed, which normalises the score. Runtime compatibility needs revalidation when Ollama changes. The client and preparation script are portable; measured hardware results are macOS only, not a Windows/Linux performance guarantee.

The existing HTTP RERANK_ENDPOINT + RERANK_MODEL configuration remains compatible with indexed /rerank responses; it also has no default reranking deadline. The Ollama configuration above needs no separate service. See the measured results and limits.

Compatibility

All public tools use the knowledge_* prefix in both protocol eras. Historical wiki_* tools and knowledge_menu are not advertised. The legacy adapter is transport/workspace compatibility only: it does not restore the old tool catalog. Conservative migration of existing wiki data remains supported independently of protocol compatibility.

Development and verification

npm ci
npm run verify
npm run audit:runtime
npm run audit:signatures
npm run package:smoke

Run all deterministic retrieval and quality gates:

npm run eval:gates

The aggregate command runs these unchanged individual gates:

npm run eval:retrieval:gate
npm run eval:hybrid:gate
npm run eval:widening:gate
npm run eval:source-coverage:gate
npm run eval:evidence-ir:gate
npm run eval:code-evidence:gate
npm run eval:drift:gate
npm run eval:recovery:gate
npm run eval:task-context:gate
npm run eval:semantic:gate
npm run eval:migration:gate
npm run eval:editorial:gate
npm run eval:documents:gate
npm run eval:tool-surface:gate

The benchmark fixtures and acceptance rules are documented in benchmarks/README.md. CI verifies Node.js 22 and 24, all regression gates, benchmark smoke tests, the runtime dependency audit, and installed-tarball smokes on Ubuntu, macOS, and Windows.

See CONTRIBUTING.md before opening a pull request and SECURITY.md for vulnerability reporting.

License

Licensed under the Apache License 2.0. You may use, modify, and distribute the project, including commercially, subject to the license terms and preservation of required notices. The license does not require derivative products to be open source.

Origins and acknowledgement

KnowledgeRail is an independent project. Its starting point was inspired in part by Andrej Karpathy's LLM Wiki idea file: an LLM maintains durable Markdown knowledge that compounds instead of reconstructing everything from raw sources on every query.

KnowledgeRail has since evolved into a distinct MCP 2.0 agent-memory system with bounded hybrid retrieval, coverage and gap reporting, Evidence IR, deterministic code evidence, migration support, and contract-driven document production. It is not affiliated with or endorsed by Andrej Karpathy. See ACKNOWLEDGEMENTS.md.