@theokit/memory-honcho

Honcho memory adapter for @theokit/sdk.

Wraps @honcho-ai/sdk@^2 (zod peer-dep) with the MemoryAdapter contract from ADR D141. Honcho's differentiator is dialectic reasoning — recall returns ONE synthesized answer about the user, not a list of raw facts.

Install

pnpm add @theokit/memory-honcho @honcho-ai/sdk

Usage

import { Agent } from "@theokit/sdk";
import { honchoMemory } from "@theokit/memory-honcho";

const agent = await Agent.create({
  apiKey: process.env.OPENROUTER_API_KEY,
  model: { id: "openai/gpt-4o-mini" },
  local: {},
  plugins: [honchoMemory({
    apiKey: process.env.HONCHO_API_KEY!,
    workspaceId: process.env.HONCHO_WORKSPACE_ID,
  })],
  memoryContext: { userId: "alice" },
});

// Persist a turn
await agent.memory.write("User likes Brazilian jazz", { userId: "alice" });

// Recall: returns ONE synthesized reasoning answer (Honcho dialectic)
const [answer] = await agent.memory.recall(
  "What music does the user like?",
  { userId: "alice" },
);
console.log(answer.content);

Options

| Field | Type | Default | Description | |---|---|---|---| | apiKey | string | — | Honcho API key. Required. | | workspaceId | string | env HONCHO_WORKSPACE_ID | Workspace scope. | | baseUrl | string | Honcho cloud | Override for self-hosted Honcho. |

Session namespacing (EC-D)

Honcho sessions are workspace-scoped. To prevent cross-user contamination, this adapter prefixes every session key with userId:

• agent.memory.write(content, { userId: "alice" }) → session "alice:default"
• agent.memory.write(content, { userId: "alice", sessionId: "chat42" }) → session "alice:chat42"
• agent.memory.write(content, { userId: "bob" }) → session "bob:default"

Two users without sessionId land in distinct sessions automatically.

License & Self-Hosting

This adapter is licensed Apache-2.0.

Note on Honcho self-hosting: the Honcho server itself is licensed AGPL-3.0. When you use the managed Honcho cloud at app.honcho.dev, your application is unaffected (the network use clause applies to Honcho Inc.'s deployment, not yours). When you self-host Honcho, the AGPL network-use trigger applies to YOUR deployment: any application that communicates with your self-hosted Honcho instance over a network may itself need to provide source under AGPL-3.0 terms, depending on interpretation.

If you self-host Honcho, consult your legal team before connecting proprietary or closed-source applications to it. The managed cloud avoids this concern entirely. The @honcho-ai/sdk npm client is Apache-2.0 (per its package.json), so consuming the SDK does not itself trigger AGPL.

Failure modes

| Honcho error | Maps to | isRetryable | |---|---|---| | AuthenticationError / 401 / 403 | MemoryAdapterError(code: "auth_failed") | false | | RateLimitError / 429 | MemoryAdapterError(code: "rate_limited") | true | | NotFoundError / 404 | MemoryAdapterError(code: "not_found") | false | | ConnectionError / TimeoutError | MemoryAdapterError(code: "network") | true | | Other | MemoryAdapterError(code: "unknown") | false |

Adapter semantics

• write calls session.addMessages([peer.message(text)]).
• recall calls peer.chat(query, { session }) — returns ONE synthesized reasoning answer wrapped as a MemoryFact with score: 1.0.
• delete throws — @honcho-ai/sdk@^2 does not expose a public message delete endpoint. Use the Honcho dashboard or wait for a future SDK version.
• capabilities.history === false and capabilities.reasoning === true.

License

Apache-2.0. See LICENSE.