# Pi Experience

open-zk-kb ships as a native [Pi package](https://github.com/badlogic/pi-mono). It bridges the Bun-powered MCP server into Pi's tool system, preserves complete results for the model, and renders focused summaries for humans.

[Watch the complete 47-second demo](../assets/pi-demo.mp4), or install the package:

```bash
pi install npm:open-zk-kb
```

Bun remains required for the local MCP server and SQLite storage. Restart Pi after installation.

## Automatic Project Preferences

When a Pi session starts, the extension loads permanent preferences for the current project through `knowledge-context`. The preference capsule enters model context through the system prompt, so it is available before the model responds and does not require a model-initiated `knowledge-search` call.

Pi separately displays an honest, deduplicated session entry:

```text
knowledge-context
✓ 2 session preferences loaded automatically
```

This entry reports extension activity; it does not pretend that the model requested a tool call. Expand it to inspect the scopes and guidance that were loaded.

## Store a Preference

The agent stores one durable concept as a structured personalization note. Pi shows the title, summary, kind, and note ID while the complete server response remains available to the model.

<p align="center">
  <a href="../assets/pi-preference-store.png"><img src="../assets/pi-preference-store.png" alt="Storing a cooking-metaphor preference through knowledge-store in Pi" width="800"></a>
</p>

## Apply It in a Fresh Session

After `/new`, Pi automatically loads both the project preference and the newly stored cooking-metaphor preference. The Rust explanation applies the preference without a search call.

<p align="center">
  <a href="../assets/pi-preference-application.png"><img src="../assets/pi-preference-application.png" alt="A fresh Pi session automatically applying the stored preference" width="800"></a>
</p>

## Inspect Knowledge Base Health

`knowledge-health` summarizes scale and maintenance quality without flooding the terminal. This example contains 240 permanent notes across five knowledge kinds, complete embedding coverage, and healthy links.

<p align="center">
  <a href="../assets/pi-demo.png"><img src="../assets/pi-demo.png" alt="Pi rendering a healthy 240-note open-zk-kb project" width="800"></a>
</p>

## Remove a Preference

Preferences remain ordinary Markdown-backed knowledge notes. The agent can delete one through `knowledge-maintain`, and the next session refreshes its preference capsule.

<p align="center">
  <a href="../assets/pi-preference-removal.png"><img src="../assets/pi-preference-removal.png" alt="Removing a stored preference through knowledge-maintain in Pi" width="800"></a>
</p>

## Native Tool Rendering

The package registers all ten `knowledge-*` tools directly in Pi:

- `knowledge-store`, `knowledge-search`, `knowledge-get`, and `knowledge-template`
- `knowledge-context`, `knowledge-health`, and `knowledge-maintain`
- `knowledge-mine`, `knowledge-ingest`, and `knowledge-open`

Pi retains its native tool header and interaction shell. open-zk-kb supplies only knowledge-specific result content, with compact collapsed states and expanded detail where useful. Malformed responses and server errors fall back to complete raw output instead of hiding diagnostic information.

For installation and troubleshooting, see the [Setup Guide](setup-guide.md#pi-installation). For tool parameters and response behavior, see the [Tools Reference](tools-reference.md).