添加 图数据库结构设计

图数据库结构设计

@@ -0,0 +1,254 @@
+以下是完整的 Neo4j 图数据库结构设计，针对 OpenClaw 对话记忆场景优化，边上带完整时间戳和元数据：
+ 1. 节点（Node）设计
+  实体节点（Entity）
+  (:Entity {
+        name: string,           // 实体名称（唯一标识）
+            type: string,           // 类型：concept | technology | person | project | decision
+                created_at: datetime,   // 首次出现时间
+                    updated_at: datetime,   // 最后更新时间
+                        mention_count: int      // 被提及次数（用于权重）
+  })
+
+   会话节点（Session）
+   (:Session {
+        session_id: string,     // 会话唯一ID（如 20260408-a7f3）
+            created_at: datetime,   // 会话开始时间
+                summary: string,        // 会话摘要（可选）
+                    status: string          // active | archived | compacted
+   })
+
+    2. 关系（Edge）设计
+     核心关系（RELATES）
+     所有对话关系统一使用 RELATES 类型，属性承载时间戳和元数据：
+     (source:Entity)-[:RELATES {
+            // 基础关系属性
+                type: string,           // 关系类型：uses | implements | depends_on | rejects | prefers | leads_to | contradicts
+                    
+                        // 时间戳（核心）
+                            created_at: datetime,   // 关系创建时间（精确到秒）
+                                updated_at: datetime,   // 最后更新时间（纠错时更新）
+                                    
+                                        // 来源追踪
+                                            session_id: string,     // 所属会话ID
+                                                turn_id: int,           // 轮次序号（该会话中的第几轮）
+                                                    
+                                                        // 角色标记
+                                                            role: string,           // "user" | "assistant" | "system"
+                                                                
+                                                                    // 内容快照
+                                                                        context_snippet: string, // 原始文本片段（前100字符）
+                                                                            
+                                                                                // 状态管理
+                                                                                    status: string,         // active | deleted | archived | superseded（被取代）
+                                                                                        confidence: float,      // 置信度（0.0-1.0，提取算法给出）
+                                                                                            
+                                                                                                // 时序检索辅助
+                                                                                                    date_bucket: string     // 日期分区（2026-04-08），用于快速范围查询
+     }]->(target:Entity)
+
+      时序链（NEXT）- 可选
+      用于严格保持对话顺序：
+      (:Entity)-[:NEXT {
+            session_id: string,
+                created_at: datetime
+      }]->(:Entity)
+
+       3. 索引与约束
+       // 实体唯一性约束
+       CREATE CONSTRAINT entity_name_constraint IF NOT EXISTS 
+       FOR (e:Entity) REQUIRE e.name IS UNIQUE;
+
+       // 会话唯一性约束  
+       CREATE CONSTRAINT session_id_constraint IF NOT EXISTS
+       FOR (s:Session) REQUIRE s.session_id IS UNIQUE;
+
+       // 关系查询索引（按时间戳检索关键）
+       CREATE INDEX rel_created_at IF NOT EXISTS 
+       FOR ()-[r:RELATES]-() ON r.created_at;
+
+       CREATE INDEX rel_session_id IF NOT EXISTS
+       FOR ()-[r:RELATES]-() ON r.session_id;
+
+       CREATE INDEX rel_type IF NOT EXISTS
+       FOR ()-[r:RELATES]-() ON r.type;
+
+       CREATE INDEX rel_status IF NOT EXISTS
+       FOR ()-[r:RELATES]-() ON r.status;
+
+       CREATE INDEX rel_date_bucket IF NOT EXISTS
+       FOR ()-[r:RELATES]-() ON r.date_bucket;
+
+       // 复合索引（会话+时间）
+       CREATE INDEX rel_session_time IF NOT EXISTS
+       FOR ()-[r:RELATES]-() ON (r.session_id, r.created_at);
+
+        4. 数据模型示例
+         插入场景
+         用户说："我想用 Neo4j 改造 OpenClaw 的记忆系统，替换掉原来的 SQLite 方案。"
+         生成的图结构：
+         // 节点
+         (:Entity {name: "OpenClaw", type: "project", created_at: now()})
+         (:Entity {name: "Neo4j", type: "technology", created_at: now()})
+         (:Entity {name: "SQLite", type: "technology", created_at: now()})
+         (:Entity {name: "记忆系统改造", type: "decision", created_at: now()})
+
+         // 关系（带时间戳）
+         (OpenClaw)-[:RELATES {
+                type: "uses",
+                    created_at: datetime("2026-04-08T19:45:00"),
+                        session_id: "20260408-a7f3",
+                            turn_id: 1,
+                                role: "user",
+                                    context_snippet: "我想用 Neo4j 改造 OpenClaw...",
+                                        status: "active",
+                                            confidence: 0.95,
+                                                date_bucket: "2026-04-08"
+         }]->(Neo4j)
+
+         (OpenClaw)-[:RELATES {
+                type: "replaces",
+                    created_at: datetime("2026-04-08T19:45:00"),
+                        session_id: "20260408-a7f3",
+                            turn_id: 1,
+                                role: "user",
+                                    context_snippet: "替换掉原来的 SQLite 方案",
+                                        status: "active",
+                                            confidence: 0.92,
+                                                date_bucket: "2026-04-08"
+         }]->(SQLite)
+
+         (记忆系统改造)-[:RELATES {
+                type: "involves",
+                    created_at: datetime("2026-04-08T19:45:00"),
+                        session_id: "20260408-a7f3",
+                            turn_id: 1,
+                                role: "user",
+                                    status: "active",
+                                        date_bucket: "2026-04-08"
+         }]->(OpenClaw)
+
+          5. 关键查询模式
+           A. 时序检索（最新记忆优先）
+           // 查询实体相关的最新关系（按时间戳倒序）
+           MATCH (e:Entity {name: $entity_name})-[r:RELATES]-(target:Entity)
+           WHERE r.status = 'active'
+           RETURN e, r, target
+           ORDER BY r.created_at DESC
+           LIMIT 20
+
+            B. 会话范围查询（上下文隔离）
+            // 仅查询特定会话内的关系
+            MATCH (s:Entity)-[r:RELATES]->(t:Entity)
+            WHERE r.session_id = $session_id
+            RETURN s.name, r.type, t.name, r.created_at
+            ORDER BY r.turn_id
+
+             C. 时间范围查询（最近N天）
+             // 利用 date_bucket 或时间戳范围
+             MATCH (s:Entity)-[r:RELATES]->(t:Entity)
+             WHERE r.date_bucket >= date().isoDate - duration('P7D')  // 最近7天
+                OR r.created_at >= datetime() - duration('P7D')
+                RETURN s, r, t
+                ORDER BY r.created_at DESC
+
+                 D. 多跳路径查询（关联推理）
+                 // 查询两个实体间的路径（带时间约束）
+                 MATCH path = (start:Entity {name: $start})-[:RELATES*1..3]->(end:Entity {name: $end})
+                 WHERE ALL(r IN relationships(path) WHERE r.status = 'active')
+                 RETURN path,
+                        [r IN relationships(path) | r.created_at] as path_timestamps,
+                               length(path) as hops
+                               ORDER BY path_timestamps[-1] DESC  // 按最后关系时间排序
+                               LIMIT 5
+
+                                E. 纠错更新（软删除）
+                                // 用户更正时，不物理删除，而是标记为 superseded 并创建新关系
+                                MATCH (s:Entity {name: $source})-[r:RELATES {type: $old_relation}]->(t:Entity {name: $target})
+                                WHERE r.status = 'active'
+                                SET r.status = 'superseded',
+                                    r.updated_at = datetime(),
+                                        r.superseded_by = $new_relation_id  // 指向新关系的ID
+
+                                        // 创建新关系（带新的时间戳）
+                                        CREATE (s)-[:RELATES {
+                                                type: $new_relation,
+                                                    created_at: datetime(),
+                                                        session_id: $session_id,
+                                                            turn_id: $turn_id,
+                                                                role: $role,
+                                                                    status: 'active',
+                                                                        supersedes: $old_relation_id
+                                        }]->(t)
+
+                                         6. 存储过程（APOC）优化
+                                          批量插入（高性能）
+                                          // 使用 APOC 批量合并，避免逐条插入开销
+                                          CALL apoc.periodic.iterate(
+                                              "UNWIND $triples as t RETURN t",
+                                                "
+                                                  MERGE (s:Entity {name: t.source})
+                                                    ON CREATE SET s.created_at = datetime(), s.type = coalesce(t.source_type, 'unknown')
+                                                      ON MATCH SET s.updated_at = datetime(), s.mention_count = coalesce(s.mention_count, 0) + 1
+                                                        
+                                                          MERGE (e:Entity {name: t.target})
+                                                            ON CREATE SET e.created_at = datetime(), e.type = coalesce(t.target_type, 'unknown')
+                                                              ON MATCH SET e.updated_at = datetime(), e.mention_count = coalesce(e.mention_count, 0) + 1
+                                                                
+                                                                  CREATE (s)-[r:RELATES {
+                                                                        type: t.relation,
+                                                                            created_at: datetime(),
+                                                                                session_id: t.session_id,
+                                                                                    turn_id: t.turn_id,
+                                                                                        role: t.role,
+                                                                                            status: 'active',
+                                                                                                date_bucket: date().isoDate,
+                                                                                                    confidence: coalesce(t.confidence, 1.0)
+                                                                  }]->(e)
+                                                                    ",
+                                                                      {batchSize: 100, params: {triples: $triples}}
+                                          )
+
+                                           时序压缩（归档旧关系）
+                                           // 将N天前的关系标记为 archived，但保留节点
+                                           MATCH ()-[r:RELATES]->()
+                                           WHERE r.created_at < datetime() - duration('P30D')  // 30天前
+                                             AND r.status = 'active'
+                                             SET r.status = 'archived',
+                                                 r.archived_at = datetime()
+                                                 RETURN count(r) as archived_count
+
+                                                  7. 与 Bridge API 的映射
+                                                  API 端点	Cypher 操作	时间戳处理
+                                                  POST /insert	MERGE 节点 + CREATE 关系	datetime() 自动生成
+                                                  POST /search	MATCH 带时间戳排序	返回 r.created_at 等字段
+                                                  POST /delete	SET r.status = 'deleted'	软删除，保留 updated_at
+                                                   8. 数据保留策略
+                                                   // 节点保留：永久（实体名词长期有效）
+                                                   // 关系保留策略：
+                                                   // - active: 最近30天（高频查询）
+                                                   // - archived: 30-90天（低频查询，需指定时间范围）
+                                                   // - deleted: 逻辑删除，保留90天后物理清理（APOC 定时任务）
+
+                                                   // 物理清理（谨慎操作）
+                                                   MATCH ()-[r:RELATES]->()
+                                                   WHERE r.status = 'deleted' 
+                                                     AND r.updated_at < datetime() - duration('P90D')
+                                                     DELETE r
+                                                     WITH count(*) as deleted_relations
+                                                     MATCH (e:Entity)
+                                                     WHERE NOT (e)-[:RELATES]-()  // 无关系的孤立节点
+                                                     DELETE e
+                                                     RETURN deleted_relations, count(e) as deleted_orphans
+
+                                                     这个设计支持时间旅行查询（查看任意时刻的图状态）、会话隔离（只看当前对话历史）和渐进式遗忘（旧关系归档但不删除），符合 OpenClaw 的增量记忆需求。
+                                                     
+                                                                  }]
+                                          )
+                                        }]
+         }]
+         }]
+         }]
+      }]
+     }]
+   })
+  })