{
"canonical_name": "yantrikos/yantrikdb",
"compilation_id": "pack_f11c9e680b074e76b943f55f118df033",
"created_at": "2026-05-14T04:53:42.040826+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `pip install yantrikdb-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "pip install yantrikdb-mcp",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_5df036e1c7994461b6ff606bc1ca3fd6"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_cb9d289d2e0c9a308b9af311e310bf3f",
"canonical_name": "yantrikos/yantrikdb",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/yantrikos/yantrikdb",
"slug": "yantrikdb",
"source_packet_id": "phit_f3b095d238ec4c2ebe929367905d4a7d",
"source_validation_id": "dval_c248d7a8ec53475a8b3593d4b8b4e781"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 6,
"github_stars": 17,
"one_liner_en": "Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL.",
"one_liner_zh": "Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL.",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "yantrikdb",
"title_zh": "yantrikdb 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Knowledge Base Q&A",
"label_zh": "知识库问答",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-knowledge-base-q-a",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_f3b095d238ec4c2ebe929367905d4a7d",
"page_model": {
"artifacts": {
"artifact_slug": "yantrikdb",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "pip install yantrikdb-mcp",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/yantrikos/yantrikdb#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"知识库问答",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL."
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：Migration v14→v15 fails: ALTER TABLE on edges view",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v0.7.7 — recall_text Keyword-Only Filter Args",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：think() runs consolidation before conflict detection — contradictions get merged",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 2,
"forks": 6,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 17
},
"source_url": "https://github.com/yantrikos/yantrikdb",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL.",
"title": "yantrikdb 能力包",
"trial_prompt": "# yantrikdb - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 yantrikdb 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：YantrikDB 简介。围绕“YantrikDB 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-five-indexes：五大索引架构。围绕“五大索引架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-decoupled-write-path：解耦写入路径。围绕“解耦写入路径”模拟一次用户任务，不展示安装或运行结果。\n5. page-record-recall：记录与检索操作。围绕“记录与检索操作”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“YantrikDB 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-five-indexes\n输入：用户提供的“五大索引架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-decoupled-write-path\n输入：用户提供的“解耦写入路径”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-record-recall\n输入：用户提供的“记录与检索操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“YantrikDB 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-five-indexes：Step 3 必须围绕“五大索引架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-decoupled-write-path：Step 4 必须围绕“解耦写入路径”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-record-recall：Step 5 必须围绕“记录与检索操作”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/yantrikos/yantrikdb\n- https://github.com/yantrikos/yantrikdb#readme\n- README.md\n- Cargo.toml\n- LICENSE\n- pyproject.toml\n- src/yantrikdb/__init__.py\n- crates/yantrikdb-core/src/vector/hnsw.rs\n- crates/yantrikdb-core/src/vector/delta_index.rs\n- crates/yantrikdb-core/src/knowledge/graph.rs\n- crates/yantrikdb-core/src/knowledge/graph_index.rs\n- crates/yantrikdb-core/src/engine/indices.rs\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 yantrikdb 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: API addition: deterministic mutation primitives (record_with_rid + frien（https://github.com/yantrikos/yantrikdb/issues/9）；github/github_issue: Migration v14→v15 fails: ALTER TABLE on edges view（https://github.com/yantrikos/yantrikdb/issues/10）；github/github_issue: [bug] Tombstoned memories still appear in similarity-scan recall results（https://github.com/yantrikos/yantrikdb/issues/8）；github/github_issue: [bug] POST /v1/admin/snapshot unusable in single-node mode — requires cl（https://github.com/yantrikos/yantrikdb/issues/7）；github/github_issue: [bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently（https://github.com/yantrikos/yantrikdb/issues/6）；github/github_issue: [bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0（https://github.com/yantrikos/yantrikdb/issues/3）；github/github_issue: Bug: `namespace` parameter ignored in batch `remember` calls — memories （https://github.com/yantrikos/yantrikdb/issues/2）；github/github_issue: think() runs consolidation before conflict detection — contradictions ge（https://github.com/yantrikos/yantrikdb/issues/1）；github/github_release: v0.7.11 — pyo3 0.28.3 + python3.14 Support（https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11）；github/github_release: v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)（https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10）；github/github_release: v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-dow（https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9）；github/github_release: v0.7.8 — Extended Idempotent Migration Runner (closes #10)（https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "API addition: deterministic mutation primitives (record_with_rid + frien",
"url": "https://github.com/yantrikos/yantrikdb/issues/9"
},
{
"kind": "github_issue",
"source": "github",
"title": "Migration v14→v15 fails: ALTER TABLE on edges view",
"url": "https://github.com/yantrikos/yantrikdb/issues/10"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] Tombstoned memories still appear in similarity-scan recall results",
"url": "https://github.com/yantrikos/yantrikdb/issues/8"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cl",
"url": "https://github.com/yantrikos/yantrikdb/issues/7"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently",
"url": "https://github.com/yantrikos/yantrikdb/issues/6"
},
{
"kind": "github_issue",
"source": "github",
"title": "[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0",
"url": "https://github.com/yantrikos/yantrikdb/issues/3"
},
{
"kind": "github_issue",
"source": "github",
"title": "Bug: `namespace` parameter ignored in batch `remember` calls — memories ",
"url": "https://github.com/yantrikos/yantrikdb/issues/2"
},
{
"kind": "github_issue",
"source": "github",
"title": "think() runs consolidation before conflict detection — contradictions ge",
"url": "https://github.com/yantrikos/yantrikdb/issues/1"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.11 — pyo3 0.28.3 + python3.14 Support",
"url": "https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)",
"url": "https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-dow",
"url": "https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9"
},
{
"kind": "github_release",
"source": "github",
"title": "v0.7.8 — Extended Idempotent Migration Runner (closes #10)",
"url": "https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL.",
"effort": "安装已验证",
"forks": 6,
"icon": "link",
"name": "yantrikdb 能力包",
"risk": "可发布",
"slug": "yantrikdb",
"stars": 17,
"tags": [
"MCP 工具",
"知识库问答",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/yantrikos/yantrikdb 项目说明书\n\n生成时间：2026-05-14 04:39:48 UTC\n\n## 目录\n\n- [YantrikDB 简介](#page-introduction)\n- [快速开始](#page-quickstart)\n- [五大索引架构](#page-five-indexes)\n- [解耦写入路径](#page-decoupled-write-path)\n- [线程安全与并发模型](#page-threading-model)\n- [记录与检索操作](#page-record-recall)\n- [知识图谱操作](#page-knowledge-graph)\n- [认知循环与思考](#page-cognitive-loop)\n- [冲突检测与解决](#page-conflict-detection)\n- [主动触发系统](#page-triggers-proactive)\n\n\n\n## YantrikDB 简介\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [五大索引架构](#page-five-indexes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n- [crates/yantrikdb-core/src/cognition/extractor.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/extractor.rs)\n- [crates/yantrikdb-core/src/cognition/personality_bias.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/personality_bias.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n \n\n# YantrikDB 简介\n\n## 项目概述\n\nYantrikDB 是一个开源的个人 AI 记忆引擎，采用 Rust 语言实现核心功能，同时提供 Python 语言绑定。它旨在为 AI 助手和大型语言模型（LLM）应用提供持久化的语义记忆能力，帮助 AI 系统记住用户的偏好、上下文信息和历史交互。资料来源：[README.md:1-50]()\n\nYantrikDB 的设计理念是让 AI 记忆系统**开箱即用**，无需复杂的依赖配置或第三方服务。引擎内置了默认的嵌入模型（`potion-base-2M`，约 7MB），直接通过 pip 安装后即可使用 `record_text()` 和 `recall_text()` 接口进行语义记忆的记录和检索。资料来源：[README.md:18-22]()\n\n## 核心架构\n\nYantrikDB 采用模块化架构设计，主要包含三个核心 crate：\n\n| Crate 名称 | 说明 |\n|-----------|------|\n| yantrikdb-core | 核心认知引擎，包含记忆存储、查询、冲突检测等功能 |\n| yantrikdb-python | Python 语言绑定，提供面向 Python 生态的 API |\n| yantrikdb-cli | 命令行工具，用于直接操作记忆库 |\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Python API / CLI]\n B --> C[yantrikdb-core]\n C --> D[(SQLite 持久存储)]\n C --> E[认知处理层]\n E --> F[冲突检测]\n E --> G[记忆巩固]\n E --> H[主动建议]\n```\n\n架构的核心层包括：**认知状态管理**、**记忆查询系统**、**冲突检测与解决**、**叙事理解**以及**主动建议生成**。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n## 节点类型系统\n\nYantrikDB 使用统一的图结构来表示所有类型的记忆和认知对象。每种节点类型都有其特定的语义含义和属性。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:100-200]()\n\n### 节点类型一览\n\n| 节点类型 | 英文标识 | 说明 |\n|---------|---------|------|\n| 实体 | entity | 客观事实或具体对象 |\n| 事件 | episode | 时间相关的经历记录 |\n| 信念 | belief | 带有置信度的主观认知 |\n| 目标 | goal | 期望达成的状态 |\n| 任务 | task | 具体的可执行动作项 |\n| 意图假设 | intent_hypothesis | 推测的用户意图 |\n| 习惯 | routine | 周期性行为模式 |\n| 需求 | need | 用户的各种需求 |\n| 机会 | opportunity | 时间窗口内的有利时机 |\n| 风险 | risk | 潜在的威胁或问题 |\n| 约束 | constraint | 限制条件 |\n| 偏好 | preference | 用户偏好设置 |\n| 对话线程 | conversation_thread | 特定话题的对话上下文 |\n| 动作模式 | action_schema | 可复用的动作模板 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-280]()\n\n### 节点持久化策略\n\n并非所有节点类型都需要持久化存储到 SQLite 数据库中。以下节点类型默认为**瞬态**（transient），仅在工作集中存在：\n\n- `intent_hypothesis`（意图假设）\n- `conversation_thread`（对话线程）\n\n其他节点类型默认会持久化存储，支持跨会话记忆保持。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:250-270]()\n\n## 关系边类型\n\nYantrikDB 支持多种关系边类型，每种边类型都有不同的激活传递因子（activation_transfer），用于控制信息在图网络中的传播强度。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:300-400]()\n\n### 强关联边\n\n| 边类型 | 激活传递因子 | 说明 |\n|-------|-------------|------|\n| causes | 0.8 | 因果关系 |\n| supports | 0.7 | 支持关系 |\n| triggers | 0.7 | 触发关系 |\n| advances_goal | 0.6 | 推进目标 |\n| requires | 0.5 | 前置依赖 |\n| subtask_of | 0.4 | 子任务归属 |\n\n### 中等关联边\n\n| 边类型 | 激活传递因子 | 说明 |\n|-------|-------------|------|\n| predicts | 0.4 | 预测关系 |\n| associated_with | 0.3 | 关联关系 |\n| similar_to | 0.3 | 相似关系 |\n| instance_of | 0.3 | 实例关系 |\n| part_of | 0.3 | 部分关系 |\n| prefers | 0.3 | 偏好关系 |\n| precedes_temporally | 0.2 | 时间先后 |\n\n### 抑制边\n\n某些边类型具有负的激活传递因子，表示对目标节点的抑制作用。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:320-380]()\n\n## 认知属性系统\n\n每个认知节点都携带一套统一的属性集，用于描述节点在认知网络中的行为特征。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:400-500]()\n\n### 属性维度\n\n| 属性名称 | 范围 | 说明 |\n|---------|------|------|\n| confidence | [0.0, 1.0] | 置信度 |\n| activation | [0.0, 1.0] | 激活水平 |\n| salience | [0.0, 1.0] | 显著性/突出度 |\n| persistence | [0.0, 1.0] | 持久度 |\n| valence | [-1.0, 1.0] | 情感效价 |\n| urgency | [0.0, 1.0] | 紧迫程度 |\n| novelty | [0.0, 1.0] | 新颖程度 |\n| volatility | [0.0, 1.0] | 波动性 |\n\n### 来源可靠性\n\n节点的可信度与其信息来源（provenance）密切相关：\n\n| 来源类型 | 可靠性先验值 | 说明 |\n|---------|-------------|------|\n| Told | 0.95 | 用户明确陈述，信任度最高 |\n| Observed | 0.90 | 直接观察到的行为 |\n| Experimented | 0.85 | 通过实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取，可能过时 |\n| Inferred | 0.60 | 基于模式的推断 |\n| SystemDefault | 0.50 | 系统默认值，最易被覆盖 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:380-420]()\n\n## 记忆查询系统\n\n### Python API 查询接口\n\nPython 绑定提供了功能丰富的 `query` 方法，支持多种过滤和检索策略。资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-120]()\n\n```python\ndb.query(\n query=None, # 文本查询字符串\n embedding=None, # 直接传入嵌入向量\n top_k=10, # 返回前 k 条结果\n memory_type=None, # 按记忆类型过滤（如 \"episodic\"）\n namespace=None, # 按命名空间过滤\n time_window=None, # 时间窗口过滤 (start_ts, end_ts)\n expand_entities=False,# 是否展开关联实体\n include_consolidated=False, # 是否包含巩固后的记忆\n skip_reinforce=False, # 是否跳过强化学习步骤\n domain=None, # 按领域过滤\n source=None # 按来源过滤\n)\n```\n\n### 查询操作符\n\n核心认知引擎提供了 DSL 风格的查询操作符系统。资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-80]()\n\n| 操作符 | 优先级 | 说明 |\n|-------|-------|------|\n| Recall | 9 | 上下文检索，关键操作 |\n| Believe | 8 | 证据整合 |\n| Compare | 7 | 动作选择 |\n| Constrain | 7 | 安全约束，始终执行 |\n| Plan | 6 | 手段-目标推理 |\n| Project | 5 | 前向模拟 |\n| Anticipate | 4 | 主动预测 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性检查，资源紧张时可跳过 |\n\n### 查询结果示例\n\n```python\nresults = db.recall(\"who leads the team?\", top_k=3)\n# → [{\"text\": \"Alice is the engineering lead\", \"score\": 1.0}, ...]\n```\n\n资料来源：[README.md:30-35]()\n\n## 认知处理流程\n\n### Think 循环\n\n`think()` 方法是 YantrikDB 的核心认知处理入口，执行记忆巩固、冲突检测、模式挖掘等后台任务。资料来源：[README.md:36]()\n\n```mermaid\ngraph LR\n A[新事件记录] --> B[think() 调用]\n B --> C[记忆巩固]\n B --> D[冲突检测]\n B --> E[模式挖掘]\n B --> F[主动建议生成]\n C --> G[衰减处理]\n D --> H{检测到冲突?}\n H -->|是| I[冲突解决]\n H -->|否| J[输出建议]\n I --> J\n```\n\n### 冲突检测与解决\n\nYantrikDB 实现了完整的冲突检测和解决机制。冲突类型包括：资料来源：[crates/yantrikdb-core/src/base/types.rs:50-100]()\n\n| 冲突类型 | 默认优先级 | 说明 |\n|---------|-----------|------|\n| IdentityFact | critical | 身份事实冲突 |\n| Preference | high | 偏好冲突 |\n| Temporal | high | 时间冲突 |\n| Consolidation | medium | 合并冲突 |\n| Minor | low | 次要冲突 |\n\n冲突检测策略包括检查关系策略（relation_policies），考虑命名空间级别的配置。资料来源：[crates/yantrikdb-core/src/distributed/conflict.rs:80-120]()\n\n## 个性化系统\n\n### 人格偏差维度\n\nYantrikDB 包含一个人格偏差系统，包含 8 个可配置的维度，用于调整系统行为以适应用户偏好。资料来源：[crates/yantrikdb-core/src/cognition/personality_bias.rs:1-80]()\n\n| 维度名称 | 说明 |\n|---------|------|\n| curiosity | 好奇心 - 对新信息的探索倾向 |\n| proactivity | 主动性 - 主动干预的程度 |\n| caution | 谨慎性 - 行动前的风险评估 |\n| warmth | 温暖度 - 情感表达的程度 |\n| efficiency | 效率优先 - 完成任务的速度 |\n| playfulness | 趣味性 - 互动风格 |\n| formality | 正式程度 - 沟通风格 |\n| persistence | 坚持度 - 持续跟进的能力 |\n\n这些维度支持余弦相似度计算，可用于比较不同人格配置或与用户偏好进行匹配。资料来源：[crates/yantrikdb-core/src/cognition/personality_bias.rs:60-80]()\n\n## 叙事理解\n\nYantrikDB 包含叙事理解子系统，用于追踪和管理用户生活中的长期叙事弧线。资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:1-60]()\n\n### 叙事弧线状态\n\n| 状态 | 说明 |\n|-----|------|\n| Emerging | 刚检测到，尚未确认 |\n| Active | 活跃积累中 |\n| Paused | 暂停，可能恢复 |\n| Resolved | 目标达成或故事结束 |\n| Abandoned | 停止追踪 |\n\n### 章节类型\n\n| 类型 | 说明 |\n|-----|------|\n| Setup | 初始情境设定 |\n| Rising | 上升/进展 |\n| Climax | 高潮时刻 |\n| Falling | 回落/收尾 |\n| Resolution | 最终结论 |\n| Interlude | 插曲/过渡 |\n\n## 任务与目标管理\n\n### 任务状态机\n\nYantrikDB 内置完整的任务管理功能，支持任务生命周期管理。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress : 开始执行\n InProgress --> Completed : 任务完成\n InProgress --> Blocked : 遇到阻碍\n Blocked --> InProgress : 阻碍解除\n InProgress --> Cancelled : 用户取消\n Pending --> Cancelled : 用户取消\n [*] --> Blocked\n```\n\n### 优先级等级\n\n| 优先级 | 系数 |\n|-------|------|\n| Low | 0.25 |\n| Medium | 0.50 |\n| High | 0.75 |\n| Critical | 1.00 |\n\n## 接受度与主动建议\n\nYantrikDB 的主动建议系统会考虑用户的当前状态和偏好。资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:1-50]()\n\n### 用户活动状态\n\n| 状态 | 中断成本 | 接收度 |\n|-----|---------|-------|\n| Idle | 0.20 | 0.70 |\n| JustReturned | 0.30 | 0.65 |\n| Browsing | 0.40 | 0.60 |\n| Communicating | 0.50 | 0.55 |\n| TaskSwitching | 0.55 | 0.45 |\n| FocusedWork | 0.75 | 0.30 |\n| DeepFocus | 0.95 | 0.10 |\n\n### 通知模式\n\n| 模式 | 说明 |\n|-----|------|\n| All | 允许所有通知 |\n| ImportantOnly | 仅重要通知 |\n| DoNotDisturb | 完全免打扰 |\n\n## 动作系统\n\n### 动作类型\n\nYantrikDB 定义了多种动作类型，每种类型有不同的基础成本：资料来源：[crates/yantrikdb-core/src/cognition/state.rs:450-520]()\n\n| 动作类型 | 基础成本 | 说明 |\n|---------|---------|------|\n| Abstain | 0.0 | 无操作 |\n| Inform | 0.05 | 信息告知 |\n| Organize | 0.10 | 整理组织 |\n| Suggest | 0.15 | 建议提议 |\n| Communicate | 0.20 | 沟通交流 |\n| Schedule | 0.25 | 日程安排 |\n| Warn | 0.30 | 警告提醒 |\n| Execute | 0.35 | 直接执行 |\n\n## 快速开始\n\n### 安装\n\n```bash\npip install yantrikdb\n```\n\n### Python 使用示例\n\n```python\nimport yantrikdb\n\n# 初始化数据库，使用内置嵌入模型\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录重要信息\ndb.record(\"Alice 是工程主管\", importance=0.8, domain=\"people\")\ndb.record(\"项目截止日期是 3 月 30 日\", importance=0.9, domain=\"work\")\ndb.record(\"用户偏好深色模式\", importance=0.6, domain=\"preference\")\n\n# 语义检索\nresults = db.recall(\"谁是团队负责人?\", top_k=3)\n\n# 建立关系\ndb.relate(\"Alice\", \"Engineering\", \"leads\")\ndb.get_edges(\"Alice\")\n\n# 执行认知处理\ndb.think()\n\ndb.close()\n```\n\n资料来源：[README.md:14-45]()\n\n## 技术特点总结\n\n| 特性 | 说明 |\n|-----|------|\n| 开箱即用 | 内置嵌入模型，无需额外依赖 |\n| 多语言支持 | Python API + CLI 工具 |\n| 图数据库 | 支持复杂关系建模 |\n| 持久化存储 | SQLite 本地存储 |\n| 认知计算 | 内置冲突检测、模式挖掘、叙事理解 |\n| 个性化 | 8 维人格偏差系统 |\n| 主动建议 | 基于用户状态智能推送 |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[YantrikDB 简介](#page-introduction), [记录与检索操作](#page-record-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)\n- [pyproject.toml](https://github.com/yantrikos/yantrikdb/blob/main/pyproject.toml)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n- [crates/yantrikdb-python/src/py_engine/sync.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/sync.rs)\n- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n \n\n# 快速开始\n\n本文档为开发者提供 YantrikDB 的入门指南，帮助您快速了解系统架构、安装配置以及核心 API 的使用方法。\n\n## 系统概述\n\nYantrikDB 是一个基于 Rust 构建的认知记忆数据库，设计用于 AI 个人助手应用场景。它通过混合索引架构（DeltaIndex + HNSW）实现高效的记忆存储与检索，并提供完整的认知推理能力。\n\n**核心特性：**\n\n- 混合索引架构：DeltaIndex（增量索引）与 HNSW（分层可导航小世界图）结合\n- 多模态记忆支持：情景记忆、语义记忆、工作记忆\n- 认知引擎：支持注意力扩散、信念整合、规划推理等认知操作\n- 冲突检测与解决：自动检测记忆冲突并提供解决策略\n- 复制与同步：基于 HLC（混合逻辑时钟）的操作复制\n\n## 安装配置\n\n### 环境要求\n\n| 要求 | 版本 |\n|------|------|\n| Python | ≥ 3.10 |\n| Rust | ≥ 1.70 |\n\n### 安装步骤\n\n```bash\n# 从源码编译\ncargo build --release\n\n# 安装 Python 包\npip install -e .\n```\n\n## 核心概念\n\n### 记忆类型\n\n系统支持多种记忆类型，每种类型对应不同的存储和检索策略：\n\n| 记忆类型 | 说明 | 持久化 |\n|----------|------|--------|\n| Entity | 实体节点（人、地点、事物） | ✓ |\n| Episode | 情景记忆（事件片段） | ✓ |\n| Belief | 信念（带置信度） | ✓ |\n| Goal | 目标节点 | ✓ |\n| Task | 任务项（带状态） | ✓ |\n| IntentHypothesis | 意图假设 | ✗（默认） |\n| Routine | 例行行为模式 | ✓ |\n| Need | 需求（分类层级） | ✓ |\n| Opportunity | 机会（有时限） | ✓ |\n| Risk | 风险 | ✓ |\n| Constraint | 约束条件 | ✓ |\n| Preference | 用户偏好 | ✓ |\n| ConversationThread | 对话线程 | ✗（默认） |\n| ActionSchema | 动作模式 | ✓ |\n\n### 认知节点状态\n\n任务（Task）具有完整的状态机：\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress\n InProgress --> Completed\n InProgress --> Blocked\n InProgress --> Cancelled\n Blocked --> InProgress\n Completed --> [*]\n Cancelled --> [*]\n```\n\n### 边类型与激活传递\n\n认知节点通过边连接，系统使用激活扩散算法进行推理：\n\n| 边类型 | 激活传递值 | 说明 |\n|--------|-----------|------|\n| Causes | 0.8 | 因果关系 |\n| Supports | 0.7 | 支持关系 |\n| Triggers | 0.7 | 触发关系 |\n| AdvancesGoal | 0.6 | 推进目标 |\n| Requires | 0.5 | 依赖关系 |\n| SubtaskOf | 0.4 | 子任务关系 |\n| Predicts | 0.4 | 预测关系 |\n| AssociatedWith | 0.3 | 关联关系 |\n| SimilarTo | 0.3 | 相似关系 |\n| Contradicts | -0.5 | 矛盾关系（抑制） |\n| BlocksGoal | -0.5 | 阻塞目标（抑制） |\n| Prevents | -0.6 | 阻止关系（抑制） |\n\n## Python API 快速使用\n\n### 初始化数据库\n\n```python\nfrom yantrikdb import YantrikDB\n\n# 初始化数据库\ndb = YantrikDB(\n path=\"./yantrik_data\",\n namespace=\"default\"\n)\n```\n\n### 记忆查询\n\n`query` 方法是核心检索接口，支持向量相似度搜索：\n\n```python\n# 使用文本查询\nresults = db.query(\n query=\"今天下午的会议内容\",\n top_k=10,\n memory_type=\"episode\",\n namespace=\"work\"\n)\n\n# 使用向量嵌入\nresults = db.query(\n embedding=[0.1, 0.2, 0.3, ...],\n top_k=5\n)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | str | None | 自然语言查询 |\n| embedding | List[float] | None | 向量嵌入 |\n| top_k | int | 10 | 返回结果数量 |\n| memory_type | str | None | 记忆类型过滤 |\n| namespace | str | None | 命名空间过滤 |\n| time_window | Tuple[float, float] | None | 时间窗口（unix时间戳） |\n| expand_entities | bool | False | 展开关联实体 |\n| include_consolidated | bool | False | 包含已整合记忆 |\n| domain | str | None | 领域过滤 |\n| source | str | None | 来源过滤 |\n\n### 操作同步\n\n系统提供操作日志的提取和应用接口：\n\n```python\n# 提取指定时间点之后的操作\nops = db.extract_ops_since(\n since_hlc=hlc_bytes,\n since_op_id=\"op_123\",\n exclude_actor=None,\n limit=100\n)\n\n# 应用远程操作\ndb.apply_ops(ops)\n```\n\n**操作结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| op_id | str | 操作唯一标识 |\n| op_type | str | 操作类型 |\n| timestamp | float | 时间戳 |\n| target_rid | str | 目标资源ID |\n| payload | dict | 操作载荷 |\n| actor_id | str | 执行者ID |\n| hlc | bytes | HLC 逻辑时钟 |\n| embedding_hash | str | 嵌入哈希 |\n| origin_actor | str | 原始执行者 |\n\n## 认知引擎操作\n\n### 操作类型体系\n\n认知引擎通过 DSL 定义认知操作：\n\n| 操作 | 优先级 | 说明 |\n|------|--------|------|\n| Attend | 10 | 注意力聚焦 |\n| Recall | 9 | 记忆召回 |\n| Believe | 8 | 信念整合 |\n| Compare | 7 | 行动比较 |\n| Constrain | 7 | 约束检查 |\n| Plan | 6 | 规划推理 |\n| Project | 5 | 未来投影 |\n| Anticipate | 4 | 主动预期 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性检查 |\n\n### 注意力操作\n\n```python\n# 聚焦特定节点并扩散激活\nresult = db.think(\n operation=\"attend\",\n seeds=[\"node_id_1\", \"node_id_2\"],\n max_hops=3,\n decay=0.9\n)\n```\n\n### 信念整合\n\n```python\n# 整合新证据到信念网络\nresult = db.think(\n operation=\"believe\",\n evidence={\n \"target\": \"belief_node_id\", # 可选，None则创建新信念\n \"observation\": \"用户今天说喜欢喝咖啡\",\n \"direction\": \"positive\" # positive=确认, negative=矛盾\n }\n)\n```\n\n## 需求分类系统\n\n系统内置完整的需求分类层级：\n\n```mermaid\ngraph TD\n Need --> Informational\n Need --> Social\n Need --> Emotional\n Need --> Organizational\n Need --> Creative\n Need --> Health\n Need --> Financial\n Need --> Professional\n```\n\n| 类别 | 标识符 |\n|------|--------|\n| 信息需求 | informational |\n| 社交需求 | social |\n| 情感需求 | emotional |\n| 组织需求 | organizational |\n| 创造需求 | creative |\n| 健康需求 | health |\n| 财务需求 | financial |\n| 职业需求 | professional |\n\n## 冲突检测与解决\n\n### 冲突类型\n\n| 类型 | 标识符 | 默认优先级 |\n|------|--------|-----------|\n| 身份事实冲突 | identity_fact | critical |\n| 偏好冲突 | preference | high |\n| 时间冲突 | temporal | high |\n| 整合冲突 | consolidation | medium |\n| 轻微冲突 | minor | low |\n\n### 冲突结构\n\n```python\nclass Conflict:\n conflict_id: str # 冲突唯一ID\n conflict_type: str # 冲突类型\n priority: str # 优先级\n status: str # 状态\n memory_a: str # 冲突方A\n memory_b: str # 冲突方B\n entity: Optional[str] # 相关实体\n detected_at: float # 检测时间\n detected_by: str # 检测方法\n resolution_note: Optional[str] # 解决说明\n```\n\n## 叙事弧线追踪\n\n系统支持叙事弧线（Narrative Arc）来理解用户生活中的长期主题：\n\n**弧线类型：**\n\n- Project（项目）\n- Habit（习惯）\n- Relationship（关系）\n- Discovery（发现）\n- Loss（失去）\n- Recovery（恢复）\n\n**弧线状态：**\n\n```mermaid\nstateDiagram-v2\n [*] --> Emerging\n Emerging --> Active\n Active --> Paused\n Paused --> Active\n Active --> Resolved\n Active --> Abandoned\n Paused --> Abandoned\n Resolved --> [*]\n Abandoned --> [*]\n```\n\n## 完整示例\n\n```python\nfrom yantrikdb import YantrikDB\n\n# 1. 初始化\ndb = YantrikDB(path=\"./data\", namespace=\"user_001\")\n\n# 2. 记录情景记忆\ndb.remember(\n text=\"用户下午3点与张经理开会讨论Q4计划\",\n memory_type=\"episode\",\n entities=[\"张经理\"],\n domain=\"work\"\n)\n\n# 3. 创建关联任务\ndb.think(operation=\"create_task\", description=\"跟进Q4计划讨论结果\")\n\n# 4. 设置偏好\ndb.set_preference(domain=\"notifications\", preferred=\"静默模式\")\n\n# 5. 查询相关记忆\nresults = db.query(\n query=\"Q4计划相关\",\n top_k=5,\n memory_type=[\"episode\", \"task\"],\n expand_entities=True\n)\n\n# 6. 提取同步数据（用于多设备同步）\nops = db.extract_ops_since(since_op_id=\"last_sync_id\")\n```\n\n## 下一步\n\n- 查看 [架构设计](./architecture.md) 深入了解系统内部实现\n- 参考 [API 文档](./api_reference.md) 获取完整接口说明\n- 阅读 [认知引擎](./cognitive_engine.md) 了解推理机制\n- 查看 [复制协议](./replication.md) 学习多节点同步\n\n---\n\n\n\n## 五大索引架构\n\n### 相关页面\n\n相关主题：[YantrikDB 简介](#page-introduction), [解耦写入路径](#page-decoupled-write-path), [知识图谱操作](#page-knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/vector/hnsw.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/hnsw.rs)\n- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n- [crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n- [crates/yantrikdb-core/src/knowledge/graph_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph_index.rs)\n- [crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n \n\n# 五大索引架构\n\n## 概述\n\nyantrikdb 采用多层次、多类型的索引架构来支撑知识存储与检索能力。根据源码组织结构，该系统主要包含五大索引组件：\n\n| 索引类型 | 源码位置 | 主要用途 |\n|---------|---------|---------|\n| HNSW 向量索引 | `vector/hnsw.rs` | 高维向量相似性搜索 |\n| Delta 索引 | `vector/delta_index.rs` | 增量数据变更追踪 |\n| 知识图谱索引 | `knowledge/graph.rs` | 实体关系网络存储 |\n| 图索引 | `knowledge/graph_index.rs` | 图遍历查询优化 |\n| 引擎索引 | `engine/indices.rs` | 统一索引协调管理 |\n\n资料来源：[crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n\n---\n\n## 一、HNSW 向量索引\n\n### 1.1 架构设计\n\nHNSW（Hierarchical Navigable Small World）是一种基于概率跳表结构的近似最近邻搜索算法，在 yantrikdb 中用于支持语义相似性检索。\n\n```mermaid\ngraph TD\n A[输入向量] --> B[搜索层 L_max]\n B --> C[搜索层 L_1]\n C --> D[底层向量空间]\n D --> E[候选最近邻]\n E --> F[精排结果]\n \n G[插入向量] --> H[随机层选择]\n H --> I[自上而下插入]\n I --> D\n```\n\n### 1.2 核心特性\n\n- **分层结构**：构建多层 skip list，每层跳过的距离逐渐缩小\n- **贪心搜索**：在每层执行贪心遍历寻找最优邻居\n- **ef_construction 参数**：控制构建时候选集大小，影响索引质量与构建时间\n- **ef_search 参数**：控制搜索时候选集大小，影响查询精度与延迟\n\n### 1.3 应用场景\n\n| 场景 | 说明 |\n|-----|------|\n| 语义记忆检索 | 基于文本 embedding 查找相关记忆 |\n| 向量相似匹配 | 支持余弦相似度、欧氏距离等度量 |\n| 召回阶段加速 | 在大规模候选集中快速定位 top-k |\n\n资料来源：[crates/yantrikdb-core/src/vector/hnsw.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/hnsw.rs)\n\n---\n\n## 二、Delta 索引\n\n### 2.1 设计目的\n\nDelta 索引用于追踪和管理增量变更，避免频繁全量重建索引带来的性能开销。\n\n```mermaid\ngraph LR\n A[新增数据] --> B[Delta Log]\n C[修改数据] --> B\n D[删除数据] --> B\n \n B --> E[增量合并]\n E --> F[主索引更新]\n \n G[查询请求] --> H[合并视图]\n H --> G\n```\n\n### 2.2 核心数据结构\n\nDelta 索引维护一个变更日志，包含以下操作类型：\n\n| 操作类型 | 说明 | 对索引的影响 |\n|---------|------|-------------|\n| INSERT | 新增记录 | 追加到索引末尾 |\n| UPDATE | 更新记录 | 标记旧版本、插入新版本 |\n| DELETE | 删除记录 | 软删除或版本号标记 |\n\n### 2.3 合并策略\n\n- **定期合并**：定时将 delta 变更合并回主索引\n- **阈值触发**：当 delta 大小超过阈值时触发合并\n- **写时合并**：高写入场景采用 LSM-tree 风格的合并策略\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n\n---\n\n## 三、知识图谱索引\n\n### 3.1 图模型\n\nyantrikdb 的知识图谱采用属性图模型，支持多类型节点和关系边。\n\n```mermaid\ngraph TD\n A[Entity 节点] -->|HasAttribute| B[属性键值对]\n A -->|BelongsTo| C[命名空间]\n \n D[Relation 边] -->|src| A\n D -->|dst| E[目标节点]\n D -->|rel_type| F[关系类型]\n D -->|temporal| G[时序信息]\n \n H[元数据] -->|provenance| I[来源信息]\n H -->|confidence| J[置信度]\n```\n\n### 3.2 节点类型体系\n\n系统支持多种认知节点类型，通过 `NodeKind` 枚举统一管理：\n\n| 节点类型 | 英文标识 | 持久化 | 说明 |\n|---------|---------|-------|------|\n| 实体 | entity | ✓ | 事实性信息 |\n| 事件 | episode | ✓ | 时序发生的事件 |\n| 信念 | belief | ✓ | 带有置信度的认知 |\n| 目标 | goal | ✓ | 用户意图目标 |\n| 任务 | task | ✓ | 具体行动项 |\n| 意图假设 | intent_hypothesis | ✗ | 临时推理结果 |\n| 习惯 | routine | ✓ | 周期性行为 |\n| 需求 | need | ✓ | 用户需求分类 |\n| 机会 | opportunity | ✓ | 时限性机会 |\n| 风险 | risk | ✓ | 潜在问题 |\n| 约束 | constraint | ✓ | 限制条件 |\n| 偏好 | preference | ✓ | 用户偏好设置 |\n| 对话线索 | conversation_thread | ✗ | 临时对话状态 |\n| 行动模式 | action_schema | ✓ | 可执行动作模板 |\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n\n### 3.3 边类型与激活传递\n\n边类型定义了节点间的语义关联强度，影响激活传播算法：\n\n| 关系类型 | 激活传递系数 | 说明 |\n|---------|-------------|------|\n| causes | 0.8 | 强因果关系 |\n| supports | 0.7 | 支持关系 |\n| triggers | 0.7 | 触发关系 |\n| advances_goal | 0.6 | 推进目标 |\n| requires | 0.5 | 依赖关系 |\n| subtask_of | 0.4 | 子任务关系 |\n| predicts | 0.4 | 预测关系 |\n| associated_with | 0.3 | 关联关系 |\n| similar_to | 0.3 | 相似关系 |\n| precedes_temporally | 0.2 | 时序先导 |\n| contradicts | -0.5 | 矛盾关系 |\n| blocks_goal | -0.6 | 阻碍目标 |\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n\n---\n\n## 四、图索引\n\n### 4.1 索引构建策略\n\n图索引针对知识图谱的查询模式进行专门优化，支持多种索引类型：\n\n```mermaid\ngraph LR\n A[原始图数据] --> B[关系类型索引]\n A --> C[时序索引]\n A --> D[命名空间索引]\n A --> E[属性索引]\n \n B --> F[关系遍历加速]\n C --> G[时序查询优化]\n D --> H[多租户隔离]\n E --> I[属性过滤加速]\n```\n\n### 4.2 查询优化\n\n| 优化类型 | 实现方式 | 适用场景 |\n|---------|---------|---------|\n| 入度/出度索引 | 预计算节点连接数 | 度过滤查询 |\n| 邻接列表 | 按关系类型分组存储 | 批量遍历 |\n| 时序索引 | B-Tree 或 LSM-Tree | 范围查询 |\n| 命名空间索引 | Hash 分区 | 多租户隔离 |\n\n### 4.3 冲突检测\n\n图索引支持基于命名空间策略的冲突检测：\n\n- **overlap_allowed**：是否允许同一关系类型的重叠\n- **temporal_required**：是否要求时序约束\n- **missing_time_severity**：缺失时序信息的严重级别\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph_index.rs)\n\n---\n\n## 五、引擎索引协调层\n\n### 5.1 统一索引接口\n\n引擎索引作为协调层，统一管理上述各类索引的创建、查询和生命周期：\n\n```mermaid\ngraph TD\n A[Query 请求] --> B[引擎索引协调器]\n B --> C{Hash 路由}\n C -->|向量查询| D[HNSW 索引]\n C -->|图查询| E[图索引]\n C -->|混合查询| F[Delta 合并]\n \n D --> G[结果集]\n E --> G\n F --> G\n \n G --> H[结果合并与排序]\n H --> I[最终结果]\n \n J[写入请求] --> K[Delta 索引]\n K --> L{合并阈值}\n L -->|触发| M[主索引更新]\n M --> D\n M --> E\n```\n\n### 5.2 索引配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| hnsw_ef_construction | u32 | 100 | HNSW 构建参数 |\n| hnsw_ef_search | u32 | 50 | HNSW 搜索参数 |\n| hnsw_m | u32 | 16 | HNSW 邻居数 |\n| delta_merge_threshold | usize | 10000 | Delta 合并阈值 |\n| graph_cache_size | usize | 1000 | 图索引缓存大小 |\n\n### 5.3 索引生命周期\n\n| 阶段 | 操作 | 说明 |\n|-----|------|------|\n| 创建 | `create_index()` | 根据配置初始化索引结构 |\n| 写入 | `insert()` / `upsert()` | 添加或更新索引数据 |\n| 查询 | `search()` / `query()` | 执行索引检索 |\n| 合并 | `merge_delta()` | 将增量合并回主索引 |\n| 重建 | `rebuild()` | 全量重建索引 |\n| 删除 | `drop_index()` | 清理索引资源 |\n\n资料来源：[crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n\n---\n\n## 六、协同工作流程\n\n### 6.1 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as 引擎索引\n participant Delta as Delta 索引\n participant HNSW as HNSW\n participant Graph as 图索引\n \n Client->>Engine: 写入请求\n Engine->>Delta: 记录变更\n Engine->>HNSW: 异步插入向量\n Engine->>Graph: 创建/更新节点/边\n \n alt Delta 达到阈值\n Delta->>Engine: 触发合并\n Engine->>HNSW: 批量更新\n Engine->>Graph: 批量更新\n end\n```\n\n### 6.2 查询流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as 引擎索引\n participant HNSW as HNSW\n participant Graph as 图索引\n participant Recall as Recall 查询\n \n Client->>Engine: Recall 查询\n Engine->>Recall: 构建查询参数\n Recall->>HNSW: 向量相似搜索\n Recall->>Graph: 图关系扩展\n HNSW-->>Recall: Top-K 向量结果\n Graph-->>Recall: 关系过滤结果\n Recall->>Engine: 合并排序结果\n Engine-->>Client: 最终结果\n```\n\n### 6.3 认知查询语言集成\n\n系统通过 `RecallQuery` 结构支持组合查询：\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| embedding | Vec | 查询向量 |\n| top_k | usize | 返回结果数量 |\n| memory_type | Option<&str> | 记忆类型过滤 |\n| namespace | Option<&str> | 命名空间隔离 |\n| time_window | Option<(f64, f64)> | 时序范围 |\n| domain | Option<&str> | 领域过滤 |\n| source | Option<&str> | 来源过滤 |\n\n---\n\n## 七、总结\n\nyantrikdb 的五大索引架构通过分层设计实现了高效的知识存储与检索：\n\n1. **HNSW 向量索引**：提供亚线性时间复杂度的近似最近邻搜索能力\n2. **Delta 索引**：通过增量变更追踪实现高写入性能\n3. **知识图谱索引**：支持丰富的语义关系建模\n4. **图索引**：针对图遍历操作进行专门优化\n5. **引擎索引协调层**：统一管理各类索引，提供一致的查询接口\n\n这些索引组件相互协作，共同支撑了 yantrikdb 作为认知数据库的核心功能。\n\n---\n\n\n\n## 解耦写入路径\n\n### 相关页面\n\n相关主题：[五大索引架构](#page-five-indexes), [线程安全与并发模型](#page-threading-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/decoupled_write_path_rfc.md](https://github.com/yantrikos/yantrikdb/blob/main/docs/decoupled_write_path_rfc.md)\n- [CONCURRENCY.md](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md)\n- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n- [crates/yantrikdb-core/src/engine/materializer.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/materializer.rs)\n \n\n# 解耦写入路径\n\n## 概述\n\n解耦写入路径（Decoupled Write Path）是 yantrikdb 中一项核心架构设计，旨在将前台写入操作与向量索引维护工作彻底分离。该设计解决了传统向量数据库在高并发写入场景下的性能瓶颈问题。\n\n传统的向量数据库通常将写入操作与索引更新耦合在一起，导致写入线程在执行 HNSW（Hierarchical Navigable Small World）图构建时产生显著延迟。yantrikdb 通过引入 **Delta Index** 增量索引机制，将写入操作限制在 O(1) 复杂度的简单数据结构中，而将计算密集型的 HNSW 索引构建工作委托给后台压缩进程执行。\n\n资料来源：[docs/decoupled_write_path_rfc.md:1-20]()\n\n## 核心设计原则\n\n### 写入操作的约束\n\n解耦写入路径对前台写入操作施加了严格的约束，确保写入路径保持极低的延迟：\n\n| 操作类型 | 允许操作 | 禁止操作 |\n|---------|---------|---------|\n| DeltaIndex | `append` / `tombstone` | `HnswIndex::insert` |\n| 序列号分配 | `assign_seq` (atomic fetch_add) | `HnswIndex::remove` |\n| 可见性更新 | `bump_visible_seq` | `compact()` |\n\n资料来源：[CONCURRENCY.md:1-30]()\n\n### 写入操作的职责边界\n\n写入原语（如 `record_with_rid`、`forget`、`correct` 等）**必须**仅执行以下操作：\n\n- `DeltaIndex::append` / `DeltaIndex::tombstone`：O(1) 复杂度的写操作，仅进行简单的向量推送，不涉及 HNSW 工作\n- `assign_seq`：原子序列号分配，使用 `fetch_add` 或 `fetch_max`\n- `bump_visible_seq`：DashMap 分片读取 + `AtomicU64::fetch_max`，稳态下无锁\n\n写入原语**禁止**调用：\n\n- `HnswIndex::insert` / `HnswIndex::remove`：这些属于压缩进程的职责\n- `compact()`：仅允许后台执行\n\n资料来源：[CONCURRENCY.md:25-40]()\n\n## 架构设计\n\n### 分层存储结构\n\nyantrikdb 采用冷热分离的分层存储架构：\n\n```mermaid\ngraph TD\n subgraph 前台写入路径\n Write[写入请求] --> Delta[DeltaIndex
热数据层]\n Delta --> Append[append
O1复杂度]\n Delta --> Tombstone[tombstone
墓碑标记]\n end\n \n subgraph 后台压缩路径\n Compact[compact
后台进程] --> Seal[seal_delta_for_compaction
密封热数据]\n Seal --> Clone[clone-rebuild cold
克隆重建冷数据]\n Clone --> Install[安装新的冷数据层]\n Delta -.->|定期触发| Compact\n end\n \n subgraph 存储层\n Cold[ArcSwap<HnswIndex>
冷数据层-只读快照]\n Install --> Cold\n end\n \n subgraph 读取路径\n Read[读取请求] --> Snapshot[获取快照]\n Snapshot -->|lock-free| Cold\n Snapshot -->|lock-free| Delta\n end\n```\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs:1-50]()\n\n### DeltaIndex 实现\n\nDeltaIndex 是解耦写入路径的核心数据结构，负责管理增量写入操作：\n\n```mermaid\nclassDiagram\n class DeltaIndex {\n +entries: RwLock~Vec~DeltaEntry~~\n +append(entry: DeltaEntry)\n +tombstone(rid: &str)\n +compact() -> HnswIndex\n +seal_delta_for_compaction() Vec~DeltaEntry~\n }\n \n class DeltaEntry {\n +op_type: OpType\n +rid: String\n +vector: Vec~f32~\n +seq: u64\n +is_tombstone: bool\n }\n \n class OpType {\n <>\n Insert\n Update\n Delete\n }\n```\n\nDeltaIndex 的 `append` 和 `tombstone` 方法是 O(1) 复杂度的操作，不会触发任何 HNSW 索引更新。这确保了前台写入的极低延迟。\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs:50-150]()\n\n### ArcSwap 冷数据层\n\n冷数据层采用 `ArcSwap` 实现，而非传统的 `RwLock` 或 `Mutex`。这种设计提供了无锁的快照获取能力：\n\n```rust\n// 正确的实现方式\nstruct ColdTier {\n index: ArcSwap, // 原子交换的不可变快照\n}\n```\n\n**关键不变量**：不得将冷数据层的 `ArcSwap` 替换为 `RwLock` 或 `Mutex`。这种替换会破坏并发性能，导致读取 p99 延迟上升。\n\n资料来源：[CONCURRENCY.md:60-80]()\n\n## 后台压缩机制\n\n### 压缩流程\n\n后台压缩进程负责将增量数据合并到主索引中：\n\n```mermaid\nsequenceDiagram\n participant Write as 写入线程\n participant Delta as DeltaIndex\n participant Compact as 压缩进程\n participant Cold as ArcSwap冷数据层\n \n Write->>Delta: append(entry)\n Write->>Delta: bump_visible_seq(ns)\n \n Note over Delta: 稳态无锁操作\n \n Compact->>Delta: seal_delta_for_compaction()\n Note over Delta: 短暂持有delta RwLock
仅用于密封操作\n \n Compact->>Compact: clone-rebuild cold\n Note over Compact: 不持有任何锁\n \n Compact->>Cold: ArcSwap::store(new_index)\n Note over Cold: 短暂持有install锁\n \n Write->>Cold: load_arc() 获取新快照\n Write->>Delta: 继续追加新entry\n```\n\n压缩进程在执行克隆重建期间**不会持有**任何前台写入需要获取的锁。这确保了写入操作不会因压缩而阻塞。\n\n资料来源：[CONCURRENCY.md:45-60]()\n\n### 锁的获取顺序\n\n| 阶段 | 持有的锁 | 时长 |\n|-----|---------|-----|\n| 密封阶段 | `delta` RwLock | 短暂 |\n| 重建阶段 | 无 | 较长 |\n| 安装阶段 | `delta` RwLock | 短暂 |\n\n资料来源：[CONCURRENCY.md:45-55]()\n\n## 并发控制\n\n### visible_seq 的无锁实现\n\nPhase 6 引入的 `visible_seq` 映射表**必须**保持读取无锁特性：\n\n```rust\n// 字段类型定义\nvisible_seq: DashMap\n\n// 读取路径 (lock-free)\nlet seq = visible_seq\n .get(ns)\n .map(|e| e.load(Acquire));\n\n// 写入路径 (fast path)\nvisible_seq\n .get(ns)\n .fetch_max(seq, Release);\n```\n\n**性能影响**：在集群规模下，`visible_seq_for(ns)` 在每次 `recall_with_seq` 调用时都会执行。如果替换为 `Mutex`，会导致集群 RYW（Read-Your-Writes）退化为全局互斥锁热点路径。\n\n资料来源：[CONCURRENCY.md:85-100]()\n\n### 写入原语的模式\n\n所有新的写入原语必须遵循 `record_with_rid` 的模式：\n\n```mermaid\ngraph LR\n A[SAVEPOINT] --> B[SQL操作]\n B --> C[DeltaIndex::append]\n C --> D[bump_visible_seq]\n D --> E[COMMIT/ROLLBACK]\n```\n\n资料来源：[CONCURRENCY.md:35-40]()\n\n## Materializer 模块\n\nMaterializer 负责将查询结果从内部表示转换为外部格式，是解耦写入路径在读取侧的配合组件：\n\n```mermaid\nclassDiagram\n class Materializer {\n +materialize(query_result: QueryResult) -> SurfaceResult\n +apply_salience(node: Node) -> Node\n +filter_hidden(nodes: Vec~Node~) -> Vec~Node~\n }\n \n class QueryResult {\n +nodes: Vec~NodeId~\n +scores: Vec~f64~\n +context: RecallContext\n }\n \n class SurfaceResult {\n +items: Vec~SurfaceItem~\n +metadata: SurfaceMetadata\n }\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/materializer.rs:1-60]()\n\n## 配置选项\n\n解耦写入路径的行为可通过以下配置进行调整：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|-----|\n| `delta_capacity` | usize | 10000 | DeltaIndex 的初始容量 |\n| `compaction_interval_secs` | u64 | 3600 | 压缩检查间隔（秒） |\n| `compaction_batch_size` | usize | 1000 | 每次压缩处理的条目数 |\n| `tombstone_retention_secs` | u64 | 86400 | 墓碑保留时间 |\n\n资料来源：[docs/decoupled_write_path_rfc.md:50-80]()\n\n## 性能特性\n\n### 写入性能\n\n| 指标 | 目标值 | 说明 |\n|-----|-------|-----|\n| 写入延迟 P50 | < 1ms | 单次 append 操作 |\n| 写入延迟 P99 | < 5ms | 含序列号分配 |\n| 写入吞吐量 | > 50k/s | 8 写入线程下 |\n\n资料来源：[CONCURRENCY.md:70-75]()\n\n### 读取性能\n\n| 指标 | 目标值 | 说明 |\n|-----|-------|-----|\n| 读取延迟 P50 | < 10ms | 含快照获取 |\n| 读取延迟 P99 | < 200ms | 8 写入线程 / 30s 压力下 |\n\n资料来源：[CONCURRENCY.md:75-80]()\n\n## 最佳实践\n\n### 开发新写入原语\n\n新增写入原语时，必须遵循以下模式：\n\n1. **使用 SAVEPOINT 包装**：确保 SQL 操作的事务性\n2. **调用 DeltaIndex::append**：而非直接操作 HNSW 索引\n3. **调用 bump_visible_seq**：更新命名空间的可见序列号\n4. **禁止阻塞操作**：不得在写入路径中调用任何可能阻塞的操作\n\n```rust\n// 正确的实现示例\nfn new_write_primitive(&self, entry: DeltaEntry) -> Result<()> {\n self.conn().execute(\"SAVEPOINT sp_new_write\")?;\n \n // SQL 操作\n self.sql_insert(&entry)?;\n \n // DeltaIndex 操作\n self.delta.append(entry.clone())?;\n \n // 可见性更新\n self.bump_visible_seq(&entry.namespace)?;\n \n self.conn().execute(\"RELEASE SAVEPOINT sp_new_write\")?;\n Ok(())\n}\n```\n\n资料来源：[CONCURRENCY.md:30-45]()\n\n### 验证并发正确性\n\n新增写入原语后，必须验证：\n\n- 运行 `crates/yantrikdb-core/examples/wedge_repro.rs` 示例\n- 确保读取 p99 延迟 < 200ms（8 写入线程 / 30s 压力下）\n- 确认读取 P50 延迟保持稳定\n- 验证写入吞吐量未下降\n\n资料来源：[CONCURRENCY.md:70-80]()\n\n## 总结\n\n解耦写入路径是 yantrikdb 架构中的关键创新，通过以下设计实现了高并发下的稳定性能：\n\n- **热数据层（DeltaIndex）**：O(1) 复杂度的无阻塞写入\n- **冷数据层（ArcSwap）**：无锁的只读快照访问\n- **后台压缩**：将 HNSW 计算与前台写入完全隔离\n- **DashMap visible_seq**：集群级别的无锁读取保证\n\n这种设计使得 yantrikdb 能够在高写入负载下保持毫秒级的查询延迟，同时支持复杂的向量搜索能力。\n\n资料来源：[docs/decoupled_write_path_rfc.md:80-100](), [CONCURRENCY.md:1-100]()\n\n---\n\n\n\n## 线程安全与并发模型\n\n### 相关页面\n\n相关主题：[解耦写入路径](#page-decoupled-write-path)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONCURRENCY.md](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md)\n- [crates/yantrikdb-core/src/engine/mod.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/mod.rs)\n- [crates/yantrikdb-core/src/engine/tick.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/tick.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n \n\n# 线程安全与并发模型\n\nyantrikdb 是一个基于 Rust 构建的认知数据库引擎，其线程安全与并发模型是保障系统在高并发读写场景下稳定运行的核心设计。本文档详细阐述 yantrikdb 的并发控制机制、锁策略、以及核心不变性保证。\n\n## 1. 设计目标与约束\n\nyantrikdb 的并发模型围绕以下核心目标设计：\n\n| 目标 | 描述 |\n|------|------|\n| **读写分离** | 读取操作不应被写入操作阻塞 |\n| **无锁读取** | 读取路径尽可能采用 lock-free 数据结构 |\n| **写吞吐** | 写入操作需保持高吞吐量，避免锁竞争 |\n| **后台隔离** | 压缩（compaction）等重量级操作不得干扰前台写入 |\n\n资料来源：[CONCURRENCY.md:1-15]()\n\n## 2. 核心并发规则\n\nyantrikdb 定义了六条必须遵守的并发不变性规则：\n\n### 2.1 规则一：写入路径禁止非 O(1) 锁\n\n所有写操作原语必须遵守**单锁原则**：禁止在写路径中获取任何非 O(1) 复杂度的锁。任何新的写原语必须仅使用：\n\n- `DeltaIndex::append` / `DeltaIndex::tombstone`（短暂 RwLock 写操作）\n- `assign_seq`（原子操作 fetch_add 或 fetch_max）\n- `bump_visible_seq`（DashMap 分片读取 + AtomicU64::fetch_max）\n\n资料来源：[CONCURRENCY.md:17-25]()\n\n### 2.2 规则二：写入原语仅操作增量索引\n\n以下写入操作**必须仅**触碰增量索引相关接口：\n\n- `upsert_*_with_rid`\n- `forget`\n- `correct`\n- `upsert_entity_edge_with_id`\n- `delete_entity_edge_with_id`\n\n它们**禁止**调用：\n\n- `HnswIndex::insert` / `HnswIndex::remove`（仅压缩时可用）\n- `compact()`（仅后台执行）\n- 任何压缩器也会获取的新 RwLock\n\n新增写原语需遵循 `record_with_rid` 的模式：SAVEPOINT 保护的 SQL 块 + `DeltaIndex::append` + `bump_visible_seq`。\n\n资料来源：[CONCURRENCY.md:27-42]()\n\n### 2.3 规则三：后台压缩与前台写操作锁隔离\n\n`DeltaIndex::compact` 执行昂贵的 HNSW 向量索引重建工作，其锁持有策略如下：\n\n```mermaid\ngraph TD\n A[开始压缩] --> B[seal_delta_for_compaction]\n B --> C{获取 delta RwLock}\n C -->|短暂| D[交换待处理条目]\n D --> E[释放 delta 锁]\n E --> F[执行 HNSW 重建]\n F --> G{获取 delta RwLock}\n G -->|短暂| H[安装新 cold tier]\n H --> I[释放锁]\n I --> J[压缩完成]\n \n K[前台写入] -.->|不受 F 阶段阻塞| L[DeltaIndex::append]\n```\n\n后台压缩在**封存**（seal）和**安装**（install）阶段短暂持有 delta 锁，在 HNSW 重建期间**不持有**任何前台写入也会获取的锁。\n\n资料来源：[CONCURRENCY.md:44-58]()\n\n## 3. 分层存储与读写分离\n\nyantrikdb 采用分层存储架构实现读写分离：\n\n```mermaid\ngraph TD\n subgraph 写入路径\n W[写入请求] --> D[DeltaIndex
增量索引]\n D --> |append| DS[DeltaIndex 结构
RwLock Vec]\n end\n \n subgraph 读取路径\n R[读取请求] --> C[Cold Tier]\n C --> |ArcSwap| HI[HnswIndex
向量索引]\n end\n \n subgraph 后台压缩\n CP[Compactor] --> |定期| CC[Clone + Rebuild]\n CC --> |install| C\n end\n \n DS -.->|compaction| CC\n```\n\n### 3.1 Cold Tier 的 ArcSwap 保证\n\nCold tier（冷数据层）必须使用 `ArcSwap` 而非 `RwLock` 或 `Mutex`。\n\n| 锁类型 | 读取行为 | 问题 |\n|--------|----------|------|\n| `RwLock` | 写锁持有期间阻塞所有读取 | 高并发下读取延迟飙升 |\n| `Mutex` | 独占访问 | 完全串行化读取 |\n| `ArcSwap` | 读取获取稳定快照 | 无锁读取，性能稳定 |\n\n**不变性**：不要用 `RwLock` 或 `Mutex` 替换 cold tier 的 `ArcSwap`。如需验证，应运行 `crates/yantrikdb-core/examples/wedge_repro.rs` 并保持 v0.6.6 版本后的性能指标（8 writers / 30s 下读取 p99 < 200ms）。\n\n资料来源：[CONCURRENCY.md:60-75]()\n\n## 4. Visible Sequence 的 Lock-Free 设计\n\n### 4.1 架构设计\n\n`visible_seq` 是 Phase 6 引入的读-your-writes（RYW）可见性机制，其数据结构定义为：\n\n```rust\ndashmap::DashMap\n```\n\n| 操作 | 方法 | 复杂度 |\n|------|------|--------|\n| 读取 | `get(ns).map(|e| e.load(Acquire))` | O(1), lock-free |\n| 写入 | `get(ns).fetch_max(seq, Release)` | O(1), lock-free |\n\n### 4.2 性能影响\n\n`visible_seq_for(ns)` 在每次 `recall_with_seq` 调用时都会执行，在集群规模下这是**主要流量路径**。用 `Mutex>` 替代将导致全局互斥锁热点，严重影响集群 RYW 性能。\n\n**不变性**：`YantrikDB::visible_seq` 字段类型必须保持为 `dashmap::DashMap`。\n\n资料来源：[CONCURRENCY.md:77-90]()\n\n## 5. 认知引擎的操作符并发模型\n\n认知引擎（cognition engine）通过 DSL 定义操作符的执行优先级：\n\n### 5.1 操作符优先级表\n\n| 优先级 | 操作符 | 说明 |\n|--------|--------|------|\n| 10 | `Attend` | 基础注意力机制，始终执行 |\n| 9 | `Recall` | 上下文召回关键操作 |\n| 8 | `Believe` | 证据整合 |\n| 7 | `Compare` | 动作选择 |\n| 7 | `Constrain` | 安全约束，必要时执行 |\n| 6 | `Plan` | 手段-目标推理 |\n| 5 | `Project` | 前向模拟 |\n| 4 | `Anticipate` | 主动预测 |\n| 3 | `Assess` | 元认知评估 |\n| 2 | `CoherenceCheck` | 一致性检查，高压下可跳过 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n### 5.2 步骤执行结果输出\n\n```rust\npub enum StepOutput {\n Attend(AttendOutput),\n Recall(RecallOutput),\n Believe(BelieveOutput),\n Compare(CompareOutput),\n Constrain(ConstrainOutput),\n Plan(PlanOutput),\n Project(ProjectOutput),\n Anticipate(AnticipateOutput),\n Assess(AssessOutput),\n CoherenceCheck(CoherenceCheckOutput),\n Skipped { reason: String },\n Error { message: String },\n}\n```\n\n操作符执行结果通过 `ExplanationTrace` 结构进行追踪和解释构建：\n\n```rust\nfn build_explanation(steps: &[StepResult]) -> ExplanationTrace {\n let explanation_steps: Vec = steps\n .iter()\n .enumerate()\n .filter(|(_, s)| s.success)\n .map(|(i, s)| ExplanationStep {\n step_number: i + 1,\n operator: s.operator.clone(),\n description: s.trace.clone().unwrap_or_else(|| ...),\n key_insight: extract_key_insight(&s.output),\n })\n .collect();\n // ...\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:150-180]()\n\n## 6. 分布式冲突检测\n\n在分布式场景下，yantrikdb 使用 `relation_policies` 表管理命名空间级别的冲突策略：\n\n```sql\nSELECT overlap_allowed, temporal_required, missing_time_severity\nFROM relation_policies\nWHERE relation_type = ?1 AND (namespace = ?2 OR namespace = '*')\nORDER BY CASE WHEN namespace = ?2 THEN 0 ELSE 1 END\nLIMIT 1\n```\n\n### 6.1 冲突检测流程\n\n```mermaid\ngraph TD\n A[检测候选关系对] --> B{超过最大冲突数?}\n B -->|是| Z[停止检测]\n B -->|否| C[查询命名空间策略]\n C --> D{存在策略记录?}\n D -->|是| E[应用 overlap_allowed]\n D -->|否| F[使用全局 '*' 策略]\n E --> G{冲突类型检查}\n F --> G\n G --> H[标记冲突节点]\n```\n\n### 6.2 冲突类型\n\n| 冲突类型 | 默认优先级 | 说明 |\n|----------|------------|------|\n| `IdentityFact` | critical | 身份事实冲突 |\n| `Preference` | high | 偏好冲突 |\n| `Temporal` | high | 时间维度冲突 |\n| `Consolidation` | medium | 整合冲突 |\n| `Minor` | low | 轻微冲突 |\n\n资料来源：[crates/yantrikdb-core/src/distributed/conflict.rs:1-50]()\n\n## 7. 认知节点的状态与激活传播\n\n### 7.1 节点类型\n\n| 节点类型 | 持久化 | 激活转移因子 |\n|----------|--------|--------------|\n| `Entity` | ✓ | 0.8 |\n| `Episode` | ✓ | 0.6 |\n| `Belief` | ✓ | 0.7 |\n| `Goal` | ✓ | 0.6 |\n| `Task` | ✓ | 0.4 |\n| `IntentHypothesis` | ✗ | 0.5 |\n| `Routine` | ✓ | 0.5 |\n| `Need` | ✓ | 0.6 |\n| `Opportunity` | ✓ | 0.4 |\n| `Risk` | ✓ | 0.4 |\n| `Constraint` | ✓ | 0.9 |\n| `Preference` | ✓ | 0.6 |\n| `ConversationThread` | ✗ | 0.8 |\n| `ActionSchema` | ✓ | 0.7 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n### 7.2 边缘类型的激活传播\n\n边缘类型决定激活如何在节点间传播，负值表示抑制：\n\n```mermaid\ngraph LR\n A[源节点] -->|\"Supports 0.7\"| B[目标节点]\n A -->|\"Causes 0.8\"| C[目标节点]\n A -->|\"Inhibits -0.5\"| D[目标节点]\n```\n\n| 边缘类型 | 激活转移 | 语义 |\n|----------|----------|------|\n| `Supports` | 0.7 | 支持关系 |\n| `Causes` | 0.8 | 因果关系 |\n| `AdvancesGoal` | 0.6 | 推进目标 |\n| `Triggers` | 0.7 | 触发关系 |\n| `Requires` | 0.5 | 依赖关系 |\n| `SubtaskOf` | 0.4 | 子任务关系 |\n| `Contradicts` | -0.6 | 矛盾关系 |\n| `Prevents` | -0.8 | 阻止关系 |\n\n## 8. 认知属性的可靠性模型\n\n### 8.1 来源类型（Provenance）\n\n信息来源影响信任度：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|------------|------|\n| `Told` | 0.95 | 用户明确陈述，最高信任 |\n| `Observed` | 0.90 | 直接观察的行为 |\n| `Experimented` | 0.85 | 通过受控实验确认 |\n| `Consolidated` | 0.80 | 多源合并 |\n| `Extracted` | 0.75 | 外部文档提取，可能过时 |\n| `Inferred` | 0.60 | 基于模式的推断 |\n| `SystemDefault` | 0.50 | 默认值，最弱 |\n\n### 8.2 通用认知属性\n\n每个认知节点携带 11 维属性：\n\n| 属性 | 范围 | 说明 |\n|------|------|------|\n| `confidence` | [0.0, 1.0] | 置信度 |\n| `activation` | [0.0, 1.0] | 激活水平 |\n| `salience` | [0.0, 1.0] | 显著度 |\n| `persistence` | [0.0, 1.0] | 持久性 |\n| `valence` | [-1.0, 1.0] | 情感效价 |\n| `urgency` | [0.0, 1.0] | 紧急程度 |\n| `novelty` | [0.0, 1.0] | 新颖性 |\n| `volatility` | [0.0, 1.0] | 波动性 |\n| `provenance` | enum | 信息来源 |\n| `evidence_count` | u32 | 证据数量 |\n| `last_updated_ms` | u64 | 最后更新时间 |\n\n## 9. 触发器与冷却机制\n\n### 9.1 触发器类型\n\n| 触发器类型 | 默认冷却时间 | 默认过期时间 |\n|------------|--------------|--------------|\n| `DecayReview` | 3 天 | 7 天 |\n| `ConsolidationReady` | 1 天 | 3 天 |\n| `ConflictEscalation` | 2 天 | 14 天 |\n| `TemporalDrift` | 14 天 | 7 天 |\n| `Redundancy` | 1 天 | 7 天 |\n| `RelationshipInsight` | 7 天 | 7 天 |\n| `ValenceTrend` | 7 天 | 7 天 |\n| `EntityAnomaly` | 7 天 | 7 天 |\n| `PatternDiscovered` | 7 天 | 7 天 |\n\n## 10. 行动成本模型\n\n行动类型具有不同的基础成本：\n\n| 行动类型 | 基础成本 | 说明 |\n|----------|----------|------|\n| `Abstain` | 0.0 | 无操作 |\n| `Inform` | 0.05 | 信息通知 |\n| `Organize` | 0.10 | 组织整理 |\n| `Suggest` | 0.15 | 建议提出 |\n| `Communicate` | 0.20 | 主动沟通 |\n| `Schedule` | 0.25 | 日程安排 |\n| `Warn` | 0.30 | 警告提示 |\n| `Execute` | 0.35 | 执行操作 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n## 11. 关键不变性总结\n\n| 编号 | 不变性描述 | 违反后果 |\n|------|------------|----------|\n| INV-1 | 写路径不得获取非 O(1) 锁 | 写入延迟增加 |\n| INV-2 | 写原语仅操作 DeltaIndex | 压缩逻辑耦合前台写入 |\n| INV-3 | 压缩与前台锁隔离 | 前台写入被后台阻塞 |\n| INV-4 | Cold tier 使用 ArcSwap | 读取延迟飙升（wedge 问题） |\n| INV-5 | visible_seq 保持 lock-free | 全局互斥锁成为热点 |\n\n---\n\n**相关文档**：\n- [架构设计](./architecture.md)\n- [分布式冲突检测](./distributed-conflict.md)\n- [认知引擎](./cognition-engine.md)\n\n---\n\n\n\n## 记录与检索操作\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [认知循环与思考](#page-cognitive-loop)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/engine/record.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/record.rs)\n- [crates/yantrikdb-core/src/engine/recall.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/recall.rs)\n- [crates/yantrikdb-core/src/base/scoring.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/scoring.rs)\n- [src/yantrikdb/api.py](https://github.com/yantrikos/yantrikdb/blob/main/src/src/yantrikdb/api.py)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n \n\n# 记录与检索操作\n\n## 概述\n\n记录（Record）与检索（Recall）是 YantrikDB 的核心认知操作模块，负责信息的持久化存储和上下文感知的记忆召回。记录操作用于将文本、嵌入向量及元数据存入数据库；检索操作用于根据查询向量或文本从存储的记忆中匹配最相关的结果。\n\n这两个操作构成了知识管理的基础循环：记录输入新信息 → 检索召回相关上下文 → 支持推理决策。\n\n---\n\n## 核心架构\n\n### 模块位置\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 记录引擎 | `crates/yantrikdb-core/src/engine/record.rs` | 处理记忆写入、加密、元数据管理 |\n| 检索引擎 | `crates/yantrikdb-core/src/engine/recall.rs` | 向量相似度搜索、评分排序 |\n| 评分系统 | `crates/yantrikdb-core/src/base/scoring.rs` | 多维度相关性评分计算 |\n| Python绑定 | `crates/yantrikdb-python/src/py_engine/memory.rs` | Python API封装 |\n\n### 数据流图\n\n```mermaid\ngraph TD\n subgraph 记录流程\n A[输入文本] --> B[文本嵌入]\n B --> C[重要性评分]\n C --> D[情感极性标注]\n D --> E[加密存储]\n E --> F[(SQLite数据库)]\n end\n \n subgraph 检索流程\n G[查询向量] --> H[候选集生成]\n H --> I[多维度评分]\n I --> J[重排序]\n J --> K[结果过滤]\n K --> L[返回结果]\n end\n \n F -.->|候选集| H\n```\n\n---\n\n## 记录操作\n\n### record 方法签名\n\nPython API 中 `record` 方法的完整签名：\n\n```python\ndef record(\n self,\n text: str,\n memory_type: str = \"episodic\",\n importance: float = 0.5,\n valence: float = 0.5,\n half_life: Optional[float] = None,\n embedding: Optional[List[float]] = None,\n metadata: Optional[Dict] = None,\n namespace: Optional[str] = None,\n certainty: float = 1.0,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n emotional_state: Optional[str] = None,\n) -> str:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `text` | `str` | 必填 | 要记录的文本内容 |\n| `memory_type` | `str` | `\"episodic\"` | 记忆类型（见下表） |\n| `importance` | `float` | `0.5` | 重要性评分 [0.0, 1.0] |\n| `valence` | `float` | `0.5` | 情感极性 [0.0=负面, 1.0=正面] |\n| `half_life` | `float` | `None` | 记忆衰减半衰期（秒），默认按类型自动计算 |\n| `embedding` | `List[float]` | `None` | 预计算的嵌入向量，默认使用内置 embedder |\n| `metadata` | `Dict` | `None` | 自定义键值对元数据 |\n| `namespace` | `str` | `None` | 命名空间隔离 |\n| `certainty` | `float` | `1.0` | 信息确定性 [0.0, 1.0] |\n| `domain` | `str` | `None` | 知识领域标签 |\n| `source` | `str` | `None` | 信息来源标识 |\n| `emotional_state` | `str` | `None` | 记录时的情感状态 |\n\n### 记忆类型\n\n| 类型 | 说明 | 默认半衰期 |\n|------|------|-----------|\n| `episodic` | 情景记忆 - 具体事件经历 | 7天 |\n| `semantic` | 语义记忆 - 抽象知识事实 | 30天 |\n| `procedural` | 程序记忆 - 技能与习惯 | 90天 |\n| `working` | 工作记忆 - 当前任务上下文 | 1小时 |\n| `consolidated` | 已整合记忆 | 由系统管理 |\n\n### 记录流程详解\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant API as Python API\n participant Core as 核心引擎\n participant Embed as 嵌入模块\n participant Crypto as 加密模块\n participant DB as SQLite\n\n User->>API: record(text, importance, ...)\n API->>Core: record(...)\n alt 无预计算嵌入\n Core->>Embed: embed_text(text)\n Embed-->>Core: embedding_vector\n end\n Core->>Core: 计算重要性评分\n Core->>Crypto: encrypt_text(text)\n Crypto-->>Core: encrypted_blob\n Core->>DB: INSERT memory\n DB-->>Core: rid (记录ID)\n Core-->>API: rid\n API-->>User: record_id\n```\n\n### 返回值\n\n记录成功时返回唯一的记录标识符 `rid`（字符串格式），可用于后续的关联查询：\n\n```python\nrid = db.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\n# rid: \"M01H2K3...\"\n```\n\n---\n\n## 检索操作\n\n### recall 方法签名\n\nPython API 中 `recall` 方法的完整签名：\n\n```python\ndef recall(\n self,\n query: Optional[str] = None,\n query_embedding: Optional[List[float]] = None,\n top_k: int = 10,\n time_window: Optional[Tuple[float, float]] = None,\n memory_type: Optional[str] = None,\n include_consolidated: bool = False,\n expand_entities: bool = True,\n skip_reinforce: bool = False,\n namespace: Optional[str] = None,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n) -> List[Dict]:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `query` | `str` | `None` | 自然语言查询文本 |\n| `query_embedding` | `List[float]` | `None` | 预计算的查询向量 |\n| `top_k` | `int` | `10` | 返回结果数量上限 |\n| `time_window` | `Tuple[float, float]` | `None` | 时间窗口过滤 `(start_unix, end_unix)` |\n| `memory_type` | `str` | `None` | 按记忆类型过滤 |\n| `include_consolidated` | `bool` | `False` | 是否包含已整合的记忆 |\n| `expand_entities` | `bool` | `True` | 是否展开实体节点 |\n| `skip_reinforce` | `bool` | `False` | 是否跳过记忆强化 |\n| `namespace` | `str` | `None` | 命名空间过滤 |\n| `domain` | `str` | `None` | 领域标签过滤 |\n| `source` | `str` | `None` | 来源过滤 |\n\n### 返回结构\n\n```python\n{\n \"results\": [\n {\n \"rid\": \"M01H2K3...\",\n \"text\": \"Alice is the engineering lead\",\n \"score\": 0.92,\n \"memory_type\": \"semantic\",\n \"importance\": 0.8,\n \"timestamp\": 1234567890.0,\n \"metadata\": {...}\n },\n ...\n ],\n \"confidence\": 0.87,\n \"certainty_reasons\": [\"entity_overlap\", \"recency\"],\n \"retrieval_summary\": {\n \"top_similarity\": 0.92,\n \"score_spread\": 0.31,\n \"sources_used\": [\"episodic\", \"semantic\"],\n \"candidate_count\": 150\n },\n \"hints\": [...]\n}\n```\n\n### 多维度评分机制\n\n检索结果通过多维度加权评分计算相关性：\n\n```mermaid\ngraph LR\n A[查询向量] --> B[语义相似度]\n A --> C[时间衰减]\n A --> D[重要性权重]\n A --> E[实体重叠度]\n \n B --> F[综合评分]\n C --> F\n D --> F\n E --> F\n \n F --> G[重排序]\n G --> H[Top-K 结果]\n```\n\n评分维度说明：\n\n| 维度 | 权重范围 | 说明 |\n|------|----------|------|\n| `recency` | 0.0-1.0 | 最近访问的记忆得分更高 |\n| `frequency` | 0.0-1.0 | 访问频率影响权重 |\n| `entity_overlap` | 0.0-1.0 | 与查询实体重叠程度 |\n| `valence_match` | 0.0-1.0 | 情感极性与上下文匹配度 |\n| `importance` | 0.0-1.0 | 记录时的重要性评分 |\n| `similarity` | 0.0-1.0 | 向量余弦相似度 |\n\n### 检索流程详解\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant API as Python API\n participant Core as 核心引擎\n participant Embed as 嵌入模块\n participant DB as SQLite\n participant Score as 评分引擎\n\n User->>API: recall(query, top_k)\n API->>Core: recall(...)\n alt 无预计算向量\n Core->>Embed: embed_text(query)\n Embed-->>Core: query_vector\n end\n Core->>DB: SELECT candidates\n DB-->>Core: candidate_set\n Core->>Score: score(query_vector, candidates)\n Score-->>Core: ranked_results\n Core->>Core: apply_filters\n Core-->>API: RecallResponse\n API-->>User: results\n```\n\n---\n\n## 查询构建器模式\n\n核心模块提供了流畅的查询构建器接口：\n\n```python\nfrom yantrikdb_core import RecallQuery\n\nquery = (RecallQuery::new(embedding)\n .top_k(10)\n .memory_type(\"episodic\")\n .namespace(\"work\")\n .time_window(start_time, end_time)\n .include_consolidated(false)\n .domain(\"engineering\"))\n```\n\n---\n\n## 记忆强化机制\n\n检索操作默认会触发记忆强化（reinforcement），增强被召回记忆的持久性：\n\n- 增加访问计数 `access_count`\n- 更新最后访问时间 `last_access`\n- 动态调整半衰期（频繁访问的记忆衰减更慢）\n\n如需跳过强化，使用 `skip_reinforce=True` 参数。\n\n---\n\n## 命名空间隔离\n\n通过 `namespace` 参数实现多用户或多场景的数据隔离：\n\n```python\n# 用户A的记忆\ndb.record(\"Project deadline March 30\", namespace=\"user_a\")\ndb.record(\"Prefers email notifications\", namespace=\"user_a\")\n\n# 用户B的记忆\ndb.record(\"Likes video calls\", namespace=\"user_b\")\n\n# 检索时指定命名空间\nresults = db.recall(\"deadline?\", namespace=\"user_a\")\n```\n\n---\n\n## 实用示例\n\n### 基本记录与检索\n\n```python\nimport yantrikdb\n\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录信息\ndb.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\ndb.record(\"Project deadline is March 30\", importance=0.9, domain=\"work\")\ndb.record(\"User prefers dark mode\", importance=0.6, domain=\"preference\")\n\n# 检索相关记忆\nresults = db.recall(\"who leads the team?\", top_k=3)\n# → [{\"text\": \"Alice is the engineering lead\", \"score\": 1.0}, ...]\n\ndb.close()\n```\n\n### 高级过滤检索\n\n```python\nimport time\n\n# 时间窗口过滤：最近7天的记忆\nnow = time.time()\nweek_ago = now - 7 * 86400\n\nresults = db.recall(\n query=\"meeting notes\",\n top_k=5,\n time_window=(week_ago, now),\n memory_type=\"episodic\",\n domain=\"work\",\n include_consolidated=False\n)\n```\n\n---\n\n## 相关配置\n\n### 内置嵌入器\n\nYantrikDB 自带默认嵌入模型 (`potion-base-2M`，64维)，无需额外依赖：\n\n```python\n# 使用默认嵌入器（开箱即用）\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 升级为更高质量嵌入（首次调用时下载）\ndb = yantrikdb.YantrikDB(\"memory.db\", embedder=\"bge-base\")\n```\n\n### 置信度阈值\n\n检索结果的置信度由 `certainty_reasons` 和多维度评分综合计算得出，可用于过滤低质量结果：\n\n```python\nresults = db.recall(\"project status?\", top_k=10)\nhigh_confidence = [r for r in results[\"results\"] if r[\"score\"] > 0.7]\n```\n\n---\n\n## 参考链接\n\n- API 文档：`src/yantrikdb/api.py`\n- 核心实现：`crates/yantrikdb-core/src/engine/`\n- 评分系统：`crates/yantrikdb-core/src/base/scoring.rs`\n\n---\n\n\n\n## 知识图谱操作\n\n### 相关页面\n\n相关主题：[记录与检索操作](#page-record-recall), [五大索引架构](#page-five-indexes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/engine/graph_ops.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/graph_ops.rs)\n- [crates/yantrikdb-core/src/engine/graph_state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/graph_state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n \n\n# 知识图谱操作\n\n知识图谱操作是 YantrikDB 认知引擎的核心子系统，负责管理和维护实体、概念及其相互关系的有组织表示。与传统的向量检索不同，知识图谱操作提供了语义关联建模、激活传播推理和结构化推理能力，使系统能够在记忆网络中发现深层关联模式。\n\n## 架构概览\n\nYantrikDB 的知识图谱采用混合架构，结合了图结构存储与认知属性系统。每个节点携带多维度属性（置信度、激活值、显著性等），边携带类型化的语义关系和激活转移因子。\n\n```mermaid\ngraph TD\n subgraph 知识图谱层\n NK[节点Kind枚举]\n EK[边Kind枚举]\n CA[认知属性]\n PV[ Provenance 可追溯性]\n end\n \n subgraph 操作引擎\n GO[graph_ops 操作]\n GS[graph_state 状态管理]\n QR[query_dsl 查询]\n end\n \n subgraph 认知推理\n SP[surfacing 表面化]\n NT[narrative 叙事弧]\n end\n \n NK --> GO\n EK --> GO\n CA --> GO\n GO --> GS\n GS --> QR\n QR --> SP\n SP --> NT\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()\n\n## 节点类型系统\n\n知识图谱中的节点（Node）代表认知世界中的各种实体或概念。系统定义了14种节点类型，每种类型具有不同的持久化策略和默认认知属性。\n\n### 节点类型枚举\n\n| 类型标识 | 说明 | 持久化 | 典型用途 |\n|---------|------|--------|---------|\n| `entity` | 实体/对象 | 是 | 人、地点、物品 |\n| `episode` | 事件片段 | 是 | 经验记录 |\n| `belief` | 信念 | 是 | 存储的知识 |\n| `goal` | 目标 | 是 | 长期意图 |\n| `task` | 任务 | 是 | 具体行动项 |\n| `intent_hypothesis` | 意图假设 | **否** | 瞬时推理 |\n| `routine` | 行为模式 | 是 | 周期性习惯 |\n| `need` | 需求 | 是 | 动机驱动 |\n| `opportunity` | 机会 | 是 | 时间窗口性行动 |\n| `risk` | 风险 | 是 | 潜在问题 |\n| `constraint` | 约束 | 是 | 限制条件 |\n| `preference` | 偏好 | 是 | 用户选择倾向 |\n| `conversation_thread` | 对话线程 | **否** | 瞬时会话 |\n| `action_schema` | 行动模式 | 是 | 技能/流程模板 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:80-115]()\n\n### 节点类型方法\n\n节点类型提供了字符串序列化与反序列化支持：\n\n```rust\npub fn as_str(self) -> &'static str {\n match self {\n Self::Entity => \"entity\",\n Self::Episode => \"episode\",\n // ... 其他类型\n }\n}\n\npub fn from_str(s: &str) -> Option {\n match s {\n \"entity\" => Some(Self::Entity),\n // ...\n _ => None,\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:95-125]()\n\n### 节点持久化策略\n\n`is_persistent()` 方法决定了节点类型是否写入 SQLite 存储：\n\n- **持久化类型**：entity, episode, belief, goal, task, routine, need, opportunity, risk, constraint, preference, action_schema\n- **瞬时类型**：intent_hypothesis, conversation_thread（仅存在于工作集）\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:130-140]()\n\n## 边类型系统\n\n边（Edge）表示节点之间的语义关系，是激活传播和推理的基础。系统定义了17种边类型，具有不同的激活转移因子。\n\n### 边类型分类\n\n| 边类型 | 转移因子 | 说明 | 语义方向 |\n|--------|---------|------|---------|\n| `supports` | 0.7 | 支持关系 | 正向激活 |\n| `contradicts` | -0.5 | 矛盾关系 | 抑制 |\n| `causes` | 0.8 | 因果关系 | 强正向激活 |\n| `predicts` | 0.4 | 预测关系 | 中等正向 |\n| `prevents` | -0.6 | 预防关系 | 强抑制 |\n| `advances_goal` | 0.6 | 推进目标 | 正向激活 |\n| `blocks_goal` | -0.5 | 阻碍目标 | 抑制 |\n| `subtask_of` | 0.4 | 子任务归属 | 结构化 |\n| `requires` | 0.5 | 依赖关系 | 正向激活 |\n| `associated_with` | 0.3 | 关联关系 | 弱正向 |\n| `instance_of` | 0.3 | 实例关系 | 分类传播 |\n| `part_of` | 0.3 | 组成部分 | 结构传播 |\n| `similar_to` | 0.3 | 相似关系 | 类比传播 |\n| `precedes_temporally` | 0.2 | 时间先后 | 弱正向 |\n| `triggers` | 0.7 | 触发关系 | 事件激活 |\n| `prefers` | 0.3 | 偏好关系 | 倾向传播 |\n| `avoids` | -0.3 | 回避关系 | 弱抑制 |\n| `constrains` | -0.4 | 约束关系 | 限制传播 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n### 激活转移机制\n\n边的 `activation_transfer()` 方法定义了激活值如何从源节点流向目标节点：\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n Self::Supports => 0.7,\n Self::Causes => 0.8,\n Self::AdvancesGoal => 0.6,\n // ...\n }\n}\n```\n\n负值表示抑制关系，激活值会从目标节点中减去转移量。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:240-280]()\n\n## 认知属性系统\n\n每个知识图谱节点携带统一的认知属性集，包含11个维度，这些属性共同决定了节点在推理过程中的行为。\n\n### 属性维度\n\n| 属性名 | 范围 | 说明 | 默认值来源 |\n|--------|------|------|-----------|\n| `confidence` | [0.0, 1.0] | 置信度 | 类型相关 |\n| `activation` | [0.0, 1.0] | 当前激活水平 | 0.0 |\n| `salience` | [0.0, 1.0] | 显著性权重 | 类型相关 |\n| `persistence` | [0.0, 1.0] | 持久化倾向 | 类型相关 |\n| `valence` | [-1.0, 1.0] | 情感效价 | 0.0 |\n| `urgency` | [0.0, 1.0] | 紧急程度 | 0.0 |\n| `novelty` | [0.0, 1.0] | 新颖性 | 1.0 |\n| `last_updated_ms` | Unix ms | 最后更新时间 | 当前时间 |\n| `volatility` | [0.0, 1.0] | 波动率 | 0.1 |\n| `provenance` | Provenance枚举 | 信息来源 | Observed |\n| `evidence_count` | 正整数 | 证据数量 | 1 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:280-350]()\n\n### 节点类型默认属性\n\n不同节点类型具有预设的认知属性基线：\n\n| 节点类型 | 置信度 | 显著性 | 持久化 |\n|---------|--------|--------|--------|\n| Entity | 0.90 | 0.80 | 0.80 |\n| Episode | 0.80 | 0.60 | 0.70 |\n| Belief | 0.70 | 0.70 | 0.75 |\n| Goal | 0.85 | 0.90 | 0.85 |\n| Task | 0.90 | 0.70 | 0.60 |\n| Need | 0.60 | 0.70 | 0.40 |\n| Opportunity | 0.40 | 0.60 | 0.20 |\n| Risk | 0.40 | 0.70 | 0.60 |\n| Constraint | 0.90 | 0.80 | 0.95 |\n| Preference | 0.60 | 0.50 | 0.85 |\n| ConversationThread | 0.90 | 0.80 | 0.10 |\n| ActionSchema | 0.70 | 0.40 | 0.90 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:350-400]()\n\n## 信息溯源系统\n\n`Provenance` 枚举定义了知识来源的可信度等级，用于信念修正时的加权计算。\n\n### 来源类型与可靠度\n\n| 来源类型 | 可靠度 | 说明 |\n|---------|--------|------|\n| `told` | 0.95 | 用户显式声明，最信任 |\n| `observed` | 0.90 | 直接观察行为 |\n| `experimented` | 0.85 | 受控实验确认 |\n| `consolidated` | 0.80 | 多源合并 |\n| `extracted` | 0.75 | 外部文档提取，可能过时 |\n| `inferred` | 0.60 | 模式推理，中等信任 |\n| `system_default` | 0.50 | 默认值，最弱 |\n\n```rust\npub fn reliability_prior(self) -> f64 {\n match self {\n Self::Told => 0.95,\n Self::Observed => 0.90,\n Self::Experimented => 0.85,\n Self::Consolidated => 0.80,\n Self::Extracted => 0.75,\n Self::Inferred => 0.60,\n Self::SystemDefault => 0.50,\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:400-450]()\n\n## 任务与目标系统\n\n### 任务状态机\n\n`TaskStatus` 定义了任务的生命周期状态：\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建\n Pending --> InProgress: 开始\n InProgress --> Completed: 完成\n InProgress --> Blocked: 阻塞\n Blocked --> InProgress: 解除阻塞\n InProgress --> Cancelled: 取消\n Pending --> Cancelled: 取消\n Completed --> [*]\n Cancelled --> [*]\n```\n\n| 状态 | 字符串标识 | 说明 |\n|------|-----------|------|\n| Pending | `pending` | 等待执行 |\n| InProgress | `in_progress` | 执行中 |\n| Completed | `completed` | 已完成 |\n| Cancelled | `cancelled` | 已取消 |\n| Blocked | `blocked` | 被阻塞 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:480-520]()\n\n### 优先级层级\n\n`Priority` 枚举定义任务的紧急程度：\n\n| 优先级 | 紧急度值 | 说明 |\n|-------|---------|------|\n| Low | 0.25 | 低优先级 |\n| Medium | 0.50 | 中优先级 |\n| High | 0.75 | 高优先级 |\n| Critical | 1.00 | 紧急/关键 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:520-550]()\n\n## 操作类型\n\n### 行动类型与成本\n\n`ActionKind` 定义了系统可能执行的操作类型及其基线成本：\n\n| 操作类型 | 字符串标识 | 基线成本 | 说明 |\n|---------|-----------|---------|------|\n| Abstain | `abstain` | 0.00 | 不行动 |\n| Inform | `inform` | 0.05 | 通知用户 |\n| Organize | `organize` | 0.10 | 组织信息 |\n| Suggest | `suggest` | 0.15 | 建议行动 |\n| Communicate | `communicate` | 0.20 | 主动沟通 |\n| Schedule | `schedule` | 0.25 | 安排日程 |\n| Warn | `warn` | 0.30 | 警告用户 |\n| Execute | `execute` | 0.35 | 执行操作 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:550-600]()\n\n## 叙事弧系统\n\n知识图谱支持叙事结构建模，用于跟踪用户生活中的长期主题和故事线。\n\n### 叙事弧状态\n\n| 状态 | 字符串标识 | 说明 |\n|------|-----------|------|\n| Emerging | `emerging` | 初检测，样本不足 |\n| Active | `active` | 活跃积累中 |\n| Paused | `paused` | 暂停，可能恢复 |\n| Resolved | `resolved` | 目标达成或自然结束 |\n| Abandoned | `abandoned` | 停止追踪 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:50-80]()\n\n### 章节类型\n\n叙事弧内的章节分为：\n\n| 类型 | 说明 |\n|------|------|\n| Setup | 初始背景设定 |\n| Rising | 构建张力或进展 |\n| Climax | 弧线峰值时刻 |\n| Falling | 峰值后收尾 |\n| Resolution | 最终结论 |\n| Interlude | 主线间的暂停或旁支 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:80-110]()\n\n## 查询与推理操作\n\n### Recall 操作参数\n\n`RecallOp` 定义了召回操作参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| top_k | usize | 返回结果数量 |\n| query | Option | 自然语言查询 |\n| domain | Option | 领域过滤 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:80-100]()\n\n### Think 循环操作优先级\n\n`ThinkConfig` 定义了认知循环中各操作的优先级：\n\n| 操作 | 优先级 | 说明 |\n|------|--------|------|\n| Attend | 10 | 注意力聚焦，始终执行 |\n| Recall | 9 | 上下文召回，关键 |\n| Believe | 8 | 证据整合 |\n| Compare | 7 | 行动选择 |\n| Constrain | 7 | 安全约束 |\n| Plan | 6 | 手段-目标推理 |\n| Project | 5 | 前向模拟 |\n| Anticipate | 4 | 主动预测 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性维护 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:100-130]()\n\n## 表面化与主动建议\n\n### 抑制原因\n\n`SuppressionReason` 枚举定义了建议被抑制的原因：\n\n| 抑制原因 | 字符串标识 |\n|---------|-----------|\n| LowReceptivity | `low_receptivity` |\n| ItemSuppressionRule | `item_suppression_rule` |\n| QuietHours | `quiet_hours` |\n| RateLimited | `rate_limited` |\n| AntiNag | `anti_nag` |\n| MaxSurfaces | `max_surfaces` |\n| TooSoon | `too_soon` |\n| NotificationModeBlock | `notification_mode_block` |\n\n资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:50-80]()\n\n## 冲突检测与解决\n\n### 冲突类型\n\n`ConflictType` 定义了记忆间的冲突类型：\n\n| 冲突类型 | 默认优先级 | 说明 |\n|---------|-----------|------|\n| IdentityFact | critical | 身份事实矛盾 |\n| Preference | high | 偏好矛盾 |\n| Temporal | high | 时间线矛盾 |\n| Consolidation | medium | 整合冲突 |\n| Minor | low | 次要冲突 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n## 使用场景\n\n### 实体关联查询\n\n当用户记录\"Alice 是工程主管\"后，系统创建实体节点，并可通过 `relate()` 建立与\"Engineering\"节点的\"leads\"关系边。\n\n### 目标驱动的任务分解\n\n目标节点通过 `subtask_of` 边连接到子任务节点，激活值从目标向下传播，自动提升相关子任务的显著性。\n\n### 偏好学习与冲突检测\n\n用户偏好通过 `Preference` 节点存储，当新记录与现有偏好矛盾时，系统检测到 `Preference` 类型的冲突并触发解决流程。\n\n### 机会与风险管理\n\n`Opportunity` 节点携带有效期和预期收益属性，`Risk` 节点携带严重程度，系统通过激活传播计算当前最需要关注的机会和风险。\n\n## 总结\n\nYantrikDB 的知识图谱操作模块提供了丰富的语义建模能力，通过14种节点类型、17种边类型和11维认知属性，构建了一个可解释、可追溯的认知表示系统。激活传播机制使系统能够基于图结构进行动态推理，表面化系统确保相关信息适时呈现，而叙事弧模块则支持长期主题的跟踪与理解。\n\n---\n\n\n\n## 认知循环与思考\n\n### 相关页面\n\n相关主题：[记录与检索操作](#page-record-recall), [冲突检测与解决](#page-conflict-detection), [主动触发系统](#page-triggers-proactive)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n- [crates/yantrikdb-core/src/cognition/narrative.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/narrative.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/engine/cognition.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/cognition.rs)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n \n\n# 认知循环与思考\n\n## 概述\n\n**认知循环与思考**（Cognitive Loop and Thinking）是 YantrikDB 中负责模拟人类认知过程的核心子系统。它通过一系列认知操作符（cognitive operators）驱动记忆激活、信念更新、推理规划和主动建议等高级认知功能。该系统基于\"工作集\"（working set）机制运行，将持久化的图结构数据转换为动态激活的认知空间，从而实现上下文感知和目标导向的智能行为。\n\n认知循环的核心目标是：\n\n- **上下文感知**：根据当前情境选择性地激活相关记忆节点\n- **信念维护**：整合新证据并解决认知冲突\n- **目标驱动**：通过规划和预测推进用户目标\n- **主动交互**：在适当时机向用户推送相关建议\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 系统架构\n\n### 核心组件\n\nYantrikDB 的认知系统由以下核心组件构成：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **CognitiveOperator** | 定义认知操作符枚举，封装认知原语 | query_dsl.rs |\n| **YantrikExecutor** | 执行认知操作符的核心引擎 | engine/cognition.rs |\n| **WorkingSet** | 工作集管理，维护激活状态的节点子集 | engine/cognition.rs |\n| **CognitiveAttrs** | 认知属性集，定义节点的动态特征 | state.rs |\n| **SurfaceEngine** | 主动建议生成与推送 | surfacing.rs |\n\n### 认知操作符体系\n\n认知操作符是认知循环的基本执行单元，按优先级从高到低排列：\n\n| 优先级 | 操作符 | 功能描述 | 源码位置 |\n|:------:|--------|----------|----------|\n| 10 | **Attend** | 注意力聚焦，选择性激活相关节点 | query_dsl.rs |\n| 9 | **Recall** | 记忆召回，从持久存储检索相关信息 | query_dsl.rs |\n| 8 | **Believe** | 信念整合，整合新证据更新信念 | query_dsl.rs |\n| 7 | **Compare** | 方案比较，评估候选行动的效用 | query_dsl.rs |\n| 7 | **Constrain** | 约束满足，应用安全与业务约束 | query_dsl.rs |\n| 6 | **Plan** | 计划生成，means-ends 规划 | query_dsl.rs |\n| 5 | **Project** | 前景预测，前向模拟结果 | query_dsl.rs |\n| 4 | **Anticipate** | 主动预判，预测未来需求 | query_dsl.rs |\n| 3 | **Assess** | 元认知评估，评估系统状态 | query_dsl.rs |\n| 2 | **CoherenceCheck** | 一致性检查，维护认知连贯性 | query_dsl.rs |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 认知节点类型\n\n### NodeKind 枚举\n\n系统定义了 15 种认知节点类型，每种类型具有不同的持久化策略和认知特性：\n\n```mermaid\ngraph TD\n A[NodeKind 节点类型] --> B[Entity 实体]\n A --> C[Episode 事件]\n A --> D[Belief 信念]\n A --> E[Goal 目标]\n A --> F[Task 任务]\n A --> G[IntentHypothesis 意图假设]\n A --> H[Routine 习惯]\n A --> I[Need 需求]\n A --> J[Opportunity 机会]\n A --> K[Risk 风险]\n A --> L[Constraint 约束]\n A --> M[Preference 偏好]\n A --> N[ConversationThread 对话线程]\n A --> O[ActionSchema 行动模式]\n \n G -.->|瞬态节点| P[不持久化到SQLite]\n N -.->|瞬态节点| P\n```\n\n### 节点类型特性表\n\n| 节点类型 | 持久化 | 默认置信度 | 激活率 | 显著性 | 典型用途 |\n|----------|:------:|:----------:|:------:|:------:|----------|\n| Entity | ✓ | 0.90 | 0.80 | 0.90 | 实体概念建模 |\n| Episode | ✓ | 0.70 | 0.60 | 0.50 | 事件记忆存储 |\n| Belief | ✓ | 0.65 | 0.70 | 0.70 | 信念状态管理 |\n| Goal | ✓ | 0.80 | 0.90 | 0.80 | 目标追踪 |\n| Task | ✓ | 0.85 | 0.70 | 0.70 | 任务执行管理 |\n| IntentHypothesis | ✗ | 0.60 | 0.70 | 0.50 | 意图识别（瞬态） |\n| Routine | ✓ | 0.75 | 0.60 | 0.40 | 习惯模式识别 |\n| Need | ✓ | 0.60 | 0.70 | 0.40 | 需求状态 |\n| Opportunity | ✓ | 0.40 | 0.60 | 0.20 | 机会识别 |\n| Risk | ✓ | 0.40 | 0.70 | 0.60 | 风险评估 |\n| Constraint | ✓ | 0.90 | 0.80 | 0.95 | 安全/业务约束 |\n| Preference | ✓ | 0.60 | 0.50 | 0.85 | 用户偏好 |\n| ConversationThread | ✗ | 0.90 | 0.80 | 0.10 | 对话上下文（瞬态） |\n| ActionSchema | ✓ | 0.70 | 0.40 | 0.90 | 行动模式库 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n---\n\n## 认知属性系统\n\n### CognitiveAttrs 结构\n\n每个认知节点携带一组动态属性，这些属性控制节点在认知循环中的行为：\n\n```rust\npub struct CognitiveAttrs {\n pub confidence: f64, // 置信度 [0.0, 1.0]\n pub activation: f64, // 激活水平 [0.0, 1.0]\n pub salience: f64, // 显著性 [0.0, 1.0]\n pub persistence: f64, // 持久性 [0.0, 1.0]\n pub valence: f64, // 情感效价 [-1.0, 1.0]\n pub urgency: f64, // 紧迫性 [0.0, 1.0]\n pub novelty: f64, // 新颖性 [0.0, 1.0]\n pub last_updated_ms: u64, // 上次更新时间戳\n pub volatility: f64, // 波动性 [0.0, 1.0]\n pub provenance: Provenance, // 信息来源\n pub evidence_count: u32, // 证据数量\n}\n```\n\n### 属性值范围\n\n| 属性 | 范围 | 含义 |\n|------|------|------|\n| confidence | [0.0, 1.0] | 节点内容的可信程度 |\n| activation | [0.0, 1.0] | 当前激活水平，影响检索优先级 |\n| salience | [0.0, 1.0] | 固有显著性，不随时间衰减 |\n| persistence | [0.0, 1.0] | 记忆持久化倾向 |\n| valence | [-1.0, 1.0] | 情感效价，负值为负面，正值为正面 |\n| urgency | [0.0, 1.0] | 时间敏感性 |\n| novelty | [0.0, 1.0] | 与已知信息的差异程度 |\n| volatility | [0.0, 1.0] | 值随时间的波动程度 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:250-280]()\n\n---\n\n## 边类型与激活传播\n\n### EdgeKind 枚举\n\n认知节点之间通过带类型的边连接，边的类型决定了激活传播的方式：\n\n| 边类型 | 激活转移因子 | 语义 |\n|--------|:------------:|------|\n| **Supports** | 0.7 | 支持关系 |\n| **Contradicts** | -0.6 | 矛盾关系 |\n| **Causes** | 0.8 | 因果关系 |\n| **Predicts** | 0.4 | 预测关系 |\n| **Prevents** | -0.7 | 阻止关系 |\n| **AdvancesGoal** | 0.6 | 推进目标 |\n| **BlocksGoal** | -0.5 | 阻碍目标 |\n| **SubtaskOf** | 0.4 | 子任务关系 |\n| **Requires** | 0.5 | 依赖关系 |\n| **AssociatedWith** | 0.3 | 关联关系 |\n| **InstanceOf** | 0.3 | 实例关系 |\n| **PartOf** | 0.3 | 部分关系 |\n| **SimilarTo** | 0.3 | 相似关系 |\n| **PrecedesTemporally** | 0.2 | 时间先后 |\n| **Triggers** | 0.7 | 触发关系 |\n| **Prefers** | 0.3 | 偏好关系 |\n| **Avoids** | -0.4 | 回避关系 |\n| **Constrains** | -0.5 | 约束关系 |\n\n### 激活传播机制\n\n激活传播基于**扩散激活模型**（Spreading Activation Model）：\n\n```mermaid\ngraph LR\n A[种子节点] -->|activate_and_spread| B[相邻节点]\n B -->|继续传播| C[二级相邻节点]\n C -->|衰减| D[三级相邻节点]\n \n A -->|激活+0.3| A\n B -->|因子×边类型| B\n C -->|因子×0.5| C\n D -->|因子×0.25| D\n```\n\n**关键参数**：\n\n- 初始激活增量：0.3\n- 传播衰减因子：由 `EdgeKind::activation_transfer()` 定义\n- 负值边表示抑制传播\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n---\n\n## 认知操作符详解\n\n### Attend（注意力聚焦）\n\n**功能**：选择性聚焦于特定节点并激活相关上下文。\n\n```rust\npub struct AttendOp {\n pub seeds: Vec, // 种子节点列表\n pub max_hops: u32, // 最大传播跳数\n pub decay: f64, // 衰减系数\n}\n```\n\n**执行流程**：\n\n1. 从种子节点开始\n2. 按 `max_hops` 限制进行激活传播\n3. 应用 `decay` 衰减系数\n4. 返回激活节点数量和 Top-N 激活节点\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:50-60]()\n\n### Recall（记忆召回）\n\n**功能**：从持久存储中检索与查询相关的记忆。\n\n```rust\npub struct RecallOp {\n pub top_k: usize, // 返回 top_k 结果\n pub query: Option, // 自然语言查询\n pub domain: Option, // 限定领域\n}\n```\n\n**召回参数**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| top_k | usize | 返回结果数量上限 |\n| query | Option | 自然语言描述的查询 |\n| embedding | Option> | 向量嵌入（可替代 query） |\n| memory_type | Option | 记忆类型过滤 |\n| namespace | Option | 命名空间过滤 |\n| time_window | Option<(f64, f64)> | 时间窗口过滤 |\n\n资料来源：[crates/yantrikdb-core/src/engine/cognition.rs:1-50]()\n\n### Believe（信念整合）\n\n**功能**：将新证据整合到信念系统中，解决认知冲突。\n\n```rust\npub struct BelieveOp {\n pub evidence: EvidenceInput,\n}\n\npub struct EvidenceInput {\n pub target: Option, // 目标信念节点\n pub observation: String, // 观察描述\n pub direction: f64, // 方向：positive=确认，negative=矛盾\n}\n```\n\n**证据可靠性优先级**：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|:----------:|------|\n| Told | 0.95 | 用户明确陈述 |\n| Observed | 0.90 | 直接观察行为 |\n| Experimented | 0.85 | 控制实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取 |\n| Inferred | 0.60 | 模式推断 |\n| SystemDefault | 0.50 | 系统默认值 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:220-240]()\n\n### Plan（计划生成）\n\n基于 means-ends 推理的目标分解，调用子任务生成和约束满足机制。\n\n### Project（前景预测）\n\n前向模拟行动结果，评估不同行动路径的预期收益。\n\n### Compare（方案比较）\n\n评估候选行动的效用，考虑收益、成本和风险。\n\n### Constrain（约束满足）\n\n应用安全和业务约束，确保行动符合用户设定的限制。\n\n### Anticipate（主动预判）\n\n基于模式和趋势预测未来需求和机会。\n\n### Assess（元认知评估）\n\n评估当前认知状态的质量和效率。\n\n### CoherenceCheck（一致性检查）\n\n检测和修复认知冲突，维护信念系统的连贯性。\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 行动系统\n\n### ActionKind 枚举\n\n定义了系统可执行的基本行动类型：\n\n| 行动类型 | 基础成本 | 说明 |\n|----------|:--------:|------|\n| Abstain | 0.00 | 无行动 |\n| Inform | 0.05 | 信息告知 |\n| Organize | 0.10 | 组织整理 |\n| Suggest | 0.15 | 主动建议 |\n| Communicate | 0.20 | 沟通交流 |\n| Schedule | 0.25 | 日程安排 |\n| Warn | 0.30 | 风险警告 |\n| Execute | 0.35 | 直接执行 |\n\n**基础成本**用于效用计算，较高成本意味着对用户更大的干扰。\n\n### TaskStatus 任务状态\n\n| 状态 | 字符串表示 | 说明 |\n|------|------------|------|\n| Pending | \"pending\" | 待处理 |\n| InProgress | \"in_progress\" | 进行中 |\n| Completed | \"completed\" | 已完成 |\n| Cancelled | \"cancelled\" | 已取消 |\n| Blocked | \"blocked\" | 被阻塞 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:80-120]()\n\n---\n\n## 优先级系统\n\n### Priority 枚举\n\n| 优先级 | 字符串 | 紧急度值 | 说明 |\n|--------|--------|:--------:|------|\n| Low | \"low\" | 0.25 | 低优先级 |\n| Medium | \"medium\" | 0.50 | 中优先级 |\n| High | \"high\" | 0.75 | 高优先级 |\n| Critical | \"critical\" | 1.00 | 紧急 |\n\n### 冲突类型与默认优先级\n\n| 冲突类型 | 默认优先级 | 说明 |\n|----------|------------|------|\n| IdentityFact | \"critical\" | 身份事实冲突 |\n| Preference | \"high\" | 偏好冲突 |\n| Temporal | \"high\" | 时间冲突 |\n| Consolidation | \"medium\" | 合并冲突 |\n| Minor | \"low\" | 轻微冲突 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n---\n\n## 叙事与故事弧系统\n\n### ArcStatus 生命周期状态\n\n| 状态 | 说明 |\n|------|------|\n| Emerging | 新检测到，证据不足 |\n| Active | 活跃积累事件中 |\n| Paused | 暂停，可能恢复 |\n| Resolved | 目标达成或故事结束 |\n| Abandoned | 用户或系统决定停止追踪 |\n\n### ChapterType 章节类型\n\n| 类型 | 说明 |\n|------|------|\n| Setup | 初始上下文设置 |\n| Rising | 紧张感建立或进展中 |\n| Climax | 弧的高峰时刻 |\n| Falling | 高峰后回落 |\n| Resolution | 最终结论 |\n| Interlude | 主线间的插曲 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:1-50]()\n\n---\n\n## 用户接受度系统\n\n### ActivityState 用户活动状态\n\n系统通过感知用户当前活动状态来调整交互策略：\n\n| 状态 | 中断成本 | 接收度 | 适用场景 |\n|------|:--------:|:------:|----------|\n| Idle | 0.15 | 0.85 | 空闲状态 |\n| JustReturned | 0.25 | 0.75 | 刚返回 |\n| Browsing | 0.35 | 0.65 | 浏览中 |\n| Communicating | 0.45 | 0.55 | 沟通中 |\n| TaskSwitching | 0.65 | 0.45 | 任务切换中 |\n| FocusedWork | 0.85 | 0.25 | 专注工作 |\n| DeepFocus | 0.95 | 0.05 | 深度专注 |\n\n### NotificationMode 通知模式\n\n| 模式 | 说明 |\n|------|------|\n| All | 允许所有通知 |\n| ImportantOnly | 仅重要通知 |\n| DoNotDisturb | 完全静音 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/receptivity.rs:1-50]()\n\n---\n\n## 主动建议系统\n\n### SurfaceMode 展示模式\n\n| 模式 | 说明 |\n|------|------|\n| Ambient | 环境感知，轻量提示 |\n| Prominent | 醒目展示，需要注意 |\n| Interrupt | 打断式，需立即响应 |\n\n### SurfaceReason 展示原因\n\n| 原因 | 说明 |\n|------|------|\n| Opportunity | 识别到新机会 |\n| DeadlineApproaching | 截止日期临近 |\n| GoalProgress | 目标进展更新 |\n| PatternDetected | 检测到用户模式 |\n| ConflictDetected | 检测到冲突 |\n| SystemInitiated | 系统主动发起 |\n\n### 抑制规则\n\n| 规则 | 说明 |\n|------|------|\n| LowReceptivity | 用户接受度低 |\n| ItemSuppressionRule | 特定项目被抑制 |\n| QuietHours | 安静时段 |\n| RateLimited | 频率限制 |\n| AntiNag | 防打扰机制 |\n| MaxSurfaces | 达到最大展示次数 |\n| TooSoon | 展示间隔太短 |\n| NotificationModeBlock | 通知模式阻止 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:1-80]()\n\n---\n\n## 触发器系统\n\n### TriggerType 触发器类型\n\n| 触发类型 | 默认冷却时间 | 默认过期时间 |\n|----------|:------------:|:------------:|\n| DecayReview | 3天 | 7天 |\n| ConsolidationReady | 1天 | 3天 |\n| ConflictEscalation | 2天 | 14天 |\n| TemporalDrift | 14天 | 7天 |\n| Redundancy | 1天 | 7天 |\n| RelationshipInsight | 7天 | 7天 |\n| ValenceTrend | 7天 | 7天 |\n| EntityAnomaly | 7天 | 7天 |\n| PatternDiscovered | 7天 | 7天 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:100-130]()\n\n---\n\n## ThinkConfig 配置\n\n```rust\npub struct ThinkConfig {\n pub importance_threshold: f64, // 重要性阈值\n pub decay_threshold: f64, // 衰减阈值\n pub max_triggers: usize, // 最大触发数\n}\n```\n\n**配置参数说明**：\n\n| 参数 | 说明 | 典型值 |\n|------|------|--------|\n| importance_threshold | 节点被视为重要的最低阈值 | 0.5-0.7 |\n| decay_threshold | 触发衰减审查的阈值 | 0.2-0.4 |\n| max_triggers | 单次思考循环的最大触发数 | 10-20 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:140-150]()\n\n---\n\n## 执行流程\n\n### 认知循环执行管道\n\n```mermaid\ngraph TD\n A[ThinkConfig 配置] --> B[按优先级排序操作符]\n B --> C{操作符队列}\n \n C -->|Attend| D[激活种子节点]\n D --> E[扩散激活传播]\n E --> F[更新 WorkingSet]\n \n C -->|Recall| G[检索相关记忆]\n G --> H[构建候选集合]\n \n C -->|Believe| I[整合新证据]\n I --> J{检测冲突?}\n J -->|是| K[触发冲突解决]\n J -->|否| L[更新信念置信度]\n \n C -->|Plan| M[目标分解]\n M --> N[生成子任务图]\n \n C -->|Project| O[前向模拟]\n O --> P[计算预期收益]\n \n C -->|Compare| Q[评估候选行动]\n Q --> R[计算效用函数]\n \n C -->|Constrain| S[应用约束]\n S --> T[过滤非法行动]\n \n C -->|Anticipate| U[预测未来]\n U --> V[生成预判结果]\n \n C -->|Assess| W[元认知评估]\n W --> X[输出状态报告]\n \n C -->|CoherenceCheck| Y[一致性检查]\n Y --> Z{发现冲突?}\n Z -->|是| AA[标记冲突节点]\n Z -->|否| AB[结束检查]\n \n F --> AC[合并结果]\n H --> AC\n L --> AC\n N --> AC\n P --> AC\n R --> AC\n T --> AC\n V --> AC\n X --> AC\n AB --> AC\n \n AC --> AD[SurfaceEngine]\n AD --> AE[ProactiveSuggestion]\n```\n\n### 核心执行器实现\n\n```rust\nimpl<'a> YantrikExecutor<'a> {\n fn execute_attend(&self, op: &AttendOp) -> StepOutput {\n match self.db.hydrate_working_set(self.attention_config.clone()) {\n Ok(mut ws) => {\n let mut activated = 0;\n let mut top = Vec::new();\n \n // 激活种子节点\n for &seed in &op.seeds {\n if let Some(node) = ws.get_mut(seed) {\n let new_activation = (node.attrs.activation + 0.3).min(1.0);\n node.attrs.activation = new_activation;\n top.push((seed, new_activation));\n activated += 1;\n }\n }\n \n // 扩散激活\n for &seed in &op.seeds {\n activated += ws.activate_and_spread(seed, 0.3);\n }\n \n StepOutput::Attend {\n nodes_activated: activated,\n top_activated: top,\n }\n }\n Err(e) => StepOutput::Error {\n message: format!(\"Attend failed: {}\", e),\n },\n }\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/cognition.rs:50-100]()\n\n---\n\n## Python 接口\n\n### Memory.query() 方法\n\nPython SDK 提供了认知查询的便捷接口：\n\n```python\ndef query(\n query: Optional[str] = None,\n embedding: Optional[List[float]] = None,\n top_k: int = 10,\n memory_type: Optional[str] = None,\n namespace: Optional[str] = None,\n time_window: Optional[Tuple[float, float]] = None,\n expand_entities: bool = False,\n include_consolidated: bool = False,\n skip_reinforce: bool = False,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n) -> List[PyObject]\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | Optional[str] | None | 自然语言查询 |\n| embedding | Optional[List[float]] | None | 向量嵌入 |\n| top_k | int | 10 | 返回结果数 |\n| memory_type | Optional[str] | None | 记忆类型过滤 |\n| namespace | Optional[str] | None | 命名空间 |\n| time_window | Optional[Tuple[float, float]] | None | 时间窗口 (start, end) |\n| expand_entities | bool | False | 展开关联实体 |\n| include_consolidated | bool | False | 包含已合并记忆 |\n| skip_reinforce | bool | False | 跳过强化学习 |\n| domain | Optional[str] | None | 领域过滤 |\n| source | Optional[str] | None | 来源过滤 |\n\n资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-100]()\n\n---\n\n## 工作集管理\n\n### WorkingSet 工作机制\n\n工作集是认知循环的核心数据结构，它：\n\n1. **从 SQLite 加载活跃节点**：根据 `AttentionConfig` 过滤高激活/高显著性节点\n2. **维护激活状态**：所有计算在工作集内完成，不直接修改持久存储\n3. **支持激活扩散**：基于边类型进行激活传播\n4. **惰性同步**：修改通过批处理同步回 SQLite\n\n### Hydration 流程\n\n```mermaid\ngraph LR\n A[SQLite 持久存储] -->|SELECT| B[候选节点集]\n B -->|按阈值过滤| C[WorkingSet]\n C -->|激活扩散| D[激活图]\n D -->|惰性同步| A\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/lifecycle.rs:1-50]()\n\n---\n\n## 总结\n\nYantrikDB 的认知循环与思考系统是一个复杂但层次分明的认知架构，其核心特点包括：\n\n1. **操作符驱动的管道**：通过优先级排序的认知操作符序列实现结构化推理\n2. **工作集抽象**：平衡了计算效率和持久化一致性\n3. **激活传播模型**：基于边类型的扩散激活实现了上下文敏感的检索\n4. **多维属性系统**：通过置信度、显著性、紧迫性等属性控制节点行为\n5. **主动建议引擎**：结合用户接受度和场景感知生成适时建议\n6. **叙事支持**：通过故事弧和章节机制维护长时程上下文\n\n该系统设计遵循认知科学原理，同时针对实际应用场景进行了工程优化，为构建智能个人助理提供了坚实的认知基础。\n\n---\n\n\n\n## 冲突检测与解决\n\n### 相关页面\n\n相关主题：[认知循环与思考](#page-cognitive-loop), [主动触发系统](#page-triggers-proactive)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/contradiction.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/contradiction.rs)\n- [crates/yantrikdb-core/src/engine/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/conflict.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n \n\n# 冲突检测与解决\n\n## 概述\n\n冲突检测与解决（Conflict Detection and Resolution）是 yantrikdb 认知引擎的核心子系统之一，负责识别、管理和解决记忆网络中的矛盾与不一致。该系统涵盖三个层次：\n\n1. **认知层冲突** (`cognition/contradiction.rs`) - 处理信念、意图、偏好之间的逻辑矛盾\n2. **引擎层冲突** (`engine/conflict.rs`) - 管理记忆存储和检索过程中的冲突\n3. **分布式冲突** (`distributed/conflict.rs`) - 处理多节点复制环境下的冲突\n\n系统的设计目标是在保持记忆完整性的同时，智能地检测、评估和解决各种类型的冲突，确保认知代理基于一致的信息进行决策。\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:1-50]()\n\n## 冲突类型体系\n\nyantrikdb 定义了完整的冲突类型层次结构，每种类型都有对应的优先级和处理策略。\n\n### 冲突类型枚举\n\n| 类型 | 标识符 | 默认优先级 | 说明 |\n|------|--------|-----------|------|\n| 身份事实冲突 | `identity_fact` | critical（关键） | 关于实体核心属性的根本性矛盾 |\n| 偏好冲突 | `preference` | high（高） | 用户偏好陈述之间的不一致 |\n| 时间冲突 | `temporal` | high（高） | 时间线或时序信息的矛盾 |\n| 整合冲突 | `consolidation` | medium（中） | 记忆整合过程中的冲突 |\n| 次要冲突 | `minor` | low（低） | 其他轻微的不一致 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:1-30]()\n\n### 冲突数据模型\n\n```rust\npub struct Conflict {\n pub conflict_id: String,\n pub conflict_type: String,\n pub priority: String,\n pub status: String,\n pub memory_a: String,\n pub memory_b: String,\n pub entity: Option,\n pub rel_type: Option,\n pub detected_at: f64,\n pub detected_by: String,\n pub detection_reason: String,\n pub resolved_at: Option,\n pub resolved_by: Option,\n pub strategy: Option,\n pub winner_rid: Option,\n pub resolution_note: Option,\n}\n```\n\n该模型记录了冲突的完整生命周期：\n\n- **检测阶段**：记录冲突ID、类型、优先级、涉及的双方记忆（`memory_a`/`memory_b`）、检测时间和检测原因\n- **解决阶段**：记录解决策略、获胜方（`winner_rid`）、解决者和解决时间\n- **元数据**：关联的实体（`entity`）和关系类型（`rel_type`）用于上下文追踪\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n## 认知层冲突检测\n\n### 矛盾检测器\n\n认知层的矛盾检测器负责识别信念、意图和偏好之间的逻辑矛盾。\n\n```mermaid\ngraph TD\n A[新证据输入] --> B{证据分析}\n B --> C[与现有信念比较]\n C --> D{存在矛盾?}\n D -->|是| E[创建矛盾节点]\n D -->|否| F[更新信念置信度]\n E --> G[冲突分类]\n G --> H[优先级评估]\n H --> I[进入待解决队列]\n```\n\n矛盾检测器通过以下方式工作：\n\n1. **证据收集**：接收来自观察、推断或外部来源的新证据\n2. **相似性检查**：与现有信念进行特征向量比较\n3. **矛盾识别**：使用激活传播算法检测负向关联边\n4. **分类与优先级**：根据冲突类型分配优先级\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n### 关系类型与激活传播\n\n冲突检测与边类型紧密相关。以下边类型可能指示潜在的矛盾：\n\n| 边类型 | 激活转移值 | 冲突关联 |\n|--------|-----------|----------|\n| `contradicts` | -0.8 | 直接矛盾 |\n| `contradicts` | -0.8 | 核心否定关系 |\n| `supports` | 0.7 | 相互支持 |\n| `predicts` | 0.4 | 预测关系 |\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n Self::Contradicts => -0.8, // 强负向转移 = 冲突指示\n Self::Supports => 0.7,\n Self::Predicts => 0.4,\n // ...\n }\n}\n```\n\n负向激活转移值（如 -0.8）表示该边会抑制目标节点，这正是矛盾检测的核心机制。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()\n\n## 引擎层冲突处理\n\n### 冲突解决策略\n\n引擎层的冲突解决器实现了多种策略来处理存储和检索层面的冲突：\n\n| 策略 | 适用场景 | 说明 |\n|------|---------|------|\n| `timestamp_wins` | 时间敏感数据 | 以最新时间戳为准 |\n| `priority_wins` | 重要性数据 | 以优先级高者为准 |\n| `merge` | 可整合数据 | 合并而非覆盖 |\n| `user_decides` | 需人工判断 | 保留供用户选择 |\n\n```rust\npub struct ConflictResolutionResult {\n pub conflict_id: String,\n pub resolution_strategy: String,\n pub winner_rid: String,\n pub loser_rid: String,\n pub resolved_at: f64,\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:80-100]()\n\n### 认知属性与冲突敏感性\n\n不同的认知节点类型对冲突的敏感度不同：\n\n| 节点类型 | 置信度基线 | 显著性基线 | 持久性基线 |\n|----------|-----------|-----------|-----------|\n| Constraint | 0.90 | 0.80 | 0.95 |\n| Preference | 0.60 | 0.50 | 0.85 |\n| Belief | 0.75 | 0.60 | 0.70 |\n| IntentHypothesis | 0.40 | 0.50 | 0.10 |\n\n约束节点（Constraint）具有最高的置信度和持久性，表明它们最难被冲突推翻；而意图假设（IntentHypothesis）则最容易被新证据更新。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:100-150]()\n\n## 分布式冲突处理\n\n### 多节点复制冲突\n\n在分布式环境中，冲突检测与解决需要考虑网络分区和并发写入：\n\n```mermaid\ngraph LR\n A[节点 A 写入] --> C{冲突检测}\n B[节点 B 写入] --> C\n C --> D[生成冲突记录]\n D --> E[广播到集群]\n E --> F[一致性解决]\n F --> G[同步状态]\n```\n\n### HLC 时钟冲突\n\nyantrikdb 使用混合逻辑时钟（HLC）处理分布式时序：\n\n```rust\npub struct OpLogEntry {\n pub op_id: String,\n pub op_type: String,\n pub timestamp: f64,\n pub target_rid: String,\n pub payload: String,\n pub actor_id: String,\n pub hlc: Vec,\n pub embedding_hash: String,\n pub origin_actor: String,\n}\n```\n\n`extract_ops_since` 函数用于从指定时间点提取后续操作，实现增量同步和冲突检测：\n\n```rust\nfn extract_ops_since(\n &self,\n since_hlc: Option>,\n since_op_id: Option<&str>,\n exclude_actor: Option<&str>,\n limit: usize,\n) -> PyResult>\n```\n\n资料来源：[crates/yantrikdb-python/src/py_engine/sync.rs:1-50]()\n\n## 工作流程\n\n### 完整冲突处理流程\n\n```mermaid\ngraph TD\n A[冲突检测] --> B[冲突分类]\n B --> C{优先级评估}\n C -->|Critical| D[立即处理]\n C -->|High| E[队列优先处理]\n C -->|Medium| F[批量处理]\n C -->|Low| G[延迟处理]\n D --> H[应用解决策略]\n E --> H\n F --> H\n G --> H\n H --> I[更新记忆状态]\n I --> J[记录解决历史]\n J --> K[传播激活更新]\n```\n\n### 一致性检查\n\n认知引擎定期执行一致性检查：\n\n```rust\nCognitiveOperator::CoherenceCheck => self.execute_coherence()\n```\n\n一致性检查评估：\n\n- 激活分数（Coherence Score）\n- 冲突数量\n- 陈旧节点数量\n- 系统整体健康状态\n\n资料来源：[crates/yantrikdb-core/src/engine/query_dsl.rs:1-30]()\n\n## 配置参数\n\n### 冲突处理配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `importance_threshold` | f64 | - | 重要性阈值 |\n| `decay_threshold` | f64 | - | 衰减阈值 |\n| `max_triggers` | usize | - | 最大触发器数 |\n\n### 触发器冷却与过期\n\n| 触发类型 | 冷却时间（秒） | 过期时间（秒） |\n|----------|---------------|---------------|\n| DecayReview | 3天 | 7天 |\n| ConsolidationReady | 1天 | 3天 |\n| ConflictEscalation | 2天 | 14天 |\n| Redundancy | 1天 | 7天 |\n| PatternDiscovered | 7天 | 7天 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:100-150]()\n\n## 可靠性先验\n\n冲突检测的可靠性与信息来源相关：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|-----------|------|\n| Told | 0.95 | 用户明确陈述 - 最高信任 |\n| Observed | 0.90 | 直接观察行为 |\n| Experimented | 0.85 | 通过实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取 |\n| Inferred | 0.60 | 模式推断 - 中等信任 |\n| SystemDefault | 0.50 | 默认值 - 最弱 |\n\n这些先验值在冲突解决时作为置信度计算的乘数因子。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n## API 接口\n\n### Python 绑定\n\n```python\n# 查询冲突历史\nconflicts = db.query_conflicts(\n status=\"unresolved\",\n priority=\"high\",\n limit=10\n)\n\n# 手动解决冲突\nresult = db.resolve_conflict(\n conflict_id=\"cf_xxx\",\n strategy=\"timestamp_wins\",\n winner_rid=\"mem_yyy\"\n)\n```\n\n资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:1-50]()\n\n## 总结\n\nyantrikdb 的冲突检测与解决系统采用了多层次、策略化的设计：\n\n1. **认知层** 通过激活传播和关系类型识别逻辑矛盾\n2. **引擎层** 实现多种解决策略，基于节点属性和冲突类型做出决策\n3. **分布式层** 使用 HLC 时钟和操作日志处理网络分区\n\n系统的核心设计原则是最小化对用户的干扰，同时确保记忆网络的一致性和可靠性。\n\n---\n\n\n\n## 主动触发系统\n\n### 相关页面\n\n相关主题：[认知循环与思考](#page-cognitive-loop), [冲突检测与解决](#page-conflict-detection)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)\n \n\n# 主动触发系统\n\n## 概述\n\n主动触发系统（Active Trigger System）是 yantrikdb 认知引擎的核心组件，负责监控记忆状态变化、检测模式并在适当时机主动发起认知操作。该系统基于预定义的触发类型（TriggerType）驱动认知循环（think loop），实现记忆衰减审查、冲突检测、模式发现等智能功能。\n\n触发系统的设计遵循事件驱动架构，通过冷却时间（cooldown）和过期时间（expiry）机制防止触发器过度激活，确保系统在用户可接受的频率下运行。\n\n## 触发类型体系\n\n### 触发类型枚举\n\n系统定义了 9 种触发类型，每种类型对应不同的认知需求场景：\n\n| 触发类型 | 描述 | 默认冷却时间 | 默认过期时间 | 资料来源 |\n|---------|------|-------------|-------------|---------|\n| `DecayReview` | 记忆衰减审查 | 3 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ConsolidationReady` | 记忆整合就绪 | 1 天 | 3 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ConflictEscalation` | 冲突升级检测 | 2 天 | 14 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `TemporalDrift` | 时间漂移检测 | 14 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `Redundancy` | 冗余检测 | 1 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `RelationshipInsight` | 关系洞察 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ValenceTrend` | 情感趋势分析 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `EntityAnomaly` | 实体异常检测 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `PatternDiscovered` | 模式发现 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n\n### 类型字符串映射\n\n每种触发类型支持与字符串的双向转换，便于序列化和配置管理：\n\n```rust\nimpl TriggerType {\n pub fn as_str(self) -> &'static str {\n match self {\n TriggerType::DecayReview => \"decay_review\",\n TriggerType::ConsolidationReady => \"consolidation_ready\",\n TriggerType::ConflictEscalation => \"conflict_escalation\",\n TriggerType::TemporalDrift => \"temporal_drift\",\n TriggerType::Redundancy => \"redundancy\",\n TriggerType::RelationshipInsight => \"relationship_insight\",\n TriggerType::ValenceTrend => \"valence_trend\",\n TriggerType::EntityAnomaly => \"entity_anomaly\",\n TriggerType::PatternDiscovered => \"pattern_discovered\",\n }\n }\n\n pub fn from_str(s: &str) -> Self {\n match s {\n \"decay_review\" => TriggerType::DecayReview,\n \"consolidation_ready\" => TriggerType::ConsolidationReady,\n // ... 其他映射\n _ => TriggerType::DecayReview,\n }\n }\n}\n```\n\n资料来源：[types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n\n## 触发配置\n\n### ThinkConfig 配置结构\n\n触发系统通过 `ThinkConfig` 结构体进行配置：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `importance_threshold` | f64 | 重要性阈值，决定哪些记忆值得触发 |\n| `decay_threshold` | f64 | 衰减阈值，用于判断记忆是否需要审查 |\n| `max_triggers` | - | 单次触发循环中允许的最大触发数量 |\n\n### 认知运算符优先级\n\n触发系统与认知运算符协同工作，不同运算符具有不同的优先级：\n\n```rust\nimpl CognitiveOperator {\n pub fn priority(self) -> usize {\n match self {\n Self::Attend(_) => 10, // 基础 - 始终运行\n Self::Recall(_) => 9, // 关键 - 上下文必需\n Self::Believe(_) => 8, // 证据整合\n Self::Compare(_) => 7, // 行动选择\n Self::Constrain(_) => 7, // 安全 - 比较时必须运行\n Self::Plan(_) => 6, // 手段-目的推理\n Self::Project(_) => 5, // 前向模拟\n Self::Anticipate(_) => 4, // 主动 - 锦上添花\n Self::Assess => 3, // 元认知 - 压力大时可跳过\n Self::CoherenceCheck => 2, // 维护 - 预算紧张时跳过\n }\n }\n}\n```\n\n资料来源：[query_dsl.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n\n## 触发工作流\n\n```mermaid\ngraph TD\n A[记忆状态变化] --> B{触发条件检查}\n B -->|满足| C[冷却时间检查]\n B -->|不满足| Z[跳过]\n C -->|冷却中| Z\n C -->|可触发| D[创建触发事件]\n D --> E[评估优先级]\n E --> F[执行认知运算符]\n F --> G{操作成功?}\n G -->|是| H[更新记忆状态]\n G -->|否| I[记录错误]\n H --> J[重置冷却计时器]\n I --> J\n```\n\n## 与感知系统的集成\n\n### SurfaceReason 表面原因\n\n触发系统与主动建议（Proactive Suggestion）机制紧密集成，通过 `SurfaceReason` 枚举记录触发原因：\n\n| 表面原因 | 描述 |\n|---------|------|\n| `LowReceptivity` | 低感知状态 |\n| `ItemSuppressionRule` | 项目抑制规则 |\n| `QuietHours` | 安静时段 |\n| `RateLimited` | 速率限制 |\n| `AntiNag` | 防打扰机制 |\n| `MaxSurfaces` | 达到最大表面数 |\n| `TooSoon` | 距上次过近 |\n| `NotificationModeBlock` | 通知模式阻止 |\n\n```rust\nimpl SurfaceReason {\n pub fn as_str(self) -> &'static str {\n match self {\n Self::LowReceptivity => \"low_receptivity\",\n Self::ItemSuppressionRule => \"item_suppression_rule\",\n Self::QuietHours => \"quiet_hours\",\n Self::RateLimited => \"rate_limited\",\n Self::AntiNag => \"anti_nag\",\n Self::MaxSurfaces => \"max_surfaces\",\n Self::TooSoon => \"too_soon\",\n Self::NotificationModeBlock => \"notification_mode_block\",\n }\n }\n}\n```\n\n资料来源：[surfacing.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n\n### 用户感知状态\n\n触发系统根据用户当前状态调整行为：\n\n```rust\npub fn interruption_cost(self) -> f64 {\n match self {\n Self::Idle => 0.10,\n Self::JustReturned => 0.35,\n Self::Browsing => 0.45,\n Self::Communicating => 0.55,\n Self::TaskSwitching => 0.65,\n Self::FocusedWork => 0.75,\n Self::DeepFocus => 0.95,\n }\n}\n```\n\n| 活动状态 | 中断成本 | 说明 |\n|---------|---------|------|\n| `Idle` | 0.10 | 空闲状态 |\n| `JustReturned` | 0.35 | 刚返回 |\n| `Browsing` | 0.45 | 浏览中 |\n| `Communicating` | 0.55 | 通讯中 |\n| `TaskSwitching` | 0.65 | 任务切换中 |\n| `FocusedWork` | 0.75 | 专注工作 |\n| `DeepFocus` | 0.95 | 深度专注 |\n\n资料来源：[receptivity.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n\n## 冲突触发机制\n\n### ConflictType 冲突类型\n\n冲突检测是触发系统的重要组成部分：\n\n| 冲突类型 | 默认优先级 | 描述 |\n|---------|----------|------|\n| `IdentityFact` | critical | 身份事实冲突 |\n| `Preference` | high | 偏好冲突 |\n| `Temporal` | high | 时间相关冲突 |\n| `Consolidation` | medium | 整合冲突 |\n| `Minor` | low | 轻微冲突 |\n\n```rust\nimpl ConflictType {\n pub fn default_priority(&self) -> &'static str {\n match self {\n ConflictType::IdentityFact => \"critical\",\n ConflictType::Preference => \"high\",\n ConflictType::Temporal => \"high\",\n ConflictType::Consolidation => \"medium\",\n ConflictType::Minor => \"low\",\n }\n }\n}\n```\n\n### Conflict 数据结构\n\n```rust\npub struct Conflict {\n pub conflict_id: String,\n pub conflict_type: String,\n pub priority: String,\n pub status: String,\n pub memory_a: String,\n pub memory_b: String,\n pub entity: Option,\n pub rel_type: Option,\n pub detected_at: f64,\n pub detected_by: String,\n pub detection_reason: String,\n pub resolved_at: Option,\n pub resolved_by: Option,\n pub strategy: Option,\n pub winner_rid: Option,\n pub resolution_note: Option,\n}\n```\n\n## 触发执行引擎\n\n### Attend 运算符\n\n`Attend` 运算符是触发系统的核心执行单元，负责激活相关记忆节点：\n\n```rust\nfn execute_attend(&self, op: &AttendOp) -> StepOutput {\n match self.db.hydrate_working_set(self.attention_config.clone()) {\n Ok(mut ws) => {\n let mut activated = 0;\n let mut top = Vec::new();\n for &seed in &op.seeds {\n if let Some(node) = ws.get_mut(seed) {\n let new_activation = (node.attrs.activation + 0.3).min(1.0);\n node.attrs.activation = new_activation;\n top.push((seed, new_activation));\n activated += 1;\n }\n }\n // 从种子节点扩散激活\n for &seed in &op.seeds {\n activated += ws.activate_and_spread(seed, 0.3);\n }\n StepOutput::Attend { nodes_activated: activated, top_activated: top }\n }\n Err(e) => StepOutput::Error { message: format!(\"Attend failed: {}\", e) },\n }\n}\n```\n\n### 运算符参数结构\n\n| 运算符 | 参数结构 | 主要功能 |\n|-------|---------|---------|\n| `Attend` | `AttendOp { seeds, max_hops, decay }` | 注意力激活与扩散 |\n| `Recall` | `RecallOp { top_k, query, domain }` | 记忆召回 |\n| `Believe` | `BelieveOp { evidence }` | 证据整合 |\n| `Project` | - | 前向模拟 |\n| `Compare` | - | 比较操作 |\n| `Constrain` | - | 约束检查 |\n| `Anticipate` | - | 预期生成 |\n| `Plan` | - | 计划生成 |\n\n## 认知属性与触发\n\n### CognitiveAttributes 认知属性\n\n每条记忆节点携带认知属性，影响触发决策：\n\n```rust\nSelf {\n confidence,\n activation: 0.0,\n salience,\n persistence,\n valence: 0.0,\n urgency: 0.0,\n novelty: 1.0,\n last_updated_ms: now_ms(),\n volatility: 0.1,\n provenance: Provenance::Observed,\n evidence_count: 1,\n}\n```\n\n### 节点类型与初始值\n\n| 节点类型 | 置信度 | 显著性 | 持久性 |\n|---------|-------|-------|-------|\n| `Entity` | 0.80 | 0.90 | 0.95 |\n| `Episode` | 0.60 | 0.80 | 0.70 |\n| `Belief` | 0.50 | 0.50 | 0.50 |\n| `Goal` | 0.70 | 0.60 | 0.80 |\n| `Task` | 0.90 | 0.80 | 0.90 |\n| `Need` | 0.60 | 0.70 | 0.40 |\n| `Opportunity` | 0.40 | 0.60 | 0.20 |\n| `Risk` | 0.40 | 0.70 | 0.60 |\n| `Constraint` | 0.90 | 0.80 | 0.95 |\n| `Preference` | 0.60 | 0.50 | 0.85 |\n\n资料来源：[state.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n\n### Provenance 可靠性先验\n\n```rust\npub fn reliability_prior(self) -> f64 {\n match self {\n Self::Told => 0.95, // 用户明确陈述 - 最高信任\n Self::Observed => 0.90, // 直接观察行为\n Self::Experimented => 0.85, // 通过受控实验确认\n Self::Extracted => 0.75, // 外部文档 - 可能过时\n Self::Inferred => 0.60, // 基于模式推理 - 中等信任\n Self::Consolidated => 0.80, // 多源合并\n Self::SystemDefault => 0.50, // 默认值 - 最弱，易覆盖\n }\n}\n```\n\n## 边缘类型与激活传递\n\n触发系统通过边缘类型决定激活如何在记忆网络间传递：\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n // 强正传递\n Self::Causes => 0.8,\n Self::Supports => 0.7,\n Self::Triggers => 0.7,\n Self::AdvancesGoal => 0.6,\n Self::Requires => 0.5,\n Self::SubtaskOf => 0.4,\n \n // 中等正传递\n Self::Predicts => 0.4,\n Self::AssociatedWith => 0.3,\n Self::SimilarTo => 0.3,\n Self::InstanceOf => 0.3,\n Self::PartOf => 0.3,\n Self::Prefers => 0.3,\n Self::PrecedesTemporally => 0.2,\n // ...\n }\n}\n```\n\n| 边缘类型 | 传递系数 | 说明 |\n|---------|---------|------|\n| `Causes` | 0.8 | 因果关系 |\n| `Supports` | 0.7 | 支持关系 |\n| `Triggers` | 0.7 | 触发关系 |\n| `AdvancesGoal` | 0.6 | 推进目标 |\n| `Requires` | 0.5 | 依赖关系 |\n| `SubtaskOf` | 0.4 | 子任务 |\n| `Predicts` | 0.4 | 预测关系 |\n| `AssociatedWith` | 0.3 | 关联关系 |\n| `SimilarTo` | 0.3 | 相似关系 |\n\n资料来源：[state.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n\n## 触发系统架构图\n\n```mermaid\ngraph TD\n subgraph 触发源层\n T1[DecayReview]\n T2[ConsolidationReady]\n T3[ConflictEscalation]\n T4[PatternDiscovered]\n T5[其他触发类型]\n end\n \n subgraph 冷却管理\n C1[冷却时间检查]\n C2[过期时间检查]\n C3[频率限制]\n end\n \n subgraph 执行层\n E1[Attend 运算符]\n E2[Recall 运算符]\n E3[Believe 运算符]\n E4[Plan 运算符]\n end\n \n subgraph 输出层\n O1[主动建议]\n O2[冲突报告]\n O3[认知追踪]\n end\n \n T1 --> C1\n T2 --> C1\n T3 --> C1\n T4 --> C1\n T5 --> C1\n \n C1 -->|通过| C2\n C2 -->|通过| C3\n C3 -->|通过| E1\n E1 --> E2\n E2 --> E3\n E3 --> E4\n \n E4 --> O1\n E4 --> O2\n E4 --> O3\n \n style T1 fill:#ff9999\n style T3 fill:#ffcc99\n style O1 fill:#99ff99\n```\n\n## 配置示例\n\n### Rust 配置\n\n```rust\nlet think_config = ThinkConfig {\n importance_threshold: 0.5,\n decay_threshold: 0.3,\n max_triggers: 5,\n};\n```\n\n### Python API 使用\n\n```python\nimport yantrikdb\n\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录记忆\ndb.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\n\n# 触发认知循环\ndb.think() # 触发整合、冲突检测、模式挖掘\n\ndb.close()\n```\n\n## 总结\n\n主动触发系统是 yantrikdb 实现智能记忆管理的核心机制。通过定义多种触发类型、完善的冷却/过期机制、与认知运算符的深度集成，系统能够在适当的时机主动发起记忆整合、冲突解决等操作，在不打扰用户的前提下持续优化记忆网络的质量和一致性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：yantrikos/yantrikdb\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。\n\n## 1. 安装坑 · 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code\n\n## 11. 配置坑 · 来源证据：v0.7.7 — recall_text Keyword-Only Filter Args\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：think() runs consolidation before conflict detection — contradictions get merged\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80497be2ab644e66be4fec1a966b4c10 | https://github.com/yantrikos/yantrikdb/issues/7 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7c8f7ee1384f9d97652734d01b8d67 | https://github.com/yantrikos/yantrikdb/issues/3 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40bcf8933f1b4ec7a559a746497c3bae | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.6 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5a77701b7ac401a863105d996cb585c | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 安全/权限坑 · 来源证据：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a590e518c884b5b9a2bbdc995c372fd | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | release_recency=unknown\n\n\n",
"markdown_key": "yantrikdb",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1164482810",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yantrikos/yantrikdb"
},
{
"evidence_id": "art_5d8de236598d4951b74656487f7d85ac",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/yantrikos/yantrikdb#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "yantrikdb 说明书",
"toc": [
"https://github.com/yantrikos/yantrikdb 项目说明书",
"目录",
"YantrikDB 简介",
"项目概述",
"核心架构",
"节点类型系统",
"关系边类型",
"认知属性系统",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "895a77725801db73e1bb0eb26d74af031ecc53ff",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/phase_4_3_design.md",
"docs/wedge_empirical_baseline_2026-05-06.md",
"docs/wedge_lock_scope_audit_2026-05-06.md",
"docs/wedge_concurrency_sweep_2026-05-07.md",
"docs/decoupled_write_path_rfc.md",
"docs/whitepaper/aidb_whitepaper.md",
"docs/showcase/wirecard.md",
"src/yantrikdb/cli.py",
"src/yantrikdb/consolidate.py",
"src/yantrikdb/api.py",
"src/yantrikdb/triggers.py",
"src/yantrikdb/__init__.py",
"src/yantrikdb/mcp/tools.py",
"src/yantrikdb/mcp/resources.py",
"src/yantrikdb/mcp/server.py",
"src/yantrikdb/mcp/__init__.py",
"src/yantrikdb/adapters/crewai.py",
"src/yantrikdb/adapters/__init__.py",
"src/yantrikdb/adapters/langchain.py",
"src/yantrikdb/adapters/openai_agents.py",
"src/yantrikdb/eval/harness.py",
"src/yantrikdb/eval/persona_marcus.py",
"src/yantrikdb/eval/persona_aisha.py",
"src/yantrikdb/eval/life_simulation.py",
"src/yantrikdb/eval/synthetic.py",
"src/yantrikdb/eval/__init__.py",
"src/yantrikdb/agent/companion.py",
"src/yantrikdb/agent/background.py",
"src/yantrikdb/agent/tools.py",
"src/yantrikdb/agent/embedder.py",
"src/yantrikdb/agent/voice.py",
"src/yantrikdb/agent/learning.py",
"src/yantrikdb/agent/llm.py",
"src/yantrikdb/agent/context.py",
"src/yantrikdb/agent/service.py",
"src/yantrikdb/agent/urges.py",
"src/yantrikdb/agent/__init__.py"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# yantrikdb - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 yantrikdb 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install yantrikdb-mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install yantrikdb` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：236\n- 重要文件覆盖：22/236\n- 证据索引条目：21\n- 角色 / Skill 条目：10\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 yantrikdb 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 yantrikdb 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 yantrikdb 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 10 个角色 / Skill / 项目文档条目。\n\n- **YantrikDB — A Cognitive Memory Engine for Persistent AI Systems**（project_doc）：YantrikDB — A Cognitive Memory Engine for Persistent AI Systems 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **RFC: Decoupled Write Path engine v0.7.0**（project_doc）：RFC: Decoupled Write Path engine v0.7.0 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/decoupled_write_path_rfc.md`\n- **Phase 4.3 — SQL writes off foreground design memo**（project_doc）：Phase 4.3 — SQL writes off foreground design memo 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/phase_4_3_design.md`\n- **Wedge — Concurrency Scaling Sweep**（project_doc）：Date: 2026-05-07 Engine version: v0.6.5 @ 36ba7da clean main, no Patch A Harness: crates/yantrikdb-core/examples/wedge repro.rs Params: dim=384, warmup=2000 records, duration=20s, readers=4, writers ∈ {1, 4, 8, 16, 32} Goal: characterize the wedge knee — at what writer concurrency does the engine start to bleed? 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/wedge_concurrency_sweep_2026-05-07.md`\n- **Wedge — Empirical Baseline**（project_doc）：Captured by: yantrikdb-core claude-opus-4-7 Date: 2026-05-06 Harness: crates/yantrikdb-core/examples/wedge repro.rs Engine version: v0.6.5 @ 36ba7da Goal: empirically confirm the lock-scope audit's mechanism hypothesis audit doc docs/wedge lock scope audit 2026-05-06.md and establish baseline numbers for measuring fixes against. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/wedge_empirical_baseline_2026-05-06.md`\n- **Lock-Scope Audit — Engine Hot Paths**（project_doc）：Lock-Scope Audit — Engine Hot Paths 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/wedge_lock_scope_audit_2026-05-06.md`\n- **What a claim-graph sees that a vector DB doesn't**（project_doc）：What a claim-graph sees that a vector DB doesn't 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/showcase/wirecard.md`\n- **1. Introduction**（project_doc）：The emergence of large language models has created AI systems capable of sophisticated reasoning, yet fundamentally amnesic. Each conversation begins from zero. Every user preference must be re-stated. No continuity of relationship develops over time. This is not merely an inconvenience---it represents a structural barrier to AI systems that genuinely know their users. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/whitepaper/aidb_whitepaper.md`\n- **YantrikDB Concurrency Invariants**（project_doc）：This document records the load-bearing concurrency invariants of the yantrikdb engine. Several inline // See CONCURRENCY.md comments in the code resolve to this file. Violating any of these silently regresses the wedge fix or correctness; review carefully before changing the affected code paths. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONCURRENCY.md`\n- **YantrikDB MCP Server Redesign — Session Brief**（project_doc）：YantrikDB MCP Server Redesign — Session Brief 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`MCP_REDESIGN.md`\n\n## 证据索引\n\n- 共索引 21 条证据。\n\n- **YantrikDB — A Cognitive Memory Engine for Persistent AI Systems**（documentation）：YantrikDB — A Cognitive Memory Engine for Persistent AI Systems 证据：`README.md`\n- **License**（source_file）：GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 证据：`LICENSE`\n- **RFC: Decoupled Write Path engine v0.7.0**（documentation）：RFC: Decoupled Write Path engine v0.7.0 证据：`docs/decoupled_write_path_rfc.md`\n- **Phase 4.3 — SQL writes off foreground design memo**（documentation）：Phase 4.3 — SQL writes off foreground design memo 证据：`docs/phase_4_3_design.md`\n- **Wedge — Concurrency Scaling Sweep**（documentation）：Date: 2026-05-07 Engine version: v0.6.5 @ 36ba7da clean main, no Patch A Harness: crates/yantrikdb-core/examples/wedge repro.rs Params: dim=384, warmup=2000 records, duration=20s, readers=4, writers ∈ {1, 4, 8, 16, 32} Goal: characterize the wedge knee — at what writer concurrency does the engine start to bleed? 证据：`docs/wedge_concurrency_sweep_2026-05-07.md`\n- **Wedge — Empirical Baseline**（documentation）：Captured by: yantrikdb-core claude-opus-4-7 Date: 2026-05-06 Harness: crates/yantrikdb-core/examples/wedge repro.rs Engine version: v0.6.5 @ 36ba7da Goal: empirically confirm the lock-scope audit's mechanism hypothesis audit doc docs/wedge lock scope audit 2026-05-06.md and establish baseline numbers for measuring fixes against. 证据：`docs/wedge_empirical_baseline_2026-05-06.md`\n- **Lock-Scope Audit — Engine Hot Paths**（documentation）：Lock-Scope Audit — Engine Hot Paths 证据：`docs/wedge_lock_scope_audit_2026-05-06.md`\n- **What a claim-graph sees that a vector DB doesn't**（documentation）：What a claim-graph sees that a vector DB doesn't 证据：`docs/showcase/wirecard.md`\n- **1. Introduction**（documentation）：The emergence of large language models has created AI systems capable of sophisticated reasoning, yet fundamentally amnesic. Each conversation begins from zero. Every user preference must be re-stated. No continuity of relationship develops over time. This is not merely an inconvenience---it represents a structural barrier to AI systems that genuinely know their users. 证据：`docs/whitepaper/aidb_whitepaper.md`\n- **YantrikDB Concurrency Invariants**（documentation）：This document records the load-bearing concurrency invariants of the yantrikdb engine. Several inline // See CONCURRENCY.md comments in the code resolve to this file. Violating any of these silently regresses the wedge fix or correctness; review carefully before changing the affected code paths. 证据：`CONCURRENCY.md`\n- **YantrikDB MCP Server Redesign — Session Brief**（documentation）：YantrikDB MCP Server Redesign — Session Brief 证据：`MCP_REDESIGN.md`\n- **Config**（structured_config）：{\"model type\": \"model2vec\", \"architectures\": \"StaticModel\" ,\"tokenizer name\": \"baai/bge-base-en-v1.5\", \"apply pca\": 64, \"apply zipf\": true, \"hidden dim\": 64, \"seq length\": 1000000, \"normalize\": true} 证据：`crates/yantrikdb-core/assets/potion-base-2M/config.json`\n- **Modules**（structured_config）：{ \"idx\": 0, \"name\": \"0\", \"path\": \".\", \"type\": \"sentence transformers.models.StaticEmbedding\" }, { \"idx\": 1, \"name\": \"1\", \"path\": \"1 Normalize\", \"type\": \"sentence transformers.models.Normalize\" } 证据：`crates/yantrikdb-core/assets/potion-base-2M/modules.json`\n- **Tokenizer**（structured_config）：{ \"version\": \"1.0\", \"truncation\": null, \"padding\": null, \"added tokens\": { \"id\": 0, \"content\": \" PAD \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\": true }, { \"id\": 1, \"content\": \" UNK \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\": true }, { \"id\": 2, \"content\": \" CLS \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\": true }, { \"id\": 3, \"content\": \" SEP \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\": true }, { \"id\": 4, \"content\": \" MASK \", \"single word\": false, \"lstrip\": false, \"rstrip\": false, \"normalized\": false, \"special\"… 证据：`crates/yantrikdb-core/assets/potion-base-2M/tokenizer.json`\n- **Scheduled Tasks**（source_file）：{\"sessionId\":\"48c5baf6-0baa-4c37-93d2-a8f22722b261\",\"pid\":92712,\"acquiredAt\":1778091707761} 证据：`.claude/scheduled_tasks.lock`\n- **MCP / Saga**（source_file）：MCP / Saga .mcp.json .tracker.db .tracker.db-shm .tracker.db-wal .env 证据：`.gitignore`\n- **Optimize dependencies candle, tokenizers even in dev builds.**（source_file）：workspace resolver = \"2\" members = \"crates/yantrikdb-core\", \"crates/yantrikdb-python\", exclude = \"crates/yantrikdb-wasm\", 证据：`Cargo.toml`\n- **Bench Rust Vs Python**（source_file）：\"\"\"Benchmarks for AIDB Rust engine core operations. 证据：`benchmarks/bench_rust_vs_python.py`\n- **v0.7.6 — bundled-embedder respect. Default install is just the**（source_file）：build-system requires = \"maturin =1.5\" build-backend = \"maturin\" 证据：`pyproject.toml`\n- **── 1. Test corpus: yantrikdb-shaped memories ──**（source_file）：\"\"\" Empirical quality eval: potion-base-2M vs all-MiniLM-L6-v2 vs Slice A hash-trick baseline, on yantrikdb-shaped memory texts. 证据：`scratch/eval_potion_2m.py`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\"Run the AIDB evaluation harness with real embeddings. 证据：`scripts/run_eval.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `LICENSE`, `docs/decoupled_write_path_rfc.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `LICENSE`, `docs/decoupled_write_path_rfc.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **YantrikDB 简介**：importance `high`\n - source_paths: README.md, Cargo.toml, LICENSE\n- **快速开始**：importance `high`\n - source_paths: README.md, pyproject.toml, src/yantrikdb/__init__.py\n- **五大索引架构**：importance `high`\n - source_paths: crates/yantrikdb-core/src/vector/hnsw.rs, crates/yantrikdb-core/src/vector/delta_index.rs, crates/yantrikdb-core/src/knowledge/graph.rs, crates/yantrikdb-core/src/knowledge/graph_index.rs, crates/yantrikdb-core/src/engine/indices.rs\n- **解耦写入路径**：importance `high`\n - source_paths: docs/decoupled_write_path_rfc.md, CONCURRENCY.md, crates/yantrikdb-core/src/vector/delta_index.rs, crates/yantrikdb-core/src/engine/materializer.rs\n- **线程安全与并发模型**：importance `medium`\n - source_paths: CONCURRENCY.md, crates/yantrikdb-core/src/engine/mod.rs, crates/yantrikdb-core/src/engine/tick.rs\n- **记录与检索操作**：importance `high`\n - source_paths: crates/yantrikdb-core/src/engine/record.rs, crates/yantrikdb-core/src/engine/recall.rs, crates/yantrikdb-core/src/base/scoring.rs, src/yantrikdb/api.py\n- **知识图谱操作**：importance `medium`\n - source_paths: crates/yantrikdb-core/src/knowledge/graph.rs, crates/yantrikdb-core/src/engine/graph_ops.rs, crates/yantrikdb-core/src/engine/graph_state.rs\n- **认知循环与思考**：importance `high`\n - source_paths: crates/yantrikdb-core/src/cognition/mod.rs, crates/yantrikdb-core/src/cognition/consolidate.rs, crates/yantrikdb-core/src/cognition/patterns.rs, crates/yantrikdb-core/src/engine/cognition.rs\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `895a77725801db73e1bb0eb26d74af031ecc53ff`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/phase_4_3_design.md`, `docs/wedge_empirical_baseline_2026-05-06.md`, `docs/wedge_lock_scope_audit_2026-05-06.md`, `docs/wedge_concurrency_sweep_2026-05-07.md`, `docs/decoupled_write_path_rfc.md`, `docs/whitepaper/aidb_whitepaper.md`, `docs/showcase/wirecard.md`, `src/yantrikdb/cli.py`, `src/yantrikdb/consolidate.py`, `src/yantrikdb/api.py`, `src/yantrikdb/triggers.py`, `src/yantrikdb/__init__.py`, `src/yantrikdb/mcp/tools.py`, `src/yantrikdb/mcp/resources.py`, `src/yantrikdb/mcp/server.py`, `src/yantrikdb/mcp/__init__.py`, `src/yantrikdb/adapters/crewai.py`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：yantrikos/yantrikdb\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host, claude, claude_code\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication（medium）：可能阻塞安装或首次运行。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/yantrikos/yantrikdb 项目说明书\n\n生成时间：2026-05-14 04:39:48 UTC\n\n## 目录\n\n- [YantrikDB 简介](#page-introduction)\n- [快速开始](#page-quickstart)\n- [五大索引架构](#page-five-indexes)\n- [解耦写入路径](#page-decoupled-write-path)\n- [线程安全与并发模型](#page-threading-model)\n- [记录与检索操作](#page-record-recall)\n- [知识图谱操作](#page-knowledge-graph)\n- [认知循环与思考](#page-cognitive-loop)\n- [冲突检测与解决](#page-conflict-detection)\n- [主动触发系统](#page-triggers-proactive)\n\n\n\n## YantrikDB 简介\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [五大索引架构](#page-five-indexes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n- [crates/yantrikdb-core/src/cognition/extractor.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/extractor.rs)\n- [crates/yantrikdb-core/src/cognition/personality_bias.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/personality_bias.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n \n\n# YantrikDB 简介\n\n## 项目概述\n\nYantrikDB 是一个开源的个人 AI 记忆引擎，采用 Rust 语言实现核心功能，同时提供 Python 语言绑定。它旨在为 AI 助手和大型语言模型（LLM）应用提供持久化的语义记忆能力，帮助 AI 系统记住用户的偏好、上下文信息和历史交互。资料来源：[README.md:1-50]()\n\nYantrikDB 的设计理念是让 AI 记忆系统**开箱即用**，无需复杂的依赖配置或第三方服务。引擎内置了默认的嵌入模型（`potion-base-2M`，约 7MB），直接通过 pip 安装后即可使用 `record_text()` 和 `recall_text()` 接口进行语义记忆的记录和检索。资料来源：[README.md:18-22]()\n\n## 核心架构\n\nYantrikDB 采用模块化架构设计，主要包含三个核心 crate：\n\n| Crate 名称 | 说明 |\n|-----------|------|\n| yantrikdb-core | 核心认知引擎，包含记忆存储、查询、冲突检测等功能 |\n| yantrikdb-python | Python 语言绑定，提供面向 Python 生态的 API |\n| yantrikdb-cli | 命令行工具，用于直接操作记忆库 |\n\n```mermaid\ngraph TD\n A[用户应用] --> B[Python API / CLI]\n B --> C[yantrikdb-core]\n C --> D[(SQLite 持久存储)]\n C --> E[认知处理层]\n E --> F[冲突检测]\n E --> G[记忆巩固]\n E --> H[主动建议]\n```\n\n架构的核心层包括：**认知状态管理**、**记忆查询系统**、**冲突检测与解决**、**叙事理解**以及**主动建议生成**。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n## 节点类型系统\n\nYantrikDB 使用统一的图结构来表示所有类型的记忆和认知对象。每种节点类型都有其特定的语义含义和属性。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:100-200]()\n\n### 节点类型一览\n\n| 节点类型 | 英文标识 | 说明 |\n|---------|---------|------|\n| 实体 | entity | 客观事实或具体对象 |\n| 事件 | episode | 时间相关的经历记录 |\n| 信念 | belief | 带有置信度的主观认知 |\n| 目标 | goal | 期望达成的状态 |\n| 任务 | task | 具体的可执行动作项 |\n| 意图假设 | intent_hypothesis | 推测的用户意图 |\n| 习惯 | routine | 周期性行为模式 |\n| 需求 | need | 用户的各种需求 |\n| 机会 | opportunity | 时间窗口内的有利时机 |\n| 风险 | risk | 潜在的威胁或问题 |\n| 约束 | constraint | 限制条件 |\n| 偏好 | preference | 用户偏好设置 |\n| 对话线程 | conversation_thread | 特定话题的对话上下文 |\n| 动作模式 | action_schema | 可复用的动作模板 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-280]()\n\n### 节点持久化策略\n\n并非所有节点类型都需要持久化存储到 SQLite 数据库中。以下节点类型默认为**瞬态**（transient），仅在工作集中存在：\n\n- `intent_hypothesis`（意图假设）\n- `conversation_thread`（对话线程）\n\n其他节点类型默认会持久化存储，支持跨会话记忆保持。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:250-270]()\n\n## 关系边类型\n\nYantrikDB 支持多种关系边类型，每种边类型都有不同的激活传递因子（activation_transfer），用于控制信息在图网络中的传播强度。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:300-400]()\n\n### 强关联边\n\n| 边类型 | 激活传递因子 | 说明 |\n|-------|-------------|------|\n| causes | 0.8 | 因果关系 |\n| supports | 0.7 | 支持关系 |\n| triggers | 0.7 | 触发关系 |\n| advances_goal | 0.6 | 推进目标 |\n| requires | 0.5 | 前置依赖 |\n| subtask_of | 0.4 | 子任务归属 |\n\n### 中等关联边\n\n| 边类型 | 激活传递因子 | 说明 |\n|-------|-------------|------|\n| predicts | 0.4 | 预测关系 |\n| associated_with | 0.3 | 关联关系 |\n| similar_to | 0.3 | 相似关系 |\n| instance_of | 0.3 | 实例关系 |\n| part_of | 0.3 | 部分关系 |\n| prefers | 0.3 | 偏好关系 |\n| precedes_temporally | 0.2 | 时间先后 |\n\n### 抑制边\n\n某些边类型具有负的激活传递因子，表示对目标节点的抑制作用。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:320-380]()\n\n## 认知属性系统\n\n每个认知节点都携带一套统一的属性集，用于描述节点在认知网络中的行为特征。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:400-500]()\n\n### 属性维度\n\n| 属性名称 | 范围 | 说明 |\n|---------|------|------|\n| confidence | [0.0, 1.0] | 置信度 |\n| activation | [0.0, 1.0] | 激活水平 |\n| salience | [0.0, 1.0] | 显著性/突出度 |\n| persistence | [0.0, 1.0] | 持久度 |\n| valence | [-1.0, 1.0] | 情感效价 |\n| urgency | [0.0, 1.0] | 紧迫程度 |\n| novelty | [0.0, 1.0] | 新颖程度 |\n| volatility | [0.0, 1.0] | 波动性 |\n\n### 来源可靠性\n\n节点的可信度与其信息来源（provenance）密切相关：\n\n| 来源类型 | 可靠性先验值 | 说明 |\n|---------|-------------|------|\n| Told | 0.95 | 用户明确陈述，信任度最高 |\n| Observed | 0.90 | 直接观察到的行为 |\n| Experimented | 0.85 | 通过实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取，可能过时 |\n| Inferred | 0.60 | 基于模式的推断 |\n| SystemDefault | 0.50 | 系统默认值，最易被覆盖 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:380-420]()\n\n## 记忆查询系统\n\n### Python API 查询接口\n\nPython 绑定提供了功能丰富的 `query` 方法，支持多种过滤和检索策略。资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-120]()\n\n```python\ndb.query(\n query=None, # 文本查询字符串\n embedding=None, # 直接传入嵌入向量\n top_k=10, # 返回前 k 条结果\n memory_type=None, # 按记忆类型过滤（如 \"episodic\"）\n namespace=None, # 按命名空间过滤\n time_window=None, # 时间窗口过滤 (start_ts, end_ts)\n expand_entities=False,# 是否展开关联实体\n include_consolidated=False, # 是否包含巩固后的记忆\n skip_reinforce=False, # 是否跳过强化学习步骤\n domain=None, # 按领域过滤\n source=None # 按来源过滤\n)\n```\n\n### 查询操作符\n\n核心认知引擎提供了 DSL 风格的查询操作符系统。资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-80]()\n\n| 操作符 | 优先级 | 说明 |\n|-------|-------|------|\n| Recall | 9 | 上下文检索，关键操作 |\n| Believe | 8 | 证据整合 |\n| Compare | 7 | 动作选择 |\n| Constrain | 7 | 安全约束，始终执行 |\n| Plan | 6 | 手段-目标推理 |\n| Project | 5 | 前向模拟 |\n| Anticipate | 4 | 主动预测 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性检查，资源紧张时可跳过 |\n\n### 查询结果示例\n\n```python\nresults = db.recall(\"who leads the team?\", top_k=3)\n# → [{\"text\": \"Alice is the engineering lead\", \"score\": 1.0}, ...]\n```\n\n资料来源：[README.md:30-35]()\n\n## 认知处理流程\n\n### Think 循环\n\n`think()` 方法是 YantrikDB 的核心认知处理入口，执行记忆巩固、冲突检测、模式挖掘等后台任务。资料来源：[README.md:36]()\n\n```mermaid\ngraph LR\n A[新事件记录] --> B[think() 调用]\n B --> C[记忆巩固]\n B --> D[冲突检测]\n B --> E[模式挖掘]\n B --> F[主动建议生成]\n C --> G[衰减处理]\n D --> H{检测到冲突?}\n H -->|是| I[冲突解决]\n H -->|否| J[输出建议]\n I --> J\n```\n\n### 冲突检测与解决\n\nYantrikDB 实现了完整的冲突检测和解决机制。冲突类型包括：资料来源：[crates/yantrikdb-core/src/base/types.rs:50-100]()\n\n| 冲突类型 | 默认优先级 | 说明 |\n|---------|-----------|------|\n| IdentityFact | critical | 身份事实冲突 |\n| Preference | high | 偏好冲突 |\n| Temporal | high | 时间冲突 |\n| Consolidation | medium | 合并冲突 |\n| Minor | low | 次要冲突 |\n\n冲突检测策略包括检查关系策略（relation_policies），考虑命名空间级别的配置。资料来源：[crates/yantrikdb-core/src/distributed/conflict.rs:80-120]()\n\n## 个性化系统\n\n### 人格偏差维度\n\nYantrikDB 包含一个人格偏差系统，包含 8 个可配置的维度，用于调整系统行为以适应用户偏好。资料来源：[crates/yantrikdb-core/src/cognition/personality_bias.rs:1-80]()\n\n| 维度名称 | 说明 |\n|---------|------|\n| curiosity | 好奇心 - 对新信息的探索倾向 |\n| proactivity | 主动性 - 主动干预的程度 |\n| caution | 谨慎性 - 行动前的风险评估 |\n| warmth | 温暖度 - 情感表达的程度 |\n| efficiency | 效率优先 - 完成任务的速度 |\n| playfulness | 趣味性 - 互动风格 |\n| formality | 正式程度 - 沟通风格 |\n| persistence | 坚持度 - 持续跟进的能力 |\n\n这些维度支持余弦相似度计算，可用于比较不同人格配置或与用户偏好进行匹配。资料来源：[crates/yantrikdb-core/src/cognition/personality_bias.rs:60-80]()\n\n## 叙事理解\n\nYantrikDB 包含叙事理解子系统，用于追踪和管理用户生活中的长期叙事弧线。资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:1-60]()\n\n### 叙事弧线状态\n\n| 状态 | 说明 |\n|-----|------|\n| Emerging | 刚检测到，尚未确认 |\n| Active | 活跃积累中 |\n| Paused | 暂停，可能恢复 |\n| Resolved | 目标达成或故事结束 |\n| Abandoned | 停止追踪 |\n\n### 章节类型\n\n| 类型 | 说明 |\n|-----|------|\n| Setup | 初始情境设定 |\n| Rising | 上升/进展 |\n| Climax | 高潮时刻 |\n| Falling | 回落/收尾 |\n| Resolution | 最终结论 |\n| Interlude | 插曲/过渡 |\n\n## 任务与目标管理\n\n### 任务状态机\n\nYantrikDB 内置完整的任务管理功能，支持任务生命周期管理。资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress : 开始执行\n InProgress --> Completed : 任务完成\n InProgress --> Blocked : 遇到阻碍\n Blocked --> InProgress : 阻碍解除\n InProgress --> Cancelled : 用户取消\n Pending --> Cancelled : 用户取消\n [*] --> Blocked\n```\n\n### 优先级等级\n\n| 优先级 | 系数 |\n|-------|------|\n| Low | 0.25 |\n| Medium | 0.50 |\n| High | 0.75 |\n| Critical | 1.00 |\n\n## 接受度与主动建议\n\nYantrikDB 的主动建议系统会考虑用户的当前状态和偏好。资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:1-50]()\n\n### 用户活动状态\n\n| 状态 | 中断成本 | 接收度 |\n|-----|---------|-------|\n| Idle | 0.20 | 0.70 |\n| JustReturned | 0.30 | 0.65 |\n| Browsing | 0.40 | 0.60 |\n| Communicating | 0.50 | 0.55 |\n| TaskSwitching | 0.55 | 0.45 |\n| FocusedWork | 0.75 | 0.30 |\n| DeepFocus | 0.95 | 0.10 |\n\n### 通知模式\n\n| 模式 | 说明 |\n|-----|------|\n| All | 允许所有通知 |\n| ImportantOnly | 仅重要通知 |\n| DoNotDisturb | 完全免打扰 |\n\n## 动作系统\n\n### 动作类型\n\nYantrikDB 定义了多种动作类型，每种类型有不同的基础成本：资料来源：[crates/yantrikdb-core/src/cognition/state.rs:450-520]()\n\n| 动作类型 | 基础成本 | 说明 |\n|---------|---------|------|\n| Abstain | 0.0 | 无操作 |\n| Inform | 0.05 | 信息告知 |\n| Organize | 0.10 | 整理组织 |\n| Suggest | 0.15 | 建议提议 |\n| Communicate | 0.20 | 沟通交流 |\n| Schedule | 0.25 | 日程安排 |\n| Warn | 0.30 | 警告提醒 |\n| Execute | 0.35 | 直接执行 |\n\n## 快速开始\n\n### 安装\n\n```bash\npip install yantrikdb\n```\n\n### Python 使用示例\n\n```python\nimport yantrikdb\n\n# 初始化数据库，使用内置嵌入模型\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录重要信息\ndb.record(\"Alice 是工程主管\", importance=0.8, domain=\"people\")\ndb.record(\"项目截止日期是 3 月 30 日\", importance=0.9, domain=\"work\")\ndb.record(\"用户偏好深色模式\", importance=0.6, domain=\"preference\")\n\n# 语义检索\nresults = db.recall(\"谁是团队负责人?\", top_k=3)\n\n# 建立关系\ndb.relate(\"Alice\", \"Engineering\", \"leads\")\ndb.get_edges(\"Alice\")\n\n# 执行认知处理\ndb.think()\n\ndb.close()\n```\n\n资料来源：[README.md:14-45]()\n\n## 技术特点总结\n\n| 特性 | 说明 |\n|-----|------|\n| 开箱即用 | 内置嵌入模型，无需额外依赖 |\n| 多语言支持 | Python API + CLI 工具 |\n| 图数据库 | 支持复杂关系建模 |\n| 持久化存储 | SQLite 本地存储 |\n| 认知计算 | 内置冲突检测、模式挖掘、叙事理解 |\n| 个性化 | 8 维人格偏差系统 |\n| 主动建议 | 基于用户状态智能推送 |\n\n---\n\n\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[YantrikDB 简介](#page-introduction), [记录与检索操作](#page-record-recall)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/yantrikos/yantrikdb/blob/main/README.md)\n- [pyproject.toml](https://github.com/yantrikos/yantrikdb/blob/main/pyproject.toml)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n- [crates/yantrikdb-python/src/py_engine/sync.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/sync.rs)\n- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n \n\n# 快速开始\n\n本文档为开发者提供 YantrikDB 的入门指南，帮助您快速了解系统架构、安装配置以及核心 API 的使用方法。\n\n## 系统概述\n\nYantrikDB 是一个基于 Rust 构建的认知记忆数据库，设计用于 AI 个人助手应用场景。它通过混合索引架构（DeltaIndex + HNSW）实现高效的记忆存储与检索，并提供完整的认知推理能力。\n\n**核心特性：**\n\n- 混合索引架构：DeltaIndex（增量索引）与 HNSW（分层可导航小世界图）结合\n- 多模态记忆支持：情景记忆、语义记忆、工作记忆\n- 认知引擎：支持注意力扩散、信念整合、规划推理等认知操作\n- 冲突检测与解决：自动检测记忆冲突并提供解决策略\n- 复制与同步：基于 HLC（混合逻辑时钟）的操作复制\n\n## 安装配置\n\n### 环境要求\n\n| 要求 | 版本 |\n|------|------|\n| Python | ≥ 3.10 |\n| Rust | ≥ 1.70 |\n\n### 安装步骤\n\n```bash\n# 从源码编译\ncargo build --release\n\n# 安装 Python 包\npip install -e .\n```\n\n## 核心概念\n\n### 记忆类型\n\n系统支持多种记忆类型，每种类型对应不同的存储和检索策略：\n\n| 记忆类型 | 说明 | 持久化 |\n|----------|------|--------|\n| Entity | 实体节点（人、地点、事物） | ✓ |\n| Episode | 情景记忆（事件片段） | ✓ |\n| Belief | 信念（带置信度） | ✓ |\n| Goal | 目标节点 | ✓ |\n| Task | 任务项（带状态） | ✓ |\n| IntentHypothesis | 意图假设 | ✗（默认） |\n| Routine | 例行行为模式 | ✓ |\n| Need | 需求（分类层级） | ✓ |\n| Opportunity | 机会（有时限） | ✓ |\n| Risk | 风险 | ✓ |\n| Constraint | 约束条件 | ✓ |\n| Preference | 用户偏好 | ✓ |\n| ConversationThread | 对话线程 | ✗（默认） |\n| ActionSchema | 动作模式 | ✓ |\n\n### 认知节点状态\n\n任务（Task）具有完整的状态机：\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending\n Pending --> InProgress\n InProgress --> Completed\n InProgress --> Blocked\n InProgress --> Cancelled\n Blocked --> InProgress\n Completed --> [*]\n Cancelled --> [*]\n```\n\n### 边类型与激活传递\n\n认知节点通过边连接，系统使用激活扩散算法进行推理：\n\n| 边类型 | 激活传递值 | 说明 |\n|--------|-----------|------|\n| Causes | 0.8 | 因果关系 |\n| Supports | 0.7 | 支持关系 |\n| Triggers | 0.7 | 触发关系 |\n| AdvancesGoal | 0.6 | 推进目标 |\n| Requires | 0.5 | 依赖关系 |\n| SubtaskOf | 0.4 | 子任务关系 |\n| Predicts | 0.4 | 预测关系 |\n| AssociatedWith | 0.3 | 关联关系 |\n| SimilarTo | 0.3 | 相似关系 |\n| Contradicts | -0.5 | 矛盾关系（抑制） |\n| BlocksGoal | -0.5 | 阻塞目标（抑制） |\n| Prevents | -0.6 | 阻止关系（抑制） |\n\n## Python API 快速使用\n\n### 初始化数据库\n\n```python\nfrom yantrikdb import YantrikDB\n\n# 初始化数据库\ndb = YantrikDB(\n path=\"./yantrik_data\",\n namespace=\"default\"\n)\n```\n\n### 记忆查询\n\n`query` 方法是核心检索接口，支持向量相似度搜索：\n\n```python\n# 使用文本查询\nresults = db.query(\n query=\"今天下午的会议内容\",\n top_k=10,\n memory_type=\"episode\",\n namespace=\"work\"\n)\n\n# 使用向量嵌入\nresults = db.query(\n embedding=[0.1, 0.2, 0.3, ...],\n top_k=5\n)\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | str | None | 自然语言查询 |\n| embedding | List[float] | None | 向量嵌入 |\n| top_k | int | 10 | 返回结果数量 |\n| memory_type | str | None | 记忆类型过滤 |\n| namespace | str | None | 命名空间过滤 |\n| time_window | Tuple[float, float] | None | 时间窗口（unix时间戳） |\n| expand_entities | bool | False | 展开关联实体 |\n| include_consolidated | bool | False | 包含已整合记忆 |\n| domain | str | None | 领域过滤 |\n| source | str | None | 来源过滤 |\n\n### 操作同步\n\n系统提供操作日志的提取和应用接口：\n\n```python\n# 提取指定时间点之后的操作\nops = db.extract_ops_since(\n since_hlc=hlc_bytes,\n since_op_id=\"op_123\",\n exclude_actor=None,\n limit=100\n)\n\n# 应用远程操作\ndb.apply_ops(ops)\n```\n\n**操作结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| op_id | str | 操作唯一标识 |\n| op_type | str | 操作类型 |\n| timestamp | float | 时间戳 |\n| target_rid | str | 目标资源ID |\n| payload | dict | 操作载荷 |\n| actor_id | str | 执行者ID |\n| hlc | bytes | HLC 逻辑时钟 |\n| embedding_hash | str | 嵌入哈希 |\n| origin_actor | str | 原始执行者 |\n\n## 认知引擎操作\n\n### 操作类型体系\n\n认知引擎通过 DSL 定义认知操作：\n\n| 操作 | 优先级 | 说明 |\n|------|--------|------|\n| Attend | 10 | 注意力聚焦 |\n| Recall | 9 | 记忆召回 |\n| Believe | 8 | 信念整合 |\n| Compare | 7 | 行动比较 |\n| Constrain | 7 | 约束检查 |\n| Plan | 6 | 规划推理 |\n| Project | 5 | 未来投影 |\n| Anticipate | 4 | 主动预期 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性检查 |\n\n### 注意力操作\n\n```python\n# 聚焦特定节点并扩散激活\nresult = db.think(\n operation=\"attend\",\n seeds=[\"node_id_1\", \"node_id_2\"],\n max_hops=3,\n decay=0.9\n)\n```\n\n### 信念整合\n\n```python\n# 整合新证据到信念网络\nresult = db.think(\n operation=\"believe\",\n evidence={\n \"target\": \"belief_node_id\", # 可选，None则创建新信念\n \"observation\": \"用户今天说喜欢喝咖啡\",\n \"direction\": \"positive\" # positive=确认, negative=矛盾\n }\n)\n```\n\n## 需求分类系统\n\n系统内置完整的需求分类层级：\n\n```mermaid\ngraph TD\n Need --> Informational\n Need --> Social\n Need --> Emotional\n Need --> Organizational\n Need --> Creative\n Need --> Health\n Need --> Financial\n Need --> Professional\n```\n\n| 类别 | 标识符 |\n|------|--------|\n| 信息需求 | informational |\n| 社交需求 | social |\n| 情感需求 | emotional |\n| 组织需求 | organizational |\n| 创造需求 | creative |\n| 健康需求 | health |\n| 财务需求 | financial |\n| 职业需求 | professional |\n\n## 冲突检测与解决\n\n### 冲突类型\n\n| 类型 | 标识符 | 默认优先级 |\n|------|--------|-----------|\n| 身份事实冲突 | identity_fact | critical |\n| 偏好冲突 | preference | high |\n| 时间冲突 | temporal | high |\n| 整合冲突 | consolidation | medium |\n| 轻微冲突 | minor | low |\n\n### 冲突结构\n\n```python\nclass Conflict:\n conflict_id: str # 冲突唯一ID\n conflict_type: str # 冲突类型\n priority: str # 优先级\n status: str # 状态\n memory_a: str # 冲突方A\n memory_b: str # 冲突方B\n entity: Optional[str] # 相关实体\n detected_at: float # 检测时间\n detected_by: str # 检测方法\n resolution_note: Optional[str] # 解决说明\n```\n\n## 叙事弧线追踪\n\n系统支持叙事弧线（Narrative Arc）来理解用户生活中的长期主题：\n\n**弧线类型：**\n\n- Project（项目）\n- Habit（习惯）\n- Relationship（关系）\n- Discovery（发现）\n- Loss（失去）\n- Recovery（恢复）\n\n**弧线状态：**\n\n```mermaid\nstateDiagram-v2\n [*] --> Emerging\n Emerging --> Active\n Active --> Paused\n Paused --> Active\n Active --> Resolved\n Active --> Abandoned\n Paused --> Abandoned\n Resolved --> [*]\n Abandoned --> [*]\n```\n\n## 完整示例\n\n```python\nfrom yantrikdb import YantrikDB\n\n# 1. 初始化\ndb = YantrikDB(path=\"./data\", namespace=\"user_001\")\n\n# 2. 记录情景记忆\ndb.remember(\n text=\"用户下午3点与张经理开会讨论Q4计划\",\n memory_type=\"episode\",\n entities=[\"张经理\"],\n domain=\"work\"\n)\n\n# 3. 创建关联任务\ndb.think(operation=\"create_task\", description=\"跟进Q4计划讨论结果\")\n\n# 4. 设置偏好\ndb.set_preference(domain=\"notifications\", preferred=\"静默模式\")\n\n# 5. 查询相关记忆\nresults = db.query(\n query=\"Q4计划相关\",\n top_k=5,\n memory_type=[\"episode\", \"task\"],\n expand_entities=True\n)\n\n# 6. 提取同步数据（用于多设备同步）\nops = db.extract_ops_since(since_op_id=\"last_sync_id\")\n```\n\n## 下一步\n\n- 查看 [架构设计](./architecture.md) 深入了解系统内部实现\n- 参考 [API 文档](./api_reference.md) 获取完整接口说明\n- 阅读 [认知引擎](./cognitive_engine.md) 了解推理机制\n- 查看 [复制协议](./replication.md) 学习多节点同步\n\n---\n\n\n\n## 五大索引架构\n\n### 相关页面\n\n相关主题：[YantrikDB 简介](#page-introduction), [解耦写入路径](#page-decoupled-write-path), [知识图谱操作](#page-knowledge-graph)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/vector/hnsw.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/hnsw.rs)\n- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n- [crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n- [crates/yantrikdb-core/src/knowledge/graph_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph_index.rs)\n- [crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n \n\n# 五大索引架构\n\n## 概述\n\nyantrikdb 采用多层次、多类型的索引架构来支撑知识存储与检索能力。根据源码组织结构，该系统主要包含五大索引组件：\n\n| 索引类型 | 源码位置 | 主要用途 |\n|---------|---------|---------|\n| HNSW 向量索引 | `vector/hnsw.rs` | 高维向量相似性搜索 |\n| Delta 索引 | `vector/delta_index.rs` | 增量数据变更追踪 |\n| 知识图谱索引 | `knowledge/graph.rs` | 实体关系网络存储 |\n| 图索引 | `knowledge/graph_index.rs` | 图遍历查询优化 |\n| 引擎索引 | `engine/indices.rs` | 统一索引协调管理 |\n\n资料来源：[crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n\n---\n\n## 一、HNSW 向量索引\n\n### 1.1 架构设计\n\nHNSW（Hierarchical Navigable Small World）是一种基于概率跳表结构的近似最近邻搜索算法，在 yantrikdb 中用于支持语义相似性检索。\n\n```mermaid\ngraph TD\n A[输入向量] --> B[搜索层 L_max]\n B --> C[搜索层 L_1]\n C --> D[底层向量空间]\n D --> E[候选最近邻]\n E --> F[精排结果]\n \n G[插入向量] --> H[随机层选择]\n H --> I[自上而下插入]\n I --> D\n```\n\n### 1.2 核心特性\n\n- **分层结构**：构建多层 skip list，每层跳过的距离逐渐缩小\n- **贪心搜索**：在每层执行贪心遍历寻找最优邻居\n- **ef_construction 参数**：控制构建时候选集大小，影响索引质量与构建时间\n- **ef_search 参数**：控制搜索时候选集大小，影响查询精度与延迟\n\n### 1.3 应用场景\n\n| 场景 | 说明 |\n|-----|------|\n| 语义记忆检索 | 基于文本 embedding 查找相关记忆 |\n| 向量相似匹配 | 支持余弦相似度、欧氏距离等度量 |\n| 召回阶段加速 | 在大规模候选集中快速定位 top-k |\n\n资料来源：[crates/yantrikdb-core/src/vector/hnsw.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/hnsw.rs)\n\n---\n\n## 二、Delta 索引\n\n### 2.1 设计目的\n\nDelta 索引用于追踪和管理增量变更，避免频繁全量重建索引带来的性能开销。\n\n```mermaid\ngraph LR\n A[新增数据] --> B[Delta Log]\n C[修改数据] --> B\n D[删除数据] --> B\n \n B --> E[增量合并]\n E --> F[主索引更新]\n \n G[查询请求] --> H[合并视图]\n H --> G\n```\n\n### 2.2 核心数据结构\n\nDelta 索引维护一个变更日志，包含以下操作类型：\n\n| 操作类型 | 说明 | 对索引的影响 |\n|---------|------|-------------|\n| INSERT | 新增记录 | 追加到索引末尾 |\n| UPDATE | 更新记录 | 标记旧版本、插入新版本 |\n| DELETE | 删除记录 | 软删除或版本号标记 |\n\n### 2.3 合并策略\n\n- **定期合并**：定时将 delta 变更合并回主索引\n- **阈值触发**：当 delta 大小超过阈值时触发合并\n- **写时合并**：高写入场景采用 LSM-tree 风格的合并策略\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n\n---\n\n## 三、知识图谱索引\n\n### 3.1 图模型\n\nyantrikdb 的知识图谱采用属性图模型，支持多类型节点和关系边。\n\n```mermaid\ngraph TD\n A[Entity 节点] -->|HasAttribute| B[属性键值对]\n A -->|BelongsTo| C[命名空间]\n \n D[Relation 边] -->|src| A\n D -->|dst| E[目标节点]\n D -->|rel_type| F[关系类型]\n D -->|temporal| G[时序信息]\n \n H[元数据] -->|provenance| I[来源信息]\n H -->|confidence| J[置信度]\n```\n\n### 3.2 节点类型体系\n\n系统支持多种认知节点类型，通过 `NodeKind` 枚举统一管理：\n\n| 节点类型 | 英文标识 | 持久化 | 说明 |\n|---------|---------|-------|------|\n| 实体 | entity | ✓ | 事实性信息 |\n| 事件 | episode | ✓ | 时序发生的事件 |\n| 信念 | belief | ✓ | 带有置信度的认知 |\n| 目标 | goal | ✓ | 用户意图目标 |\n| 任务 | task | ✓ | 具体行动项 |\n| 意图假设 | intent_hypothesis | ✗ | 临时推理结果 |\n| 习惯 | routine | ✓ | 周期性行为 |\n| 需求 | need | ✓ | 用户需求分类 |\n| 机会 | opportunity | ✓ | 时限性机会 |\n| 风险 | risk | ✓ | 潜在问题 |\n| 约束 | constraint | ✓ | 限制条件 |\n| 偏好 | preference | ✓ | 用户偏好设置 |\n| 对话线索 | conversation_thread | ✗ | 临时对话状态 |\n| 行动模式 | action_schema | ✓ | 可执行动作模板 |\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n\n### 3.3 边类型与激活传递\n\n边类型定义了节点间的语义关联强度，影响激活传播算法：\n\n| 关系类型 | 激活传递系数 | 说明 |\n|---------|-------------|------|\n| causes | 0.8 | 强因果关系 |\n| supports | 0.7 | 支持关系 |\n| triggers | 0.7 | 触发关系 |\n| advances_goal | 0.6 | 推进目标 |\n| requires | 0.5 | 依赖关系 |\n| subtask_of | 0.4 | 子任务关系 |\n| predicts | 0.4 | 预测关系 |\n| associated_with | 0.3 | 关联关系 |\n| similar_to | 0.3 | 相似关系 |\n| precedes_temporally | 0.2 | 时序先导 |\n| contradicts | -0.5 | 矛盾关系 |\n| blocks_goal | -0.6 | 阻碍目标 |\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph.rs)\n\n---\n\n## 四、图索引\n\n### 4.1 索引构建策略\n\n图索引针对知识图谱的查询模式进行专门优化，支持多种索引类型：\n\n```mermaid\ngraph LR\n A[原始图数据] --> B[关系类型索引]\n A --> C[时序索引]\n A --> D[命名空间索引]\n A --> E[属性索引]\n \n B --> F[关系遍历加速]\n C --> G[时序查询优化]\n D --> H[多租户隔离]\n E --> I[属性过滤加速]\n```\n\n### 4.2 查询优化\n\n| 优化类型 | 实现方式 | 适用场景 |\n|---------|---------|---------|\n| 入度/出度索引 | 预计算节点连接数 | 度过滤查询 |\n| 邻接列表 | 按关系类型分组存储 | 批量遍历 |\n| 时序索引 | B-Tree 或 LSM-Tree | 范围查询 |\n| 命名空间索引 | Hash 分区 | 多租户隔离 |\n\n### 4.3 冲突检测\n\n图索引支持基于命名空间策略的冲突检测：\n\n- **overlap_allowed**：是否允许同一关系类型的重叠\n- **temporal_required**：是否要求时序约束\n- **missing_time_severity**：缺失时序信息的严重级别\n\n资料来源：[crates/yantrikdb-core/src/knowledge/graph_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/knowledge/graph_index.rs)\n\n---\n\n## 五、引擎索引协调层\n\n### 5.1 统一索引接口\n\n引擎索引作为协调层，统一管理上述各类索引的创建、查询和生命周期：\n\n```mermaid\ngraph TD\n A[Query 请求] --> B[引擎索引协调器]\n B --> C{Hash 路由}\n C -->|向量查询| D[HNSW 索引]\n C -->|图查询| E[图索引]\n C -->|混合查询| F[Delta 合并]\n \n D --> G[结果集]\n E --> G\n F --> G\n \n G --> H[结果合并与排序]\n H --> I[最终结果]\n \n J[写入请求] --> K[Delta 索引]\n K --> L{合并阈值}\n L -->|触发| M[主索引更新]\n M --> D\n M --> E\n```\n\n### 5.2 索引配置参数\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|-------|------|\n| hnsw_ef_construction | u32 | 100 | HNSW 构建参数 |\n| hnsw_ef_search | u32 | 50 | HNSW 搜索参数 |\n| hnsw_m | u32 | 16 | HNSW 邻居数 |\n| delta_merge_threshold | usize | 10000 | Delta 合并阈值 |\n| graph_cache_size | usize | 1000 | 图索引缓存大小 |\n\n### 5.3 索引生命周期\n\n| 阶段 | 操作 | 说明 |\n|-----|------|------|\n| 创建 | `create_index()` | 根据配置初始化索引结构 |\n| 写入 | `insert()` / `upsert()` | 添加或更新索引数据 |\n| 查询 | `search()` / `query()` | 执行索引检索 |\n| 合并 | `merge_delta()` | 将增量合并回主索引 |\n| 重建 | `rebuild()` | 全量重建索引 |\n| 删除 | `drop_index()` | 清理索引资源 |\n\n资料来源：[crates/yantrikdb-core/src/engine/indices.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/indices.rs)\n\n---\n\n## 六、协同工作流程\n\n### 6.1 写入流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as 引擎索引\n participant Delta as Delta 索引\n participant HNSW as HNSW\n participant Graph as 图索引\n \n Client->>Engine: 写入请求\n Engine->>Delta: 记录变更\n Engine->>HNSW: 异步插入向量\n Engine->>Graph: 创建/更新节点/边\n \n alt Delta 达到阈值\n Delta->>Engine: 触发合并\n Engine->>HNSW: 批量更新\n Engine->>Graph: 批量更新\n end\n```\n\n### 6.2 查询流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Engine as 引擎索引\n participant HNSW as HNSW\n participant Graph as 图索引\n participant Recall as Recall 查询\n \n Client->>Engine: Recall 查询\n Engine->>Recall: 构建查询参数\n Recall->>HNSW: 向量相似搜索\n Recall->>Graph: 图关系扩展\n HNSW-->>Recall: Top-K 向量结果\n Graph-->>Recall: 关系过滤结果\n Recall->>Engine: 合并排序结果\n Engine-->>Client: 最终结果\n```\n\n### 6.3 认知查询语言集成\n\n系统通过 `RecallQuery` 结构支持组合查询：\n\n| 参数 | 类型 | 说明 |\n|-----|------|------|\n| embedding | Vec | 查询向量 |\n| top_k | usize | 返回结果数量 |\n| memory_type | Option<&str> | 记忆类型过滤 |\n| namespace | Option<&str> | 命名空间隔离 |\n| time_window | Option<(f64, f64)> | 时序范围 |\n| domain | Option<&str> | 领域过滤 |\n| source | Option<&str> | 来源过滤 |\n\n---\n\n## 七、总结\n\nyantrikdb 的五大索引架构通过分层设计实现了高效的知识存储与检索：\n\n1. **HNSW 向量索引**：提供亚线性时间复杂度的近似最近邻搜索能力\n2. **Delta 索引**：通过增量变更追踪实现高写入性能\n3. **知识图谱索引**：支持丰富的语义关系建模\n4. **图索引**：针对图遍历操作进行专门优化\n5. **引擎索引协调层**：统一管理各类索引，提供一致的查询接口\n\n这些索引组件相互协作，共同支撑了 yantrikdb 作为认知数据库的核心功能。\n\n---\n\n\n\n## 解耦写入路径\n\n### 相关页面\n\n相关主题：[五大索引架构](#page-five-indexes), [线程安全与并发模型](#page-threading-model)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [docs/decoupled_write_path_rfc.md](https://github.com/yantrikos/yantrikdb/blob/main/docs/decoupled_write_path_rfc.md)\n- [CONCURRENCY.md](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md)\n- [crates/yantrikdb-core/src/vector/delta_index.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/vector/delta_index.rs)\n- [crates/yantrikdb-core/src/engine/materializer.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/materializer.rs)\n \n\n# 解耦写入路径\n\n## 概述\n\n解耦写入路径（Decoupled Write Path）是 yantrikdb 中一项核心架构设计，旨在将前台写入操作与向量索引维护工作彻底分离。该设计解决了传统向量数据库在高并发写入场景下的性能瓶颈问题。\n\n传统的向量数据库通常将写入操作与索引更新耦合在一起，导致写入线程在执行 HNSW（Hierarchical Navigable Small World）图构建时产生显著延迟。yantrikdb 通过引入 **Delta Index** 增量索引机制，将写入操作限制在 O(1) 复杂度的简单数据结构中，而将计算密集型的 HNSW 索引构建工作委托给后台压缩进程执行。\n\n资料来源：[docs/decoupled_write_path_rfc.md:1-20]()\n\n## 核心设计原则\n\n### 写入操作的约束\n\n解耦写入路径对前台写入操作施加了严格的约束，确保写入路径保持极低的延迟：\n\n| 操作类型 | 允许操作 | 禁止操作 |\n|---------|---------|---------|\n| DeltaIndex | `append` / `tombstone` | `HnswIndex::insert` |\n| 序列号分配 | `assign_seq` (atomic fetch_add) | `HnswIndex::remove` |\n| 可见性更新 | `bump_visible_seq` | `compact()` |\n\n资料来源：[CONCURRENCY.md:1-30]()\n\n### 写入操作的职责边界\n\n写入原语（如 `record_with_rid`、`forget`、`correct` 等）**必须**仅执行以下操作：\n\n- `DeltaIndex::append` / `DeltaIndex::tombstone`：O(1) 复杂度的写操作，仅进行简单的向量推送，不涉及 HNSW 工作\n- `assign_seq`：原子序列号分配，使用 `fetch_add` 或 `fetch_max`\n- `bump_visible_seq`：DashMap 分片读取 + `AtomicU64::fetch_max`，稳态下无锁\n\n写入原语**禁止**调用：\n\n- `HnswIndex::insert` / `HnswIndex::remove`：这些属于压缩进程的职责\n- `compact()`：仅允许后台执行\n\n资料来源：[CONCURRENCY.md:25-40]()\n\n## 架构设计\n\n### 分层存储结构\n\nyantrikdb 采用冷热分离的分层存储架构：\n\n```mermaid\ngraph TD\n subgraph 前台写入路径\n Write[写入请求] --> Delta[DeltaIndex
热数据层]\n Delta --> Append[append
O1复杂度]\n Delta --> Tombstone[tombstone
墓碑标记]\n end\n \n subgraph 后台压缩路径\n Compact[compact
后台进程] --> Seal[seal_delta_for_compaction
密封热数据]\n Seal --> Clone[clone-rebuild cold
克隆重建冷数据]\n Clone --> Install[安装新的冷数据层]\n Delta -.->|定期触发| Compact\n end\n \n subgraph 存储层\n Cold[ArcSwap<HnswIndex>
冷数据层-只读快照]\n Install --> Cold\n end\n \n subgraph 读取路径\n Read[读取请求] --> Snapshot[获取快照]\n Snapshot -->|lock-free| Cold\n Snapshot -->|lock-free| Delta\n end\n```\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs:1-50]()\n\n### DeltaIndex 实现\n\nDeltaIndex 是解耦写入路径的核心数据结构，负责管理增量写入操作：\n\n```mermaid\nclassDiagram\n class DeltaIndex {\n +entries: RwLock~Vec~DeltaEntry~~\n +append(entry: DeltaEntry)\n +tombstone(rid: &str)\n +compact() -> HnswIndex\n +seal_delta_for_compaction() Vec~DeltaEntry~\n }\n \n class DeltaEntry {\n +op_type: OpType\n +rid: String\n +vector: Vec~f32~\n +seq: u64\n +is_tombstone: bool\n }\n \n class OpType {\n <>\n Insert\n Update\n Delete\n }\n```\n\nDeltaIndex 的 `append` 和 `tombstone` 方法是 O(1) 复杂度的操作，不会触发任何 HNSW 索引更新。这确保了前台写入的极低延迟。\n\n资料来源：[crates/yantrikdb-core/src/vector/delta_index.rs:50-150]()\n\n### ArcSwap 冷数据层\n\n冷数据层采用 `ArcSwap` 实现，而非传统的 `RwLock` 或 `Mutex`。这种设计提供了无锁的快照获取能力：\n\n```rust\n// 正确的实现方式\nstruct ColdTier {\n index: ArcSwap, // 原子交换的不可变快照\n}\n```\n\n**关键不变量**：不得将冷数据层的 `ArcSwap` 替换为 `RwLock` 或 `Mutex`。这种替换会破坏并发性能，导致读取 p99 延迟上升。\n\n资料来源：[CONCURRENCY.md:60-80]()\n\n## 后台压缩机制\n\n### 压缩流程\n\n后台压缩进程负责将增量数据合并到主索引中：\n\n```mermaid\nsequenceDiagram\n participant Write as 写入线程\n participant Delta as DeltaIndex\n participant Compact as 压缩进程\n participant Cold as ArcSwap冷数据层\n \n Write->>Delta: append(entry)\n Write->>Delta: bump_visible_seq(ns)\n \n Note over Delta: 稳态无锁操作\n \n Compact->>Delta: seal_delta_for_compaction()\n Note over Delta: 短暂持有delta RwLock
仅用于密封操作\n \n Compact->>Compact: clone-rebuild cold\n Note over Compact: 不持有任何锁\n \n Compact->>Cold: ArcSwap::store(new_index)\n Note over Cold: 短暂持有install锁\n \n Write->>Cold: load_arc() 获取新快照\n Write->>Delta: 继续追加新entry\n```\n\n压缩进程在执行克隆重建期间**不会持有**任何前台写入需要获取的锁。这确保了写入操作不会因压缩而阻塞。\n\n资料来源：[CONCURRENCY.md:45-60]()\n\n### 锁的获取顺序\n\n| 阶段 | 持有的锁 | 时长 |\n|-----|---------|-----|\n| 密封阶段 | `delta` RwLock | 短暂 |\n| 重建阶段 | 无 | 较长 |\n| 安装阶段 | `delta` RwLock | 短暂 |\n\n资料来源：[CONCURRENCY.md:45-55]()\n\n## 并发控制\n\n### visible_seq 的无锁实现\n\nPhase 6 引入的 `visible_seq` 映射表**必须**保持读取无锁特性：\n\n```rust\n// 字段类型定义\nvisible_seq: DashMap\n\n// 读取路径 (lock-free)\nlet seq = visible_seq\n .get(ns)\n .map(|e| e.load(Acquire));\n\n// 写入路径 (fast path)\nvisible_seq\n .get(ns)\n .fetch_max(seq, Release);\n```\n\n**性能影响**：在集群规模下，`visible_seq_for(ns)` 在每次 `recall_with_seq` 调用时都会执行。如果替换为 `Mutex`，会导致集群 RYW（Read-Your-Writes）退化为全局互斥锁热点路径。\n\n资料来源：[CONCURRENCY.md:85-100]()\n\n### 写入原语的模式\n\n所有新的写入原语必须遵循 `record_with_rid` 的模式：\n\n```mermaid\ngraph LR\n A[SAVEPOINT] --> B[SQL操作]\n B --> C[DeltaIndex::append]\n C --> D[bump_visible_seq]\n D --> E[COMMIT/ROLLBACK]\n```\n\n资料来源：[CONCURRENCY.md:35-40]()\n\n## Materializer 模块\n\nMaterializer 负责将查询结果从内部表示转换为外部格式，是解耦写入路径在读取侧的配合组件：\n\n```mermaid\nclassDiagram\n class Materializer {\n +materialize(query_result: QueryResult) -> SurfaceResult\n +apply_salience(node: Node) -> Node\n +filter_hidden(nodes: Vec~Node~) -> Vec~Node~\n }\n \n class QueryResult {\n +nodes: Vec~NodeId~\n +scores: Vec~f64~\n +context: RecallContext\n }\n \n class SurfaceResult {\n +items: Vec~SurfaceItem~\n +metadata: SurfaceMetadata\n }\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/materializer.rs:1-60]()\n\n## 配置选项\n\n解耦写入路径的行为可通过以下配置进行调整：\n\n| 配置项 | 类型 | 默认值 | 说明 |\n|-------|------|-------|-----|\n| `delta_capacity` | usize | 10000 | DeltaIndex 的初始容量 |\n| `compaction_interval_secs` | u64 | 3600 | 压缩检查间隔（秒） |\n| `compaction_batch_size` | usize | 1000 | 每次压缩处理的条目数 |\n| `tombstone_retention_secs` | u64 | 86400 | 墓碑保留时间 |\n\n资料来源：[docs/decoupled_write_path_rfc.md:50-80]()\n\n## 性能特性\n\n### 写入性能\n\n| 指标 | 目标值 | 说明 |\n|-----|-------|-----|\n| 写入延迟 P50 | < 1ms | 单次 append 操作 |\n| 写入延迟 P99 | < 5ms | 含序列号分配 |\n| 写入吞吐量 | > 50k/s | 8 写入线程下 |\n\n资料来源：[CONCURRENCY.md:70-75]()\n\n### 读取性能\n\n| 指标 | 目标值 | 说明 |\n|-----|-------|-----|\n| 读取延迟 P50 | < 10ms | 含快照获取 |\n| 读取延迟 P99 | < 200ms | 8 写入线程 / 30s 压力下 |\n\n资料来源：[CONCURRENCY.md:75-80]()\n\n## 最佳实践\n\n### 开发新写入原语\n\n新增写入原语时，必须遵循以下模式：\n\n1. **使用 SAVEPOINT 包装**：确保 SQL 操作的事务性\n2. **调用 DeltaIndex::append**：而非直接操作 HNSW 索引\n3. **调用 bump_visible_seq**：更新命名空间的可见序列号\n4. **禁止阻塞操作**：不得在写入路径中调用任何可能阻塞的操作\n\n```rust\n// 正确的实现示例\nfn new_write_primitive(&self, entry: DeltaEntry) -> Result<()> {\n self.conn().execute(\"SAVEPOINT sp_new_write\")?;\n \n // SQL 操作\n self.sql_insert(&entry)?;\n \n // DeltaIndex 操作\n self.delta.append(entry.clone())?;\n \n // 可见性更新\n self.bump_visible_seq(&entry.namespace)?;\n \n self.conn().execute(\"RELEASE SAVEPOINT sp_new_write\")?;\n Ok(())\n}\n```\n\n资料来源：[CONCURRENCY.md:30-45]()\n\n### 验证并发正确性\n\n新增写入原语后，必须验证：\n\n- 运行 `crates/yantrikdb-core/examples/wedge_repro.rs` 示例\n- 确保读取 p99 延迟 < 200ms（8 写入线程 / 30s 压力下）\n- 确认读取 P50 延迟保持稳定\n- 验证写入吞吐量未下降\n\n资料来源：[CONCURRENCY.md:70-80]()\n\n## 总结\n\n解耦写入路径是 yantrikdb 架构中的关键创新，通过以下设计实现了高并发下的稳定性能：\n\n- **热数据层（DeltaIndex）**：O(1) 复杂度的无阻塞写入\n- **冷数据层（ArcSwap）**：无锁的只读快照访问\n- **后台压缩**：将 HNSW 计算与前台写入完全隔离\n- **DashMap visible_seq**：集群级别的无锁读取保证\n\n这种设计使得 yantrikdb 能够在高写入负载下保持毫秒级的查询延迟，同时支持复杂的向量搜索能力。\n\n资料来源：[docs/decoupled_write_path_rfc.md:80-100](), [CONCURRENCY.md:1-100]()\n\n---\n\n\n\n## 线程安全与并发模型\n\n### 相关页面\n\n相关主题：[解耦写入路径](#page-decoupled-write-path)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONCURRENCY.md](https://github.com/yantrikos/yantrikdb/blob/main/CONCURRENCY.md)\n- [crates/yantrikdb-core/src/engine/mod.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/mod.rs)\n- [crates/yantrikdb-core/src/engine/tick.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/tick.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n \n\n# 线程安全与并发模型\n\nyantrikdb 是一个基于 Rust 构建的认知数据库引擎，其线程安全与并发模型是保障系统在高并发读写场景下稳定运行的核心设计。本文档详细阐述 yantrikdb 的并发控制机制、锁策略、以及核心不变性保证。\n\n## 1. 设计目标与约束\n\nyantrikdb 的并发模型围绕以下核心目标设计：\n\n| 目标 | 描述 |\n|------|------|\n| **读写分离** | 读取操作不应被写入操作阻塞 |\n| **无锁读取** | 读取路径尽可能采用 lock-free 数据结构 |\n| **写吞吐** | 写入操作需保持高吞吐量，避免锁竞争 |\n| **后台隔离** | 压缩（compaction）等重量级操作不得干扰前台写入 |\n\n资料来源：[CONCURRENCY.md:1-15]()\n\n## 2. 核心并发规则\n\nyantrikdb 定义了六条必须遵守的并发不变性规则：\n\n### 2.1 规则一：写入路径禁止非 O(1) 锁\n\n所有写操作原语必须遵守**单锁原则**：禁止在写路径中获取任何非 O(1) 复杂度的锁。任何新的写原语必须仅使用：\n\n- `DeltaIndex::append` / `DeltaIndex::tombstone`（短暂 RwLock 写操作）\n- `assign_seq`（原子操作 fetch_add 或 fetch_max）\n- `bump_visible_seq`（DashMap 分片读取 + AtomicU64::fetch_max）\n\n资料来源：[CONCURRENCY.md:17-25]()\n\n### 2.2 规则二：写入原语仅操作增量索引\n\n以下写入操作**必须仅**触碰增量索引相关接口：\n\n- `upsert_*_with_rid`\n- `forget`\n- `correct`\n- `upsert_entity_edge_with_id`\n- `delete_entity_edge_with_id`\n\n它们**禁止**调用：\n\n- `HnswIndex::insert` / `HnswIndex::remove`（仅压缩时可用）\n- `compact()`（仅后台执行）\n- 任何压缩器也会获取的新 RwLock\n\n新增写原语需遵循 `record_with_rid` 的模式：SAVEPOINT 保护的 SQL 块 + `DeltaIndex::append` + `bump_visible_seq`。\n\n资料来源：[CONCURRENCY.md:27-42]()\n\n### 2.3 规则三：后台压缩与前台写操作锁隔离\n\n`DeltaIndex::compact` 执行昂贵的 HNSW 向量索引重建工作，其锁持有策略如下：\n\n```mermaid\ngraph TD\n A[开始压缩] --> B[seal_delta_for_compaction]\n B --> C{获取 delta RwLock}\n C -->|短暂| D[交换待处理条目]\n D --> E[释放 delta 锁]\n E --> F[执行 HNSW 重建]\n F --> G{获取 delta RwLock}\n G -->|短暂| H[安装新 cold tier]\n H --> I[释放锁]\n I --> J[压缩完成]\n \n K[前台写入] -.->|不受 F 阶段阻塞| L[DeltaIndex::append]\n```\n\n后台压缩在**封存**（seal）和**安装**（install）阶段短暂持有 delta 锁，在 HNSW 重建期间**不持有**任何前台写入也会获取的锁。\n\n资料来源：[CONCURRENCY.md:44-58]()\n\n## 3. 分层存储与读写分离\n\nyantrikdb 采用分层存储架构实现读写分离：\n\n```mermaid\ngraph TD\n subgraph 写入路径\n W[写入请求] --> D[DeltaIndex
增量索引]\n D --> |append| DS[DeltaIndex 结构
RwLock Vec]\n end\n \n subgraph 读取路径\n R[读取请求] --> C[Cold Tier]\n C --> |ArcSwap| HI[HnswIndex
向量索引]\n end\n \n subgraph 后台压缩\n CP[Compactor] --> |定期| CC[Clone + Rebuild]\n CC --> |install| C\n end\n \n DS -.->|compaction| CC\n```\n\n### 3.1 Cold Tier 的 ArcSwap 保证\n\nCold tier（冷数据层）必须使用 `ArcSwap` 而非 `RwLock` 或 `Mutex`。\n\n| 锁类型 | 读取行为 | 问题 |\n|--------|----------|------|\n| `RwLock` | 写锁持有期间阻塞所有读取 | 高并发下读取延迟飙升 |\n| `Mutex` | 独占访问 | 完全串行化读取 |\n| `ArcSwap` | 读取获取稳定快照 | 无锁读取，性能稳定 |\n\n**不变性**：不要用 `RwLock` 或 `Mutex` 替换 cold tier 的 `ArcSwap`。如需验证，应运行 `crates/yantrikdb-core/examples/wedge_repro.rs` 并保持 v0.6.6 版本后的性能指标（8 writers / 30s 下读取 p99 < 200ms）。\n\n资料来源：[CONCURRENCY.md:60-75]()\n\n## 4. Visible Sequence 的 Lock-Free 设计\n\n### 4.1 架构设计\n\n`visible_seq` 是 Phase 6 引入的读-your-writes（RYW）可见性机制，其数据结构定义为：\n\n```rust\ndashmap::DashMap\n```\n\n| 操作 | 方法 | 复杂度 |\n|------|------|--------|\n| 读取 | `get(ns).map(|e| e.load(Acquire))` | O(1), lock-free |\n| 写入 | `get(ns).fetch_max(seq, Release)` | O(1), lock-free |\n\n### 4.2 性能影响\n\n`visible_seq_for(ns)` 在每次 `recall_with_seq` 调用时都会执行，在集群规模下这是**主要流量路径**。用 `Mutex>` 替代将导致全局互斥锁热点，严重影响集群 RYW 性能。\n\n**不变性**：`YantrikDB::visible_seq` 字段类型必须保持为 `dashmap::DashMap`。\n\n资料来源：[CONCURRENCY.md:77-90]()\n\n## 5. 认知引擎的操作符并发模型\n\n认知引擎（cognition engine）通过 DSL 定义操作符的执行优先级：\n\n### 5.1 操作符优先级表\n\n| 优先级 | 操作符 | 说明 |\n|--------|--------|------|\n| 10 | `Attend` | 基础注意力机制，始终执行 |\n| 9 | `Recall` | 上下文召回关键操作 |\n| 8 | `Believe` | 证据整合 |\n| 7 | `Compare` | 动作选择 |\n| 7 | `Constrain` | 安全约束，必要时执行 |\n| 6 | `Plan` | 手段-目标推理 |\n| 5 | `Project` | 前向模拟 |\n| 4 | `Anticipate` | 主动预测 |\n| 3 | `Assess` | 元认知评估 |\n| 2 | `CoherenceCheck` | 一致性检查，高压下可跳过 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n### 5.2 步骤执行结果输出\n\n```rust\npub enum StepOutput {\n Attend(AttendOutput),\n Recall(RecallOutput),\n Believe(BelieveOutput),\n Compare(CompareOutput),\n Constrain(ConstrainOutput),\n Plan(PlanOutput),\n Project(ProjectOutput),\n Anticipate(AnticipateOutput),\n Assess(AssessOutput),\n CoherenceCheck(CoherenceCheckOutput),\n Skipped { reason: String },\n Error { message: String },\n}\n```\n\n操作符执行结果通过 `ExplanationTrace` 结构进行追踪和解释构建：\n\n```rust\nfn build_explanation(steps: &[StepResult]) -> ExplanationTrace {\n let explanation_steps: Vec = steps\n .iter()\n .enumerate()\n .filter(|(_, s)| s.success)\n .map(|(i, s)| ExplanationStep {\n step_number: i + 1,\n operator: s.operator.clone(),\n description: s.trace.clone().unwrap_or_else(|| ...),\n key_insight: extract_key_insight(&s.output),\n })\n .collect();\n // ...\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:150-180]()\n\n## 6. 分布式冲突检测\n\n在分布式场景下，yantrikdb 使用 `relation_policies` 表管理命名空间级别的冲突策略：\n\n```sql\nSELECT overlap_allowed, temporal_required, missing_time_severity\nFROM relation_policies\nWHERE relation_type = ?1 AND (namespace = ?2 OR namespace = '*')\nORDER BY CASE WHEN namespace = ?2 THEN 0 ELSE 1 END\nLIMIT 1\n```\n\n### 6.1 冲突检测流程\n\n```mermaid\ngraph TD\n A[检测候选关系对] --> B{超过最大冲突数?}\n B -->|是| Z[停止检测]\n B -->|否| C[查询命名空间策略]\n C --> D{存在策略记录?}\n D -->|是| E[应用 overlap_allowed]\n D -->|否| F[使用全局 '*' 策略]\n E --> G{冲突类型检查}\n F --> G\n G --> H[标记冲突节点]\n```\n\n### 6.2 冲突类型\n\n| 冲突类型 | 默认优先级 | 说明 |\n|----------|------------|------|\n| `IdentityFact` | critical | 身份事实冲突 |\n| `Preference` | high | 偏好冲突 |\n| `Temporal` | high | 时间维度冲突 |\n| `Consolidation` | medium | 整合冲突 |\n| `Minor` | low | 轻微冲突 |\n\n资料来源：[crates/yantrikdb-core/src/distributed/conflict.rs:1-50]()\n\n## 7. 认知节点的状态与激活传播\n\n### 7.1 节点类型\n\n| 节点类型 | 持久化 | 激活转移因子 |\n|----------|--------|--------------|\n| `Entity` | ✓ | 0.8 |\n| `Episode` | ✓ | 0.6 |\n| `Belief` | ✓ | 0.7 |\n| `Goal` | ✓ | 0.6 |\n| `Task` | ✓ | 0.4 |\n| `IntentHypothesis` | ✗ | 0.5 |\n| `Routine` | ✓ | 0.5 |\n| `Need` | ✓ | 0.6 |\n| `Opportunity` | ✓ | 0.4 |\n| `Risk` | ✓ | 0.4 |\n| `Constraint` | ✓ | 0.9 |\n| `Preference` | ✓ | 0.6 |\n| `ConversationThread` | ✗ | 0.8 |\n| `ActionSchema` | ✓ | 0.7 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n### 7.2 边缘类型的激活传播\n\n边缘类型决定激活如何在节点间传播，负值表示抑制：\n\n```mermaid\ngraph LR\n A[源节点] -->|\"Supports 0.7\"| B[目标节点]\n A -->|\"Causes 0.8\"| C[目标节点]\n A -->|\"Inhibits -0.5\"| D[目标节点]\n```\n\n| 边缘类型 | 激活转移 | 语义 |\n|----------|----------|------|\n| `Supports` | 0.7 | 支持关系 |\n| `Causes` | 0.8 | 因果关系 |\n| `AdvancesGoal` | 0.6 | 推进目标 |\n| `Triggers` | 0.7 | 触发关系 |\n| `Requires` | 0.5 | 依赖关系 |\n| `SubtaskOf` | 0.4 | 子任务关系 |\n| `Contradicts` | -0.6 | 矛盾关系 |\n| `Prevents` | -0.8 | 阻止关系 |\n\n## 8. 认知属性的可靠性模型\n\n### 8.1 来源类型（Provenance）\n\n信息来源影响信任度：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|------------|------|\n| `Told` | 0.95 | 用户明确陈述，最高信任 |\n| `Observed` | 0.90 | 直接观察的行为 |\n| `Experimented` | 0.85 | 通过受控实验确认 |\n| `Consolidated` | 0.80 | 多源合并 |\n| `Extracted` | 0.75 | 外部文档提取，可能过时 |\n| `Inferred` | 0.60 | 基于模式的推断 |\n| `SystemDefault` | 0.50 | 默认值，最弱 |\n\n### 8.2 通用认知属性\n\n每个认知节点携带 11 维属性：\n\n| 属性 | 范围 | 说明 |\n|------|------|------|\n| `confidence` | [0.0, 1.0] | 置信度 |\n| `activation` | [0.0, 1.0] | 激活水平 |\n| `salience` | [0.0, 1.0] | 显著度 |\n| `persistence` | [0.0, 1.0] | 持久性 |\n| `valence` | [-1.0, 1.0] | 情感效价 |\n| `urgency` | [0.0, 1.0] | 紧急程度 |\n| `novelty` | [0.0, 1.0] | 新颖性 |\n| `volatility` | [0.0, 1.0] | 波动性 |\n| `provenance` | enum | 信息来源 |\n| `evidence_count` | u32 | 证据数量 |\n| `last_updated_ms` | u64 | 最后更新时间 |\n\n## 9. 触发器与冷却机制\n\n### 9.1 触发器类型\n\n| 触发器类型 | 默认冷却时间 | 默认过期时间 |\n|------------|--------------|--------------|\n| `DecayReview` | 3 天 | 7 天 |\n| `ConsolidationReady` | 1 天 | 3 天 |\n| `ConflictEscalation` | 2 天 | 14 天 |\n| `TemporalDrift` | 14 天 | 7 天 |\n| `Redundancy` | 1 天 | 7 天 |\n| `RelationshipInsight` | 7 天 | 7 天 |\n| `ValenceTrend` | 7 天 | 7 天 |\n| `EntityAnomaly` | 7 天 | 7 天 |\n| `PatternDiscovered` | 7 天 | 7 天 |\n\n## 10. 行动成本模型\n\n行动类型具有不同的基础成本：\n\n| 行动类型 | 基础成本 | 说明 |\n|----------|----------|------|\n| `Abstain` | 0.0 | 无操作 |\n| `Inform` | 0.05 | 信息通知 |\n| `Organize` | 0.10 | 组织整理 |\n| `Suggest` | 0.15 | 建议提出 |\n| `Communicate` | 0.20 | 主动沟通 |\n| `Schedule` | 0.25 | 日程安排 |\n| `Warn` | 0.30 | 警告提示 |\n| `Execute` | 0.35 | 执行操作 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n## 11. 关键不变性总结\n\n| 编号 | 不变性描述 | 违反后果 |\n|------|------------|----------|\n| INV-1 | 写路径不得获取非 O(1) 锁 | 写入延迟增加 |\n| INV-2 | 写原语仅操作 DeltaIndex | 压缩逻辑耦合前台写入 |\n| INV-3 | 压缩与前台锁隔离 | 前台写入被后台阻塞 |\n| INV-4 | Cold tier 使用 ArcSwap | 读取延迟飙升（wedge 问题） |\n| INV-5 | visible_seq 保持 lock-free | 全局互斥锁成为热点 |\n\n---\n\n**相关文档**：\n- [架构设计](./architecture.md)\n- [分布式冲突检测](./distributed-conflict.md)\n- [认知引擎](./cognition-engine.md)\n\n---\n\n\n\n## 记录与检索操作\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [认知循环与思考](#page-cognitive-loop)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/engine/record.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/record.rs)\n- [crates/yantrikdb-core/src/engine/recall.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/recall.rs)\n- [crates/yantrikdb-core/src/base/scoring.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/scoring.rs)\n- [src/yantrikdb/api.py](https://github.com/yantrikos/yantrikdb/blob/main/src/src/yantrikdb/api.py)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n \n\n# 记录与检索操作\n\n## 概述\n\n记录（Record）与检索（Recall）是 YantrikDB 的核心认知操作模块，负责信息的持久化存储和上下文感知的记忆召回。记录操作用于将文本、嵌入向量及元数据存入数据库；检索操作用于根据查询向量或文本从存储的记忆中匹配最相关的结果。\n\n这两个操作构成了知识管理的基础循环：记录输入新信息 → 检索召回相关上下文 → 支持推理决策。\n\n---\n\n## 核心架构\n\n### 模块位置\n\n| 模块 | 路径 | 职责 |\n|------|------|------|\n| 记录引擎 | `crates/yantrikdb-core/src/engine/record.rs` | 处理记忆写入、加密、元数据管理 |\n| 检索引擎 | `crates/yantrikdb-core/src/engine/recall.rs` | 向量相似度搜索、评分排序 |\n| 评分系统 | `crates/yantrikdb-core/src/base/scoring.rs` | 多维度相关性评分计算 |\n| Python绑定 | `crates/yantrikdb-python/src/py_engine/memory.rs` | Python API封装 |\n\n### 数据流图\n\n```mermaid\ngraph TD\n subgraph 记录流程\n A[输入文本] --> B[文本嵌入]\n B --> C[重要性评分]\n C --> D[情感极性标注]\n D --> E[加密存储]\n E --> F[(SQLite数据库)]\n end\n \n subgraph 检索流程\n G[查询向量] --> H[候选集生成]\n H --> I[多维度评分]\n I --> J[重排序]\n J --> K[结果过滤]\n K --> L[返回结果]\n end\n \n F -.->|候选集| H\n```\n\n---\n\n## 记录操作\n\n### record 方法签名\n\nPython API 中 `record` 方法的完整签名：\n\n```python\ndef record(\n self,\n text: str,\n memory_type: str = \"episodic\",\n importance: float = 0.5,\n valence: float = 0.5,\n half_life: Optional[float] = None,\n embedding: Optional[List[float]] = None,\n metadata: Optional[Dict] = None,\n namespace: Optional[str] = None,\n certainty: float = 1.0,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n emotional_state: Optional[str] = None,\n) -> str:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `text` | `str` | 必填 | 要记录的文本内容 |\n| `memory_type` | `str` | `\"episodic\"` | 记忆类型（见下表） |\n| `importance` | `float` | `0.5` | 重要性评分 [0.0, 1.0] |\n| `valence` | `float` | `0.5` | 情感极性 [0.0=负面, 1.0=正面] |\n| `half_life` | `float` | `None` | 记忆衰减半衰期（秒），默认按类型自动计算 |\n| `embedding` | `List[float]` | `None` | 预计算的嵌入向量，默认使用内置 embedder |\n| `metadata` | `Dict` | `None` | 自定义键值对元数据 |\n| `namespace` | `str` | `None` | 命名空间隔离 |\n| `certainty` | `float` | `1.0` | 信息确定性 [0.0, 1.0] |\n| `domain` | `str` | `None` | 知识领域标签 |\n| `source` | `str` | `None` | 信息来源标识 |\n| `emotional_state` | `str` | `None` | 记录时的情感状态 |\n\n### 记忆类型\n\n| 类型 | 说明 | 默认半衰期 |\n|------|------|-----------|\n| `episodic` | 情景记忆 - 具体事件经历 | 7天 |\n| `semantic` | 语义记忆 - 抽象知识事实 | 30天 |\n| `procedural` | 程序记忆 - 技能与习惯 | 90天 |\n| `working` | 工作记忆 - 当前任务上下文 | 1小时 |\n| `consolidated` | 已整合记忆 | 由系统管理 |\n\n### 记录流程详解\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant API as Python API\n participant Core as 核心引擎\n participant Embed as 嵌入模块\n participant Crypto as 加密模块\n participant DB as SQLite\n\n User->>API: record(text, importance, ...)\n API->>Core: record(...)\n alt 无预计算嵌入\n Core->>Embed: embed_text(text)\n Embed-->>Core: embedding_vector\n end\n Core->>Core: 计算重要性评分\n Core->>Crypto: encrypt_text(text)\n Crypto-->>Core: encrypted_blob\n Core->>DB: INSERT memory\n DB-->>Core: rid (记录ID)\n Core-->>API: rid\n API-->>User: record_id\n```\n\n### 返回值\n\n记录成功时返回唯一的记录标识符 `rid`（字符串格式），可用于后续的关联查询：\n\n```python\nrid = db.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\n# rid: \"M01H2K3...\"\n```\n\n---\n\n## 检索操作\n\n### recall 方法签名\n\nPython API 中 `recall` 方法的完整签名：\n\n```python\ndef recall(\n self,\n query: Optional[str] = None,\n query_embedding: Optional[List[float]] = None,\n top_k: int = 10,\n time_window: Optional[Tuple[float, float]] = None,\n memory_type: Optional[str] = None,\n include_consolidated: bool = False,\n expand_entities: bool = True,\n skip_reinforce: bool = False,\n namespace: Optional[str] = None,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n) -> List[Dict]:\n```\n\n### 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `query` | `str` | `None` | 自然语言查询文本 |\n| `query_embedding` | `List[float]` | `None` | 预计算的查询向量 |\n| `top_k` | `int` | `10` | 返回结果数量上限 |\n| `time_window` | `Tuple[float, float]` | `None` | 时间窗口过滤 `(start_unix, end_unix)` |\n| `memory_type` | `str` | `None` | 按记忆类型过滤 |\n| `include_consolidated` | `bool` | `False` | 是否包含已整合的记忆 |\n| `expand_entities` | `bool` | `True` | 是否展开实体节点 |\n| `skip_reinforce` | `bool` | `False` | 是否跳过记忆强化 |\n| `namespace` | `str` | `None` | 命名空间过滤 |\n| `domain` | `str` | `None` | 领域标签过滤 |\n| `source` | `str` | `None` | 来源过滤 |\n\n### 返回结构\n\n```python\n{\n \"results\": [\n {\n \"rid\": \"M01H2K3...\",\n \"text\": \"Alice is the engineering lead\",\n \"score\": 0.92,\n \"memory_type\": \"semantic\",\n \"importance\": 0.8,\n \"timestamp\": 1234567890.0,\n \"metadata\": {...}\n },\n ...\n ],\n \"confidence\": 0.87,\n \"certainty_reasons\": [\"entity_overlap\", \"recency\"],\n \"retrieval_summary\": {\n \"top_similarity\": 0.92,\n \"score_spread\": 0.31,\n \"sources_used\": [\"episodic\", \"semantic\"],\n \"candidate_count\": 150\n },\n \"hints\": [...]\n}\n```\n\n### 多维度评分机制\n\n检索结果通过多维度加权评分计算相关性：\n\n```mermaid\ngraph LR\n A[查询向量] --> B[语义相似度]\n A --> C[时间衰减]\n A --> D[重要性权重]\n A --> E[实体重叠度]\n \n B --> F[综合评分]\n C --> F\n D --> F\n E --> F\n \n F --> G[重排序]\n G --> H[Top-K 结果]\n```\n\n评分维度说明：\n\n| 维度 | 权重范围 | 说明 |\n|------|----------|------|\n| `recency` | 0.0-1.0 | 最近访问的记忆得分更高 |\n| `frequency` | 0.0-1.0 | 访问频率影响权重 |\n| `entity_overlap` | 0.0-1.0 | 与查询实体重叠程度 |\n| `valence_match` | 0.0-1.0 | 情感极性与上下文匹配度 |\n| `importance` | 0.0-1.0 | 记录时的重要性评分 |\n| `similarity` | 0.0-1.0 | 向量余弦相似度 |\n\n### 检索流程详解\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant API as Python API\n participant Core as 核心引擎\n participant Embed as 嵌入模块\n participant DB as SQLite\n participant Score as 评分引擎\n\n User->>API: recall(query, top_k)\n API->>Core: recall(...)\n alt 无预计算向量\n Core->>Embed: embed_text(query)\n Embed-->>Core: query_vector\n end\n Core->>DB: SELECT candidates\n DB-->>Core: candidate_set\n Core->>Score: score(query_vector, candidates)\n Score-->>Core: ranked_results\n Core->>Core: apply_filters\n Core-->>API: RecallResponse\n API-->>User: results\n```\n\n---\n\n## 查询构建器模式\n\n核心模块提供了流畅的查询构建器接口：\n\n```python\nfrom yantrikdb_core import RecallQuery\n\nquery = (RecallQuery::new(embedding)\n .top_k(10)\n .memory_type(\"episodic\")\n .namespace(\"work\")\n .time_window(start_time, end_time)\n .include_consolidated(false)\n .domain(\"engineering\"))\n```\n\n---\n\n## 记忆强化机制\n\n检索操作默认会触发记忆强化（reinforcement），增强被召回记忆的持久性：\n\n- 增加访问计数 `access_count`\n- 更新最后访问时间 `last_access`\n- 动态调整半衰期（频繁访问的记忆衰减更慢）\n\n如需跳过强化，使用 `skip_reinforce=True` 参数。\n\n---\n\n## 命名空间隔离\n\n通过 `namespace` 参数实现多用户或多场景的数据隔离：\n\n```python\n# 用户A的记忆\ndb.record(\"Project deadline March 30\", namespace=\"user_a\")\ndb.record(\"Prefers email notifications\", namespace=\"user_a\")\n\n# 用户B的记忆\ndb.record(\"Likes video calls\", namespace=\"user_b\")\n\n# 检索时指定命名空间\nresults = db.recall(\"deadline?\", namespace=\"user_a\")\n```\n\n---\n\n## 实用示例\n\n### 基本记录与检索\n\n```python\nimport yantrikdb\n\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录信息\ndb.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\ndb.record(\"Project deadline is March 30\", importance=0.9, domain=\"work\")\ndb.record(\"User prefers dark mode\", importance=0.6, domain=\"preference\")\n\n# 检索相关记忆\nresults = db.recall(\"who leads the team?\", top_k=3)\n# → [{\"text\": \"Alice is the engineering lead\", \"score\": 1.0}, ...]\n\ndb.close()\n```\n\n### 高级过滤检索\n\n```python\nimport time\n\n# 时间窗口过滤：最近7天的记忆\nnow = time.time()\nweek_ago = now - 7 * 86400\n\nresults = db.recall(\n query=\"meeting notes\",\n top_k=5,\n time_window=(week_ago, now),\n memory_type=\"episodic\",\n domain=\"work\",\n include_consolidated=False\n)\n```\n\n---\n\n## 相关配置\n\n### 内置嵌入器\n\nYantrikDB 自带默认嵌入模型 (`potion-base-2M`，64维)，无需额外依赖：\n\n```python\n# 使用默认嵌入器（开箱即用）\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 升级为更高质量嵌入（首次调用时下载）\ndb = yantrikdb.YantrikDB(\"memory.db\", embedder=\"bge-base\")\n```\n\n### 置信度阈值\n\n检索结果的置信度由 `certainty_reasons` 和多维度评分综合计算得出，可用于过滤低质量结果：\n\n```python\nresults = db.recall(\"project status?\", top_k=10)\nhigh_confidence = [r for r in results[\"results\"] if r[\"score\"] > 0.7]\n```\n\n---\n\n## 参考链接\n\n- API 文档：`src/yantrikdb/api.py`\n- 核心实现：`crates/yantrikdb-core/src/engine/`\n- 评分系统：`crates/yantrikdb-core/src/base/scoring.rs`\n\n---\n\n\n\n## 知识图谱操作\n\n### 相关页面\n\n相关主题：[记录与检索操作](#page-record-recall), [五大索引架构](#page-five-indexes)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/engine/graph_ops.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/graph_ops.rs)\n- [crates/yantrikdb-core/src/engine/graph_state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/graph_state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n \n\n# 知识图谱操作\n\n知识图谱操作是 YantrikDB 认知引擎的核心子系统，负责管理和维护实体、概念及其相互关系的有组织表示。与传统的向量检索不同，知识图谱操作提供了语义关联建模、激活传播推理和结构化推理能力，使系统能够在记忆网络中发现深层关联模式。\n\n## 架构概览\n\nYantrikDB 的知识图谱采用混合架构，结合了图结构存储与认知属性系统。每个节点携带多维度属性（置信度、激活值、显著性等），边携带类型化的语义关系和激活转移因子。\n\n```mermaid\ngraph TD\n subgraph 知识图谱层\n NK[节点Kind枚举]\n EK[边Kind枚举]\n CA[认知属性]\n PV[ Provenance 可追溯性]\n end\n \n subgraph 操作引擎\n GO[graph_ops 操作]\n GS[graph_state 状态管理]\n QR[query_dsl 查询]\n end\n \n subgraph 认知推理\n SP[surfacing 表面化]\n NT[narrative 叙事弧]\n end\n \n NK --> GO\n EK --> GO\n CA --> GO\n GO --> GS\n GS --> QR\n QR --> SP\n SP --> NT\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()\n\n## 节点类型系统\n\n知识图谱中的节点（Node）代表认知世界中的各种实体或概念。系统定义了14种节点类型，每种类型具有不同的持久化策略和默认认知属性。\n\n### 节点类型枚举\n\n| 类型标识 | 说明 | 持久化 | 典型用途 |\n|---------|------|--------|---------|\n| `entity` | 实体/对象 | 是 | 人、地点、物品 |\n| `episode` | 事件片段 | 是 | 经验记录 |\n| `belief` | 信念 | 是 | 存储的知识 |\n| `goal` | 目标 | 是 | 长期意图 |\n| `task` | 任务 | 是 | 具体行动项 |\n| `intent_hypothesis` | 意图假设 | **否** | 瞬时推理 |\n| `routine` | 行为模式 | 是 | 周期性习惯 |\n| `need` | 需求 | 是 | 动机驱动 |\n| `opportunity` | 机会 | 是 | 时间窗口性行动 |\n| `risk` | 风险 | 是 | 潜在问题 |\n| `constraint` | 约束 | 是 | 限制条件 |\n| `preference` | 偏好 | 是 | 用户选择倾向 |\n| `conversation_thread` | 对话线程 | **否** | 瞬时会话 |\n| `action_schema` | 行动模式 | 是 | 技能/流程模板 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:80-115]()\n\n### 节点类型方法\n\n节点类型提供了字符串序列化与反序列化支持：\n\n```rust\npub fn as_str(self) -> &'static str {\n match self {\n Self::Entity => \"entity\",\n Self::Episode => \"episode\",\n // ... 其他类型\n }\n}\n\npub fn from_str(s: &str) -> Option {\n match s {\n \"entity\" => Some(Self::Entity),\n // ...\n _ => None,\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:95-125]()\n\n### 节点持久化策略\n\n`is_persistent()` 方法决定了节点类型是否写入 SQLite 存储：\n\n- **持久化类型**：entity, episode, belief, goal, task, routine, need, opportunity, risk, constraint, preference, action_schema\n- **瞬时类型**：intent_hypothesis, conversation_thread（仅存在于工作集）\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:130-140]()\n\n## 边类型系统\n\n边（Edge）表示节点之间的语义关系，是激活传播和推理的基础。系统定义了17种边类型，具有不同的激活转移因子。\n\n### 边类型分类\n\n| 边类型 | 转移因子 | 说明 | 语义方向 |\n|--------|---------|------|---------|\n| `supports` | 0.7 | 支持关系 | 正向激活 |\n| `contradicts` | -0.5 | 矛盾关系 | 抑制 |\n| `causes` | 0.8 | 因果关系 | 强正向激活 |\n| `predicts` | 0.4 | 预测关系 | 中等正向 |\n| `prevents` | -0.6 | 预防关系 | 强抑制 |\n| `advances_goal` | 0.6 | 推进目标 | 正向激活 |\n| `blocks_goal` | -0.5 | 阻碍目标 | 抑制 |\n| `subtask_of` | 0.4 | 子任务归属 | 结构化 |\n| `requires` | 0.5 | 依赖关系 | 正向激活 |\n| `associated_with` | 0.3 | 关联关系 | 弱正向 |\n| `instance_of` | 0.3 | 实例关系 | 分类传播 |\n| `part_of` | 0.3 | 组成部分 | 结构传播 |\n| `similar_to` | 0.3 | 相似关系 | 类比传播 |\n| `precedes_temporally` | 0.2 | 时间先后 | 弱正向 |\n| `triggers` | 0.7 | 触发关系 | 事件激活 |\n| `prefers` | 0.3 | 偏好关系 | 倾向传播 |\n| `avoids` | -0.3 | 回避关系 | 弱抑制 |\n| `constrains` | -0.4 | 约束关系 | 限制传播 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n### 激活转移机制\n\n边的 `activation_transfer()` 方法定义了激活值如何从源节点流向目标节点：\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n Self::Supports => 0.7,\n Self::Causes => 0.8,\n Self::AdvancesGoal => 0.6,\n // ...\n }\n}\n```\n\n负值表示抑制关系，激活值会从目标节点中减去转移量。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:240-280]()\n\n## 认知属性系统\n\n每个知识图谱节点携带统一的认知属性集，包含11个维度，这些属性共同决定了节点在推理过程中的行为。\n\n### 属性维度\n\n| 属性名 | 范围 | 说明 | 默认值来源 |\n|--------|------|------|-----------|\n| `confidence` | [0.0, 1.0] | 置信度 | 类型相关 |\n| `activation` | [0.0, 1.0] | 当前激活水平 | 0.0 |\n| `salience` | [0.0, 1.0] | 显著性权重 | 类型相关 |\n| `persistence` | [0.0, 1.0] | 持久化倾向 | 类型相关 |\n| `valence` | [-1.0, 1.0] | 情感效价 | 0.0 |\n| `urgency` | [0.0, 1.0] | 紧急程度 | 0.0 |\n| `novelty` | [0.0, 1.0] | 新颖性 | 1.0 |\n| `last_updated_ms` | Unix ms | 最后更新时间 | 当前时间 |\n| `volatility` | [0.0, 1.0] | 波动率 | 0.1 |\n| `provenance` | Provenance枚举 | 信息来源 | Observed |\n| `evidence_count` | 正整数 | 证据数量 | 1 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:280-350]()\n\n### 节点类型默认属性\n\n不同节点类型具有预设的认知属性基线：\n\n| 节点类型 | 置信度 | 显著性 | 持久化 |\n|---------|--------|--------|--------|\n| Entity | 0.90 | 0.80 | 0.80 |\n| Episode | 0.80 | 0.60 | 0.70 |\n| Belief | 0.70 | 0.70 | 0.75 |\n| Goal | 0.85 | 0.90 | 0.85 |\n| Task | 0.90 | 0.70 | 0.60 |\n| Need | 0.60 | 0.70 | 0.40 |\n| Opportunity | 0.40 | 0.60 | 0.20 |\n| Risk | 0.40 | 0.70 | 0.60 |\n| Constraint | 0.90 | 0.80 | 0.95 |\n| Preference | 0.60 | 0.50 | 0.85 |\n| ConversationThread | 0.90 | 0.80 | 0.10 |\n| ActionSchema | 0.70 | 0.40 | 0.90 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:350-400]()\n\n## 信息溯源系统\n\n`Provenance` 枚举定义了知识来源的可信度等级，用于信念修正时的加权计算。\n\n### 来源类型与可靠度\n\n| 来源类型 | 可靠度 | 说明 |\n|---------|--------|------|\n| `told` | 0.95 | 用户显式声明，最信任 |\n| `observed` | 0.90 | 直接观察行为 |\n| `experimented` | 0.85 | 受控实验确认 |\n| `consolidated` | 0.80 | 多源合并 |\n| `extracted` | 0.75 | 外部文档提取，可能过时 |\n| `inferred` | 0.60 | 模式推理，中等信任 |\n| `system_default` | 0.50 | 默认值，最弱 |\n\n```rust\npub fn reliability_prior(self) -> f64 {\n match self {\n Self::Told => 0.95,\n Self::Observed => 0.90,\n Self::Experimented => 0.85,\n Self::Consolidated => 0.80,\n Self::Extracted => 0.75,\n Self::Inferred => 0.60,\n Self::SystemDefault => 0.50,\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:400-450]()\n\n## 任务与目标系统\n\n### 任务状态机\n\n`TaskStatus` 定义了任务的生命周期状态：\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: 创建\n Pending --> InProgress: 开始\n InProgress --> Completed: 完成\n InProgress --> Blocked: 阻塞\n Blocked --> InProgress: 解除阻塞\n InProgress --> Cancelled: 取消\n Pending --> Cancelled: 取消\n Completed --> [*]\n Cancelled --> [*]\n```\n\n| 状态 | 字符串标识 | 说明 |\n|------|-----------|------|\n| Pending | `pending` | 等待执行 |\n| InProgress | `in_progress` | 执行中 |\n| Completed | `completed` | 已完成 |\n| Cancelled | `cancelled` | 已取消 |\n| Blocked | `blocked` | 被阻塞 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:480-520]()\n\n### 优先级层级\n\n`Priority` 枚举定义任务的紧急程度：\n\n| 优先级 | 紧急度值 | 说明 |\n|-------|---------|------|\n| Low | 0.25 | 低优先级 |\n| Medium | 0.50 | 中优先级 |\n| High | 0.75 | 高优先级 |\n| Critical | 1.00 | 紧急/关键 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:520-550]()\n\n## 操作类型\n\n### 行动类型与成本\n\n`ActionKind` 定义了系统可能执行的操作类型及其基线成本：\n\n| 操作类型 | 字符串标识 | 基线成本 | 说明 |\n|---------|-----------|---------|------|\n| Abstain | `abstain` | 0.00 | 不行动 |\n| Inform | `inform` | 0.05 | 通知用户 |\n| Organize | `organize` | 0.10 | 组织信息 |\n| Suggest | `suggest` | 0.15 | 建议行动 |\n| Communicate | `communicate` | 0.20 | 主动沟通 |\n| Schedule | `schedule` | 0.25 | 安排日程 |\n| Warn | `warn` | 0.30 | 警告用户 |\n| Execute | `execute` | 0.35 | 执行操作 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:550-600]()\n\n## 叙事弧系统\n\n知识图谱支持叙事结构建模，用于跟踪用户生活中的长期主题和故事线。\n\n### 叙事弧状态\n\n| 状态 | 字符串标识 | 说明 |\n|------|-----------|------|\n| Emerging | `emerging` | 初检测，样本不足 |\n| Active | `active` | 活跃积累中 |\n| Paused | `paused` | 暂停，可能恢复 |\n| Resolved | `resolved` | 目标达成或自然结束 |\n| Abandoned | `abandoned` | 停止追踪 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:50-80]()\n\n### 章节类型\n\n叙事弧内的章节分为：\n\n| 类型 | 说明 |\n|------|------|\n| Setup | 初始背景设定 |\n| Rising | 构建张力或进展 |\n| Climax | 弧线峰值时刻 |\n| Falling | 峰值后收尾 |\n| Resolution | 最终结论 |\n| Interlude | 主线间的暂停或旁支 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:80-110]()\n\n## 查询与推理操作\n\n### Recall 操作参数\n\n`RecallOp` 定义了召回操作参数：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| top_k | usize | 返回结果数量 |\n| query | Option | 自然语言查询 |\n| domain | Option | 领域过滤 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:80-100]()\n\n### Think 循环操作优先级\n\n`ThinkConfig` 定义了认知循环中各操作的优先级：\n\n| 操作 | 优先级 | 说明 |\n|------|--------|------|\n| Attend | 10 | 注意力聚焦，始终执行 |\n| Recall | 9 | 上下文召回，关键 |\n| Believe | 8 | 证据整合 |\n| Compare | 7 | 行动选择 |\n| Constrain | 7 | 安全约束 |\n| Plan | 6 | 手段-目标推理 |\n| Project | 5 | 前向模拟 |\n| Anticipate | 4 | 主动预测 |\n| Assess | 3 | 元认知评估 |\n| CoherenceCheck | 2 | 一致性维护 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:100-130]()\n\n## 表面化与主动建议\n\n### 抑制原因\n\n`SuppressionReason` 枚举定义了建议被抑制的原因：\n\n| 抑制原因 | 字符串标识 |\n|---------|-----------|\n| LowReceptivity | `low_receptivity` |\n| ItemSuppressionRule | `item_suppression_rule` |\n| QuietHours | `quiet_hours` |\n| RateLimited | `rate_limited` |\n| AntiNag | `anti_nag` |\n| MaxSurfaces | `max_surfaces` |\n| TooSoon | `too_soon` |\n| NotificationModeBlock | `notification_mode_block` |\n\n资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:50-80]()\n\n## 冲突检测与解决\n\n### 冲突类型\n\n`ConflictType` 定义了记忆间的冲突类型：\n\n| 冲突类型 | 默认优先级 | 说明 |\n|---------|-----------|------|\n| IdentityFact | critical | 身份事实矛盾 |\n| Preference | high | 偏好矛盾 |\n| Temporal | high | 时间线矛盾 |\n| Consolidation | medium | 整合冲突 |\n| Minor | low | 次要冲突 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n## 使用场景\n\n### 实体关联查询\n\n当用户记录\"Alice 是工程主管\"后，系统创建实体节点，并可通过 `relate()` 建立与\"Engineering\"节点的\"leads\"关系边。\n\n### 目标驱动的任务分解\n\n目标节点通过 `subtask_of` 边连接到子任务节点，激活值从目标向下传播，自动提升相关子任务的显著性。\n\n### 偏好学习与冲突检测\n\n用户偏好通过 `Preference` 节点存储，当新记录与现有偏好矛盾时，系统检测到 `Preference` 类型的冲突并触发解决流程。\n\n### 机会与风险管理\n\n`Opportunity` 节点携带有效期和预期收益属性，`Risk` 节点携带严重程度，系统通过激活传播计算当前最需要关注的机会和风险。\n\n## 总结\n\nYantrikDB 的知识图谱操作模块提供了丰富的语义建模能力，通过14种节点类型、17种边类型和11维认知属性，构建了一个可解释、可追溯的认知表示系统。激活传播机制使系统能够基于图结构进行动态推理，表面化系统确保相关信息适时呈现，而叙事弧模块则支持长期主题的跟踪与理解。\n\n---\n\n\n\n## 认知循环与思考\n\n### 相关页面\n\n相关主题：[记录与检索操作](#page-record-recall), [冲突检测与解决](#page-conflict-detection), [主动触发系统](#page-triggers-proactive)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n- [crates/yantrikdb-core/src/cognition/narrative.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/narrative.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/engine/cognition.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/cognition.rs)\n- [crates/yantrikdb-python/src/py_engine/memory.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-python/src/py_engine/memory.rs)\n \n\n# 认知循环与思考\n\n## 概述\n\n**认知循环与思考**（Cognitive Loop and Thinking）是 YantrikDB 中负责模拟人类认知过程的核心子系统。它通过一系列认知操作符（cognitive operators）驱动记忆激活、信念更新、推理规划和主动建议等高级认知功能。该系统基于\"工作集\"（working set）机制运行，将持久化的图结构数据转换为动态激活的认知空间，从而实现上下文感知和目标导向的智能行为。\n\n认知循环的核心目标是：\n\n- **上下文感知**：根据当前情境选择性地激活相关记忆节点\n- **信念维护**：整合新证据并解决认知冲突\n- **目标驱动**：通过规划和预测推进用户目标\n- **主动交互**：在适当时机向用户推送相关建议\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 系统架构\n\n### 核心组件\n\nYantrikDB 的认知系统由以下核心组件构成：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **CognitiveOperator** | 定义认知操作符枚举，封装认知原语 | query_dsl.rs |\n| **YantrikExecutor** | 执行认知操作符的核心引擎 | engine/cognition.rs |\n| **WorkingSet** | 工作集管理，维护激活状态的节点子集 | engine/cognition.rs |\n| **CognitiveAttrs** | 认知属性集，定义节点的动态特征 | state.rs |\n| **SurfaceEngine** | 主动建议生成与推送 | surfacing.rs |\n\n### 认知操作符体系\n\n认知操作符是认知循环的基本执行单元，按优先级从高到低排列：\n\n| 优先级 | 操作符 | 功能描述 | 源码位置 |\n|:------:|--------|----------|----------|\n| 10 | **Attend** | 注意力聚焦，选择性激活相关节点 | query_dsl.rs |\n| 9 | **Recall** | 记忆召回，从持久存储检索相关信息 | query_dsl.rs |\n| 8 | **Believe** | 信念整合，整合新证据更新信念 | query_dsl.rs |\n| 7 | **Compare** | 方案比较，评估候选行动的效用 | query_dsl.rs |\n| 7 | **Constrain** | 约束满足，应用安全与业务约束 | query_dsl.rs |\n| 6 | **Plan** | 计划生成，means-ends 规划 | query_dsl.rs |\n| 5 | **Project** | 前景预测，前向模拟结果 | query_dsl.rs |\n| 4 | **Anticipate** | 主动预判，预测未来需求 | query_dsl.rs |\n| 3 | **Assess** | 元认知评估，评估系统状态 | query_dsl.rs |\n| 2 | **CoherenceCheck** | 一致性检查，维护认知连贯性 | query_dsl.rs |\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 认知节点类型\n\n### NodeKind 枚举\n\n系统定义了 15 种认知节点类型，每种类型具有不同的持久化策略和认知特性：\n\n```mermaid\ngraph TD\n A[NodeKind 节点类型] --> B[Entity 实体]\n A --> C[Episode 事件]\n A --> D[Belief 信念]\n A --> E[Goal 目标]\n A --> F[Task 任务]\n A --> G[IntentHypothesis 意图假设]\n A --> H[Routine 习惯]\n A --> I[Need 需求]\n A --> J[Opportunity 机会]\n A --> K[Risk 风险]\n A --> L[Constraint 约束]\n A --> M[Preference 偏好]\n A --> N[ConversationThread 对话线程]\n A --> O[ActionSchema 行动模式]\n \n G -.->|瞬态节点| P[不持久化到SQLite]\n N -.->|瞬态节点| P\n```\n\n### 节点类型特性表\n\n| 节点类型 | 持久化 | 默认置信度 | 激活率 | 显著性 | 典型用途 |\n|----------|:------:|:----------:|:------:|:------:|----------|\n| Entity | ✓ | 0.90 | 0.80 | 0.90 | 实体概念建模 |\n| Episode | ✓ | 0.70 | 0.60 | 0.50 | 事件记忆存储 |\n| Belief | ✓ | 0.65 | 0.70 | 0.70 | 信念状态管理 |\n| Goal | ✓ | 0.80 | 0.90 | 0.80 | 目标追踪 |\n| Task | ✓ | 0.85 | 0.70 | 0.70 | 任务执行管理 |\n| IntentHypothesis | ✗ | 0.60 | 0.70 | 0.50 | 意图识别（瞬态） |\n| Routine | ✓ | 0.75 | 0.60 | 0.40 | 习惯模式识别 |\n| Need | ✓ | 0.60 | 0.70 | 0.40 | 需求状态 |\n| Opportunity | ✓ | 0.40 | 0.60 | 0.20 | 机会识别 |\n| Risk | ✓ | 0.40 | 0.70 | 0.60 | 风险评估 |\n| Constraint | ✓ | 0.90 | 0.80 | 0.95 | 安全/业务约束 |\n| Preference | ✓ | 0.60 | 0.50 | 0.85 | 用户偏好 |\n| ConversationThread | ✗ | 0.90 | 0.80 | 0.10 | 对话上下文（瞬态） |\n| ActionSchema | ✓ | 0.70 | 0.40 | 0.90 | 行动模式库 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:200-250]()\n\n---\n\n## 认知属性系统\n\n### CognitiveAttrs 结构\n\n每个认知节点携带一组动态属性，这些属性控制节点在认知循环中的行为：\n\n```rust\npub struct CognitiveAttrs {\n pub confidence: f64, // 置信度 [0.0, 1.0]\n pub activation: f64, // 激活水平 [0.0, 1.0]\n pub salience: f64, // 显著性 [0.0, 1.0]\n pub persistence: f64, // 持久性 [0.0, 1.0]\n pub valence: f64, // 情感效价 [-1.0, 1.0]\n pub urgency: f64, // 紧迫性 [0.0, 1.0]\n pub novelty: f64, // 新颖性 [0.0, 1.0]\n pub last_updated_ms: u64, // 上次更新时间戳\n pub volatility: f64, // 波动性 [0.0, 1.0]\n pub provenance: Provenance, // 信息来源\n pub evidence_count: u32, // 证据数量\n}\n```\n\n### 属性值范围\n\n| 属性 | 范围 | 含义 |\n|------|------|------|\n| confidence | [0.0, 1.0] | 节点内容的可信程度 |\n| activation | [0.0, 1.0] | 当前激活水平，影响检索优先级 |\n| salience | [0.0, 1.0] | 固有显著性，不随时间衰减 |\n| persistence | [0.0, 1.0] | 记忆持久化倾向 |\n| valence | [-1.0, 1.0] | 情感效价，负值为负面，正值为正面 |\n| urgency | [0.0, 1.0] | 时间敏感性 |\n| novelty | [0.0, 1.0] | 与已知信息的差异程度 |\n| volatility | [0.0, 1.0] | 值随时间的波动程度 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:250-280]()\n\n---\n\n## 边类型与激活传播\n\n### EdgeKind 枚举\n\n认知节点之间通过带类型的边连接，边的类型决定了激活传播的方式：\n\n| 边类型 | 激活转移因子 | 语义 |\n|--------|:------------:|------|\n| **Supports** | 0.7 | 支持关系 |\n| **Contradicts** | -0.6 | 矛盾关系 |\n| **Causes** | 0.8 | 因果关系 |\n| **Predicts** | 0.4 | 预测关系 |\n| **Prevents** | -0.7 | 阻止关系 |\n| **AdvancesGoal** | 0.6 | 推进目标 |\n| **BlocksGoal** | -0.5 | 阻碍目标 |\n| **SubtaskOf** | 0.4 | 子任务关系 |\n| **Requires** | 0.5 | 依赖关系 |\n| **AssociatedWith** | 0.3 | 关联关系 |\n| **InstanceOf** | 0.3 | 实例关系 |\n| **PartOf** | 0.3 | 部分关系 |\n| **SimilarTo** | 0.3 | 相似关系 |\n| **PrecedesTemporally** | 0.2 | 时间先后 |\n| **Triggers** | 0.7 | 触发关系 |\n| **Prefers** | 0.3 | 偏好关系 |\n| **Avoids** | -0.4 | 回避关系 |\n| **Constrains** | -0.5 | 约束关系 |\n\n### 激活传播机制\n\n激活传播基于**扩散激活模型**（Spreading Activation Model）：\n\n```mermaid\ngraph LR\n A[种子节点] -->|activate_and_spread| B[相邻节点]\n B -->|继续传播| C[二级相邻节点]\n C -->|衰减| D[三级相邻节点]\n \n A -->|激活+0.3| A\n B -->|因子×边类型| B\n C -->|因子×0.5| C\n D -->|因子×0.25| D\n```\n\n**关键参数**：\n\n- 初始激活增量：0.3\n- 传播衰减因子：由 `EdgeKind::activation_transfer()` 定义\n- 负值边表示抑制传播\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n---\n\n## 认知操作符详解\n\n### Attend（注意力聚焦）\n\n**功能**：选择性聚焦于特定节点并激活相关上下文。\n\n```rust\npub struct AttendOp {\n pub seeds: Vec, // 种子节点列表\n pub max_hops: u32, // 最大传播跳数\n pub decay: f64, // 衰减系数\n}\n```\n\n**执行流程**：\n\n1. 从种子节点开始\n2. 按 `max_hops` 限制进行激活传播\n3. 应用 `decay` 衰减系数\n4. 返回激活节点数量和 Top-N 激活节点\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:50-60]()\n\n### Recall（记忆召回）\n\n**功能**：从持久存储中检索与查询相关的记忆。\n\n```rust\npub struct RecallOp {\n pub top_k: usize, // 返回 top_k 结果\n pub query: Option, // 自然语言查询\n pub domain: Option, // 限定领域\n}\n```\n\n**召回参数**：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| top_k | usize | 返回结果数量上限 |\n| query | Option | 自然语言描述的查询 |\n| embedding | Option> | 向量嵌入（可替代 query） |\n| memory_type | Option | 记忆类型过滤 |\n| namespace | Option | 命名空间过滤 |\n| time_window | Option<(f64, f64)> | 时间窗口过滤 |\n\n资料来源：[crates/yantrikdb-core/src/engine/cognition.rs:1-50]()\n\n### Believe（信念整合）\n\n**功能**：将新证据整合到信念系统中，解决认知冲突。\n\n```rust\npub struct BelieveOp {\n pub evidence: EvidenceInput,\n}\n\npub struct EvidenceInput {\n pub target: Option, // 目标信念节点\n pub observation: String, // 观察描述\n pub direction: f64, // 方向：positive=确认，negative=矛盾\n}\n```\n\n**证据可靠性优先级**：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|:----------:|------|\n| Told | 0.95 | 用户明确陈述 |\n| Observed | 0.90 | 直接观察行为 |\n| Experimented | 0.85 | 控制实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取 |\n| Inferred | 0.60 | 模式推断 |\n| SystemDefault | 0.50 | 系统默认值 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:220-240]()\n\n### Plan（计划生成）\n\n基于 means-ends 推理的目标分解，调用子任务生成和约束满足机制。\n\n### Project（前景预测）\n\n前向模拟行动结果，评估不同行动路径的预期收益。\n\n### Compare（方案比较）\n\n评估候选行动的效用，考虑收益、成本和风险。\n\n### Constrain（约束满足）\n\n应用安全和业务约束，确保行动符合用户设定的限制。\n\n### Anticipate（主动预判）\n\n基于模式和趋势预测未来需求和机会。\n\n### Assess（元认知评估）\n\n评估当前认知状态的质量和效率。\n\n### CoherenceCheck（一致性检查）\n\n检测和修复认知冲突，维护信念系统的连贯性。\n\n资料来源：[crates/yantrikdb-core/src/cognition/query_dsl.rs:1-30]()\n\n---\n\n## 行动系统\n\n### ActionKind 枚举\n\n定义了系统可执行的基本行动类型：\n\n| 行动类型 | 基础成本 | 说明 |\n|----------|:--------:|------|\n| Abstain | 0.00 | 无行动 |\n| Inform | 0.05 | 信息告知 |\n| Organize | 0.10 | 组织整理 |\n| Suggest | 0.15 | 主动建议 |\n| Communicate | 0.20 | 沟通交流 |\n| Schedule | 0.25 | 日程安排 |\n| Warn | 0.30 | 风险警告 |\n| Execute | 0.35 | 直接执行 |\n\n**基础成本**用于效用计算，较高成本意味着对用户更大的干扰。\n\n### TaskStatus 任务状态\n\n| 状态 | 字符串表示 | 说明 |\n|------|------------|------|\n| Pending | \"pending\" | 待处理 |\n| InProgress | \"in_progress\" | 进行中 |\n| Completed | \"completed\" | 已完成 |\n| Cancelled | \"cancelled\" | 已取消 |\n| Blocked | \"blocked\" | 被阻塞 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:80-120]()\n\n---\n\n## 优先级系统\n\n### Priority 枚举\n\n| 优先级 | 字符串 | 紧急度值 | 说明 |\n|--------|--------|:--------:|------|\n| Low | \"low\" | 0.25 | 低优先级 |\n| Medium | \"medium\" | 0.50 | 中优先级 |\n| High | \"high\" | 0.75 | 高优先级 |\n| Critical | \"critical\" | 1.00 | 紧急 |\n\n### 冲突类型与默认优先级\n\n| 冲突类型 | 默认优先级 | 说明 |\n|----------|------------|------|\n| IdentityFact | \"critical\" | 身份事实冲突 |\n| Preference | \"high\" | 偏好冲突 |\n| Temporal | \"high\" | 时间冲突 |\n| Consolidation | \"medium\" | 合并冲突 |\n| Minor | \"low\" | 轻微冲突 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n---\n\n## 叙事与故事弧系统\n\n### ArcStatus 生命周期状态\n\n| 状态 | 说明 |\n|------|------|\n| Emerging | 新检测到，证据不足 |\n| Active | 活跃积累事件中 |\n| Paused | 暂停，可能恢复 |\n| Resolved | 目标达成或故事结束 |\n| Abandoned | 用户或系统决定停止追踪 |\n\n### ChapterType 章节类型\n\n| 类型 | 说明 |\n|------|------|\n| Setup | 初始上下文设置 |\n| Rising | 紧张感建立或进展中 |\n| Climax | 弧的高峰时刻 |\n| Falling | 高峰后回落 |\n| Resolution | 最终结论 |\n| Interlude | 主线间的插曲 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/narrative.rs:1-50]()\n\n---\n\n## 用户接受度系统\n\n### ActivityState 用户活动状态\n\n系统通过感知用户当前活动状态来调整交互策略：\n\n| 状态 | 中断成本 | 接收度 | 适用场景 |\n|------|:--------:|:------:|----------|\n| Idle | 0.15 | 0.85 | 空闲状态 |\n| JustReturned | 0.25 | 0.75 | 刚返回 |\n| Browsing | 0.35 | 0.65 | 浏览中 |\n| Communicating | 0.45 | 0.55 | 沟通中 |\n| TaskSwitching | 0.65 | 0.45 | 任务切换中 |\n| FocusedWork | 0.85 | 0.25 | 专注工作 |\n| DeepFocus | 0.95 | 0.05 | 深度专注 |\n\n### NotificationMode 通知模式\n\n| 模式 | 说明 |\n|------|------|\n| All | 允许所有通知 |\n| ImportantOnly | 仅重要通知 |\n| DoNotDisturb | 完全静音 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/receptivity.rs:1-50]()\n\n---\n\n## 主动建议系统\n\n### SurfaceMode 展示模式\n\n| 模式 | 说明 |\n|------|------|\n| Ambient | 环境感知，轻量提示 |\n| Prominent | 醒目展示，需要注意 |\n| Interrupt | 打断式，需立即响应 |\n\n### SurfaceReason 展示原因\n\n| 原因 | 说明 |\n|------|------|\n| Opportunity | 识别到新机会 |\n| DeadlineApproaching | 截止日期临近 |\n| GoalProgress | 目标进展更新 |\n| PatternDetected | 检测到用户模式 |\n| ConflictDetected | 检测到冲突 |\n| SystemInitiated | 系统主动发起 |\n\n### 抑制规则\n\n| 规则 | 说明 |\n|------|------|\n| LowReceptivity | 用户接受度低 |\n| ItemSuppressionRule | 特定项目被抑制 |\n| QuietHours | 安静时段 |\n| RateLimited | 频率限制 |\n| AntiNag | 防打扰机制 |\n| MaxSurfaces | 达到最大展示次数 |\n| TooSoon | 展示间隔太短 |\n| NotificationModeBlock | 通知模式阻止 |\n\n资料来源：[crates/yantrikdb-core/src/cognition/surfacing.rs:1-80]()\n\n---\n\n## 触发器系统\n\n### TriggerType 触发器类型\n\n| 触发类型 | 默认冷却时间 | 默认过期时间 |\n|----------|:------------:|:------------:|\n| DecayReview | 3天 | 7天 |\n| ConsolidationReady | 1天 | 3天 |\n| ConflictEscalation | 2天 | 14天 |\n| TemporalDrift | 14天 | 7天 |\n| Redundancy | 1天 | 7天 |\n| RelationshipInsight | 7天 | 7天 |\n| ValenceTrend | 7天 | 7天 |\n| EntityAnomaly | 7天 | 7天 |\n| PatternDiscovered | 7天 | 7天 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:100-130]()\n\n---\n\n## ThinkConfig 配置\n\n```rust\npub struct ThinkConfig {\n pub importance_threshold: f64, // 重要性阈值\n pub decay_threshold: f64, // 衰减阈值\n pub max_triggers: usize, // 最大触发数\n}\n```\n\n**配置参数说明**：\n\n| 参数 | 说明 | 典型值 |\n|------|------|--------|\n| importance_threshold | 节点被视为重要的最低阈值 | 0.5-0.7 |\n| decay_threshold | 触发衰减审查的阈值 | 0.2-0.4 |\n| max_triggers | 单次思考循环的最大触发数 | 10-20 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:140-150]()\n\n---\n\n## 执行流程\n\n### 认知循环执行管道\n\n```mermaid\ngraph TD\n A[ThinkConfig 配置] --> B[按优先级排序操作符]\n B --> C{操作符队列}\n \n C -->|Attend| D[激活种子节点]\n D --> E[扩散激活传播]\n E --> F[更新 WorkingSet]\n \n C -->|Recall| G[检索相关记忆]\n G --> H[构建候选集合]\n \n C -->|Believe| I[整合新证据]\n I --> J{检测冲突?}\n J -->|是| K[触发冲突解决]\n J -->|否| L[更新信念置信度]\n \n C -->|Plan| M[目标分解]\n M --> N[生成子任务图]\n \n C -->|Project| O[前向模拟]\n O --> P[计算预期收益]\n \n C -->|Compare| Q[评估候选行动]\n Q --> R[计算效用函数]\n \n C -->|Constrain| S[应用约束]\n S --> T[过滤非法行动]\n \n C -->|Anticipate| U[预测未来]\n U --> V[生成预判结果]\n \n C -->|Assess| W[元认知评估]\n W --> X[输出状态报告]\n \n C -->|CoherenceCheck| Y[一致性检查]\n Y --> Z{发现冲突?}\n Z -->|是| AA[标记冲突节点]\n Z -->|否| AB[结束检查]\n \n F --> AC[合并结果]\n H --> AC\n L --> AC\n N --> AC\n P --> AC\n R --> AC\n T --> AC\n V --> AC\n X --> AC\n AB --> AC\n \n AC --> AD[SurfaceEngine]\n AD --> AE[ProactiveSuggestion]\n```\n\n### 核心执行器实现\n\n```rust\nimpl<'a> YantrikExecutor<'a> {\n fn execute_attend(&self, op: &AttendOp) -> StepOutput {\n match self.db.hydrate_working_set(self.attention_config.clone()) {\n Ok(mut ws) => {\n let mut activated = 0;\n let mut top = Vec::new();\n \n // 激活种子节点\n for &seed in &op.seeds {\n if let Some(node) = ws.get_mut(seed) {\n let new_activation = (node.attrs.activation + 0.3).min(1.0);\n node.attrs.activation = new_activation;\n top.push((seed, new_activation));\n activated += 1;\n }\n }\n \n // 扩散激活\n for &seed in &op.seeds {\n activated += ws.activate_and_spread(seed, 0.3);\n }\n \n StepOutput::Attend {\n nodes_activated: activated,\n top_activated: top,\n }\n }\n Err(e) => StepOutput::Error {\n message: format!(\"Attend failed: {}\", e),\n },\n }\n }\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/cognition.rs:50-100]()\n\n---\n\n## Python 接口\n\n### Memory.query() 方法\n\nPython SDK 提供了认知查询的便捷接口：\n\n```python\ndef query(\n query: Optional[str] = None,\n embedding: Optional[List[float]] = None,\n top_k: int = 10,\n memory_type: Optional[str] = None,\n namespace: Optional[str] = None,\n time_window: Optional[Tuple[float, float]] = None,\n expand_entities: bool = False,\n include_consolidated: bool = False,\n skip_reinforce: bool = False,\n domain: Optional[str] = None,\n source: Optional[str] = None,\n) -> List[PyObject]\n```\n\n**参数说明**：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | Optional[str] | None | 自然语言查询 |\n| embedding | Optional[List[float]] | None | 向量嵌入 |\n| top_k | int | 10 | 返回结果数 |\n| memory_type | Optional[str] | None | 记忆类型过滤 |\n| namespace | Optional[str] | None | 命名空间 |\n| time_window | Optional[Tuple[float, float]] | None | 时间窗口 (start, end) |\n| expand_entities | bool | False | 展开关联实体 |\n| include_consolidated | bool | False | 包含已合并记忆 |\n| skip_reinforce | bool | False | 跳过强化学习 |\n| domain | Optional[str] | None | 领域过滤 |\n| source | Optional[str] | None | 来源过滤 |\n\n资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:50-100]()\n\n---\n\n## 工作集管理\n\n### WorkingSet 工作机制\n\n工作集是认知循环的核心数据结构，它：\n\n1. **从 SQLite 加载活跃节点**：根据 `AttentionConfig` 过滤高激活/高显著性节点\n2. **维护激活状态**：所有计算在工作集内完成，不直接修改持久存储\n3. **支持激活扩散**：基于边类型进行激活传播\n4. **惰性同步**：修改通过批处理同步回 SQLite\n\n### Hydration 流程\n\n```mermaid\ngraph LR\n A[SQLite 持久存储] -->|SELECT| B[候选节点集]\n B -->|按阈值过滤| C[WorkingSet]\n C -->|激活扩散| D[激活图]\n D -->|惰性同步| A\n```\n\n资料来源：[crates/yantrikdb-core/src/engine/lifecycle.rs:1-50]()\n\n---\n\n## 总结\n\nYantrikDB 的认知循环与思考系统是一个复杂但层次分明的认知架构，其核心特点包括：\n\n1. **操作符驱动的管道**：通过优先级排序的认知操作符序列实现结构化推理\n2. **工作集抽象**：平衡了计算效率和持久化一致性\n3. **激活传播模型**：基于边类型的扩散激活实现了上下文敏感的检索\n4. **多维属性系统**：通过置信度、显著性、紧迫性等属性控制节点行为\n5. **主动建议引擎**：结合用户接受度和场景感知生成适时建议\n6. **叙事支持**：通过故事弧和章节机制维护长时程上下文\n\n该系统设计遵循认知科学原理，同时针对实际应用场景进行了工程优化，为构建智能个人助理提供了坚实的认知基础。\n\n---\n\n\n\n## 冲突检测与解决\n\n### 相关页面\n\n相关主题：[认知循环与思考](#page-cognitive-loop), [主动触发系统](#page-triggers-proactive)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/cognition/contradiction.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/contradiction.rs)\n- [crates/yantrikdb-core/src/engine/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/conflict.rs)\n- [crates/yantrikdb-core/src/distributed/conflict.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/distributed/conflict.rs)\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n \n\n# 冲突检测与解决\n\n## 概述\n\n冲突检测与解决（Conflict Detection and Resolution）是 yantrikdb 认知引擎的核心子系统之一，负责识别、管理和解决记忆网络中的矛盾与不一致。该系统涵盖三个层次：\n\n1. **认知层冲突** (`cognition/contradiction.rs`) - 处理信念、意图、偏好之间的逻辑矛盾\n2. **引擎层冲突** (`engine/conflict.rs`) - 管理记忆存储和检索过程中的冲突\n3. **分布式冲突** (`distributed/conflict.rs`) - 处理多节点复制环境下的冲突\n\n系统的设计目标是在保持记忆完整性的同时，智能地检测、评估和解决各种类型的冲突，确保认知代理基于一致的信息进行决策。\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:1-50]()\n\n## 冲突类型体系\n\nyantrikdb 定义了完整的冲突类型层次结构，每种类型都有对应的优先级和处理策略。\n\n### 冲突类型枚举\n\n| 类型 | 标识符 | 默认优先级 | 说明 |\n|------|--------|-----------|------|\n| 身份事实冲突 | `identity_fact` | critical（关键） | 关于实体核心属性的根本性矛盾 |\n| 偏好冲突 | `preference` | high（高） | 用户偏好陈述之间的不一致 |\n| 时间冲突 | `temporal` | high（高） | 时间线或时序信息的矛盾 |\n| 整合冲突 | `consolidation` | medium（中） | 记忆整合过程中的冲突 |\n| 次要冲突 | `minor` | low（低） | 其他轻微的不一致 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:1-30]()\n\n### 冲突数据模型\n\n```rust\npub struct Conflict {\n pub conflict_id: String,\n pub conflict_type: String,\n pub priority: String,\n pub status: String,\n pub memory_a: String,\n pub memory_b: String,\n pub entity: Option,\n pub rel_type: Option,\n pub detected_at: f64,\n pub detected_by: String,\n pub detection_reason: String,\n pub resolved_at: Option,\n pub resolved_by: Option,\n pub strategy: Option,\n pub winner_rid: Option,\n pub resolution_note: Option,\n}\n```\n\n该模型记录了冲突的完整生命周期：\n\n- **检测阶段**：记录冲突ID、类型、优先级、涉及的双方记忆（`memory_a`/`memory_b`）、检测时间和检测原因\n- **解决阶段**：记录解决策略、获胜方（`winner_rid`）、解决者和解决时间\n- **元数据**：关联的实体（`entity`）和关系类型（`rel_type`）用于上下文追踪\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:50-80]()\n\n## 认知层冲突检测\n\n### 矛盾检测器\n\n认知层的矛盾检测器负责识别信念、意图和偏好之间的逻辑矛盾。\n\n```mermaid\ngraph TD\n A[新证据输入] --> B{证据分析}\n B --> C[与现有信念比较]\n C --> D{存在矛盾?}\n D -->|是| E[创建矛盾节点]\n D -->|否| F[更新信念置信度]\n E --> G[冲突分类]\n G --> H[优先级评估]\n H --> I[进入待解决队列]\n```\n\n矛盾检测器通过以下方式工作：\n\n1. **证据收集**：接收来自观察、推断或外部来源的新证据\n2. **相似性检查**：与现有信念进行特征向量比较\n3. **矛盾识别**：使用激活传播算法检测负向关联边\n4. **分类与优先级**：根据冲突类型分配优先级\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-100]()\n\n### 关系类型与激活传播\n\n冲突检测与边类型紧密相关。以下边类型可能指示潜在的矛盾：\n\n| 边类型 | 激活转移值 | 冲突关联 |\n|--------|-----------|----------|\n| `contradicts` | -0.8 | 直接矛盾 |\n| `contradicts` | -0.8 | 核心否定关系 |\n| `supports` | 0.7 | 相互支持 |\n| `predicts` | 0.4 | 预测关系 |\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n Self::Contradicts => -0.8, // 强负向转移 = 冲突指示\n Self::Supports => 0.7,\n Self::Predicts => 0.4,\n // ...\n }\n}\n```\n\n负向激活转移值（如 -0.8）表示该边会抑制目标节点，这正是矛盾检测的核心机制。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:1-50]()\n\n## 引擎层冲突处理\n\n### 冲突解决策略\n\n引擎层的冲突解决器实现了多种策略来处理存储和检索层面的冲突：\n\n| 策略 | 适用场景 | 说明 |\n|------|---------|------|\n| `timestamp_wins` | 时间敏感数据 | 以最新时间戳为准 |\n| `priority_wins` | 重要性数据 | 以优先级高者为准 |\n| `merge` | 可整合数据 | 合并而非覆盖 |\n| `user_decides` | 需人工判断 | 保留供用户选择 |\n\n```rust\npub struct ConflictResolutionResult {\n pub conflict_id: String,\n pub resolution_strategy: String,\n pub winner_rid: String,\n pub loser_rid: String,\n pub resolved_at: f64,\n}\n```\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:80-100]()\n\n### 认知属性与冲突敏感性\n\n不同的认知节点类型对冲突的敏感度不同：\n\n| 节点类型 | 置信度基线 | 显著性基线 | 持久性基线 |\n|----------|-----------|-----------|-----------|\n| Constraint | 0.90 | 0.80 | 0.95 |\n| Preference | 0.60 | 0.50 | 0.85 |\n| Belief | 0.75 | 0.60 | 0.70 |\n| IntentHypothesis | 0.40 | 0.50 | 0.10 |\n\n约束节点（Constraint）具有最高的置信度和持久性，表明它们最难被冲突推翻；而意图假设（IntentHypothesis）则最容易被新证据更新。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:100-150]()\n\n## 分布式冲突处理\n\n### 多节点复制冲突\n\n在分布式环境中，冲突检测与解决需要考虑网络分区和并发写入：\n\n```mermaid\ngraph LR\n A[节点 A 写入] --> C{冲突检测}\n B[节点 B 写入] --> C\n C --> D[生成冲突记录]\n D --> E[广播到集群]\n E --> F[一致性解决]\n F --> G[同步状态]\n```\n\n### HLC 时钟冲突\n\nyantrikdb 使用混合逻辑时钟（HLC）处理分布式时序：\n\n```rust\npub struct OpLogEntry {\n pub op_id: String,\n pub op_type: String,\n pub timestamp: f64,\n pub target_rid: String,\n pub payload: String,\n pub actor_id: String,\n pub hlc: Vec,\n pub embedding_hash: String,\n pub origin_actor: String,\n}\n```\n\n`extract_ops_since` 函数用于从指定时间点提取后续操作，实现增量同步和冲突检测：\n\n```rust\nfn extract_ops_since(\n &self,\n since_hlc: Option>,\n since_op_id: Option<&str>,\n exclude_actor: Option<&str>,\n limit: usize,\n) -> PyResult>\n```\n\n资料来源：[crates/yantrikdb-python/src/py_engine/sync.rs:1-50]()\n\n## 工作流程\n\n### 完整冲突处理流程\n\n```mermaid\ngraph TD\n A[冲突检测] --> B[冲突分类]\n B --> C{优先级评估}\n C -->|Critical| D[立即处理]\n C -->|High| E[队列优先处理]\n C -->|Medium| F[批量处理]\n C -->|Low| G[延迟处理]\n D --> H[应用解决策略]\n E --> H\n F --> H\n G --> H\n H --> I[更新记忆状态]\n I --> J[记录解决历史]\n J --> K[传播激活更新]\n```\n\n### 一致性检查\n\n认知引擎定期执行一致性检查：\n\n```rust\nCognitiveOperator::CoherenceCheck => self.execute_coherence()\n```\n\n一致性检查评估：\n\n- 激活分数（Coherence Score）\n- 冲突数量\n- 陈旧节点数量\n- 系统整体健康状态\n\n资料来源：[crates/yantrikdb-core/src/engine/query_dsl.rs:1-30]()\n\n## 配置参数\n\n### 冲突处理配置\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `importance_threshold` | f64 | - | 重要性阈值 |\n| `decay_threshold` | f64 | - | 衰减阈值 |\n| `max_triggers` | usize | - | 最大触发器数 |\n\n### 触发器冷却与过期\n\n| 触发类型 | 冷却时间（秒） | 过期时间（秒） |\n|----------|---------------|---------------|\n| DecayReview | 3天 | 7天 |\n| ConsolidationReady | 1天 | 3天 |\n| ConflictEscalation | 2天 | 14天 |\n| Redundancy | 1天 | 7天 |\n| PatternDiscovered | 7天 | 7天 |\n\n资料来源：[crates/yantrikdb-core/src/base/types.rs:100-150]()\n\n## 可靠性先验\n\n冲突检测的可靠性与信息来源相关：\n\n| 来源类型 | 可靠性先验 | 说明 |\n|----------|-----------|------|\n| Told | 0.95 | 用户明确陈述 - 最高信任 |\n| Observed | 0.90 | 直接观察行为 |\n| Experimented | 0.85 | 通过实验确认 |\n| Consolidated | 0.80 | 多源合并 |\n| Extracted | 0.75 | 外部文档提取 |\n| Inferred | 0.60 | 模式推断 - 中等信任 |\n| SystemDefault | 0.50 | 默认值 - 最弱 |\n\n这些先验值在冲突解决时作为置信度计算的乘数因子。\n\n资料来源：[crates/yantrikdb-core/src/cognition/state.rs:150-200]()\n\n## API 接口\n\n### Python 绑定\n\n```python\n# 查询冲突历史\nconflicts = db.query_conflicts(\n status=\"unresolved\",\n priority=\"high\",\n limit=10\n)\n\n# 手动解决冲突\nresult = db.resolve_conflict(\n conflict_id=\"cf_xxx\",\n strategy=\"timestamp_wins\",\n winner_rid=\"mem_yyy\"\n)\n```\n\n资料来源：[crates/yantrikdb-python/src/py_engine/memory.rs:1-50]()\n\n## 总结\n\nyantrikdb 的冲突检测与解决系统采用了多层次、策略化的设计：\n\n1. **认知层** 通过激活传播和关系类型识别逻辑矛盾\n2. **引擎层** 实现多种解决策略，基于节点属性和冲突类型做出决策\n3. **分布式层** 使用 HLC 时钟和操作日志处理网络分区\n\n系统的核心设计原则是最小化对用户的干扰，同时确保记忆网络的一致性和可靠性。\n\n---\n\n\n\n## 主动触发系统\n\n### 相关页面\n\n相关主题：[认知循环与思考](#page-cognitive-loop), [冲突检测与解决](#page-conflict-detection)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [crates/yantrikdb-core/src/base/types.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n- [crates/yantrikdb-core/src/cognition/surfacing.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n- [crates/yantrikdb-core/src/cognition/state.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n- [crates/yantrikdb-core/src/cognition/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n- [crates/yantrikdb-core/src/cognition/receptivity.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n- [crates/yantrikdb-core/src/engine/query_dsl.rs](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/engine/query_dsl.rs)\n \n\n# 主动触发系统\n\n## 概述\n\n主动触发系统（Active Trigger System）是 yantrikdb 认知引擎的核心组件，负责监控记忆状态变化、检测模式并在适当时机主动发起认知操作。该系统基于预定义的触发类型（TriggerType）驱动认知循环（think loop），实现记忆衰减审查、冲突检测、模式发现等智能功能。\n\n触发系统的设计遵循事件驱动架构，通过冷却时间（cooldown）和过期时间（expiry）机制防止触发器过度激活，确保系统在用户可接受的频率下运行。\n\n## 触发类型体系\n\n### 触发类型枚举\n\n系统定义了 9 种触发类型，每种类型对应不同的认知需求场景：\n\n| 触发类型 | 描述 | 默认冷却时间 | 默认过期时间 | 资料来源 |\n|---------|------|-------------|-------------|---------|\n| `DecayReview` | 记忆衰减审查 | 3 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ConsolidationReady` | 记忆整合就绪 | 1 天 | 3 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ConflictEscalation` | 冲突升级检测 | 2 天 | 14 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `TemporalDrift` | 时间漂移检测 | 14 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `Redundancy` | 冗余检测 | 1 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `RelationshipInsight` | 关系洞察 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `ValenceTrend` | 情感趋势分析 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `EntityAnomaly` | 实体异常检测 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n| `PatternDiscovered` | 模式发现 | 7 天 | 7 天 | [types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs) |\n\n### 类型字符串映射\n\n每种触发类型支持与字符串的双向转换，便于序列化和配置管理：\n\n```rust\nimpl TriggerType {\n pub fn as_str(self) -> &'static str {\n match self {\n TriggerType::DecayReview => \"decay_review\",\n TriggerType::ConsolidationReady => \"consolidation_ready\",\n TriggerType::ConflictEscalation => \"conflict_escalation\",\n TriggerType::TemporalDrift => \"temporal_drift\",\n TriggerType::Redundancy => \"redundancy\",\n TriggerType::RelationshipInsight => \"relationship_insight\",\n TriggerType::ValenceTrend => \"valence_trend\",\n TriggerType::EntityAnomaly => \"entity_anomaly\",\n TriggerType::PatternDiscovered => \"pattern_discovered\",\n }\n }\n\n pub fn from_str(s: &str) -> Self {\n match s {\n \"decay_review\" => TriggerType::DecayReview,\n \"consolidation_ready\" => TriggerType::ConsolidationReady,\n // ... 其他映射\n _ => TriggerType::DecayReview,\n }\n }\n}\n```\n\n资料来源：[types.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/base/types.rs)\n\n## 触发配置\n\n### ThinkConfig 配置结构\n\n触发系统通过 `ThinkConfig` 结构体进行配置：\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| `importance_threshold` | f64 | 重要性阈值，决定哪些记忆值得触发 |\n| `decay_threshold` | f64 | 衰减阈值，用于判断记忆是否需要审查 |\n| `max_triggers` | - | 单次触发循环中允许的最大触发数量 |\n\n### 认知运算符优先级\n\n触发系统与认知运算符协同工作，不同运算符具有不同的优先级：\n\n```rust\nimpl CognitiveOperator {\n pub fn priority(self) -> usize {\n match self {\n Self::Attend(_) => 10, // 基础 - 始终运行\n Self::Recall(_) => 9, // 关键 - 上下文必需\n Self::Believe(_) => 8, // 证据整合\n Self::Compare(_) => 7, // 行动选择\n Self::Constrain(_) => 7, // 安全 - 比较时必须运行\n Self::Plan(_) => 6, // 手段-目的推理\n Self::Project(_) => 5, // 前向模拟\n Self::Anticipate(_) => 4, // 主动 - 锦上添花\n Self::Assess => 3, // 元认知 - 压力大时可跳过\n Self::CoherenceCheck => 2, // 维护 - 预算紧张时跳过\n }\n }\n}\n```\n\n资料来源：[query_dsl.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/query_dsl.rs)\n\n## 触发工作流\n\n```mermaid\ngraph TD\n A[记忆状态变化] --> B{触发条件检查}\n B -->|满足| C[冷却时间检查]\n B -->|不满足| Z[跳过]\n C -->|冷却中| Z\n C -->|可触发| D[创建触发事件]\n D --> E[评估优先级]\n E --> F[执行认知运算符]\n F --> G{操作成功?}\n G -->|是| H[更新记忆状态]\n G -->|否| I[记录错误]\n H --> J[重置冷却计时器]\n I --> J\n```\n\n## 与感知系统的集成\n\n### SurfaceReason 表面原因\n\n触发系统与主动建议（Proactive Suggestion）机制紧密集成，通过 `SurfaceReason` 枚举记录触发原因：\n\n| 表面原因 | 描述 |\n|---------|------|\n| `LowReceptivity` | 低感知状态 |\n| `ItemSuppressionRule` | 项目抑制规则 |\n| `QuietHours` | 安静时段 |\n| `RateLimited` | 速率限制 |\n| `AntiNag` | 防打扰机制 |\n| `MaxSurfaces` | 达到最大表面数 |\n| `TooSoon` | 距上次过近 |\n| `NotificationModeBlock` | 通知模式阻止 |\n\n```rust\nimpl SurfaceReason {\n pub fn as_str(self) -> &'static str {\n match self {\n Self::LowReceptivity => \"low_receptivity\",\n Self::ItemSuppressionRule => \"item_suppression_rule\",\n Self::QuietHours => \"quiet_hours\",\n Self::RateLimited => \"rate_limited\",\n Self::AntiNag => \"anti_nag\",\n Self::MaxSurfaces => \"max_surfaces\",\n Self::TooSoon => \"too_soon\",\n Self::NotificationModeBlock => \"notification_mode_block\",\n }\n }\n}\n```\n\n资料来源：[surfacing.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/surfacing.rs)\n\n### 用户感知状态\n\n触发系统根据用户当前状态调整行为：\n\n```rust\npub fn interruption_cost(self) -> f64 {\n match self {\n Self::Idle => 0.10,\n Self::JustReturned => 0.35,\n Self::Browsing => 0.45,\n Self::Communicating => 0.55,\n Self::TaskSwitching => 0.65,\n Self::FocusedWork => 0.75,\n Self::DeepFocus => 0.95,\n }\n}\n```\n\n| 活动状态 | 中断成本 | 说明 |\n|---------|---------|------|\n| `Idle` | 0.10 | 空闲状态 |\n| `JustReturned` | 0.35 | 刚返回 |\n| `Browsing` | 0.45 | 浏览中 |\n| `Communicating` | 0.55 | 通讯中 |\n| `TaskSwitching` | 0.65 | 任务切换中 |\n| `FocusedWork` | 0.75 | 专注工作 |\n| `DeepFocus` | 0.95 | 深度专注 |\n\n资料来源：[receptivity.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/receptivity.rs)\n\n## 冲突触发机制\n\n### ConflictType 冲突类型\n\n冲突检测是触发系统的重要组成部分：\n\n| 冲突类型 | 默认优先级 | 描述 |\n|---------|----------|------|\n| `IdentityFact` | critical | 身份事实冲突 |\n| `Preference` | high | 偏好冲突 |\n| `Temporal` | high | 时间相关冲突 |\n| `Consolidation` | medium | 整合冲突 |\n| `Minor` | low | 轻微冲突 |\n\n```rust\nimpl ConflictType {\n pub fn default_priority(&self) -> &'static str {\n match self {\n ConflictType::IdentityFact => \"critical\",\n ConflictType::Preference => \"high\",\n ConflictType::Temporal => \"high\",\n ConflictType::Consolidation => \"medium\",\n ConflictType::Minor => \"low\",\n }\n }\n}\n```\n\n### Conflict 数据结构\n\n```rust\npub struct Conflict {\n pub conflict_id: String,\n pub conflict_type: String,\n pub priority: String,\n pub status: String,\n pub memory_a: String,\n pub memory_b: String,\n pub entity: Option,\n pub rel_type: Option,\n pub detected_at: f64,\n pub detected_by: String,\n pub detection_reason: String,\n pub resolved_at: Option,\n pub resolved_by: Option,\n pub strategy: Option,\n pub winner_rid: Option,\n pub resolution_note: Option,\n}\n```\n\n## 触发执行引擎\n\n### Attend 运算符\n\n`Attend` 运算符是触发系统的核心执行单元，负责激活相关记忆节点：\n\n```rust\nfn execute_attend(&self, op: &AttendOp) -> StepOutput {\n match self.db.hydrate_working_set(self.attention_config.clone()) {\n Ok(mut ws) => {\n let mut activated = 0;\n let mut top = Vec::new();\n for &seed in &op.seeds {\n if let Some(node) = ws.get_mut(seed) {\n let new_activation = (node.attrs.activation + 0.3).min(1.0);\n node.attrs.activation = new_activation;\n top.push((seed, new_activation));\n activated += 1;\n }\n }\n // 从种子节点扩散激活\n for &seed in &op.seeds {\n activated += ws.activate_and_spread(seed, 0.3);\n }\n StepOutput::Attend { nodes_activated: activated, top_activated: top }\n }\n Err(e) => StepOutput::Error { message: format!(\"Attend failed: {}\", e) },\n }\n}\n```\n\n### 运算符参数结构\n\n| 运算符 | 参数结构 | 主要功能 |\n|-------|---------|---------|\n| `Attend` | `AttendOp { seeds, max_hops, decay }` | 注意力激活与扩散 |\n| `Recall` | `RecallOp { top_k, query, domain }` | 记忆召回 |\n| `Believe` | `BelieveOp { evidence }` | 证据整合 |\n| `Project` | - | 前向模拟 |\n| `Compare` | - | 比较操作 |\n| `Constrain` | - | 约束检查 |\n| `Anticipate` | - | 预期生成 |\n| `Plan` | - | 计划生成 |\n\n## 认知属性与触发\n\n### CognitiveAttributes 认知属性\n\n每条记忆节点携带认知属性，影响触发决策：\n\n```rust\nSelf {\n confidence,\n activation: 0.0,\n salience,\n persistence,\n valence: 0.0,\n urgency: 0.0,\n novelty: 1.0,\n last_updated_ms: now_ms(),\n volatility: 0.1,\n provenance: Provenance::Observed,\n evidence_count: 1,\n}\n```\n\n### 节点类型与初始值\n\n| 节点类型 | 置信度 | 显著性 | 持久性 |\n|---------|-------|-------|-------|\n| `Entity` | 0.80 | 0.90 | 0.95 |\n| `Episode` | 0.60 | 0.80 | 0.70 |\n| `Belief` | 0.50 | 0.50 | 0.50 |\n| `Goal` | 0.70 | 0.60 | 0.80 |\n| `Task` | 0.90 | 0.80 | 0.90 |\n| `Need` | 0.60 | 0.70 | 0.40 |\n| `Opportunity` | 0.40 | 0.60 | 0.20 |\n| `Risk` | 0.40 | 0.70 | 0.60 |\n| `Constraint` | 0.90 | 0.80 | 0.95 |\n| `Preference` | 0.60 | 0.50 | 0.85 |\n\n资料来源：[state.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n\n### Provenance 可靠性先验\n\n```rust\npub fn reliability_prior(self) -> f64 {\n match self {\n Self::Told => 0.95, // 用户明确陈述 - 最高信任\n Self::Observed => 0.90, // 直接观察行为\n Self::Experimented => 0.85, // 通过受控实验确认\n Self::Extracted => 0.75, // 外部文档 - 可能过时\n Self::Inferred => 0.60, // 基于模式推理 - 中等信任\n Self::Consolidated => 0.80, // 多源合并\n Self::SystemDefault => 0.50, // 默认值 - 最弱，易覆盖\n }\n}\n```\n\n## 边缘类型与激活传递\n\n触发系统通过边缘类型决定激活如何在记忆网络间传递：\n\n```rust\npub fn activation_transfer(self) -> f64 {\n match self {\n // 强正传递\n Self::Causes => 0.8,\n Self::Supports => 0.7,\n Self::Triggers => 0.7,\n Self::AdvancesGoal => 0.6,\n Self::Requires => 0.5,\n Self::SubtaskOf => 0.4,\n \n // 中等正传递\n Self::Predicts => 0.4,\n Self::AssociatedWith => 0.3,\n Self::SimilarTo => 0.3,\n Self::InstanceOf => 0.3,\n Self::PartOf => 0.3,\n Self::Prefers => 0.3,\n Self::PrecedesTemporally => 0.2,\n // ...\n }\n}\n```\n\n| 边缘类型 | 传递系数 | 说明 |\n|---------|---------|------|\n| `Causes` | 0.8 | 因果关系 |\n| `Supports` | 0.7 | 支持关系 |\n| `Triggers` | 0.7 | 触发关系 |\n| `AdvancesGoal` | 0.6 | 推进目标 |\n| `Requires` | 0.5 | 依赖关系 |\n| `SubtaskOf` | 0.4 | 子任务 |\n| `Predicts` | 0.4 | 预测关系 |\n| `AssociatedWith` | 0.3 | 关联关系 |\n| `SimilarTo` | 0.3 | 相似关系 |\n\n资料来源：[state.rs:行](https://github.com/yantrikos/yantrikdb/blob/main/crates/yantrikdb-core/src/cognition/state.rs)\n\n## 触发系统架构图\n\n```mermaid\ngraph TD\n subgraph 触发源层\n T1[DecayReview]\n T2[ConsolidationReady]\n T3[ConflictEscalation]\n T4[PatternDiscovered]\n T5[其他触发类型]\n end\n \n subgraph 冷却管理\n C1[冷却时间检查]\n C2[过期时间检查]\n C3[频率限制]\n end\n \n subgraph 执行层\n E1[Attend 运算符]\n E2[Recall 运算符]\n E3[Believe 运算符]\n E4[Plan 运算符]\n end\n \n subgraph 输出层\n O1[主动建议]\n O2[冲突报告]\n O3[认知追踪]\n end\n \n T1 --> C1\n T2 --> C1\n T3 --> C1\n T4 --> C1\n T5 --> C1\n \n C1 -->|通过| C2\n C2 -->|通过| C3\n C3 -->|通过| E1\n E1 --> E2\n E2 --> E3\n E3 --> E4\n \n E4 --> O1\n E4 --> O2\n E4 --> O3\n \n style T1 fill:#ff9999\n style T3 fill:#ffcc99\n style O1 fill:#99ff99\n```\n\n## 配置示例\n\n### Rust 配置\n\n```rust\nlet think_config = ThinkConfig {\n importance_threshold: 0.5,\n decay_threshold: 0.3,\n max_triggers: 5,\n};\n```\n\n### Python API 使用\n\n```python\nimport yantrikdb\n\ndb = yantrikdb.YantrikDB.with_default(\"memory.db\")\n\n# 记录记忆\ndb.record(\"Alice is the engineering lead\", importance=0.8, domain=\"people\")\n\n# 触发认知循环\ndb.think() # 触发整合、冲突检测、模式挖掘\n\ndb.close()\n```\n\n## 总结\n\n主动触发系统是 yantrikdb 实现智能记忆管理的核心机制。通过定义多种触发类型、完善的冷却/过期机制、与认知运算符的深度集成，系统能够在适当的时机主动发起记忆整合、冲突解决等操作，在不打扰用户的前提下持续优化记忆网络的质量和一致性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：yantrikos/yantrikdb\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。\n\n## 1. 安装坑 · 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code\n\n## 11. 配置坑 · 来源证据：v0.7.7 — recall_text Keyword-Only Filter Args\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：think() runs consolidation before conflict detection — contradictions get merged\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80497be2ab644e66be4fec1a966b4c10 | https://github.com/yantrikos/yantrikdb/issues/7 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7c8f7ee1384f9d97652734d01b8d67 | https://github.com/yantrikos/yantrikdb/issues/3 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40bcf8933f1b4ec7a559a746497c3bae | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.6 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5a77701b7ac401a863105d996cb585c | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 安全/权限坑 · 来源证据：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a590e518c884b5b9a2bbdc995c372fd | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：yantrikos/yantrikdb\n\n摘要：发现 24 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication。\n\n## 1. 安装坑 · 来源证据：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：API addition: deterministic mutation primitives (record_with_rid + friends) for cluster-mode replication\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4ab95be6a3ac4fb192053e8c3829f762 | https://github.com/yantrikos/yantrikdb/issues/9 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Bug: `namespace` parameter ignored in batch `remember` calls — memories always stored under `default`\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c37cd96e9c8d476880caca4f7314118e | https://github.com/yantrikos/yantrikdb/issues/2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安装坑 · 来源证据：Migration v14→v15 fails: ALTER TABLE on edges view\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Migration v14→v15 fails: ALTER TABLE on edges view\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bb378d100e9d472892b1d5e42e640cad | https://github.com/yantrikos/yantrikdb/issues/10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：[bug] Tombstoned memories still appear in similarity-scan recall results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] Tombstoned memories still appear in similarity-scan recall results\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_aa3d426055a44483b47ffd3b9f3fdb6a | https://github.com/yantrikos/yantrikdb/issues/8 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安装坑 · 来源证据：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[bug] YANTRIKDB_ENCRYPTION_KEY_HEX env var ignored — encryption silently disabled\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_17652fc680ba4b64bee5018b2d1514e4 | https://github.com/yantrikos/yantrikdb/issues/6 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 6. 安装坑 · 来源证据：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.10 — Fix has_embedder() for Python-side embedders (plugin#4)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_daa2ca5265524c83bb21727be2a980a1 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 7. 安装坑 · 来源证据：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.11 — pyo3 0.28.3 + python3.14 Support\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_91b7975fce7d49b6b87ef05b914e80b2 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.11 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 安装坑 · 来源证据：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.4 — Python Bindings: with_default + record_text/recall_text\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_54938994017d4b5899ad9cef4e6a2723 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.4 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 9. 安装坑 · 来源证据：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v0.7.5 — Python UX: TypeError Guard + embedder-download in Default Wheel\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be61ad4afd5b4f669a6f727d727474c4 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.5 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | host_targets=mcp_host, claude, claude_code\n\n## 11. 配置坑 · 来源证据：v0.7.7 — recall_text Keyword-Only Filter Args\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.7.7 — recall_text Keyword-Only Filter Args\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_45587e0ca02f4e95ac36c364d3a88519 | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.7 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：think() runs consolidation before conflict detection — contradictions get merged\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：think() runs consolidation before conflict detection — contradictions get merged\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6908447fb6a6482f89b1a85e714de42a | https://github.com/yantrikos/yantrikdb/issues/1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：risks.safety_notes | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 17. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | no_demo; severity=medium\n\n## 18. 安全/权限坑 · 来源证据：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] POST /v1/admin/snapshot unusable in single-node mode — requires cluster master token that doesn't exist\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_80497be2ab644e66be4fec1a966b4c10 | https://github.com/yantrikos/yantrikdb/issues/7 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[bug] at-rest encryption `key_hex` in TOML has no effect on disk (v0.5.0)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7c8f7ee1384f9d97652734d01b8d67 | https://github.com/yantrikos/yantrikdb/issues/3 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.6 — Drop sentence-transformers + numpy from Default Deps\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_40bcf8933f1b4ec7a559a746497c3bae | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.6 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。\n\n## 21. 安全/权限坑 · 来源证据：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.8 — Extended Idempotent Migration Runner (closes #10)\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e5a77701b7ac401a863105d996cb585c | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.8 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 22. 安全/权限坑 · 来源证据：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v0.7.9 — Bundle potion-multilingual-128M (101 Languages) in embedder-download Registry\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7a590e518c884b5b9a2bbdc995c372fd | https://github.com/yantrikos/yantrikdb/releases/tag/v0.7.9 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 23. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | issue_or_pr_quality=unknown\n\n## 24. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1164482810 | https://github.com/yantrikos/yantrikdb | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# yantrikdb - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 yantrikdb 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude / Claude Code\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Cognitive memory engine for AI agents — temporal decay, contradiction detection, autonomous consolidation, knowledge graph, ANN recall via HNSW. Embeddable Rust library with Python bindings; powers yantrikdb-server (HTTP gateway, MCP server, openraft cluster). AGPL. 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：YantrikDB 简介。围绕“YantrikDB 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n3. page-five-indexes：五大索引架构。围绕“五大索引架构”模拟一次用户任务，不展示安装或运行结果。\n4. page-decoupled-write-path：解耦写入路径。围绕“解耦写入路径”模拟一次用户任务，不展示安装或运行结果。\n5. page-record-recall：记录与检索操作。围绕“记录与检索操作”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“YantrikDB 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-five-indexes\n输入：用户提供的“五大索引架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-decoupled-write-path\n输入：用户提供的“解耦写入路径”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-record-recall\n输入：用户提供的“记录与检索操作”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“YantrikDB 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-quickstart：Step 2 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-five-indexes：Step 3 必须围绕“五大索引架构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-decoupled-write-path：Step 4 必须围绕“解耦写入路径”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-record-recall：Step 5 必须围绕“记录与检索操作”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/yantrikos/yantrikdb\n- https://github.com/yantrikos/yantrikdb#readme\n- README.md\n- Cargo.toml\n- LICENSE\n- pyproject.toml\n- src/yantrikdb/__init__.py\n- crates/yantrikdb-core/src/vector/hnsw.rs\n- crates/yantrikdb-core/src/vector/delta_index.rs\n- crates/yantrikdb-core/src/knowledge/graph.rs\n- crates/yantrikdb-core/src/knowledge/graph_index.rs\n- crates/yantrikdb-core/src/engine/indices.rs\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 yantrikdb 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：yantrikos/yantrikdb\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install yantrikdb-mcp\n```\n\n来源：https://github.com/yantrikos/yantrikdb#readme\n\n## 来源\n\n- repo: https://github.com/yantrikos/yantrikdb\n- docs: https://github.com/yantrikos/yantrikdb#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_c248d7a8ec53475a8b3593d4b8b4e781"
}