# honcho-integration

A skill that walks an agent through adding Honcho memory to existing Python or TypeScript code. Useful when a chat bot has to remember a user across sessions.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 882 installs · ★ 7776
- Author: plastic-labs
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/plastic-labs/honcho/tree/HEAD/skills/honcho-integration/SKILL.md
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/skills/honcho-integration

## What it does

The skill gets an agent to wire Honcho, an open-source memory library for stateful agents, into a codebase that already exists in Python or TypeScript. It reads the repo first: finds LLM calls, user models, chat handlers. Then it runs a short interview with `AskUserQuestion` about which entities become peers, how conversations map to sessions, and how the model should read context.

Reference files open in step order: `references/core-patterns.md` for the client, peers and message storage, `references/agent-patterns.md` for tool call, pre-fetch and `context()` wiring, `references/bot-frameworks.md` for agent loops such as nanobot and openclaw. Allowed tools stay narrow — read, search, edit files, plus `uv`, `bun` and `npm` for installs.

How the memory behaves: your app sends messages, background reasoning builds a representation of each peer, and the agent pulls it back with `session.context()` or asks `peer.chat(query)`. `chat()` spends a few seconds reasoning live, so keep it for questions that need a reasoned answer and take `context()` per turn.

Get a Honcho API key from `app.honcho.dev` and put it in the environment before anything runs. The SDK is `honcho-ai` on Python, `@honcho-ai/sdk` on TypeScript. Bots with deterministic behaviour should get `observe_me=False`, otherwise Honcho models a peer that gains nothing from it. The project ships under AGPL-3.0.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add plastic-labs/honcho --skill honcho-integration -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/honcho-integration/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/honcho-integration/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add plastic-labs/honcho --skill honcho-integration -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/honcho-integration/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add plastic-labs/honcho --skill honcho-integration -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/honcho-integration/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install plastic-labs/honcho honcho-integration
```

2. **Manually: put the files in place**
- File: `.github/skills/honcho-integration/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add plastic-labs/honcho --skill honcho-integration -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/plastic-labs/honcho --path skills/honcho-integration
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/honcho-integration/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add plastic-labs/honcho --skill honcho-integration -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/plastic-labs/honcho/tree/HEAD/skills/honcho-integration/SKILL.md

## When to use it
- attach Honcho memory to an existing FastAPI or Express service
- map users and bots onto peers with the right observation flags
- connect Honcho sessions to chat threads the app already has
- pick between `session.context()` and `peer.chat()` for a given model call
- check key connectivity with `honcho doctor` before touching code

## Example prompts
- Add Honcho to our TypeScript project, make users and the assistant the peers.
- Fetch user context before each model call with `session.context()`.
- Run `honcho doctor` and show me that peers and sessions get created.

## Similar
- [claude-sdk-integration-patterns](https://affpapa.org/en/nevibecode/skills/claude-sdk-integration-patterns.md) — skill · 434 installs
- [build-with-exa](https://affpapa.org/en/nevibecode/skills/build-with-exa.md) — skill · 3600 installs
- [api-integration-surface-strategy](https://affpapa.org/en/nevibecode/skills/api-integration-surface-strategy.md) — skill · 8000 installs
- [apify-integration-expert](https://affpapa.org/en/nevibecode/agents/apify-integration-expert.md) — subagent · 222 installs
- [memory-engineering](https://affpapa.org/en/nevibecode/skills/memory-engineering.md) — skill · 29 installs
- [ontology](https://affpapa.org/en/nevibecode/skills/ontology.md) — skill · 3700 installs

From the same set: [plastic-labs/honcho](https://affpapa.org/en/nevibecode/by/plastic-labs/honcho.md) — 3 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md