pi-llm-wiki: four layers of durable knowledge, with immutability enforced by a guard script

Four layers, and the boundary between them is enforced by a script

The architecture is four layers and each one has a different mutability contract. Raw source packets preserve the inputs exactly as captured, and the readme calls that capture immutable. Source pages summarise what each source says. Canonical wiki pages track what the wiki currently believes. Generated metadata keeps everything searchable and navigable. Capturing a URL, a local file in any of several formats, or pasted text produces a structured packet, and a separate batch command turns unprocessed packets into concept, entity, synthesis and analysis pages. The guardrail is what makes the layering hold: direct edits to raw sources and to generated metadata are blocked, and the package ships the script that does the blocking alongside a script that runs at session start. That is the difference between a convention and a boundary. A prompt asking the model not to touch a file is advice; a hook that refuses the write is a control.

The premise is that synthesis is ephemeral in every other file-based setup

The justification section names the problem in three sentences and it is worth quoting, because it is the whole reason the package exists. Most file-based language model workflows behave like one-shot retrieval: the model searches raw documents every time you ask a question, and the synthesis it produces is ephemeral. So you pay for the same reading twice and you cannot cite what the agent concluded last Tuesday. This package creates a middle layer between raw documents and the model, and the claim is that the wiki compounds as you capture sources, ask questions and file durable analyses. Compounding is doing real work in that sentence. It is the difference between a search index that costs nothing to build and nothing to reuse, and a page that makes the next query cheaper and the next answer citable. If your workload is one-off questions about a document, none of this matters. If you are building something over months, it is the whole design.

Two native hosts, one extension, and a protocol for the other eleven harnesses

The packaging is deliberately layered by how the host loads software. Two agents load the extension natively, and both get the same extension, skill and slash commands. For one of them the whole install is:

pi install npm:@zosmaai/pi-llm-wiki

and for the other it is a different command against the same package, so the difference between them is limited to what changes. Everything else, which the readme names as Claude Code, Codex, Cursor, Windsurf, Zed, Cline and other protocol-capable harnesses, uses a packaged standard I/O server that you register as a local server. There is also a marketplace path for one specific harness, three commands that add the marketplace, install the plugin by name and reload. The user-facing commands are three, and they are the whole interface most people need: initialise a vault with a topic, ingest pending sources, and ask a question. So there are two ways in and one mental model. The practical consequence is that switching harnesses means registering a different path in a configuration file rather than relearning the tool, which is the right property for something meant to be infrastructure.

Absolute server paths, because the clients do not expand the home directory

There is one setup constraint that will cost you an hour if nobody tells you, and the readme tells you. When you register the standard I/O server by hand, use an absolute path, because the clients do not expand the home directory in server paths. You can pin which vault is in use with an environment variable rather than relying on discovery, and per-client configuration examples are provided for six named clients plus a generic form. That single note is the most operationally useful sentence in the installation section, and it is the kind of thing that is only written after somebody hit it. It also tells you something about the shape of the setup: there is an environment variable for the vault, an environment variable for the extraction timeout, and one for path pinning, so a deployment has three knobs and no configuration file. For a tool that writes to your home directory by default, that is a reasonable amount of configuration, and each knob is worth reading before you set it.

Two vaults, deduplicated, and one of them is always on

Recall searches two vaults and merges the results. One is per project, sitting in the working directory. The other is personal, sitting in the home directory, and it is described as an always-on fallback whose purpose is that knowledge compounds across projects even when no project wiki exists. Results are deduplicated across the two, which is the right call and also the hard part: if the same page exists in both, you have to decide which wins, and the readme does not say. The design bet here is that most of what a person accumulates about their own work is not project-scoped. Knowledge that you learned about a customer, a language runtime or a debugging technique belongs to you, not to the repository, and a per-project notes system keeps losing it at the next clone. The cost is that the personal vault is a file on your machine that an agent writes to by default, which is why it is paired with the immutable-source guardrail rather than left as an ordinary notes directory.

Agent working memory records the trajectory, and it is off by default

One feature is opt-in and is the most interesting idea in the list. Instead of saving the answer a task produced, it saves how the task was solved: a tool-call trajectory. That trajectory is then distilled into reusable pages, split into skills and cases, and a recall tool surfaces them the next time a similar task comes up. The distinction matters because answers go stale and procedures do not. If an agent worked out that a flaky test in this repository is caused by a specific ordering problem, the value is in the procedure, not in the patch it produced. The three-step flow is record, distil, recall, and it sits next to a lighter capture tool that saves a single atomic insight as one markdown file when you do not want the full pipeline. It is off by default and enabled with one slash command. That default is correct. Trajectory capture doubles what the agent writes and widens what the next retrieval can surface, so it should be something you turn on for a class of work rather than something that happens to everybody.

Deterministic projections, and a lint pass that can fix itself

Two features are about keeping the thing honest over time rather than adding capability. The first is determinism: indexes and logs are generated from the authoritative pages so that navigation and metadata stay reproducible, which means the same vault produces the same index twice and a diff in the index tells you something real. The second is a lint command that runs deterministic health checks and can auto-fix what it finds, looking for orphans, broken links, duplicate aliases, coverage gaps and stale captures. There is a status command for counts, source states and recent activity, and an update command that does not install a scheduler but prints a line you can paste into a task schedule, which is a nicely restrained choice for a package that would otherwise be adding a daemon to your machine. Together these four make the wiki maintainable rather than a write-only log. A knowledge base that only grows is a folder; one that reports its own orphans is a system.

The manifest reads 0.6.3 and the release tags read v0.12.5

Packaging details are where this project is loosest. The published version field in the manifest is 0.6.3, while three releases in the 0.12 line were published in the five days before this listing was assembled, with two of them on the same day. So the release tags run roughly six minor versions ahead of the manifest field, which is the opposite of the more common drift where the manifest is ahead of the last tag. Nothing in the readme explains it, and anyone automating an upgrade check will get the wrong answer. Two other observations from the tree. There are ten translated readme files, which is a real translation effort rather than a badge. And there is a configuration file for a static site generator alongside a code-reviewer directory and a review bot configuration, so documentation and review are both automated. Four open issues on 599 stars, and the change log is committed, which is what you want to read when deciding whether a jump from 0.6 to 0.12 is safe for you.

Editorial conclusion

pi-llm-wiki is aimed at a specific frustration that most file-based agent workflows have and do not name: synthesis is ephemeral. If your agent re-reads raw documents every time you ask a question, nothing it concluded last week survives, and the cost is paid on every subsequent query. This package inserts a middle layer so a conclusion becomes a page that can be cited, contradicted and linted later. The design detail I would copy first is the guardrail. Sources and generated indexes are immutable, and that is not a convention: a guard script ships inside the package specifically to block edits to them, alongside a script that runs at session start, which means the harness enforces the boundary rather than asking the model politely. What to weigh. It reaches two native hosts directly and everything else over a protocol, which is the right trade but adds the absolute-path requirement described below. The manifest version sits well behind the release tags, so pinning what you install needs a moment's thought. And the agent working-memory feature, which records how a task was solved rather than what it produced, is off by default and should stay that way until you trust the retrieval half. Confirm three things: that the personal vault location is acceptable on shared machines, whether your harness expands the home directory in server paths before you configure it, and that the pages you would rather the agent not touch are inside the boundary the guard script protects.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. zosmaai/pi-llm-wiki on GitHub