# pi Coding Agent Extension

Give [pi](https://github.com/earendil-works/pi) cross-session long-term memory and context takeover. The extension is built on pi's native extension API (pi does not support MCP): recall happens automatically before every prompt, conversation turns are captured after every turn, and OpenViking can replace committed local history with an archive overview in pi's `context` hook.

Source: [examples/pi-coding-agent-extension](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension)

## How it works

- **Session start** injects your OpenViking profile block and restores takeover state, including the branch watermark used by `pi -c`.
- **Every prompt** runs semantic recall against the OpenViking server and injects matching memories as hidden context.
- **Every turn** captures user and assistant messages (including structured tool calls) into an OpenViking session; takeover mode commits once synced-token pressure crosses the threshold and then keeps only the recent live tail in model context.
- **Context takeover** is enabled by default. The `context` hook injects `[OpenViking Session Context]` from the latest archive overview before recall is added to the latest user turn.
- **Native tools** `viking_search`, `viking_read`, `viking_browse`, `viking_remember`, `viking_forget`, `viking_add_resource`, `viking_archive_expand` let the model query and update memory on demand.
- A footer status segment (`OV ✓ …`) shows connection and capture state; the `/viking` command prints status, and `/viking commit` forces a commit.
- Accidental `read`/`bash` calls on `viking://` URIs are blocked with a hint pointing back to `viking_read` / `viking_search`.

## Prerequisites

- pi coding agent (`npm i -g @earendil-works/pi-coding-agent`)
- An OpenViking HTTP server — verify with `curl http://localhost:1933/health`

## Install

pi shares the unified installer with the other memory plugins. It asks for your language, harnesses, download source, and OpenViking credentials; every step is idempotent.

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness pi
```

In regions where GitHub is hard to reach, run the same installer from the Volcengine TOS mirror:

```bash
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
```

The installer copies the extension into `~/.pi/agent/extensions/openviking` (preserving an existing `config.json`), registers it with `pi install`, and configures `~/.openviking/ovcli.conf`.

Manual copy from a repo checkout also works:

```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking
```

## Configure

Credentials resolve from `OPENVIKING_*` environment variables, then `~/.openviking/ovcli.conf`, then `~/.openviking/ov.conf` — shared with the Claude Code, Codex, and OpenCode plugins. Run the wizard once if you have not configured them yet:

```bash
node ~/.pi/agent/extensions/openviking/scripts/setup.mjs
```

`~/.pi/agent/extensions/openviking/config.json` holds behavior knobs only, and reinstalls preserve your edits:

```json
{
  "recallLimit": 6,
  "scoreThreshold": 0.35,
  "recallTokenBudget": 2000,
  "profileTokenBudget": 10000,
  "resumeContextBudget": 32000,
  "commitTokenThreshold": 20000,
  "commitKeepRecentCount": 10,
  "takeover": {
    "enabled": true,
    "tokenThreshold": 30000,
    "keepRecentTurns": 3,
    "overviewBudget": 3000,
    "overviewPollMs": 2000,
    "overviewPollMax": 15
  },
  "captureAssistantTurns": true,
  "bypassPatterns": []
}
```

Takeover is fail-open: if pending writes cannot flush, commit fails, the archive overview is not ready, or the branch fingerprint no longer matches, pi keeps full local history or falls back to its default compaction. Set `OV_DEBUG_LOG=/tmp/ov-pi.log` when validating boundary advances.

## Verify

Start `pi`. Once connected, the footer shows an `OV ✓` status segment, and `/viking` prints the current session mapping. Ask pi about something you mentioned in an earlier session to confirm recall.

## Troubleshooting

| Issue | What to check |
|-------|---------------|
| `OV ✗` in the footer or "server not reachable" | `curl http://localhost:1933/health`; check the endpoint in `~/.openviking/ovcli.conf` |
| Extension does not load | `pi list` should show `extensions/openviking`; re-run the installer or `pi install ~/.pi/agent/extensions/openviking` |
| Import errors mentioning `@mariozechner/*` | Stale copy from before pi's move to `@earendil-works/*` — re-run the installer |
| 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
| Recall is empty | Confirm the server has indexed memories and the prompt is longer than `minQueryLength` |

For the full tool, configuration, and design reference, see the [extension README](https://github.com/volcengine/OpenViking/tree/main/examples/pi-coding-agent-extension).