{"slug": "show-hn-hermes-notes-pkb", "title": "Show HN: Hermes Notes PKB", "summary": "Hermes Notes, a self-hosted block-first personal knowledge base, has been released on GitHub by developer jpmoo. The application unifies notes, tasks, and projects into typed blocks that link together, and includes features such as collections (lists, tables, kanban, calendars, canvas), semantic search via Ollama, an optional local AI assistant, an MCP server, and Obsidian-compatible export. It requires Node.js 22+, pnpm 9+, and PostgreSQL 14+, and is designed for non-developers to run with a setup wizard.", "body_md": "**A block-first personal knowledge base — where notes, tasks, and projects are all the same thing, and everything connects.**\n\nHermes Notes is a self-hosted PKB. Every piece of information — a note, a task, a project, a person, a bookmark — is a **block** of a type you define. Blocks link to each other, roll up into flexible **collections** (lists, tables, kanban matrices, calendars, or an infinite canvas), and are searchable by keyword *and* meaning. It ships with daily notes, a weekly-review workflow, an optional local AI assistant, an MCP server for agents, and one-click export to Obsidian-compatible Markdown.\n\nI'm a vibe-coder, and Claude did all of the heavy lifting here. Expect some hard edges here and there!\n\n**Block-first data model.** Define your own block types (Task, Project, Person, Book…) with typed fields — text, long-text (Markdown), dates & date-spans, numbers, selects, status, references to other blocks, and file attachments.**Everything links.** Inline`@`\n\n/`#`\n\n/`|`\n\nmentions, reference fields, and a live backlinks/connections panel. Links to deleted blocks are surfaced so you can clean them up.**Collections, many shapes.** Group blocks as a**list**,** table**,** kanban matrix**(rows × columns × regions),** calendar**,** document**, or** infinite canvas**— including*smart*collections driven by a query builder.**Tasks & projects.** Statuses, due/scheduled date-spans, recurrence, and project relations. On a canvas, drawing a link from a task to a project files it under that project.**Daily notes & weekly review.** A dated scratchpad per day, plus a configurable weekly-review flow with reflections.**Semantic + keyword search.** Full-text search everywhere, backed by vector embeddings (via your own Ollama model) for \"find things like this.\"**Local AI assistant (optional).** Chat over your knowledge base using an Ollama model you choose — nothing leaves your server.**MCP server built in.** Point Claude or any MCP client at your notes to read, search, and manage tasks/projects.**Obsidian-compatible export.** Download a`.zip`\n\nof Markdown files (one per block, a folder per type, deduped attachments, YAML frontmatter, and`[[wikilinks]]`\n\n).**Yours to run.** Postgres for storage, per-user Ollama config, nightly database backups, and a first-run setup wizard so you don't have to hand-write config.\n\nYou don't need to be a developer. If you can install a couple of tools and run a few commands, you can run Hermes.\n\n**You'll need**\n\n**Node.js 22+** and**pnpm 9+**— install pnpm with`npm install -g pnpm`\n\n.**PostgreSQL 14+** running somewhere the app can reach. On first run, Hermes' setup wizard can create its own database and install the bits it needs (the`vector`\n\nand`pgcrypto`\n\nextensions) for you — for that, give it a Postgres**admin/superuser** login (e.g. the default`postgres`\n\nuser). Or point it at a database you've already made.*(Optional)*— only if you want semantic search and the AI assistant. Then pull a model, e.g.[Ollama](https://ollama.com)`ollama pull nomic-embed-text`\n\n.\n\n**Run it**\n\n```\ngit clone https://github.com/jpmoo/hermesnotes.git\ncd hermesnotes\npnpm install\npnpm build\npnpm start\n```\n\nNow open ** http://localhost:3000** in your browser. A\n\n**setup wizard** walks you through the rest: point it at your Postgres admin login, and it creates the database, installs the extensions, sets everything up, and makes your account. Done — it's running on a port.\n\nThat's the whole thing. It's a single program: one command (`pnpm start`\n\n) runs both the app and its web page on one port. To reach it from other devices or give it a real web address with HTTPS, put it behind a reverse proxy (Caddy makes this a two-line config):\n\n```\nnotes.example.com {\n    reverse_proxy localhost:3000\n}\n```\n\n**To keep it running** across reboots/crashes, use a process manager — systemd, [pm2](https://pm2.keymetrics.io/), or Docker.\n\nEverything's optional — with nothing set, the setup wizard handles the database and generates a secret for you. If you'd rather configure by hand, copy [ .env.example](/jpmoo/hermesnotes/blob/main/.env.example) to\n\n`.env`\n\nand edit it:| Variable | Default | Purpose |\n|---|---|---|\n`PORT` |\n`3000` |\nThe port the app runs on. |\n`HOST` |\n`0.0.0.0` |\nBind address. |\n`APP_ORIGIN` |\n`http://localhost:3000` |\nYour app's public address (scheme + host, no path), for CORS + cookies. |\n`DATABASE_URL` |\n(wizard) |\nPostgres connection. Needs the `vector` extension. Left to the wizard if unset. |\n`AUTH_SECRET` |\n(generated) |\nSigning key for logins. Auto-generated if unset (`openssl rand -base64 48` to make your own). |\n`EMBEDDING_INDEX_DIM` |\n`2000` |\nVector index width; leave as-is unless you know you need more. |\n`APP_BASE_PATH` / `PUBLIC_BASE` |\n(root) |\nOnly needed to host under a subpath — see below. |\n\n**Hosting under a subpath.** By default the app lives at the root of its address (`http://host:PORT/`\n\n). To host it at something like `example.com/notes`\n\nbehind a reverse proxy, set both `APP_BASE_PATH=/notes/`\n\nand `PUBLIC_BASE=https://example.com/notes`\n\nin `.env`\n\nbefore `pnpm build`\n\n. Otherwise, ignore these.\n\n**Ollama is per-user and configured in-app**(Settings → Admin → Ollama URL + embed model). Choose an embedding model for semantic search and an inference model for the assistant. Set the similarity threshold in Settings; the Admin tab shows embedding coverage and a \"re-embed all\" button.**MCP server.** A Model Context Protocol endpoint is mounted at`<your-app>/mcp`\n\n(streamable HTTP,`Authorization: Bearer <access key>`\n\nfrom Settings → Access Keys). Connect Claude or any MCP client to read/search blocks and manage tasks & projects.**Export.** Settings → Export builds an Obsidian-compatible`.zip`\n\n: one Markdown file per block, a folder per type, a shared deduped`attachments/`\n\nfolder, YAML frontmatter from your field labels, and connections as`[[wikilinks]]`\n\n.\n\nHermes is built for **personal use** — on your own laptop, or a home server on your own network, for you (and maybe a few people you trust). It is **not** hardened to be a public, multi-tenant service on the open internet. Running on localhost or a trusted LAN, the defaults are fine and there's nothing extra to do.\n\nIf you *do* put it on the internet (a public domain, a port forward), spend two minutes on these:\n\n**Finish the setup wizard before you expose it.** Until your first account exists, setup is open and*the first account to register becomes the admin*— so complete setup and create your account while the box is still private.**Lock down registration.** Sign-ups are open by default. Once your account exists, turn off open registration in**Settings → Admin** unless you actually want others to self-register.**Serve it over HTTPS behind a reverse proxy**(see the Caddy snippet under[Install & run](#install--run)). Hermes trusts the proxy's`X-Forwarded-For`\n\n, so login rate-limiting and logs see the real client — not just the proxy.**Set** This marks the session cookie`NODE_ENV=production`\n\n.`Secure`\n\n(HTTPS-only), which matters once you're off plain localhost.**Add HSTS at the proxy.** Caddy's automatic HTTPS handles this; for nginx, add a`Strict-Transport-Security`\n\nheader.\n\nA few things are handled for you: your data is strictly per-user (no account can see another's blocks), passwords are hashed with argon2id, and **permanent deletion requires a real browser login** — an AI agent connected over MCP can archive blocks but can never hard-delete your notes.\n\nTypeScript · **Fastify** (API) · **PostgreSQL + pgvector** · **Drizzle** (schema/migrations) · **React + Vite + TipTap** (web). A pnpm monorepo.\n\n```\npackages/shared   Shared block/property-schema types (zod)\npackages/db       Drizzle schema + SQL migrations\napps/server       Fastify API (also serves the built web app + MCP)\napps/web          React client\ndocs/             Design doc + architecture notes\n```\n\n*Only if you want to change the code* — to just run Hermes, use [Install & run](#install--run) above.\n\nRun the two dev servers in separate terminals (hot reload). The web dev server proxies API calls to the running server:\n\n```\nPORT=8089 pnpm dev:server     # API, on :8089\npnpm dev:web                  # web, on http://localhost:5173\n```\n\nOther scripts: `pnpm build`\n\n, `pnpm typecheck`\n\n, `pnpm db:generate`\n\n, `pnpm db:migrate`\n\n.\n\nIssues and pull requests are welcome. Please run `pnpm typecheck`\n\nbefore opening a PR. The [design doc](/jpmoo/hermesnotes/blob/main/docs/hermes-notes-v2-design-doc.md) and [architecture notes](/jpmoo/hermesnotes/blob/main/docs/hermes-notes-v2-architecture.md) explain the data model and decisions.\n\nIf Hermes is useful to you, a coffee is always appreciated ☕.\n\nReleased under the [MIT License](/jpmoo/hermesnotes/blob/main/LICENSE).", "url": "https://wpnews.pro/news/show-hn-hermes-notes-pkb", "canonical_source": "https://github.com/jpmoo/hermesnotes/", "published_at": "2026-07-31 10:07:11+00:00", "updated_at": "2026-07-31 10:22:55.919471+00:00", "lang": "en", "topics": ["ai-tools", "ai-infrastructure", "developer-tools"], "entities": ["Hermes Notes", "jpmoo", "Ollama", "Claude", "PostgreSQL", "Node.js", "pnpm", "Obsidian"], "alternates": {"html": "https://wpnews.pro/news/show-hn-hermes-notes-pkb", "markdown": "https://wpnews.pro/news/show-hn-hermes-notes-pkb.md", "text": "https://wpnews.pro/news/show-hn-hermes-notes-pkb.txt", "jsonld": "https://wpnews.pro/news/show-hn-hermes-notes-pkb.jsonld"}}