The Embedding Pattern (Honcho): Retrieve by Similarity

+15 Mana ✨
Honcho documentation(DOCUMENTATION)

Introduction

When the fact set grows past what fits in a small Markdown file, plain file-based memory hits a wall. You need a way to surface the right fact based on the topic of the current question, not by scanning the whole file. That is what embedding-based providers do, and Honcho is the canonical example in the Hermes ecosystem.

Key Concepts

  • Embedding: A vector representation of text that captures meaning numerically.
  • Vector store: A specialized database that indexes embeddings for nearest-neighbor search.
  • Similarity retrieval: Given a query, return the stored facts whose embeddings are closest to the query's embedding.
  • Recall by meaning, not exact words: "How do I run tests?" can retrieve a fact saved as "the test command is pnpm test" without keyword overlap.

Real World Context

A customer support agent has logged 2,400 past interactions for a single user. A new question arrives: "my export is empty." The system needs to surface the three prior tickets about CSV export bugs, even though the new wording does not match the old wording exactly. Embedding retrieval is the standard tool for this kind of work, and it is what Honcho brings to Hermes.

Deep Dive

The embedding flow is straightforward in principle:

text
Write path:                       Read path:
  fact text                          current question
     ↓ embedding model                  ↓ embedding model
  vector (~1536 dims)                vector
     ↓                                  ↓ similarity search
  vector store                       top-k stored facts
                                        ↓
                                     injected into the prompt

What makes this powerful: the model never has to scroll through every fact. The vector store finds the most relevant entries by cosine similarity (or a related metric) and Hermes injects just those into the current prompt. Storage scales to millions of entries without per-turn token cost ballooning.

What makes this expensive: every fact you store has to be embedded (one model call), the vector store has to be hosted somewhere (managed service or self-hosted), and every retrieval pays an embedding latency. For five preferences, this is overkill. For 2,400 support tickets, it is the only sane option.

Honchu is one of several embedding providers Hermes integrates with. Others in the same archetype include Mem0 and Supermemory. They differ in details (managed vs self-hosted, what they do with metadata, how they handle user namespaces) but share the underlying pattern: write embeddings, retrieve by similarity, inject the top-k.

The practical implication for you is that if your use case is "a personal agent for a developer", you almost certainly do not need this. If your use case is "an agent that serves many users with deep history", you almost certainly do.

Common Pitfalls

  1. Forgetting that similarity is not understanding: Two facts can be near each other in vector space and still both be wrong for the question. Always treat retrieval as a hint, not a guarantee.
  2. Adding everything as a separate entry: The vector store will happily store ten near-duplicate entries, all of which match the next query, all of which spend tokens. Consolidate before writing.

Best Practices

  1. Use embedding providers when you cannot enumerate facts in advance: If you cannot list what to remember today, you need similarity retrieval tomorrow.
  2. Pair with a namespace: When serving multiple users, ensure each user has an isolated vector space so retrieval does not cross profiles.

Summary

  • Embedding-based memory stores facts as vectors and retrieves them by similarity.
  • Honcho is the canonical example in Hermes; Mem0, Supermemory, and others follow the same archetype.
  • It scales to many facts but adds embedding-model latency and vector-store cost.
  • Use it when the fact set is large and the retrieval pattern is "find me things about this topic".

Code Examples

yaml
# ~/.hermes/config.yaml
memory:
  provider: honcho
  honcho:
    base_url: https://api.honcho.dev
    api_key: ${HONCHO_API_KEY}
    user_namespace: olivier-personal  # isolate facts per user
✓ Completed