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

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

[![NPM Version](https://img.shields.io/npm/v/qwikvault-mcp.svg?color=green)](https://www.npmjs.com/package/qwikvault-mcp)
![Node.js 20+](https://img.shields.io/badge/Node.js-%3E%3D20.0-blue.svg)
![MCP SDK 1.0](https://img.shields.io/badge/MCP-SDK%201.0-orange.svg)
![License MIT](https://img.shields.io/badge/License-MIT-purple.svg)
![Obsidian Compatible](https://img.shields.io/badge/Obsidian-Compatible-violet.svg)

[![QwikVault Thumbnail](assets/thumbnail.webp)](https://www.youtube.com/watch?v=vlY3Lyez1mE)

---

## Table of Contents

1. [What This MCP Actually Does](#📌-what-this-mcp-actually-does)
2. [Benchmarks](#📊-benchmarks)
3. [The Problem It Solves](#🔴-the-problem-it-solves)
4. [Core Philosophy - A Pen, Not a Brain](#🎯-core-philosophy---a-pen-not-a-brain)
5. [How It Works](#🔄-how-it-works)
6. [Knowledge Trust Hierarchy - T1 Context](#📊-knowledge-trust-hierarchy---t1-context)
7. [The Claude.md Rules File](#📋-the-claudemd-rules-file)
8. [Wiki Agent Protocol](#📜-wiki-agent-protocol)
9. [Quick Start](#🚀-quick-start)
10. [Commands Reference](#💻-commands-reference)
11. [System Architecture](#🛠️-system-architecture)
12. [Environment Variables](#⚙️-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

```typescript
/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

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

```bash
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](#📋-the-claudemd-rules-file) above) and reference it in your AI configuration.

### 3. Start the MCP server

```bash
npx qwikvault-mcp
```

### 4. Configure your AI client

Refer to the [configs/](./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](./ARCHITECTURE.md).

---

## ⚙️ 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:

```markdown
---
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](https://github.com/VoTrongHoang-Dyor/QwikVault-MCP/blob/465197d1aa5f989fd764b958a379474ddeb93674/LICENSE)

---

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