Knowledge

Knowledge

Made by [Seaynic Labs](https://seayniclabs.com). 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.

Skills

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

1. Start your assistant and ask it to list your notebooks. It calls open_notebook_notebooks and shows you the names.
2. Ask it to search a word you know is in one of your notes. It calls open_notebook_search.
3. 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.

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" } } } }

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

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. . : Fix: .

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](https://seayniclabs.com). We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.