🧠 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

---

📌 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

<!-- BENCHMARK_START -->

Latest Benchmark Score: 100/100 🟢 PASSED

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

Suite	Score	Weight	Duration	Status
MMLongBench	100	25%	73ms	✅
DocETL	100	25%	7ms	✅
M3DocVQA	100	25%	3ms	✅
GraphRanker	100	25%	5ms	✅

<!-- BENCHMARK_END -->

---

🔴 The Problem It Solves

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

Loss Scenario	Impact
Context window filled (~100K–200K tokens)	Agent forgets early architectural decisions
IDE restart / session timeout	Agent starts from zero each time
Multi-agent handoff	No shared state between agents
Long-running projects (days/weeks)	Patterns rediscovered repeatedly, conventions drift

Existing workarounds address symptoms but not the root cause:

Approach	Critical Limitation
RAG (Chroma, Pinecone, Weaviate)	Infrastructure overhead; embeddings silently steer AI toward noisy corpus data
mem0, Zep, Letta	External SaaS; opaque retrieval; AI cannot audit what it "remembers"
.cursorrules / system prompts	Static — cannot evolve; agents cannot write new knowledge back
Conversation history	Unstructured; requires full re-read; no navigation layer

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:

AI Client	Recommended file name
Claude (Anthropic)	Claude.md or CLAUDE.md
Cursor	.cursorrules or AGENTS.md
Gemini / Antigravity	GEMINI.md
Generic agents	AGENTS.md

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

Situation	Action
No existing article covers this topic	/wiki write "New Title" "..." --purpose "..." --tags t1,t2
Content extends an existing article	/wiki write "Existing Title" "..." --append
Content is too small for a standalone article	Append to the most relevant existing article

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:

Path	Description
.brain_wiki/Directory-tree.md	Navigation catalog — AI reads this first each session
.brain_wiki/taxonomy.yml	Canonical tag definitions for normalized search
.context/mcp-long-ctx.lock	Instance lock placeholder (managed at runtime)
.context/wiki-audit.jsonl	Append-only audit trail of all wiki operations
.gitignore.env	Pre-configured ignore rules for .brain_wiki, .context, Claude.md
Claude.md	Agent protocol rulebook — rename to match your AI client
.git/hooks/post-commit	Optional hook — records changed files for /wiki sync

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

Command	Description
/wiki write "<title>" "<content>" --purpose "..." --tags t1,t2	Create or overwrite an article with full metadata
/wiki write "<title>" "<content>" --append	Append content to an existing article
/wiki write ... --force	Override min-content/language policy checks intentionally
/wiki read <id-or-title>	Load a complete article into context
/wiki search <query>	Fuzzy search across titles, tags, purpose, and body preview
/wiki list	List all articles with title, tags, and purpose

Navigation & Discovery

Command	Description
/wiki read-map	Load Directory-tree.md — the library catalog
/wiki suggest "<task-description>"	Get top-5 most relevant articles for an upcoming task

Multi-Agent Coordination

Command	Description
/wiki emit --diff "<description>" --agent <id>	Agent reports task completion to wiki queue
/wiki status	View pending queue and session context usage

Governance & Maintenance

Command	Description
/wiki sync	Detect articles that have fallen behind code changes via git log
/wiki report	Health metrics: orphan articles, staleness scores, read frequency
/wiki delete <id-or-title>	Soft-delete an article (preserves history in Git)
/health	Server uptime, RAM usage, and subsystem status

---

🛠️ 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

Variable	Default	Description
MCP_WIKI_ROOT	process.cwd()	Absolute path to the directory containing .brain_wiki/
MCP_WIKI_LANGUAGE	auto	Enforce wiki write language: auto | vi | en
MCP_LOG_LEVEL	info	Log verbosity: debug | info | warn | error
MCP_DISABLE_INSTANCE_LOCK	false	Allow concurrent instances for multi-agent swarm configurations
MCP_ENFORCE_WIKI_FIRST	false	Enforce /wiki read-map before other wiki commands in each server process
MCP_TOKEN_BUDGET	100000	Max token budget for Directory-tree.md read operations
MCP_ENABLE_EMBEDDING	false	(v2) Enable optional vector layer for wikis >1,000 articles

---

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

<p align="left"> <a href="https://ko-fi.com/tronghoang_dyor"> <img src="https://img.shields.io/badge/Ko--fi-F16061?style=for-the-badge&logo=ko-fi&logoColor=white" alt="Ko-fi"/> </a> <a href="https://paypal.me/TrongHoangDyor"> <img src="https://img.shields.io/badge/PayPal-00457C?style=for-the-badge&logo=paypal&logoColor=white" alt="PayPal"/> </a> </p>