memory-writer-agent-spec

Memory Writer Agent

负责写入 memory vault 。

Memory Writer Agent 负责验证、合并 Chat Agent 构造的 entries，并写入 memory vault 。

除"创建/合并笔记"主流程外，Writer 还接收 Chat Agent 同步触发的"删除 / 编辑"请求，走代码路径，不调 LLM（见下文「笔记删除与编辑」节）。

Memory Writer Agent 用一个队列接收请求，然后异步处理。Memory Writer Agent 是全局单例和独立单线程或协程。由于使用独立单线程或协程，所以没有并发写文件问题。队列内容不需要持久化，可接受因程序非法结束的丢失。

即，用独立 daemon Thread + queue.Queue 。

单例归属：放 src/everlingo/gateway/gateway.py 模块级实例。

实现形态（2026-07 迁移）：所有 vault 文件操作改走 Vault MCP Server（indexer 进程内嵌的 FastMCP Streamable HTTP server）；MCP URL 从 $workspace/indexer.mcp.url 发现。indexer 离线时，entry 被丢弃并 logger.error 告警，不重试、不阻塞队列。

Memory Writer 并发模型图（双入口）：

vars: {
  d2-config: {
    layout-engine: elk
    theme-id: 4
    dark-theme-id: 200
  }
}

direction: down

p_batch: "生产者① MainAgent.invoke() 末尾\nbatch list[MemoryEntry]\n（异步，不阻塞回复）"
p_action: "生产者② Chat Agent memory_writer_action\ndelete/edit 请求（同步等待结果）"

q: "queue.Queue\nitem① list[MemoryEntry]\nitem② _ActionRequest(entry, future)" { shape: cylinder }

thread: "daemon thread _run_loop\n全局单例·串行消费·无锁" {
  pb: "_process_batch"
  pa: "_process_action\ndelete/edit 纯代码（no LLM）"
}

kb: "_write_kb_item_async（per-entry）" {
  agent: "create_agent(self._llm, tools)\nsystem_prompt：mem_entry_spec /\nenvelope_spec / vault_spec（MCP 加载）"
  llm: "LLM 合并或新建 kb markdown" { shape: cloud }
}
evt: "_append_event_async（纯代码）\nstat → write(preamble) / append(section)"

mcp: "Vault MCP Server（Indexer 进程）\nper-entry mcp_vault_connection(lang)\n沙箱锁定 lang vault_dir"

vault: "vault 文件系统 memory/languages/<lang>/vault/" {
  items: "items/\nkb item：LLM 合并/新建 markdown" { shape: page }
  events_f: "events/YYYY/MM/DD.md\n## Event 段落追加（纯代码）" { shape: page }
}

notice: "notice_sink.notify → Session SystemNotice\n（写入确认告知，Chat Agent 决定是否转述）"
imgstore: "ImageStore\ncopy_session_image_to_vault 路径" { shape: cylinder }

off_b: "离线降级（创建流程）：\nentry 丢弃 + logger.error 告警\n不重试、不阻塞队列" { shape: text; style.opacity: 0.75 }
off_a: "离线降级（action 流程）：\nIndexerOfflineError 经 future.set_exception 回传\nChat Agent 抛出并转告用户（不丢弃）" { shape: text; style.opacity: 0.75 }

p_batch -> q: "入队"
p_action -> q: "execute_action_async\nasyncio.wrap_future(future)"
q -> thread: "串行 get() 按 item 类型分发"
thread.pb -> kb
thread.pb -> evt
kb -> mcp: "fs 工具 read / write / find / grep"
evt -> mcp: "stat / write / append"
thread.pa -> mcp: "read / delete / write\nfrontmatter 保护字段强制保留原值"
mcp -> vault.items: "normalize_frontmatter_text 归一化后落盘"
mcp -> vault.events_f
kb -> notice: "解析最终 AIMessage 确认 JSON\nupdated_files / update_summary"
kb -> imgstore: "嵌聊天图片时先复制\n拿 markdown_relative_path"
imgstore -> vault: "图片写入 {md}.assets/"
mcp -> off_b: "MCP 连不上"
mcp -> off_a: "MCP 连不上"