Skip to content
Back to search

knowledge-base-server

Make every AI agent you use smarter. Persistent memory with SQLite FTS5, MCP server, Obsidian sync, and self-learning intelligence pipeline.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/willynikes2--knowledge-base-server/badge.svg)](/listings/willynikes2--knowledge-base-server)

HTML

<a href="/listings/willynikes2--knowledge-base-server"><img src="/api/listings/willynikes2--knowledge-base-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 654 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # knowledge-base-server
  2. [![CI](https://github.com/willynikes2/knowledge-base-server/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/willynikes2/knowledge-base-server/actions/workflows/ci.yml)
  3. [![CodeQL](https://github.com/willynikes2/knowledge-base-server/actions/workflows/codeql.yml/badge.svg?branch=master)](https://github.com/willynikes2/knowledge-base-server/actions/workflows/codeql.yml)
  4. **Make every AI agent you use smarter.**
  5. 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.
  6. 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.
  7. ---
  8. ## The Problem
  9. AI agents are stateless. Every session starts from zero. You end up:
  10. - Copy-pasting context between sessions
  11. - Re-explaining your codebase, architecture, and preferences
  12. - Watching agents hallucinate because they lack YOUR information
  13. - Losing debugging insights that took hours to discover
  14. - Running multiple agents that can't share what they know
  15. The smarter the model, the more painful the amnesia. Context is the bottleneck, not intelligence.
  16. ## The Solution
  17. 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.
  18. **Your AI gets smarter every day. Every session builds on the last.**
  19. ```
  20. Obsidian Vault ------+
  21. Code Repos ----------+
  22. YouTube Transcripts --+---> [ KB Server ] ---> SQLite + FTS5 ---> [ MCP ] ---> Claude Code
  23. X/Twitter Bookmarks -+ | | Codex CLI
  24. Web Clippings -------+ Port 3838 Embeddings [ REST ] --> Gemini CLI
  25. Terminal Sessions ----+ Web Dashboard Semantic Search ChatGPT
  26. Bug Fix Captures -----+ Any MCP Client
  27. ```
  28. **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.
  29. ---
  30. ## How It Works: The Intelligence Pipeline
  31. This is the core differentiator. Raw information flows through seven layers to become actionable intelligence:
  32. ### 1. Capture Layer
  33. Ingest from everywhere:
  34. - **Obsidian vault** -- bidirectional sync, auto-indexes on changes
  35. - **YouTube transcripts** -- via yt-dlp or `kb_capture_youtube`
  36. - **X/Twitter bookmarks** -- browser export to markdown, auto-ingest
  37. - **Web articles** -- Obsidian Web Clipper or `kb_capture_web`
  38. - **Terminal sessions** -- `kb_capture_session` records what worked, failed, and why
  39. - **Bug fixes** -- `kb_capture_fix` records symptom, cause, and resolution
  40. - **Code, PDFs, text** -- 20+ file types with automatic type detection
  41. Every source enters the system as a raw capture, ready for processing.
  42. ### 2. Classification Layer
  43. The `kb_classify` tool runs AI classification on unprocessed content:
  44. - Assigns document type (research, idea, workflow, lesson, fix, decision, session)
  45. - Auto-generates tags and project routing
  46. - Writes structured summaries and key topics
  47. - Adds confidence scoring
  48. - Enforces frontmatter discipline on every note
  49. Raw clippings become structured, searchable knowledge automatically.
  50. ### 3. Promotion Pipeline
  51. Raw captures get refined into higher-value knowledge artifacts:
  52. - **Captures** in inbox get normalized into **sources**
  53. - Sources get promoted to **insights**, **lessons**, **decisions**, **runbooks**
  54. - The `kb_promote` tool extracts structured knowledge from raw material
  55. - Higher-value knowledge ranks higher in retrieval
  56. - The system distinguishes signal from noise automatically
  57. ### 4. Synthesis Layer
  58. The `kb_synthesize` tool connects dots across sources:
  59. - Reads recent notes across all types and projects
  60. - Identifies recurring themes, patterns, and bottlenecks
  61. - Surfaces opportunities and workflow improvements
  62. - Generates cross-cutting insights that no single source contains
  63. - This is where raw information becomes actionable intelligence
  64. ### 5. Three-Tier Memory (Cold / Warm / Hot)
  65. Not all knowledge is equal. The system uses three tiers to prevent context pollution:
  66. | Tier | What Lives Here | When Retrieved | Example |
  67. |------|----------------|----------------|---------|
  68. | **Hot** | Active project context, recent sessions, current decisions | First, always | "How did we fix auth yesterday?" |
  69. | **Warm** | Accumulated lessons, research, validated workflows | When relevant to query | "What's our Docker networking pattern?" |
  70. | **Cold** | Raw captures, archived sources, old terminal logs | Only when deep-diving | "What did that YouTube video say about caching?" |
  71. **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.
  72. ### 6. Token-Optimized Retrieval
  73. Every token costs money and context window space. The retrieval system minimizes waste:
  74. - `kb_context` returns summaries and metadata WITHOUT full content -- **90%+ token savings**
  75. - `kb_search` uses FTS5 with BM25 ranking, title boosting, and AND-first precision
  76. - `kb_search_smart` combines keyword and semantic search for conceptual queries
  77. - `kb_read` loads full content only when needed, after context identifies relevant docs
  78. - Agents get the right information in the fewest possible tokens
  79. ### 7. The Self-Learning Loop
  80. This is the core innovation. The system compounds intelligence over time:
  81. ```
  82. Sessions 1-10: AI makes mistakes. You correct. Fixes get captured.
  83. Sessions 10-50: AI recognizes patterns. Starts getting things right more often.
  84. Sessions 50-100: AI knows your codebase, preferences, architecture patterns.
  85. Sessions 100+: One-shot clean code. Accumulated context covers everything.
  86. ```
  87. The loop in detail:
  88. 1. AI agent attempts a task
  89. 2. Output gets evaluated (human judgment -- the irreplaceable element)
  90. 3. Corrections and findings get captured (`kb_capture_session`, `kb_capture_fix`)
  91. 4. KB server ingests the session data
  92. 5. `kb_synthesize` organizes and connects to existing knowledge
  93. 6. Agent instructions auto-update with lessons learned
  94. 7. Next session starts with better context
  95. 8. Repeat -- compounding improvement
  96. **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.
  97. ---
  98. ## Features
  99. **Core**
  100. - SQLite FTS5 full-text search with BM25 ranking and highlighted snippets
  101. - Semantic/vector search via local HuggingFace embeddings (Xenova/all-MiniLM-L6-v2) — no API keys needed
  102. - Hybrid search mode (`kb_search_smart`) combining keyword + semantic for conceptual queries
  103. - Web dashboard for browsing, searching, and managing documents
  104. - CLI for all operations (`kb start`, `kb search`, `kb ingest`, `kb setup`)
  105. - One-command MCP registration (`kb register`)
  106. - Interactive setup wizard (`kb setup`) with agent-compatible auto mode
  107. **Ingestion**
  108. - 20+ file types: Markdown, text, code, PDFs, JSON, YAML, XML, CSV
  109. - Auto-ingest on first run (~/knowledgebase + Claude memory directories)
  110. - Duplicate detection via content hashing
  111. - Obsidian vault bidirectional sync with incremental indexing
  112. - YouTube transcript capture
  113. - X/Twitter bookmark ingestion
  114. - Web article capture with metadata
  115. **Intelligence**
  116. - AI auto-classification (type, tags, summary, key topics, confidence)
  117. - Knowledge promotion pipeline (raw -> structured)
  118. - Cross-source synthesis (themes, patterns, opportunities)
  119. - Three-tier memory (cold/warm/hot) with tier-aware retrieval
  120. - Token-optimized context briefings (90%+ savings over full reads)
  121. - Session and fix capture for operational learning
  122. - Safety review for destructive actions (multi-model consensus)
  123. **Integration**
  124. - MCP server (stdio for local, StreamableHTTP for remote)
  125. - REST API with OpenAPI 3.1 specification
  126. - ChatGPT Custom GPT Actions via OpenAPI import
  127. - OAuth 2.1 with OIDC discovery for remote access
  128. - API key authentication for scripts and automation
  129. - systemd service with auto-restart for production deployment
  130. **Security**
  131. - bcrypt password hashing with HttpOnly session cookies
  132. - Dual auth: API keys (fast path) + OAuth 2.1 Bearer tokens (signed JWTs bound to the MCP resource)
  133. - No self-registration: OAuth accounts are created by the operator with `kb auth add-user`
  134. - Three separate API keys for Claude, OpenAI, and Gemini
  135. - Safety review tool checks KB history before destructive actions
  136. - No external dependencies for core functionality
  137. ---
  138. ## Quickstart
  139. ### Prerequisites
  140. - Node.js >= 18.0.0
  141. - That's it. No external databases, no Docker required, no cloud dependencies.
  142. ### Install
  143. ```bash
  144. git clone https://github.com/willynikes2/knowledge-base-server.git
  145. cd knowledge-base-server
  146. npm install
  147. npm link
  148. ```
  149. ### First Run (Interactive Setup Wizard)
  150. ```bash
  151. kb setup
  152. ```
  153. The wizard detects your environment, asks which AI agents you use, configures everything, and runs your first ingest. Takes about 60 seconds.
  154. For agent-driven installation (no prompts):
  155. ```bash
  156. kb setup --auto --password=yourpass --vault=~/obsidian-vault --agents=claude,codex --deploy=systemd
  157. ```
  158. ### Manual Setup
  159. ```bash
  160. KB_PASSWORD=yourpassword kb start # Start server on port 3838
  161. kb register # Register MCP with Claude, Codex, and Gemini
  162. kb register --agents=claude,codex # Register only a subset
  163. kb ingest ~/obsidian-vault # Ingest your knowledge
  164. kb search "docker networking" # Search from terminal
  165. kb status # Check stats
  166. ```
  167. ### Connect to Local Agents
  168. 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:
  169. ```
  170. > Search the knowledge base for recent bug fixes
  171. ```
  172. Your agent will use `kb_search` and return results from your accumulated knowledge.
  173. ---
  174. ## Don't Want to Self-Host? Use Memstalker
  175. **[Memstalker](https://memstalker.com)** is the hosted version of knowledge-base-server. Same engine, zero infrastructure.
  176. | | Self-Hosted (Free) | Memstalker Hosted |
  177. |---|---|---|
  178. | **Cost** | Free forever | From $12/mo |
  179. | **Setup** | Clone, install, configure | Sign up, connect your agents |
  180. | **Infrastructure** | You run the VPS | We handle everything |
  181. | **Updates** | `git pull` | Automatic |
  182. | **Multi-device sync** | You configure | Built-in |
  183. | **Backups** | You manage | Automatic |
  184. | **All 16 MCP tools** | Yes | Yes |
  185. | **Obsidian integration** | Yes | Yes |
  186. | **REST API + ChatGPT** | Yes | Yes |
  187. **Self-host if:** You want full control, have a VPS, and enjoy running your own infrastructure.
  188. **Use Memstalker if:** You want persistent AI memory without managing servers. Connect your agents in minutes.
  189. First 500 early adopters get Pro at $12/mo forever (normally $25): [memstalker.com](https://memstalker.com)
  190. ---
  191. ## MCP Tools
  192. ### Core tools (stdio + HTTP)
  193. All 16 core tools are available via both stdio and HTTP:
  194. | Tool | Description |
  195. |------|-------------|
  196. | `kb_search` | Full-text search with BM25 ranking and highlighted snippets |
  197. | `kb_search_smart` | Hybrid keyword + semantic search for conceptual queries |
  198. | `kb_context` | Token-efficient briefing -- summaries only, 90%+ savings. Use BEFORE kb_read |
  199. | `kb_read` | Read full document content by ID |
  200. | `kb_list` | List documents filtered by type or tag |
  201. | `kb_write` | Write a new note to the Obsidian vault |
  202. | `kb_ingest` | Ingest raw text directly into the database |
  203. | `kb_classify` | Auto-classify unprocessed notes (type, tags, summary) |
  204. | `kb_promote` | Promote raw source into structured knowledge |
  205. | `kb_synthesize` | Generate cross-source synthesis connecting recent knowledge |
  206. | `kb_capture_session` | Record a debugging/coding session with findings |
  207. | `kb_capture_fix` | Record a bug fix with symptom, cause, resolution |
  208. | `kb_capture_web` | Capture a web article with content and metadata |
  209. | `kb_capture_youtube` | Capture a YouTube transcript with metadata |
  210. | `kb_vault_status` | Show vault indexing stats by type and project |
  211. | `kb_safety_check` | Review a destructive action against KB history |
  212. ### Local-only bus tools (stdio only)
  213. The stdio MCP server also exposes a lightweight append-only message bus for cross-model coordination:
  214. | Tool | Description |
  215. |------|-------------|
  216. | `bus_send` | Send a markdown message to a local channel |
  217. | `bus_inbox` | Read messages newer than a cursor |
  218. | `bus_wait` | Long-poll until a new message arrives or timeout elapses |
  219. Resource template: `bus://{channel}`
  220. Shell shims:
  221. ```bash
  222. bus-send ticket:PF-1884 "report ready" --sender codex --kind result
  223. bus-inbox ticket:PF-1884 --since 0
  224. bus-wait ticket:PF-1884 --since 12 --timeout-ms 30000
  225. ```
  226. See [docs/message-bus.md](docs/message-bus.md) for channel conventions and cross-model usage.
  227. ### Mistake ledger tools (local stdio only)
  228. | Tool | Description |
  229. |------|-------------|
  230. | `kb_mistake_record` | Record a mistake a reviewer or test caught, with its fix |
  231. | `kb_patterns_for` | Get up to 3 approved "known pitfalls" that match a task |
  232. See [docs/mistake-ledger.md](docs/mistake-ledger.md).
  233. ---
  234. ## CLI Commands
  235. ```
  236. kb setup Interactive setup wizard (--auto for agent mode)
  237. kb start Start the dashboard + API server (default :3838)
  238. kb stop Stop the running server
  239. kb mcp Start MCP stdio server (used by AI tools)
  240. kb register Register MCP server with Claude Code
  241. kb ingest <path> Ingest a file or directory
  242. kb search <query> Search documents from terminal
  243. kb status Show stats and server status
  244. kb classify Auto-classify unprocessed vault notes
  245. kb summarize Generate AI summaries for unsummarized notes
  246. kb capture-x Ingest X/Twitter bookmarks from export
  247. kb safety-check Review a planned action against KB history
  248. kb mistakes Mistake ledger: import-sdd, import-seed, record, record-run, list, stats
  249. kb patterns Patterns from repeated mistakes: draft, list, page, set-status
  250. ```
  251. ---
  252. ## Architecture
  253. ```
  254. +------------------+
  255. | AI Agents |
  256. | Claude | Codex |
  257. | Gemini | ChatGPT |
  258. +--------+---------+
  259. |
  260. MCP (stdio) | REST API (/api/v1/)
  261. MCP (HTTP) | OpenAPI 3.1
  262. |
  263. +--------+---------+
  264. | KB Server |
  265. | Express :3838 |
  266. +--------+---------+
  267. |
  268. +-------------------+-------------------+
  269. | | |
  270. +--------+-------+ +-------+--------+ +-------+--------+
  271. | SQLite + FTS5 | | Embeddings | | Obsidian |
  272. | documents | | all-MiniLM | | Vault Sync |
  273. | vault_files | | L6-v2 local | | (bidirectional)|
  274. | embeddings | | cosine sim | | source of truth|
  275. +----------------+ +----------------+ +----------------+
  276. ```
  277. Data directory: `~/.knowledge-base/`
  278. - `kb.db` -- SQLite database with FTS5 index
  279. - `files/` -- Ingested file copies
  280. - `config.json` -- Password hash and settings
  281. ---
  282. ## Supported File Types
  283. | Category | Extensions |
  284. |----------|-----------|
  285. | Markdown | .md |
  286. | Text | .txt, .log, .json, .yaml, .yml, .xml, .csv |
  287. | Code | .js, .ts, .jsx, .tsx, .py, .go, .rs, .java, .rb, .sh, .bash, .c, .cpp, .h, .hpp, .html, .css, .sql, .toml |
  288. | PDF | .pdf (with text extraction) |
  289. | Config | .env, .ini, .cfg, .conf |
  290. ---
  291. ## Content Ingestion Examples
  292. ### Obsidian Vault
  293. ```bash
  294. # Set vault path in .env
  295. OBSIDIAN_VAULT_PATH=~/obsidian-vault
  296. # Or ingest manually
  297. kb ingest ~/obsidian-vault
  298. ```
  299. The vault indexer tracks file hashes for incremental updates -- only changed files get re-indexed.
  300. ### YouTube Transcripts
  301. ```bash
  302. # Download transcript
  303. yt-dlp --write-auto-sub --skip-download -o transcript https://youtube.com/watch?v=VIDEO_ID
  304. # Or use the MCP tool directly from your AI agent:
  305. # kb_capture_youtube with URL and transcript text
  306. ```
  307. ### X/Twitter Bookmarks
  308. ```bash
  309. # Export bookmarks to markdown using twitter-web-exporter (browser extension)
  310. # Then ingest:
  311. kb ingest ~/bookmarks/x_bookmarks.md
  312. # Or use the built-in capture command:
  313. kb capture-x ~/path/to/x_bookmarks.md
  314. ```
  315. ### Terminal Sessions
  316. From your AI agent after a debugging session:
  317. ```
  318. Use kb_capture_session to record:
  319. - goal: "Fix authentication flow for email users"
  320. - commands_worked: "docker exec postgres psql query"
  321. - commands_failed: "curl returned 401 - missing jellyfin_user_id"
  322. - root_causes: "Email login path didn't propagate jellyfin_user_id to frontend"
  323. - fixes: "Added jellyfin_user_id to auth response schema"
  324. - lessons: "Always check all auth paths when adding fields to user response"
  325. ```
  326. ### Bug Fixes
  327. ```
  328. Use kb_capture_fix to record:
  329. - title: "Library page blank for email login users"
  330. - symptom: "Library page shows empty, no media items loaded"
  331. - cause: "jellyfin_user_id not included in email auth response"
  332. - resolution: "Added field to shared auth schema, redeployed"
  333. ```
  334. ---
  335. ## Multi-Agent Setup
  336. ### Claude Code (MCP -- Native)
  337. ```bash
  338. kb register # Writes to ~/.claude.json, ~/.codex/mcp.json, ~/.gemini/mcp.json
  339. ```
  340. All 16 MCP tools become available in Claude Code immediately.
  341. ### Codex / Other MCP Agents
  342. Point your MCP client at the stdio transport:
  343. ```json
  344. {
  345. "mcpServers": {
  346. "knowledge-base": {
  347. "command": "node",
  348. "args": ["/path/to/knowledge-base-server/bin/kb.js", "mcp"]
  349. }
  350. }
  351. }
  352. ```
  353. ### ChatGPT plugin (remote MCP with OAuth)
  354. 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.
  355. ```json
  356. {
  357. "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  358. "mcpServers": {
  359. "knowledge-base": {
  360. "type": "streamable-http",
  361. "url": "https://your-domain.com/mcp",
  362. "extensions": {
  363. "com.openai": {
  364. "auth": {
  365. "type": "oauth",
  366. "client": { "mode": "dcr" },
  367. "baseScopes": ["openid", "offline_access"]
  368. }
  369. }
  370. }
  371. }
  372. }
  373. }
  374. ```
  375. - `dcr`: ChatGPT registers itself as an OAuth client. The package holds no client ID, secret or API key.
  376. - Endpoints are found through discovery (`/.well-known/oauth-protected-resource/mcp`), so no URL overrides are needed.
  377. - `offline_access` gets ChatGPT a refresh token. Without it you sign in again every hour.
  378. - Sign in with the account created by `kb auth add-user <email>`. Public sign-up is off.
  379. ### ChatGPT Custom GPTs (REST API)
  380. 1. Import the OpenAPI spec from `https://your-domain.com/openapi.json`
  381. 2. Set authentication to API Key with header `X-API-Key`
  382. 3. ChatGPT can now search, read, and write to your knowledge base
  383. REST API endpoints at `/api/v1/`:
  384. - `GET /api/v1/search?q=query` -- Full-text search
  385. - `GET /api/v1/search/smart?q=query` -- Semantic search
  386. - `GET /api/v1/context?q=query` -- Token-efficient briefing
  387. - `GET /api/v1/documents` -- List documents
  388. - `GET /api/v1/documents/:id` -- Read document
  389. - `POST /api/v1/ingest` -- Ingest content
  390. - `POST /api/v1/capture/session` -- Capture session
  391. - `POST /api/v1/capture/fix` -- Capture fix
  392. - `POST /api/v1/capture/web` -- Capture web content
  393. ### Running Multiple Agents Simultaneously
  394. 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.
  395. For remote agents, set up API keys in `.env`:
  396. ```bash
  397. KB_API_KEY_CLAUDE=your-unique-key-for-claude
  398. KB_API_KEY_OPENAI=your-unique-key-for-openai
  399. KB_API_KEY_GEMINI=your-unique-key-for-gemini
  400. ```
  401. ---
  402. ## Agentic Installation
  403. This repo is designed to be set up BY AI agents, not just for them.
  404. 1. User clones the repo
  405. 2. User tells their AI: "Read llms.txt and EXTENDING.md, then set this up for me"
  406. 3. Agent reads `llms.txt` (30 seconds to understand the full system)
  407. 4. Agent reads `EXTENDING.md` (deep customization guide written FOR agents)
  408. 5. Agent runs `kb setup --auto` with appropriate flags for the user's environment
  409. 6. Done. Every deployment is unique -- security by customization.
  410. 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.
  411. **For the non-technical user:** `kb setup` and answer 5 questions.
  412. **For the programmer:** Everything is in `.env` and composable. Override anything.
  413. **For the AI agent:** `kb setup --auto` with flags. Zero prompts.
  414. ---
  415. ## The Self-Learning Workflow
  416. This repo includes templates for the self-learning development methodology:
  417. ```
  418. docs/workflow/
  419. CLAUDE.md.template -- Operating contract for Claude Code
  420. AGENTS.md.template -- Cross-agent rules (Claude, Codex, Gemini)
  421. SELF-LEARNING.md -- The full methodology: three-tier memory,
  422. intelligence pipeline, compounding loop,
  423. multi-agent self-learning, Obsidian integration
  424. ```
  425. Copy these templates to your project root and customize them. They define:
  426. - How agents should search the KB before starting work
  427. - When and how to capture session findings
  428. - The self-learning loop that compounds intelligence
  429. - Multi-agent coordination rules
  430. - Verification standards
  431. These are the actual development patterns used to build this system. Open sourced so you can adopt the same workflow.
  432. ---
  433. ## Environment Variables
  434. | Variable | Required | Default | Description |
  435. |----------|----------|---------|-------------|
  436. | `KB_PASSWORD` | Yes (first run) | -- | Dashboard login password |
  437. | `KB_PORT` | No | 3838 | HTTP server port |
  438. | `OBSIDIAN_VAULT_PATH` | No | -- | Obsidian vault path for sync |
  439. | `KB_API_KEY_CLAUDE` | No | -- | API key for Claude remote access |
  440. | `KB_API_KEY_OPENAI` | No | -- | API key for OpenAI/ChatGPT access |
  441. | `KB_API_KEY_GEMINI` | No | -- | API key for Gemini access |
  442. | `KB_API_KEY_SWARM` | No | -- | API key for agent-swarm to write to the mistake ledger |
  443. | `KB_MISTAKES_HOME` | No | ~/.knowledge-base/mistakes | Folder for the mistake ledger files |
  444. | `KB_PATTERN_MODEL` | No | claude-sonnet-5-5 | Model for `kb patterns draft` |
  445. | `BETTER_AUTH_SECRET` | No | -- | OAuth token signing secret |
  446. | `BETTER_AUTH_URL` | No | -- | OAuth issuer URL for remote access |
  447. | `CLASSIFY_MODEL` | No | claude-haiku-4-5-20251001 | Model for AI classification |
  448. ---
  449. ## systemd Service
  450. For production deployment with auto-restart:
  451. ```bash
  452. sudo cp kb-server.service /etc/systemd/system/
  453. sudo systemctl daemon-reload
  454. sudo systemctl enable kb-server
  455. sudo systemctl start kb-server
  456. ```
  457. Or use the setup wizard: `kb setup` and select "systemd" as the deployment mode.
  458. The service restarts automatically on failure with a 5-second delay. Logs via `journalctl -u kb-server -f`.
  459. ---
  460. ## Why This Exists
  461. I built this because I run three AI agents (Claude, Codex, Gemini) across multiple projects. Without shared context, each agent starts from zero every session. I was copy-pasting context, re-explaining architecture, and losing debugging insights that took hours to discover.
  462. With the KB server, all three agents share the same brain. Claude captures a bug fix at 2am, Codex finds it the next morning. Gemini reviews code with full project history. The system gets smarter every day -- not because the models improve, but because the context they receive compounds.
  463. The cost model: $60/month total for three agents via CLI subscription wrapping (not per-token API billing). The KB server runs on a $5/month VPS alongside everything else. The ROI is measured in hours of context re-discovery that never need to happen again.
  464. AI is only as good as its context. This is the context layer.
  465. ---
  466. ## Roadmap
  467. - [ ] Watch mode for auto-ingesting new vault files in real-time
  468. - [ ] Multi-user support with role-based access
  469. - [x] Hosted SaaS version -- **[memstalker.com](https://memstalker.com)** (self-hosted remains free and full-featured)
  470. - [ ] Plugin system for custom ingestion sources
  471. - [ ] Ollama integration for fully local AI classification
  472. - [ ] WebSocket real-time updates on the dashboard
  473. - [ ] Export/import for knowledge base migration
  474. ---
  475. ## License
  476. MIT -- see [LICENSE](LICENSE)
  477. ---
  478. ## Author
  479. Built by [Shawn Daniel](https://github.com/willynikes2) with significant contributions from Claude, Codex, and Gemini -- the first three users of the system they helped build.
  480. "You gotta 100-shot 10 apps before you can 1-shot 10 apps."

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.