PierrotKnowledge2
A local knowledge base that a person and an AI agent can both work in, using the same plain Markdown files as the source of truth.
No database to sync, no proprietary format, no account. A bundle is a folder of
.md files you can read in any editor, keep in Git, and open again in ten
years.
日本語のドキュメントは docs/ja/usage.md。
Three ways to run it
They are separate processes that share a folder, not a client and a server. Nothing coordinates them except the files on disk — which is the whole design: there is one write path, so a human edit and an agent edit cannot disagree.
Agents run headless. Always. An agent host — Claude Code, Codex, opencode,
Hermes — spawns build/headless/okf-mcp.exe itself and talks to it over stdio.
It is one process with no page attached, which is where the difference between
8 MB and 135 MB comes from. Never point an agent at ui mode: that interface
speaks RPC to a browser, not MCP, and there is nothing there for an agent to
call.
Build it with bun run build:headless (SETUP.bat -Connect does it for you)
and register it from the connections panel. Without that binary the config
written for an agent falls back to bun run …/standalone.ts, which works only
where the agent host's own environment has Bun on PATH.
There was a fourth mode: a packaged desktop window, removed at 0.5.0. See Honest numbers for why.
Measured on this machine, Windows 11. Method and raw data: docs/BENCHMARK.md.
What each one exposes
The two halves of the application are deliberately separate surfaces:
- 46 RPC methods — what the interface calls.
uimode exposes this and nothing else. - 54 MCP tools — what an agent calls. Headless exposes this and nothing else, over stdio.
- The CLI reaches every one of the 54 tools plus
info,watch,ui,serve,updateandrmux.
The interface does not serve MCP. An agent working alongside you is a second process — the headless server, started by the agent's own host — and the two meet in the files. That is why an agent's edit shows up in your page a moment later rather than through any connection between them.
Honest numbers
Of the 147 MB, 145 MB is node_modules and 1.4 MB is this project. The
three runtime dependencies are marked, turndown and yaml. The desktop
column is left blank rather than estimated: that build no longer exists to
measure, and the figure in earlier revisions of this table was the headless
executable's size mislabelled.
Headless is a separate shape again: bun run build:headless produces one
self-contained executable — no node_modules, no Bun on PATH — and that is
all an agent host needs. With a Rust toolchain (cargo) on PATH it builds
the Rust port in rust/: 7 MB, about 8 MB resident, first answer in
33 ms. Without one, Bun compiles the TypeScript into a 94 MB executable
that answers identically — test/rust-parity.test.ts sends the same 186 MCP
calls to both and requires byte-identical replies. bun run build:cli does the
same for the CLI (build/cli/okf, 9 MB), which the PierrotKnowledge2
launcher prefers; its ui command hands off to Bun, because the interface is
still TypeScript. OKF_BUILD=bun forces the Bun build.
The desktop build was not light and never became light. At 633 MB it was heavier than Obsidian. The premise this project began with — that the system WebView would beat a bundled Chromium — did not hold: Windows starts six of those renderer processes for one window, measured at 360 MB, and the packaging layer added a second copy of the Bun runtime. Neither was something this codebase could fix.
So it is gone. By the end it was the same Vite bundle, the same RPC surface
and the same Workspace as ui mode, and its only exclusive capability was
the native folder dialog — which the OS opens for any process that asks, and
now does (src/bun/platform.ts). What that left was 5× the memory and a
patched pin of a young desktop framework, for a dialog.
One thing was genuinely lost, and it is worth naming rather than burying: a
page in your browser is reachable by your browser extensions, and a window was
not. ui binds to loopback and mints a per-run token, but an extension with
host access to 127.0.0.1 can read the page. If that matters for your threat
model, open it in a browser profile with no extensions.
Everything written for this project is 0.8 MB under src/ — 1.4 MB with the
tests, docs and scripts — with a live heap around 10 MB. There is nothing left
to trim on our side.
Install
One command per platform. Bun is installed for you if it is not already there.
Windows — double-click SETUP.bat, or:
SETUP.bat
macOS / Linux — from the folder you unzipped into:
bash SETUP.command
bash, not./. The current release ships with the executable bit set, so./SETUP.commandworks too — butbashworks no matter how the copy on disk got there. Setup also clears macOS's quarantine flag, so double-clicking works from then on.
Either one installs dependencies, builds the interface, scaffolds a starter bundle and puts a launcher on the Desktop. Both are safe to re-run.
Add -Connect (Windows) or --connect (macOS / Linux) to also register this
bundle with every agent host found on the machine — Claude Code, Codex,
opencode and the rest. Each tool's own config is backed up before one entry is
added, and nothing else in it is touched.
To update later, double-click UPDATE.bat (or bash UPDATE.command); to
remove it, UNINSTALL.bat (or bash UNINSTALL.command). Each shows what it
is about to do and asks once; your notes are never touched.
Then, from the folder you installed into:
.\PierrotKnowledge2 ui the interface, in your browser
.\PierrotKnowledge2 Update check for a new release
./PierrotKnowledge2 ui # macOS / Linux
The
.\is not optional. Setup does not put this folder on yourPATH, and PowerShell never runs a program from the current directory without being told to — a barePierrotKnowledge2 UpdateanswersCommandNotFoundException. Add the folder toPATHyourself if you would rather type it without the prefix.
ui binds to 127.0.0.1, mints a token for the run and opens the URL. Nothing
reaches the network, and no other page in the browser can drive it.
The command is named after the application rather than
okf— a short, generic word likely to collide with something else on the same PATH.okfstill works.
The three layers
bundle/
├── MAP.md Where everything is. Read this first.
├── human.md Who the user is
├── Task.md Open work, and recently finished work
├── raw/ Layer 1 — source material, as it arrived
├── wiki/ Layer 2 — the canonical, curated knowledge
└── .rag/ Layer 3 — derived search index (rebuildable, never hand-edited)
The three files at the top are not layers and sit deliberately outside them. The layers are three stages of one material — sources, curated knowledge, derived index — and these are not that material.
Who may write where:
raw/ is the human's inbox: originals go there, and imports from Notion,
GitHub, Google Drive or Obsidian land there. An agent cannot write to it, so
the record of what actually arrived can never be rewritten by the thing
summarising it.
Inside wiki/
wiki/
├── AGENTS.md The full contract for agents
├── daily/ One dated note per day
├── 1-projects/ PARA — active, has an end
├── 2-areas/ PARA — ongoing interest, no deadline
├── 3-resources/ PARA — useful knowledge (default)
├── 4-archive/ PARA — not currently in use
├── skills/ <category>/<name>/SKILL.md
├── loops/ One repeatable-task design per file
├── index.md OKF §8 reserved
└── log.md OKF §9 reserved
PARA sets search rank. The same hit scores higher in 1-projects/ than in
4-archive/, and archived pages are excluded from skill selection entirely.
Features
Writing
- Reading view first. Opening a document shows it rendered — frontmatter and link syntax are not what you should see on a page you came to read.
- One writing surface: the editor and the preview are the same pane.
- Format bar — headings, bold, italic, strikethrough, code, three kinds of list, quote, link, table, rule, alignment. Everything toggles.
- Width slider, full width by default, persisted.
- Pasting keeps Markdown. HTML from another tool is converted, not flattened.
- Wikilinks with completion, backlinks, unresolved-link report. Renaming a page rewrites every link to it.
- Full-text search with CJK bigram indexing, so Japanese matches without word boundaries.
- 開く shows the OS's own folder dialog, even though the page is in a browser: the page asks the server and the server asks the OS. Where there is no desktop session to ask — a container, an SSH shell — it falls back to asking for the path as text.
Daily notes
wiki/daily/YYYY-MM-DD.md, one action to open or create. Indexed like any
other page, so "what did I decide last Tuesday" is answerable.
Unchecked items under ## タスク are moved into Task.md by
collect_daily_tasks, then ticked and stamped with the id they became — so
the transfer is idempotent and a requirement written in a day's notes does not
vanish tomorrow.
For agents
MAP.mdis a routing table naming the one file that answers each kind of question. Measured: MAP is 522 tokens against 2342 for reading all four orientation files.- SkillSpace — agents see only each skill's name and description and open a body once chosen. Measured 58% fewer tokens than loading every procedure.
list_tasksreturns open work by default.- Loops — one repeatable task is one file; the last 5 runs keep their full journal, the next 20 collapse to a line, older ones to a count.
- RMUX — work that outlives a single tool call goes in a terminal session.
.\PierrotKnowledge2 rmux runreturns exactly when the command does, with the byte stream rather than the visible screen.
Connections
One panel, one page, three sections.
- External services (MCP) — Notion, GitHub, Google Drive, Obsidian, or
anything else that speaks the protocol. The tool list and its form are built
from whatever the server declares, so there is no per-service code. Imports
land in
raw/. - Agent hosts (11) — Claude Code, Codex, opencode, Hermes Agent, Cursor,
Antigravity, Strata's chat and
Unsloth Desktop, most offered in both a bundle-scoped and a user-scoped
form. One entry is added to their own config, after a backup and after
showing you the diff. Claude Code's user scope is the exception: it lives in
~/.claude.jsonalongside project state and server toggles, so the app shows you theclaude mcp addcommand rather than rewriting a file that big to add one line. Unsloth keeps its MCP servers in a database, so it gets anmcpServerssnippet to paste into its import instead; Strata reads a file of ours through--mcp-config. すべてのエージェントに登録 does the whole sweep in one press: every host found on the machine, sequentially, with a per-host report of what was written, what was already there, and what needs a command you run yourself. Hosts whose CLI is not onPATHare skipped rather than littered with a config for a tool that is not there — a checkbox includes them, for a real install the probe cannot see (Cursor on Windows, usually). - Anything else local that speaks MCP —
PierrotKnowledge2 mcp-configprints the entry to paste, in the dialect you ask for (--format json | toml | opencode | yaml | command). It is built from the sameserverSpecForthe one-press connection uses, so a pasted config and a written one cannot describe different servers. Printed rather than written, because editing a config whose shape has not been verified is how a connection ends up looking successful while the tool never reads it. - Orchestrators — Orca has no MCP
config of its own; it runs Codex, Claude Code, opencode or Pi each in its own
git worktree. Connect the underlying agent, and use a user-scoped entry:
a worktree is never the bundle directory, so project-scoped config is never
found there. For Claude Code that scope lives in
~/.claude.json, which also holds project state — so this app shows you theclaude mcp addcommand rather than editing that file. - Local model servers (6) — Ollama, llama.cpp, LM Studio, vLLM, Strata and Unsloth Desktop are MCP clients; they emit tool calls with nothing to execute them, so this app runs the agent loop itself with the token spend shown as it happens. Ports and required flags come from each vendor own docs — vLLM in particular ignores every tool unless started with both and . Unsloth's API is authenticated: its key is read from (Strata's, when it has one, from ) and never written to a file. The panel opens on a server that is actually installed, and one that is not running says so beside the model picker instead of raising an error.
Credentials are never typed into this app.
Updating
Double-click UPDATE.bat (Windows) or run bash UPDATE.command (macOS /
Linux). It checks, verifies and shows the release notes, asks once, and on y
installs the release and rebuilds — bun install, the interface, and whichever
binaries were built here before. Quit the app and any agent using it first: a
running binary cannot be replaced, and that step is reported as failed.
Coming from 0.8.0 or earlier?
UPDATE.batarrives with 0.8.1, so that one update is the command form below, followed bybun installandbun run build:view. From then on, double-click.
The command form:
.\PierrotKnowledge2 Update check, verify, show the release notes
.\PierrotKnowledge2 Update --apply install
When a newer release exists and you are online, the interface shows a pulsing indicator; opening it renders the release notes.
An update replaces source, never build/ — so anything you compiled is still
the previous release until you rebuild it, and the launcher and every agent
host prefer those compiled copies. --apply names each stale binary and the
command that rebuilds it rather than leaving you with a new version that
nothing is running.
Uninstalling
Double-click UNINSTALL.bat (Windows) or run bash UNINSTALL.command
(macOS / Linux). Both show the plan and ask once; y carries it out. The
command form keeps the two steps apart:
.\PierrotKnowledge2 Uninstall show the plan
.\PierrotKnowledge2 Uninstall --apply carry it out
bash UNINSTALL.command # show the plan, ask, carry it out
bash UNINSTALL.command --apply # carry it out without asking
The plan lists what survives before it lists what goes, because that is the only question anyone uninstalling has. Bundles are never touched, and a bundle found inside the install directory aborts the whole thing. What it does do is the tedious part: take our entry back out of every agent host config, so none of them reports a broken MCP server for a program that no longer exists. Those files are backed up before being edited. The install folder itself is left for you to delete once the app has stopped — a running process cannot remove its own executable.
Downloads are verified against the SHA-256 GitHub computes server-side.
Versions come from a manifest inside the archive rather than the tag, and
an update that would go backwards is refused. Replaced files are moved to a
timestamped backup, never deleted, and --rollback puts them back.
An update never touches a bundle: it writes only to an allowlist of paths inside the install directory, and refuses outright if a bundle is found inside it. Upgrading from before 0.3.0 → docs/ja/upgrade.md.
Standards
Open Knowledge Format v0.2. Every concept is Markdown with YAML
frontmatter carrying a non-empty type; index.md and log.md are reserved
and carry no frontmatter. Conformance is checked on write and on demand.
Clause-by-clause audit: docs/CONFORMANCE.md.
The format is the storage. There is no separate database that could drift
from it — .rag/ is derived and can be deleted and rebuilt at any time.
Built with
Bun · Vite · TypeScript strict (exactOptionalPropertyTypes included) ·
SQLite FTS5 with BM25 · MCP over NDJSON stdio. No UI framework, no bundled
browser engine — the interface is served to the one you already run.
Developed and measured on Windows. macOS and Linux are handled in the code
and adjusted for — see docs/ja/platforms.md for what is
and is not known. The one place the OS is touched directly is the folder dialog
(powershell / osascript / zenity or kdialog), and it degrades to typing
a path when there is no desktop session.
735 tests, all passing. Typecheck clean on both configurations.
License
MIT. See LICENSE.
