Pi Honcho

Durable, privacy-aware memory for Pi, powered by Honcho.

Pi Honcho carries useful context across conversations and repositories without putting remote work on the critical path of a Pi turn. It also includes exact local session search, Pi-native skill management, and standing instructions.

Features

• Cross-project user memory — remembers preferences and working style through one stable user peer.
• Repository memory — keeps project context in a repository- and stable-user-peer-scoped memory session shared by that peer's branches and worktrees.
• Automatic recall — adds bounded user and project context to top-level Pi turns as fenced reference material.
• Reliable delivery — sends completed exchanges asynchronously, in order, with durable retry and stable operation IDs.
• Fork continuity — clones remote history at Pi fork points while keeping later branches isolated.
• Exact local recall — searches existing Pi session JSONL with SQLite FTS5.
• Pi-native skills — creates and manages discoverable global and project SKILL.md files.
• Standing instructions — injects user-pinned rules on every turn, independent of remote recall.
• Privacy controls — blocks recognized secrets, supports trusted project opt-out, and hides remote tools when unavailable.

Requirements

• Pi with package support
• A Honcho API key or browser sign-in for remote memory

Local session search, skills, and standing instructions work without Honcho credentials.

Install

Install from npm:

pi install npm:pi-honcho

Install from the public Git repository:

pi install git:github.com/giuseppecrj/pi-honcho

Install from a local checkout:

pi install /absolute/path/to/pi-honcho

Use -l for a project-local installation:

pi install -l /absolute/path/to/pi-honcho

Restart Pi after installation. Pi packages execute with your user account's permissions, so review package source before installing it.

Quick start

Set your Honcho API key outside Pi's chat and session files, or sign in from Pi:

export HONCHO_API_KEY="your-api-key"
pi

/honcho login

Configure a stable workspace and user peer, then check the connection:

/honcho init
/honcho setup
/honcho status

Once connected, memory works automatically. Pi retrieves cached context when a session starts and sends each completed user/assistant exchange in the background.

How memory works

Pi Honcho uses two remote scopes:

• User peer — preferences and working style shared across projects.
• Memory session — conversation history and derived context for one repository and stable user peer. Branches and worktrees for that peer share the repository session.

New unmapped Pi conversations use a new opaque repo-v2- repository session. Pi histories with a stored remote-session mapping continue to use that mapping. Pi Honcho never automatically searches, merges, or deletes legacy sessions.

At session start, the extension retrieves a cached user representation and project summary. It supplies that memory to the current model call as bounded, untrusted reference material. After a turn completes, it queues the submitted user prompt and completed text assistant response for ordered background delivery.

Herdr subagents identified by PI_SUBAGENT_ID do not start remote Honcho behavior. They neither recall nor deliver memory, so synthetic assignments cannot affect the user peer. User-controlled top-level conversations, including forks and worktree handoffs, retain automatic memory.

Remote startup, recall, delivery, and retry do not block normal Pi operation. If Honcho is offline or disabled, Pi continues and local knowledge tools remain available.

Conversation lifecycle

The ledger records are local Pi session entries. Recalled context stays in the running extension and is supplied only to a model call; it is not appended to the Pi session.

Commands

Command	Action
/honcho or /honcho help	Show command help and current status.
/honcho status	Show connection, repository-memory, workspace, peer, and repository-session status.
/honcho init	Select or create a workspace and initialize the current trusted repository.
/honcho login	Sign in to Honcho in your browser.
/honcho setup	Change the stable user and Pi identities.
/honcho enable	Enable memory for an initialized trusted repository.
/honcho disable	Immediately stop recall, delivery, clients, and tools for an initialized trusted repository.
/honcho session delete	Confirm deletion of the active repository session.
/memory-pin	List, add, remove, or clear standing instructions.

Direct command aliases are also available: /honcho-status, /honcho-init, /honcho-login, /honcho-setup, /honcho-enable, /honcho-disable, and /honcho-session-delete.

Standing-instruction examples:

/memory-pin Always run focused tests before the full suite
/memory-pin list
/memory-pin remove 1
/memory-pin clear

Tools

Honcho tools

These tools are available only while the Honcho connection is healthy and the current repository is enabled.

Tool	Purpose
honcho_search	Search bounded remote project memory.
honcho_chat	Ask a bounded question about connected remote memory.
honcho_remember	Save a conclusion when the user explicitly asks Pi to remember it.

Local knowledge tools

These tools do not require Honcho and remain available offline.

Tool	Purpose
session_search	Search local Pi sessions by text, project, role, result count, and snippet size.
skill_manage	Create, view, patch, update, and delete global or project Pi skills. Use view without a skill ID to list them.

session_search treats Pi session JSONL as its source and keeps a rebuildable SQLite FTS5 index under the Pi agent directory. skill_manage writes ordinary SKILL.md files that Pi discovers through its resource lifecycle.

Configuration

You can configure Honcho with an API key or /honcho login. Browser sign-in requires a Honcho host that supports device authorization. Manual API-key configuration uses environment variables or ~/.honcho/config.json.

Credentials stay in ~/.honcho/config.json or environment variables. Pi stores its stable identity and repository mappings in honcho-memory.json under PI_CODING_AGENT_DIR (default ~/.pi/agent), separate from credentials.

Pi Honcho can use a workspace-scoped API key. Peer- and session-scoped keys are insufficient because Pi Honcho operates across two peers and a memory session. You need an admin key to mint scoped keys, not for routine memory operations.

A repository is uninitialized until you run /honcho init from a trusted project. /honcho status then tells you to run /honcho init and does not show a workspace. The registry uses the canonical Git origin when available and the resolved directory outside Git. /honcho disable retains the workspace mapping. /honcho enable restores it. Legacy workspace settings and .pi/honcho-memory.json project-policy files do not activate memory.

Pi uses user and pi as the default peer IDs. Use /honcho setup to change them. Pi confirms an identity change when it affects initialized repositories.

Workspace IDs must contain only letters, digits, _, and -, for example pi-user_1. Pi rejects invalid IDs without changing them.

Environment variables

Variable	Purpose	Default
HONCHO_API_KEY	Honcho API key.	Required unless present in Honcho config.
HONCHO_BASE_URL	Honcho API endpoint override.	Honcho SDK default.
HONCHO_ENABLED	Set to false or 0 to disable remote memory.	Enabled for an enabled repository when credentials exist.
HONCHO_MAX_MESSAGE_LENGTH	Maximum safe message chunk size.	8000
PI_CODING_AGENT_DIR	Pi agent data directory used by local knowledge tools.	~/.pi/agent

Restart or reload Pi after changing API-key credentials or environment configuration. Use /honcho login for browser sign-in, and /honcho init, /honcho enable, and /honcho disable to change the repository lifecycle.

Privacy and data lifecycle

The automatic remote-write unit is one finalized exchange: the submitted user prompt plus its completed text assistant response.

The extension does not independently upload:

• Tool calls or tool output
• Shell history
• Source files or images
• System prompts or standing instructions
• Model thinking
• Aborted or incomplete turns
• Pi-native skills

Text that the user includes in a submitted prompt, or that Pi includes in its completed text response, is part of the finalized exchange. A recognized secret or private key on either side rejects the complete exchange before delivery. The detected value is not logged.

Remote deletion is explicit and confirmed. It never deletes local Pi sessions, skills, or standing instructions. Pending exchanges stay in Pi's session ledger for ordered retry, and remote acknowledgements make recovery idempotent.

Offline behavior

When Honcho is unavailable, unconfigured, or disabled:

• Pi starts and continues normally.
• Honcho tools are hidden.
• Remote memory is not injected.
• Pending delivery can resume after a healthy connection returns.
• session_search, skill_manage, and /memory-pin remain local and available.

Use /honcho status to inspect the current connection and policy state.

Package structure

The package registers one Pi extension composition root:

Module	Responsibility
src/index.ts	Package composition root that registers the remote module, then the local module.
src/remote/index.ts	Honcho lifecycle, delivery, recall, remote tools, and /honcho commands.
src/local/index.ts	Exact local recall, Pi-native skills, and standing instructions.

Development

npm ci
npm run check
npm run verify
pi -e . --list-models

npm run verify runs type checking, linting, and the complete test suite.

License

MIT. See LICENSE and THIRD_PARTY_NOTICES.md.