📚 Librarian MCP: The Atomic Knowledge OS (v5.0.0)

Librarian MCP is an intelligent orchestration layer for your personal knowledge base, inspired by Andrej Karpathy's LLM Wiki vision. It transforms a simple folder of Markdown files into a dynamic, structured, and safe "digital brain" accessible via the Model Context Protocol (MCP).

🏗️ Architecture: Modular & Layered

Librarian v5/v6 features a professional Clean Architecture. Every microservice is split into three layers:

• 📂 core/: Pure business logic (Manager classes) decoupled from protocols.

• 📂 bootstrap/: Self-healing initialization and migration routines.

• 📄 index.ts: Thin orchestrators for the MCP SDK.

graph TD
    User([User / Obsidian]) <--> Hub[(Knowledge Hub\nMarkdown + Git)]
    subgraph "Librarian Modular Suite"
        Hub_MCP[Librarian Hub] <--> Hub
        Git_MCP[Librarian Git] <--> Hub
        Search_MCP[Librarian Search] <--> Hub
    end
    AI_Agent([AI Agent / Gemini-CLI / Cursor]) <--> Hub_MCP
    AI_Agent <--> Git_MCP
    AI_Agent <--> Search_MCP

🏛️ The Two-Branch Protocol (State Machine)

Librarian v5 treats your knowledge hub as a robust state machine. To ensure architectural integrity, we enforce the Two-Branch Protocol:

1. master (Crystallized): The immutable source of truth. Stable, indexed, and ready for consumption.

2. draft (Active Session): The ONLY legal space for modifications. All AI interactions accumulate here.

Consolidation sessions automatically detect "illegal" branches and merge them into the draft using the Accumulative Merge strategy.

🛡️ Core Protocols

🔄 Accumulative Merge

Librarian never destroys knowledge during conflicts. Instead of traditional Git merge conflicts, we use Non-Destructive Markdown Callouts. Conflicting versions are wrapped in GitHub-compatible blocks:

🧹 Smart Curation Protocol

The Hub root directory is kept strictly clean. Librarian classifies stray files into:

• GHOSTS: Redundant empty files of existing nodes (automatically deleted).

• NODES: Misplaced wiki entries with YAML metadata (moved to wiki/).

• SOURCES: Raw data or text logs (moved to raw/).

🏗️ The Microservice Suite

🛡️ Librarian Hub (alsokolov2/librarian-hub-mcp)

The Hub is the guardian of structure.

• Smart Audit: Classifies and curates root directory items.

• Validation: Enforces naming conventions and YAML requirements.

• Templates: Automatic project and entity scaffolding.

📜 Librarian Git (alsokolov2/librarian-git-mcp)

The Git service is the guardian of state.

• State Control: Manages the Master/Draft lifecycle.

• Atomic Commits: Structured, auditable change history.

🧠 Librarian Search (alsokolov2/librarian-search-mcp)

The Search service is the intellectual layer.

• Semantic Search: Fully local RAG (Transformers.js + LanceDB).

• Global Indexing: Unified searchable map of your digital brain.

🚀 Quick Start (Docker Compose)

services:
  librarian-hub:
    image: alsokolov2/librarian-hub-mcp:latest
    container_name: librarian-hub
    user: "1000:1000"
    volumes:
      - /path/to/your/notes:/app/knowledge-hub
    environment:
      - KNOWLEDGE_HUB_PATH=/app/knowledge-hub
    stdin_open: true
    tty: true
    restart: unless-stopped

  librarian-git:
    image: alsokolov2/librarian-git-mcp:latest
    container_name: librarian-git
    user: "1000:1000"
    volumes:
      - /path/to/your/notes:/app/knowledge-hub
    environment:
      - KNOWLEDGE_HUB_PATH=/app/knowledge-hub
    stdin_open: true
    tty: true
    restart: unless-stopped

🛠️ Development

npm install
npm run build
npm test
npm run release

⚖️ License

MIT License. Created with ❤️ by AlSokolov2.