Honcho adds AI-native memory to Apus through an external plugin. It persists conversations to a dedicated service and builds user and agent models over time, giving your agent cross-session context that goes beyond workspace Markdown files.

What it provides

Available tools

Honcho registers tools the agent can use during conversation:

Data retrieval (fast, no LLM call):

Tool What it does
honcho_context Full user representation across sessions
honcho_search_conclusions Semantic search over stored conclusions
honcho_search_messages Find messages across sessions (filter by sender, date)
honcho_session Current session history and summary

Q&A (LLM-powered):

Tool What it does
honcho_ask Ask about the user. depth='quick' for facts, 'thorough' for synthesis

Getting started

Install the plugin and run setup:

apus plugins install @honcho-ai/apus-honcho
apus honcho setup
apus gateway --force

The setup command prompts for your API credentials, writes the config, and optionally migrates existing workspace memory files. The API key it asks for is issued by Honcho, not by Apus, and is only needed for the managed API at api.honcho.dev; a self-hosted Honcho deployment has no key to enter.

Honcho can run entirely locally (self-hosted) or via the managed API at api.honcho.dev. No external dependencies are required for the self-hosted option.

Configuration

Settings live under plugins.entries["apus-honcho"].config:

{
  plugins: {
    entries: {
      "apus-honcho": {
        config: {
          apiKey: "your-api-key", // omit for self-hosted
          workspaceId: "apus", // memory isolation
          baseUrl: "https://api.honcho.dev",
        },
      },
    },
  },
}

For self-hosted instances, point baseUrl to your local server (for example http://localhost:8000) and omit the API key.

Migrating existing memory

If you have existing workspace memory files (USER.md, MEMORY.md, IDENTITY.md, memory/), apus honcho setup detects and offers to migrate them.

Migration is non-destructive - files are uploaded to Honcho. Originals are never deleted or moved.

How it works

After every AI turn, the conversation is persisted to Honcho. Both user and agent messages are observed, letting Honcho build and refine its models over time.

During conversation, Honcho tools query the service during Apus's before_prompt_build plugin hook, injecting relevant context before the model sees the prompt.

Honcho vs builtin memory

Builtin memory Honcho
Storage Workspace Markdown files Dedicated service (local or hosted)
Cross-session Via memory files Automatic, built-in
User modeling Manual (write to MEMORY.md) Automatic profiles
Search Vector + keyword (hybrid) Semantic over observations
Multi-agent Not tracked Parent/child awareness
Dependencies None Plugin install

Honcho and the builtin memory system can work together. Builtin search keeps local Markdown available alongside Honcho's cross-session memory.

CLI commands

apus honcho setup                        # Configure API key and migrate files
apus honcho status                       # Check connection status
apus honcho ask <question>               # Query Honcho about the user
apus honcho search <query> [-k N] [-d D] # Semantic search over memory

Further reading

Related