🧠 Smart Long Context — Wiki-Obsidian ( QwikVault MCP )

A structured wiki writer for AI — not a memory system that controls how AI thinks.

Table of Contents

1. What This MCP Actually Does

2. Benchmarks

3. The Problem It Solves

4. Core Philosophy - A Pen, Not a Brain

5. How It Works

6. Knowledge Trust Hierarchy - T1 Context

7. The Claude.md Rules File

8. Wiki Agent Protocol

9. Quick Start

10. Commands Reference

11. System Architecture

12. Environment Variables

Related MCP server: MCP Brain Server

📌 What This MCP Actually Does

QwikVault MCP is an AI-powered wiki reading and writing tool built on the Obsidian architecture and a Q&A knowledge model.

Its single job: write and retrieve reliable, structured documentation so that AI has the best possible context when answering your requests.

It does not:

• Intercept or redirect how AI reasons

• Inject knowledge automatically or silently

• Replace the AI's inference engine

• Use vector embeddings to steer semantic outputs

• Act as a memory proxy that "controls" what AI knows

It does:

• Let AI (or you) write completed, verified knowledge into .brain_wiki/ as Obsidian-compatible Markdown files

• Provide a structured navigation index (Directory-tree.md) so AI can find the right article for each task

• Expose a clean slash-command interface that AI uses to decide — on its own — which article to read

• Keep all knowledge human-readable, Git-trackable, and fully auditable

One sentence summary: This MCP gives AI a well-organized library of verified project knowledge. The AI still decides what to read and how to use it.

📊 Benchmarks

Latest Benchmark Score: 100/100 🟢 PASSED

Updated at: Mon, 04 May 2026 03:18:06 GMT

🔴 The Problem It Solves

Every AI agent — Claude, Cursor, Gemini, GPT — loses all memory at session boundaries.

Existing workarounds address symptoms but not the root cause:

The core gap: there is no reliable, human-curated, AI-readable knowledge layer that lives inside the project repo and stays under human control.

🎯 Core Philosophy - A Pen, Not a Brain

This MCP is a pen that writes structured knowledge, not a brain that controls how AI thinks.

What separates this from RAG and vector memory systems

RAG and vector systems operate by automatically pushing relevant chunks of data into AI's reasoning based on semantic similarity scores. The AI has no choice — it receives pre-selected context based on embedding distances it cannot inspect.

This MCP takes the opposite approach:

1. Humans (or AI agents) deliberately write finalized, verified knowledge into .brain_wiki/ articles

2. Directory-tree.md acts as a table of contents — a library catalog, not a retrieval engine

3. The AI reads the catalog first, then decides which article is relevant to its current task

4. The AI reads only what it chooses — no silent injection, no background steering

The removal of vector embeddings is not a technical regression. It is a deliberate design choice:

Vectors pump semantically "similar" but unverified data into AI reasoning automatically. This wiki requires AI to exercise judgment — to choose what it reads. That judgment gap is where hallucination prevention lives.

AI remains the reasoning engine. The wiki provides the domain grounding.

🔄 How It Works

User Request
     │
     ▼
┌─────────────────────────────────────────────────────────────┐
│                     AI Agent Session                         │
│                                                             │
│  Step 1 — AI reads the library catalog                     │
│  /wiki read-map                                            │
│     ↓ Loads Directory-tree.md                              │
│     ↓ Reviews article titles, purposes, "Read when:" hints │
│     ↓ AI decides which articles are relevant               │
│                                                             │
│  Step 2 — AI selects and reads relevant articles           │
│  /wiki read <article-id>                                   │
│     ↓ Loads curated T1 knowledge into context              │
│     ↓ AI supplements its reasoning — not overridden        │
│                                                             │
│  Step 3 — AI executes the task                             │
│     ↓ Uses project-specific context it chose to load       │
│     ↓ Architectural decisions respected                     │
│                                                             │
│  Step 4 — (Optional) AI writes new verified knowledge      │
│  /wiki write "Title" "Content..." --purpose "..." --tags   │
│     ↓ Writes completed knowledge to .brain_wiki/           │
│     ↓ Directory-tree.md auto-regenerated                   │
└─────────────────────────────────────────────────────────────┘
     │
     ▼
Persistent, verified knowledge in .brain_wiki/ (cross-session)

Critical constraint: Wiki articles are read by AI as supplementary, human-verified context — not as mandatory training signal or forced reasoning paths. AI reads, considers, and decides how to use the information. Its inference capability is never bypassed.

📊 Knowledge Trust Hierarchy - T1 Context

When an AI agent handles a request, it should consult knowledge sources in priority order. This wiki occupies the top tier because it contains deliberately written, human-verified knowledge — not inferred, scraped, or automatically embedded data.

T1 ── .brain_wiki/ articles
       └── Written by humans or AI after task completion
       └── Verified, finalized — not WIP or speculation
       └── AI reads these FIRST before other research
       └── Consulted via /wiki read-map → /wiki read

T2 ── Web search / documentation
       └── General knowledge; may be outdated
       └── Used when T1 has no coverage

T3 ── LLM trained priors / inference
       └── Fallback when T1+T2 insufficient
       └── Must be flagged as "inferred, not verified"

T4 ── Real-time code scanning
       └── Implementation-level detail
       └── T1 provides intent; T4 provides current code reality

T1 is trusted because it was written deliberately — not because the system decided it was "relevant" via embedding distance.

The wiki does not replace the agent's reasoning. It provides curated, versioned project intelligence that makes AI's answers more accurate and aligned with actual project decisions.

📋 The Claude.md Rules File

This MCP ships with a Claude.md file — a plain-text protocol that tells AI how to interact with the wiki.

What Claude.md does:

• Instructs AI to read the wiki catalog first (/wiki read-map) before working on tasks

• Tells AI which articles to look for based on task type

• Defines when to write new articles and what belongs in them

• Sets quality standards for wiki content

What Claude.md does NOT do:

• Force or hardcode AI reasoning paths

• Override AI's judgment or inference capability

• Inject content silently

• Replace the AI's system prompt or base model behavior

Think of Claude.md as a librarian's guide: it tells AI "when working on auth tasks, the auth-related articles in the library are worth checking first." The AI still decides how to use what it finds.

Adapting the Rules File to Your AI

The file is named Claude.md by default. If you use a different AI:

Rename the file and reference it in your AI client's system prompt or rules configuration. The content is portable — no vendor-specific instructions are required.

📜 Wiki Agent Protocol

AI agents using this MCP follow a simple four-rule protocol for writing wiki articles.

Rule W-1: Read the catalog before writing

/wiki read-map
// → Loads Directory-tree.md (the library catalog)
// → AI identifies: does this article already exist?
// → Decision: create new article OR append to existing

Rule W-2: Create vs. Append

Rule W-3: Required metadata on every new article

Every new article must include:

• --purpose — one sentence: what knowledge this article stores

• --tags — at least one canonical taxonomy tag

• --depends-on — IDs of prerequisite articles (if applicable)

Rule W-4: Only write durable, verified knowledge

Write only:

• ✅ Completed architectural decisions

• ✅ Implemented technical patterns and conventions

• ✅ Resolved integration issues with proven solutions

• ✅ Performance optimizations validated in production

• ✅ Q&A pairs that reflect confirmed project behavior

Never write:

• ❌ Technical debt notes or known bugs (creates misleading T1 context)

• ❌ WIP / in-progress context (becomes stale and misleading immediately)

• ❌ API keys, secrets, or credentials in any form

• ❌ Speculation or unverified assumptions

• ❌ Scratch notes or temporary task context

🚀 Quick Start

1. Initialize the wiki vault

npx qwikvault-mcp init --project .

Run this in your project root before starting any AI chat session. This command creates the full project structure in one shot:

Without the post-commit hook, staleness detection in /wiki sync is incomplete.

Optionally generate IDE config files:

npx qwikvault-mcp init --project . --ide cursor
# or: --ide vscode | windsurf | claude | gemini | all

2. Rename and configure the rules file for your AI

The included Claude.md file defines how AI should interact with the wiki. Rename it to match your AI client (see The Claude.md Rules File above) and reference it in your AI configuration.

3. Start the MCP server

npx qwikvault-mcp

4. Configure your AI client

Refer to the configs/ directory for pre-configured templates for Claude Desktop, Cursor, Windsurf, Gemini, and more.

5. Open wiki in Obsidian (Optional)

Point Obsidian's vault to your project root. The .brain_wiki/ directory renders as a visual knowledge graph with full depends_on link resolution.

💻 Commands Reference

All interactions use the single cmd MCP tool with slash syntax.

Core Knowledge Operations

Navigation & Discovery

Multi-Agent Coordination

Governance & Maintenance

🛠️ System Architecture

Design Principles

1. File-per-Article — No Database

Each article is one .md file in .brain_wiki/. No JSON database, no SQLite, no binary formats:

• Fully human-readable and editable in any text editor

• Meaningful Git diffs per article for PR review

• Native Obsidian graph visualization via depends_on links

• No schema migrations required

2. No Vector Embeddings — By Design

Eliminating vectors is not a technical limitation — it is a deliberate architectural decision.

Vector systems inject semantically "similar" but unverified data into AI reasoning automatically. The AI receives pre-selected context it did not choose. This system requires AI to read the directory catalog and decide which article to load. That act of selection is where knowledge quality is preserved.

With 50–500 curated articles (typical project scale), deterministic trigram + taxonomy scoring is:

• Locally fast — retrieval logic runs on local filesystem with no external service calls

• Predictable — no semantic drift, no model dependency, no embedding staleness

• Auditable — every search is traceable; no opaque similarity scores

An optional embedding layer is reserved for v2 via MCP_ENABLE_EMBEDDING=true for wikis exceeding 1,000 articles.

3. Single Slash-Command Router

One cmd MCP tool handles all operations via slash syntax. This prevents "tool explosion" — a failure mode where agents get confused selecting among dozens of specialized tools.

4. Command-Driven, No Background Workers

The server has no file watchers, no autonomous job loops, and no background timers beyond a short debounced write coalescer for Directory-tree.md regeneration. The server only computes when explicitly called.

"Smart behavior comes from the agent's reasoning, not from the server guessing what to do."

Post-commit Git hooks write to .context/pending-sync.txt, consumed synchronously on the next /wiki read-map call — providing event bridging without background processes.

5. POSIX-Atomic Writes

writeFileSync(tmp) → renameSync(tmp, final) guarantees crash safety. Readers see complete files or nothing — never partial writes.

6. Project-Scoped Instance Lock

The server uses a project-scoped lock (derived from MCP_WIKI_ROOT) to prevent duplicate server processes for the same project across multiple IDE clients. Use MCP_DISABLE_INSTANCE_LOCK=true only when running intentional multi-agent swarms.

For a complete decision log, see the Architecture Decision Record.

⚙️ Environment Variables

📄 Article format

Every article in the wiki follows a strict YAML frontmatter structure for maximum AI readability and Obsidian compatibility:

---
id: auth-jwt-refresh-flow-abc123
title: Auth JWT Refresh Flow
purpose: Documents the token refresh strategy and edge cases for the auth module
tags: [auth, jwt, security]
depends_on: [api-rate-limiting-xyz, user-session-management-def]
language: en
created: 2026-04-21T10:00:00Z
updated: 2026-04-21T10:00:00Z
---

## Token Refresh Strategy

[Article body — verified, completed knowledge only]

License

MIT © VoTrongHoang-Dyor

💖 Support me

If you resonate with first-principles engineering, robust system architecture, and sovereign digital solutions, your support accelerates the development of these ecosystems.