Honcho Plugin for Kilo Code

Add AI-native memory to Kilo Code

This plugin gives Kilo Code long-term memory that survives context wipes, session restarts and fresh chats. Honcho remembers what you work on, your durable preferences and prior context across projects. The plugin runs inside kilo serve, so it works in the Kilo CLI, the VS Code extension and the JetBrains plugin.

Quick Start

Step 1: Get Your Honcho API Key

1. Go to app.honcho.dev
2. Sign up or log in
3. Copy your API key

Step 2: Install the Plugin

kilo plugin @honcho-ai/kilo-honcho --global

kilo plugin installs the package and adds it to the plugin list of Kilo's global config (the server half) and ~/.config/kilo/tui.json (the /honcho:* commands). It still uses Kilo's older opencode.json name for the server entry; Kilo reads kilo.jsonc, kilo.json and opencode.json alike. To update an existing install, add --force. To add it by hand, put "@honcho-ai/kilo-honcho" in the plugin array of ~/.config/kilo/kilo.jsonc and ~/.config/kilo/tui.json.

For the Kilo desktop app or the VS Code and JetBrains extensions, install Honcho from the Kilo Marketplace, then type /honcho in the chat. The agent asks what name Honcho should call you and opens a window on your screen for your API key. You can skip Step 3.

Until Honcho is listed in the Kilo Marketplace, add "@honcho-ai/kilo-honcho" to the plugin array of ~/.config/kilo/kilo.jsonc yourself, creating the file if it does not exist. Restart Kilo, then type /honcho.

Step 3: Run Setup in Kilo

1. Start Kilo. The first time the plugin loads without an API key, it offers to set up Honcho.
2. Choose Set up now, or run /honcho:setup
3. Keep the default Honcho Cloud option unless you want a self-hosted or local endpoint
4. Enter your Honcho API key
5. Confirm the name Honcho should call you. Setup fills in the peerName your other Honcho tools use, or your OS user name.
6. Choose a workspace: Kilo's own, or one another Honcho tool already uses
7. Run /honcho:status to check the runtime

What You Get

• Persistent memory. Kilo keeps durable context across sessions.
• Hook-driven recall. Hooks add memory to the prompt and record significant tool activity, so recall works with any model.
• Honcho memory skill. A honcho-memory skill is installed into Kilo's skills directory, so the agent knows when to pull and save memory on its own.
• Cloud or local. Use Honcho Cloud, or point at a self-hosted or local Honcho instance.
• Session mapping. Sessions can be scoped per directory, repo, branch, chat instance or globally.
• Peer modeling. User and agent observation are configurable (observationMode, agentObserveMe).
• Visible recall. A Honcho section in Kilo's sidebar shows what Honcho added to the session, and /honcho:recall shows the exact text.

Configuration

Configuration lives in the shared file ~/.honcho/config.json, which other Honcho plugins also read. Kilo-specific settings live under hosts.kilo.

{
  "apiKey": "hch-...",
  "peerName": "user",
  "baseUrl": "https://api.honcho.dev",
  "hosts": {
    "kilo": {
      "workspace": "kilo",
      "aiPeer": "kilo",
      "recallMode": "hybrid",
      "observationMode": "unified",
      "agentObserveMe": false,
      "autoConclusions": false,
      "sessionStrategy": "per-directory",
      "apiKey": "hch-..." // optional; overrides the root apiKey for Kilo
    }
  }
}

Set KILO_HONCHO_CONFIG_PATH to read and write a different file.

Cloud vs Local

For Honcho Cloud, apiKey is required and baseUrl stays https://api.honcho.dev.

For self-hosted or local Honcho, point baseUrl at your deployment, for example http://127.0.0.1:8000. apiKey is needed only if that deployment requires authentication. If Kilo runs in Docker or on another machine, localhost may not be your machine; the baseUrl must be reachable from where kilo serve runs.

Session Strategies

| Strategy | Behavior | Best for | | --- | --- | --- | | per-directory | One session per working directory | Default project memory | | per-repo | One session per repository | Repos with several entry directories | | git-branch | Session changes with the current branch | Branch-specific work | | per-session | New session for each Kilo session id | Short-lived isolated work | | chat-instance | Session follows the current chat instance | Very short-lived use | | global | One session for everything | Shared memory across all work |

Observation Mode

This decides which Honcho collection honcho_chat, honcho_create_conclusion and per-prompt recall use for the user.

| Mode | Collection | Best for | | --- | --- | --- | | unified (default) | The user's own collection (observer=user, observed=user) | Several agents sharing what they learn about you | | directional | This agent's view of the user (observer=aiPeer, observed=user) | Memory kept separate per agent |

In unified mode the agent peer does not observe the user, so Honcho derives each message once. If you switch to directional, the agent's view of you starts from the messages saved after the switch.

Peer name

Your peer is your peerName, unchanged, so Kilo uses the same peer as your other Honcho tools. Kilo reads HONCHO_PEER_NAME, then peerName in ~/.honcho/config.json, then your OS user name ($USER). Characters Honcho does not allow in ids become -. The plugin writes ~/.honcho/config.json only when you run setup or change a setting.

A peer belongs to one workspace. Kilo uses its own kilo workspace by default, so it starts with no memory of you. To share memory with another Honcho tool, choose that tool's workspace in /honcho:setup, or set hosts.kilo.workspace to it. This changes nothing for the other tool.

peerName and aiPeer must differ. If they match, Honcho calls fail with an error in the sidebar until you change one.

Agent self-observation

The agent peer is created with observeMe: false, so Honcho models you, not the assistant. Set agentObserveMe: true to give the agent its own representation.

Auto conclusions

Honcho derives conclusions from every saved message. With autoConclusions: true, the plugin also saves a prompt verbatim as a conclusion when it contains phrases such as "I prefer", "always", "never" or "remember that". The conclusion is available on the next prompt, before Honcho's deriver runs. It is off by default because it also saves prompts like "never mind, revert that".

Kilo CLI, Desktop App and IDE Extensions

Every Kilo client starts its own local Kilo server, and the plugin runs inside it. Recall, saving, the honcho_* tools and the /honcho command work in all of them. The sidebar section and the /honcho:* commands come from the terminal UI half, which only the Kilo CLI loads.

| | Kilo CLI | Desktop app, VS Code, JetBrains | | --- | --- | --- | | Setup | /honcho:setup, or Set up now on first load | /honcho, or yes to the agent's offer | | /honcho | Yes | Yes | | Honcho sidebar section and /honcho:* commands | Yes | No | | Check that Honcho is working | Sidebar, /honcho:status, /honcho:recall | /honcho |

Outside the CLI:

• The desktop app and editors opened from the Dock or an app launcher do not see shell-profile variables such as HONCHO_API_KEY. Save the key with setup.
• Each desktop chat runs in its own folder, so each chat is its own Honcho session. Memory of you carries across chats; honcho_search only searches the current session.
• The desktop app and the extensions bundle their own Kilo version, and read the same ~/.config/kilo and ~/.honcho/config.json as the CLI.

Seeing What Honcho Did

Kilo's sidebar shows Memory • Disabled when Kilo's own memory feature is off. The plugin adds a Honcho section directly below it:

Honcho
• Active
Peer: alice
Session: View in Honcho ↗
/honcho:recall

On Honcho Cloud, clicking View in Honcho opens the session in the Honcho dashboard, where you can read the saved messages and the conclusions. Any other Honcho server has no known dashboard address, so the sidebar shows the session name, shortened in the middle to fit. Clicking /honcho:recall opens the recall view. The section shows Not set up before /honcho:setup, and Error with the reason when a Honcho request fails.

/honcho:recall opens the exact text the model received. Kilo does not save this text in its session history.

The server half writes this record to ~/.honcho/kilo/sessions/<session id>.json with mode 600, and the TUI reads it. The sidebar and the /honcho:* commands belong to the Kilo CLI's terminal UI. The desktop app and the VS Code and JetBrains extensions do not load TUI plugins, so they show neither. When Honcho has no API key, the agent offers setup once per session.

Operator Commands

| Command | Description | | --- | --- | | /honcho | Set up Honcho from the chat, or show your peer, workspace, session link and latest recall. Every Kilo client lists it. | | /honcho:setup | First-time setup for cloud or local Honcho | | /honcho:status | Effective Honcho status for the current project | | /honcho:recall | The exact memory text Honcho added to the current session | | /honcho:settings | Effective config values and config paths | | /honcho:config | Edit shared Honcho fields in ~/.honcho/config.json | | /honcho:import | Preview or import local Kilo session history into Honcho |

The /honcho:* commands are part of the Kilo CLI only. /honcho is a prompt to the agent, so it uses a model call.

/honcho:import reads history through the Kilo SDK client, maps sessions with the same sessionStrategy as live capture, and uploads user and assistant text with the original timestamps. The first run is a dry run. Imported sessions are recorded in ~/.honcho/kilo-import-state.json and skipped next time.

Agent Tools

| Tool | Description | | --- | --- | | honcho_setup | Save the peer name and workspace, and ask for the API key in a window on the user's screen. A key never passes through the chat, and the saved key is never sent to a new server. | | honcho_status | Show effective runtime status | | honcho_get_config | Read effective and persisted settings | | honcho_set_config | Update a persisted shared setting. apiKey and baseUrl can only be changed by the user. | | honcho_search | Search the messages in the current Honcho session only | | honcho_chat | Ask Honcho a question answered by reasoning over memory | | honcho_create_conclusion | Save a durable fact about the user |

The agent cannot read Honcho's config. The plugin refuses any Kilo tool call that names ~/.honcho, the config file in use, or the session activity folder, and tells the agent to call honcho_status instead. It checks file paths and command text, so it stops an agent that means well, but not one that hides the path on purpose.

Plugin Surfaces

| Purpose | Kilo hook | | --- | --- | | Record your prompt, fetch prompt-specific recall | chat.message | | Attach recall to the request without saving it to Kilo's history | experimental.chat.messages.transform | | Memory instructions and a stable snapshot | experimental.chat.system.transform | | Continuity block during compaction | experimental.session.compacting | | Refuse tool calls that name Honcho's config | tool.execute.before | | Record significant tool activity | tool.execute.after | | HONCHO_URL and HONCHO_WORKSPACE_ID for shell tools (never the API key) | shell.env | | honcho_* tools | tool | | The /honcho command in every client | config | | Session start, assistant capture, cleanup | event | | Honcho sidebar section (TUI) | sidebar_content slot |

The packaged honcho-memory skill is copied to ~/.config/kilo/skills/honcho-memory ($XDG_CONFIG_HOME/kilo/skills/honcho-memory when that is set), which every Kilo client reads.

Remote and Headless Use

The plugin runs wherever Kilo's server runs, and reads ~/.honcho/config.json on that machine. When no window can open on your screen, finish setup on that machine in one of two ways:

• Run /honcho:setup in the Kilo CLI there, if that machine has it.

• Write ~/.honcho/config.json yourself with at least apiKey and peerName (see Configuration), then run chmod 600 ~/.honcho/config.json.

• VS Code Remote SSH, dev containers, Codespaces. Kilo's server runs on the remote machine, so it reads the remote's ~/.honcho/config.json, not your laptop's. Set Honcho up on the remote.

• Key window over SSH. On macOS and Windows, honcho_setup does not open the key window in an SSH session, because it would appear on that machine's own screen. The agent tells you to finish setup one of the two ways above instead. On Linux it opens only when a display is available, including through X forwarding. An unanswered window closes after 2 minutes.

• CI and scripts. When the CI variable is set, the agent does not offer setup. Set HONCHO_API_KEY to use Honcho in CI, or KILO_PURE=1 to turn off every plugin.

Development

bun install
bun run check
bun run test

bun run build compiles the sidebar's JSX with @opentui/solid's Bun plugin. solid-js and @opentui/* stay external: Kilo rewrites those imports to its own copies when it loads the plugin, so the sidebar shares Kilo's Solid runtime.

To load a local build in Kilo, build it and point the plugin array at the server entry by file path. The exported plugin id makes a file-path entry valid:

{
  "plugin": ["file:///absolute/path/to/kilo-honcho/dist/server.js"]
}

Plugin logs appear in Kilo's log under service=kilo-honcho; run kilo run --print-logs to see them on stderr.