Skip to content

JiuwenMemory v0.2.1

Latest

Choose a tag to compare

@openjiuwen-release-bot openjiuwen-release-bot released this 13 Nov 10:00

🎉 JiuwenMemory v0.2.1 版本发布说明

发布日期:2026 年 11 月 13 日

openJiuwen 社区正式发布 JiuwenMemory v0.2.1。本版本以 v0.2.0 的架构内核为基线,重点补齐树状分层记忆、Schema 时序与实体双轴检索、文档记忆、安全加固与定时演进等能力,并新增 MCP 接入面、上下文感知查询改写与 agent 方向适配;同时集中修复了一批接入层、存储与生命周期相关的正确性问题。


🚀 新特性

树状分层记忆

  • 跨源结构关系:在既有「披露 / 多模态粒度 / 认知分层」三轴之外引入第四轴——以 HierarchyRef 表达跨 MemoryUnit 的父子包含,父节点作为可检索概要、子节点作为可按需展开的证据。
  • 显式建树与区间重建:通过 evolve 的 HIERARCHY 模式显式建树,支持复用完整旧树与按时间区间重建(replace_in_span 以叶权威为边界)。
  • 分层检索:search 支持按父侧 role 优先召回、祖先上卷(rollup)与向下展开(expand_depth),展开选子与 max_tokens 共用预算;支持默认 TimeSpan 查询预设与已召回后代补位。
  • 后台增量构建:支持固定 home 的后台自动增量建树、安全封口与故障保护;Snapshot 自动接入并在同步 infer 中继承。首期结构 kind 为 TIME,其余 kind 仅提供模型与协议。

Schema 时序与实体双轴检索

  • TemporalEntity 只读视图:由已持久化的 Schema Property 按 canonical identity 组装实体时间线,不写入任何存储,保留 Source-first 兜底。
  • 实体 / 属性两条独立召回路径:实体路径走实体 seed + schema_entities 召回后做实体内属性二次选择;属性路径绕过实体名额截断直达召回,再晚融合回填所属实体。
  • 双时间轴:事件时间(t_event)与系统有效时间([t_valid, t_invalid) / knowledge_as_of)独立计算,支持 latest / snapshot / history / range 模式。
  • 默认关闭、请求级启用:受装配期硬门 globals.schema_temporal_enabled 控制,单次查询通过 RetrievalQuery.schema_temporal 显式开启,未启用时不改变普通检索行为。

文档记忆

  • Markdown 人类可读真源:开启 globals.write_document 后,记忆按归属类别与 project 坐标落成 USER.md / MEMORY.md / daily_memory/日期.md,可直接用编辑器阅读。
  • 单文件影子索引:以单个 SQLite 文件承载 FTS5 倒排、sqlite-vec 向量与全量 unit_json,统一承接点查、检索与 list;缺少 embedder / sqlite-vec 时优雅降级。
  • 看门狗双向同步:监听用户手改 Markdown,以 unit 粒度增量同步回影子索引,并通过写窗口防护避免写入与对账之间的回环竞态;路径访问做 realpath + commonpath 逃逸校验。
  • md 文件级接口:新增 read_md_file / edit_md_file,按文件路径读写原文;edit_md_file 采用继承式 SUPERSEDE,保留原 unit 元数据并维护版本链。

安全加固

  • 认证内核:支持 dev / api_key / trusted 三种认证方式与可信网关主体初始化入口,身份只经认证中间件注入,请求 payload 中的身份保留字段在契约边界直接拒绝。
  • 静态加密:面向 KV / 文件系统等存储提供 ENC1 加密装饰器与统一装配开关,支持全存储后端静态加密与索引部署保护契约。
  • 角色感知授权与代理:以 Grant / Delegation 为真源,按角色与空间两轴判定,支持 Agent 代用户操作。
  • 审计完整性:可选的链式 HMAC(chained_hmac)审计,提供内存 / SQLite 链式 Store 与受保护审计;未装配时显式返回 unsupported。
  • 本地媒体准入:视频导入按落点 Scope 与服务端 local_media_roots 精确绑定读取范围,无绑定默认拒绝。

检索增强

  • 上下文感知 Query Rewrite:显式开启后,结合调用方提供的近期上下文,把口语化 / 省略主体的 query 改写为自包含检索短语;仅增强软召回信号,不生成答案、不改变权限与硬过滤。
  • 绝对日期两侧共享规则:查询侧解析时间窗、写入侧生成 t_event 共用同一 first_absolute_date 规则,修复「查询某日期无法命中同日记忆」。

多形态接入

  • MCP 接入面:MCP 工具与 MemoryAPI 全量对齐(38/38),复用 HTTP/CLI 的契约校验与调用桥;支持 async 工具线程隔离、认证 fail-closed 与工具签名 / 契约锁测试。
  • 接入层一致化:HTTP / CLI / MCP / SDK 统一补齐 as_of、mode、tier、channel 等参数转发,统一错误语义,修复 legacy 入口参数静默丢弃与误报 500。
  • Agent 方向适配:新增 agent_llm Extractor(中英文可配、抽取时同步判定 memory_class)、AgentEngine 文档模式读路径,并更新 jiuwenswarm 适配层。

工具与工程

  • 应用 ruff UP 规则迁移类型注解导入,新增 ruff lint 与单元测试 CI 工作流。

🛠 修复与稳定性

  • 存储与生命周期:修复看门狗物理删除 SUPERSEDE 旧版行导致版本链历史丢失;修复 # 开头正文被误判为标题引发的连坐删除;修复 lifecycle 治理未接文档真源;修复不可解码 MemoryUnit 记录中断读取;统一引擎时间比较语义;已配置后端依赖预加载提前至装配期。
  • 检索与构建:修复 QueryParser globals 开关被 defaults 遮蔽;优化树状记忆召回过滤与子节点补位;大文本写路径预切分与 LLM prompt 护栏,修复同步 add 卡死 900s;统一 construction LLM 尝试次数语义;Fuser._normalize_weights 对非法通道名抛 ValidationError;本地 BGE 模型解析与不可用 reranker 降级。
  • 接入层:修复远程 CLI 超时配置与错误处理;修复 MCP 服务生命周期上下文管理器;修复 _search / _delete / _add / _evolve 参数校验与枚举解析;修复 _update / _get 参数遗漏;空内容消息过滤并保留 HTTPException 状态码。
  • 安全与导入:修复 Markdown 标题日志敏感信息泄露;修复视频导入本地文件访问范围;核验加密卷初始化的 ext4 内部 journal;修复可选依赖导入吞噬内部 ImportError;按实例隔离 LLM 晚绑定端点键;默认以 USER 运行并支持显式 ROOT。
  • 时序与调度:修复乱序消息写入的时序校验与反向失效处理;完善异步调度器关闭与后台线程回收,按需创建 daemon thread;修复 ingest 任务无法取消;修复上游限流被误报为不可重试的 500。

📚 兼容性说明

本版本在 v0.2.0 公开接口基础上保持能力与接口兼容,新增能力默认关闭或保持原有行为:树状记忆、Schema 时序检索与上下文改写均需显式开启,文档记忆与 dreaming 由配置开关控制;安全认证与加密按部署配置启用。升级前请结合实际部署形态核对配置项与安全默认值,并规划所需后端依赖(加密卷、审计 Store 等)。


以上就是 JiuwenMemory v0.2.1 的完整发布内容!感谢您使用 JiuwenMemory!我们期待您的反馈和建议!🚀



🎉 JiuwenMemory v0.2.1 Release Notes

Release Date: November 13, 2026

The openJiuwen community officially releases JiuwenMemory v0.2.1. Building on the v0.2.0 kernel as its baseline, this release focuses on tree-structured hierarchical memory, schema-temporal and entity dual-axis retrieval, document memory, security hardening, and scheduled evolution, while adding an MCP surface, context-aware query rewrite, and agent-oriented adaptation. It also fixes a batch of correctness issues across the access layer, storage, and lifecycle.


🚀 New Features

Tree-Structured Hierarchical Memory

  • Cross-source structural relations: Adds a fourth axis on top of disclosure / multimodal granularity / cognitive tier — HierarchyRef expresses parent-child containment across MemoryUnits, using parents as retrievable summaries and children as on-demand evidence.
  • Explicit construction and interval rebuild: Build trees explicitly via evolve's HIERARCHY mode, with full-tree reuse and time-interval rebuild (replace_in_span bounded by leaf authority).
  • Hierarchical retrieval: search supports parent-role-prioritized recall, ancestor rollup, and downward expansion (expand_depth); expansion shares the max_tokens budget, with default TimeSpan query presets and backfill of already-recalled descendants.
  • Background incremental construction: Fixed-home background incremental tree building with safe sealing and fault protection; Snapshots attach automatically and are inherited in synchronous infer. The first structural kind is TIME; other kinds provide models and protocols only.

Schema-Temporal and Entity Dual-Axis Retrieval

  • Read-only TemporalEntity view: Assembled from persisted Schema Properties by canonical identity; nothing is written to storage, preserving the Source-first fallback.
  • Independent entity / property recall paths: The entity path recalls entity seeds plus schema_entities, then selects properties within the entity; the property path bypasses entity quota truncation and late-fuses back to its entity.
  • Dual time axes: Event time (t_event) and system valid time ([t_valid, t_invalid) / knowledge_as_of) are computed independently, supporting latest / snapshot / history / range modes.
  • Off by default, enabled per request: Gated by globals.schema_temporal_enabled; enabled per query via RetrievalQuery.schema_temporal, with ordinary retrieval unchanged when disabled.

Document Memory

  • Human-readable Markdown source of truth: With globals.write_document enabled, memories land as USER.md / MEMORY.md / daily_memory/<date>.md by class and project, directly readable in an editor.
  • Single-file shadow index: One SQLite file carries FTS5 full-text, sqlite-vec vectors, and full unit_json, serving point reads, retrieval, and list; degrades gracefully without an embedder / sqlite-vec.
  • Watchdog two-way sync: Hand edits to Markdown are synced back to the shadow index at unit granularity, with write-window protection against write/reconcile races and realpath + commonpath path-escape checks.
  • File-level md APIs: New read_md_file / edit_md_file operate on raw content by file path; edit_md_file uses inherited SUPERSEDE, preserving unit metadata and the version chain.

Security Hardening

  • Authentication kernel: dev / api_key / trusted modes and a trusted-gateway principal initialization entry; identity is injected only by auth middleware, and reserved identity fields in request payloads are rejected at the contract boundary.
  • Encryption at rest: ENC1 encryption decorators and a unified assembly switch for KV / filesystem stores, with index deployment protection contracts.
  • Role-aware authorization and delegation: Grant / Delegation as the source of truth, decided along role and space axes, supporting agent operations on behalf of a user.
  • Audit integrity: Optional chained HMAC (chained_hmac) audit with in-memory / SQLite chained stores and protected audit; explicitly reports unsupported when not assembled.
  • Local media admission: Video import binds read scope to the server's local_media_roots per target Scope; denied by default without a binding.

Retrieval Enhancements

  • Context-aware query rewrite: When explicitly enabled, rewrites colloquial or subject-elided queries into self-contained retrieval phrases using caller-provided recent context; it only strengthens soft recall signals and never changes permissions or hard filters.
  • Shared absolute-date rule: Query-side time-window parsing and write-side t_event generation share the same first_absolute_date rule, fixing date queries that missed same-day memories.

Multi-Form Access

  • MCP surface: MCP tools fully align with MemoryAPI (38/38), reusing the HTTP/CLI contract validation and invocation bridge; includes async tool thread isolation, fail-closed auth, and tool-signature / contract lock tests.
  • Access-layer consistency: HTTP / CLI / MCP / SDK uniformly forward as_of, mode, tier, channel, and more; unified error semantics, fixing silent parameter drops and false 500s in the legacy entry.
  • Agent-oriented adaptation: New agent_llm Extractor (bilingual, determines memory_class during extraction), an AgentEngine document-mode read path, and updated jiuwenswarm adapter.

Tooling & Engineering

  • Applied ruff UP rules to annotation imports, and added ruff lint plus unit-test CI workflows.

🛠 Fixes & Stability

  • Storage & lifecycle: Fixed watchdog physical deletion of superseded rows losing version-chain history; fixed #-prefixed body lines misread as titles triggering cascading deletes; fixed lifecycle governance not wired to the document source of truth; isolated undecodable MemoryUnit records; unified engine time-comparison semantics; moved configured-backend preloading to assembly time.
  • Retrieval & construction: Fixed QueryParser globals switches shadowed by defaults; improved tree recall filtering and child backfill; added large-text pre-chunking and prompt guards to fix synchronous add hanging for 900s; unified construction LLM attempt semantics; Fuser._normalize_weights now raises ValidationError for invalid channels; improved local BGE model resolution and unavailable-reranker degradation.
  • Access layer: Fixed remote CLI timeout configuration and error handling; fixed MCP server lifecycle context manager; fixed parameter validation and enum parsing in _search / _delete / _add / _evolve; fixed missing parameters in _update / _get; filtered empty messages while preserving HTTPException status codes.
  • Security & imports: Fixed sensitive-information leaks in Markdown title logs; fixed video-import local file access scope; verified ext4 internal journal on encrypted volume init; fixed optional-dependency imports swallowing internal ImportErrors; isolated LLM late-binding endpoint keys per instance; run as USER by default with explicit ROOT support.
  • Temporal & scheduling: Fixed temporal validation and reverse invalidation for out-of-order messages; improved async scheduler shutdown and background thread reclamation with on-demand daemon threads; fixed uncancellable ingest jobs; fixed upstream rate limits misreported as non-retryable 500s.

📚 Compatibility Notes

This release remains compatible in capability and API with v0.2.0. New capabilities are off by default or preserve existing behavior: tree memory, schema-temporal retrieval, and query rewrite must be explicitly enabled; document memory and dreaming are controlled by config switches; authentication and encryption are enabled per deployment. Before upgrading, review config items and security defaults for your deployment, and plan for required backend dependencies (encrypted volumes, audit stores, etc.).


That's everything in JiuwenMemory v0.2.1! Thank you for using JiuwenMemory — we look forward to your feedback and suggestions! 🚀