mirror of
https://github.com/bytedance/deer-flow.git
synced 2026-09-09 21:49:37 +00:00
docs(memory): document the Honcho backend (#4822)
The Honcho backend landed in #4730 without user-facing docs: the main README's Long-Term Memory section covers the other opt-in backends (mem0, openviking) but never mentions honcho, and unlike mem0 the backend shipped no guide README. - Add backends/honcho/README.md mirroring the mem0 guide structure: configuration (with the plain-HTTP api_key guard), workspace-per-user isolation and fail-closed identity, recall/search behavior per mode, limitations (no fact CRUD -> gateway 501, no DeerMem migration), and async/failure-policy semantics. - Add a short honcho paragraph + guide link to the README Long-Term Memory section, alongside the existing mem0 paragraph.
This commit is contained in:
hataa
GitHub
parent
13fe06ee67
commit
3fa5e94c3b
@ -1187,6 +1187,14 @@ servers. Its token-bearing `base_url` must use HTTPS by default; plaintext HTTP
|
||||
requires an explicit local-development opt-in. See the
|
||||
[mem0 backend guide](backend/packages/harness/deerflow/agents/memory/backends/mem0/README.md).
|
||||
|
||||
An opt-in `honcho` backend is available for self-hosted or hosted Honcho (v3
|
||||
API). It builds user-model memory — long-term preferences and a cross-session
|
||||
working representation — on Honcho's server side, so the backend makes no LLM
|
||||
calls locally. Each user gets an isolated workspace derived from `user_id`; a
|
||||
missing user id fails closed instead of falling back to a shared workspace.
|
||||
Fact CRUD and Settings-page fact editing are not available for this backend. See
|
||||
the [Honcho backend guide](backend/packages/harness/deerflow/agents/memory/backends/honcho/README.md).
|
||||
|
||||
Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context do not accumulate endlessly across sessions.
|
||||
|
||||
In the default DeerMem `middleware` mode, automatic extraction now classifies every proposed fact by scope, durability, and authority before a deterministic write gate accepts it. Only durable, descriptive user-level facts are stored; current-thread or project constraints and one-time action permissions stay in conversation state. User-global summaries require both user scope and descriptive authority, contradiction removals are scope-gated, and a replacement-dependent removal is applied only when its replacement actually survives validation and storage. These classification labels are extraction-only metadata, add no extra LLM call, and are not written into the fact files. The explicit CRUD tools in `memory.mode: tool` remain a separate, model-directed path. Deployments that override the bundled DeerMem prompts via `memory.backend_config.prompts_dir` must add the new classification fields to their custom templates (the `memory_update` fact/summary/removal formats and the `consolidation` consolidated-fact schema): the write gate fails closed, so an un-migrated template stops every extraction-driven fact, summary, and removal write, surfacing only through the `rejected_by_scope_gate` metrics and the high-rejection-rate warning.
|
||||
|
||||
@ -0,0 +1,90 @@
|
||||
# Honcho memory backend
|
||||
|
||||
Uses Honcho (self-hosted or hosted, v3 API) as DeerFlow's
|
||||
user-model memory store. Honcho covers the user dimension of memory — long-term
|
||||
user modeling, preferences, and a cross-session working representation — built
|
||||
by Honcho's own server-side deriver. Ingestion is cheap plain message writes;
|
||||
this backend makes **no LLM calls** locally.
|
||||
|
||||
## Configuration
|
||||
|
||||
```yaml
|
||||
memory:
|
||||
enabled: true
|
||||
injection_enabled: true
|
||||
manager_class: honcho
|
||||
mode: middleware # or "tool"
|
||||
backend_config:
|
||||
base_url: http://localhost:8000
|
||||
# api_key: $HONCHO_API_KEY # hosted Honcho; plain-http + api_key needs allow_insecure_http: true
|
||||
workspace_prefix: deerflow-u- # one isolated workspace per user id
|
||||
# workspace_overrides: {} # map specific user ids to custom workspaces
|
||||
# user_peer_overrides: {} # map specific user ids to custom peer names
|
||||
assistant_peer: deerflow
|
||||
message_char_limit: 8000
|
||||
max_injection_chars: 6000
|
||||
timeout_seconds: 10
|
||||
connect_timeout_seconds: 3
|
||||
failure_policy:
|
||||
read: fail_open # fail_open | fail_closed
|
||||
```
|
||||
|
||||
A configured `api_key` over a plain-`http://` base URL is rejected at startup
|
||||
unless you explicitly set `allow_insecure_http: true` (local-development opt-in,
|
||||
same posture as the mem0 backend). Use HTTPS for any non-local deployment.
|
||||
|
||||
Config errors (bad URL, insecure key combination) fail fast at Gateway startup;
|
||||
connectivity is deliberately not probed, so a temporarily unreachable Honcho
|
||||
does not block startup — reads then degrade per `failure_policy.read`.
|
||||
|
||||
## Multi-user isolation
|
||||
|
||||
Every operation resolves a workspace from `user_id`:
|
||||
`workspace_overrides[user_id]` on exact match, else
|
||||
`workspace_prefix + <stable id>`. The stable id is the sanitized user id plus
|
||||
an 8-hex-char SHA-256 suffix of the original id, so distinct raw ids that
|
||||
sanitize identically cannot silently merge into one workspace. Honcho scopes
|
||||
all queries to a single workspace, so under the default derivation users
|
||||
cannot see each other's memory by construction.
|
||||
|
||||
- A missing or empty `user_id` **fails closed**: writes become no-ops and reads
|
||||
return empty — there is never a shared fallback workspace.
|
||||
- A `workspace_overrides` entry deliberately shared across users shares that
|
||||
workspace's search index (`search` is workspace-scoped; `get_context` /
|
||||
`get_memory` stay peer-scoped).
|
||||
- Session ids reuse the same collision-resistant derivation
|
||||
(`df-` + stable id of `thread_id`).
|
||||
|
||||
## Recall and search
|
||||
|
||||
- `mode: middleware` recall is query-less: `get_context` fetches the user's
|
||||
working representation (up to 25 conclusions) and injects it truncated to
|
||||
`max_injection_chars`.
|
||||
- `mode: tool` adds query-aware `memory_search` backed by Honcho's
|
||||
workspace-scoped search, while the passive per-turn write middleware is
|
||||
retained because Honcho's deriver learns from `add()` writes.
|
||||
|
||||
## Limitations
|
||||
|
||||
- No DeerMem-style fact CRUD: `create_fact`/`delete_fact`/`update_fact`,
|
||||
`import_memory`, and Settings-page fact editing are not implemented
|
||||
(`get_memory` returns a minimal DeerMem-shaped document with the working
|
||||
representation as the `workContext` summary and an empty fact list).
|
||||
`memory_add`/`memory_update`/`memory_delete` return a clear
|
||||
unsupported-operation error; conversation writes still happen through the
|
||||
retained middleware. DeerMem remains the default backend.
|
||||
- No migration of existing DeerMem data.
|
||||
- Writes are fire-and-forget per call: a failed write is logged and dropped
|
||||
(at-most-once); nothing is buffered locally, so `shutdown_flush` is a no-op.
|
||||
- `agent_name` is not mapped — Honcho models the user, not per-agent facts.
|
||||
|
||||
## Async execution and failure behavior
|
||||
|
||||
The Honcho HTTP client is synchronous for compatibility with the
|
||||
`MemoryManager` contract. DeerFlow offloads it at every async boundary via
|
||||
`asyncio.to_thread` (the manager's `a*` methods), so a slow Honcho request
|
||||
never blocks ASGI handlers or SSE heartbeats.
|
||||
|
||||
`failure_policy.read: fail_open` (default) logs a recall failure and continues
|
||||
without new memory context. `fail_closed` propagates the backend error through
|
||||
prompt construction and aborts the run instead of silently degrading.
|
||||
Loading…
x
Reference in New Issue
Block a user