c9be04fdac
## 根因（4ab888c 的自检抓出来的）
4ab888c 在发送前加了配对自检，生产日志立刻指出真正来源：
★ dropped 1 unpaired tool message(s) before send (names: [qq_call_state])
顺着工具名查 context.json，脏帧是决定性的：
[42] tool_calls = [qq_call_state, output_send__qq]
tool_results = [output_send__qq] ← call_state 从未落盘
该帧自己的记录写了原因：qq_call_state 被 QQ 插件的来源权限策略拦下
（判定为"非所有者私聊"）。
## 缺陷位置
stepToolBegin 的顺序是「先记 call，再判能不能执行」：
f.appendToolCallRecord(tc) // ← 先落 ToolCalls
if a.runStage(sdk.StageBeforeToolcall, …) {
f.Msgs 补一条 role=tool // ← 模型能看到
f.ToolIdx++
return outcomeContinue // ← 但没写 ToolResults
}
同一函数里还有一处同构分支（插件崩溃态跳过执行），同样只补 f.Msgs。
task.go 顶部的注释写着「ToolCalls 与 ToolResults 通过 CallID 配对；
两者都由 appendToolCallRecord 同步追加」—— 这个不变量在**提前返回路径**
上被违反了。
## 为什么这会变成会话级故障
ContextEvent{ToolCalls: 2, ToolResults: 1}
⇒ 渲染出 assistant(tool_calls=[c1,c2]) 但只有 c1 的结果
⇒ 上游硬拒绝（HTTP 400）：
An assistant message with 'tool_calls' must be followed by tool messages
responding to each 'tool_call_id'. (insufficient tool messages…)
关键在于脏数据**持久化进 context.json**，之后每一轮都带着它，直到自检剔掉。
## 修法
新增 appendToolResultRecord（与 appendToolCallRecord 成对的公开入口），
在两处提前返回各补一行。
判定"被拒绝/被跳过"≠"没有结果"：拒绝原因本身就是结果，而且模型确实
从 f.Msgs 看到了它。落 context 的那份必须与发给模型的一致。
并发路径（stepToolBatch）没有这个问题 —— runOneTool 只返回结果，
join 后的顺序收尾段无条件写 ToolResults（含被拒绝项）。
## 判据（2 条，2 次变异全部实测变红）
TestDeniedToolStillRecordsResult
注册一个真的会拒绝的 before_toolcall 钩子，跑完整一轮，
断言落进 context 的每个 call 都有 result，且拒绝原因文本一致。
变异：删掉拒绝分支那行 ⇒ "★ call call_deny_1 (denied_tool) 没有对应的
ToolResults"（实测红）
TestUnhealthyPluginSkipStillRecordsResult
钉住第二条同构分支。
变异：删掉跳过分支那行 ⇒ "★ 被跳过的工具 call_unhealthy_1 没落
ToolResults —— 同型失配，上游 400"（实测红）
两条都走真实链路（真的调 runStage / 真的置崩溃态），不是只测
appendToolResultRecord 这个函数本身。
## 顺带发现一个独立缺陷（未修，不在本次范围）
写第二条判据时发现：插件崩溃熔断**实际从不生效**。
recordCrash 标记 Unhealthy=true，但从不设置 LastReload
⇒ isHealthy 的冷却判据 time.Since(r.LastReload) > reloadCooldown
在 LastReload 为零值时恒为真（Since 是巨大的正数）
⇒ 判定"冷却期早已过去" ⇒ 立刻自愈
实测：连续 3 次 recordCrash 后 needReload=true、Unhealthy=true，
紧接着 isHealthy 返回 true。
后果：task.go:1065/1135 的「插件崩溃态跳过执行」分支实际走不到。
这条应单独修并单独钉，本提交的判据用直达状态绕过它（注释已写明原因）。
## 验证
go build ./... PASS
go vet ./... PASS
gofmt -l 干净
go test ./... -count=1 62 包全过，0 FAIL
干净检出（worktree） build + TestDenied/TestUnhealthy 全绿
⚠️ AI-Assisted Programming Notice: Parts of this project's code, documentation, and commit history were generated or modified with AI assistance. Key changes have been human-reviewed, but please evaluate and verify before use.
HologramAgent
中文: README.md
Self-hosted agent kernel. Runs on your own hardware; plugins attach as separate processes.
make build build-cli
./build/homed -data /tmp/ha
API keys go in the web UI at http://localhost:8080. Requires Linux.
The main difference from typical agent frameworks is context handling: instead of truncating on overflow or asking the model to summarize, it scores history by relevance and sinks the low-scoring events into cold context, then distills those into a graph. Two other things differ: startup order is resolved at build time, and plugins launch as soon as their facilities are ready.
Architecture
homed (kernel)
LLM orchestration · memory · retrieval
│
┌──────────────┼──────────────┐
│ │ │
stdio RPC shared mem event ring
control bulk data notify
│ │ │
└──────────────┼──────────────┘
│
plugins (separate processes)
web UI · QQ · CLI · files · browser
The kernel process handles orchestration, memory and retrieval; HTTP, files and devices belong to
plugins (internal/plugin). A crashed plugin is restarted with backoff 1s / 2s / 3s; the 4th
crash within 5 minutes stops automatic restarting pending human intervention
(cmd/homed/kmod_runtime.go).
Context window
internal/agent/core/context.go
Each event gets two vectors on entry: a dense vector sharing one space with media and cold context, and a TF-IDF word vector as fallback. Pruning scores history against the current input and keeps topK, with the most recent N events exempt from scoring.
N defaults to 10, bounded by budget: min(configured, ContextTokens / avg tokens per event).
That bound came from a measurement. At a 50k window with 5800 tokens per event and a 40000 budget, pinning 10 events needed 58k, more than the budget itself. Every prune met its target without freeing space; the budget was gone after two rounds and the task terminated, with recall falling from 44% to 22%. Small windows now tighten automatically; a 1M window uses the configured value.
Pruned events move to the cold-context layer together with the media blocks they hold. Block IDs
stay the same; only the holding layer changes. Retrieval uses coldcontext_query: Peek to
confirm, then Remove the source copy. There is no fetch-and-delete path, since deletion follows
confirmation.
Three layers
internal/agent/core/context.go · internal/memory/coldcontext/ · internal/memory/graph.go
| Layer | Holds | Reaches the model | Cooling |
|---|---|---|---|
| L1 Context | events + blocks | directly, in the system prompt | low relevance sinks |
| L2 Cold Context | events + blocks (same shape as L1) | inserted back into L1 order on recall | ≤2 accesses and 72h idle, then distilled |
| L3 Stable | triples, nodes are blocks | on recall | never leaves |
A block has exactly one holder at any layer, with no reference counting. Images and audio are blocks in L2/L3 with their own vectors, searched in the same space as text.
Scenes
internal/memory/scene_emerge.go
A scene is built from five weighted features: channel 1.0, conversation partner 1.0, tools 0.8,
topic 0.4, time of day 0.2. A scene is created on the second occurrence of the same fingerprint
(minSceneEvidence = 2); one-off interactions don't create one. Join threshold 0.5, recall 0.35.
Recurrence adds 1 to strength; scenes that stop recurring decay by half-life.
Two entry points run in parallel: a plugin declares the scene at an injection point (e.g.
chan:qq/peer:group_1), or fingerprints cluster on their own. A declared scene derives features
only from its own key and does not absorb the full fingerprint. Absorbing it would make the
declared scene match nearly every later turn of that kind at close to 1.0 similarity, and the
clustering path could never grow narrower scenes.
Seven stages
internal/agent/core/stages.go
| Stage | When | Plugins can |
|---|---|---|
on_input |
message arrives | blocklist, rate limit, short-circuit reply |
pre_action |
context ready, before LLM | inject external data |
post_action |
LLM returns text and tool calls | filter, force redirect |
before_toolcall |
before one tool runs | audit, deny, rewrite args |
after_toolcall |
after one tool runs | redact, sort results |
before_output |
final text ready | format adaptation |
after_output |
after sending | statistics |
The inner loop is post_action → [before_toolcall → run → after_toolcall] → post_action. It exits
when the model stops calling tools, all calls are denied, or the limit is reached.
Everything else
- Channels: web UI, CLI, QQ groups and DMs, A2A, ACP in your IDE
- Tools: files, shell, code, browser (real Chrome), calendar, notes, RSS, music
- Modalities: images, video, voice, screenshots, web pages
28 built-in plugins, 89 model-callable tools. External plugins live one per repo under github.com/HologramAgent.
Downloads
Releases ship three variants:
| Variant | Contents | For |
|---|---|---|
| full | homed + waiter + desktop GUI + systemd unit | Single-machine, everything |
| server | homed + waiter + systemd unit | Servers (no desktop environment) |
| client | waiter + desktop GUI | Connecting to a remote HologramAgent |
- Linux:
.deb(amd64/arm64),.rpm(x86_64),.tar.gz - Windows:
HologramAgent_v1.2.0_{Full,Server,Client}_win64.exe(NSIS installer, includes the AGPL license page). Since v1.2.0homedno longer supports native Windows (it relies on fd inheritance and in-segment offset dereferencing), so the installer bootstraps WSL2 and installs the Linux packages inside the distribution the same way a Linux host would. - Portable:
homeagent-bin-<os>_<arch>.tar.gz(homed/waiter/initconfig) - Verification:
SHA256SUMS
The macOS homed requires a native macOS build (CGO + sqlite3), so release packages ship only waiter/initconfig.
Build
make build build-cli # Build daemon + CLI
make test # go test ./...
make install # Install to system
Dependencies: Go 1.25+, CGo (go-sqlite3), Linux.
homedrequires Linux (it relies on fd inheritance and intra-segment offset dereferencing of the shared memory region; seecmd/homed/platform_windows.go). On Windows onlywaiter.exeis built andhomedruns under WSL2 (see Downloads). macOS can buildwaiter/initconfig;homedmust be built on native macOS.
License
AGPL-3.0-only. See LICENSE.
Bundled third-party components keep their own licenses; full texts ship in
/usr/share/doc/hologramagent/licenses/.
Third-party components shipped with the packages
| Component | License | Location |
|---|---|---|
| Chinese-CLIP ViT-B/16 (ONNX artifacts) | Apache-2.0 | /usr/lib/hologram/models/chinese-clip-vit-b16-onnx/ |
ONNX Runtime (libonnxruntime.so) |
MIT | /usr/lib/hologram/onnxruntime/ |
| jieba dictionary (embedded in the binary) | MIT | internal/memory/jiebadict/ |
| Go dependencies (go-sqlite3, gojieba, bubbletea, …) | MIT / BSD-3 / Apache-2.0 | permissive, AGPL-3.0-compatible |
The package metadata declares this package as AGPL-3.0-only.