knowledge-base MCP server

knowledge-base-server

Make every AI agent you use smarter.

A persistent memory system that captures, classifies, synthesizes, and retrieves knowledge for AI agents. One brain, multiple agents, compounding intelligence. Production-proven with 200+ documents, three agents (Claude, Codex, Gemini), and daily use.

This is not just a search engine. It is an intelligence pipeline that turns raw information into refined, retrievable knowledge -- and gets smarter every session.

---

The Problem

AI agents are stateless. Every session starts from zero. You end up:

• Copy-pasting context between sessions
• Re-explaining your codebase, architecture, and preferences
• Watching agents hallucinate because they lack YOUR information
• Losing debugging insights that took hours to discover
• Running multiple agents that can't share what they know

The smarter the model, the more painful the amnesia. Context is the bottleneck, not intelligence.

The Solution

knowledge-base-server sits between your knowledge and your AI agents. It ingests everything -- your Obsidian vault, code, documents, YouTube transcripts, X bookmarks, terminal sessions -- and serves it through MCP and REST APIs. Every agent you use reads from and writes to the same brain.

Your AI gets smarter every day. Every session builds on the last.

Obsidian Vault ------+
Code Repos ----------+
YouTube Transcripts --+---> [ KB Server ] ---> SQLite + FTS5 ---> [ MCP ] ---> Claude Code
X/Twitter Bookmarks -+         |                   |                          Codex CLI
Web Clippings -------+     Port 3838          Embeddings          [ REST ] --> Gemini CLI
Terminal Sessions ----+    Web Dashboard      Semantic Search                  ChatGPT
Bug Fix Captures -----+                                                       Any MCP Client

Obsidian is the source of truth -- the human layer where you organize, link, and curate knowledge. The KB server is the optimized retrieval layer that makes it AI-ready with minimal token usage.

---

How It Works: The Intelligence Pipeline

This is the core differentiator. Raw information flows through seven layers to become actionable intelligence:

1. Capture Layer

Ingest from everywhere:

• Obsidian vault -- bidirectional sync, auto-indexes on changes
• YouTube transcripts -- via yt-dlp or kb_capture_youtube
• X/Twitter bookmarks -- browser export to markdown, auto-ingest
• Web articles -- Obsidian Web Clipper or kb_capture_web
• Terminal sessions -- kb_capture_session records what worked, failed, and why
• Bug fixes -- kb_capture_fix records symptom, cause, and resolution
• Code, PDFs, text -- 20+ file types with automatic type detection

Every source enters the system as a raw capture, ready for processing.

2. Classification Layer

The kb_classify tool runs AI classification on unprocessed content:

• Assigns document type (research, idea, workflow, lesson, fix, decision, session)
• Auto-generates tags and project routing
• Writes structured summaries and key topics
• Adds confidence scoring
• Enforces frontmatter discipline on every note

Raw clippings become structured, searchable knowledge automatically.

3. Promotion Pipeline

Raw captures get refined into higher-value knowledge artifacts:

• Captures in inbox get normalized into sources
• Sources get promoted to insights, lessons, decisions, runbooks
• The kb_promote tool extracts structured knowledge from raw material
• Higher-value knowledge ranks higher in retrieval
• The system distinguishes signal from noise automatically

4. Synthesis Layer

The kb_synthesize tool connects dots across sources:

• Reads recent notes across all types and projects
• Identifies recurring themes, patterns, and bottlenecks
• Surfaces opportunities and workflow improvements
• Generates cross-cutting insights that no single source contains
• This is where raw information becomes actionable intelligence

5. Three-Tier Memory (Cold / Warm / Hot)

Not all knowledge is equal. The system uses three tiers to prevent context pollution:

Tier	What Lives Here	When Retrieved	Example
Hot	Active project context, recent sessions, current decisions	First, always	"How did we fix auth yesterday?"
Warm	Accumulated lessons, research, validated workflows	When relevant to query	"What's our Docker networking pattern?"
Cold	Raw captures, archived sources, old terminal logs	Only when deep-diving	"What did that YouTube video say about caching?"

Why three tiers? Without tiering, a search for "authentication" returns every raw article you ever clipped alongside your actual auth architecture decision. The tiers ensure agents get signal, not noise. Hot knowledge is always fresh and relevant. Cold knowledge is preserved but doesn't pollute active context.

6. Token-Optimized Retrieval

Every token costs money and context window space. The retrieval system minimizes waste:

• kb_context returns summaries and metadata WITHOUT full content -- 90%+ token savings
• kb_search uses FTS5 with BM25 ranking, title boosting, and AND-first precision
• kb_search_smart combines keyword and semantic search for conceptual queries
• kb_read loads full content only when needed, after context identifies relevant docs
• Agents get the right information in the fewest possible tokens

7. The Self-Learning Loop

This is the core innovation. The system compounds intelligence over time:

Sessions 1-10:    AI makes mistakes. You correct. Fixes get captured.
Sessions 10-50:   AI recognizes patterns. Starts getting things right more often.
Sessions 50-100:  AI knows your codebase, preferences, architecture patterns.
Sessions 100+:    One-shot clean code. Accumulated context covers everything.

The loop in detail:

1. AI agent attempts a task
2. Output gets evaluated (human judgment -- the irreplaceable element)
3. Corrections and findings get captured (kb_capture_session, kb_capture_fix)
4. KB server ingests the session data
5. kb_synthesize organizes and connects to existing knowledge
6. Agent instructions auto-update with lessons learned
7. Next session starts with better context
8. Repeat -- compounding improvement

This is NOT fine-tuning. NOT RLHF. It is self-modifying instructions through operational history. The model doesn't change. The context it receives does. And context is everything.

---

Features

Core

• SQLite FTS5 full-text search with BM25 ranking and highlighted snippets
• Semantic/vector search via local HuggingFace embeddings (Xenova/all-MiniLM-L6-v2) — no API keys needed
• Hybrid search mode (kb_search_smart) combining keyword + semantic for conceptual queries
• Web dashboard for browsing, searching, and managing documents
• CLI for all operations (kb start, kb search, kb ingest, kb setup)
• One-command MCP registration (kb register)
• Interactive setup wizard (kb setup) with agent-compatible auto mode

Ingestion

• 20+ file types: Markdown, text, code, PDFs, JSON, YAML, XML, CSV
• Auto-ingest on first run (~/knowledgebase + Claude memory directories)
• Duplicate detection via content hashing
• Obsidian vault bidirectional sync with incremental indexing
• YouTube transcript capture
• X/Twitter bookmark ingestion
• Web article capture with metadata

Intelligence

• AI auto-classification (type, tags, summary, key topics, confidence)
• Knowledge promotion pipeline (raw -> structured)
• Cross-source synthesis (themes, patterns, opportunities)
• Three-tier memory (cold/warm/hot) with tier-aware retrieval
• Token-optimized context briefings (90%+ savings over full reads)
• Session and fix capture for operational learning
• Safety review for destructive actions (multi-model consensus)

Integration

• MCP server (stdio for local, StreamableHTTP for remote)
• REST API with OpenAPI 3.1 specification
• ChatGPT Custom GPT Actions via OpenAPI import
• OAuth 2.1 with OIDC discovery for remote access
• API key authentication for scripts and automation
• systemd service with auto-restart for production deployment

Security

• bcrypt password hashing with HttpOnly session cookies
• Dual auth: API keys (fast path) + OAuth 2.1 Bearer tokens (signed JWTs bound to the MCP resource)
• No self-registration: OAuth accounts are created by the operator with kb auth add-user
• Three separate API keys for Claude, OpenAI, and Gemini
• Safety review tool checks KB history before destructive actions
• No external dependencies for core functionality

---

Quickstart

Prerequisites

• Node.js >= 18.0.0
• That's it. No external databases, no Docker required, no cloud dependencies.

Install

git clone https://github.com/willynikes2/knowledge-base-server.git
cd knowledge-base-server
npm install
npm link

First Run (Interactive Setup Wizard)

kb setup

The wizard detects your environment, asks which AI agents you use, configures everything, and runs your first ingest. Takes about 60 seconds.

For agent-driven installation (no prompts):

kb setup --auto --password=yourpass --vault=~/obsidian-vault --agents=claude,codex --deploy=systemd

Manual Setup

KB_PASSWORD=yourpassword kb start    # Start server on port 3838
kb register                          # Register MCP with Claude, Codex, and Gemini
kb register --agents=claude,codex    # Register only a subset
kb ingest ~/obsidian-vault           # Ingest your knowledge
kb search "docker networking"        # Search from terminal
kb status                            # Check stats

Connect to Local Agents

After kb register, Claude Code, Codex CLI, and Gemini CLI automatically point at kb mcp. Restart the sessions you want to update, then test it:

> Search the knowledge base for recent bug fixes

Your agent will use kb_search and return results from your accumulated knowledge.

---

Don't Want to Self-Host? Use Memstalker

Memstalker is the hosted version of knowledge-base-server. Same engine, zero infrastructure.

	Self-Hosted (Free)	Memstalker Hosted
Cost	Free forever	From $12/mo
Setup	Clone, install, configure	Sign up, connect your agents
Infrastructure	You run the VPS	We handle everything
Updates	git pull	Automatic
Multi-device sync	You configure	Built-in
Backups	You manage	Automatic
All 16 MCP tools	Yes	Yes
Obsidian integration	Yes	Yes
REST API + ChatGPT	Yes	Yes

Self-host if: You want full control, have a VPS, and enjoy running your own infrastructure.

Use Memstalker if: You want persistent AI memory without managing servers. Connect your agents in minutes.

First 500 early adopters get Pro at $12/mo forever (normally $25): memstalker.com

---

MCP Tools

Core tools (stdio + HTTP)

All 16 core tools are available via both stdio and HTTP:

Tool	Description
kb_search	Full-text search with BM25 ranking and highlighted snippets
kb_search_smart	Hybrid keyword + semantic search for conceptual queries
kb_context	Token-efficient briefing -- summaries only, 90%+ savings. Use BEFORE kb_read
kb_read	Read full document content by ID
kb_list	List documents filtered by type or tag
kb_write	Write a new note to the Obsidian vault
kb_ingest	Ingest raw text directly into the database
kb_classify	Auto-classify unprocessed notes (type, tags, summary)
kb_promote	Promote raw source into structured knowledge
kb_synthesize	Generate cross-source synthesis connecting recent knowledge
kb_capture_session	Record a debugging/coding session with findings
kb_capture_fix	Record a bug fix with symptom, cause, resolution
kb_capture_web	Capture a web article with content and metadata
kb_capture_youtube	Capture a YouTube transcript with metadata
kb_vault_status	Show vault indexing stats by type and project
kb_safety_check	Review a destructive action against KB history

Local-only bus tools (stdio only)

The stdio MCP server also exposes a lightweight append-only message bus for cross-model coordination:

Tool	Description
bus_send	Send a markdown message to a local channel
bus_inbox	Read messages newer than a cursor
bus_wait	Long-poll until a new message arrives or timeout elapses

Resource template: bus://{channel}

Shell shims:

bus-send ticket:PF-1884 "report ready" --sender codex --kind result
bus-inbox ticket:PF-1884 --since 0
bus-wait ticket:PF-1884 --since 12 --timeout-ms 30000

See docs/message-bus.md for channel conventions and cross-model usage.

Mistake ledger tools (local stdio only)

Tool	Description
kb_mistake_record	Record a mistake a reviewer or test caught, with its fix
kb_patterns_for	Get up to 3 approved "known pitfalls" that match a task

See docs/mistake-ledger.md.

---

CLI Commands

kb setup              Interactive setup wizard (--auto for agent mode)
kb start              Start the dashboard + API server (default :3838)
kb stop               Stop the running server
kb mcp                Start MCP stdio server (used by AI tools)
kb register           Register MCP server with Claude Code
kb ingest <path>      Ingest a file or directory
kb search <query>     Search documents from terminal
kb status             Show stats and server status
kb classify           Auto-classify unprocessed vault notes
kb summarize          Generate AI summaries for unsummarized notes
kb capture-x          Ingest X/Twitter bookmarks from export
kb safety-check       Review a planned action against KB history
kb mistakes           Mistake ledger: import-sdd, import-seed, record, record-run, list, stats
kb patterns           Patterns from repeated mistakes: draft, list, page, set-status

---

Architecture

                         +------------------+
                         |   AI Agents      |
                         | Claude | Codex   |
                         | Gemini | ChatGPT |
                         +--------+---------+
                                  |
                    MCP (stdio)   |   REST API (/api/v1/)
                    MCP (HTTP)    |   OpenAPI 3.1
                                  |
                         +--------+---------+
                         |    KB Server     |
                         |   Express :3838  |
                         +--------+---------+
                                  |
              +-------------------+-------------------+
              |                   |                   |
     +--------+-------+  +-------+--------+  +-------+--------+
     | SQLite + FTS5   |  |  Embeddings    |  |  Obsidian      |
     | documents       |  |  all-MiniLM    |  |  Vault Sync    |
     | vault_files     |  |  L6-v2 local   |  |  (bidirectional)|
     | embeddings      |  |  cosine sim    |  |  source of truth|
     +----------------+  +----------------+  +----------------+

Data directory: ~/.knowledge-base/

• kb.db -- SQLite database with FTS5 index
• files/ -- Ingested file copies
• config.json -- Password hash and settings

---

Supported File Types

Category	Extensions
Markdown	.md
Text	.txt, .log, .json, .yaml, .yml, .xml, .csv
Code	.js, .ts, .jsx, .tsx, .py, .go, .rs, .java, .rb, .sh, .bash, .c, .cpp, .h, .hpp, .html, .css, .sql, .toml
PDF	.pdf (with text extraction)
Config	.env, .ini, .cfg, .conf

---

Content Ingestion Examples

Obsidian Vault

# Set vault path in .env
OBSIDIAN_VAULT_PATH=~/obsidian-vault

# Or ingest manually
kb ingest ~/obsidian-vault

The vault indexer tracks file hashes for incremental updates -- only changed files get re-indexed.

YouTube Transcripts

# Download transcript
yt-dlp --write-auto-sub --skip-download -o transcript https://youtube.com/watch?v=VIDEO_ID

# Or use the MCP tool directly from your AI agent:
# kb_capture_youtube with URL and transcript text

X/Twitter Bookmarks

# Export bookmarks to markdown using twitter-web-exporter (browser extension)
# Then ingest:
kb ingest ~/bookmarks/x_bookmarks.md

# Or use the built-in capture command:
kb capture-x ~/path/to/x_bookmarks.md

Terminal Sessions

From your AI agent after a debugging session:

Use kb_capture_session to record:
- goal: "Fix authentication flow for email users"
- commands_worked: "docker exec postgres psql query"
- commands_failed: "curl returned 401 - missing jellyfin_user_id"
- root_causes: "Email login path didn't propagate jellyfin_user_id to frontend"
- fixes: "Added jellyfin_user_id to auth response schema"
- lessons: "Always check all auth paths when adding fields to user response"

Bug Fixes

Use kb_capture_fix to record:
- title: "Library page blank for email login users"
- symptom: "Library page shows empty, no media items loaded"
- cause: "jellyfin_user_id not included in email auth response"
- resolution: "Added field to shared auth schema, redeployed"

---

Multi-Agent Setup

Claude Code (MCP -- Native)

kb register    # Writes to ~/.claude.json, ~/.codex/mcp.json, ~/.gemini/mcp.json

All 16 MCP tools become available in Claude Code immediately.

Codex / Other MCP Agents

Point your MCP client at the stdio transport:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": ["/path/to/knowledge-base-server/bin/kb.js", "mcp"]
    }
  }
}

ChatGPT plugin (remote MCP with OAuth)

The HTTP MCP endpoint at https://your-domain.com/mcp signs clients in through OAuth. A ChatGPT plugin only shows its Connect button when the plugin's mcp.json declares that. Without the auth block, ChatGPT treats the server as needing no sign-in, and the server refuses every request.

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "knowledge-base": {
      "type": "streamable-http",
      "url": "https://your-domain.com/mcp",
      "extensions": {
        "com.openai": {
          "auth": {
            "type": "oauth",
            "client": { "mode": "dcr" },
            "baseScopes": ["openid", "offline_access"]
          }
        }
      }
    }
  }
}

• dcr: ChatGPT registers itself as an OAuth client. The package holds no client ID, secret or API key.
• Endpoints are found through discovery (/.well-known/oauth-protected-resource/mcp), so no URL overrides are needed.
• offline_access gets ChatGPT a refresh token. Without it you sign in again every hour.
• Sign in with the account created by kb auth add-user <email>. Public sign-up is off.

ChatGPT Custom GPTs (REST API)

1. Import the OpenAPI spec from https://your-domain.com/openapi.json
2. Set authentication to API Key with header X-API-Key
3. ChatGPT can now search, read, and write to your knowledge base

REST API endpoints at /api/v1/:

• GET /api/v1/search?q=query -- Full-text search
• GET /api/v1/search/smart?q=query -- Semantic search
• GET /api/v1/context?q=query -- Token-efficient briefing
• GET /api/v1/documents -- List documents
• GET /api/v1/documents/:id -- Read document
• POST /api/v1/ingest -- Ingest content
• POST /api/v1/capture/session -- Capture session
• POST /api/v1/capture/fix -- Capture fix
• POST /api/v1/capture/web -- Capture web content

Running Multiple Agents Simultaneously

All agents connect to the same KB server. What Claude learns in one session, Codex and Gemini can access in the next. The KB is the shared brain.

For remote agents, set up API keys in .env:

KB_API_KEY_CLAUDE=your-unique-key-for-claude
KB_API_KEY_OPENAI=your-unique-key-for-openai
KB_API_KEY_GEMINI=your-unique-key-for-gemini

---

Agentic Installation

This repo is designed to be set up BY AI agents, not just for them.

1. User clones the repo
2. User tells their AI: "Read llms.txt and EXTENDING.md, then set this up for me"
3. Agent reads llms.txt (30 seconds to understand the full system)
4. Agent reads EXTENDING.md (deep customization guide written FOR agents)
5. Agent runs kb setup --auto with appropriate flags for the user's environment
6. Done. Every deployment is unique -- security by customization.

The wizard detects your OS, available AI tools, Obsidian vault location, and preferred deployment method. It generates a custom .env, registers MCP, installs the service, and runs the first ingest.

For the non-technical user: kb setup and answer 5 questions. For the programmer: Everything is in .env and composable. Override anything. For the AI agent: kb setup --auto with flags. Zero prompts.

---

The Self-Learning Workflow

This repo includes templates for the self-learning development methodology:

docs/workflow/
  CLAUDE.md.template     -- Operating contract for Claude Code
  AGENTS.md.template     -- Cross-agent rules (Claude, Codex, Gemini)
  SELF-LEARNING.md       -- The full methodology: three-tier memory,
                            intelligence pipeline, compounding loop,
                            multi-agent self-learning, Obsidian integration

Copy these templates to your project root and customize them. They define:

• How agents should search the KB before starting work
• When and how to capture session findings
• The self-learning loop that compounds intelligence
• Multi-agent coordination rules
• Verification standards

These are the actual development patterns used to build this system. Open sourced so you can adopt the same workflow.

---

Environment Variables

Variable	Required	Default	Description
KB_PASSWORD	Yes (first run)	--	Dashboard login password
KB_PORT	No	3838	HTTP server port
OBSIDIAN_VAULT_PATH	No	--	Obsidian vault path for sync
KB_API_KEY_CLAUDE	No	--	API key for Claude remote access
KB_API_KEY_OPENAI	No	--	API key for OpenAI/ChatGPT access
KB_API_KEY_GEMINI	No	--	API key for Gemini access
KB_API_KEY_SWARM	No	--	API key for agent-swarm to write to the mistake ledger
KB_MISTAKES_HOME	No	~/.knowledge-base/mistakes	Folder for the mistake ledger files
KB_PATTERN_MODEL	No	claude-sonnet-5-5	Model for kb patterns draft
BETTER_AUTH_SECRET	No	--	OAuth token signing secret
BETTER_AUTH_URL	No	--	OAuth issuer URL for remote access
CLASSIFY_MODEL	No	claude-haiku-4-5-20251001	Model for AI classification

---

systemd Service

For production deployment with auto-restart:

sudo cp kb-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable kb-server
sudo systemctl start kb-server

Or use the setup wizard: kb setup and select "systemd" as the deployment mode.

The service restarts automatically on failure with a 5-second delay. Logs via journalctl -u kb-server -f.

---