Skip to content
Conduit

skill

knosi

Turn your Claude tokens into a second brain you actually own.

zhousiyao03-cyber/knosicommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/zhousiyao03-cyber/knosi itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 23, 2026

Knosi

Next.js React Tailwind CSS License: AGPL-3.0 PRs Welcome

Turn your Claude tokens into a second brain you actually own.

Your Claude Max runs out. Your notes don't.

Every great insight you pull out of a Claude conversation disappears into the void the moment you close the tab. Knosi closes that loop — it's a self-hosted knowledge platform built for developers who live in AI tools and want a permanent, searchable home for what they learn.

Write notes with a Notion-level editor, index your knowledge with hybrid RAG, and ask questions against your own corpus. Route "Ask AI" through your existing Claude subscription instead of burning extra API credits. Own your data, run it locally, or self-host it with Docker Compose on your own server.

Product: knosi.xyz

Features

Core Knowledge

  • Rich Text Editor — Notion-style block editor powered by Tiptap v3. Code blocks with language selector, Mermaid diagrams, Excalidraw whiteboards, callouts, toggles, tables with toolbar, side-by-side image rows, TOC block and collapsible sidebar, drag-and-drop sorting, slash commands, search & replace, and mixed Markdown paste.
  • Notes — Full-width cover images, type/tag metadata, hover-to-insert controls, block-level move/copy/delete/transform, auto-save with loss prevention, public read-only sharing links, and one-click daily journal with plan inheritance.
  • Learning Notebooks — Topic-oriented study sessions with AI-generated outlines, blind-spot analysis, review question generation, and Ask AI scoped to the topic's note context.
  • Curriculum Map — /learn/map knowledge gap analysis across target roles (AI Engineer, Backend Architect). ~240 seeded topics with 4-state mastery (blank/heard/learning/mastered). Auto-links existing learning and general notes by string matching; click a topic to open a side panel with mastery toggle, linked notes (with source badges + bulk unlink), AI description generation, inline rename/delete, and quick "Create new note". Editable in-place: add new tracks/areas/topics. Note editors (both kinds) surface curriculum tags inline; deep-link from a tag jumps back to the map and locates the topic.
  • Knowledge Audit — /learn/audit runs an LLM gap analysis on a chosen track, producing strengths / weak areas / missing must-knows / next steps. Past audits stored for comparison. Embedded 90-day mastery progress chart shows mastered/learning/heard counts over time.
  • OSS Project Notes — Per-project note collections with repo metadata, tag filtering, per-note read-only links, and long-term analysis archiving.

AI

  • Ask AI — Chunk-level hybrid RAG: semantic retrieval + keyword recall + adjacent-paragraph expansion + clickable source citations. Falls back gracefully to keyword-only when no embedding provider is configured.
  • Claude Code Daemon — Route Ask AI through your local Claude Pro/Max subscription. No extra API spend. Works against both local dev and the self-hosted web deployment, with Redis-backed live token fan-out plus Redis/SSE wakeups so the daemon no longer has to idle-poll claims aggressively.
  • Structured AI Calls — Learning outline generation, OSS analysis, and portfolio news summarization use the configured provider independently of the chat daemon.
  • Claude Capture Integrations — Claude Web can connect through a remote MCP endpoint, and Claude Code can save explicit conversation excerpts through the Knosi CLI + personal skill flow. Both write raw captures into AI Inbox.

Developer Workflow

  • Token Usage Dashboard — Auto-reads local Claude Code session files (~/.claude/projects/) and Codex state databases (~/.codex/state*.sqlite). Aggregates across all workspaces and subagents. Manual entry supported for OpenAI API and other sources.
  • Focus Tracker — Server-side ingestion and /focus web UI for app-level time tracking. Pairs with the desktop Tauri collector — ⬇️ download the macOS app (Apple Silicon), then sign in with your Knosi account.
  • Installable PWA — Ships a standalone web app manifest with dedicated 192x192, 512x512, and Apple touch icons that work on the self-hosted Hetzner deployment.

Optional Modules

  • Portfolio Tracker — Position management with Yahoo Finance and CoinGecko real-time prices, AI position analysis, and news aggregation via Marketaux or Google News RSS with server-side cron auto-refresh.
  • Speak — /speak shadow-drill module. One native English sentence at a time, browser TTS plays it, you shadow it, press Next. Per-sentence lifetime practice count synced across devices. Ships with 30 hand-picked working-professional sentences.
  • Words — /words per-word pronunciation drill. Each card shows stress visualization, IPA, brief Chinese meaning, and a native example sentence. 100 hand-picked seeds. Add your own words; AI enriches them on save. Browser TTS reused from /speak.
  • Search — Cmd+K global note search with keyword highlighting.
  • Dark Mode — Global toggle, full dark mode coverage.

Hosted vs Self-Hosted

Knosi is AGPL-3.0 and fully self-hostable for free — every feature, no feature gating, no telemetry. The hosted service at knosi.xyz offers a paid Pro tier ($9/mo or $90/yr) with included Knosi AI (no API key needed), 80 Ask AI calls per day, unlimited notes, 10 GB image storage, and access to the Portfolio, Focus, OSS Projects, and Claude Capture modules. See /pricing for the full plan comparison. Self-hosted deployments stay unaffected by the hosted tier — what's free is free forever.

Quick Start

Option A: Docker (recommended for self-hosting)

git clone https://github.com/zhousiyao03-cyber/knosi.git
cd knosi

# Start with default settings (SQLite, email/password login)
docker compose up -d

# → http://localhost:3000

Data is persisted in a Docker volume. To customize, create a .env file:

# Generate a secure auth secret
echo "AUTH_SECRET=$(openssl rand -base64 32)" > .env

# Optional: add GitHub/Google OAuth
echo "AUTH_GITHUB_ID=your-id" >> .env
echo "AUTH_GITHUB_SECRET=your-secret" >> .env

Then restart: docker compose up -d --build

Option B: Local development

# 1. Clone
git clone https://github.com/zhousiyao03-cyber/knosi.git
cd knosi

# 2. Install dependencies (npm works; pnpm also supported)
npm install

# 3. Configure environment
cp .env.example .env.local
# Edit .env.local — see "Environment Variables" below

# 4. Initialize the database
npm run db:push

# 5. Start the dev server
npm run dev
# → http://localhost:3200

In development mode, a test account is automatically provisioned for quick access:

Email:    test@secondbrain.local
Password: test123456

This account is only created when NODE_ENV=development and has no effect in production.

Option C: Hetzner single-server deployment

The repository now includes a production-oriented Docker Compose stack for a single Ubuntu server:

Recommended first migration cut:

  1. Keep TURSO_DATABASE_URL pointed at Turso.
  2. Configure S3-compatible object storage for note image uploads.
  3. Move app hosting, reverse proxy, Redis, and cron to your own server first.

Example flow on a fresh Ubuntu host:

ssh root@your-server
git clone https://github.com/zhousiyao03-cyber/knosi.git /srv/knosi
cd /srv/knosi

bash ops/hetzner/bootstrap.sh 4
cp .env.production.example .env.production
# edit .env.production

# APP_DOMAIN=www.knosi.xyz
# ROOT_DOMAIN=knosi.xyz
# ACME_EMAIL=you@example.com

docker compose -f docker-compose.prod.yml up -d --build

Then install the cron entries:

crontab -e
# paste ops/hetzner/knosi.cron.example and fill in the secrets

The cron example now includes the host snapshot collector. That script writes /srv/knosi/runtime/ops-snapshot.json, which the app mounts read-only at /app/runtime/ops-snapshot.json for the owner-only /settings/ops dashboard.

Automatic deployments:

  1. Add these repository secrets in GitHub:
    • HETZNER_HOST — your server IP or hostname
    • HETZNER_USER — the SSH user that owns the deployment
    • HETZNER_SSH_KEY — the private key for that SSH user
    • HETZNER_SSH_PORT — optional, defaults to 22
    • If you followed the current Hetzner bootstrap flow exactly, the live server currently uses root for deployments, so HETZNER_USER=root is the drop-in value until you introduce a dedicated deploy user.
  2. Push to main.
  3. GitHub Actions will lint, rsync the repository to /srv/knosi, then run ops/hetzner/deploy.sh on the server.

The deployment script validates docker-compose.prod.yml, generates a unique NEXT_DEPLOYMENT_ID for every rollout, rebuilds the knosi image, restarts redis + knosi + caddy, and waits for http://127.0.0.1:3000/login to return 200.

Environment Variables

Copy .env.example to .env.local and fill in the values you need.

Required (minimum to run locally)

# SQLite file for local dev — no auth token needed
TURSO_DATABASE_URL=file:data/second-brain.db

# Auth.js secret — generate with: openssl rand -base64 32
AUTH_SECRET=your-auth-secret

Authentication (OAuth)

# GitHub OAuth App
AUTH_GITHUB_ID=your-github-oauth-app-id
AUTH_GITHUB_SECRET=your-github-oauth-app-secret

# Google OAuth Client
AUTH_GOOGLE_ID=your-google-oauth-client-id
AUTH_GOOGLE_SECRET=your-google-oauth-client-secret

Production Database (Turso)

TURSO_DATABASE_URL=libsql://your-db-name-your-org.turso.io
TURSO_AUTH_TOKEN=your-turso-auth-token

Production Self-Hosting

APP_DOMAIN=knosi.example.com
ACME_EMAIL=ops@example.com
AUTH_URL=https://knosi.example.com
AUTH_TRUST_HOST=true
CRON_SECRET=your-random-secret
JOBS_TICK_TOKEN=your-random-secret
OPS_OWNER_EMAIL=you@example.com

If you enable GitHub or Google login on a self-hosted deployment, set AUTH_URL to the public HTTPS origin served by your reverse proxy. OAuth providers validate the callback URL against that origin, so relying on the container's internal HOSTNAME=0.0.0.0 will produce redirect_uri_mismatch errors.

Set OPS_OWNER_EMAIL to the single account that should be allowed to open /settings/ops. The page is read-only and only renders for that owner; other authenticated users receive a 404. The System card in /settings/ops reports memory using the same Linux semantics as free -h: Memory matches the host's used column, while Available, Cache, and Swap are shown separately so you can tell reclaimable cache from real headroom.

Image uploads on self-hosted deployments use S3-compatible object storage:

S3_ENDPOINT=https://s3.example.com
S3_REGION=auto
S3_BUCKET=knosi-assets
S3_ACCESS_KEY_ID=your-access-key
S3_SECRET_ACCESS_KEY=your-secret-key
S3_PUBLIC_BASE_URL=https://assets.example.com
# S3_FORCE_PATH_STYLE=true

Historical note images can be migrated into the same bucket with:

node --env-file=.env.local scripts/db/migrate-base64-images-to-blob.mjs --dry
node --env-file=.env.local scripts/db/migrate-base64-images-to-blob.mjs

The migration script handles inlined data:image/... content and legacy remote image URLs stored in notes, learning_notes, and os_project_notes, rewriting them to your configured S3-compatible bucket.

Feature Flags

# All optional modules are off by default
ENABLE_TOKEN_USAGE=false
NEXT_PUBLIC_ENABLE_TOKEN_USAGE=false
ENABLE_PORTFOLIO=false
NEXT_PUBLIC_ENABLE_PORTFOLIO=false
ENABLE_OSS_PROJECTS=false
NEXT_PUBLIC_ENABLE_OSS_PROJECTS=false
ENABLE_FOCUS_TRACKER=false
NEXT_PUBLIC_ENABLE_FOCUS_TRACKER=false

Set both the server-side and NEXT_PUBLIC_ variant to true to enable a module.

AI Rate Limit

AI_DAILY_LIMIT=50   # Per-user daily AI call cap; set to 0 for unlimited

AI Provider Setup

AI providers are configured per-user in /settings, not via env vars. Sign in, click + Add provider, and pick one of:

  • OpenAI-compatible API — OpenAI, DeepSeek, Moonshot, SiliconFlow, Groq, or any custom OpenAI-compatible endpoint. Provide the base URL, API key, and a label.
  • Local Model (Ollama / LM Studio) — point to your local OpenAI-compatible server (http://127.0.0.1:11434/v1 by default).
  • Claude Code Daemon — route Ask AI through your local Claude Pro/Max subscription via the Knosi CLI daemon. No API key required.
  • Transformers.js — in-process embedding-only kind for the RAG indexer when you don't want to call out at all.

After adding providers, assign one to each AI Role (Chat / Task / Embedding) in the same Settings page. Each role can use a different provider and model — Chat → DeepSeek, Task → GPT-4o-mini, Embedding → OpenAI text-embedding-3-small is a typical setup.

Required deployment env

The single AI-related env var on the deployment is the encryption master key for stored API keys:

# .env.local — generate once and keep it in your secret store
KNOSI_SECRET_KEY=$(openssl rand -hex 32)

Without KNOSI_SECRET_KEY the server refuses to start. Losing it requires every user to re-enter their API keys.

Claude Code Daemon

To use the daemon kind, run on your local machine:

npx @knosi/cli --url https://www.knosi.xyz

Or during local development:

npm run daemon

The daemon opens a notification stream for queued AI tasks, executes them via your local Claude CLI, and streams results back. Requirements: Claude CLI installed and logged in (claude login).

Claude Web Connector

Knosi now exposes a remote MCP surface for Claude Web:

/.well-known/oauth-authorization-server
/api/mcp

In Claude Web, add a custom connector that points to your Knosi deployment. The OAuth flow uses your existing Knosi account and grants scoped access for:

  • knowledge:read
  • knowledge:write_inbox

Saved conversations land in the root-level AI Inbox folder as raw captures.

Claude Code Save-To-Knosi Flow

The local CLI now supports an explicit save path for Claude Code:

# 1. Log the CLI into your Knosi deployment
npx @knosi/cli auth login https://www.knosi.xyz

# 2. Install the personal Claude Code skill
npx @knosi/cli install-skill

# 3. Save a raw conversation payload
cat payload.json | npx @knosi/cli save-ai-note --json

The installed skill template is written to ~/.claude/skills/save-to-knosi/SKILL.md and is intended for explicit user-triggered saves only.

Pulling a local model

If you're using the Local kind with Ollama, pull a model first:

ollama pull qwen2.5:14b
ollama pull nomic-embed-text   # for embeddings

Then in /settings, add a Local provider pointing at http://127.0.0.1:11434/v1 and select the model in the Chat / Embedding role rows.

Feature Flags

Optional modules are hidden by default and activated through environment variables. Each module requires both a server-side flag and a NEXT_PUBLIC_ counterpart so the navigation renders correctly on the client.

ModuleServer flagClient flag
Token Usage DashboardENABLE_TOKEN_USAGENEXT_PUBLIC_ENABLE_TOKEN_USAGE
Portfolio TrackerENABLE_PORTFOLIONEXT_PUBLIC_ENABLE_PORTFOLIO
OSS Project NotesENABLE_OSS_PROJECTSNEXT_PUBLIC_ENABLE_OSS_PROJECTS
Focus TrackerENABLE_FOCUS_TRACKERNEXT_PUBLIC_ENABLE_FOCUS_TRACKER

Set both to true to show the module in the sidebar and enable its routes.

Tech Stack

LayerTechnology
FrameworkNext.js 16 (App Router) + React 19
StylingTailwind CSS v4
APItRPC v11 + Zod v4
DatabaseDrizzle ORM + SQLite via libsql / Turso
AuthAuth.js v5 (GitHub / Google OAuth + email-password)
AIVercel AI SDK v6 (ai@6 + @ai-sdk/react@3)
Object StorageS3-compatible (R2 / MinIO / S3)
EditorTiptap v3 (ProseMirror)
DiagramsMermaid + Excalidraw
Content fetching@mozilla/readability + linkedom
TestingPlaywright (E2E)
DeploymentDocker Compose / Hetzner-style self-hosting

Project Structure

src/
  app/              Next.js App Router pages and API routes
    (app)/          Authenticated route group
  components/
    editor/         Tiptap editor — extensions, blocks, toolbar, paste handlers
    layout/         Sidebar, mobile nav
    ui/             Shared UI primitives
  server/
    db/             Drizzle schema and database connection
    routers/        tRPC routers
    ai/             Chunking, indexer, hybrid RAG, provider abstraction
    focus/          Focus Tracker interval slicing and aggregation
  lib/              Client utilities and tRPC client
e2e/                Playwright E2E tests
eval/               RAG + agent eval datasets and run results
docs/changelog/     Engineering change log

Common Commands

npm run dev           # Start dev server at http://localhost:3200
npm run build         # Production build (includes TypeScript check)
npm run lint          # ESLint
npm run test:e2e      # Playwright E2E tests
npm run db:generate   # Generate Drizzle migrations
npm run db:push       # Apply migrations to the database
npm run db:studio     # Open Drizzle Studio
npm run daemon        # Start local Claude Code AI daemon
npm run usage:daemon  # Start usage reporter + analysis daemon

Eval

Whenever you touch retrieval, ranking, or chat-prep code under src/server/ai/, run the eval suite and attach the compare output to the PR description:

pnpm eval:prepare                                                          # one-time env prep
pnpm eval:rag --user <id> --top-k 16 --out eval/results/run-<label>.json   # RAG retrieval scores
pnpm eval:agent --user <id> --out eval/results/agent/run-<label>.json      # agent tool-use scores
pnpm eval:compare eval/results/baseline.json eval/results/run-<label>.json # per-case Δ vs baseline

Datasets live in eval/ground-truth.json (retrieval) and eval/agent-cases.json (agent). See docs/eval/README.md for the full workflow.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

GNU Affero General Public License v3.0

AGPL-3.0 means: you can use, modify, and self-host freely. If you run a modified version as a network service, you must publish your source changes under the same license.

Author

Built by Zhou Siyao — @zhousiyao03

↑↓ navigate openesc close