knowledge

Knowledge

Made by Seaynic Labs. Need tools like this built around your own systems? We do that.

Knowledge lets an AI assistant search, read and write the notes in your self-hosted Open Notebook, and comes with skills that teach it to do that work well: meeting notes, decision records, weekly reviews and source-backed research.

It is a bundle: tools, skills and instructions in one install. The tools are one server made of modules. You switch on the modules you use. New modules arrive switched off, so an update never changes what your assistant can do until you choose to.

Security card
Network	Only the Open Notebook server you configure (KNOWLEDGE_OPEN_NOTEBOOK_URL). Open Notebook fetches the links you add, not Knowledge. Nothing else, no telemetry.
Files	Reads its config file (/.config/knowledge/config.toml). Reads a local file only when you name it in open_notebook_add_source, and only after you approve it (the file goes to your Open Notebook server). Writes one local approval log (/.local/state/knowledge/approvals.jsonl).
Secrets	API keys and passwords come from your environment or config file. They are never tool arguments and never returned to the model.
Read-only tools	6: open_notebook_notebooks, open_notebook_search, open_notebook_notes, open_notebook_note_get, open_notebook_source_get, knowledge_modules
Needs your approval	open_notebook_note_create, open_notebook_add_source: you approve each write in your app, or pre-approve notebooks in settings (not for local files). The AI cannot approve for you.
Startup cost	about 4,600 tokens (8 tools, 7 skill prompts)
Changes	Tool descriptions are locked by hash (tool-manifest.lock.json); CI fails if they change silently.

Skills

Skill	What it does	Source
getting-started	Checks the settings, runs the first calls, explains approvals and errors	Seaynic Labs (MIT)
research-with-sources	Answers from your notebooks, cites each claim, flags sources that disagree	Seaynic Labs (MIT)
weekly-review	Done, open and next-week items from the notes you changed this week	Seaynic Labs (MIT)
meeting-notes	Structured meeting notes as a Markdown file, optionally saved to a notebook	Seaynic Labs (MIT)
decision-record	A numbered Architecture Decision Record in a Decisions/ folder	Seaynic Labs (MIT)
icm-architect	Organises a knowledge base as a folder structure that agents can walk	Jake Van Clief (MIT), credits
obsidian-markdown	Obsidian-flavoured Markdown: wikilinks, callouts, properties	Steph Ango (MIT), credits

Skills reach every app. Claude Code and other skill-aware apps read the skills/ folder. Any MCP app gets the same text as prompts: getting-started, for example, is the prompt named getting-started. Third-party skills keep their own license files. See CREDITS.md.

Install

Knowledge needs Python 3.11 or newer. With uv you don't install anything ahead of time:

uvx knowledge-bundle-mcp --version

Or with pip:

pip install knowledge-bundle-mcp

Pinned install. For a fixed setup, pin the exact version. The plugin manifest pins it the same way:

uvx knowledge-bundle-mcp==0.2.1 --version

As a Claude Code plugin. One install gives you the MCP server and the skills. This needs the seayniclabs/plugins marketplace, which is published with the release:

/plugin marketplace add seayniclabs/plugins
/plugin install knowledge@seayniclabs

The plugin still needs your Open Notebook address in its settings. The plugin file is .claude-plugin/plugin.json.

First five minutes

1. Set KNOWLEDGE_OPEN_NOTEBOOK_URL to your server's address (step 2 below shows where).

2. Run the check. It prints ok or FIX for each item and exits 0 when everything is ready:

   knowledge-bundle-mcp --doctor
   

3. Start your assistant and ask it to list your notebooks. It calls open_notebook_notebooks and shows you the names.

4. Ask it to search a word you know is in one of your notes. It calls open_notebook_search.

5. Ask it to save a note. It shows a preview first, then asks you to approve the save in your app.

Settings

Set these as environment variables in your MCP client's config, or put them in a config file (see below). Knowledge starts without any of them and tells you what's missing when you call a tool.

Variable	Module	What it is
KNOWLEDGE_OPEN_NOTEBOOK_URL	open_notebook	Address of your Open Notebook server, e.g. https://notebook.example.com. No path.
KNOWLEDGE_OPEN_NOTEBOOK_PASSWORD	open_notebook	Only if your server has a password (OPEN_NOTEBOOK_PASSWORD on the server). Leave it unset otherwise.
KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM	open_notebook	true by default: you approve each new note and link. false lets the assistant save them on its own. Local files always need your approval.
KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS	open_notebook	Optional. Comma-separated notebook names the assistant may save links and notes to without asking, e.g. Research,Inbox
KNOWLEDGE_APPROVAL_LOG	any	Optional. Where the approval log is written. Default: ~/.local/state/knowledge/approvals.jsonl
KNOWLEDGE_<MODULE>_ENABLED	any	false turns a module off, e.g. KNOWLEDGE_OPEN_NOTEBOOK_ENABLED=false

Config file (optional). Knowledge also reads ~/.config/knowledge/config.toml, or the file named by KNOWLEDGE_CONFIG. Environment variables win over the file.

[open_notebook]
url = "https://notebook.example.com"
password = "change-me"
require_confirm = true

Add it to your MCP client

Most clients use the same JSON shape. Put it where your client keeps MCP servers:

{
  "mcpServers": {
    "knowledge": {
      "command": "uvx",
      "args": ["knowledge-bundle-mcp"],
      "env": {
        "KNOWLEDGE_OPEN_NOTEBOOK_URL": "https://notebook.example.com"
      }
    }
  }
}

Client	Where the config goes
Claude Desktop	claude_desktop_config.json (Settings → Developer → Edit Config)
Claude Code	claude mcp add knowledge -- uvx knowledge-bundle-mcp, then add the env values, or a project .mcp.json
Cursor	~/.cursor/mcp.json, or .cursor/mcp.json in a project
VS Code	.vscode/mcp.json, using "servers" instead of "mcpServers"
Sonique, Hermes, OpenClaw, others	Any client that launches a stdio MCP server: command uvx, args ["knowledge-bundle-mcp"], plus the env values

Over HTTP. For clients that connect to a URL instead of launching a process:

knowledge-bundle-mcp --transport http --port 8765

It serves streamable HTTP at http://127.0.0.1:8765/mcp. It listens only on your own machine by default. Put authentication in front of it before exposing it anywhere else.

Try these

Paste any of these into your assistant once Knowledge passes --doctor:

1. "List my notebooks and tell me which one changed most recently."
2. "Search my notebooks for what I wrote about the Q3 budget, and cite each note."
3. "Write a weekly review of the notes I changed this week, using the weekly-review skill."
4. "Make an ADR for choosing SQLite over Postgres for the prototype, with the alternatives table filled in."
5. "Save this link to my Research notebook: https://example.com/article. Show me the preview first."

Tools

Tool	What it returns
knowledge_modules	Which modules are on, which settings are missing, the skills, and the publisher. Call this first.
open_notebook_notebooks	Your notebooks, most recently updated first, paged
open_notebook_search	Matching sources and notes. mode is text (keywords) or vector (meaning; needs an embedding model on the server). Optional notebook_id. Paged.
open_notebook_notes	The notes in one notebook, titles only, paged
open_notebook_note_get	One note's content, cut at max_chars
open_notebook_source_get	One source: title, topics, extracted text, notebooks, processing status
open_notebook_note_create	Saves a note after you approve it. Without confirm=true it only returns a preview.
open_notebook_add_source	Adds a web link, or a local file you name, as a source. Preview first; you approve it. Processed in the background.

Every tool returns structured data with a published schema, so an assistant can work with the results instead of parsing text. Errors always look like knowledge.<module>.<code>: <message> Fix: <hint>.

Safety

• Knowledge only calls the Open Notebook server you configure. It sends nothing anywhere else and keeps no data of its own.
• open_notebook_note_create and open_notebook_add_source change your notebooks, so you approve each one. When the assistant asks to save, Knowledge asks you directly through your MCP client (MCP elicitation) and shows the notebook, the title and the full text or link. The assistant can't answer that question for you.
• A local file is read only after you name it, and it is uploaded only after you approve its full path and size. Files named like credential stores (.env, .netrc, private keys, *.pem, *.key) and files in ~/.ssh, ~/.aws or ~/.gnupg are refused.
• Some MCP clients can't ask you questions yet. In those, Knowledge refuses to write unless you've pre-approved the notebook with KNOWLEDGE_OPEN_NOTEBOOK_ALLOWED_NOTEBOOKS, or turned approval off with KNOWLEDGE_OPEN_NOTEBOOK_REQUIRE_CONFIRM=false. Local files are never pre-approved.
• Before anything is written or sent, text that looks like a credential (API keys, tokens, private keys, passwords in URLs) is refused. The error names the kind of credential found, never the value.
• Use an https:// address for your server, and give the password only to Knowledge, not to other tools.

Develop

uv venv && uv pip install -e '.[dev]'
.venv/bin/pytest
python3 scripts/check_skills.py
.venv/bin/python scripts/tool_lock.py --check
.venv/bin/python scripts/security_card.py --check

scripts/tool_lock.py (without --check) rewrites tool-manifest.lock.json after a deliberate change to a tool, prompt or instruction. Add a changelog line in the same commit.

Security

Report a vulnerability privately through GitHub (Security tab, "Report a vulnerability"). See SECURITY.md. Every approval, decline and refusal is logged locally in ~/.local/state/knowledge/approvals.jsonl: titles, notebook names and sizes, never the text. Set KNOWLEDGE_APPROVAL_LOG to move it.

License

MIT. Published by Seaynic Labs. Third-party skills are credited in CREDITS.md and keep their own licenses.

---

Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.