OpenViking Memory Extension for Pi Coding Agent

Long-term semantic memory for Pi sessions, powered by OpenViking. Recall happens automatically before every prompt, capture happens after every turn, and sessions are committed for persistent memory extraction — all via pi's native extension API.

Design informed by lessons from all three OpenViking agent plugins: synchronous recall from OpenClaw, production-hardened capture/ranking from Claude Code, and anti-patterns dodged from Hermes's stale prefetch approach. See DESIGN.md for the full design spec with comparison tables and event flow diagrams.

Quick Start

Prerequisites

• Pi coding agent installed (npm i -g @mariozechner/pi-coding-agent)
• Node.js 18+ (for the extension's TypeScript runtime)
• An OpenViking server reachable — local or remote

1. Have an OpenViking server reachable

Either run one locally or point at a remote one. The quickstart guide walks through both options. Default port is 1933; local mode runs without authentication.

Verify it's up:

curl http://localhost:1933/health   # or your remote URL

2. Install the extension

Copy the extension directory into pi's extension folder:

mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking

Pi auto-discovers extensions in ~/.pi/agent/extensions/ — no explicit registration needed. The extension loads on next pi invocation.

3. Configure (optional)

The extension ships with defaults that work out-of-the-box for a local OpenViking server (http://127.0.0.1:1933, no auth). To connect to a remote server or tune behavior, edit ~/.pi/agent/extensions/openviking/config.json:

{
  "enabled": true,
  "endpoint": "https://your-openviking-server.example.com",
  "apiKey": "<your-api-key>",
  "account": "my-team",
  "user": "alice",
  "agentId": "pi"
}

All config fields can also be overridden via environment variables:

Env vars take priority over config.json.

4. Start Pi

pi

The extension shows an [OpenViking] status line on startup. Tools (viking_search, viking_remember, etc.) are registered automatically. Memories persist across sessions — no additional setup.

Configuration Reference

Tuning fields

All fields below live in config.json. Defaults are shown.

Recall tuning

Capture tuning

Injection tuning

Misc

Architecture

┌──────────────────────────────────────────────────────┐
│                    Pi Coding Agent                    │
│                                                      │
│  session_start  before_agent_start  context  turn_end│
│  session_before_compact  session_shutdown            │
└────────┬──────────────────┬───────────┬──────────────┘
         │                  │           │
         │  ┌───────────────▼───────────▼────────┐
         │  │   extension modules (.ts)           │
         │  │   client / sync / recall / tools    │──────►  OpenViking
         │  └─────────────────────────────────────┘        Server
         │                                                (HTTP API)
         │  ┌──────────────────────────────────────┐
         └──►  7 registered LLM tools              │
            │  viking_search / viking_read / …     │
            └──────────────────────────────────────┘

The extension is a single directory of TypeScript files loaded by pi's jiti transpiler — no build step, no npm dependencies, no MCP server. All communication goes over HTTP to the OpenViking REST API.

Event Flow

Recall: Synchronous, Not Stale

Unlike Hermes's stale prefetch (recall from previous turn's query, injected one turn late), this extension searches OpenViking with the current user prompt via pi's context event. Results are injected into the same turn as <relevant-memories> blocks. This means:

• First turn of a session gets relevant context immediately
• Topic switches within a session get correct recall
• No waiting for the next turn to see relevant memories

Memory Pollution Prevention

Before pushing turns to OpenViking, the extension strips injected context blocks (<openviking-context>, <relevant-memories>, ``) to prevent a self-referential pollution loop where recall context is captured back as user messages.

Tool Use Preservation

Tool capture preserves agent-authored inputs ([tool: read]\n<path>) and drops raw tool results by default. The memory extractor sees what the agent did, not megabytes of raw output.

LLM Tools

The extension registers 7 tools that pi's model can invoke on demand:

The canonical /viking command (type /viking in pi's chat) displays connection status, session info, and accepts commit for manual synchronous commit.

Compared to Pi's Built-in Memory

Pi has a built-in MEMORY.md file system. This extension complements it:

Compared to Claude Code Plugin

Both plugins share the same core design (informed by each other):

Extension Structure

See DESIGN.md for the full design specification — comparison of all three OV plugins, detailed event flow, design rationale, and implementation guidance useful for building OV extensions for any agent harness.

pi-coding-agent-extension/
├── config.json          # Default configuration (edit to customize)
├── config.ts            # Config loader (defaults + config.json merge)
├── client.ts            # OpenViking HTTP client (fetch + response envelope)
├── sync.ts              # Turn capture, write queue, session lifecycle
├── recall.ts            # Synchronous recall with ranking + budget
├── tools.ts             # 7 registered LLM tools + /viking command
├── index-builder.ts     # Memory index builder (knowledge map)
├── index.ts             # Extension entry point (event handlers)
└── README.md

All TypeScript files are loaded directly by pi's built-in jiti transpiler — zero dependencies beyond Node.js.

Troubleshooting

License

Apache-2.0 — same as OpenViking.