---

name: honcho description: "Router for Honcho self-hosting, integrations, CLI usage, and maintenance workflows." metadata: disco-role: operating disable-model-invocation: true license: AGPL 3.0

Honcho

Honcho is a peer/session/message memory system with a FastAPI API, a background worker for memory formation and consolidation, Python and TypeScript SDKs, and a terminal CLI.

Use this repo skill when a user asks about Honcho configuration, startup, client integration, memory-model behavior, CLI inspection, repository testing, or release maintenance.

Start here

• Use sub-skills/self-hosting/ when the task is about running the API, deriver worker, database, Redis, embeddings, keys, or startup validation.
• Use sub-skills/integrations/ when the task is about the Python SDK, TypeScript SDK, REST routes, memory reads/writes, session context, chat, or webhooks.
• Use sub-skills/cli-operations/ when the task is about the honcho CLI, honcho init, honcho doctor, config files, or command output.
• Use sub-skills/maintenance/ when the task is about tests, type checks, versioning, release hygiene, or repo scripts.

If you need a quick surface summary, run scripts/surface_report.py from a Honcho checkout.

Core mental model

Honcho centers on four public concepts:

• Workspace: the top-level tenancy boundary.
• Peer: any participant, human or AI.
• Session: a conversation thread shared by one or more peers.
• Message / conclusion: the raw turns and the derived observations that feed peer representations.

The API server handles requests and queues work; the deriver and dreamer run in the background. Reads such as session.context() and peer.representation() are cheap. Live reasoning through peer.chat() is slower and should be used when a plain read is not enough.

Reference map

Read these files when you need the fuller details:

• references/core-model.md — workspace/peer/session/message/conclusion model and the server/worker split.
• references/configuration-and-environment.md — config precedence, env vars, database and vector-store settings, and runtime defaults.
• references/api-route-map.md — grouped /v3 route families and what each one is for.
• references/cli-reference.md — honcho command groups, config file behavior, scope flags, JSON output, and exit-code expectations.
• references/development-and-testing.md — tests, type checks, SDK checks, and release-adjacent maintenance commands.
• references/troubleshooting.md — common startup, auth, config, scope, and backend failures.
• references/repo-provenance.md — source revision and evidence trail.
• references/repo-routing-metadata.json — managed router metadata for downstream import.

Routing guide

If the user asks about…	Go to
Local API startup, DB/Redis, embeddings, keys, or queue health	sub-skills/self-hosting/
Python SDK, TypeScript SDK, REST routes, memory reads/writes, or webhooks	sub-skills/integrations/
honcho CLI commands, init, doctor, config, or JSON output	sub-skills/cli-operations/
Tests, scripts, type checking, versioning, or release maintenance	sub-skills/maintenance/

Good defaults

• Prefer the narrowest sub-skill that owns the workflow.
• Use the references before guessing at command flags or route names.
• Keep examples and command snippets inside this skill tree.
• Treat live reasoning, external providers, and remote vector stores as optional runtime surfaces unless the request explicitly needs them.

Common signals

• honcho doctor is the fastest CLI health check.
• honcho peer inspect and honcho session context are the quickest memory inspection commands.
• uv run pytest tests/ is the broad Python test command, but maintenance tasks should usually start with a smaller targeted subset.
• uv run pytest tests/ -k typescript is the supported TypeScript SDK test path from the monorepo root.
• cd sdks/typescript && bun run tsc --noEmit is the direct TypeScript SDK type-check command.

Troubleshooting shortcuts

• If startup fails, check DB connectivity, embedding dimensions, and vector store configuration first.
• If CLI output looks human-readable when you expected JSON, add --json or pipe the command.
• If SDK or REST calls fail with scope errors, confirm the workspace, peer, and session IDs match the request.
• If tests fail in a live provider suite, confirm credentials and model env vars before changing code.

Self-containment

This skill is intended to stand on its own. Runtime links stay inside this skill tree, and bundled references/scripts capture the practical details a future agent needs without reopening the source repository.