README file from
GithubThe knowledge base your agents can live in.
A local-first knowledge system for people and agents. Plain Markdown in. Traceable knowledge out.
One plain-markdown workspace, served by three shells: an MCP server and CLI for Codex, Claude, Cursor, and Antigravity — and an Obsidian plugin as its richest human interface. Obsidian maximizes Knowlery; nothing about it requires Obsidian.
Your free-form notes stay yours. Agents get a structured, retrievable layer —
entities/, concepts/, comparisons/, queries/ — compiled from your
material through a reviewed pipeline, plus the skills and conduct that make
them good collaborators. Retrieval is deterministic and measured, answers
carry citations, and "no confident match" is an honest verdict instead of
noise. The workspace format, CLI surface, and MCP contracts are frozen under
semver and pinned by contract tests.
Read the official documentation: https://jayjiangct.github.io/knowlery/.
Two ways to start
With your agent (no Obsidian required)
Install the agent plugin — MCP server plus all fifteen skills — with a two-command marketplace flow:
Claude Code: /plugin marketplace add JayJiangCT/knowlery
/plugin install knowlery
Codex: codex plugin marketplace add JayJiangCT/knowlery
codex plugin add knowlery@knowlery
Start a new agent session after installation so the bundled skills and MCP tools are loaded. In Codex Desktop, open Plugins → Installed to confirm that Knowlery is enabled.
Or add one MCP config block to any client (Cursor, Claude Desktop, Antigravity, …):
{ "command": "npx", "args": ["-y", "knowlery@^1", "mcp"] }
Then everything is conversation: "set up a knowledge base called main", "remember this", "what do I know about X?", "give my KB a checkup". Per-client setup: Connect Your Agent · usage by conversation: Talk to Your Knowledge Base.
In Obsidian
Install Knowlery from Obsidian's community plugin directory (Settings → Community plugins → Browse) and run the setup wizard. You get the action-first dashboard, Knowledge health, and the bundle sharing UI — and the vault registers itself so every agent can address it by name. Full walkthrough: Start in Obsidian.
Either way it's the same plain folder: a KB born in a conversation opens in Obsidian with zero migration, and an Obsidian vault is automatically available to your agents.
Brand
Knowlery's identity is the Atlas Fold system — a K-shaped route connecting source, structure, and retrieval, drawn in graphite and paper with a single Knowledge Lime signal. The metaphor is deliberate: a map you can trust, not a mind you have to believe.
| Position | Local-first knowledge infrastructure — your notes remain plain Markdown; Knowlery adds structure, retrieval, and agent access without taking ownership of the source. |
| Character | Exact, calm, and quietly alive — technical enough to earn developer trust, warm enough to feel like a place where knowledge accumulates. |
| Difference | Structure over spectacle — no chatbot face, neural cloud, or AI glow. The visual language is navigation through a maintained body of knowledge. |
The full brand system — logo construction, palette, typography, voice, and
usage rules — lives in design/brand/ (open
brand-guide.html in a browser). Marks,
lockups, and the app icon are under
design/brand/assets/.
Inspiration: LLM Wiki & BYOAO
Andrej Karpathy's "LLM Wiki"
In LLM Wiki, Andrej Karpathy describes a pattern different from one-off RAG: instead of re-deriving answers from raw notes on every question, an agent incrementally builds and maintains a persistent wiki—structured, interlinked markdown that sits between you and your sources. New material is read, distilled, and folded into entity pages, topic summaries, and cross-links; the base is kept current rather than re-scanned from scratch each time.
Knowlery operationalizes that maintenance story: the layout (KNOWLEDGE.md, SCHEMA.md, the four compiled directories), the skills (/cook, /ask, and friends), the staleness report that tells the agent exactly what to fold in next, and the health checks that keep the machinery honest — with a clear boundary (your free-form notes stay yours; the agent works the shared map).
BYOAO
BYOAO (Build Your Own AI OS) was Knowlery's predecessor: an OpenCode-oriented flow that turned Obsidian into an AI-powered "LLM Wiki" style knowledge base with global CLI install. Working on BYOAO is what made it natural to ask: what if the same ideas lived as a first-class Obsidian plugin — and, later, as a proper CLI, an MCP server, and an agent plugin too. BYOAO is archived — its role is fully superseded.
Getting started (video)
▶ Full walkthrough (~3 min, with audio) · same file: Releases
The CLI and MCP server
One-line install (isolated prefix, PATH handled with consent — never silently):
curl -fsSL https://jayjiangct.github.io/knowlery/install.sh | sh
(Or npm i -g knowlery, or zero-install via npx -y knowlery@^1 <command>.)
knowlery init # scaffold a workspace (works brownfield — never touches your notes)
knowlery kb add work ~/vaults/work-kb # name it; every command and agent can address it
knowlery sync # bring skills, rules, and the retrieval script up to date
knowlery health # config integrity + knowledge-page counts; exit code for CI
knowlery query --kb work "<question>" # deterministic retrieval, from any directory
knowlery query --kb '*' "<question>" # federated search across every registered KB
knowlery stale # compiled pages whose sources changed; notes never compiled
knowlery bundle install <zip-folder-or-url> # install a shared knowledge bundle
knowlery bundle publish <seed> # review-gated publish to a GitHub Release
knowlery mcp # MCP server over stdio: 9 tools, 10 skill prompts, page resources
knowlery mcp serve --port <n> --token-file <path> # self-hosted remote mode
Retrieval works headlessly too: node .knowlery/bin/query.mjs "<question>" (written by
init/sync) searches the workspace with Obsidian closed.
The Obsidian plugin
Requirements: Obsidian desktop 1.12.2+, community plugins enabled. Claude Code or OpenCode if you want to run installed skills from the dashboard; Node.js/npm for the optional external skills registry. Knowlery is desktop-only because it uses local command-line tools and Electron desktop APIs.
During the setup wizard, Knowlery can detect whether Claude Code, OpenCode, Node.js, and the external skills CLI are available, and can optionally help install or prepare missing agent tools. These steps are opt-in; if a tool is already installed, Knowlery skips it.
Install beta builds with BRAT
BRAT is the Beta Reviewers Auto-update Tool for Obsidian. Upstream project: TfTHacker/obsidian42-brat (documentation: tfthacker.com/BRAT).
- Install the BRAT plugin in Obsidian.
- Open BRAT settings, Add Beta plugin, and use
https://github.com/JayJiangCT/knowlery. - Enable Knowlery under Settings → Community plugins.
Manual install
- Download
main.js,manifest.json, andstyles.cssfrom the latest release. - Put those files in
.obsidian/plugins/knowlery/inside your vault. - Reload Obsidian and enable Knowlery from Settings → Community plugins.
Agent chat in Obsidian (optional companions)
If you also want a full agent chat inside Obsidian (sidebar, inline edit, multi-provider), consider installing one of these in addition to Knowlery:
- Claudian — embeds Claude Code, Codex, and related flows in the vault; file read/write and bash from a chat UI.
- obsidian-agent-client — brings agents in via Agent Client Protocol (ACP) with multi-session and MCP support.
What Knowlery Creates
During setup and normal use, Knowlery can create or update these files and folders inside your workspace:
KNOWLEDGE.mdSCHEMA.md(knowledge taxonomy and page conventions)INDEX.baseentities/,concepts/,comparisons/, andqueries/inbox/, when the MCPcapturetool saves conversation notes.knowlery/manifest.json.agents/skills/and.agents/rules/(the one rules directory, for every platform)AGENTS.md— the entry file for Codex, OpenCode, and other agents (no import syntax there):KNOWLEDGE.md, Knowlery's operating rules, and the rule files copied into a managed block, regenerated on sync.claude/skills/and.claude/CLAUDE.md(the entry file for Claude Code:@-importsKNOWLEDGE.mdand each rule, operating rules inlined)skills-lock.json.knowlery/activity/, when activity logging is enabled.knowlery/reports/, when Weekly summary generates an HTML report.knowlery/requests/and.knowlery/reviews/, when daily review polish is used.knowlery/exports/, when Share knowledge bundle compiles a bundle (plus an optional.zipnext to it)Library/<bundle-id>/and.knowlery/bundles.json, when Install knowledge bundle installs a shared bundle.knowlery/bin/query.mjs, the local retrieval script (written on setup and refreshed on upgrades)~/.config/knowlery/registry.json, the global registry of named knowledge bases (outside the vault)
Knowlery may delete skill or rule files only when you use the corresponding delete or disable actions in the UI, and may delete an installed bundle's Library/<bundle-id>/ folder when you uninstall that bundle.
Permissions and Disclosures
Knowlery does not collect telemetry.
Knowlery reads and writes files inside your workspace to create and maintain the knowledge base layout, bundled skills, rules, activity summaries, review requests, and generated reports listed above. It also reads Obsidian's configured plugin directory when detecting or installing optional companion plugins.
Network access is opt-in and feature-specific. The skill browser can call the external skills registry through npx skills ... when you search for or install registry skills. Bundle install/publish/update can contact the URLs and GitHub repositories you point them at (private access delegates to your own gh login; Knowlery never asks for or stores tokens). The setup wizard can download the latest Claudian release from GitHub when you choose to install that optional companion plugin.
Knowlery can run local CLI commands such as claude, opencode, node, npx, gh, and skills when you explicitly use CLI-related features. These commands run on your computer with your user permissions. Knowlery does not send vault contents to those tools by itself; agent requests are created only from the actions you trigger.
The MCP server (knowlery mcp) runs locally over stdio and serves only the knowledge bases you registered; resource reads are allowlisted to the curated knowledge surface — free-form notes are not readable over MCP. Remote mode (knowlery mcp serve) requires an explicit port and a bearer token you generate, is read-only unless each write is individually enabled by flag, and never logs or stores the token. The agent plugin performs no install scripts: MCP provisioning is configuration plus npx.
On Obsidian 1.12.2+ with the command line interface enabled, Knowlery registers two read-only CLI commands, knowlery:query and knowlery:stale, which search and inspect vault content locally when you (or an agent you run) invoke them. The bundled .knowlery/bin/query.mjs script does the same offline with plain Node; neither makes network requests.
Some companion tools or services used with Knowlery, including Claude Code, OpenCode, registry skills, or model providers configured outside Knowlery, may require separate accounts or paid usage. Knowlery itself is free and does not process payments.
Development
npm install
npm run build # plugin (main.js) + CLI (knowlery-cli.mjs)
npm test # behavior + contract suites
npm run build:plugin # regenerate the agent plugin tree (drift-guarded in CI)
Release assets include main.js, manifest.json, styles.css, and
knowlery-plugin-<version>.zip. Architecture and design docs:
Architecture ·
Design Decisions ·
Stability Contract.
License
MIT (see LICENSE).