# Honcho [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/plastic-labs/honcho  
**GitHub Stars:** 7734  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/honcho

## Description
Memory that reasons: continual learning for stateful agents. Better context, fewer tokens.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "honcho": {
    "command": "uvx",
    "args": ["honcho-ai"],
    "env": {
      "HONCHO_API_KEY": "",
      "HONCHO_URL": ""
    }
  }
}
```

**Requires environment variables:** `HONCHO_API_KEY`, `HONCHO_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Honcho MCP server does

Honcho provides memory infrastructure for stateful agents. It organizes data into workspaces, peers, and sessions: peers represent entities such as users or agents, while sessions contain messages, documents, events, or tool traces. Background processing turns that activity into representations that agents can query later.

The MCP integration is intended for coding agents and other MCP clients that need durable context. Honcho supports both a managed service at `api.honcho.dev` and deployments that run locally or are self-hosted from the project’s FastAPI service.

## How it works

The system follows a store, reason, query, and inject workflow. An application or agent first records messages and other events on a session. Honcho then processes the queue asynchronously and updates its peer-level representations.

Agents can query those representations directly, request a natural-language response, retrieve session context formatted for model use, or search stored information. Workspace-wide and peer- or session-specific queries are supported. Because reasoning runs in the background, newly added messages may not be immediately available through chat or representation responses; static representation reads are intended for lower-latency access.

Honcho can model relationships between multiple peers when configured, including what one peer knows about another. Its search API combines BM25 and vector search.

## Setup and configuration

A managed workspace can be created through the Honcho application, which provides an API key and a dedicated instance. Local use starts with the Honcho CLI and can point SDK clients at `http://localhost:8000`; the hosted service is the default endpoint for the Python SDK.

Set `HONCHO_API_KEY` for authenticated access. Set `HONCHO_URL` when using a self-hosted or local endpoint instead of the managed service. Python and TypeScript clients are available through the `honcho-ai` and `@honcho-ai/sdk` packages.

The repository also includes a CLI for starting a local stack, inspecting a workspace, and running diagnostics. MCP-oriented integrations share the configuration stored in `~/.honcho/config.json`.

## Tools and capabilities

- Store messages on sessions for persistent interaction history.
- Ask a peer or workspace-wide memory questions with chat APIs.
- Retrieve prompt-ready session context for OpenAI or Anthropic message formats.
- Search peers, sessions, or workspaces using hybrid BM25 and vector retrieval.
- Read peer and session representations for lower-latency context access.
- Upload documents to sessions and inspect background queue status.

## Limitations and notes

Background reasoning is asynchronous, so recent writes may require a short delay before they appear in chat or representation results. Honcho is a memory and context layer rather than a replacement for the model that ultimately generates an agent’s response; retrieved results are intended to be passed into an LLM or agent framework.

_Full upstream README: https://allmcps.com/mcp/honcho/readme_