diff --git a/README.md b/README.md index e1acf0ee..9b130df0 100644 --- a/README.md +++ b/README.md @@ -38,12 +38,23 @@ homed(内核零 IO) ← PluginSDK → 插件(所有 IO 能力) > 当输入已过期时,它会据此认出「这事上一轮已经办过」并**主动纠正自己先前的错误判断**—— > 表现为自我复盘。这是记忆召回的自然结果,内核里**没有**任何名为「反思」的机制。 +**安全防火墙(独立内核模块)** — 安全不是"某个工具顺手扫一下",而是**横在 Core 与 +全部外部模块之间的一堵墙**:Core 流出的请求、外部流回的响应都先过 security 审查。 +它管四件事:凭据闸门(明文 ⇄ `@{别名}`,执行前才回填)、工具黑白名单与沙箱 +(读写根/网络/`..` 逃逸,`deny` 永远优先)、敏感词与提示词注入预警(命中记录不带原文)、 +按主体授权与**插件命名限式**(`qq.owner` / `qq.guest`,未声明的档位会报错而不是静默回落)。 +落地形态是**显式代理**,不是 monkey patch。 + +**device 数据面(独立内核模块)** — 工具注册与路由、inputch、outputch、设备登记 +统一归 `internal/kernelmod/device`;内置工具路由表在 `internal/toolroute`(避免 +core ↔ kernelboot 成环),device 保留对外入口。 + **输入调度:两类别 + 四级中断** — 输入不直接进 LLM,先进调度器。 排队(待办工作)与中断(按"有多不能等"分 L1~L4)两类;高级可抢占低级并保存现场 (中断栈),同级不抢占。L4 只归内核与内核级插件(如 WebUI 终止按钮)。 见 [`assets/docs/zh/ARCHITECTURE.md`](assets/docs/zh/ARCHITECTURE.md) 的「输入调度器与中断机制」。 -**驻留式子 agent** — 内核可派驻轻量内核的子 agent(自己的调度器与 temp 图记忆, +**驻留式子 agent** — 内核可派驻轻量内核的子 agent(自己的调度器与 temp 稳定记忆, 共享通道登记表),把长任务/积压交出去并行做。主 agent 忙久了,内核还会把排队输入 交给临时**分诊助手**:简单的直接处理,需要主 agent 的立刻回「忙碌中,请稍候」, 用户不再干等。见 [`docs/zh/resident-subagent-design.md`](docs/zh/resident-subagent-design.md)。 @@ -157,7 +168,7 @@ flowchart TB subgraph D[② Document 文件记忆] DS[DocStore JSON+TF-IDF] Q1[QueryScored+crossModalMarkdown] -->|【跨模态相关记忆】| SP - Q2[doc_query LLM主动召回] -->|Consume+删除源| DS + Q2[coldcontext_query 冷上下文召回] -->|Consume+删除源| DS Q2 -->|原始时间戳写入上下文| RC CD[FindColdDocs 72h] -->|docToTriples| G end @@ -184,7 +195,7 @@ flowchart TB PIPE[Pipeline 正则] -->|姓名/住址/喜好/年龄/职业| DB end SP[System Prompt] -->|顺序组装| LLM - LLM[LLM] -->|doc_query| Q2 + LLM[LLM] -->|coldcontext_query| Q2 LLM -->|memory_recall| MEM ``` @@ -263,14 +274,14 @@ internal/ **v1.3.x 线**(v1.3.1–v1.3.13)—— **驻留式子 agent** + **输入调度器重做**。 -- **驻留式子 agent**:内核可派驻轻量内核的子 agent(自己的调度器、自己的 temp 图记忆、 +- **驻留式子 agent**:内核可派驻轻量内核的子 agent(自己的调度器、自己的 temp 稳定记忆、 共享通道登记表)。父经 `resident_agents`(list/create/send/inspect/compress/reclaim/destroy) 派活与收活;inputch 可划给子,输入**在进内核之前**就已路由到子。 - **输出通道可寻址到具体 agent**:`AllowedOutputs` 授权集合(三处过滤点一致), 父/子之间可互相投递;设备能力也 outputch 化(每设备一个 `device/` 通道)。 - **输入调度器**:排队/中断两类别 + 四级中断(L1~L4)+ 抢占/挂起/恢复/中断栈; 同级不抢占、有饥饿防护与抢占冷却;L4 只归内核与内核级插件(WebUI 终止按钮)。 -- **轻量内核 profile**:子的记忆面收窄为「传统上下文 + 图记忆」(窄接口, +- **轻量内核 profile**:子的记忆面收窄为「传统上下文 + 稳定记忆(stablemem)」(窄接口, 主库以 query_only 受限句柄打开,写走自己的 temp 实例)。 - **积压及时反馈**(后续线):主 agent 长时间忙时,内核把排队输入交给临时**分诊助手** —— 简单的直接处理并回复,需要主 agent 的立刻回「忙碌中,请稍候」,用户不再干等十几分钟。 @@ -278,7 +289,7 @@ internal/ 子的轮次永远显示 0(`info()` 根本没填)、子侧 childIO 空壳(未继承父的输出通道)、 设备心跳 pong 忘了 Flush(每 60 秒掉线)、Lua 插件桥与 SDK 1.3.0 对齐。 -**v1.2.0** — 统一多模态向量空间 + 媒体升为图记忆一等节点 + 数据面全量迁到共享内存。 +**v1.2.0** — 统一多模态向量空间 + 媒体升为稳定记忆一等节点 + 数据面全量迁到共享内存。 - **模型中立的统一向量空间**:内核不再适配任何具体模型,只提供公共 provider SPI (`pkg/embedding`:`Modality` / `Input{Data,MIME}` / `Info{Dimension,Fingerprint,Modalities}` diff --git a/README_EN.md b/README_EN.md index 455cdd1d..14ae40c6 100644 --- a/README_EN.md +++ b/README_EN.md @@ -28,9 +28,13 @@ plane). A plugin crash cannot take down the kernel and it restarts automatically **Three-Layer Memory Architecture** — Manages information retention in long-running agents through a tiered storage strategy: -- **Context Layer**: Pretrained word embedding / TF-IDF fallback relevance-scored event window, protects last 10 entries, maintains topK context entries -- **Document Layer**: Temporary memory with automatic cold data sinking, also supports user-initiated submissions -- **stablemem layer**: SQLite graph database, persists entity relationships and semantic memory, supports distillation pipelines to extract triples from conversations +- **Context Layer (L1, hot)**: Pretrained word embedding / TF-IDF fallback relevance-scored event window, protects last 10 entries, maintains topK context entries +- **Cold-context Layer (L2, not fed directly)**: Temporary memory with automatic cold data sinking, also supports user-initiated submissions +- **Stablemem Layer (L3, persistent)**: SQLite graph database, persists entity relationships and semantic memory, supports distillation pipelines to extract triples from conversations + +**Security firewall (standalone kernel module)** — Security is not "a scan tucked into some tool"; it is a wall between Core and every external module: requests leaving Core and responses coming back both pass inspection. It owns four things: the credential gate (plaintext ⇄ `@{alias}`, real values filled only right before execution), tool allow/deny plus sandbox (read/write roots, network, `..` escapes; **deny always wins**), sensitive-word and prompt-injection warnings (findings never carry the matched text), and per-principal grants with **plugin-named profiles** (`qq.owner` / `qq.guest`; an undeclared profile is an error, never a silent fallback). Implemented as an **explicit proxy**, not monkey patching. + +**Device data plane (standalone kernel module)** — Tool registration and routing, inputch, outputch and the device registry all belong to `internal/kernelmod/device`; the built-in routing table lives in `internal/toolroute` (to avoid a core ↔ kernelboot cycle) while device keeps the public entry point. **Input Scheduling: 2 classes + 4 interrupt levels** — Input does not go straight to the LLM; it first enters the scheduler. Two classes (queued = pending work, interrupt = ranked L1–L4 by @@ -39,7 +43,7 @@ same level. L4 belongs only to the kernel and kernel-level plugins (e.g. the Web See "Input Scheduler & Interrupt Mechanism" in [`assets/docs/en/ARCHITECTURE.md`](assets/docs/en/ARCHITECTURE.md). **Resident sub-agents** — The kernel can station lightweight-kernel child agents (their own -scheduler and temp graph memory, sharing the channel registry) to run long or backlogged work +scheduler and temp stable memory, sharing the channel registry) to run long or backlogged work in parallel. When the main agent stays busy, the kernel hands queued input to a temporary **triage assistant**: simple items are handled directly, items needing the main agent get an immediate "busy, please wait" — users no longer wait in silence. @@ -155,7 +159,7 @@ flowchart TB subgraph D[② Document File Memory] DS[DocStore JSON+TF-IDF] Q1[Query summary auto-inject] -->|Related Memory Docs| SP - Q2[doc_query LLM active recall] -->|Consume+delete source| DS + Q2[coldcontext_query cold-context recall] -->|Consume+delete source| DS Q2 -->|Original timestamp write to context| RC CD[FindColdDocs 72h] -->|docToTriples| G end @@ -182,7 +186,7 @@ flowchart TB PIPE[Pipeline regex] -->|Name/Address/Likes/Age/Job| DB end SP[System Prompt] -->|Sequential assembly| LLM - LLM[LLM] -->|doc_query| Q2 + LLM[LLM] -->|coldcontext_query| Q2 LLM -->|memory_recall| MEM ``` @@ -247,7 +251,7 @@ External plugin development: see [hologramagentsdk](https://github.com/JianFeeee **v1.3.x line** (v1.3.1–v1.3.13) — **resident sub-agents** + **input scheduler rework**. - **Resident sub-agents**: the kernel can station lightweight-kernel child agents (their own - scheduler, their own temp graph memory, sharing the channel registry). The parent dispatches + scheduler, their own temp stable memory, sharing the channel registry). The parent dispatches and collects work via `resident_agents` (list/create/send/inspect/compress/reclaim/destroy). An inputch can be assigned to a child, so input is routed to it **before entering the kernel**. - **Output channels addressable to a specific agent**: the `AllowedOutputs` grant set @@ -258,7 +262,7 @@ External plugin development: see [hologramagentsdk](https://github.com/JianFeeee starvation guard and preemption cooldown. L4 belongs only to the kernel and kernel-level plugins (e.g. the WebUI stop button). - **Lightweight kernel profile**: a child's memory surface narrows to "conventional context - - graph memory" (narrow interface; the main graph opens as a query_only handle, writes go + - stable memory" (narrow interface; the main graph opens as a query_only handle, writes go to its own temp instance). - **Backlog timely feedback** (later in the line): when the main agent is busy for a long time, the kernel hands queued input to a temporary **triage assistant** — simple items are handled @@ -269,7 +273,7 @@ External plugin development: see [hologramagentsdk](https://github.com/JianFeeee child-side childIO (output channels not inherited), device heartbeat pong missing Flush (dropping every 60s), and Lua plugin bridge alignment with SDK 1.3.0. -**v1.2.0** — unified multimodal vector space, media promoted to first-class graph memory, and the whole data plane moved into shared memory. +**v1.2.0** — unified multimodal vector space, media promoted to first-class stable-memory nodes, and the whole data plane moved into shared memory. - **Model-neutral unified embedding space**: the kernel no longer adapts to any specific model. It exposes only a public provider SPI (`pkg/embedding`: `Modality` / `Input{Data,MIME}` / diff --git a/assets/docs/en/ARCHITECTURE.md b/assets/docs/en/ARCHITECTURE.md index 095f0054..7f40dad2 100644 --- a/assets/docs/en/ARCHITECTURE.md +++ b/assets/docs/en/ARCHITECTURE.md @@ -100,10 +100,10 @@ Setting `ctx.Response` at any stage jumps to `after_output`. ② Document (File Memory) DocStore — JSON files + dense vectors (unified multimodal space; dense_fp must match the current space fingerprint or the doc is recomputed; fallback: StaticEmbedder / TF-IDF InvertedIndex) - Write: Prune archive / doc_commit / Graph snapshot (syncGraphToDocs) + Write: Prune archive / coldcontext_commit / stablemem snapshot (syncGraphToDocs) Read: ├── Auto-inject: Query(input, top3) → similarity summary under same vector space → [Related Memory Docs] → system prompt (read-only) - └── LLM active: doc_query → Consume(read and delete) + └── LLM active: coldcontext_query → Consume(read and delete) → context.Append{Timestamp: d.CreatedAt, Source: "cold_storage"} per doc → Docs written to context timeline with original timestamps, deleted from docStore Cold: FindColdDocs(72h, ≤2 accesses) → docToTriples → Graph @@ -178,15 +178,47 @@ dimension** participate in fusion (mixing coordinate systems yields a direction - Three-branch `textForVector`: agent events → Response, user events → Input, cold_storage → Input+Response - Pretrained word embedding `StaticEmbedder` → CosineSimilarity, auto-fallback to TF-IDF if unavailable - Protects last 10 events from eviction; excess candidates are sorted by relevance and archived to document memory -- Archived events retain original timestamps; on `doc_query` recall they re-insert into the context timeline at their original position +- Archived events retain original timestamps; on `coldcontext_query` recall they re-insert into the context timeline at their original position ### Document Layer `internal/memory/document/document.go` — `Store` -- Consume-on-read mode: deleted after `doc_query` retrieval +- Consume-on-read mode: deleted after `coldcontext_query` retrieval - Dual recall: shared StaticEmbedder semantic vector search + jieba keyword extraction (falls back to char-bigram TF-IDF when model is not loaded) -### Graph Layer +### Security firewall (kernel module) + +`internal/kernelmod/security` is a standalone kernel module sitting between Core and +every external module: + +```text +Core ──outbound inspection──▶ external (device / plugin / channel) +Core ◀─inbound inspection── external +``` + +- **Credential gate**: outbound plaintext becomes `@{alias}`, inbound results are scrubbed, + real values are filled back only right before execution +- **Tool allow/deny + sandbox**: read/write roots, network switch, `..` escape rejection + (`deny` always wins) +- **Content review**: sensitive-word filtering and prompt-injection warnings + (findings never carry the matched text, so logs cannot leak it) +- **Per-principal grants**: hard-private tools are refused for every non-internal principal +- **Plugin-named profiles**: a plugin declares `qq.owner` / `qq.guest` and selects one per + inputch via `InjectOptions.SecurityProfile`; an undeclared name is an **error**, never a + silent fallback + +It is implemented as an **explicit proxy** (not monkey patching): at assembly the public +mount points on `KernelState` are replaced by security-owned objects, so modules keep +believing they talk to each other directly. + +### Device / tool data plane (kernel module) + +`internal/kernelmod/device` owns tool registration and routing, inputch, outputch and the +device registry. The built-in tool routing table lives in `internal/toolroute` (to avoid a +core ↔ kernelboot import cycle) while device keeps the public entry point; without a mounted +device, the agent falls back to its local switch. + +### Stable memory layer `internal/memory/graph.go` — `GraphDB` - SQLite WAL mode, two tables (driver: mattn/go-sqlite3, CGo) @@ -204,10 +236,10 @@ dimension** participate in fusion (mixing coordinate systems yields a direction | `memory_edit` | Edit existing entity/relation | | `memory_delete_entity` | Delete entity and all its relations | | `memory_introspect` | View memory statistics | -| `doc_query` | Search from Document | -| `doc_commit` | Write to Document | +| `coldcontext_query` | Recall from cold context | +| `coldcontext_commit` | Write to cold context | -Since v1.1.1 `memory_commit` and `doc_commit` accept `media_digests`, and the kernel appends the +Since v1.1.1 `memory_commit` and `coldcontext_commit` accept `media_digests`, and the kernel appends the `[ ] ` marker into the sentence/body — **the kernel builds the marker, the model only supplies the digest**. Requiring the caller to know the format would mean a single typo silently breaks reference binding with no error anywhere in the chain. `memory_commit` @@ -605,7 +637,7 @@ task, and counting only `sched.queue` yields 0. Design: [`docs/zh/resident-subagent-design.md`](../../../docs/zh/resident-subagent-design.md). - A **resident** is an independent lightweight-kernel agent: its own scheduler, its own - temp graph memory, sharing the channel registry. + temp stable memory, sharing the channel registry. - Parent→child control plane: `resident_agents` (list / create / send / inspect / compress / reclaim / destroy). - **Backlog feedback**: when the main agent is busy for a long time (default > 5m, diff --git a/assets/docs/en/OVERVIEW.md b/assets/docs/en/OVERVIEW.md index 1124e5ba..d1424e4f 100644 --- a/assets/docs/en/OVERVIEW.md +++ b/assets/docs/en/OVERVIEW.md @@ -30,9 +30,9 @@ require touching the kernel, and no second version of business truth accumulates **Three-Layer Memory Architecture** — Manages information retention across long agent runtimes through a tiered storage strategy: - **Context Layer**: In-memory pretrained word embedding scored event window (StaticEmbedder word vectors → CosineSimilarity, TF-IDF fallback), maintains recent context in real-time, low-relevance events automatically sink to the next layer - **Document Layer**: JSON files + TF-IDF vector-indexed temporary memory, supports explicit submission and implicit archival, cold data distills to Graph -- **Graph Layer**: SQLite graph database, persists entities and relations, BFS traversal recall, distillation pipeline extracts triples from conversations +- **Stablemem Layer**: SQLite graph database, persists entities and relations, BFS traversal recall, distillation pipeline extracts triples from conversations -Three progressive layers — context, cold archive, long-term graph memory — form an information decay and consolidation pipeline from short-term to persistent storage. +Three progressive layers — context, cold archive, long-term stable memory — form an information decay and consolidation pipeline from short-term to persistent storage. **Media Memory (first-class memory blocks since v1.2.0)** — Images and audio are not attachments; they are first-class nodes of memory: - **Content-addressed store (CAS)**: addressed by digest, metadata in SQLite and blobs on disk (two-level @@ -44,7 +44,7 @@ Three progressive layers — context, cold archive, long-term graph memory — f Context → Document → Graph is a **migration** of a block, not a copy, and nothing is kept alive by references; **deleting a block deletes its content.** - **Reaches the plugin boundary since v1.1.1**: plugins read and write media through `InsertWithMedia` / - `InjectInputMedia`; the model attaches media via the `media_digests` argument of `memory_commit` / `doc_commit`. + `InjectInputMedia`; the model attaches media via the `media_digests` argument of `memory_commit` / `coldcontext_commit`. - **The old mechanism was removed entirely**: the **descriptive index** — writing the vision model's description into the body text as a `[ ] ` marker and retrieving by it — together with `media_refs` reference counting, was deleted in v1.2.0. A description is second-hand diff --git a/assets/docs/zh/ARCHITECTURE.md b/assets/docs/zh/ARCHITECTURE.md index 72319421..3e9f72bf 100644 --- a/assets/docs/zh/ARCHITECTURE.md +++ b/assets/docs/zh/ARCHITECTURE.md @@ -109,7 +109,7 @@ eventLoop() → processTextInput() |---|---|---|---|---| | **L1 Context** | 事件(内联正文 + 块) | **直接投喂**(进 system prompt 时序) | 最近 n 条 / 上限 m 条 | 超限时按相似度迁出 | | **L2 Document** | 事件(内联正文 + 块) | **不直接投喂**(需召回才进 L1) | 无上限 | 冷到阈值后蒸馏进 L3 | -| **L3 Graph** | 三元组(节点 + 关系边),节点即记忆块 | 不投喂(经召回进入 L1) | 持久 | 不流出 | +| **L3 Stable** | 三元组(节点 + 关系边),节点即记忆块 | 不投喂(经召回进入 L1) | 持久 | 不流出 | ★ **L1 与 L2 结构完全同构**,唯一区别是「是否被直接投喂给模型」。 L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样的事件 + 同样的块,只是不直接进模型视野。 @@ -138,10 +138,10 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样 ② Document (文件记忆 — 不直接投喂,结构与 L1 同构) DocStore — 每篇文档 = 检索元数据 + 事件列表(内联正文 + 块) - 写入: Prune归档 / doc_commit / Graph快照(syncGraphToDocs) + 写入: Prune归档 / coldcontext_commit / stablemem 快照(syncGraphToDocs) 读取: ├── 自动预填充: Query(input, top3) → 同一向量空间下相似度摘要 → 【相关记忆文档】→ system prompt (只读,不动层) - └── LLM主动: doc_query → Consume(取走) + └── LLM主动: coldcontext_query → Consume(取走) → 逐条按各自原始时间戳把事件插回 L1 时序 → 块随事件迁回(同一块 ID,向量不重算),L2 不再持有 冷化: FindColdDocs(72h, ≤2次访问) → docToTriples → Graph @@ -226,9 +226,38 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样 - 正文内联在块里:文本块的 `Text` 是正文,媒体块的 `Data` 是字节 - `Doc.Content` 只是**渲染视图**(供摘要/人工阅读/SDK 兼容),不是原文载体 - 自动预填充:与 Context 共享的向量空间做相似度检索 → 摘要进 system prompt(**只读**,不动层) -- 主动召回:`doc_query` 取走后,**逐条按各自原始时间戳**把事件插回 L1 时序,块随事件迁回 +- 主动召回:`coldcontext_query` 取走后,**逐条按各自原始时间戳**把事件插回 L1 时序,块随事件迁回 - 冷化:`FindColdDocs(72h, ≤2次访问)` → `docToTriples` → Graph +## 安全防火墙与设备数据面(内核模块) + +###security 内核模块(`internal/kernelmod/security`) + +安全不是"某项能力",而是**横在 Core 与全部外部模块之间的一堵墙**: + +```text +Core ──出向审查──▶ 外部(device / plugin / channel) +Core ◀─入向审查── 外部 +``` + +- **凭据闸门**:出向把明文换成 `@{别名}`、入向清洗返回值、执行前才回填真实值 +- **工具黑白名单 + 沙箱**:路径读写根、网络开关、`..` 逃逸拦截(`deny` 永远优先) +- **内容审查**:敏感词过滤 + 提示词注入预警(Finding **不带原文**,避免日志泄漏) +- **按主体授权**:hard-private 工具对任何非内部主体永久拒绝 +- **插件命名限式**:插件声明 `qq.owner` / `qq.guest` 等档位,inputch 触发时用 + `InjectOptions.SecurityProfile` 选择;**未声明的档位名会报错**,不静默回落 + +落地形态是**显式代理**(不是 monkey patch):装配时把 `KernelState` 的公共挂载点 +换成安全对象,业务模块仍认为自己直接与对端交互。 + +### device 内核模块(`internal/kernelmod/device`) + +统一拥有:工具注册与路由、inputch、outputch、设备登记。内置工具的路由表在 +`internal/toolroute`(避免 core ↔ kernelboot 成环),device 保留对外入口; +未挂载 device 时 agent 退化为本地 switch。 + +--- + ### Graph 层 `internal/memory/graph.go` — `GraphDB` @@ -252,10 +281,10 @@ L2 不是 L1 的摘要层,也不是另一种数据形态——它就是同样 | `memory_edit` | 编辑已有实体/关系 | | `memory_delete_entity` | 删除实体及其所有关系 | | `memory_introspect` | 查看记忆统计 | -| `doc_query` | 从 Document 搜索 | -| `doc_commit` | 写入 Document | +| `coldcontext_query` | 从冷上下文(cold context)召回 | +| `coldcontext_commit` | 写入冷上下文 | -`memory_commit` 与 `doc_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把 +`memory_commit` 与 `coldcontext_commit` 自 v1.1.1 起接受 `media_digests`,并由内核把 `[ <短digest>] <描述>` 标记补进句子/正文——**标记由内核拼,模型只给 digest**。 要求调用方知道格式,等于让一个拼写错误静默切断引用绑定而全链路无人报错。 `memory_commit` 同时新增 `sentence_text`:媒体引用挂在句子上,没有句子就无处可挂。 @@ -626,7 +655,7 @@ type Plugin interface { 设计见 [`docs/zh/resident-subagent-design.md`](../../../docs/zh/resident-subagent-design.md)。 -- **驻留子**是轻量内核的独立 agent:自己的调度器、自己的 temp 图记忆、共享的通道登记表。 +- **驻留子**是轻量内核的独立 agent:自己的调度器、自己的 temp 稳定记忆、共享的通道登记表。 - 父对子的控制面:`resident_agents`(list / create / send / inspect / compress / reclaim / destroy)。 - **积压及时反馈**:主 agent 长时间忙时(默认 > 5m,可配),内核把排队输入交给 一个临时**分诊助手**(`offload_*` 配置):简单的直接处理并回复,需要主 agent 的 diff --git a/assets/docs/zh/OVERVIEW.md b/assets/docs/zh/OVERVIEW.md index 4ca835a5..bba320c2 100644 --- a/assets/docs/zh/OVERVIEW.md +++ b/assets/docs/zh/OVERVIEW.md @@ -26,8 +26,8 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev **三层记忆架构** — 三层不是三种数据结构,而是**同一批记忆块的三层持有关系**: - **Context 层(L1,直接投喂)**:内存中预训练词嵌入评分的事件窗口(StaticEmbedder 词向量 → CosineSimilarity,TF-IDF 回退),实时维护最近上下文,低相关性事件自动下沉到下一层 -- **Document 层(L2,不直接投喂)**:与 L1 **结构同构**——同样的事件 + 同样的块,只是不直接进模型视野;支持显式提交和隐式归档,冷数据蒸馏到 Graph -- **Graph 层(L3,持久)**:SQLite 图数据库,**顶层仍是三元组**(节点 + 关系边),但节点从 `entities` 表升级为 `memory_blocks`;BFS 遍历召回,蒸馏管道从对话中提取三元组 +- **Document 层(L2,不直接投喂)**:与 L1 **结构同构**——同样的事件 + 同样的块,只是不直接进模型视野;支持显式提交和隐式归档,冷数据蒸馏到稳定记忆(stablemem) +- **Stablemem 层(L3,持久)**:SQLite 图数据库,**顶层仍是三元组**(节点 + 关系边),但节点从 `entities` 表升级为 `memory_blocks`;BFS 遍历召回,蒸馏管道从对话中提取三元组 ★ **L1 与 L2 唯一区别是「是否被直接投喂给模型」**:L2 不是 L1 的摘要层,也不是 另一种数据形态。召回 = 把事件(连同它持有的块)从“不投喂”的持有层**迁回**“投喂”的持有层。 @@ -36,7 +36,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev 不存在「块 + 外部正文」的分离形态。**任何一层都不压缩** —— 视图(检索摘要、渲染结果) 可以是压缩的,但视图不是记忆。 -三层流动:上下文 → 冷归档 → 长期图记忆,构成从短期到持久的信息衰减与整合管道; +三层流动:上下文 → 冷归档 → 长期稳定记忆,构成从短期到持久的信息衰减与整合管道; 每一次都是**迁移**(块 ID 与向量不变,只换持有层),不是复制。 **媒体记忆(v1.2.0 起:一等记忆块)** — 图片/音频不是附属物,而是记忆的一等节点: @@ -46,7 +46,7 @@ CLI 需要终端面板时,**订阅事件总线**(`EventTerminalOutput` + `Ev - **无独立 GC、无引用计数、无 keep-set**:记忆块遵循单层不变量——Context → Document → Graph 是块的**迁移**,不是复制、也不靠引用保活;**删除块即删内容** - **v1.1.1 起贯通插件边界**:插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体, - 模型可用 `memory_commit` / `doc_commit` 的 `media_digests` 参数关联媒体 + 模型可用 `memory_commit` / `coldcontext_commit` 的 `media_digests` 参数关联媒体 - **旧机制已整体拆除**:此前把视觉模型生成的描述写进正文、以 `[ <短digest>] <描述>` 标记 参与检索的**描述式索引**,以及 `media_refs` 引用计数,均已在 v1.2.0 删除——描述是模型生成的 二手信息,检索「别人转述的图片」不如检索图片自己的向量 diff --git a/docs/git-branching.md b/docs/git-branching.md index 5c889995..54124835 100644 --- a/docs/git-branching.md +++ b/docs/git-branching.md @@ -1,5 +1,11 @@ # Git 分支管理规范 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 生效:2026-08-31,2026-09-04 修订(三级发布通道 + 单条发布分支),2026-09-06 修订(SDK 仓版本语义与发版联动,见 §七),2026-09-13 修订(发布线路牌随 patch 推进 + 版本号不得固化落库)。 > 适用:**本仓(HologramAgent)与 third_party/homeagent-sdk(SDK 仓)**——两仓协作时分支策略必须一致,本规范两仓同用。 > 核心原则一句话:**main 唯一长命、永远可部署;一切新工作在特性分支;一个中版本一条发布分支,alpha/beta/正式由 tag 区分;hotfix 只进发布分支并 cherry-pick 回 main。** diff --git a/docs/zh/context-overflow-l4-design.md b/docs/zh/context-overflow-l4-design.md index 1c70c88e..7f1cea1c 100644 --- a/docs/zh/context-overflow-l4-design.md +++ b/docs/zh/context-overflow-l4-design.md @@ -1,5 +1,11 @@ # 上下文超页 L4 中断 —— 设计与落地 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 特性分支 `feat/context-overflow-l4` > 起因:2026-10-01 记忆召回跑分(v4)实测到HA 上下文管理失控,本文档是那次归因的产出。 diff --git a/docs/zh/entities-retirement-plan.md b/docs/zh/entities-retirement-plan.md index 91fae711..4e9a4dfb 100644 --- a/docs/zh/entities-retirement-plan.md +++ b/docs/zh/entities-retirement-plan.md @@ -1,5 +1,11 @@ # entities 退场迁移方案 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 状态:已确认(方案 A:三表全退),执行中 > 范围:含生产实例 ${HA_DATA}(用户 2026-10-02 确认迁移) > 前置:docs/zh/memory-restructure-plan.md(重构计划) diff --git a/docs/zh/memory-blockflow-repair-plan.md b/docs/zh/memory-blockflow-repair-plan.md index e013314e..d995ec36 100644 --- a/docs/zh/memory-blockflow-repair-plan.md +++ b/docs/zh/memory-blockflow-repair-plan.md @@ -1,5 +1,11 @@ # 三层记忆系统修复计划:块化重构后的失效面 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 状态:**已实施**(2026-10-22)。实施记录见文末 §九。 > 原计划写作于同日,下述前提与失效面均经源码与生产数据核实。 > 触发:块化统一(`docs/zh/memory-restructure-plan.md`)重构了底层数据结构, diff --git a/docs/zh/memory-restructure-plan.md b/docs/zh/memory-restructure-plan.md index 9bc85fa3..8d6337f4 100644 --- a/docs/zh/memory-restructure-plan.md +++ b/docs/zh/memory-restructure-plan.md @@ -1,5 +1,11 @@ # 记忆系统重构计划:块节点统一载体 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 状态:**已执行完毕(2026-10-04)**。本文是当时的执行计划,保留作为决策记录。 > 日期:2026-10-02(计划) / 2026-10-04(完成) > diff --git a/docs/zh/memory-usability-plan.md b/docs/zh/memory-usability-plan.md index d80bb8cc..f1742c3f 100644 --- a/docs/zh/memory-usability-plan.md +++ b/docs/zh/memory-usability-plan.md @@ -1,5 +1,11 @@ # 三层记忆可用性修复计划:统一向量化 + 提示词让 agent 真正理解 +> **归档说明(2026-10-27)**:本文是历史计划,**术语已过时** —— +> `doc_query` / `doc_commit` 已改名为 `coldcontext_query` / `coldcontext_commit`, +> 图记忆(Graph)在对外语义上改称 **stablemem(稳定记忆)**。 +> 现行架构与术语以 `assets/docs/zh/ARCHITECTURE.md` 为准;本文保留作为决策记录。 + + > 状态:**待执行**(2026-10-22) > 前置:`docs/zh/memory-blockflow-repair-plan.md`(L1↔L2 结构同构,已实施) > 本文修的是**上一轮没修的那一层**:结构对了,但检索质量与提示词仍然不可用。