@nanpaidashi/dsh-honcho-sync

Honcho Memory Plugin for DeepSeek Harness — give your AI persistent, cross-session memory backed by a self-hosted Honcho v3 service.

中文 | English

---

What it does

• Auto-sync: Every conversation turn is automatically synced to Honcho (with debounce). Sync cursors persist across restarts.
• Hybrid recall: Semantic search across both raw messages AND reasoned conclusions (explicit/deductive/inductive) in parallel.
• Memory injection: On session start, relevant peer cards, representations, and semantic recall results are injected into the system prompt.
• 25 tools: Full Honcho v3 API surface exposed as DSH tools — search, profile, session management, peer management, conclusions, dreaming, queue monitoring.

Requirements

• DeepSeek Harness (DSH) with web profile
• A running Honcho v3 instance (self-hosted)
• Node.js >= 18

Installation

# From npm
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web

# Or from GitHub
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

Then restart DSH:

systemctl --user restart dsh-web
# or: dsh web --restart

Upgrading

If you installed an earlier version (v0.6.x or v0.7.0):

# Re-run the same install command — it pulls the latest version and overwrites
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web
# or
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

systemctl --user restart dsh-web

The install is idempotent: it replaces the plugin source file in place. Your configuration (settings panel) and sync state (~/.dsh/honcho-sync-state.json) are preserved — no data loss, no re-configuration needed.

v0.8.0 → v0.8.1 changelog

• Context efficiency: Reduced registered tools from 25 to 4 (honcho_recall, honcho_ask, honcho_remember, honcho_context) — saves ~7K tokens of tool schema injection per session
• Injection quality: Added _filterRepresentation() — removes Pattern [medium]/[low] blocks, Premises/Sources provenance chains, and orphan Type/Sources lines from representation injection
• Injection quality: Added _assembleByPriority() — assembles memory-context parts by priority (peer-card > session-summary > semantic-recall > representation) instead of fixed order
• Injection budget: injectionMaxChars default 8000 → 4000, reprMaxObs default 8 → 4
• Tool descriptions: Shortened all tool descriptions to ~100 chars

v0.7.x → v0.8.0 changelog

• DSH 0.1.0-rc.8 compatibility: Added normalizeToolParameters() to convert legacy parameter shorthand to standard JSON Schema
• DSH 0.1.0-rc.8 compatibility: Added output.render returning content blocks array (required by DSH >= 2026)
• README: Removed settings panel references — configuration is done via environment variables in ~/.config/systemd/user/dsh-web.service
• Fixed conclusions/query requiring filters parameter
• Fixed response parsing for /search, /peers/list, /summaries
• Fixed POST /conclusions body format
• Fixed schedule_dream parameter name (dream_type)
• Added 4 tools: honcho_conclude, honcho_conclude_list, honcho_conclude_query, honcho_message_get
• Hybrid recall now searches messages + conclusions in parallel

Uninstalling

# 1. Remove the plugin from DSH
dsh plugin --profile web remove honcho-sync dsh web

# 2. (Optional) Remove sync state file
rm ~/.dsh/honcho-sync-state.json

# 3. Restart DSH
systemctl --user restart dsh-web

Note: Removing the plugin does NOT delete your Honcho data. All messages, conclusions, and peer cards remain on your Honcho server. The plugin is just the bridge — your memory is safe.

Configuration

There is no settings panel. All configuration is done via environment variables in your DSH service file.

Step 1: Edit the DSH service file

# For systemd (Linux)
nano ~/.config/systemd/user/dsh-web.service

Add these environment variables to the [Service] section:

[Service]
Environment="HONCHO_URL=http://localhost:8000"
Environment="HONCHO_WORKSPACE=my-workspace"
Environment="HONCHO_USER_PEER=user"
Environment="HONCHO_AGENT_PEER=agent"

Step 2: Apply the changes

systemctl --user daemon-reload
systemctl --user restart dsh-web

Configuration reference

| Variable | Description | Default | |----------|-------------|---------| | HONCHO_URL | Honcho API base URL | (required) | | HONCHO_WORKSPACE | Honcho workspace name | (required) | | HONCHO_USER_PEER | Peer ID representing the user | user | | HONCHO_AGENT_PEER | Peer ID representing the agent | agent |

Note: Advanced options (debounce, recall budget, timeouts) use sensible defaults and rarely need tuning. If you do need to customize them, edit the DEFAULTS object at the top of src/index.mjs.

Honcho Server Setup

If you don't have Honcho running yet:

# Quick start with Docker
docker run -d --name honcho \
  -p 8000:8000 \
  -e HONCHO_API_KEY="your-api-key" \
  plasticlabs/honcho:latest

# Or self-host from source (recommended for production)
# See: https://github.com/plastic-labs/honcho#self-hosting

Create a workspace and peers:

curl -X POST http://localhost:8000/v3/workspaces/my-workspace \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json"

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user"}'

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "agent"}'

Tools

Memory

| Tool | Description | |------|-------------| | honcho_recall | Hybrid semantic search (messages + conclusions). Fast (2-5s). | | honcho_ask | Deep dialectic reasoning with a peer. Slower (2-5min) but thorough. | | honcho_remember | Save a fact/statement to Honcho memory. | | honcho_context | Get compressed conversation context for a session. |

Search

| Tool | Description | |------|-------------| | honcho_search | Search across ALL sessions (no date filter). | | honcho_session_search | Search within a specific session. |

Profile

| Tool | Description | |------|-------------| | honcho_profile | Get a peer's card (identity, attributes, relationships). | | honcho_representation | Get a peer's representation (compressed observations). |

Session

| Tool | Description | |------|-------------| | honcho_session | List sessions. | | honcho_session_create | Create a new session. | | honcho_session_clone | Clone an existing session. | | honcho_session_peers | List/add/remove peers on a session. | | honcho_session_summaries | Get session summaries (compressed context). | | honcho_session_context | Get full conversation context. |

Peer

| Tool | Description | |------|-------------| | honcho_peer | List all peers. | | honcho_peer_create | Create or get a peer. | | honcho_peer_list | List all peers (alias). |

Message

| Tool | Description | |------|-------------| | honcho_message_send | Send a message to a session. | | honcho_message_get | Get a message by ID. |

Conclude

| Tool | Description | |------|-------------| | honcho_conclude | Create an explicit conclusion. | | honcho_conclude_list | List conclusions. | | honcho_conclude_query | Semantic search across conclusions. |

Admin

| Tool | Description | |------|-------------| | honcho_status | Health check + queue stats. | | honcho_dream | Trigger a dream (card_refresh or omni). | | honcho_queue | Check processing queue status. |

Session Strategy

• per-directory (default): Each working directory gets its own Honcho session (e.g., dsh-home-user-project). Conversations in different directories are isolated.
• global: All conversations share one session regardless of directory.

Auto-sync & Persistence

• Messages are synced with a configurable debounce (default 3s).
• Sync cursors are persisted to ~/.dsh/honcho-sync-state.json — survives HMR and DSH restarts.
• On restart, only new events since the last cursor are synced (no duplicates).

Memory Injection

When autoRecall is enabled, on the first user message of each session:

1. Peer cards (profile) for both peers are fetched
2. Representations are fetched and deduplicated (semantic overlap removal)
3. A semantic search query is run using the user's message as the query
4. Results are wrapped in <memory-context> tags and injected into the system prompt

Privacy

• All data stays on your Honcho server. No third-party data transmission.
• The plugin does not log message content.
• Configuration (URL, workspace, peer IDs) is stored in DSH settings, not in the plugin source.

Troubleshooting

| Symptom | Fix | |---------|-----| | HONCHO_URL is required at boot | Set via environment variable in ~/.config/systemd/user/dsh-web.service. | | No sync happening | Check autoSync is true, verify Honcho URL is reachable, check logs: journalctl --user -u dsh-web \| grep honcho | | Recall returns empty | Ensure Deriver has processed messages (check honcho_queue), wait a few minutes after first sync | | 401 Unauthorized | Check your Honcho API key in server config | | Session not found | Verify workspace name matches your Honcho workspace exactly |

License

MIT

---

中文说明

English | 中文

Honcho 记忆插件，为 DeepSeek Harness 提供持久化跨会话记忆，基于自托管的 Honcho v3 服务。

功能

• 自动同步：每轮对话自动同步到 Honcho（带防抖）。同步游标跨重启持久化。
• 混合召回：同时搜索原始消息和推理结论（显式/演绎/归纳），并行执行。
• 记忆注入：会话开始时，将相关的 peer 卡片、表征和语义召回结果注入系统提示词。
• 25 个工具：覆盖 Honcho v3 完整 API — 搜索、画像、会话管理、peer 管理、结论、做梦、队列监控。

依赖

• DeepSeek Harness (DSH) web profile
• 一个运行中的 Honcho v3 实例（自托管）
• Node.js >= 18

安装

# 从 npm
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web

# 或从 GitHub
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

然后重启 DSH：

systemctl --user restart dsh-web
# 或: dsh web --restart

升级

如果你安装过旧版本（v0.6.x 或 v0.7.0）：

# 重跑同一条安装命令 — 会拉取最新版并覆盖
dsh plugin --profile web add npm:@nanpaidashi/dsh-honcho-sync dsh web
# 或
dsh plugin --profile web add link:https://github.com/nanpaidashi/dsh-honcho-sync dsh web

systemctl --user restart dsh-web

安装是幂等的：原地替换插件源码文件。你的配置（环境变量）和同步状态（~/.dsh/honcho-sync-state.json）会保留 — 无数据丢失，无需重新配置。

v0.8.0 → v0.8.1 变更

• 上下文效率：注册工具从 25 个精简到 4 个（honcho_recall、honcho_ask、honcho_remember、honcho_context）— 每会话节省约 7K tokens 的工具 schema 注入
• 注入质量：新增 _filterRepresentation() — 从表征注入中过滤 Pattern [medium]/[low] 块、Premises/Sources 溯源链、孤立 Type/Sources 行
• 注入质量：新增 _assembleByPriority() — 按优先级组装 memory-context（peer-card > session-summary > semantic-recall > representation）
• 注入预算：injectionMaxChars 默认 8000 → 4000，reprMaxObs 默认 8 → 4
• 工具描述：所有工具描述精简到 ~100 字符

v0.7.x → v0.8.0 变更

• DSH 0.1.0-rc.8 兼容：添加 normalizeToolParameters() 将旧式参数简写转换为标准 JSON Schema
• DSH 0.1.0-rc.8 兼容：添加 output.render 返回 content blocks 数组（DSH >= 2026 要求）
• README：移除设置面板说明 — 配置通过 ~/.config/systemd/user/dsh-web.service 中的环境变量完成
• 修复 conclusions/query 需要 filters 参数
• 修复 /search、/peers/list、/summaries 响应解析
• 修复 POST /conclusions 请求体格式
• 修复 schedule_dream 参数名（dream_type）
• 新增 4 个工具：honcho_conclude、honcho_conclude_list、honcho_conclude_query、honcho_message_get
• 混合召回现在并行搜索消息和结论

卸载

# 1. 从 DSH 移除插件
dsh plugin --profile web remove honcho-sync dsh web

# 2.（可选）删除同步状态文件
rm ~/.dsh/honcho-sync-state.json

# 3. 重启 DSH
systemctl --user restart dsh-web

注意： 卸载插件不会删除你的 Honcho 数据。所有消息、结论和 peer 卡片仍然保留在你的 Honcho 服务器上。插件只是桥梁 — 你的记忆是安全的。

配置

没有设置面板。 所有配置通过 DSH 服务文件中的环境变量完成。

第一步：编辑 DSH 服务文件

# systemd (Linux)
nano ~/.config/systemd/user/dsh-web.service

在 [Service] 部分添加环境变量：

[Service]
Environment="HONCHO_URL=http://localhost:8000"
Environment="HONCHO_WORKSPACE=my-workspace"
Environment="HONCHO_USER_PEER=user"
Environment="HONCHO_AGENT_PEER=agent"

第二步：应用更改

systemctl --user daemon-reload
systemctl --user restart dsh-web

配置参考

| 变量 | 说明 | 默认值 | |------|------|--------| | HONCHO_URL | Honcho API 地址 | (必填) | | HONCHO_WORKSPACE | Honcho 工作区名称 | (必填) | | HONCHO_USER_PEER | 用户 peer ID | user | | HONCHO_AGENT_PEER | Agent peer ID | agent |

注意： 高级选项（防抖、召回预算、超时）使用合理的默认值，很少需要调整。如需自定义，编辑 src/index.mjs 顶部的 DEFAULTS 对象。

Honcho 服务器搭建

如果你还没有运行 Honcho：

# Docker 快速启动
docker run -d --name honcho \
  -p 8000:8000 \
  -e HONCHO_API_KEY="your-api-key" \
  plasticlabs/honcho:latest

# 或从源码自托管（生产环境推荐）
# 参考: https://github.com/plastic-labs/honcho#self-hosting

创建工作区和 peers：

curl -X POST http://localhost:8000/v3/workspaces/my-workspace \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json"

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "user"}'

curl -X POST http://localhost:8000/v3/workspaces/my-workspace/peers \
  -H "Authorization: Bearer $HONCHO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id": "agent"}'

工具列表

记忆

| 工具 | 说明 | |------|------| | honcho_recall | 混合语义搜索（消息 + 结论）。快（2-5秒）。 | | honcho_ask | 与 peer 深度辩证推理。慢（2-5分钟）但全面。 | | honcho_remember | 保存事实/陈述到 Honcho 记忆。 | | honcho_context | 获取会话的压缩上下文。 |

搜索

| 工具 | 说明 | |------|------| | honcho_search | 跨所有会话搜索（无日期过滤）。 | | honcho_session_search | 在特定会话内搜索。 |

画像

| 工具 | 说明 | |------|------| | honcho_profile | 获取 peer 卡片（身份、属性、关系）。 | | honcho_representation | 获取 peer 表征（压缩观察）。 |

会话

| 工具 | 说明 | |------|------| | honcho_session | 列出会话。 | | honcho_session_create | 创建新会话。 | | honcho_session_clone | 克隆现有会话。 | | honcho_session_peers | 列出/添加/移除会话中的 peer。 | | honcho_session_summaries | 获取会话摘要（压缩上下文）。 | | honcho_session_context | 获取完整对话上下文。 |

Peer

| 工具 | 说明 | |------|------| | honcho_peer | 列出所有 peer。 | | honcho_peer_create | 创建或获取 peer。 | | honcho_peer_list | 列出所有 peer（别名）。 |

消息

| 工具 | 说明 | |------|------| | honcho_message_send | 向会话发送消息。 | | honcho_message_get | 按 ID 获取消息。 |

结论

| 工具 | 说明 | |------|------| | honcho_conclude | 创建显式结论。 | | honcho_conclude_list | 列出结论。 | | honcho_conclude_query | 跨结论语义搜索。 |

管理

| 工具 | 说明 | |------|------| | honcho_status | 健康检查 + 队列统计。 | | honcho_dream | 触发做梦（card_refresh 或 omni）。 | | honcho_queue | 查看处理队列状态。 |

会话策略

• per-directory（默认）：每个工作目录对应独立的 Honcho 会话（如 dsh-home-user-project）。不同目录的对话互相隔离。
• global：所有对话共享一个会话，不区分目录。

自动同步与持久化

• 消息以可配置的防抖间隔同步（默认 3 秒）。
• 同步游标持久化到 ~/.dsh/honcho-sync-state.json — 跨 HMR 和 DSH 重启保留。
• 重启后只同步游标之后的新事件（无重复）。

记忆注入

当 autoRecall 启用时，每个会话的首条用户消息触发：

1. 获取两个 peer 的卡片（画像）
2. 获取表征并去重（语义重叠移除）
3. 以用户消息为查询执行语义搜索
4. 结果包裹在 <memory-context> 标签中注入系统提示词

隐私

• 所有数据保留在你的 Honcho 服务器上。无第三方数据传输。
• 插件不记录消息内容。
• 配置（URL、工作区、peer ID）通过环境变量存储在 DSH 服务文件中，不在插件源码里。

故障排查

| 症状 | 解决方案 | |------|----------| | 启动时 HONCHO_URL is required | 通过设置面板或环境变量配置。如果设置异步加载，此消息无害。 | | 没有同步发生 | 检查 autoSync 是否为 true，确认 Honcho URL 可达，查看日志：journalctl --user -u dsh-web \| grep honcho | | 召回返回空 | 确认 Deriver 已处理消息（检查 honcho_queue），首次同步后等待几分钟 | | 401 Unauthorized | 检查 Honcho 服务器配置中的 API key | | Session not found | 确认 workspace 名与 Honcho 工作区完全一致 |

许可

MIT