项目概述

YantrikDB 是一个开源的个人 AI 记忆引擎，采用 Rust 语言实现核心功能，同时提供 Python 语言绑定。它旨在为 AI 助手和大型语言模型（LLM）应用提供持久化的语义记忆能力，帮助 AI 系统记住用户的偏好、上下文信息和历史交互。资料来源：README.md:1-50

YantrikDB 的设计理念是让 AI 记忆系统开箱即用，无需复杂的依赖配置或第三方服务。引擎内置了默认的嵌入模型（potion-base-2M，约 7MB），直接通过 pip 安装后即可使用 record_text() 和 recall_text() 接口进行语义记忆的记录和检索。资料来源：README.md:18-22

核心架构

YantrikDB 采用模块化架构设计，主要包含三个核心 crate：

graph TD
    A[用户应用] --> B[Python API / CLI]
    B --> C[yantrikdb-core]
    C --> D[(SQLite 持久存储)]
    C --> E[认知处理层]
    E --> F[冲突检测]
    E --> G[记忆巩固]
    E --> H[主动建议]

架构的核心层包括：认知状态管理、记忆查询系统、冲突检测与解决、叙事理解以及主动建议生成。资料来源：crates/yantrikdb-core/src/cognition/state.rs:1-100

节点类型系统

YantrikDB 使用统一的图结构来表示所有类型的记忆和认知对象。每种节点类型都有其特定的语义含义和属性。资料来源：crates/yantrikdb-core/src/cognition/state.rs:100-200

节点类型一览

资料来源：crates/yantrikdb-core/src/cognition/state.rs:200-280

节点持久化策略

并非所有节点类型都需要持久化存储到 SQLite 数据库中。以下节点类型默认为瞬态（transient），仅在工作集中存在：

• intent_hypothesis（意图假设）
• conversation_thread（对话线程）

其他节点类型默认会持久化存储，支持跨会话记忆保持。资料来源：crates/yantrikdb-core/src/cognition/state.rs:250-270

关系边类型

YantrikDB 支持多种关系边类型，每种边类型都有不同的激活传递因子（activation_transfer），用于控制信息在图网络中的传播强度。资料来源：crates/yantrikdb-core/src/cognition/state.rs:300-400

强关联边

中等关联边

抑制边

某些边类型具有负的激活传递因子，表示对目标节点的抑制作用。资料来源：crates/yantrikdb-core/src/cognition/state.rs:320-380

认知属性系统

每个认知节点都携带一套统一的属性集，用于描述节点在认知网络中的行为特征。资料来源：crates/yantrikdb-core/src/cognition/state.rs:400-500

属性维度

来源可靠性

节点的可信度与其信息来源（provenance）密切相关：

资料来源：crates/yantrikdb-core/src/cognition/state.rs:380-420

记忆查询系统

Python API 查询接口

Python 绑定提供了功能丰富的 query 方法，支持多种过滤和检索策略。资料来源：crates/yantrikdb-python/src/py_engine/memory.rs:50-120

db.query(
    query=None,           # 文本查询字符串
    embedding=None,       # 直接传入嵌入向量
    top_k=10,             # 返回前 k 条结果
    memory_type=None,     # 按记忆类型过滤（如 "episodic"）
    namespace=None,       # 按命名空间过滤
    time_window=None,     # 时间窗口过滤 (start_ts, end_ts)
    expand_entities=False,# 是否展开关联实体
    include_consolidated=False,  # 是否包含巩固后的记忆
    skip_reinforce=False, # 是否跳过强化学习步骤
    domain=None,          # 按领域过滤
    source=None           # 按来源过滤
)

查询操作符

核心认知引擎提供了 DSL 风格的查询操作符系统。资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:1-80

查询结果示例

results = db.recall("who leads the team?", top_k=3)
# → [{"text": "Alice is the engineering lead", "score": 1.0}, ...]

资料来源：README.md:30-35

认知处理流程

Think 循环

think() 方法是 YantrikDB 的核心认知处理入口，执行记忆巩固、冲突检测、模式挖掘等后台任务。资料来源：README.md:36

graph LR
    A[新事件记录] --> B[think() 调用]
    B --> C[记忆巩固]
    B --> D[冲突检测]
    B --> E[模式挖掘]
    B --> F[主动建议生成]
    C --> G[衰减处理]
    D --> H{检测到冲突?}
    H -->|是| I[冲突解决]
    H -->|否| J[输出建议]
    I --> J

冲突检测与解决

YantrikDB 实现了完整的冲突检测和解决机制。冲突类型包括：资料来源：crates/yantrikdb-core/src/base/types.rs:50-100

冲突检测策略包括检查关系策略（relation_policies），考虑命名空间级别的配置。资料来源：crates/yantrikdb-core/src/distributed/conflict.rs:80-120

个性化系统

人格偏差维度

YantrikDB 包含一个人格偏差系统，包含 8 个可配置的维度，用于调整系统行为以适应用户偏好。资料来源：crates/yantrikdb-core/src/cognition/personality_bias.rs:1-80

这些维度支持余弦相似度计算，可用于比较不同人格配置或与用户偏好进行匹配。资料来源：crates/yantrikdb-core/src/cognition/personality_bias.rs:60-80

叙事理解

YantrikDB 包含叙事理解子系统，用于追踪和管理用户生活中的长期叙事弧线。资料来源：crates/yantrikdb-core/src/cognition/narrative.rs:1-60

叙事弧线状态

章节类型

任务与目标管理

任务状态机

YantrikDB 内置完整的任务管理功能，支持任务生命周期管理。资料来源：crates/yantrikdb-core/src/cognition/state.rs:150-200

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress : 开始执行
    InProgress --> Completed : 任务完成
    InProgress --> Blocked : 遇到阻碍
    Blocked --> InProgress : 阻碍解除
    InProgress --> Cancelled : 用户取消
    Pending --> Cancelled : 用户取消
    [*] --> Blocked

优先级等级

接受度与主动建议

YantrikDB 的主动建议系统会考虑用户的当前状态和偏好。资料来源：crates/yantrikdb-core/src/cognition/surfacing.rs:1-50

用户活动状态

通知模式

动作系统

动作类型

YantrikDB 定义了多种动作类型，每种类型有不同的基础成本：资料来源：crates/yantrikdb-core/src/cognition/state.rs:450-520

快速开始

安装

pip install yantrikdb

Python 使用示例

import yantrikdb

# 初始化数据库，使用内置嵌入模型
db = yantrikdb.YantrikDB.with_default("memory.db")

# 记录重要信息
db.record("Alice 是工程主管", importance=0.8, domain="people")
db.record("项目截止日期是 3 月 30 日", importance=0.9, domain="work")
db.record("用户偏好深色模式", importance=0.6, domain="preference")

# 语义检索
results = db.recall("谁是团队负责人?", top_k=3)

# 建立关系
db.relate("Alice", "Engineering", "leads")
db.get_edges("Alice")

# 执行认知处理
db.think()

db.close()

资料来源：README.md:14-45

技术特点总结

系统概述

YantrikDB 是一个基于 Rust 构建的认知记忆数据库，设计用于 AI 个人助手应用场景。它通过混合索引架构（DeltaIndex + HNSW）实现高效的记忆存储与检索，并提供完整的认知推理能力。

核心特性：

• 混合索引架构：DeltaIndex（增量索引）与 HNSW（分层可导航小世界图）结合
• 多模态记忆支持：情景记忆、语义记忆、工作记忆
• 认知引擎：支持注意力扩散、信念整合、规划推理等认知操作
• 冲突检测与解决：自动检测记忆冲突并提供解决策略
• 复制与同步：基于 HLC（混合逻辑时钟）的操作复制

安装配置

环境要求

安装步骤

# 从源码编译
cargo build --release

# 安装 Python 包
pip install -e .

核心概念

记忆类型

系统支持多种记忆类型，每种类型对应不同的存储和检索策略：

认知节点状态

任务（Task）具有完整的状态机：

stateDiagram-v2
    [*] --> Pending
    Pending --> InProgress
    InProgress --> Completed
    InProgress --> Blocked
    InProgress --> Cancelled
    Blocked --> InProgress
    Completed --> [*]
    Cancelled --> [*]

边类型与激活传递

认知节点通过边连接，系统使用激活扩散算法进行推理：

Python API 快速使用

初始化数据库

from yantrikdb import YantrikDB

# 初始化数据库
db = YantrikDB(
    path="./yantrik_data",
    namespace="default"
)

记忆查询

query 方法是核心检索接口，支持向量相似度搜索：

# 使用文本查询
results = db.query(
    query="今天下午的会议内容",
    top_k=10,
    memory_type="episode",
    namespace="work"
)

# 使用向量嵌入
results = db.query(
    embedding=[0.1, 0.2, 0.3, ...],
    top_k=5
)

参数说明：

操作同步

系统提供操作日志的提取和应用接口：

# 提取指定时间点之后的操作
ops = db.extract_ops_since(
    since_hlc=hlc_bytes,
    since_op_id="op_123",
    exclude_actor=None,
    limit=100
)

# 应用远程操作
db.apply_ops(ops)

操作结构：

认知引擎操作

操作类型体系

认知引擎通过 DSL 定义认知操作：

注意力操作

# 聚焦特定节点并扩散激活
result = db.think(
    operation="attend",
    seeds=["node_id_1", "node_id_2"],
    max_hops=3,
    decay=0.9
)

信念整合

# 整合新证据到信念网络
result = db.think(
    operation="believe",
    evidence={
        "target": "belief_node_id",  # 可选，None则创建新信念
        "observation": "用户今天说喜欢喝咖啡",
        "direction": "positive"        # positive=确认, negative=矛盾
    }
)

需求分类系统

系统内置完整的需求分类层级：

graph TD
    Need --> Informational
    Need --> Social
    Need --> Emotional
    Need --> Organizational
    Need --> Creative
    Need --> Health
    Need --> Financial
    Need --> Professional

冲突检测与解决

冲突类型

冲突结构

class Conflict:
    conflict_id: str           # 冲突唯一ID
    conflict_type: str          # 冲突类型
    priority: str               # 优先级
    status: str                 # 状态
    memory_a: str               # 冲突方A
    memory_b: str               # 冲突方B
    entity: Optional[str]       # 相关实体
    detected_at: float          # 检测时间
    detected_by: str            # 检测方法
    resolution_note: Optional[str]  # 解决说明

叙事弧线追踪

系统支持叙事弧线（Narrative Arc）来理解用户生活中的长期主题：

弧线类型：

• Project（项目）
• Habit（习惯）
• Relationship（关系）
• Discovery（发现）
• Loss（失去）
• Recovery（恢复）

弧线状态：

stateDiagram-v2
    [*] --> Emerging
    Emerging --> Active
    Active --> Paused
    Paused --> Active
    Active --> Resolved
    Active --> Abandoned
    Paused --> Abandoned
    Resolved --> [*]
    Abandoned --> [*]

完整示例

from yantrikdb import YantrikDB

# 1. 初始化
db = YantrikDB(path="./data", namespace="user_001")

# 2. 记录情景记忆
db.remember(
    text="用户下午3点与张经理开会讨论Q4计划",
    memory_type="episode",
    entities=["张经理"],
    domain="work"
)

# 3. 创建关联任务
db.think(operation="create_task", description="跟进Q4计划讨论结果")

# 4. 设置偏好
db.set_preference(domain="notifications", preferred="静默模式")

# 5. 查询相关记忆
results = db.query(
    query="Q4计划相关",
    top_k=5,
    memory_type=["episode", "task"],
    expand_entities=True
)

# 6. 提取同步数据（用于多设备同步）
ops = db.extract_ops_since(since_op_id="last_sync_id")

下一步

• 查看 架构设计 深入了解系统内部实现
• 参考 API 文档 获取完整接口说明
• 阅读 认知引擎 了解推理机制
• 查看 复制协议 学习多节点同步

概述

yantrikdb 采用多层次、多类型的索引架构来支撑知识存储与检索能力。根据源码组织结构，该系统主要包含五大索引组件：

资料来源：crates/yantrikdb-core/src/engine/indices.rs

概述

解耦写入路径（Decoupled Write Path）是 yantrikdb 中一项核心架构设计，旨在将前台写入操作与向量索引维护工作彻底分离。该设计解决了传统向量数据库在高并发写入场景下的性能瓶颈问题。

传统的向量数据库通常将写入操作与索引更新耦合在一起，导致写入线程在执行 HNSW（Hierarchical Navigable Small World）图构建时产生显著延迟。yantrikdb 通过引入 Delta Index 增量索引机制，将写入操作限制在 O(1) 复杂度的简单数据结构中，而将计算密集型的 HNSW 索引构建工作委托给后台压缩进程执行。

资料来源：docs/decoupled_write_path_rfc.md:1-20

核心设计原则

写入操作的约束

解耦写入路径对前台写入操作施加了严格的约束，确保写入路径保持极低的延迟：

资料来源：CONCURRENCY.md:1-30

写入操作的职责边界

写入原语（如 record_with_rid、forget、correct 等）必须仅执行以下操作：

• DeltaIndex::append / DeltaIndex::tombstone：O(1) 复杂度的写操作，仅进行简单的向量推送，不涉及 HNSW 工作
• assign_seq：原子序列号分配，使用 fetch_add 或 fetch_max
• bump_visible_seq：DashMap 分片读取 + AtomicU64::fetch_max，稳态下无锁

写入原语禁止调用：

• HnswIndex::insert / HnswIndex::remove：这些属于压缩进程的职责
• compact()：仅允许后台执行

资料来源：CONCURRENCY.md:25-40

架构设计

分层存储结构

yantrikdb 采用冷热分离的分层存储架构：

graph TD
    subgraph 前台写入路径
        Write[写入请求] --> Delta[DeltaIndex<br/>热数据层]
        Delta --> Append[append<br/>O1复杂度]
        Delta --> Tombstone[tombstone<br/>墓碑标记]
    end
    
    subgraph 后台压缩路径
        Compact[compact<br/>后台进程] --> Seal[seal_delta_for_compaction<br/>密封热数据]
        Seal --> Clone[clone-rebuild cold<br/>克隆重建冷数据]
        Clone --> Install[安装新的冷数据层]
        Delta -.->|定期触发| Compact
    end
    
    subgraph 存储层
        Cold[ArcSwap&lt;HnswIndex&gt;<br/>冷数据层-只读快照]
        Install --> Cold
    end
    
    subgraph 读取路径
        Read[读取请求] --> Snapshot[获取快照]
        Snapshot -->|lock-free| Cold
        Snapshot -->|lock-free| Delta
    end

资料来源：crates/yantrikdb-core/src/vector/delta_index.rs:1-50

DeltaIndex 实现

DeltaIndex 是解耦写入路径的核心数据结构，负责管理增量写入操作：

classDiagram
    class DeltaIndex {
        +entries: RwLock~Vec~DeltaEntry~~
        +append(entry: DeltaEntry)
        +tombstone(rid: &str)
        +compact() -> HnswIndex
        +seal_delta_for_compaction() Vec~DeltaEntry~
    }
    
    class DeltaEntry {
        +op_type: OpType
        +rid: String
        +vector: Vec~f32~
        +seq: u64
        +is_tombstone: bool
    }
    
    class OpType {
        <<enumeration>>
        Insert
        Update
        Delete
    }

DeltaIndex 的 append 和 tombstone 方法是 O(1) 复杂度的操作，不会触发任何 HNSW 索引更新。这确保了前台写入的极低延迟。

资料来源：crates/yantrikdb-core/src/vector/delta_index.rs:50-150

ArcSwap 冷数据层

冷数据层采用 ArcSwap<HnswIndex> 实现，而非传统的 RwLock<HnswIndex> 或 Mutex<HnswIndex>。这种设计提供了无锁的快照获取能力：

// 正确的实现方式
struct ColdTier {
    index: ArcSwap<HnswIndex>,  // 原子交换的不可变快照
}

关键不变量：不得将冷数据层的 ArcSwap<HnswIndex> 替换为 RwLock<HnswIndex> 或 Mutex<HnswIndex>。这种替换会破坏并发性能，导致读取 p99 延迟上升。

资料来源：CONCURRENCY.md:60-80

后台压缩机制

压缩流程

后台压缩进程负责将增量数据合并到主索引中：

sequenceDiagram
    participant Write as 写入线程
    participant Delta as DeltaIndex
    participant Compact as 压缩进程
    participant Cold as ArcSwap冷数据层
    
    Write->>Delta: append(entry)
    Write->>Delta: bump_visible_seq(ns)
    
    Note over Delta: 稳态无锁操作
    
    Compact->>Delta: seal_delta_for_compaction()
    Note over Delta: 短暂持有delta RwLock<br/>仅用于密封操作
    
    Compact->>Compact: clone-rebuild cold
    Note over Compact: 不持有任何锁
    
    Compact->>Cold: ArcSwap::store(new_index)
    Note over Cold: 短暂持有install锁
    
    Write->>Cold: load_arc() 获取新快照
    Write->>Delta: 继续追加新entry

压缩进程在执行克隆重建期间不会持有任何前台写入需要获取的锁。这确保了写入操作不会因压缩而阻塞。

资料来源：CONCURRENCY.md:45-60

锁的获取顺序

资料来源：CONCURRENCY.md:45-55

并发控制

visible_seq 的无锁实现

Phase 6 引入的 visible_seq 映射表必须保持读取无锁特性：

// 字段类型定义
visible_seq: DashMap<String, AtomicU64>

// 读取路径 (lock-free)
let seq = visible_seq
    .get(ns)
    .map(|e| e.load(Acquire));

// 写入路径 (fast path)
visible_seq
    .get(ns)
    .fetch_max(seq, Release);

性能影响：在集群规模下，visible_seq_for(ns) 在每次 recall_with_seq 调用时都会执行。如果替换为 Mutex<HashMap>，会导致集群 RYW（Read-Your-Writes）退化为全局互斥锁热点路径。

资料来源：CONCURRENCY.md:85-100

写入原语的模式

所有新的写入原语必须遵循 record_with_rid 的模式：

graph LR
    A[SAVEPOINT] --> B[SQL操作]
    B --> C[DeltaIndex::append]
    C --> D[bump_visible_seq]
    D --> E[COMMIT/ROLLBACK]

资料来源：CONCURRENCY.md:35-40

Materializer 模块

Materializer 负责将查询结果从内部表示转换为外部格式，是解耦写入路径在读取侧的配合组件：

classDiagram
    class Materializer {
        +materialize(query_result: QueryResult) -> SurfaceResult
        +apply_salience(node: Node) -> Node
        +filter_hidden(nodes: Vec~Node~) -> Vec~Node~
    }
    
    class QueryResult {
        +nodes: Vec~NodeId~
        +scores: Vec~f64~
        +context: RecallContext
    }
    
    class SurfaceResult {
        +items: Vec~SurfaceItem~
        +metadata: SurfaceMetadata
    }

资料来源：crates/yantrikdb-core/src/engine/materializer.rs:1-60

配置选项

解耦写入路径的行为可通过以下配置进行调整：

资料来源：docs/decoupled_write_path_rfc.md:50-80

性能特性

写入性能

资料来源：CONCURRENCY.md:70-75

读取性能

资料来源：CONCURRENCY.md:75-80

最佳实践

开发新写入原语

新增写入原语时，必须遵循以下模式：

1. 使用 SAVEPOINT 包装：确保 SQL 操作的事务性
2. 调用 DeltaIndex::append：而非直接操作 HNSW 索引
3. 调用 bump_visible_seq：更新命名空间的可见序列号
4. 禁止阻塞操作：不得在写入路径中调用任何可能阻塞的操作

// 正确的实现示例
fn new_write_primitive(&self, entry: DeltaEntry) -> Result<()> {
    self.conn().execute("SAVEPOINT sp_new_write")?;
    
    // SQL 操作
    self.sql_insert(&entry)?;
    
    // DeltaIndex 操作
    self.delta.append(entry.clone())?;
    
    // 可见性更新
    self.bump_visible_seq(&entry.namespace)?;
    
    self.conn().execute("RELEASE SAVEPOINT sp_new_write")?;
    Ok(())
}

资料来源：CONCURRENCY.md:30-45

验证并发正确性

新增写入原语后，必须验证：

• 运行 crates/yantrikdb-core/examples/wedge_repro.rs 示例
• 确保读取 p99 延迟 < 200ms（8 写入线程 / 30s 压力下）
• 确认读取 P50 延迟保持稳定
• 验证写入吞吐量未下降

资料来源：CONCURRENCY.md:70-80

总结

解耦写入路径是 yantrikdb 架构中的关键创新，通过以下设计实现了高并发下的稳定性能：

• 热数据层（DeltaIndex）：O(1) 复杂度的无阻塞写入
• 冷数据层（ArcSwap）：无锁的只读快照访问
• 后台压缩：将 HNSW 计算与前台写入完全隔离
• DashMap visible_seq：集群级别的无锁读取保证

这种设计使得 yantrikdb 能够在高写入负载下保持毫秒级的查询延迟，同时支持复杂的向量搜索能力。

资料来源：docs/decoupled_write_path_rfc.md:80-100, CONCURRENCY.md:1-100

1. 设计目标与约束

yantrikdb 的并发模型围绕以下核心目标设计：

资料来源：CONCURRENCY.md:1-15

2. 核心并发规则

yantrikdb 定义了六条必须遵守的并发不变性规则：

2.1 规则一：写入路径禁止非 O(1) 锁

所有写操作原语必须遵守单锁原则：禁止在写路径中获取任何非 O(1) 复杂度的锁。任何新的写原语必须仅使用：

• DeltaIndex::append / DeltaIndex::tombstone（短暂 RwLock 写操作）
• assign_seq（原子操作 fetch_add 或 fetch_max）
• bump_visible_seq（DashMap 分片读取 + AtomicU64::fetch_max）

资料来源：CONCURRENCY.md:17-25

2.2 规则二：写入原语仅操作增量索引

以下写入操作必须仅触碰增量索引相关接口：

• upsert_*_with_rid
• forget
• correct
• upsert_entity_edge_with_id
• delete_entity_edge_with_id

它们禁止调用：

• HnswIndex::insert / HnswIndex::remove（仅压缩时可用）
• compact()（仅后台执行）
• 任何压缩器也会获取的新 RwLock

新增写原语需遵循 record_with_rid 的模式：SAVEPOINT 保护的 SQL 块 + DeltaIndex::append + bump_visible_seq。

资料来源：CONCURRENCY.md:27-42

2.3 规则三：后台压缩与前台写操作锁隔离

DeltaIndex::compact 执行昂贵的 HNSW 向量索引重建工作，其锁持有策略如下：

graph TD
    A[开始压缩] --> B[seal_delta_for_compaction]
    B --> C{获取 delta RwLock}
    C -->|短暂| D[交换待处理条目]
    D --> E[释放 delta 锁]
    E --> F[执行 HNSW 重建]
    F --> G{获取 delta RwLock}
    G -->|短暂| H[安装新 cold tier]
    H --> I[释放锁]
    I --> J[压缩完成]
    
    K[前台写入] -.->|不受 F 阶段阻塞| L[DeltaIndex::append]

后台压缩在封存（seal）和安装（install）阶段短暂持有 delta 锁，在 HNSW 重建期间不持有任何前台写入也会获取的锁。

资料来源：CONCURRENCY.md:44-58

3. 分层存储与读写分离

yantrikdb 采用分层存储架构实现读写分离：

graph TD
    subgraph 写入路径
        W[写入请求] --> D[DeltaIndex<br/>增量索引]
        D --> |append| DS[DeltaIndex 结构<br/>RwLock Vec]
    end
    
    subgraph 读取路径
        R[读取请求] --> C[Cold Tier]
        C --> |ArcSwap| HI[HnswIndex<br/>向量索引]
    end
    
    subgraph 后台压缩
        CP[Compactor] --> |定期| CC[Clone + Rebuild]
        CC --> |install| C
    end
    
    DS -.->|compaction| CC

3.1 Cold Tier 的 ArcSwap 保证

Cold tier（冷数据层）必须使用 ArcSwap<HnswIndex> 而非 RwLock<HnswIndex> 或 Mutex<HnswIndex>。

不变性：不要用 RwLock<HnswIndex> 或 Mutex<HnswIndex> 替换 cold tier 的 ArcSwap<HnswIndex>。如需验证，应运行 crates/yantrikdb-core/examples/wedge_repro.rs 并保持 v0.6.6 版本后的性能指标（8 writers / 30s 下读取 p99 < 200ms）。

资料来源：CONCURRENCY.md:60-75

4. Visible Sequence 的 Lock-Free 设计

4.1 架构设计

visible_seq 是 Phase 6 引入的读-your-writes（RYW）可见性机制，其数据结构定义为：

dashmap::DashMap<String, std::sync::atomic::AtomicU64>

4.2 性能影响

visible_seq_for(ns) 在每次 recall_with_seq 调用时都会执行，在集群规模下这是主要流量路径。用 Mutex<HashMap<...>> 替代将导致全局互斥锁热点，严重影响集群 RYW 性能。

不变性：YantrikDB::visible_seq 字段类型必须保持为 dashmap::DashMap<String, AtomicU64>。

资料来源：CONCURRENCY.md:77-90

5. 认知引擎的操作符并发模型

认知引擎（cognition engine）通过 DSL 定义操作符的执行优先级：

5.1 操作符优先级表

资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30

5.2 步骤执行结果输出

pub enum StepOutput {
    Attend(AttendOutput),
    Recall(RecallOutput),
    Believe(BelieveOutput),
    Compare(CompareOutput),
    Constrain(ConstrainOutput),
    Plan(PlanOutput),
    Project(ProjectOutput),
    Anticipate(AnticipateOutput),
    Assess(AssessOutput),
    CoherenceCheck(CoherenceCheckOutput),
    Skipped { reason: String },
    Error { message: String },
}

操作符执行结果通过 ExplanationTrace 结构进行追踪和解释构建：

fn build_explanation(steps: &[StepResult]) -> ExplanationTrace {
    let explanation_steps: Vec<ExplanationStep> = steps
        .iter()
        .enumerate()
        .filter(|(_, s)| s.success)
        .map(|(i, s)| ExplanationStep {
            step_number: i + 1,
            operator: s.operator.clone(),
            description: s.trace.clone().unwrap_or_else(|| ...),
            key_insight: extract_key_insight(&s.output),
        })
        .collect();
    // ...
}

资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:150-180

6. 分布式冲突检测

在分布式场景下，yantrikdb 使用 relation_policies 表管理命名空间级别的冲突策略：

SELECT overlap_allowed, temporal_required, missing_time_severity
FROM relation_policies
WHERE relation_type = ?1 AND (namespace = ?2 OR namespace = '*')
ORDER BY CASE WHEN namespace = ?2 THEN 0 ELSE 1 END
LIMIT 1

6.1 冲突检测流程

graph TD
    A[检测候选关系对] --> B{超过最大冲突数?}
    B -->|是| Z[停止检测]
    B -->|否| C[查询命名空间策略]
    C --> D{存在策略记录?}
    D -->|是| E[应用 overlap_allowed]
    D -->|否| F[使用全局 '*' 策略]
    E --> G{冲突类型检查}
    F --> G
    G --> H[标记冲突节点]

6.2 冲突类型

资料来源：crates/yantrikdb-core/src/distributed/conflict.rs:1-50

7. 认知节点的状态与激活传播

7.1 节点类型

资料来源：crates/yantrikdb-core/src/cognition/state.rs:1-100

7.2 边缘类型的激活传播

边缘类型决定激活如何在节点间传播，负值表示抑制：

graph LR
    A[源节点] -->|"Supports 0.7"| B[目标节点]
    A -->|"Causes 0.8"| C[目标节点]
    A -->|"Inhibits -0.5"| D[目标节点]

8. 认知属性的可靠性模型

8.1 来源类型（Provenance）

信息来源影响信任度：

8.2 通用认知属性

每个认知节点携带 11 维属性：

9. 触发器与冷却机制

9.1 触发器类型

10. 行动成本模型

行动类型具有不同的基础成本：

资料来源：crates/yantrikdb-core/src/cognition/state.rs:200-250

11. 关键不变性总结

概述

记录（Record）与检索（Recall）是 YantrikDB 的核心认知操作模块，负责信息的持久化存储和上下文感知的记忆召回。记录操作用于将文本、嵌入向量及元数据存入数据库；检索操作用于根据查询向量或文本从存储的记忆中匹配最相关的结果。

这两个操作构成了知识管理的基础循环：记录输入新信息 → 检索召回相关上下文 → 支持推理决策。

架构概览

YantrikDB 的知识图谱采用混合架构，结合了图结构存储与认知属性系统。每个节点携带多维度属性（置信度、激活值、显著性等），边携带类型化的语义关系和激活转移因子。

graph TD
    subgraph 知识图谱层
        NK[节点Kind枚举]
        EK[边Kind枚举]
        CA[认知属性]
        PV[ Provenance 可追溯性]
    end
    
    subgraph 操作引擎
        GO[graph_ops 操作]
        GS[graph_state 状态管理]
        QR[query_dsl 查询]
    end
    
    subgraph 认知推理
        SP[surfacing 表面化]
        NT[narrative 叙事弧]
    end
    
    NK --> GO
    EK --> GO
    CA --> GO
    GO --> GS
    GS --> QR
    QR --> SP
    SP --> NT

资料来源：crates/yantrikdb-core/src/cognition/state.rs:1-50

节点类型系统

知识图谱中的节点（Node）代表认知世界中的各种实体或概念。系统定义了14种节点类型，每种类型具有不同的持久化策略和默认认知属性。

节点类型枚举

资料来源：crates/yantrikdb-core/src/cognition/state.rs:80-115

节点类型方法

节点类型提供了字符串序列化与反序列化支持：

pub fn as_str(self) -> &'static str {
    match self {
        Self::Entity => "entity",
        Self::Episode => "episode",
        // ... 其他类型
    }
}

pub fn from_str(s: &str) -> Option<Self> {
    match s {
        "entity" => Some(Self::Entity),
        // ...
        _ => None,
    }
}

资料来源：crates/yantrikdb-core/src/cognition/state.rs:95-125

节点持久化策略

is_persistent() 方法决定了节点类型是否写入 SQLite 存储：

• 持久化类型：entity, episode, belief, goal, task, routine, need, opportunity, risk, constraint, preference, action_schema
• 瞬时类型：intent_hypothesis, conversation_thread（仅存在于工作集）

资料来源：crates/yantrikdb-core/src/cognition/state.rs:130-140

边类型系统

边（Edge）表示节点之间的语义关系，是激活传播和推理的基础。系统定义了17种边类型，具有不同的激活转移因子。

边类型分类

资料来源：crates/yantrikdb-core/src/cognition/state.rs:200-250

激活转移机制

边的 activation_transfer() 方法定义了激活值如何从源节点流向目标节点：

pub fn activation_transfer(self) -> f64 {
    match self {
        Self::Supports => 0.7,
        Self::Causes => 0.8,
        Self::AdvancesGoal => 0.6,
        // ...
    }
}

负值表示抑制关系，激活值会从目标节点中减去转移量。

资料来源：crates/yantrikdb-core/src/cognition/state.rs:240-280

认知属性系统

每个知识图谱节点携带统一的认知属性集，包含11个维度，这些属性共同决定了节点在推理过程中的行为。

属性维度

资料来源：crates/yantrikdb-core/src/cognition/state.rs:280-350

节点类型默认属性

不同节点类型具有预设的认知属性基线：

资料来源：crates/yantrikdb-core/src/cognition/state.rs:350-400

信息溯源系统

Provenance 枚举定义了知识来源的可信度等级，用于信念修正时的加权计算。

来源类型与可靠度

pub fn reliability_prior(self) -> f64 {
    match self {
        Self::Told => 0.95,
        Self::Observed => 0.90,
        Self::Experimented => 0.85,
        Self::Consolidated => 0.80,
        Self::Extracted => 0.75,
        Self::Inferred => 0.60,
        Self::SystemDefault => 0.50,
    }
}

资料来源：crates/yantrikdb-core/src/cognition/state.rs:400-450

任务与目标系统

任务状态机

TaskStatus 定义了任务的生命周期状态：

stateDiagram-v2
    [*] --> Pending: 创建
    Pending --> InProgress: 开始
    InProgress --> Completed: 完成
    InProgress --> Blocked: 阻塞
    Blocked --> InProgress: 解除阻塞
    InProgress --> Cancelled: 取消
    Pending --> Cancelled: 取消
    Completed --> [*]
    Cancelled --> [*]

资料来源：crates/yantrikdb-core/src/cognition/state.rs:480-520

优先级层级

Priority 枚举定义任务的紧急程度：

资料来源：crates/yantrikdb-core/src/cognition/state.rs:520-550

操作类型

行动类型与成本

ActionKind 定义了系统可能执行的操作类型及其基线成本：

资料来源：crates/yantrikdb-core/src/cognition/state.rs:550-600

叙事弧系统

知识图谱支持叙事结构建模，用于跟踪用户生活中的长期主题和故事线。

叙事弧状态

资料来源：crates/yantrikdb-core/src/cognition/narrative.rs:50-80

章节类型

叙事弧内的章节分为：

资料来源：crates/yantrikdb-core/src/cognition/narrative.rs:80-110

查询与推理操作

Recall 操作参数

RecallOp 定义了召回操作参数：

资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:80-100

Think 循环操作优先级

ThinkConfig 定义了认知循环中各操作的优先级：

资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:100-130

表面化与主动建议

抑制原因

SuppressionReason 枚举定义了建议被抑制的原因：

资料来源：crates/yantrikdb-core/src/cognition/surfacing.rs:50-80

冲突检测与解决

冲突类型

ConflictType 定义了记忆间的冲突类型：

资料来源：crates/yantrikdb-core/src/base/types.rs:50-80

使用场景

实体关联查询

当用户记录"Alice 是工程主管"后，系统创建实体节点，并可通过 relate() 建立与"Engineering"节点的"leads"关系边。

目标驱动的任务分解

目标节点通过 subtask_of 边连接到子任务节点，激活值从目标向下传播，自动提升相关子任务的显著性。

偏好学习与冲突检测

用户偏好通过 Preference 节点存储，当新记录与现有偏好矛盾时，系统检测到 Preference 类型的冲突并触发解决流程。

机会与风险管理

Opportunity 节点携带有效期和预期收益属性，Risk 节点携带严重程度，系统通过激活传播计算当前最需要关注的机会和风险。

总结

YantrikDB 的知识图谱操作模块提供了丰富的语义建模能力，通过14种节点类型、17种边类型和11维认知属性，构建了一个可解释、可追溯的认知表示系统。激活传播机制使系统能够基于图结构进行动态推理，表面化系统确保相关信息适时呈现，而叙事弧模块则支持长期主题的跟踪与理解。

概述

认知循环与思考（Cognitive Loop and Thinking）是 YantrikDB 中负责模拟人类认知过程的核心子系统。它通过一系列认知操作符（cognitive operators）驱动记忆激活、信念更新、推理规划和主动建议等高级认知功能。该系统基于"工作集"（working set）机制运行，将持久化的图结构数据转换为动态激活的认知空间，从而实现上下文感知和目标导向的智能行为。

认知循环的核心目标是：

• 上下文感知：根据当前情境选择性地激活相关记忆节点
• 信念维护：整合新证据并解决认知冲突
• 目标驱动：通过规划和预测推进用户目标
• 主动交互：在适当时机向用户推送相关建议

资料来源：crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30

概述

冲突检测与解决（Conflict Detection and Resolution）是 yantrikdb 认知引擎的核心子系统之一，负责识别、管理和解决记忆网络中的矛盾与不一致。该系统涵盖三个层次：

1. 认知层冲突 (cognition/contradiction.rs) - 处理信念、意图、偏好之间的逻辑矛盾
2. 引擎层冲突 (engine/conflict.rs) - 管理记忆存储和检索过程中的冲突
3. 分布式冲突 (distributed/conflict.rs) - 处理多节点复制环境下的冲突

系统的设计目标是在保持记忆完整性的同时，智能地检测、评估和解决各种类型的冲突，确保认知代理基于一致的信息进行决策。

资料来源：crates/yantrikdb-core/src/base/types.rs:1-50

冲突类型体系

yantrikdb 定义了完整的冲突类型层次结构，每种类型都有对应的优先级和处理策略。

冲突类型枚举

资料来源：crates/yantrikdb-core/src/base/types.rs:1-30

冲突数据模型

pub struct Conflict {
    pub conflict_id: String,
    pub conflict_type: String,
    pub priority: String,
    pub status: String,
    pub memory_a: String,
    pub memory_b: String,
    pub entity: Option<String>,
    pub rel_type: Option<String>,
    pub detected_at: f64,
    pub detected_by: String,
    pub detection_reason: String,
    pub resolved_at: Option<f64>,
    pub resolved_by: Option<String>,
    pub strategy: Option<String>,
    pub winner_rid: Option<String>,
    pub resolution_note: Option<String>,
}

该模型记录了冲突的完整生命周期：

• 检测阶段：记录冲突ID、类型、优先级、涉及的双方记忆（memory_a/memory_b）、检测时间和检测原因
• 解决阶段：记录解决策略、获胜方（winner_rid）、解决者和解决时间
• 元数据：关联的实体（entity）和关系类型（rel_type）用于上下文追踪

资料来源：crates/yantrikdb-core/src/base/types.rs:50-80

认知层冲突检测

矛盾检测器

认知层的矛盾检测器负责识别信念、意图和偏好之间的逻辑矛盾。

graph TD
    A[新证据输入] --> B{证据分析}
    B --> C[与现有信念比较]
    C --> D{存在矛盾?}
    D -->|是| E[创建矛盾节点]
    D -->|否| F[更新信念置信度]
    E --> G[冲突分类]
    G --> H[优先级评估]
    H --> I[进入待解决队列]

矛盾检测器通过以下方式工作：

1. 证据收集：接收来自观察、推断或外部来源的新证据
2. 相似性检查：与现有信念进行特征向量比较
3. 矛盾识别：使用激活传播算法检测负向关联边
4. 分类与优先级：根据冲突类型分配优先级

资料来源：crates/yantrikdb-core/src/cognition/state.rs:1-100

关系类型与激活传播

冲突检测与边类型紧密相关。以下边类型可能指示潜在的矛盾：

pub fn activation_transfer(self) -> f64 {
    match self {
        Self::Contradicts => -0.8,   // 强负向转移 = 冲突指示
        Self::Supports => 0.7,
        Self::Predicts => 0.4,
        // ...
    }
}

负向激活转移值（如 -0.8）表示该边会抑制目标节点，这正是矛盾检测的核心机制。

资料来源：crates/yantrikdb-core/src/cognition/state.rs:1-50

引擎层冲突处理

冲突解决策略

引擎层的冲突解决器实现了多种策略来处理存储和检索层面的冲突：

pub struct ConflictResolutionResult {
    pub conflict_id: String,
    pub resolution_strategy: String,
    pub winner_rid: String,
    pub loser_rid: String,
    pub resolved_at: f64,
}

资料来源：crates/yantrikdb-core/src/base/types.rs:80-100

认知属性与冲突敏感性

不同的认知节点类型对冲突的敏感度不同：

约束节点（Constraint）具有最高的置信度和持久性，表明它们最难被冲突推翻；而意图假设（IntentHypothesis）则最容易被新证据更新。

资料来源：crates/yantrikdb-core/src/cognition/state.rs:100-150

分布式冲突处理

多节点复制冲突

在分布式环境中，冲突检测与解决需要考虑网络分区和并发写入：

graph LR
    A[节点 A 写入] --> C{冲突检测}
    B[节点 B 写入] --> C
    C --> D[生成冲突记录]
    D --> E[广播到集群]
    E --> F[一致性解决]
    F --> G[同步状态]

HLC 时钟冲突

yantrikdb 使用混合逻辑时钟（HLC）处理分布式时序：

pub struct OpLogEntry {
    pub op_id: String,
    pub op_type: String,
    pub timestamp: f64,
    pub target_rid: String,
    pub payload: String,
    pub actor_id: String,
    pub hlc: Vec<u8>,
    pub embedding_hash: String,
    pub origin_actor: String,
}

extract_ops_since 函数用于从指定时间点提取后续操作，实现增量同步和冲突检测：

fn extract_ops_since(
    &self,
    since_hlc: Option<Vec<u8>>,
    since_op_id: Option<&str>,
    exclude_actor: Option<&str>,
    limit: usize,
) -> PyResult<Vec<PyObject>>

资料来源：crates/yantrikdb-python/src/py_engine/sync.rs:1-50

工作流程

完整冲突处理流程

graph TD
    A[冲突检测] --> B[冲突分类]
    B --> C{优先级评估}
    C -->|Critical| D[立即处理]
    C -->|High| E[队列优先处理]
    C -->|Medium| F[批量处理]
    C -->|Low| G[延迟处理]
    D --> H[应用解决策略]
    E --> H
    F --> H
    G --> H
    H --> I[更新记忆状态]
    I --> J[记录解决历史]
    J --> K[传播激活更新]

一致性检查

认知引擎定期执行一致性检查：

CognitiveOperator::CoherenceCheck => self.execute_coherence()

一致性检查评估：

• 激活分数（Coherence Score）
• 冲突数量
• 陈旧节点数量
• 系统整体健康状态

资料来源：crates/yantrikdb-core/src/engine/query_dsl.rs:1-30

配置参数

冲突处理配置

触发器冷却与过期

资料来源：crates/yantrikdb-core/src/base/types.rs:100-150

可靠性先验

冲突检测的可靠性与信息来源相关：

这些先验值在冲突解决时作为置信度计算的乘数因子。

资料来源：crates/yantrikdb-core/src/cognition/state.rs:150-200

API 接口

Python 绑定

# 查询冲突历史
conflicts = db.query_conflicts(
    status="unresolved",
    priority="high",
    limit=10
)

# 手动解决冲突
result = db.resolve_conflict(
    conflict_id="cf_xxx",
    strategy="timestamp_wins",
    winner_rid="mem_yyy"
)

资料来源：crates/yantrikdb-python/src/py_engine/memory.rs:1-50

总结

yantrikdb 的冲突检测与解决系统采用了多层次、策略化的设计：

1. 认知层 通过激活传播和关系类型识别逻辑矛盾
2. 引擎层 实现多种解决策略，基于节点属性和冲突类型做出决策
3. 分布式层 使用 HLC 时钟和操作日志处理网络分区

系统的核心设计原则是最小化对用户的干扰，同时确保记忆网络的一致性和可靠性。

概述

主动触发系统（Active Trigger System）是 yantrikdb 认知引擎的核心组件，负责监控记忆状态变化、检测模式并在适当时机主动发起认知操作。该系统基于预定义的触发类型（TriggerType）驱动认知循环（think loop），实现记忆衰减审查、冲突检测、模式发现等智能功能。

触发系统的设计遵循事件驱动架构，通过冷却时间（cooldown）和过期时间（expiry）机制防止触发器过度激活，确保系统在用户可接受的频率下运行。

触发类型体系

触发类型枚举

系统定义了 9 种触发类型，每种类型对应不同的认知需求场景：

类型字符串映射

每种触发类型支持与字符串的双向转换，便于序列化和配置管理：

impl TriggerType {
    pub fn as_str(self) -> &'static str {
        match self {
            TriggerType::DecayReview => "decay_review",
            TriggerType::ConsolidationReady => "consolidation_ready",
            TriggerType::ConflictEscalation => "conflict_escalation",
            TriggerType::TemporalDrift => "temporal_drift",
            TriggerType::Redundancy => "redundancy",
            TriggerType::RelationshipInsight => "relationship_insight",
            TriggerType::ValenceTrend => "valence_trend",
            TriggerType::EntityAnomaly => "entity_anomaly",
            TriggerType::PatternDiscovered => "pattern_discovered",
        }
    }

    pub fn from_str(s: &str) -> Self {
        match s {
            "decay_review" => TriggerType::DecayReview,
            "consolidation_ready" => TriggerType::ConsolidationReady,
            // ... 其他映射
            _ => TriggerType::DecayReview,
        }
    }
}

资料来源：types.rs:行

触发配置

ThinkConfig 配置结构

触发系统通过 ThinkConfig 结构体进行配置：

认知运算符优先级

触发系统与认知运算符协同工作，不同运算符具有不同的优先级：

impl CognitiveOperator {
    pub fn priority(self) -> usize {
        match self {
            Self::Attend(_) => 10,      // 基础 - 始终运行
            Self::Recall(_) => 9,       // 关键 - 上下文必需
            Self::Believe(_) => 8,      // 证据整合
            Self::Compare(_) => 7,      // 行动选择
            Self::Constrain(_) => 7,    // 安全 - 比较时必须运行
            Self::Plan(_) => 6,         // 手段-目的推理
            Self::Project(_) => 5,      // 前向模拟
            Self::Anticipate(_) => 4,   // 主动 - 锦上添花
            Self::Assess => 3,          // 元认知 - 压力大时可跳过
            Self::CoherenceCheck => 2,  // 维护 - 预算紧张时跳过
        }
    }
}

资料来源：query_dsl.rs:行

触发工作流

graph TD
    A[记忆状态变化] --> B{触发条件检查}
    B -->|满足| C[冷却时间检查]
    B -->|不满足| Z[跳过]
    C -->|冷却中| Z
    C -->|可触发| D[创建触发事件]
    D --> E[评估优先级]
    E --> F[执行认知运算符]
    F --> G{操作成功?}
    G -->|是| H[更新记忆状态]
    G -->|否| I[记录错误]
    H --> J[重置冷却计时器]
    I --> J

与感知系统的集成

SurfaceReason 表面原因

触发系统与主动建议（Proactive Suggestion）机制紧密集成，通过 SurfaceReason 枚举记录触发原因：

impl SurfaceReason {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::LowReceptivity => "low_receptivity",
            Self::ItemSuppressionRule => "item_suppression_rule",
            Self::QuietHours => "quiet_hours",
            Self::RateLimited => "rate_limited",
            Self::AntiNag => "anti_nag",
            Self::MaxSurfaces => "max_surfaces",
            Self::TooSoon => "too_soon",
            Self::NotificationModeBlock => "notification_mode_block",
        }
    }
}

资料来源：surfacing.rs:行

用户感知状态

触发系统根据用户当前状态调整行为：

pub fn interruption_cost(self) -> f64 {
    match self {
        Self::Idle => 0.10,
        Self::JustReturned => 0.35,
        Self::Browsing => 0.45,
        Self::Communicating => 0.55,
        Self::TaskSwitching => 0.65,
        Self::FocusedWork => 0.75,
        Self::DeepFocus => 0.95,
    }
}

资料来源：receptivity.rs:行

冲突触发机制

ConflictType 冲突类型

冲突检测是触发系统的重要组成部分：

impl ConflictType {
    pub fn default_priority(&self) -> &'static str {
        match self {
            ConflictType::IdentityFact => "critical",
            ConflictType::Preference => "high",
            ConflictType::Temporal => "high",
            ConflictType::Consolidation => "medium",
            ConflictType::Minor => "low",
        }
    }
}

Conflict 数据结构

pub struct Conflict {
    pub conflict_id: String,
    pub conflict_type: String,
    pub priority: String,
    pub status: String,
    pub memory_a: String,
    pub memory_b: String,
    pub entity: Option<String>,
    pub rel_type: Option<String>,
    pub detected_at: f64,
    pub detected_by: String,
    pub detection_reason: String,
    pub resolved_at: Option<f64>,
    pub resolved_by: Option<String>,
    pub strategy: Option<String>,
    pub winner_rid: Option<String>,
    pub resolution_note: Option<String>,
}

触发执行引擎

Attend 运算符

Attend 运算符是触发系统的核心执行单元，负责激活相关记忆节点：

fn execute_attend(&self, op: &AttendOp) -> StepOutput {
    match self.db.hydrate_working_set(self.attention_config.clone()) {
        Ok(mut ws) => {
            let mut activated = 0;
            let mut top = Vec::new();
            for &seed in &op.seeds {
                if let Some(node) = ws.get_mut(seed) {
                    let new_activation = (node.attrs.activation + 0.3).min(1.0);
                    node.attrs.activation = new_activation;
                    top.push((seed, new_activation));
                    activated += 1;
                }
            }
            // 从种子节点扩散激活
            for &seed in &op.seeds {
                activated += ws.activate_and_spread(seed, 0.3);
            }
            StepOutput::Attend { nodes_activated: activated, top_activated: top }
        }
        Err(e) => StepOutput::Error { message: format!("Attend failed: {}", e) },
    }
}

运算符参数结构

认知属性与触发

CognitiveAttributes 认知属性

每条记忆节点携带认知属性，影响触发决策：

Self {
    confidence,
    activation: 0.0,
    salience,
    persistence,
    valence: 0.0,
    urgency: 0.0,
    novelty: 1.0,
    last_updated_ms: now_ms(),
    volatility: 0.1,
    provenance: Provenance::Observed,
    evidence_count: 1,
}

节点类型与初始值

资料来源：state.rs:行

Provenance 可靠性先验

pub fn reliability_prior(self) -> f64 {
    match self {
        Self::Told => 0.95,          // 用户明确陈述 - 最高信任
        Self::Observed => 0.90,     // 直接观察行为
        Self::Experimented => 0.85, // 通过受控实验确认
        Self::Extracted => 0.75,     // 外部文档 - 可能过时
        Self::Inferred => 0.60,      // 基于模式推理 - 中等信任
        Self::Consolidated => 0.80,  // 多源合并
        Self::SystemDefault => 0.50, // 默认值 - 最弱，易覆盖
    }
}

边缘类型与激活传递

触发系统通过边缘类型决定激活如何在记忆网络间传递：

pub fn activation_transfer(self) -> f64 {
    match self {
        // 强正传递
        Self::Causes => 0.8,
        Self::Supports => 0.7,
        Self::Triggers => 0.7,
        Self::AdvancesGoal => 0.6,
        Self::Requires => 0.5,
        Self::SubtaskOf => 0.4,
        
        // 中等正传递
        Self::Predicts => 0.4,
        Self::AssociatedWith => 0.3,
        Self::SimilarTo => 0.3,
        Self::InstanceOf => 0.3,
        Self::PartOf => 0.3,
        Self::Prefers => 0.3,
        Self::PrecedesTemporally => 0.2,
        // ...
    }
}

资料来源：state.rs:行

触发系统架构图

graph TD
    subgraph 触发源层
        T1[DecayReview]
        T2[ConsolidationReady]
        T3[ConflictEscalation]
        T4[PatternDiscovered]
        T5[其他触发类型]
    end
    
    subgraph 冷却管理
        C1[冷却时间检查]
        C2[过期时间检查]
        C3[频率限制]
    end
    
    subgraph 执行层
        E1[Attend 运算符]
        E2[Recall 运算符]
        E3[Believe 运算符]
        E4[Plan 运算符]
    end
    
    subgraph 输出层
        O1[主动建议]
        O2[冲突报告]
        O3[认知追踪]
    end
    
    T1 --> C1
    T2 --> C1
    T3 --> C1
    T4 --> C1
    T5 --> C1
    
    C1 -->|通过| C2
    C2 -->|通过| C3
    C3 -->|通过| E1
    E1 --> E2
    E2 --> E3
    E3 --> E4
    
    E4 --> O1
    E4 --> O2
    E4 --> O3
    
    style T1 fill:#ff9999
    style T3 fill:#ffcc99
    style O1 fill:#99ff99

配置示例

Rust 配置

let think_config = ThinkConfig {
    importance_threshold: 0.5,
    decay_threshold: 0.3,
    max_triggers: 5,
};

Python API 使用

import yantrikdb

db = yantrikdb.YantrikDB.with_default("memory.db")

# 记录记忆
db.record("Alice is the engineering lead", importance=0.8, domain="people")

# 触发认知循环
db.think()  # 触发整合、冲突检测、模式挖掘

db.close()

总结

主动触发系统是 yantrikdb 实现智能记忆管理的核心机制。通过定义多种触发类型、完善的冷却/过期机制、与认知运算符的深度集成，系统能够在适当的时机主动发起记忆整合、冲突解决等操作，在不打扰用户的前提下持续优化记忆网络的质量和一致性。

Pitfall Log / 踩坑日志

项目：yantrikos/yantrikdb

摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。

1. 安装坑 · 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication
• 对用户的影响：可能阻塞安装或首次运行。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: namespace parameter ignored in batch remember calls — memories always stored under default
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

3. 安装坑 · 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。

5. 安装坑 · 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

6. 安装坑 · 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

7. 安装坑 · 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

8. 安装坑 · 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

9. 安装坑 · 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

10. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code

11. 配置坑 · 来源证据：v0.7.7 — recall_text Keyword-Only Filter Args

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

12. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass.

13. 运行坑 · 来源证据：think() runs consolidation before conflict detection — contradictions get merged

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

14. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing

15. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium

16. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use.

17. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium

18. 安全/权限坑 · 来源证据：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_80497be2ab644e66be4fec1a966b4c10 | https://github.com/yantrikos/yantrikdb/issues/7 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

19. 安全/权限坑 · 来源证据：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] at-rest encryption key_hex in TOML has no effect on disk (v0.5.0)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ca7c8f7ee1384f9d97652734d01b8d67 | https://github.com/yantrikos/yantrikdb/issues/3 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

20. 安全/权限坑 · 来源证据：v0.7.6 — Drop sentence-transformers + numpy from Default Deps

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.6 — Drop sentence-transformers + numpy from Default Deps
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_40bcf8933f1b4ec7a559a746497c3bae | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.6 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

21. 安全/权限坑 · 来源证据：v0.7.8 — Extended Idempotent Migration Runner (closes #10)

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.8 — Extended Idempotent Migration Runner (closes #10)
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e5a77701b7ac401a863105d996cb585c | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8 | 来源类型 github_release 暴露的待验证使用条件。

22. 安全/权限坑 · 来源证据：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_7a590e518c884b5b9a2bbdc995c372fd | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

23. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | issue_or_pr_quality=unknown

24. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | release_recency=unknown