{
  "canonical_name": "rishimeka/genesys",
  "compilation_id": "pack_84f706e015df4c2aa1e28d328257f01b",
  "created_at": "2026-05-15T05:11:50.376568+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 genesys-memory` 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 genesys-memory",
      "sandbox_container_image": "python:3.12-slim",
      "sandbox_execution_backend": "docker",
      "sandbox_planner_decision": "llm_execute_isolated_install",
      "sandbox_validation_id": "sbx_ef6662f6afa440e59940c76db8844e90"
    },
    "feedback_event_type": "project_pack_compilation_feedback",
    "learning_candidate_reasons": [],
    "template_gaps": []
  },
  "identity": {
    "canonical_id": "project_2de816699a8f96bcd0898accf3d332ae",
    "canonical_name": "rishimeka/genesys",
    "homepage_url": null,
    "license": "unknown",
    "repo_url": "https://github.com/rishimeka/genesys",
    "slug": "genesys",
    "source_packet_id": "phit_4660f470a17748189a921d8736a1a1b6",
    "source_validation_id": "dval_2c0e81f2b4f64a94886a7f8bf23c34db"
  },
  "merchandising": {
    "best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
    "github_forks": 2,
    "github_stars": 16,
    "one_liner_en": "Open-source causal graph memory for AI agents. 89.9% on LoCoMo. MCP server with ACT-R scoring, spreading activation, and active forgetting.",
    "one_liner_zh": "Open-source causal graph memory for AI agents. 89.9% on LoCoMo. MCP server with ACT-R scoring, spreading activation, and active forgetting.",
    "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 等宿主 AI 的用户",
    "title_en": "genesys",
    "title_zh": "genesys 能力包",
    "visible_tags": [
      {
        "label_en": "Security & Permissions",
        "label_zh": "安全审查与权限治理",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "product_domain-security-permissions",
        "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": "Durable Memory",
        "label_zh": "长期记忆",
        "source": "repo_evidence_project_characteristics",
        "tag_id": "core_capability-durable-memory",
        "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_4660f470a17748189a921d8736a1a1b6",
  "page_model": {
    "artifacts": {
      "artifact_slug": "genesys",
      "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 genesys-memory",
          "label": "Python / pip · 官方安装入口",
          "source": "https://github.com/rishimeka/genesys#readme",
          "verified": true
        }
      ],
      "display_tags": [
        "安全审查与权限治理",
        "知识库问答",
        "长期记忆",
        "节点式流程编排",
        "评测体系"
      ],
      "eyebrow": "工具连接与集成",
      "glance": [
        {
          "body": "判断自己是不是目标用户。",
          "label": "最适合谁",
          "value": "需要工具连接与集成能力，并使用 mcp_host的用户"
        },
        {
          "body": "先理解能力边界，再决定是否继续。",
          "label": "核心价值",
          "value": "Open-source causal graph memory for AI agents. 89.9% on LoCoMo. MCP server with ACT-R scoring, spreading activation, and active forgetting."
        },
        {
          "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",
          "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": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
            "category": "配置坑",
            "evidence": [
              "capability.host_targets | github_repo:1207565616 | https://github.com/rishimeka/genesys | host_targets=mcp_host, claude"
            ],
            "severity": "medium",
            "suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
            "title": "可能修改宿主 AI 配置",
            "user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
          },
          {
            "body": "README/documentation is current enough for a first validation pass.",
            "category": "能力坑",
            "evidence": [
              "capability.assumptions | github_repo:1207565616 | https://github.com/rishimeka/genesys | README/documentation is current enough for a first validation pass."
            ],
            "severity": "medium",
            "suggested_check": "将假设转成下游验证清单。",
            "title": "能力判断依赖假设",
            "user_impact": "假设不成立时，用户拿不到承诺的能力。"
          },
          {
            "body": "未记录 last_activity_observed。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | 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:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "进入安全/权限治理复核队列。",
            "title": "下游验证发现风险项",
            "user_impact": "下游已经要求复核，不能在页面中弱化。"
          },
          {
            "body": "no_demo",
            "category": "安全/权限坑",
            "evidence": [
              "risks.scoring_risks | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium"
            ],
            "severity": "medium",
            "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
            "title": "存在评分风险",
            "user_impact": "风险会影响是否适合普通用户安装。"
          },
          {
            "body": "issue_or_pr_quality=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | issue_or_pr_quality=unknown"
            ],
            "severity": "low",
            "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
            "title": "issue/PR 响应质量未知",
            "user_impact": "用户无法判断遇到问题后是否有人维护。"
          },
          {
            "body": "release_recency=unknown。",
            "category": "维护坑",
            "evidence": [
              "evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | release_recency=unknown"
            ],
            "severity": "low",
            "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
            "title": "发布节奏不明确",
            "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
          }
        ],
        "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
        "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
        "title": "踩坑日志"
      },
      "snapshot": {
        "contributors": 1,
        "forks": 2,
        "license": "unknown",
        "note": "站点快照，非实时质量证明；用于开工前背景判断。",
        "stars": 16
      },
      "source_url": "https://github.com/rishimeka/genesys",
      "steps": [
        {
          "body": "不安装项目，先体验能力节奏。",
          "code": "preview",
          "title": "先试 Prompt"
        },
        {
          "body": "理解输入、输出、失败模式和边界。",
          "code": "manual",
          "title": "读说明书"
        },
        {
          "body": "把上下文交给宿主 AI 继续工作。",
          "code": "context",
          "title": "带给 AI"
        },
        {
          "body": "进入主力环境前先完成安装入口与风险边界验证。",
          "code": "verify",
          "title": "沙箱验证"
        }
      ],
      "subtitle": "Open-source causal graph memory for AI agents. 89.9% on LoCoMo. MCP server with ACT-R scoring, spreading activation, and active forgetting.",
      "title": "genesys 能力包",
      "trial_prompt": "# genesys - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 genesys 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 项目说明, 边界判断, 后续问题。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 项目知识预览: 项目可被阅读和解释，但当前证据不足以确认可安装能力或运行入口。 输入：README 和项目文档；输出：项目说明, 边界判断, 后续问题。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-data-models：数据模型。围绕“数据模型”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-data-models\n输入：用户提供的“数据模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-data-models：Step 5 必须围绕“数据模型”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rishimeka/genesys\n- https://github.com/rishimeka/genesys#readme\n- benchmarks/README.md\n- CONTRIBUTING.md\n- LICENSE\n- .github/pull_request_template.md\n- CHANGELOG.md\n- README.md\n- src/genesys_memory/engine/scoring.py\n- src/genesys_memory/models/node.py\n- pyproject.toml\n- .env.example\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 genesys 的核心服务。\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": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
          "items": [],
          "status": "待发现 Agent 补证",
          "title": "社区讨论"
        }
      ]
    },
    "homepage_card": {
      "category": "工具连接与集成",
      "desc": "Open-source causal graph memory for AI agents. 89.9% on LoCoMo. MCP server with ACT-R scoring, spreading activation, and active forgetting.",
      "effort": "安装已验证",
      "forks": 2,
      "icon": "link",
      "name": "genesys 能力包",
      "risk": "需复核",
      "slug": "genesys",
      "stars": 16,
      "tags": [
        "安全审查与权限治理",
        "知识库问答",
        "长期记忆",
        "节点式流程编排",
        "评测体系"
      ],
      "thumb": "gray",
      "type": "MCP 配置"
    },
    "manual": {
      "markdown": "# https://github.com/rishimeka/genesys 项目说明书\n\n生成时间：2026-05-14 08:09:06 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [数据模型](#page-data-models)\n- [评分引擎](#page-scoring-engine)\n- [记忆生命周期](#page-memory-lifecycle)\n- [MCP 工具集](#page-mcp-tools)\n- [存储后端实现](#page-storage-backends)\n- [检索系统](#page-retrieval-system)\n\n<a id='page-introduction'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)\n</details>\n\n# 项目介绍\n\n## 概述\n\nGenesys 是一个面向 AI Agent 的**记忆评分引擎、因果图谱和生命周期管理器**。它解决了传统向量存储记忆方案的局限性——虽然能提供检索能力，但缺乏对记忆之间关系的理解。Genesys 通过乘法评分公式（相关性 × 连接性 × 再激活）对每条记忆进行评分，构建因果图谱实现关系推理，并主动遗忘已变得不相关的记忆。资料来源：[README.md]()\n\nGenesys 的核心理念是：记忆应该像人类一样，具有生命周期、会衰减、会被强化、会被遗忘，而非简单地堆积在向量数据库中。资料来源：[README.md]()\n\n## 核心架构\n\n### 系统定位\n\nGenesys 位于 LLM 与记忆存储层之间，作为**智能记忆层**运行。它不直接存储数据，而是协调多种存储后端，并通过 MCP（Model Context Protocol）协议与 AI 客户端原生集成。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n    A[AI 客户端<br/>Claude/Codellm] -->|MCP 协议| B[Genesys<br/>记忆引擎]\n    B -->|评分/图谱/生命周期| C{存储后端}\n    C -->|向量+图| D[Postgres + pgvector]\n    C -->|本地优先| E[Obsidian Vault]\n    C -->|图数据库| F[FalkorDB]\n    C -->|内存模式| G[SQLite]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **评分引擎** | 计算记忆的衰减分数（相关性×连接性×再激活） | `engine/scoring.py` |\n| **因果图谱** | 管理记忆节点和边，执行图遍历和扩展激活 | `models/node.py` |\n| **生命周期管理器** | 状态转移：ACTIVE → DORMANT → FADING → PRUNED | `engine/transitions.py` |\n| **MCP 服务器** | 提供标准化工具接口，连接 AI 客户端 | `server.py` |\n| **存储抽象层** | 统一接口支持多种后端（Postgres/Obsidian/FalkorDB） | `storage/base.py` |\n\n## 记忆评分机制\n\n### 评分公式\n\nGenesys 采用**三力乘法模型**对记忆进行评分：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n资料来源：[README.md]()\n\n| 维度 | 含义 | 衰减行为 |\n|------|------|----------|\n| **Relevance（相关性）** | 记忆与当前上下文的相关程度 | 随时间自然衰减，除非被强化 |\n| **Connectivity（连接性）** | 记忆在因果图中的链接数量 | 链接越多，存活能力越强（Hub 记忆） |\n| **Reactivation（再激活）** | 记忆被回忆的频率 | 频繁访问的记忆获得boost |\n\n由于采用乘法公式，记忆必须同时在**三个维度**上都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁被回忆但没有因果链接的\"孤岛\"记忆同样会消失。资料来源：[README.md]()\n\n### 评分源代码逻辑\n\n```python\n# 来自 engine/llm_provider.py 的因果关系检测\nasync def identify_causal_relationships(\n    self, \n    new_memory: str, \n    existing_memories: list[tuple[str, str]]\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"\n    识别新记忆与已有记忆之间的因果关系\n    仅包含置信度 > 0.6 的关系\n    \"\"\"\n    results: list[tuple[str, EdgeType, float, str | None]] = []\n    for item in data:\n        confidence = float(item.get(\"confidence\", 0.0))\n        if confidence > 0.6:\n            results.append((\n                item[\"target_id\"], \n                EdgeType(edge_type_str), \n                confidence, \n                item.get(\"reason\")\n            ))\n    return results\n```\n\n资料来源：[src/genesys_memory/engine/llm_provider.py:1-30]()\n\n## 记忆生命周期\n\n### 状态转移图\n\n```mermaid\ngraph TD\n    STORE[STORE<br/>新建记忆] -->|评分>阈值| ACTIVE[ACTIVE<br/>活跃]\n    ACTIVE -->|长期低分| DORMANT[DORMANT<br/>休眠]\n    DORMANT -->|再次回忆| ACTIVE\n    DORMANT -->|持续衰减| FADING[FADING<br/>消退]\n    FADING -->|重新激活| ACTIVE\n    FADING -->|评分归零且无链接| PRUNED[PRUNED<br/>删除]\n    STORE -->|tagged状态| TAGGED[TAGGED<br/>已标记]\n    TAGGED -->|形成边连接| ACTIVE\n    TAGGED -->|24h无连接| PRUNED\n    ACTIVE -->|promote| CORE[CORE<br/>核心记忆<br/>永不删除]\n```\n\n资料来源：[README.md]()\n\n### 状态详情\n\n| 状态 | 说明 | 转移条件 |\n|------|------|----------|\n| **STORE** | 初始创建的记忆 | 自动转移至 ACTIVE 或 TAGGED |\n| **ACTIVE** | 正常参与检索的记忆 | 评分下降时转入 DORMANT |\n| **DORMANT** | 暂时搁置但未删除 | 被召回时转回 ACTIVE |\n| **FADING** | 即将被遗忘 | 可被 reactivation 救回，或进入 PRUNED |\n| **CORE** | 核心记忆，结构重要性高 | 自动 pin，永不删除 |\n| **PRUNED** | 已删除的记忆 | 不可逆 |\n\n### Tagged → Active 转移逻辑\n\n```python\n# 来自 engine/transitions.py\nasync def evaluate_transitions(...):\n    # Tagged → Active: 如果节点有边则提升\n    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)\n    for node in tagged_nodes:\n        if not await graph.is_orphan(str(node.id)):\n            await graph.update_node(str(node.id), {\"status\": MemoryStatus.ACTIVE})\n            # 原因：consolidation signal: edge formed\n```\n\n资料来源：[src/genesys_memory/engine/transitions.py:1-30]()\n\n## 存储后端\n\nGenesys 支持多种存储后端，可根据使用场景灵活选择：\n\n| 后端 | 安装方式 | 适用场景 | 特点 |\n|------|----------|----------|------|\n| **memory** | 内置无需安装 | 快速尝鲜 | 零依赖，纯内存存储 |\n| **postgres** | `pip install genesys-memory[postgres]` | 生产环境 | 持久化、可扩展、向量搜索 |\n| **Obsidian** | `pip install genesys-memory[obsidian]` | 本地知识库 | Markdown 文件作为记忆节点，wikilinks 自动转为因果边 |\n| **FalkorDB** | `pip install genesys-memory[falkordb]` | 图数据库场景 | 原生图遍历，Redis 底层 |\n| **自定义** | 实现 `GraphStorageProvider` 接口 | 特殊需求 | 完全可插拔 |\n\n资料来源：[README.md]()\n\n### Obsidian Vault 集成\n\nObsidian 后端特别适合个人知识管理场景：\n\n- Markdown 文件自动转为记忆节点\n- `[[wikilinks]]` 自动转为因果边\n- SQLite 侧car（`.genesys/index.db`）处理索引\n- 文件监视器增量重索引\n\n资料来源：[README.md]()\n\n### 完全本地模式（无 API Key）\n\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n# 无需 OPENAI_API_KEY\n```\n\n本地嵌入使用 `all-MiniLM-L6-v2`（384 维）模型，首次使用时自动下载（约 80MB）。资料来源：[README.md]()\n\n## MCP 工具接口\n\nGenesys 通过 MCP（Model Context Protocol）提供标准化工具接口：\n\n| 工具名称 | 功能描述 | 参数 |\n|----------|----------|------|\n| `memory_store` | 存储新记忆，可选链接相关记忆 | `content`, `related_to?`, `source_session?` |\n| `memory_recall` | 混合检索（向量+关键词+图扩散激活） | `query`, `k?`, `max_results?` |\n| `memory_search` | 带过滤条件的向量搜索 | `query`, `filters?`, `k?` |\n| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id`, `depth?`, `edge_types?` |\n| `memory_explain` | 解释记忆的评分构成 | `node_id` |\n| `memory_stats` | 获取记忆系统统计信息 | 无 |\n| `pin_memory` | 将记忆固定为核心，永不遗忘 | `node_id` |\n| `unpin_memory` | 取消固定，重新评估核心资格 | `node_id` |\n| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |\n| `list_core_memories` | 列出所有核心记忆 | `category?` |\n| `set_core_preferences` | 配置核心记忆类别偏好 | `auto?`, `approval?`, `excluded?` |\n\n资料来源：[src/genesys_memory/server.py:1-80]()\n\n### 记忆存储工具实现\n\n```python\n# 来自 mcp/tools.py\nnode = MemoryNode(\n    status=MemoryStatus.ACTIVE,\n    content_summary=summary,\n    content_full=content,\n    embedding=embedding,\n    created_at=ts,\n    last_accessed_at=ts,\n    last_reactivated_at=ts,\n    decay_score=1.0,\n    causal_weight=0,\n    source_agent=\"claude\",\n    source_session=source_session,\n    visibility=vis,\n    org_id=org_id,\n    original_user_id=_caller_uid(),\n)\nnode_id = await self.graph.create_node(node)\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py:1-50]()\n\n## 记忆合并（Consolidation）\n\n当大量情景记忆积累后，系统会自动将其合并为语义记忆：\n\n```python\n# 来自 engine/consolidation.py\nasync def consolidate(episodic_memories: list[str], ...) -> str:\n    # 匹配相关内容\n    matching = await embeddings.find_similar(consolidated_text, ...)\n    \n    # 创建新的语义节点\n    semantic_node = MemoryNode(\n        status=MemoryStatus.SEMANTIC,\n        content_summary=summary,\n        content_full=consolidated_text,\n        embedding=embedding,\n        created_at=now,\n        entity_refs=[entity_ref],\n    )\n    \n    # 创建 DERIVED_FROM 边\n    for source_node in matching:\n        edge = MemoryEdge(\n            source_id=semantic_node.id,\n            target_id=source_node.id,\n            type=EdgeType.DERIVED_FROM,\n            weight=0.7,\n        )\n        await graph.create_edge(edge)\n```\n\n资料来源：[src/genesys_memory/engine/consolidation.py:1-60]()\n\n## 基准测试\n\nGenesys 在 [LoCoMo](https://arxiv.org/abs/2402.06397) 长对话记忆基准上进行了测试（1540 个问题，10 个对话）：\n\n| 类别 | J-Score |\n|------|---------|\n| Single-hop（单跳） | 94.3% |\n| Temporal（时序） | 87.5% |\n| Multi-hop（多跳） | 69.8% |\n| Open-domain（开放域） | 91.7% |\n| **总体** | **89.9%** |\n\n对比基线：Mem0 67.1%，Zep 75.1%\n\n资料来源：[README.md]()\n\n## 快速开始\n\n### 环境要求\n\n- Python 3.11+\n- 可选：OpenAI API Key（用于嵌入生成，非必须）\n- 可选：Anthropic API Key（用于 LLM 记忆处理）\n\n### 安装\n\n```bash\npip install genesys-memory\n```\n\n### 启动服务器\n\n```bash\n# 方式一：使用内存后端（零配置）\ncp .env.example .env\n# 配置 OPENAI_API_KEY\nuvicorn genesys.api:app --port 8000\n\n# 方式二：使用 Obsidian 后端\npip install 'genesys-memory[obsidian,local]'\nuvicorn genesys.api:app --port 8000\n```\n\n### 连接 Claude Desktop\n\n在 `claude_desktop_config.json` 中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### 连接 Claude Code\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n资料来源：[README.md]()\n\n## 配置选项\n\n| 环境变量 | 必需 | 说明 |\n|----------|------|------|\n| `OPENAI_API_KEY` | 除非使用本地嵌入 | 用于嵌入生成 |\n| `ANTHROPIC_API_KEY` | 否 | 用于 LLM 记忆处理和合并 |\n| `GENESYS_BACKEND` | 否 | `memory`（默认）、`postgres`、`obsidian`、`falkordb` |\n| `GENESYS_EMBEDDER` | 否 | `openai`（默认）或 `local` |\n| `DATABASE_URL` | 如果使用 postgres | Postgres 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | 如果使用 obsidian | Obsidian 保险库路径 |\n| `FALKORDB_HOST` | 如果使用 falkordb | FalkorDB 主机（默认 localhost） |\n| `GENESYS_USER_ID` | 否 | 单租户模式的默认用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | 状态持久化路径 |\n\n资料来源：[README.md]()\n\n## 开发指南\n\n### 代码规范\n\n- **Python 版本**：3.11+\n- **代码风格**：async-first\n- **Linting**：`ruff check src/`\n- **类型检查**：`mypy src/genesys_memory --ignore-missing-imports`\n- **格式化**：遵循现有模式，类型提示贯穿始终\n\n### 测试\n\n```bash\n# 运行所有单元测试\npytest tests/ -v\n\n# 带覆盖率\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| **Python 3.11+** | 主要开发语言 |\n| **FastAPI/Starlette** | Web 框架和 ASGI 服务器 |\n| **pgvector** | PostgreSQL 向量搜索扩展 |\n| **sentence-transformers** | 本地嵌入模型 |\n| **SQLAlchemy** | ORM（Postgres 后端） |\n| **Pydantic** | 数据验证和序列化 |\n| **Model Context Protocol** | AI 客户端通信协议 |\n\n资料来源：[README.md](), [server.json]()\n\n## 许可证与归属\n\nGenesys 采用 **AGPL-3.0-or-later** 开源许可证。\n\n> **注意**：v0.3.6 之前的版本文档中错误标注为 Apache 2.0。LICENSE 文件始终包含 AGPLv3 文本。资料来源：[README.md]()\n\n项目由 [Rishi Meka](https://github.com/rishimeka) 在 [Astrix Labs](https://astrixlabs.ai) 创建，目标是构建 LLM 与记忆之间的智能层。资料来源：[README.md]()\n\n---\n\n<a id='page-installation'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/rishimeka/genesys/blob/main/pyproject.toml)\n- [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n</details>\n\n# 安装指南\n\n本页面详细说明如何在不同环境下安装和配置 Genesys 内存系统。Genesys 支持多种存储后端和嵌入提供商，可根据使用场景灵活选择。\n\n## 前提条件\n\n### 系统要求\n\n| 要求 | 规格 |\n|------|------|\n| Python 版本 | 3.11+ |\n| 操作系统 | macOS、Linux、Windows（WSL 推荐） |\n| 内存 | 建议 4GB+ |\n| 磁盘空间 | 约 500MB（不含模型缓存） |\n\n### 必要依赖\n\n安装前需确保系统已安装以下工具：\n\n- **Python 3.11+** — 可通过 [python.org](https://www.python.org/downloads/) 或系统包管理器安装\n- **pip** — Python 包管理器（通常随 Python 一起安装）\n- **Git** — 用于从源码安装\n\n## 安装方式\n\nGenesys 提供两种主要安装方式：从 PyPI 安装预发布版本，或从源码编译最新版本。\n\n### 方式一：从 PyPI 安装（推荐）\n\n```bash\n# 基础安装（仅内置内存后端）\npip install genesys-memory\n\n# 生产环境（Postgres 后端）\npip install 'genesys-memory[postgres]'\n\n# Obsidian 集成\npip install 'genesys-memory[obsidian]'\n\n# Obsidian + 本地嵌入（无需 API Key）\npip install 'genesys-memory[obsidian,local]'\n\n# FalkorDB 图形数据库后端\npip install 'genesys-memory[falkordb]'\n\n# 开发环境（包含测试依赖）\npip install 'genesys-memory[dev]'\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方式二：从源码安装\n\n适用于需要最新功能或进行开发贡献的用户：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 以开发模式安装（包含所有依赖）\npip install -e '.[dev]'\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 存储后端选择\n\nGenesys 采用插件化架构，支持多种存储后端。选择合适的后端取决于具体使用场景：\n\n| 后端 | 安装命令 | 适用场景 | 依赖 |\n|------|----------|----------|------|\n| **memory** | 内置，无需额外安装 | 快速体验、零依赖 | 无 |\n| **postgres** | `pip install 'genesys-memory[postgres]'` | 生产环境、持久化存储 | PostgreSQL + pgvector |\n| **obsidian** | `pip install 'genesys-memory[obsidian]'` | 本地知识库、个人笔记 | Obsidian Vault |\n| **falkordb** | `pip install 'genesys-memory[falkordb]'` | 图原生查询、大规模关系 | FalkorDB (Redis-based) |\n\n### 后端架构概览\n\n```mermaid\ngraph TB\n    subgraph \"存储后端层\"\n        MEM[memory<br/>内置字典]\n        PG[postgres + pgvector]\n        OBS[Obsidian Vault]\n        FALK[FalkorDB]\n    end\n    \n    subgraph \"核心引擎层\"\n        ENG[评分引擎]\n        CAU[因果图]\n        LCM[生命周期管理器]\n    end\n    \n    subgraph \"API 层\"\n        MCP[MCP 协议接口]\n        REST[REST API]\n    end\n    \n    MEM --> ENG\n    PG --> ENG\n    OBS --> ENG\n    FALK --> ENG\n    \n    ENG --> CAU\n    CAU --> LCM\n    \n    MCP --> ENG\n    REST --> ENG\n```\n\n## 配置指南\n\n### 环境变量配置\n\n将 `.env.example` 复制为 `.env` 文件，并配置以下变量：\n\n```bash\ncp .env.example .env\n```\n\n### 配置参数详解\n\n| 变量名 | 是否必需 | 默认值 | 说明 |\n|--------|----------|--------|------|\n| `OPENAI_API_KEY` | 否* | — | OpenAI API 密钥，用于生成嵌入向量 |\n| `ANTHROPIC_API_KEY` | 否 | — | Anthropic API 密钥，用于 LLM 内存处理 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供商：`openai` 或 `local` |\n| `DATABASE_URL` | 条件必需 | — | PostgreSQL 连接字符串（使用 postgres 后端时） |\n| `OBSIDIAN_VAULT_PATH` | 条件必需 | — | Obsidian 保险库路径（使用 obsidian 后端时） |\n| `FALKORDB_HOST` | 条件必需 | `localhost` | FalkorDB 主机地址（使用 falkordb 后端时） |\n| `GENESYS_USER_ID` | 否 | — | 单租户模式的默认用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | — | 内存后端状态持久化文件路径 |\n\n*使用 `GENESYS_EMBEDDER=local` 时不需要 `OPENAI_API_KEY`\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)、[.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n\n## 快速启动方案\n\n### 方案一：内存模式（零依赖）\n\n适用于快速体验和开发测试：\n\n```bash\n# 安装基础包\npip install genesys-memory\n\n# 创建配置文件\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=memory\n```\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案二：Postgres + pgvector（生产环境）\n\n适用于需要持久化存储的生产部署：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[postgres]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=postgres\nDATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys\n```\n\n启动 PostgreSQL 并运行迁移：\n\n```bash\n# 使用 Docker 启动 Postgres\ndocker compose up -d postgres\n\n# 运行数据库迁移\nalembic upgrade head\n\n# 启动服务器\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案三：Obsidian Vault（本地优先）\n\n将 Obsidian 笔记库转换为 Genesys 记忆存储：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[obsidian]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=obsidian\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n```\n\n**自动检测功能**：如果未设置 `OBSIDIAN_VAULT_PATH`，Genesys 会自动在以下位置查找：\n- `~/Documents/personal`\n- `~/Documents/Obsidian`\n- `~/obsidian`\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n首次启动时，Genesys 会自动索引保险库中的所有 `.md` 文件。文件监视器会在编辑笔记时增量重新索引。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案四：完全本地模式（无需 API Key）\n\n使用本地嵌入模型，无需任何外部 API：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[obsidian,local]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n# 无需 OPENAI_API_KEY\n```\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n**本地嵌入模型**：`all-MiniLM-L6-v2`（384 维），首次使用时会自动下载（约 80MB）。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案五：FalkorDB（图原生）\n\n适用于需要原生图遍历的大规模关系数据：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[falkordb]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=falkordb\nFALKORDB_HOST=localhost\n```\n\n启动 FalkorDB 和服务器：\n\n```bash\n# 使用 Docker 启动 FalkorDB\ndocker compose up -d falkordb\n\n# 启动服务器\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## Docker 部署\n\n### 使用 Docker Compose 启动服务\n\n项目提供了 `docker-compose.yml` 文件，可一键启动完整环境：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 启动所有服务（包括 Postgres）\ndocker compose up -d\n\n# 或仅启动 Postgres\ndocker compose up -d postgres\n```\n\n### 环境变量配置\n\n在使用 Docker 部署时，确保 `docker-compose.yml` 中的环境变量配置正确。典型的环境变量包括：\n\n```yaml\nenvironment:\n  - OPENAI_API_KEY=${OPENAI_API_KEY}\n  - GENESYS_BACKEND=postgres\n  - DATABASE_URL=postgresql://genesys:genesys@postgres:5432/genesys\n```\n\n资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n\n## 验证安装\n\n### 启动服务器验证\n\n服务器成功启动后，应看到类似输出：\n\n```\nINFO:     Uvicorn running on http://0.0.0.0:8000\nINFO:     Application startup complete.\n```\n\n### MCP 工具列表\n\n启动后可通过以下端点查看可用工具：\n\n```\nGET http://localhost:8000/mcp\n```\n\n可用工具包括：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory_store` | 存储新记忆，可选择链接相关记忆 |\n| `memory_recall` | 通过自然语言查询回忆记忆（向量 + 图搜索） |\n| `memory_search` | 按状态、日期、关键词筛选搜索 |\n| `memory_traverse` | 从给定记忆节点遍历因果图 |\n| `memory_explain` | 解释记忆存在的原因及其因果链 |\n| `memory_stats` | 获取记忆系统统计信息 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定记忆 |\n| `delete_memory` | 永久删除记忆 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆类别偏好 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 连接到 AI 助手\n\n### Claude Desktop 配置\n\n在 `claude_desktop_config.json` 中添加配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n### 通用 MCP 客户端\n\n直接指向 MCP 端点：\n\n```\nhttp://localhost:8000/mcp\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 开发环境安装\n\n如需为 Genesys 项目贡献代码，请按以下步骤设置开发环境：\n\n### 1. 克隆并安装\n\n```bash\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\npip install -e '.[dev]'\n```\n\n### 2. 代码质量工具\n\n项目使用以下工具维护代码质量：\n\n```bash\n# 代码检查\nruff check src/\n\n# 类型检查\nmypy src/genesys_memory --ignore-missing-imports\n\n# 运行测试\npytest tests/ -v\n\n# 带覆盖率报告的测试\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n### 3. 代码规范\n\n- **Python 版本**：3.11+\n- **异步优先**：使用 async/await 模式\n- **类型提示**：全程使用类型注解\n- **行长度限制**：120 字符（配置于 `pyproject.toml`）\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| `ImportError: No module named 'genesys_memory'` | 确保已正确安装：`pip install genesys-memory` |\n| `OPENAI_API_KEY` 错误 | 检查 `.env` 文件中的 API Key 是否正确，或使用本地嵌入模式 |\n| Postgres 连接失败 | 确认 Docker 容器运行中，检查 `DATABASE_URL` 格式 |\n| Obsidian 索引失败 | 确认 `OBSIDIAN_VAULT_PATH` 路径存在且包含 `.md` 文件 |\n| 端口 8000 被占用 | 使用 `--port` 参数指定其他端口，如 `--port 8001` |\n\n### 状态持久化\n\n如需在进程重启后保留内存后端数据，设置持久化路径：\n\n```env\nGENESYS_PERSIST_PATH=.genesys_state.json\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 依赖项参考\n\n### 核心依赖\n\n从 `pyproject.toml` 中提取的核心依赖包括：\n\n- `fastapi` — Web 框架\n- `uvicorn` — ASGI 服务器\n- `pydantic` — 数据验证\n- `numpy` — 数值计算\n- `httpx` — HTTP 客户端\n- `anthropic` — Anthropic API 集成\n- `openai` — OpenAI API 集成\n- `sqlalchemy` — ORM 框架\n- `alembic` — 数据库迁移\n- `psycopg2-binary` — PostgreSQL 驱动\n\n### 可选依赖组\n\n| 组名 | 主要依赖 | 用途 |\n|------|----------|------|\n| `postgres` | `psycopg2-binary`, `alembic` | PostgreSQL 存储后端 |\n| `obsidian` | `watchfiles` | Obsidian 笔记集成 |\n| `local` | `sentence-transformers` | 本地嵌入模型 |\n| `falkordb` | `redis`, `falkordb` | FalkorDB 图形数据库 |\n| `dev` | `pytest`, `ruff`, `mypy` | 开发工具 |\n\n## 下一步\n\n安装完成后，建议：\n\n1. **运行演示脚本**：使用 `seed_demo.py` 填充示例数据\n2. **阅读架构文档**：了解 Genesys 的评分引擎和生命周期管理\n3. **探索 MCP 工具**：尝试不同的记忆操作\n4. **贡献代码**：查看 [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md) 了解贡献流程\n\n---\n\n<a id='page-quickstart'></a>\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [MCP 工具集](#page-mcp-tools)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n</details>\n\n# 快速开始\n\nGenesys 是一个面向 AI Agent 的记忆引擎，提供因果图谱、评分系统和生命周期管理功能。通过 MCP（Model Context Protocol）协议与 AI 助手原生集成，支持多种存储后端以适应不同场景需求。资料来源：[README.md:1-15]()\n\n## 系统架构概览\n\n```mermaid\ngraph TD\n    subgraph \"客户端层\"\n        Claude_Desktop[\"Claude Desktop\"]\n        Claude_Code[\"Claude Code\"]\n        其他MCP客户端[\"其他 MCP 客户端\"]\n    end\n    \n    subgraph \"Genesys 服务层\"\n        API[\"FastAPI / Uvicorn\"]\n        MCPServer[\"MCP Server\"]\n        Engine[\"记忆引擎\"]\n    end\n    \n    subgraph \"存储后端\"\n        Memory[\"In-Memory\"]\n        Postgres[\"Postgres + pgvector\"]\n        Obsidian[\"Obsidian Vault\"]\n        FalkorDB[\"FalkorDB\"]\n    end\n    \n    Claude_Desktop --> MCPServer\n    Claude_Code --> MCPServer\n    其他MCP客户端 --> MCPServer\n    API --> MCPServer\n    MCPServer --> Engine\n    Engine --> Memory\n    Engine --> Postgres\n    Engine --> Obsidian\n    Engine --> FalkorDB\n```\n\n## 前置要求\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | 3.11+ |\n| Docker（可选） | 用于 Postgres、FalkorDB 等后端 |\n| API 密钥 | OpenAI API Key（使用 `GENESYS_EMBEDDER=local` 时可选） |\n\n资料来源：[CONTRIBUTING.md:1-10]()\n\n## 安装方式\n\n### 方式一：pip 安装（推荐）\n\n```bash\n# 基础安装（内置内存存储）\npip install genesys-memory\n\n# 安装特定存储后端\npip install 'genesys-memory[postgres]'      # Postgres + pgvector\npip install 'genesys-memory[obsidian]'      # Obsidian Vault\npip install 'genesys-memory[obsidian,local]' # 完全本地化\npip install 'genesys-memory[falkordb]'       # FalkorDB 图数据库\n```\n\n资料来源：[README.md:1-50]()\n\n### 方式二：从源码安装\n\n```bash\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\npip install -e '.[dev]'\n```\n\n资料来源：[CONTRIBUTING.md:1-15]()\n\n### 方式三：Docker 部署\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 启动完整服务栈（包括 Postgres）\ndocker compose up -d\n```\n\n资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n\n## 环境配置\n\n### 配置文件创建\n\n```bash\ncp .env.example .env\n```\n\n资料来源：[README.md:50-100]()\n\n### 环境变量说明\n\n| 变量名 | 必填 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `OPENAI_API_KEY` | 否* | Embedding 生成密钥 | - |\n| `ANTHROPIC_API_KEY` | 否 | LLM 记忆处理密钥 | - |\n| `GENESYS_BACKEND` | 否 | 存储后端类型 | `memory` |\n| `GENESYS_EMBEDDER` | 否 | Embedding 提供商 | `openai` |\n| `DATABASE_URL` | postgres 时必填 | Postgres 连接字符串 | - |\n| `OBSIDIAN_VAULT_PATH` | obsidian 时必填 | Obsidian 仓库路径 | - |\n| `FALKORDB_HOST` | falkordb 时必填 | FalkorDB 主机地址 | `localhost` |\n| `GENESYS_USER_ID` | 否 | 单租户模式默认用户 ID | - |\n| `GENESYS_PERSIST_PATH` | 否 | 内存后端持久化路径 | - |\n\n*使用 `GENESYS_EMBEDDER=local` 时不需要\n\n资料来源：[README.md:100-120](), [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n\n## 启动服务器\n\n### 使用 uvicorn 启动\n\n```bash\n# 默认内存模式（零依赖）\nuvicorn genesys.api:app --port 8000\n\n# 指定后端\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md:50-80]()\n\n### 使用 Docker 启动\n\n```bash\n# 构建镜像\ndocker build -t genesys-memory .\n\n# 运行容器\ndocker run -p 8000:8000 \\\n  -e OPENAI_API_KEY=sk-... \\\n  -e GENESYS_BACKEND=memory \\\n  genesys-memory\n```\n\n资料来源：[Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)\n\n## MCP 服务集成\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n资料来源：[README.md:150-160]()\n\n### Claude Desktop 配置\n\n在 `claude_desktop_config.json` 中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n资料来源：[README.md:160-175]()\n\n### 其他 MCP 客户端\n\n直接连接到 MCP 端点：\n\n```\nhttp://localhost:8000/mcp\n```\n\n## MCP 工具列表\n\nGenesys 提供以下 MCP 工具用于记忆管理：\n\n| 工具名称 | 功能描述 | 必需参数 |\n|----------|----------|----------|\n| `memory_store` | 存储新记忆，可选关联相关记忆 | `content` |\n| `memory_recall` | 混合搜索召回记忆（向量+关键词+图传播） | `query` |\n| `memory_search` | 按状态、分类、日期等条件过滤搜索 | `query` |\n| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id` |\n| `memory_explain` | 解释记忆的评分细节和因果链 | `node_id` |\n| `memory_stats` | 获取图谱统计信息 | - |\n| `pin_memory` | 将记忆固定为核心记忆 | `node_id` |\n| `unpin_memory` | 取消固定并重新评估核心资格 | `node_id` |\n| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |\n| `list_core_memories` | 列出所有核心记忆 | `category`（可选） |\n| `set_core_preferences` | 配置核心记忆分类偏好 | `auto`, `approval`, `excluded` |\n\n资料来源：[README.md:130-150](), [src/genesys_memory/server.py:1-80]()\n\n## 记忆数据模型\n\n```mermaid\nclassDiagram\n    class MemoryNode {\n        uuid id\n        MemoryStatus status\n        str content_summary\n        str content_full\n        list~float~ embedding\n        datetime created_at\n        datetime last_accessed_at\n        float decay_score\n        int causal_weight\n        int reactivation_count\n        bool pinned\n        str category\n    }\n    \n    class MemoryEdge {\n        uuid source_id\n        uuid target_id\n        EdgeType type\n        float weight\n    }\n    \n    MemoryNode \"1\" --> \"*\" MemoryEdge : edges\n```\n\n资料来源：[src/genesys_memory/models/node.py:1-40]()\n\n### MemoryNode 核心字段\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID\n    status: MemoryStatus  # ACTIVE, DORMANT, FADING, PRUNED\n    content_summary: str  # 最大 200 字符\n    content_full: str | None\n    embedding: list[float] | None\n    decay_score: float = 1.0\n    causal_weight: int = 0\n    reactivation_count: int = 0\n    pinned: bool = False\n    category: str | None\n    stability: float = 1.0\n```\n\n资料来源：[src/genesys_memory/models/node.py:10-35]()\n\n## 存储后端对比\n\n| 后端 | 安装命令 | 适用场景 |\n|------|----------|----------|\n| `memory` | 内置 | 零依赖、快速试用 |\n| `postgres` + pgvector | `pip install 'genesys-memory[postgres]'` | 生产环境、高可用 |\n| `obsidian` | `pip install 'genesys-memory[obsidian]'` | 本地优先、知识库 |\n| `falkordb` | `pip install 'genesys-memory[falkordb]'` | 图原生遍历 |\n\n资料来源：[README.md:80-95]()\n\n## Postgres 后端启动流程\n\n```bash\n# 1. 安装依赖\npip install 'genesys-memory[postgres]'\n\n# 2. 编辑 .env\necho \"OPENAI_API_KEY=sk-...\" >> .env\necho \"GENESYS_BACKEND=postgres\" >> .env\necho \"DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys\" >> .env\n\n# 3. 启动 Postgres\ndocker compose up -d postgres\n\n# 4. 运行数据库迁移\nalembic upgrade head\n\n# 5. 启动服务\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md:95-115]()\n\n## 完全本地化配置（无需 API 密钥）\n\n```bash\n# 1. 安装\npip install 'genesys-memory[obsidian,local]'\n\n# 2. 配置 .env\necho \"GENESYS_BACKEND=obsidian\" >> .env\necho \"GENESYS_EMBEDDER=local\" >> .env\necho \"OBSIDIAN_VAULT_PATH=/path/to/your/vault\" >> .env\n\n# 3. 启动服务\nuvicorn genesys.api:app --port 8000\n```\n\n使用 `all-MiniLM-L6-v2`（384 维）模型进行 Embedding，首次使用自动下载（约 80MB）。\n\n资料来源：[README.md:30-50]()\n\n## 记忆生命周期\n\n```mermaid\nstateDiagram-v2\n    [*] --> ACTIVE: 创建\n    ACTIVE --> DORMANT: 衰减评分下降\n    DORMANT --> ACTIVE: 重新激活\n    DORMANT --> FADING: 持续未访问\n    FADING --> DORMANT: 被召回\n    FADING --> PRUNED: 评分归零\n    ACTIVE --> ACTIVE: 定期访问\n```\n\n### 评分公式\n\n记忆评分由三个因素相乘决定：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n- **Relevance（相关性）**：随时间衰减\n- **Connectivity（连接性）**：基于因果边数量\n- **Reactivation（再激活）**：基于访问频率\n\n资料来源：[README.md:175-195]()\n\n## 测试验证\n\n```bash\n# 运行所有测试\npytest tests/ -v\n\n# 带覆盖率报告\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n资料来源：[CONTRIBUTING.md:20-30]()\n\n## 快速启动模板\n\n将以下内容复制给 Claude 即可自动完成配置：\n\n> \"Install genesys-memory, create a .env with my OpenAI key, start the server on port 8000 with the in-memory backend, and connect it as an MCP server.\"\n\n资料来源：[README.md:60-70]()\n\n## 下一步\n\n- 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发规范\n- 访问 [benchmarks/](https://github.com/rishimeka/genesys/tree/main/benchmarks) 了解性能基准\n- 阅读 [LICENSE](LICENSE) 了解开源协议（AGPL-3.0）\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据模型](#page-data-models), [存储后端实现](#page-storage-backends)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)\n- [src/genesys_memory/engine/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/__init__.py)\n- [src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)\n- [src/genesys_memory/providers.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/providers.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n</details>\n\n# 系统架构\n\n## 概述\n\nGenesys 是一个面向 AI Agent 的记忆系统，集成了**评分引擎**、**因果图**和**生命周期管理器**三大核心功能。它通过 MCP（Model Context Protocol）协议与 AI 进行原生交互，支持多种存储后端，能够模拟人类记忆的遗忘机制，对记忆进行动态管理和智能遗忘。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心架构组件\n\nGenesys 的系统架构由以下主要模块组成：\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| **Engine** | `src/genesys_memory/engine/` | 核心评分引擎和记忆处理逻辑 |\n| **Storage** | `src/genesys_memory/storage/` | 存储后端抽象和实现 |\n| **Models** | `src/genesys_memory/models/` | 数据模型定义 |\n| **MCP** | `src/genesys_memory/mcp/` | MCP 协议工具实现 |\n| **Core Memory** | `src/genesys_memory/core_memory/` | 核心记忆管理 |\n\n资料来源：[src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)\n\n### 架构分层图\n\n```mermaid\ngraph TB\n    subgraph \"表现层 (MCP Interface)\"\n        MCP[MCP Server]\n        TOOLS[MCP Tools]\n    end\n    \n    subgraph \"核心引擎层 (Engine)\"\n        SCORING[Scoring Engine]\n        LIFECYCLE[Lifecycle Manager]\n        CONSOLIDATION[Consolidation Engine]\n        LLM_PROVIDER[LLM Provider]\n    end\n    \n    subgraph \"存储层 (Storage)\"\n        GRAPH[Graph Storage Provider]\n        CACHE[Cache Provider]\n        EMBEDDING[Embedding Provider]\n        EVENT[Event Bus Provider]\n    end\n    \n    subgraph \"后端实现\"\n        MEMORY[In-Memory Backend]\n        POSTGRES[Postgres + pgvector]\n        OBSIDIAN[Obsidian Vault]\n        FALKOR[FalkorDB]\n    end\n    \n    MCP --> TOOLS\n    TOOLS --> SCORING\n    SCORING --> LIFECYCLE\n    CONSOLATION --> LLM_PROVIDER\n    LLM_PROVIDER --> SCORING\n    \n    SCORING --> GRAPH\n    GRAPH --> CACHE\n    GRAPH --> EMBEDDING\n    \n    GRAPH --> MEMORY\n    GRAPH --> POSTGRES\n    GRAPH --> OBSIDIAN\n    GRAPH --> FALKOR\n```\n\n## 数据模型\n\n### MemoryNode 核心结构\n\n`MemoryNode` 是系统的核心数据模型，定义了一条记忆的所有属性：\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID = Field(default_factory=uuid.uuid4)\n    status: MemoryStatus = MemoryStatus.ACTIVE\n    content_summary: str = Field(max_length=200)\n    content_full: str | None = None\n    content_ref: str | None = None\n    embedding: list[float] | None = None\n    \n    # 时间戳\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n    \n    # 生命周期评分\n    decay_score: float = 1.0      # 衰减分数\n    causal_weight: int = 0        # 因果权重\n    reactivation_count: int = 0   # 激活次数\n    reactivation_pattern: ReactivationPattern  # 激活模式\n    irrelevance_counter: int = 0   # 无关计数器\n    \n    # 分类\n    entity_refs: list[str]        # 实体引用\n    category: str | None          # 类别\n    \n    # 稳定性\n    stability: float = 1.0        # 稳定性（记忆提取成功后增加）\n    \n    # 核心记忆\n    pinned: bool = False          # 是否固定\n    promotion_reason: str | None  # 晋升原因\n```\n\n资料来源：[src/genesys_memory/models/node.py:1-45](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 记忆状态机\n\n记忆在生命周期中经历以下状态转换：\n\n```mermaid\ngraph LR\n    STORE[STORE] --> ACTIVE[ACTIVE]\n    ACTIVE --> DORMANT[DORMANT]\n    DORMANT --> FADING[FADING]\n    FADING --> PRUNED[PRUNED]\n    \n    ACTIVE -.->|reactivation| ACTIVE\n    DORMANT -.->|reactivation| ACTIVE\n    FADING -.->|reactivation| ACTIVE\n    \n    PRUNED -.->|特殊条件| PRUNED\n```\n\n状态说明：\n\n| 状态 | 描述 | 触发条件 |\n|------|------|----------|\n| **STORE** | 初始存储状态 | 新记忆创建时 |\n| **ACTIVE** | 活跃状态 | 记忆被频繁访问 |\n| **DORMANT** | 休眠状态 | 长时间未被访问 |\n| **FADING** | 衰减状态 | decay_score 接近零 |\n| **PRUNED** | 修剪状态 | 彻底遗忘（可被恢复） |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心引擎\n\n### 评分公式\n\nGenesys 的记忆评分采用**乘法公式**，三个维度相乘得出最终分数：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 维度 | 说明 | 衰减特性 |\n|------|------|----------|\n| **relevance** | 相关性 | 随时间衰减，久未强化则消失 |\n| **connectivity** | 连接性 | 奖励因果链接多的记忆，枢纽记忆存活 |\n| **reactivation** | 再激活 | 频繁回忆的记忆得到强化 |\n\n由于采用乘法公式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆会衰减；频繁回忆但无因果链接的记忆也会消失。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### LLM Provider\n\nLLM Provider 负责使用大语言模型进行因果关系识别和记忆整合：\n\n```python\nasync def identify_causal_relationships(\n    new_memory: str,\n    existing_memories: list[tuple[str, str]]\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"识别新记忆与已有记忆之间的因果关系\"\"\"\n    # 返回: (target_id, edge_type, confidence, reason)\n```\n\n**边缘类型**包括：\n- `caused_by` - 因果导致\n- `supports` - 支持关系\n- `derived_from` - 派生关系\n\n资料来源：[src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n\n### Consolidation Engine\n\n整合引擎负责将情景记忆合并为语义记忆：\n\n```mermaid\ngraph TD\n    EPISODIC[Episodic Memories] --> CONSOLIDATE{Consolidation}\n    CONSOLIDATE --> LLM_SUMMARIZE[LLM Summarization]\n    LLM_SUMMARIZE --> SEMANTIC[Semantic Memory Node]\n    \n    CONSOLIDATE --> EDGES[Create DERIVED_FROM Edges]\n    SEMANTIC --> EDGES\n    EDGES --> GRAPH[Graph Storage]\n```\n\n资料来源：[src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n\n## 存储层架构\n\n### 抽象接口设计\n\n存储层通过抽象接口支持多种后端实现：\n\n| 接口 | 职责 |\n|------|------|\n| **GraphStorageProvider** | 图结构存储（节点和边） |\n| **CacheProvider** | 缓存层 |\n| **EmbeddingProvider** | 向量化嵌入生成 |\n| **EventBusProvider** | 事件总线 |\n\n资料来源：[src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)\n\n### 支持的存储后端\n\n```mermaid\ngraph LR\n    subgraph \"存储后端对比\"\n        MEMORY[In-Memory<br/>零依赖]\n        PG[Postgres + pgvector<br/>持久化/可扩展]\n        OBS[Obsidian Vault<br/>本地知识库]\n        FALK[FalkorDB<br/>图原生]\n        CUSTOM[Custom<br/>自定义实现]\n    end\n```\n\n| 后端 | 安装选项 | 使用场景 |\n|------|----------|----------|\n| `memory` | 内置 | 零依赖，快速试用 |\n| `postgres` | `genesys-memory[postgres]` | 持久化、可扩展 |\n| `obsidian` | `genesys-memory[obsidian]` | 本地优先知识库 |\n| `falkordb` | `genesys-memory[falkordb]` | 图原生遍历 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## MCP 协议集成\n\n### MCP Server 实现\n\nGenesys 通过 FastMCP 实现 MCP 协议服务：\n\n```python\n@app.list_tools()\nasync def list_tools() -> list[Tool]:\n    return _TOOL_SCHEMAS\n\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:\n    if name not in _TOOL_DISPATCH:\n        return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n    return await _TOOL_DISPATCH[name](**arguments)\n```\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n### MCP 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory_store` | 存储新记忆，可选择关联相关记忆 |\n| `memory_recall` | 通过自然语言查询召回记忆（向量+图混合搜索） |\n| `memory_search` | 按状态、日期、关键词过滤搜索 |\n| `memory_traverse` | 从给定节点遍历因果图 |\n| `memory_explain` | 解释记忆存在的原因及其因果链 |\n| `memory_stats` | 获取记忆系统统计信息 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定记忆 |\n| `delete_memory` | 永久删除记忆及其所有边 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆类别偏好 |\n| `promote_to_org` | 将私人记忆提升为组织可见 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n## 请求流程\n\n### 记忆存储流程\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant MCP_Server\n    participant Scoring_Engine\n    participant LLM_Provider\n    participant Graph_Storage\n    \n    Client->>MCP_Server: memory_store(content)\n    MCP_Server->>Scoring_Engine: create_node()\n    Scoring_Engine->>LLM_Provider: identify_causal_relationships()\n    LLM_Provider-->>Scoring_Engine: 返回因果边列表\n    Scoring_Engine->>Graph_Storage: create_node + create_edges\n    Graph_Storage-->>Scoring_Engine: node_id\n    Scoring_Engine-->>MCP_Server: 返回结果\n    MCP_Server-->>Client: 记忆存储成功\n```\n\n### 记忆召回流程\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant MCP_Server\n    participant Engine\n    participant Embedding\n    participant Graph\n    \n    Client->>MCP_Server: memory_recall(query)\n    MCP_Server->>Embedding: embed(query)\n    Embedding-->>Engine: query_vector\n    Engine->>Graph: vector_search(query_vector)\n    Engine->>Graph: graph_spanning_activation()\n    Graph-->>Engine: 混合排序结果\n    Engine-->>MCP_Server: 记忆列表\n    MCP_Server-->>Client: 返回召回结果\n```\n\n## 环境配置\n\n### 配置变量表\n\n| 变量名 | 必需 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `OPENAI_API_KEY` | 否* | - | 嵌入生成（除非使用 local） |\n| `ANTHROPIC_API_KEY` | 否 | - | LLM 记忆处理 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |\n| `DATABASE_URL` | postgres | - | Postgres 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | obsidian | - | Obsidian 库路径 |\n| `FALKORDB_HOST` | falkordb | `localhost` | FalkorDB 主机 |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |\n\n*除非 `GENESYS_EMBEDDER=local`\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 扩展机制\n\n### 自定义存储后端\n\n通过实现 `GraphStorageProvider` 接口，可以接入自定义存储：\n\n```python\nclass GraphStorageProvider(Protocol):\n    async def create_node(self, node: MemoryNode) -> str: ...\n    async def create_edge(self, edge: MemoryEdge) -> str: ...\n    async def get_node(self, node_id: str) -> MemoryNode | None: ...\n    async def get_neighbors(self, node_id: str) -> list[MemoryNode]: ...\n    async def search(self, embedding: list[float], k: int) -> list[MemoryNode]: ...\n```\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n## 总结\n\nGenesys 采用**模块化分层架构**，将表现层、核心引擎层和存储层解耦。核心的评分引擎通过乘法公式模拟人类记忆的遗忘机制，MCP 协议实现了与 AI Agent 的无缝集成，而灵活的存储抽象支持从内存到分布式图数据库的多种部署方式。\n\n---\n\n<a id='page-data-models'></a>\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [记忆生命周期](#page-memory-lifecycle)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n- [src/genesys_memory/models/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/__init__.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n</details>\n\n# 数据模型\n\n## 概述\n\nGenesys 的数据模型是记忆系统的基础层，采用图结构来组织和关联 AI 代理的记忆。与传统的纯向量存储不同，Genesys 通过**节点（MemoryNode）** 和**边（MemoryEdge）** 构建因果图，使记忆能够表达语义关联、因果关系和激活历史。\n\n数据模型的核心设计目标：\n\n- **语义记忆**：通过向量嵌入实现相似性检索\n- **因果关联**：通过边表达记忆之间的因果、支持和衍生关系\n- **生命周期管理**：支持记忆的状态转换和自动遗忘机制\n- **权限控制**：支持个人记忆和组织记忆的可见性管理\n\n```mermaid\ngraph TB\n    subgraph 数据模型层\n        Node[MemoryNode<br/>记忆节点]\n        Edge[MemoryEdge<br/>记忆边]\n        Enums[枚举类型<br/>MemoryStatus<br/>EdgeType<br/>ReactivationPattern]\n    end\n    \n    subgraph 存储后端\n        PG[(Postgres<br/>+ pgvector)]\n        SQLite[(SQLite)]\n        FalkorDB[(FalkorDB)]\n        Obsidian[(Obsidian Vault)]\n    end\n    \n    Node --> Edge\n    Enums --> Node\n    Enums --> Edge\n    \n    Node --> PG\n    Node --> SQLite\n    Node --> FalkorDB\n    Node --> Obsidian\n```\n\n资料来源：[src/genesys_memory/models/__init__.py:1-9]()\n\n## 核心模型\n\n### MemoryNode（记忆节点）\n\nMemoryNode 是 Genesys 中存储单个记忆的基本单元。每个节点包含记忆的内容、元数据、时间戳、嵌入向量和状态信息。\n\n```mermaid\nclassDiagram\n    class MemoryNode {\n        +UUID id\n        +str content_summary\n        +str content_full\n        +list~float~ embedding\n        +MemoryStatus status\n        +Visibility visibility\n        +str category\n        +datetime created_at\n        +datetime last_accessed_at\n        +datetime last_reactivated_at\n        +float relevance_score\n        +float connectivity_score\n        +float reactivation_count\n        +bool is_pinned\n        +bool is_core\n        +str org_id\n        +str original_user_id\n        +list~str~ entity_refs\n        +list~ReactivationPattern~ reactivation_patterns\n    }\n```\n\n#### 节点核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 节点唯一标识符 |\n| `content_summary` | str | 记忆摘要（用于语义检索显示） |\n| `content_full` | str | 完整记忆内容 |\n| `embedding` | list[float] | 向量嵌入（用于相似性检索） |\n| `status` | MemoryStatus | 当前记忆状态 |\n| `visibility` | Visibility | 可见性：个人/组织 |\n| `category` | str | 记忆分类（可选） |\n| `created_at` | datetime | 创建时间戳 |\n| `last_accessed_at` | datetime | 最后访问时间 |\n| `last_reactivated_at` | datetime | 最后重新激活时间 |\n| `relevance_score` | float | 关联度评分（0-1） |\n| `connectivity_score` | float | 连接度评分（基于边数量） |\n| `reactivation_count` | int | 重新激活次数 |\n| `is_pinned` | bool | 是否被固定 |\n| `is_core` | bool | 是否为核心记忆 |\n| `org_id` | str | 组织ID（组织记忆时需要） |\n| `original_user_id` | str | 原始创建者ID |\n| `entity_refs` | list[str] | 实体引用列表 |\n| `reactivation_patterns` | list[ReactivationPattern] | 重新激活模式历史 |\n\n资料来源：[src/genesys_memory/models/node.py]()\n\n### MemoryEdge（记忆边）\n\nMemoryEdge 表示两个记忆节点之间的关系，边具有类型、权重和创建原因。\n\n#### 边属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 边唯一标识符 |\n| `source_id` | UUID | 源节点ID |\n| `target_id` | UUID | 目标节点ID |\n| `type` | EdgeType | 边类型（因果/支持/衍生等） |\n| `weight` | float | 边权重（0-1） |\n| `reason` | str | 创建原因描述 |\n| `created_by` | str | 创建方式（user_explicit/auto_link） |\n| `created_at` | datetime | 创建时间戳 |\n\n资料来源：[src/genesys_memory/models/edge.py]()\n\n## 枚举类型\n\n### MemoryStatus（记忆状态）\n\n记忆在生命周期中可能处于以下状态：\n\n```mermaid\nstateDiagram-v2\n    [*] --> STORE: 创建新记忆\n    STORE --> ACTIVE: 首次激活/关联\n    ACTIVE --> DORMANT: 长时间未访问\n    DORMANT --> ACTIVE: 被重新激活\n    DORMANT --> FADING: 持续衰减\n    FADING --> FADING: 评分继续下降\n    FADING --> PRUNED: 评分归零/孤立/非固定\n    ACTIVE --> FADING: 评分急剧下降\n    PRUNED --> [*]\n```\n\n| 状态值 | 说明 | 触发条件 |\n|--------|------|----------|\n| `STORE` | 存储态 | 新记忆创建后 |\n| `ACTIVE` | 活跃态 | 被访问或有因果关联 |\n| `DORMANT` | 休眠态 | 长时间无访问但有连接 |\n| `FADING` | 衰减态 | 评分持续下降 |\n| `PRUNED` | 修剪态 | 评分归零且可被删除 |\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n### EdgeType（边类型）\n\n| 边类型 | 说明 | 使用场景 |\n|--------|------|----------|\n| `CAUSED_BY` | 因果关系 | 记忆A导致记忆B |\n| `SUPPORTS` | 支持关系 | 记忆A支持/强化记忆B |\n| `DERIVED_FROM` | 衍生关系 | 语义记忆从情景记忆提取 |\n| `RELATED_TO` | 相关关系 | 语义相似的记忆自动关联 |\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n### Visibility（可见性）\n\n| 值 | 说明 |\n|----|------|\n| `PRIVATE` | 仅创建者可见 |\n| `ORG` | 组织成员可见 |\n\n### ReactivationPattern（重新激活模式）\n\n记录记忆被重新激活的方式，用于分析访问模式。\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n## 评分机制\n\nGenesys 采用三因素乘法评分模型决定记忆的生存能力：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因素 | 说明 | 影响因素 |\n|------|------|----------|\n| `relevance` | 关联度 | 时间衰减、内容新鲜度 |\n| `connectivity` | 连接度 | 边数量、边权重总和 |\n| `reactivation` | 重新激活度 | 访问频率、最近访问时间 |\n\n> 由于采用乘法模型，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁访问但因果孤立记忆也会消失。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心记忆机制\n\n核心记忆是系统中结构上重要、被自动固定的记忆，具有以下特性：\n\n- **自动固定**：不会因评分下降而被遗忘\n- **权限保护**：需要明确取消固定才能降级\n- **自动晋升**：满足晋升规则的记忆可自动成为核心记忆\n\n```mermaid\ngraph LR\n    A[普通记忆] --> B{晋升评估}\n    B -->|满足规则| C[核心记忆]\n    B -->|不满足| D[继续评估]\n    C --> E[is_core=True]\n    C --> F[is_pinned=True]\n```\n\n核心记忆的晋升由 `promote_to_org` 函数和权限检查机制控制，支持组织级别的记忆推广。\n\n资料来源：[src/genesys_memory/core_memory/promoter.py]()\n\n## 所有权与权限\n\nGenesys 支持多用户和组织级别的记忆管理：\n\n### 所有权检查逻辑\n\n```python\ndef _caller_owns_node(node: MemoryNode) -> bool:\n    uid = _caller_uid()\n    role = current_user_role.get(None)\n    # 管理员可访问同组织的节点\n    if role == \"admin\" and node.org_id in current_org_ids.get([]):\n        return True\n    # 原始创建者拥有节点\n    if node.original_user_id:\n        return node.original_user_id == uid\n    return True\n```\n\n### 组织边界规则\n\n组织节点只能连接到同一组织的其他节点和边，确保数据隔离：\n\n```python\n# 组织边界规则：org节点只链接到同org节点\nif vis == Visibility.ORG:\n    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:\n        continue\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py:23-40]()\n\n## 存储后端适配\n\n数据模型通过抽象存储接口支持多种后端：\n\n```mermaid\ngraph TB\n    subgraph 存储提供者接口\n        GraphStorageProvider[GraphStorageProvider]\n        EmbeddingProvider[EmbeddingProvider]\n        CacheProvider[CacheProvider]\n        EventBusProvider[EventBusProvider]\n    end\n    \n    subgraph 具体实现\n        PostgresStore[Postgres + pgvector]\n        SQLiteStore[SQLite]\n        FalkorDBStore[FalkorDB]\n        ObsidianStore[Obsidian Vault]\n    end\n    \n    GraphStorageProvider --> PostgresStore\n    GraphStorageProvider --> SQLiteStore\n    GraphStorageProvider --> FalkorDBStore\n    GraphStorageProvider --> ObsidianStore\n```\n\n| 后端 | 存储内容 | 适用场景 |\n|------|----------|----------|\n| 内存 | 内存字典 | 开发测试 |\n| Postgres + pgvector | 向量+关系 | 生产环境 |\n| SQLite | 轻量级索引 | 个人使用 |\n| FalkorDB | 原生图结构 | 图遍历密集型 |\n| Obsidian Vault | Markdown文件 | 本地知识库 |\n\n资料来源：[src/genesys_memory/storage/base.py]()\n\n## 导出模块\n\n模型层通过 `__init__.py` 统一导出核心类：\n\n```python\nfrom genesys_memory.models import (\n    MemoryStatus,\n    EdgeType,\n    ReactivationPattern,\n    MemoryNode,\n    MemoryEdge,\n)\n```\n\n资料来源：[src/genesys_memory/models/__init__.py:1-9]()\n\n## 总结\n\nGenesys 的数据模型以**节点-边**的图结构为核心，通过：\n\n1. **MemoryNode** 存储记忆内容、状态、评分和时间信息\n2. **MemoryEdge** 表达记忆间的语义和因果关系\n3. **MemoryStatus** 管理记忆的生命周期状态转换\n4. **评分机制** 决定记忆的生存或遗忘\n5. **权限系统** 支持个人和组织级别的记忆管理\n\n这种设计使 Genesys 能够在提供向量检索能力的同时，维持对记忆之间关系的深层理解，实现更智能的记忆管理。\n\n---\n\n<a id='page-scoring-engine'></a>\n\n## 评分引擎\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [记忆生命周期](#page-memory-lifecycle)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/engine/config.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/config.py)（配置文件引用）\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n</details>\n\n# 评分引擎\n\n## 概述\n\n评分引擎（Scoring Engine）是 Genesys 记忆系统的核心组件，负责对每条记忆进行多维度评分，以决定其生命周期状态、保留优先级和遗忘时机。评分引擎采用**乘积公式**计算综合得分，确保持续活跃、高度连接、频繁复活的记忆得以保留，而孤立或长期未访问的记忆则逐渐衰减直至被剪枝。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 评分公式\n\n### 三力乘积模型\n\n每条记忆的最终得分由三个因子相乘得出：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因子 | 含义 | 影响因素 |\n|------|------|----------|\n| **relevance**（相关性） | 记忆随时间衰减 | 记忆创建时间、访问频率 |\n| **connectivity**（连接性） | 记忆在因果图中的重要性 | 因果边数量、边权重、因果权重 |\n| **reactivation**（再激活） | 记忆被回忆的频率 | 复活次数、复活时间模式 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 乘积公式的设计逻辑\n\n由于采用乘法模型，记忆必须同时在**三个维度**上都有得分才能保持高分：\n\n- **高连接但从未被访问**：仍然会衰减\n- **频繁回忆但孤立无依**：仍然会消失\n- **最近创建但无关联**：也会逐渐淡出\n\n这种设计确保只有真正重要的记忆才能长期留存。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 记忆生命周期\n\n评分引擎驱动记忆在以下状态之间转换：\n\n```mermaid\ngraph TD\n    A[STORE 存储] --> B[ACTIVE 活跃]\n    B --> C[DORMANT 休眠]\n    C --> D[FADING 消逝]\n    D --> E[PRUNED 剪枝]\n    B -->|reactivation 复活| B\n    C -->|reactivation 复活| B\n    E -->|仅当 score=0, orphan, not pinned| 结束\n```\n\n| 状态 | 说明 | 触发条件 |\n|------|------|----------|\n| **STORE** | 刚创建的初始状态 | 记忆被创建时 |\n| **ACTIVE** | 活跃记忆，可被检索 | 综合得分较高 |\n| **DORMANT** | 休眠记忆，降低检索优先级 | 综合得分下降但未归零 |\n| **FADING** | 消逝中，即将删除 | 得分持续低迷 |\n| **PRUNED** | 已删除 | 得分归零、孤立、无固定 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 评分相关数据模型\n\n### MemoryNode 核心字段\n\n记忆节点模型 `MemoryNode` 包含以下与评分直接相关的字段：\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID\n    status: MemoryStatus  # 生命周期状态\n    \n    # 评分计算因子\n    decay_score: float = 1.0      # 综合衰减得分\n    causal_weight: int = 0        # 因果权重（连接性）\n    reactivation_count: int = 0   # 复活次数\n    \n    # 时间相关\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n    \n    # 稳定性（成功检索后增加，间隔重复算法）\n    stability: float = 1.0\n    \n    # 固定与核心记忆\n    pinned: bool = False          # 是否固定（永不遗忘）\n    promotion_reason: str | None  # 晋升原因\n    \n    # 复活历史\n    reactivation_timestamps: list[datetime]\n```\n\n| 字段 | 类型 | 用途 |\n|------|------|------|\n| `decay_score` | float | 最终综合得分（0.0 - 1.0） |\n| `causal_weight` | int | 因果图中的连接权重 |\n| `reactivation_count` | int | 被回忆的总次数 |\n| `stability` | float | 稳定性（检索成功后增加） |\n| `pinned` | bool | 是否被固定（跳过遗忘逻辑） |\n\n资料来源：[src/genesys_memory/models/node.py:1-50](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 复活模式枚举\n\n```python\nclass ReactivationPattern(Enum):\n    SINGLE       # 单次激活\n    BURST        # 爆发式激活\n    SPACED       # 间隔重复激活\n    DECAYING     # 衰减模式\n```\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n## 引擎配置\n\n评分引擎的行为通过 `engine/config.py` 进行配置，所有阈值均为环境变量可配置，禁止在引擎文件中硬编码魔法数字。\n\n### 配置项管理\n\n| 配置类别 | 说明 |\n|----------|------|\n| 衰减率 | 控制 relevance 随时间的衰减速度 |\n| 连接阈值 | 影响 connectivity 的计算基准 |\n| 复活权重 | 不同复活模式的加分权重 |\n| 稳定性参数 | 间隔重复算法的参数 |\n\n> **注意**：具体的配置参数值和阈值定义在 `engine/config.py` 中，可通过环境变量覆盖默认行为。\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## LLM 驱动的因果关系发现\n\n评分引擎集成了 LLM 提供器来自动识别记忆之间的因果关系，这直接影响 **connectivity** 因子的计算。\n\n### 因果关系发现流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户记忆\n    participant LLM as LLM Provider\n    participant G as 图存储\n    \n    U->>LLM: 发现因果关系 (new_memory, existing_memories)\n    LLM->>LLM: 生成提示词\n    LLM->>LLM: 请求 LLM 分析\n    LLM-->>G: 返回关系列表 (target_id, edge_type, confidence)\n    \n    loop 对于每个关系\n        G->>G: 创建 MemoryEdge\n        G->>G: 更新 causal_weight\n    end\n```\n\n### 边类型定义\n\n| 边类型 | 含义 | 置信度要求 |\n|--------|------|------------|\n| `caused_by` | 因果导致 | > 0.6 |\n| `supports` | 支持关系 | > 0.6 |\n| `derived_from` | 派生关系 | > 0.6 |\n\n```python\nasync def discover_causal_relationships(\n    self,\n    new_memory: str,\n    existing_memories: list[tuple[str, str]],\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"\n    分析新记忆与已有记忆之间的因果关系。\n    仅返回置信度 > 0.6 的关系。\n    \"\"\"\n    # ... 实现逻辑\n```\n\n资料来源：[src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n\n## 核心记忆晋升机制\n\n评分引擎还负责评估记忆是否应晋升为**核心记忆**（Core Memory）。核心记忆具有以下特性：\n\n- **自动固定**：晋升后自动设置为 `pinned=True`\n- **永不剪枝**：即使得分归零也不会被删除\n- **高优先级检索**：在检索结果中优先返回\n\n```python\nfrom genesys_memory.core_memory.promoter import evaluate_core_promotion\n\n# 评估晋升资格\npromotion_result = await evaluate_core_promotion(memory_node)\n```\n\n### MCP 工具接口\n\n评分引擎可通过 MCP 协议调用以下相关工具：\n\n| 工具 | 功能 |\n|------|------|\n| `memory_explain` | 解释记忆的得分构成 |\n| `pin_memory` | 手动固定记忆 |\n| `unpin_memory` | 取消固定并重新评估资格 |\n| `promote_to_core` | 晋升记忆为核心记忆 |\n| `list_core_memories` | 列出所有核心记忆 |\n| `set_core_preferences` | 配置核心记忆偏好 |\n\n资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n\n## 遗忘与剪枝策略\n\n### 遗忘触发条件\n\n记忆被剪枝（Pruned）需要同时满足以下条件：\n\n| 条件 | 说明 |\n|------|------|\n| `score == 0` | 综合得分为零 |\n| `orphan` | 无任何因果边连接 |\n| `not pinned` | 未被固定 |\n\n```python\n# 伪代码示例\nif decay_score == 0 and is_orphan and not pinned:\n    await prune_memory(memory_id)\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 间隔重复与稳定性\n\n评分引擎采用**间隔重复**算法调整记忆的 `stability` 参数：\n\n- 成功检索 → stability 增加\n- 检索失败 → stability 减少\n- stability 影响 decay_score 的计算\n\n这模拟了人类记忆的遗忘曲线，使重要记忆得到强化。\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n## 检索中的评分应用\n\n### 混合检索流程\n\n评分引擎在 `memory_recall` 操作中发挥作用：\n\n```mermaid\ngraph LR\n    A[查询] --> B[向量搜索]\n    A --> C[关键词搜索]\n    B --> D[图传播激活]\n    C --> D\n    D --> E[综合评分排序]\n    E --> F[返回 Top-K 结果]\n```\n\n1. **向量搜索**：基于语义相似度检索\n2. **关键词搜索**：精确匹配关键词\n3. **图传播激活**：从初始节点沿因果边传播激活值\n4. **综合评分排序**：结合原始得分和检索相关性\n\n### 检索参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `k` | 10 | 返回结果数量 |\n| `max_results` | None | 最大结果限制 |\n\n```python\nTool(name=\"memory_recall\", description=\"Recall memories using hybrid search...\", inputSchema={\n    \"type\": \"object\",\n    \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n        \"max_results\": {\"type\": \"integer\"},\n    },\n})\n```\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n## 性能基准\n\n评分引擎在 LoCoMo 长对话记忆基准测试中的表现：\n\n| 类别 | J-Score |\n|------|---------|\n| 单跳查询 | 94.3% |\n| 时间查询 | 87.5% |\n| 多跳查询 | 69.8% |\n| 开放域查询 | 91.7% |\n| **总体** | **89.9%** |\n\n测试配置：Answer model: `gpt-4o-mini` | Judge model: `gpt-4o-mini` | Retrieval k=20\n\n对比基准：Mem0 (67.1%), Zep (75.1%)\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 开发指南\n\n### 添加新评分逻辑\n\n在添加新的评分逻辑时，请遵循以下规范：\n\n1. **配置外置**：所有阈值必须放在 `engine/config.py` 中\n2. **环境变量支持**：通过环境变量覆盖默认配置\n3. **测试覆盖**：在 `tests/` 目录添加对应的测试用例\n4. **严格模式检查**：`mypy src/genesys_memory --ignore-missing-imports` 必须通过\n\n```bash\n# 运行测试\npytest tests/ -v\n\n# 类型检查\nmypy src/genesys_memory --ignore-missing-imports\n\n# 代码检查\nruff check src/\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n### 关键模块耦合\n\n评分引擎与以下模块紧密耦合，修改时需运行完整测试套件：\n\n| 模块 | 职责 |\n|------|------|\n| **scoring** | 评分计算核心逻辑 |\n| **transitions** | 生命周期状态转换 |\n| **forgetting** | 遗忘与剪枝决策 |\n| **promotion** | 核心记忆晋升评估 |\n\n> 修改任一模块后，必须运行 `pytest tests/ -v` 确保无回归。\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 总结\n\n评分引擎是 Genesys 记忆系统的决策中心，通过**乘积公式**将相关性、连接性和再激活三个维度统一量化，驱动记忆的整个生命周期管理。其设计核心思想是：只有同时满足\"持续相关\"、\"高度连接\"、\"频繁使用\"三个条件的记忆才值得长期保留。\n\n这种设计使得 AI 能够在有限的记忆空间中保留最有价值的信息，模拟人类记忆的优先级管理机制，同时通过核心记忆机制确保关键信息永不丢失。\n\n---\n\n<a id='page-memory-lifecycle'></a>\n\n## 记忆生命周期\n\n### 相关页面\n\n相关主题：[评分引擎](#page-scoring-engine), [数据模型](#page-data-models)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n- [src/genesys_memory/engine/reactivation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/reactivation.py)\n- [src/genesys_memory/engine/forgetting.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n</details>\n\n# 记忆生命周期\n\n## 概述\n\n记忆生命周期是 Genesys 记忆引擎的核心管理机制，负责记忆从创建到消亡的完整过程。该系统通过三层评分公式（相关性 × 连接性 × 再激活）对每条记忆进行动态评分，并驱动记忆在不同的生命周期状态之间转换。\n\n**核心设计目标：**\n- 智能遗忘不重要或过时的记忆\n- 通过因果图保留重要记忆的结构完整性\n- 支持核心记忆的自动晋升与保护\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 生命周期状态\n\n记忆在系统中经历以下五种状态：\n\n| 状态 | 说明 | 可被召回 |\n|------|------|----------|\n| `TAGGED` | 新记忆，等待因果链接确认 | ❌ |\n| `ACTIVE` | 活跃状态，参与正常评分 | ✅ |\n| `DORMANT` | 休眠状态，评分较低但保留 | ✅ |\n| `FADING` | 消逝中，等待被清理 | ❌ |\n| `PRUNED` | 已删除，不再存在 | ❌ |\n\n资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n\n### 状态转换图\n\n```mermaid\ngraph TD\n    NEW[新记忆创建] --> TAGGED[TAGGED 标签态]\n    TAGGED -->|形成因果链接| ACTIVE[ACTIVE 活跃态]\n    TAGGED -->|24h无链接| PRUNED[PRUNED 已删除]\n    \n    ACTIVE -->|评分下降| DORMANT[DORMANT 休眠态]\n    ACTIVE -->|高频召回| REACTIVATE[再激活]\n    REACTIVATE --> ACTIVE\n    \n    DORMANT -->|再次召回| ACTIVE\n    DORMANT -->|长期无召回| FADING[FADING 消逝态]\n    \n    FADING -->|评分归零| PRUNED\n    FADING -->|被固定| ACTIVE\n    \n    ACTIVE -->|核心晋升| CORE[核心记忆]\n    CORE -->|永不删除| PERSIST[永久保留]\n    \n    style CORE fill:#90EE90\n    style PRUNED fill:#FFB6C1\n```\n\n## 评分引擎\n\n### 三力评分公式\n\n记忆评分由三个因子相乘得出：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因子 | 作用 | 特性 |\n|------|------|------|\n| **Relevance（相关性）** | 随时间衰减 | 时间越久分数越低，除非被强化 |\n| **Connectivity（连接性）** | 奖励因果链接多的记忆 | 作为枢纽的记忆更易存活 |\n| **Reactivation（再激活）** | 奖励被频繁召回的记忆 | 召回频率影响分数 |\n\n**乘法特性：** 三个因子必须同时较高，记忆才能存活。仅在一两个方面表现良好不足以保证记忆存活。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 评分组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `scoring.py` | `engine/scoring.py` | 计算 decay_score |\n| `transitions.py` | `engine/transitions.py` | 评估状态转换 |\n| `reactivation.py` | `engine/reactivation.py` | 处理召回事件 |\n| `forgetting.py` | `engine/forgetting.py` | 执行记忆删除 |\n\n## 状态转换引擎\n\n### Tagged → Active 转换\n\n当新记忆形成因果链接时，从 TAGGED 状态晋升为 ACTIVE：\n\n```python\nasync def evaluate_transitions(graph, embeddings, llm, context_embedding, context_entities):\n    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)\n    for node in tagged_nodes:\n        if not await graph.is_orphan(str(node.id)):\n            await graph.update_node(str(node.id), {\"status\": MemoryStatus.ACTIVE})\n```\n\n**关键逻辑：**\n- 检查节点是否为孤立节点（orphan）\n- 若存在因果边连接，则触发状态变更\n- 变更原因记录为：`\"consolidation signal: edge formed\"`\n\n资料来源：[src/genesys_memory/engine/transitions.py:14-24](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n\n### Tagged 自动过期\n\n24小时内无因果链接的 TAGGED 记忆自动过期删除：\n\n```python\nage_hours = (datetime.now(timezone.utc) - node.created_at).total_seconds() / 3600\nif age_hours > 24:\n    # 标记为过期\n```\n\n资料来源：[src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n\n### 转换评估流程\n\n```mermaid\ngraph TD\n    START[开始评估] --> GET_STATS[获取图统计]\n    GET_STATS --> GET_TAGGED[获取所有 TAGGED 节点]\n    GET_TAGGED --> IS_ORPHAN{是孤立节点?}\n    \n    IS_ORPHAN -->|是| CHECK_AGE{超过24h?}\n    IS_ORPHAN -->|否| PROMOTE[晋升为 ACTIVE]\n    \n    CHECK_AGE -->|是| EXPIRE[过期处理]\n    CHECK_AGE -->|否| WAIT[等待下次评估]\n    \n    PROMOTE --> RECORD[记录转换原因]\n    EXPIRE --> RECORD\n    RECORD --> DONE[评估完成]\n```\n\n## 再激活机制\n\n### 再激活模式\n\n记忆节点记录其再激活历史，支持多种模式：\n\n| 模式 | 说明 |\n|------|------|\n| `SINGLE` | 单次召回 |\n| `SPACED` | 间隔重复模式 |\n| `BURST` | 突发高频召回 |\n\n资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n\n### 再激活属性\n\n```python\nclass MemoryNode:\n    reactivation_count: int = 0          # 召回次数\n    reactivation_pattern: ReactivationPattern  # 召回模式\n    last_reactivated_at: datetime         # 最后召回时间\n    reactivation_timestamps: list[datetime]  # 历史时间戳\n```\n\n### 再激活评分提升\n\n每次召回都会提升记忆的 decay_score：\n\n```mermaid\ngraph LR\n    RECALL[召回请求] --> CHECK{检查记忆状态}\n    CHECK -->|ACTIVE| BOOST[boost decay_score]\n    CHECK -->|DORMANT| RESTORE[恢复为 ACTIVE]\n    CHECK -->|FADING| RESCUE{是否固定?}\n    \n    RESTORE --> UPDATE_TS[更新再激活时间戳]\n    BOOST --> UPDATE_TS\n    \n    RESCUE -->|是| KEEP[保留记忆]\n    RESCUE -->|否| FADING2[继续消逝流程]\n```\n\n## 遗忘机制\n\n### 遗忘条件\n\n记忆被遗忘（删除）需要满足以下全部条件：\n\n| 条件 | 说明 |\n|------|------|\n| `score = 0` | 评分归零 |\n| `is_orphan` | 是孤立节点（无因果链接） |\n| `not pinned` | 未被固定 |\n\n```python\nasync def forget_memories(graph):\n    for memory in low_score_memories:\n        if memory.pinned:\n            continue\n        if not await graph.is_orphan(memory.id):\n            continue\n        if memory.decay_score > 0:\n            continue\n        await graph.delete_node(memory.id)\n```\n\n资料来源：[src/genesys_memory/engine/forgetting.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)\n\n### 遗忘流程图\n\n```mermaid\ngraph TD\n    START[遗忘评估] --> SCAN[扫描低评分记忆]\n    SCAN --> LOOP{遍历记忆}\n    \n    LOOP -->|固定记忆| SKIP[跳过]\n    LOOP -->|孤立节点| ORPHAN{有因果边?}\n    \n    ORPHAN -->|有边| KEEP[保留]\n    ORPHAN -->|无边| CHECK_SCORE{评分=0?}\n    \n    CHECK_SCORE -->|是| DELETE[删除记忆]\n    CHECK_SCORE -->|否| KEEP\n    \n    SKIP --> NEXT[下一条]\n    KEEP --> NEXT\n    DELETE --> NEXT\n    \n    NEXT --> LOOP\n```\n\n## 核心记忆系统\n\n### 核心记忆特性\n\n核心记忆是结构上重要的记忆，具有以下特性：\n\n- **自动固定**：晋升为核心时自动设置 `pinned = true`\n- **永不删除**：即使评分归零也不会被遗忘\n- **分类管理**：支持按类别配置自动晋升规则\n\n### 晋升评估\n\n```python\nasync def evaluate_core_promotion(memory, category_rules):\n    if memory.category in category_rules.auto:\n        await promote_to_core(memory, reason=\"category_auto\")\n    elif memory.causal_weight > threshold:\n        await promote_to_core(memory, reason=\"high_connectivity\")\n```\n\n资料来源：[src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n\n### 核心记忆配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `auto` | 满足条件自动晋升的类别列表 |\n| `approval` | 需要审批才能晋升的类别 |\n| `excluded` | 禁止晋升为核心的类别 |\n\n### 晋升流程\n\n```mermaid\ngraph TD\n    EVAL[晋升评估] --> CHECK_CATEGORY{检查类别规则}\n    \n    CHECK_CATEGORY -->|auto 列表| AUTO[自动晋升]\n    CHECK_CATEGORY -->|approval 列表| NEED_APPROVAL[需要审批]\n    CHECK_CATEGORY -->|excluded 列表| BLOCK[阻止晋升]\n    CHECK_CATEGORY -->|无匹配| CHECK_CONNECTIVITY{高连接性?}\n    \n    CHECK_CONNECTIVITY -->|是| AUTO\n    CHECK_CONNECTIVITY -->|否| KEEP[保持当前状态]\n    \n    AUTO --> SET_PIN[设置 pinned=true]\n    NEED_APPROVAL --> AWAIT[等待用户确认]\n    BLOCK --> KEEP\n    \n    AWAIT -->|批准| SET_PIN\n    AWAIT -->|拒绝| KEEP\n    \n    SET_PIN --> LOG[记录晋升原因]\n    LOG --> DONE[完成]\n```\n\n## 记忆节点模型\n\n### 数据结构\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID                    # 唯一标识\n    status: MemoryStatus            # 当前状态\n    content_summary: str            # 内容摘要 (≤200字符)\n    content_full: str | None        # 完整内容\n    embedding: list[float] | None  # 向量嵌入\n    \n    # 时间戳\n    created_at: datetime            # 创建时间\n    last_accessed_at: datetime      # 最后访问\n    last_reactivated_at: datetime   # 最后召回\n    \n    # 评分因子\n    decay_score: float = 1.0        # 衰减评分\n    causal_weight: int = 0          # 因果权重\n    reactivation_count: int = 0     # 召回次数\n    irrelevance_counter: int = 0    # 无效计数\n    \n    # 分类与稳定性\n    category: str | None            # 类别\n    stability: float = 1.0          # 稳定性\n    pinned: bool = False            # 是否固定\n```\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 稳定性机制\n\n稳定性（Stability）随成功召回而增加，模拟间隔重复学习：\n\n- 每次成功检索：`stability += 0.1`\n- 长期未召回：`stability -= 0.05`\n- 高稳定性记忆更难被删除\n\n## 生命周期管理 API\n\n### MCP 工具\n\n| 工具名 | 功能 |\n|--------|------|\n| `memory_recall` | 召回记忆（触发再激活） |\n| `memory_search` | 搜索记忆 |\n| `memory_traverse` | 遍历因果图 |\n| `pin_memory` | 固定记忆 |\n| `unpin_memory` | 取消固定 |\n| `list_core_memories` | 列出核心记忆 |\n| `delete_memory` | 删除记忆 |\n\n### 召回工作流\n\n```mermaid\nsequenceDiagram\n    Client->>Genesys: memory_recall(query)\n    Genesys->>Graph: 查找相关节点\n    Graph-->>Genesys: 返回候选记忆\n    Genesys->>Scoring: 计算评分\n    Scoring-->>Genesys: 评分结果\n    Genesys->>Transitions: 评估状态转换\n    Transitions-->>Genesys: 更新状态\n    Genesys->>User: 返回记忆列表\n```\n\n## 配置选项\n\n### 环境变量\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `GENESYS_BACKEND` | 存储后端 | `memory` |\n| `GENESYS_EMBEDDER` | 嵌入提供者 | `openai` |\n| `GENESYS_PERSIST_PATH` | 状态持久化路径 | 无 |\n\n### 引擎阈值\n\n引擎阈值定义在 `engine/config.py` 中，可通过环境变量配置：\n\n- 遗忘阈值\n- 晋升阈值\n- 休眠阈值\n- 消逝阈值\n\n## 总结\n\n记忆生命周期是 Genesys 实现智能遗忘的核心机制：\n\n1. **三层评分** 保证记忆必须同时满足相关性、连接性和再激活三个条件才能存活\n2. **五种状态** 提供精细的记忆管理粒度\n3. **因果图** 通过链接关系保护重要记忆不被遗忘\n4. **核心记忆** 为结构关键记忆提供永久保护\n5. **固定机制** 允许用户手动保护特定记忆\n\n该系统确保 AI 记忆既不会无限膨胀，也不会遗忘重要信息，实现了记忆容量与信息价值的动态平衡。\n\n---\n\n<a id='page-mcp-tools'></a>\n\n## MCP 工具集\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)\n</details>\n\n# MCP 工具集\n\n## 概述\n\nGenesys 的 MCP 工具集是系统与外部 AI 客户端（如 Claude Desktop、Claude Code）交互的核心接口层。该工具集通过 MCP（Model Context Protocol）协议暴露一组标准化的内存操作工具，使 AI 代理能够存储、检索、遍历和管理记忆节点。\n\nMCP 工具集采用标准化的事件驱动架构，所有工具均通过统一的 `call_tool` 分发器进行路由。工具层与底层存储提供者（GraphStorageProvider、CacheProvider、EmbeddingProvider）解耦，支持多种存储后端。资料来源：[server.py:1-50]()\n\n## 架构设计\n\n### 工具调用流程\n\n```mermaid\ngraph TD\n    A[MCP 客户端请求] --> B[call_tool 分发器]\n    B --> C{工具名称校验}\n    C -->|有效| D[参数验证]\n    C -->|无效| E[返回错误]\n    D --> F[权限检查]\n    F -->|通过| G[执行业务逻辑]\n    F -->|失败| H[抛出 PermissionError]\n    G --> I[调用存储提供者]\n    I --> J[返回 TextContent]\n    J --> K[格式化响应]\n    K --> L[返回给 MCP 客户端]\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| MCP Server | `server.py` | 协议层，处理 stdio/HTTP 传输 |\n| Tool Dispatch | `server.py` | 工具路由和参数分发 |\n| Tool Implementations | `mcp/tools.py` | 业务逻辑实现 |\n| Context Management | `context.py` | 用户身份和权限上下文 |\n| Storage Providers | `storage/` | 数据持久化抽象 |\n\n## 工具清单\n\n### 存储与检索类工具\n\n#### memory_store\n\n存储新的记忆节点，可选择性地关联到现有记忆。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `content` | string | 是 | - | 记忆内容摘要（最大 200 字符） |\n| `source_session` | string | 否 | `\"\"` | 来源会话标识 |\n| `related_to` | array | 否 | `null` | 关联的记忆 ID 列表 |\n| `visibility` | string | 否 | `\"private\"` | 可见性：`private` 或 `org` |\n| `org_id` | string | 否 | `null` | 组织 ID（org 可见性时必需） |\n\n资料来源：[server.py:50]()\n\n#### memory_recall\n\n基于自然语言查询召回记忆，采用混合搜索策略（向量搜索 + 关键词 + 图传播激活）。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 自然语言查询 |\n| `k` | integer | 否 | `10` | 召回的记忆数量 |\n| `max_results` | integer | 否 | `null` | 最大结果数限制 |\n\n资料来源：[server.py:52]()\n\n#### memory_search\n\n基于过滤条件的向量搜索，支持按状态、类别、日期或实体筛选。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 搜索查询 |\n| `filters` | object | 否 | `null` | 过滤条件对象 |\n| `k` | integer | 否 | `10` | 返回结果数 |\n\n资料来源：[server.py:54]()\n\n### 图遍历类工具\n\n#### memory_traverse\n\n从指定节点开始遍历记忆因果图。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 起始节点 ID |\n| `depth` | integer | 否 | `2` | 遍历深度 |\n| `edge_types` | array | 否 | `null` | 边类型过滤（如 `[\"caused_by\"]`） |\n\n资料来源：[server.py:56]()\n\n#### memory_explain\n\n解释记忆节点的分数构成和因果链。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 记忆节点 ID |\n\n资料来源：[server.py:58]()\n\n### 生命周期管理工具\n\n#### pin_memory\n\n将记忆固定为核心记忆，防止被遗忘机制删除。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待固定的节点 ID |\n\n#### unpin_memory\n\n取消固定记忆，重新评估其核心资格。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待取消固定的节点 ID |\n\n资料来源：[server.py:60-62]()\n\n#### delete_memory\n\n永久删除记忆节点及其所有关联边。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待删除的节点 ID |\n\n### 核心记忆管理工具\n\n#### list_core_memories\n\n列出所有核心记忆，可按类别过滤。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `category` | string | 否 | `null` | 类别过滤条件 |\n\n资料来源：[server.py:64]()\n\n#### set_core_preferences\n\n配置核心记忆类别偏好。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `auto` | array | 否 | `null` | 自动升级为核心记忆的类别 |\n| `approval` | array | 否 | `null` | 需要审批才能升级的类别 |\n| `excluded` | array | 否 | `null` | 排除的核心记忆类别 |\n\n### 组织协作工具\n\n#### promote_to_org\n\n将私有记忆提升为组织可见性。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待提升的节点 ID |\n| `org_id` | string | 是 | - | 目标组织 ID |\n| `action` | string | 否 | `\"keep_private\"` | 关联操作：`keep_private`、`promote_all`、`delete_links` |\n| `dry_run` | boolean | 否 | `false` | 是否为试运行模式 |\n\n资料来源：[server.py:42-46]()\n\n### 统计与监控工具\n\n#### memory_stats\n\n获取图统计信息，包括节点总数、边总数、活跃节点数等。\n\n无参数要求。\n\n资料来源：[server.py:66]()\n\n## 工具分发机制\n\n### 分发表结构\n\n工具分发通过 `_TOOL_DISPATCH` 字典实现，每个条目包含三元素元组：\n\n```python\n_TOOL_DISPATCH = {\n    \"tool_name\": (handler, required_args, optional_args_with_defaults)\n}\n```\n\n资料来源：[server.py:35-47]()\n\n### 调用流程\n\n```mermaid\nsequenceDiagram\n    participant Client as MCP 客户端\n    participant Server as MCP Server\n    participant Dispatch as 分发器\n    participant Tools as 工具实现\n    participant Storage as 存储提供者\n\n    Client->>Server: call_tool(\"memory_store\", {...})\n    Server->>Dispatch: 查找工具处理器\n    Dispatch->>Dispatch: 验证必需参数\n    Dispatch->>Dispatch: 合并默认参数\n    Dispatch->>Tools: 调用 handler(**params)\n    Tools->>Storage: 读写数据\n    Storage-->>Tools: 返回结果\n    Tools-->>Server: TextContent 列表\n    Server-->>Client: 格式化响应\n```\n\n### 权限验证\n\n工具执行前需进行权限检查，核心逻辑位于 `mcp/tools.py`：\n\n```python\ndef _caller_owns_node(node: MemoryNode) -> bool:\n    uid = _caller_uid()\n    if uid is None:\n        raise PermissionError(\"current_user_id not set\")\n    role = current_user_role.get(None)\n    if role == \"admin\" and node.org_id in current_org_ids:\n        return True\n    return node.original_user_id == uid\n```\n\n资料来源：[mcp/tools.py:26-40]()\n\n## 记忆节点数据模型\n\n### MemoryNode 核心字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 节点唯一标识 |\n| `status` | MemoryStatus | 生命周期状态（ACTIVE、DORMANT、FADING 等） |\n| `content_summary` | string | 内容摘要（最大 200 字符） |\n| `content_full` | string | 完整内容（可选） |\n| `embedding` | float[] | 向量嵌入（用于相似度搜索） |\n| `decay_score` | float | 衰减评分（ relevance × connectivity × reactivation） |\n| `causal_weight` | int | 因果权重（连接数） |\n| `reactivation_count` | int | 激活次数 |\n| `pinned` | bool | 是否固定为核心记忆 |\n| `stability` | float | 稳定性分数（成功检索后增加） |\n\n资料来源：[models/node.py:12-45]()\n\n## MCP 协议集成\n\n### 服务端点\n\n| 传输方式 | 端点 | 用途 |\n|---------|------|------|\n| stdio | 直接标准输入输出 | Claude Desktop、本地集成 |\n| HTTP | `http://localhost:8000/mcp` | Claude Code、网络客户端 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 工具注册\n\n工具通过 `@app.list_tools()` 和 `@app.call_tool()` 装饰器注册：\n\n```python\n@app.list_tools()\nasync def list_tools() -> list[Tool]:\n    return _TOOL_SCHEMAS\n\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:\n    if name not in _TOOL_DISPATCH:\n        return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n    # 处理工具调用...\n```\n\n资料来源：[server.py:19-26]()\n\n## 配置选项\n\n### 环境变量\n\n| 变量 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端：`memory`、`postgres`、`obsidian`、`falkordb` |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式的默认用户 ID |\n| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | Anthropic API 密钥（用于 LLM 记忆处理） |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 错误处理\n\n### 权限错误\n\n```python\nif uid is None:\n    raise PermissionError(\"current_user_id not set — cannot verify ownership\")\n```\n\n### 未知工具\n\n```python\nif name not in _TOOL_DISPATCH:\n    return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n```\n\n### 返回格式\n\n所有工具返回 `list[TextContent]`，其中 `TextContent` 包含 `type` 和 `text` 字段。\n\n## 使用示例\n\n### Claude Desktop 配置\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n### 启动 MCP 服务器\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n或使用轻量级 stdio 服务器：\n\n```bash\npython -m genesys_memory\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 扩展开发\n\n如需添加新工具，需完成以下步骤：\n\n1. 在 `mcp/tools.py` 中实现工具函数\n2. 在 `_TOOL_SCHEMAS` 中定义工具元数据（名称、描述、输入模式）\n3. 在 `_TOOL_DISPATCH` 中注册工具（handler、必需参数、可选参数及默认值）\n4. 添加对应的单元测试\n\n```python\n# 示例：添加新工具\n_TOOL_DISPATCH[\"new_tool\"] = (\n    tools.new_tool,\n    [\"required_param\"],\n    {\"optional_param\": \"default_value\"}\n)\n\n---\n\n<a id='page-storage-backends'></a>\n\n## 存储后端实现\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [检索系统](#page-retrieval-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)\n- [src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n</details>\n\n# 存储后端实现\n\n## 概述\n\nGenesys 的存储后端系统是一个模块化的存储抽象层，为记忆引擎提供统一的数据持久化和检索接口。该设计允许用户根据不同场景选择合适的存储方案，同时保持核心记忆评分引擎的独立性。\n\n存储后端系统的核心职责包括：\n\n- **记忆节点管理**：创建、读取、更新、删除记忆节点\n- **因果图维护**：管理记忆之间的因果边关系\n- **向量嵌入存储**：持久化记忆的语义向量表示\n- **全文内容存储**：保存记忆的完整内容和摘要\n- **元数据管理**：维护访问时间、评分、状态等生命周期信息\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## 架构设计\n\n### 核心抽象层\n\nGenesys 采用接口抽象设计，定义了一系列存储提供者接口。任何实现这些接口的存储系统都可以作为 Genesys 的后端使用。\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      MCP 工具层                              │\n│  memory_store | memory_recall | memory_search | etc.        │\n├─────────────────────────────────────────────────────────────┤\n│                      核心引擎层                              │\n│         评分引擎 | 生命周期管理 | 记忆整合                   │\n├─────────────────────────────────────────────────────────────┤\n│                      存储抽象层                              │\n│  GraphStorageProvider | CacheProvider | EmbeddingProvider   │\n├─────────────────────────────────────────────────────────────┤\n│                      存储后端实现                            │\n│  MemoryStorage | PostgresStorage | ObsidianStorage | FalkorDB│\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n\n### 存储提供者类型\n\n| 提供者类型 | 接口定义 | 用途 |\n|-----------|---------|------|\n| `GraphStorageProvider` | 图存储接口 | 管理记忆节点和因果边 |\n| `CacheProvider` | 缓存接口 | 提供高速缓存层 |\n| `EmbeddingProvider` | 向量嵌入接口 | 生成和检索语义向量 |\n| `EventBusProvider` | 事件总线接口 | 发布记忆事件 |\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n---\n\n## 数据模型\n\n### 记忆节点（MemoryNode）\n\n`MemoryNode` 是 Genesys 中记忆的基本存储单元，包含记忆的所有属性信息。\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID = Field(default_factory=uuid.uuid4)\n    status: MemoryStatus = MemoryStatus.ACTIVE\n    content_summary: str = Field(max_length=200)\n    content_full: str | None = None\n    content_ref: str | None = None\n    embedding: list[float] | None = None\n\n    # 时间戳\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n\n    # 生命周期评分\n    decay_score: float = 1.0\n    causal_weight: int = 0\n    reactivation_count: int = 0\n    reactivation_pattern: ReactivationPattern\n    irrelevance_counter: int = 0\n\n    # 来源追踪\n    source_agent: str = \"claude\"\n    source_session: str = \"\"\n\n    # 分类\n    entity_refs: list[str] = []\n    category: str | None = None\n\n    # 稳定性\n    stability: float = 1.0\n\n    # 核心记忆\n    pinned: bool = False\n    promotion_reason: str | None = None\n\n    # 激活历史\n    reactivation_timestamps: list[datetime]\n```\n\n**字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 记忆唯一标识符 |\n| `status` | MemoryStatus | 当前生命周期状态 |\n| `content_summary` | str | 记忆摘要（最大200字符） |\n| `content_full` | str | 完整记忆内容 |\n| `content_ref` | str | 外部引用链接 |\n| `embedding` | list[float] | 语义向量表示 |\n| `decay_score` | float | 衰减评分（0.0-1.0） |\n| `causal_weight` | int | 因果权重（连接数） |\n| `reactivation_count` | int | 被激活次数 |\n| `stability` | float | 稳定性指数 |\n| `pinned` | bool | 是否固定为核心记忆 |\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 记忆边（MemoryEdge）\n\n`MemoryEdge` 表示记忆节点之间的因果关系。\n\n```python\nclass MemoryEdge(BaseModel):\n    source_id: uuid.UUID\n    target_id: uuid.UUID\n    type: EdgeType\n    weight: float\n```\n\n**边的类型**：\n\n| 类型 | 说明 | 置信度阈值 |\n|------|------|-----------|\n| `caused_by` | 因果关系 | > 0.6 |\n| `supports` | 支持关系 | > 0.6 |\n| `derived_from` | 派生关系 | > 0.6 |\n\n资料来源：[src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n\n---\n\n## 可用存储后端\n\n### 1. 内存后端（Memory）\n\n零依赖的内置后端，适合快速试用和开发测试。\n\n**特性**：\n- 无需额外安装\n- 数据存储在内存中，重启后丢失\n- 适合概念验证和小规模测试\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 2. PostgreSQL 后端（Postgres + pgvector）\n\n生产级持久化存储，支持向量相似度搜索。\n\n**安装**：\n```bash\npip install 'genesys-memory[postgres]'\n```\n\n**配置**：\n| 环境变量 | 必需 | 说明 |\n|---------|------|------|\n| `OPENAI_API_KEY` | 是 | 向量嵌入生成 |\n| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 |\n| `GENESYS_BACKEND` | 是 | 设置为 `postgres` |\n\n**启动流程**：\n```bash\ndocker compose up -d postgres\nalembic upgrade head\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 3. Obsidian Vault 后端\n\n将 Obsidian 笔记库转换为记忆存储，Markdown 文件成为记忆节点，`[[wikilinks]]` 自动转换为因果边。\n\n**安装**：\n```bash\npip install 'genesys-memory[obsidian]'\n```\n\n**配置**：\n| 环境变量 | 说明 |\n|---------|------|\n| `OBSIDIAN_VAULT_PATH` | Obsidian 库路径 |\n| `GENESYS_EMBEDDER` | `openai`（默认）或 `local` |\n\n**本地嵌入模式**（无需 API Key）：\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n使用 `all-MiniLM-L6-v2` 模型（约80MB）进行本地向量生成。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 4. FalkorDB 后端\n\n基于 Redis 的原生图数据库后端，支持高性能图遍历。\n\n**安装**：\n```bash\npip install 'genesys-memory[falkordb]'\n```\n\n**配置**：\n| 环境变量 | 说明 |\n|---------|------|\n| `FALKORDB_HOST` | FalkorDB 主机（默认：localhost） |\n\n**启动**：\n```bash\ndocker compose up -d falkordb\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## MCP 工具接口\n\nMCP 工具层提供统一的记忆操作接口，各存储后端均实现相同的功能语义。\n\n### 核心工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `memory_store` | 存储新记忆，可选链接相关记忆 |\n| `memory_recall` | 混合检索（向量 + 关键词 + 图扩散激活） |\n| `memory_search` | 过滤检索（状态、日期、关键词） |\n| `memory_traverse` | 从指定节点遍历因果图 |\n| `memory_explain` | 解释记忆评分详情 |\n| `memory_stats` | 获取记忆系统统计 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定 |\n| `delete_memory` | 永久删除记忆 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆偏好 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n### 检索流程\n\n```mermaid\ngraph TD\n    A[memory_recall 查询] --> B[向量相似度搜索]\n    A --> C[关键词匹配]\n    B --> D[图扩散激活]\n    C --> D\n    D --> E[结果排序融合]\n    E --> F[返回 Top-K 结果]\n```\n\n**recall 参数**：\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `query` | string | 必需 | 自然语言查询 |\n| `k` | integer | 10 | 返回结果数量 |\n| `max_results` | integer | - | 最大结果限制 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n---\n\n## 缓存层实现\n\n缓存层位于存储后端之上，提供高速数据访问能力。\n\n### 缓存策略\n\n| 策略 | 说明 | 适用场景 |\n|------|------|---------|\n| LRU | 最近最少使用 | 高频访问记忆 |\n| TTL | 时间过期 | 会话上下文 |\n| 写回 | 延迟写入 | 批量操作优化 |\n\n### 缓存配置\n\n| 配置项 | 说明 |\n|-------|------|\n| `max_size` | 最大缓存条目数 |\n| `ttl_seconds` | 缓存过期时间 |\n| `eviction_policy` | 淘汰策略 |\n\n资料来源：[src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)\n\n---\n\n## 自定义后端开发\n\nGenesys 支持通过实现存储接口来创建自定义后端。\n\n### 实现步骤\n\n1. **继承基础接口**：实现 `GraphStorageProvider`\n2. **实现必需方法**：`create_node`、`get_node`、`update_node`、`delete_node`、`create_edge`、`get_edges`、`search_nodes`\n3. **注册后端**：通过环境变量配置使用\n\n```python\nclass CustomStorageProvider(GraphStorageProvider):\n    async def create_node(self, node: MemoryNode) -> uuid.UUID:\n        # 实现节点创建逻辑\n        pass\n    \n    async def search_nodes(\n        self, \n        query: str, \n        embedding: list[float], \n        k: int = 10\n    ) -> list[tuple[MemoryNode, float]]:\n        # 实现向量搜索\n        pass\n```\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n---\n\n## 配置参考\n\n### 环境变量汇总\n\n| 变量名 | 必需 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `OPENAI_API_KEY` | 除非使用本地嵌入 | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | Claude API 密钥 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |\n| `DATABASE_URL` | Postgres 后端 | - | PostgreSQL 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | Obsidian 后端 | - | Obsidian 库路径 |\n| `FALKORDB_HOST` | FalkorDB 后端 | `localhost` | FalkorDB 主机 |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | - | 状态持久化路径 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## 性能考量\n\n### 后端选型建议\n\n| 场景 | 推荐后端 | 原因 |\n|------|---------|------|\n| 快速原型开发 | Memory | 零配置，即开即用 |\n| 生产部署 | Postgres | 成熟稳定，支持向量索引 |\n| 个人知识管理 | Obsidian | 本地优先，无云依赖 |\n| 图遍历密集 | FalkorDB | 原生图数据库性能优势 |\n\n### 扩展性\n\n- **水平扩展**：Postgres 后端支持连接池和读写分离\n- **向量索引**：Postgres 使用 pgvector 扩展，支持 HNSW 和 IVFFlat 索引\n- **分片**：FalkorDB 支持 Redis Cluster 模式\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n<a id='page-retrieval-system'></a>\n\n## 检索系统\n\n### 相关页面\n\n相关主题：[存储后端实现](#page-storage-backends), [MCP 工具集](#page-mcp-tools)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n</details>\n\n# 检索系统\n\n## 概述\n\nGenesys 的检索系统是整个记忆引擎的核心组件，负责从因果图中高效召回相关记忆。该系统采用混合检索策略，结合向量搜索、关键词匹配和图传播激活（graph spreading activation）三种技术，实现精准的记忆召回。 资料来源：[README.md]()\n\n检索系统的设计目标是解决\"扁平记忆无法扩展\"的问题。与传统的向量存储不同，Genesys 不仅提供回忆能力，还通过因果图理解记忆之间的关联，使第 500 条记忆不会被第 5 条记忆埋没。 资料来源：[README.md]()\n\n## 架构设计\n\n### 混合检索流程\n\n```mermaid\ngraph TD\n    A[用户查询] --> B[向量嵌入]\n    A --> C[关键词提取]\n    B --> D[向量相似度搜索]\n    C --> E[关键词匹配]\n    D --> F[候选记忆集合]\n    E --> F\n    F --> G[图传播激活]\n    G --> H[混合评分排序]\n    H --> I[最终结果]\n    \n    J[因果图] --> G\n```\n\n检索系统的工作流程包含四个主要阶段：\n\n1. **查询处理阶段**：将自然语言查询转换为向量嵌入，同时提取关键词\n2. **候选生成阶段**：通过向量搜索和关键词匹配生成候选记忆集合\n3. **图传播激活阶段**：在因果图上执行 spreading activation 算法，增强关联记忆的权重\n4. **混合排序阶段**：综合向量相似度、关键词匹配度和图关联度进行最终排序\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 向量嵌入模块 | `src/genesys_memory/retrieval/embedding.py` | 文本向量化，支持 OpenAI 和本地模型 |\n| LLM 提供器 | `src/genesys_memory/engine/llm_provider.py` | LLM 驱动的因果关系识别 |\n| MCP 工具层 | `src/genesys_memory/mcp/tools.py` | 对外暴露检索 API |\n| 图存储层 | 存储后端 | 因果图的持久化和遍历 |\n\n## MCP 检索工具\n\nGenesys 通过 MCP（Model Context Protocol）协议暴露检索能力，提供五个核心工具。 资料来源：[server.py:1-80]()\n\n### memory_recall — 混合召回\n\n`memory_recall` 是最主要的检索工具，执行向量搜索、关键词搜索和图传播激活的混合检索。\n\n```python\nTool(name=\"memory_recall\", description=\"Recall memories using hybrid search (vector + keyword + graph spreading activation).\", inputSchema={\n    \"type\": \"object\", \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n        \"max_results\": {\"type\": \"integer\"},\n    },\n})\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | string | 必需 | 自然语言查询字符串 |\n| k | integer | 10 | 返回结果数量 |\n| max_results | integer | - | 最大结果上限 |\n\n### memory_search — 过滤搜索\n\n`memory_search` 提供基于元数据过滤的向量搜索能力。\n\n```python\nTool(name=\"memory_search\", description=\"Search memories with filters (status, category, date, or entity).\", inputSchema={\n    \"type\": \"object\", \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"filters\": {\"type\": \"object\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n    },\n})\n```\n\n**支持的过滤字段：**\n\n- `status`：记忆状态（ACTIVE、DORMANT、FADING 等）\n- `category`：记忆类别\n- `date_range`：日期范围\n- `entity`：实体引用\n\n### memory_traverse — 图遍历\n\n`memory_traverse` 用于从指定节点出发，在因果图上进行深度遍历。\n\n```python\nTool(name=\"memory_traverse\", description=\"Traverse the memory graph from a starting node.\", inputSchema={\n    \"type\": \"object\", \"required\": [\"node_id\"],\n    \"properties\": {\n        \"node_id\": {\"type\": \"string\"},\n        \"depth\": {\"type\": \"integer\", \"default\": 2},\n        \"edge_types\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}},\n    },\n})\n```\n\n### memory_explain — 评分解释\n\n`memory_explain` 解释特定记忆的评分构成，帮助理解记忆为何被召回。\n\n```python\nTool(name=\"memory_explain\", description=\"Explain a memory's score breakdown.\", inputSchema={\n    \"type\": \"object\", \"required\": [\"node_id\"],\n    \"properties\": {\"node_id\": {\"type\": \"string\"}},\n})\n```\n\n### memory_stats — 统计信息\n\n`memory_stats` 获取图的统计信息，用于监控和调试。\n\n```python\nTool(name=\"memory_stats\", description=\"Get graph statistics.\", inputSchema={\n    \"type\": \"object\", \"properties\": {},\n})\n```\n\n## 向量嵌入系统\n\n### 嵌入提供者配置\n\nGenesys 支持两种嵌入提供者，通过 `GENESYS_EMBEDDER` 环境变量配置。 资料来源：[README.md]()\n\n| 提供者 | 配置值 | 说明 |\n|--------|--------|------|\n| OpenAI | `openai`（默认） | 使用 OpenAI 的 text-embedding-ada-002 或更新的模型 |\n| 本地 | `local` | 使用 sentence-transformers 的 all-MiniLM-L6-v2（384 维），约 80MB |\n\n本地嵌入模式无需任何 API 密钥，适合完全离线的使用场景：\n\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\n# 无需 OPENAI_API_KEY\n```\n\n### 嵌入生成时机\n\n在创建新记忆时，系统会自动生成嵌入向量：\n\n```python\n# 资料来源：mcp/tools.py\nembedding = await self.embeddings.embed(content) if self.embeddings else []\n```\n\n嵌入向量用于两个目的：\n\n1. **向量相似度搜索**：找到语义上相似的历史记忆\n2. **自动关联**：将新记忆与相似记忆自动建立连接边\n\n## 因果关系识别\n\n### LLM 驱动的因果分析\n\n当创建新记忆时，系统使用 LLM 分析新记忆与现有记忆之间的因果关系。 资料来源：[llm_provider.py]()\n\n```python\nprompt = (\n    \"Given a new memory and a list of existing memories, identify causal relationships.\\n\\n\"\n    f\"New memory: {new_memory}\\n\\nExisting memories:\\n{mem_lines}\\n\\n\"\n    \"For each causal relationship found, specify:\\n\"\n    \"- target_id: the ID of the existing memory\\n\"\n    '- edge_type: one of \"caused_by\", \"supports\", \"derived_from\"\\n'\n    \"- confidence: 0.0 to 1.0\\n\"\n    \"- reason: brief explanation of why this relationship exists\\n\\n\"\n    \"Only include relationships with confidence > 0.6.\\n\"\n    \"Respond with ONLY a JSON array of objects, no other text.\"\n)\n```\n\n### 边类型定义\n\n| 边类型 | 说明 | 使用场景 |\n|--------|------|----------|\n| `caused_by` | 因果关系 | A 导致 B 发生 |\n| `supports` | 支持关系 | A 为 B 提供证据 |\n| `derived_from` | 派生关系 | B 由 A 提炼而来 |\n| `related_to` | 关联关系 | 自动链接的语义相似记忆 |\n\n### 置信度阈值\n\n只有置信度超过 **0.6** 的因果关系才会被采纳：\n\n```python\nif confidence > 0.6:\n    results.append((item[\"target_id\"], edge_type, confidence, item.get(\"reason\")))\n```\n\n## 自动关联机制\n\n### 相似记忆自动链接\n\n新记忆创建时，系统会自动将其与语义相似的现有记忆关联。 资料来源：[mcp/tools.py]()\n\n```python\n# 向量搜索找到相似记忆\nsimilar = await self.graph.vector_search(embedding, k=4, org_ids=org_ids)\n\nfor other_node, score in similar:\n    if score < 0.3:  # 相似度阈值\n        continue\n```\n\n**关键参数：**\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| k | 4 | 搜索返回的最大相似记忆数 |\n| 相似度阈值 | 0.3 | 只有高于此值的链接才会创建 |\n\n### 组织边界规则\n\n当记忆可见性为 `ORG`（组织级别）时，系统会强制执行组织边界规则：\n\n```python\n# Org boundary rule: org nodes only link to same-org nodes\nif vis == Visibility.ORG:\n    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:\n        continue\n```\n\n### 自动创建的边\n\n自动关联创建的边使用 `EdgeType.RELATED_TO` 类型，并记录相似度分数和创建原因：\n\n```python\nedge = MemoryEdge(\n    source_id=node.id,\n    target_id=other_node.id,\n    type=EdgeType.RELATED_TO,\n    weight=round(score, 4),\n    reason=f\"cosine similarity {score:.3f}\",\n    created_by=\"auto_link\",\n)\n```\n\n## 记忆状态与生命周期\n\n检索系统与记忆的生命周期紧密集成。记忆在系统中经历以下状态转换： 资料来源：[README.md]()\n\n```mermaid\ngraph LR\n    A[STORE] --> B[ACTIVE]\n    B --> C[DORMANT]\n    C --> D[FADING]\n    D --> E[PRUNED]\n    B --> F[reactivation]\n    F --> B\n```\n\n### 评分公式\n\n记忆被三个因素共同评分：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因素 | 说明 | 衰减特性 |\n|------|------|----------|\n| relevance | 相关性 | 随时间衰减，久未访问的记忆会淡化 |\n| connectivity | 连接性 | 奖励拥有多条因果边的记忆，枢纽记忆存活 |\n| reactivation | 再激活 | 频繁被召回的记忆获得提升 |\n\n由于公式是乘法形式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁召回但没有因果边的孤立记忆也会淡化。\n\n## 检索配置选项\n\n### 环境变量配置\n\n| 变量 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |\n| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | 用于 LLM 记忆处理的 Anthropic 密钥 |\n\n### 不同存储后端的检索\n\nGenesys 的检索系统与存储后端解耦，可配合多种后端使用： 资料来源：[README.md]()\n\n| 后端 | 向量搜索 | 图遍历 | 适用场景 |\n|------|----------|--------|----------|\n| 内存 | 内置 | 内置 | 零依赖试用 |\n| PostgreSQL + pgvector | pgvector | SQL | 生产级持久化 |\n| Obsidian Vault | 插件实现 | WikiLink 解析 | 本地知识库 |\n| FalkorDB | Redis 模块 | 原生图遍历 | 图原生场景 |\n\n## 性能与基准\n\n在 LoCoMo 长对话记忆基准测试中（1540 个问题，10 个对话），Genesys 的检索系统表现如下： 资料来源：[README.md]()\n\n| 类别 | J-Score |\n|------|---------|\n| Single-hop（单跳） | 94.3% |\n| Temporal（时序） | 87.5% |\n| Multi-hop（多跳） | 69.8% |\n| Open-domain（开放域） | 91.7% |\n| **总体** | **89.9%** |\n\n作为对比，同一基准测试中 Mem0 得分为 67.1%，Zep 得分为 75.1%。检索模型使用 `gpt-4o-mini`，评判模型同样使用 `gpt-4o-mini`，检索 k=20。\n\n## 代码组织\n\n```\nsrc/genesys_memory/\n├── retrieval/\n│   └── embedding.py          # 向量嵌入生成\n├── engine/\n│   ├── llm_provider.py       # LLM 因果关系识别\n│   ├── consolidation.py      # 记忆整合\n│   └── config.py             # 引擎阈值配置\n└── mcp/\n    └── tools.py              # MCP 工具实现\n```\n\n## 开发指南\n\n引擎阈值配置在 `engine/config.py` 中，应通过环境变量配置，避免在引擎文件中硬编码魔法数字。 资料来源：[CONTRIBUTING.md]()\n\n### 测试检索功能\n\n```bash\n# 运行所有单元测试\npytest tests/ -v\n\n# 带覆盖率\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n测试文件位于 `tests/` 目录，使用 `pytest-asyncio`（auto 模式）。新增引擎逻辑时，应在相应测试文件中添加对应的测试用例。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rishimeka/genesys\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1207565616 | https://github.com/rishimeka/genesys | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\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:1207565616 | https://github.com/rishimeka/genesys | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1207565616 | https://github.com/rishimeka/genesys | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | release_recency=unknown\n\n<!-- canonical_name: rishimeka/genesys; human_manual_source: deepwiki_human_wiki -->\n",
      "markdown_key": "genesys",
      "pages": "draft",
      "source_refs": [
        {
          "evidence_id": "github_repo:1207565616",
          "kind": "repo",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/rishimeka/genesys"
        },
        {
          "evidence_id": "art_941c32fc1635457bacf35da1c1c1970e",
          "kind": "docs",
          "supports_claim_ids": [
            "claim_identity",
            "claim_distribution",
            "claim_capability"
          ],
          "url": "https://github.com/rishimeka/genesys#readme"
        }
      ],
      "summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
      "title": "genesys 说明书",
      "toc": [
        "https://github.com/rishimeka/genesys 项目说明书",
        "目录",
        "项目介绍",
        "概述",
        "核心架构",
        "记忆评分机制",
        "来自 engine/llm_provider.py 的因果关系检测",
        "记忆生命周期",
        "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": "0015664c38ab5fa65f2fbe512a57700fd6712175",
    "repo_inspection_error": null,
    "repo_inspection_files": [
      "pyproject.toml",
      "Dockerfile",
      "README.md",
      "docker-compose.yml",
      "src/genesys_memory/context.py",
      "src/genesys_memory/server.py",
      "src/genesys_memory/__init__.py",
      "src/genesys_memory/__main__.py",
      "src/genesys_memory/providers.py",
      "src/genesys_memory/mcp/tools.py",
      "src/genesys_memory/mcp/__init__.py",
      "src/genesys_memory/core_memory/preferences.py",
      "src/genesys_memory/core_memory/promoter.py",
      "src/genesys_memory/core_memory/__init__.py",
      "src/genesys_memory/models/edge.py",
      "src/genesys_memory/models/enums.py",
      "src/genesys_memory/models/__init__.py",
      "src/genesys_memory/models/node.py",
      "src/genesys_memory/storage/memory.py",
      "src/genesys_memory/storage/__init__.py",
      "src/genesys_memory/storage/cache.py",
      "src/genesys_memory/storage/base.py",
      "src/genesys_memory/engine/llm_provider.py",
      "src/genesys_memory/engine/transitions.py",
      "src/genesys_memory/engine/contradiction.py",
      "src/genesys_memory/engine/scoring.py",
      "src/genesys_memory/engine/forgetting.py",
      "src/genesys_memory/engine/consolidation.py",
      "src/genesys_memory/engine/reactivation.py",
      "src/genesys_memory/engine/__init__.py",
      "src/genesys_memory/engine/config.py",
      "src/genesys_memory/retrieval/embedding.py",
      "src/genesys_memory/retrieval/__init__.py"
    ],
    "repo_inspection_verified": true,
    "review_reasons": [
      "community_discussion_evidence_below_public_threshold"
    ],
    "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": "# genesys - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 genesys 编译的 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- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 Claim：`clm_0002` unverified 0.25\n\n## 它能做什么\n\n- **项目知识预览**（可做安装前预览）：项目可被阅读和解释，但当前证据不足以确认可安装能力或运行入口。 证据：`benchmarks/README.md`, `CONTRIBUTING.md`, `LICENSE`, `.github/pull_request_template.md` 等 Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- 项目证据中没有稳定 Quick Start 命令；此项应留空，而不是由 Doramagic 编造。\n\n## 继续前判断卡\n\n- **当前建议**：先做 Prompt Preview\n- **为什么**：当前信息足以做安装前体验，但真实兼容性、输出质量或风险边界还不能直接相信。\n\n### 30 秒判断\n\n- **现在怎么做**：先做 Prompt Preview\n- **最小安全下一步**：先跑 Prompt Preview\n- **先别相信**：真实输出质量不能在安装前相信。\n- **继续会触碰**：宿主 AI 上下文\n\n### 现在可以相信\n\n- **能力存在：项目知识预览**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`benchmarks/README.md`, `CONTRIBUTING.md`, `LICENSE`, `.github/pull_request_template.md` 等 Claim：`clm_0001` supported 0.86\n\n### 现在还不能相信\n\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\n### 继续会触碰什么\n\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\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_0003` inferred 0.45\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\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- **项目知识预览**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`benchmarks/README.md`, `CONTRIBUTING.md`, `LICENSE`, `.github/pull_request_template.md` 等 Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：89\n- 重要文件覆盖：34/89\n- 证据索引条目：33\n- 角色 / Skill 条目：7\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请基于 genesys 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 genesys 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 genesys 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 7 个角色 / Skill / 项目文档条目。\n\n- **Genesys Benchmarks**（project_doc）：Evaluated on the LoCoMo https://arxiv.org/abs/2402.06397 long-conversation memory benchmark: 10 conversations, 1,540 questions category 5 adversarial excluded , judged by LLM-as-Judge. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`benchmarks/README.md`\n- **Contributing to Genesys**（project_doc）：Thanks for your interest in contributing! Genesys is open source under the GNU Affero General Public License v3.0 LICENSE . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **What does this PR do?**（project_doc）：- Tests pass pytest tests/ -v - Linting passes ruff check src/ - New tests added if applicable 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.github/pull_request_template.md`\n- **Changelog**（project_doc）：- Edge semantics correctness breaking behavior change : Nodes with only CONTRADICTS or SUPERSEDES edges are now considered orphans for forgetting purposes. Previously, any edge — including contradiction edges — prevented a node from being classified as an orphan, which meant contradicted memories were immune to pruning and could be incorrectly promoted to core status. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CHANGELOG.md`\n- **Genesys Contributor License Agreement**（project_doc）：Genesys Contributor License Agreement 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLA.md`\n- **Security Policy**（project_doc）：If you discover a security vulnerability, please report it privately via GitHub's security advisory feature https://github.com/rishimeka/genesys/security/advisories/new . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **GENESYS — Causal Graph Memory Platform**（project_doc）：GENESYS — Causal Graph Memory Platform 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`benchmarks/REPORT.md`\n\n## 证据索引\n\n- 共索引 33 条证据。\n\n- **Genesys Benchmarks**（documentation）：Evaluated on the LoCoMo https://arxiv.org/abs/2402.06397 long-conversation memory benchmark: 10 conversations, 1,540 questions category 5 adversarial excluded , judged by LLM-as-Judge. 证据：`benchmarks/README.md`\n- **Contributing to Genesys**（documentation）：Thanks for your interest in contributing! Genesys is open source under the GNU Affero General Public License v3.0 LICENSE . 证据：`CONTRIBUTING.md`\n- **License**（source_file）：GNU AFFERO GENERAL PUBLIC LICENSE Version 3, 19 November 2007 证据：`LICENSE`\n- **What does this PR do?**（documentation）：- Tests pass pytest tests/ -v - Linting passes ruff check src/ - New tests added if applicable 证据：`.github/pull_request_template.md`\n- **Changelog**（documentation）：- Edge semantics correctness breaking behavior change : Nodes with only CONTRADICTS or SUPERSEDES edges are now considered orphans for forgetting purposes. Previously, any edge — including contradiction edges — prevented a node from being classified as an orphan, which meant contradicted memories were immune to pruning and could be incorrectly promoted to core status. 证据：`CHANGELOG.md`\n- **Genesys Contributor License Agreement**（documentation）：Genesys Contributor License Agreement 证据：`CLA.md`\n- **Security Policy**（documentation）：If you discover a security vulnerability, please report it privately via GitHub's security advisory feature https://github.com/rishimeka/genesys/security/advisories/new . 证据：`SECURITY.md`\n- **GENESYS — Causal Graph Memory Platform**（documentation）：GENESYS — Causal Graph Memory Platform 证据：`benchmarks/REPORT.md`\n- **Locomo Judged**（structured_config）：{ \"metadata\": { \"answer model\": \"gpt-4o-mini\", \"judge model\": \"gpt-4o-mini\", \"retrieval k\": 20, \"total questions\": 1540, \"overall j score\": 89.9, \"per category\": { \"Single-hop\": { \"correct\": 266, \"total\": 282, \"j score\": 94.3 }, \"Temporal\": { \"correct\": 281, \"total\": 321, \"j score\": 87.5 }, \"Multi-hop\": { \"correct\": 67, \"total\": 96, \"j score\": 69.8 }, \"Open-domain\": { \"correct\": 771, \"total\": 841, \"j score\": 91.7 } }, \"per conversation\": { \"conv-26\": { \"correct\": 143, \"total\": 152, \"j score\": 94.1 }, \"conv-30\": { \"correct\": 80, \"total\": 81, \"j score\": 98.8 }, \"conv-41\": { \"correct\": 130, \"total\": 152, \"j score\": 85.5 }, \"conv-42\": { \"correct\": 180, \"total\": 199, \"j score\": 90.5 }, \"conv-43\"… 证据：`benchmarks/locomo_judged.json`\n- **Default Core Categories**（structured_config）：{ \"auto promote categories\": \"professional\", \"educational\", \"family\", \"location\" , \"approval required categories\": , \"excluded categories\": , \"notes\": { \"professional\": \"Job title, employer, industry, skills, career goals\", \"educational\": \"Degrees, institutions, certifications, fields of study\", \"family\": \"Spouse/partner, children, parents, siblings, family structure\", \"location\": \"Home city, home country, neighborhood, time zone\", \"medical\": \"Not auto-promoted by default. Add to auto promote or approval required per user preference.\", \"financial\": \"Not auto-promoted by default. Sensitive category.\", \"preference\": \"General preferences food, hobbies, communication style . Not auto-promoted —… 证据：`config/default_core_categories.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.rishimeka/genesys-memory\", \"description\": \"Causal graph memory engine for AI agents with scoring, activation, and forgetting\", \"repository\": { \"url\": \"https://github.com/rishimeka/genesys\", \"source\": \"github\" }, \"version\": \"0.3.11\", \"packages\": { \"registryType\": \"pypi\", \"identifier\": \"genesys-memory\", \"version\": \"0.3.11\", \"transport\": { \"type\": \"stdio\" }, \"environmentVariables\": { \"description\": \"OpenAI API key for embedding generation optional — use GENESYS EMBEDDER=local for no API key \", \"isRequired\": false, \"format\": \"string\", \"isSecret\": true, \"name\": \"OPENAI API KEY\" }, { \"d… 证据：`server.json`\n- **Causal Reasoning**（structured_config）：{ \"name\": \"causal reasoning\", \"description\": \"Tests multi-hop causal chain traversal. Memories form cause-effect chains that require following edges to answer correctly.\", \"conversation history\": {\"turn\": 1, \"week\": 1, \"content\": \"I started learning Python because my manager suggested it for automating reports.\"}, {\"turn\": 2, \"week\": 1, \"content\": \"I found a Python course on Udemy that covers pandas for data analysis.\"}, {\"turn\": 3, \"week\": 1, \"content\": \"Had a really nice lunch at the new Thai place across the street. The pad see ew was excellent.\"}, {\"turn\": 4, \"week\": 1, \"content\": \"It was raining all day today, couldn't even go for my usual walk after lunch.\"}, {\"turn\": 5, \"week\": 1, \"c… 证据：`benchmarks/scenarios/causal_reasoning.json`\n- **Outdated Info**（structured_config）：{ \"name\": \"outdated info\", \"description\": \"Tests handling of superseded information, contradictions, and evolving facts over time.\", \"conversation history\": {\"turn\": 1, \"week\": 1, \"content\": \"I live in San Francisco. My apartment is on Market Street.\"}, {\"turn\": 2, \"week\": 1, \"content\": \"I found this great ramen place near my apartment called Tanaka Ramen. I've been going almost every day.\"}, {\"turn\": 3, \"week\": 1, \"content\": \"I use VS Code for all my editing. It's the best editor I've ever used.\"}, {\"turn\": 4, \"week\": 2, \"content\": \"I'm using Python 3.9 for my main project at work.\"}, {\"turn\": 5, \"week\": 2, \"content\": \"Had an amazing burrito from the taqueria on Valencia Street for lunch t… 证据：`benchmarks/scenarios/outdated_info.json`\n- **Structural Importance**（structured_config）：{ \"name\": \"structural importance\", \"description\": \"Tests whether the system retains structurally important memories high connectivity, core status while allowing peripheral memories to decay.\", \"conversation history\": {\"turn\": 1, \"week\": 1, \"content\": \"I'm a software engineer at TechCorp, working on the payments team.\"}, {\"turn\": 2, \"week\": 1, \"content\": \"Our payment system processes about 50,000 transactions per day using Stripe.\"}, {\"turn\": 3, \"week\": 1, \"content\": \"Got a breakfast burrito from the food truck outside the office. Pretty solid.\"}, {\"turn\": 4, \"week\": 1, \"content\": \"My commute was brutal today, 45 minutes because of an accident on the highway.\"}, {\"turn\": 5, \"week\": 2, \"cont… 证据：`benchmarks/scenarios/structural_importance.json`\n- **Temporal Awareness**（structured_config）：{ \"name\": \"temporal awareness\", \"description\": \"Tests ability to track how information evolves over time and maintain correct temporal ordering of events.\", \"conversation history\": {\"turn\": 1, \"week\": 1, \"content\": \"I just adopted a rescue dog named Max. He's a 2-year-old German Shepherd mix.\"}, {\"turn\": 2, \"week\": 1, \"content\": \"Max is very anxious around other dogs. The vet recommended a behavioral trainer.\"}, {\"turn\": 3, \"week\": 1, \"content\": \"Made spaghetti for dinner tonight. Tried a new marinara recipe from that YouTube channel I like.\"}, {\"turn\": 4, \"week\": 1, \"content\": \"It's been raining all week. I'm stuck inside with Max and he's restless, keeps pacing around the apartment.\"}, {\"… 证据：`benchmarks/scenarios/temporal_awareness.json`\n- **.dockerignore**（source_file）：pycache .pyc .git .env .venv venv node modules genesys-ui/node modules genesys-ui/.next tests benchmarks phases schemas .md !README.md .mypy cache .pytest cache .ruff cache docker-compose.yml 证据：`.dockerignore`\n- **Python**（source_file）：Python pycache / .pyc .pyo .egg-info/ dist/ build/ .venv/ venv/ .mypy cache/ .pytest cache/ .ruff cache/ 证据：`.gitignore`\n- **.Pre Commit Config**（source_file）：repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v4.6.0 hooks: - id: check-yaml - id: end-of-file-fixer - id: trailing-whitespace - id: check-added-large-files args: '--maxkb=1000' 证据：`.pre-commit-config.yaml`\n- **Dockerfile**（source_file）：COPY pyproject.toml README.md ./ COPY src/ src/ 证据：`Dockerfile`\n- **Dockerfile**（source_file）：COPY pyproject.toml README.md ./ COPY src/ src/ 证据：`Dockerfile.mcp`\n- **Alembic**（source_file）：alembic script location = alembic sqlalchemy.url = postgresql://localhost/genesys 证据：`alembic.ini`\n- **Override URL from environment**（source_file）：\"\"\"Alembic environment for raw SQL migrations no SQLAlchemy models .\"\"\" import os from logging.config import fileConfig 证据：`alembic/env.py`\n- **Script.Py**（source_file）：Revision ID: ${up revision} Revises: ${down revision comma,n} Create Date: ${create date} \"\"\" from typing import Sequence, Union from alembic import op import sqlalchemy as sa 证据：`alembic/script.py.mako`\n- **Baseline Flat**（source_file）：\"\"\"Flat vector memory baseline for benchmark comparison.\"\"\" from future import annotations 证据：`benchmarks/baseline_flat.py`\n- **gpt-4o-mini: 500 RPM on Tier 1, much higher on Tier 2+. Use 400 for headroom.**（source_file）：\"\"\"Run LoCoMo QA evaluation against Genesys. 证据：`benchmarks/locomo_eval.py`\n- **Clear any existing data for this conversation's user scope**（source_file）：\"\"\"Ingest LoCoMo conversations into Genesys via the REST API. 证据：`benchmarks/locomo_ingest.py`\n- **Limit concurrency to avoid rate limits**（source_file）：\"\"\"Judge LoCoMo eval results using LLM-as-Judge Claude Haiku . 证据：`benchmarks/locomo_judge.py`\n- **Build one memory per session: concatenate all turns with speaker labels**（source_file）：\"\"\"LoCoMo full pipeline: per-conversation independent runs. 证据：`benchmarks/locomo_run.py`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\"Benchmark runner: compares Genesys causal memory vs flat vector baseline. 证据：`benchmarks/run_benchmark.py`\n- **Init**（source_file）：CREATE EXTENSION IF NOT EXISTS vector; CREATE EXTENSION IF NOT EXISTS \"uuid-ossp\"; 证据：`config/init.sql`\n- **Docker Compose**（source_file）：services: postgres: image: pgvector/pgvector:pg16 ports: - \"5432:5432\" environment: POSTGRES DB: genesys POSTGRES USER: genesys POSTGRES PASSWORD: genesys volumes: - postgres data:/var/lib/postgresql/data - ./config/init.sql:/docker-entrypoint-initdb.d/init.sql:ro healthcheck: test: \"CMD-SHELL\", \"pg isready -U genesys\" interval: 10s timeout: 5s retries: 5 证据：`docker-compose.yml`\n- **Pyproject**（source_file）：project name = \"genesys-memory\" dynamic = \"version\" description = \"The intelligence layer for AI memory — scoring, causal inference, lifecycle management, and active forgetting\" readme = \"README.md\" authors = {name = \"Genesys Contributors\"} license = {text = \"AGPL-3.0-or-later\"} requires-python = \" =3.11\" keywords = \"memory\", \"ai\", \"mcp\", \"causal-graph\", \"agents\" classifiers = \"Development Status :: 4 - Beta\", \"Intended Audience :: Developers\", \"License :: OSI Approved :: GNU Affero General Public License v3 or later AGPLv3+ \", \"Programming Language :: Python :: 3.11\", \"Programming Language :: Python :: 3.12\", \"Topic :: Scientific/Engineering :: Artificial Intelligence\", dependencies = \"pyd… 证据：`pyproject.toml`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\"Migrate memories from JSON in-memory backend to Postgres. 证据：`scripts/migrate_to_postgres.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`benchmarks/README.md`, `CONTRIBUTING.md`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`benchmarks/README.md`, `CONTRIBUTING.md`, `LICENSE`\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- **项目介绍**：importance `high`\n  - source_paths: README.md, src/genesys_memory/engine/scoring.py, src/genesys_memory/models/node.py\n- **安装指南**：importance `high`\n  - source_paths: pyproject.toml, .env.example\n- **快速开始**：importance `high`\n  - source_paths: docker-compose.yml, Dockerfile, src/genesys_memory/server.py\n- **系统架构**：importance `high`\n  - source_paths: src/genesys_memory/__init__.py, src/genesys_memory/engine/__init__.py, src/genesys_memory/storage/__init__.py, src/genesys_memory/providers.py\n- **数据模型**：importance `high`\n  - source_paths: src/genesys_memory/models/node.py, src/genesys_memory/models/edge.py, src/genesys_memory/models/enums.py\n- **评分引擎**：importance `high`\n  - source_paths: src/genesys_memory/engine/scoring.py, src/genesys_memory/engine/config.py\n- **记忆生命周期**：importance `high`\n  - source_paths: src/genesys_memory/engine/transitions.py, src/genesys_memory/engine/reactivation.py, src/genesys_memory/engine/forgetting.py, src/genesys_memory/core_memory/promoter.py\n- **MCP 工具集**：importance `high`\n  - source_paths: src/genesys_memory/mcp/tools.py, src/genesys_memory/mcp/__init__.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `0015664c38ab5fa65f2fbe512a57700fd6712175`\n- inspected_files: `pyproject.toml`, `Dockerfile`, `README.md`, `docker-compose.yml`, `src/genesys_memory/context.py`, `src/genesys_memory/server.py`, `src/genesys_memory/__init__.py`, `src/genesys_memory/__main__.py`, `src/genesys_memory/providers.py`, `src/genesys_memory/mcp/tools.py`, `src/genesys_memory/mcp/__init__.py`, `src/genesys_memory/core_memory/preferences.py`, `src/genesys_memory/core_memory/promoter.py`, `src/genesys_memory/core_memory/__init__.py`, `src/genesys_memory/models/edge.py`, `src/genesys_memory/models/enums.py`, `src/genesys_memory/models/__init__.py`, `src/genesys_memory/models/node.py`, `src/genesys_memory/storage/memory.py`, `src/genesys_memory/storage/__init__.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: 可能修改宿主 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:1207565616 | https://github.com/rishimeka/genesys | host_targets=mcp_host, claude\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:1207565616 | https://github.com/rishimeka/genesys | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | release_recency=unknown\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项目：rishimeka/genesys\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\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 可能修改宿主 AI 配置（medium）：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（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/rishimeka/genesys 项目说明书\n\n生成时间：2026-05-14 08:09:06 UTC\n\n## 目录\n\n- [项目介绍](#page-introduction)\n- [安装指南](#page-installation)\n- [快速开始](#page-quickstart)\n- [系统架构](#page-architecture)\n- [数据模型](#page-data-models)\n- [评分引擎](#page-scoring-engine)\n- [记忆生命周期](#page-memory-lifecycle)\n- [MCP 工具集](#page-mcp-tools)\n- [存储后端实现](#page-storage-backends)\n- [检索系统](#page-retrieval-system)\n\n<a id='page-introduction'></a>\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)\n</details>\n\n# 项目介绍\n\n## 概述\n\nGenesys 是一个面向 AI Agent 的**记忆评分引擎、因果图谱和生命周期管理器**。它解决了传统向量存储记忆方案的局限性——虽然能提供检索能力，但缺乏对记忆之间关系的理解。Genesys 通过乘法评分公式（相关性 × 连接性 × 再激活）对每条记忆进行评分，构建因果图谱实现关系推理，并主动遗忘已变得不相关的记忆。资料来源：[README.md]()\n\nGenesys 的核心理念是：记忆应该像人类一样，具有生命周期、会衰减、会被强化、会被遗忘，而非简单地堆积在向量数据库中。资料来源：[README.md]()\n\n## 核心架构\n\n### 系统定位\n\nGenesys 位于 LLM 与记忆存储层之间，作为**智能记忆层**运行。它不直接存储数据，而是协调多种存储后端，并通过 MCP（Model Context Protocol）协议与 AI 客户端原生集成。资料来源：[README.md]()\n\n```mermaid\ngraph TD\n    A[AI 客户端<br/>Claude/Codellm] -->|MCP 协议| B[Genesys<br/>记忆引擎]\n    B -->|评分/图谱/生命周期| C{存储后端}\n    C -->|向量+图| D[Postgres + pgvector]\n    C -->|本地优先| E[Obsidian Vault]\n    C -->|图数据库| F[FalkorDB]\n    C -->|内存模式| G[SQLite]\n```\n\n### 核心组件\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| **评分引擎** | 计算记忆的衰减分数（相关性×连接性×再激活） | `engine/scoring.py` |\n| **因果图谱** | 管理记忆节点和边，执行图遍历和扩展激活 | `models/node.py` |\n| **生命周期管理器** | 状态转移：ACTIVE → DORMANT → FADING → PRUNED | `engine/transitions.py` |\n| **MCP 服务器** | 提供标准化工具接口，连接 AI 客户端 | `server.py` |\n| **存储抽象层** | 统一接口支持多种后端（Postgres/Obsidian/FalkorDB） | `storage/base.py` |\n\n## 记忆评分机制\n\n### 评分公式\n\nGenesys 采用**三力乘法模型**对记忆进行评分：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n资料来源：[README.md]()\n\n| 维度 | 含义 | 衰减行为 |\n|------|------|----------|\n| **Relevance（相关性）** | 记忆与当前上下文的相关程度 | 随时间自然衰减，除非被强化 |\n| **Connectivity（连接性）** | 记忆在因果图中的链接数量 | 链接越多，存活能力越强（Hub 记忆） |\n| **Reactivation（再激活）** | 记忆被回忆的频率 | 频繁访问的记忆获得boost |\n\n由于采用乘法公式，记忆必须同时在**三个维度**上都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁被回忆但没有因果链接的\"孤岛\"记忆同样会消失。资料来源：[README.md]()\n\n### 评分源代码逻辑\n\n```python\n# 来自 engine/llm_provider.py 的因果关系检测\nasync def identify_causal_relationships(\n    self, \n    new_memory: str, \n    existing_memories: list[tuple[str, str]]\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"\n    识别新记忆与已有记忆之间的因果关系\n    仅包含置信度 > 0.6 的关系\n    \"\"\"\n    results: list[tuple[str, EdgeType, float, str | None]] = []\n    for item in data:\n        confidence = float(item.get(\"confidence\", 0.0))\n        if confidence > 0.6:\n            results.append((\n                item[\"target_id\"], \n                EdgeType(edge_type_str), \n                confidence, \n                item.get(\"reason\")\n            ))\n    return results\n```\n\n资料来源：[src/genesys_memory/engine/llm_provider.py:1-30]()\n\n## 记忆生命周期\n\n### 状态转移图\n\n```mermaid\ngraph TD\n    STORE[STORE<br/>新建记忆] -->|评分>阈值| ACTIVE[ACTIVE<br/>活跃]\n    ACTIVE -->|长期低分| DORMANT[DORMANT<br/>休眠]\n    DORMANT -->|再次回忆| ACTIVE\n    DORMANT -->|持续衰减| FADING[FADING<br/>消退]\n    FADING -->|重新激活| ACTIVE\n    FADING -->|评分归零且无链接| PRUNED[PRUNED<br/>删除]\n    STORE -->|tagged状态| TAGGED[TAGGED<br/>已标记]\n    TAGGED -->|形成边连接| ACTIVE\n    TAGGED -->|24h无连接| PRUNED\n    ACTIVE -->|promote| CORE[CORE<br/>核心记忆<br/>永不删除]\n```\n\n资料来源：[README.md]()\n\n### 状态详情\n\n| 状态 | 说明 | 转移条件 |\n|------|------|----------|\n| **STORE** | 初始创建的记忆 | 自动转移至 ACTIVE 或 TAGGED |\n| **ACTIVE** | 正常参与检索的记忆 | 评分下降时转入 DORMANT |\n| **DORMANT** | 暂时搁置但未删除 | 被召回时转回 ACTIVE |\n| **FADING** | 即将被遗忘 | 可被 reactivation 救回，或进入 PRUNED |\n| **CORE** | 核心记忆，结构重要性高 | 自动 pin，永不删除 |\n| **PRUNED** | 已删除的记忆 | 不可逆 |\n\n### Tagged → Active 转移逻辑\n\n```python\n# 来自 engine/transitions.py\nasync def evaluate_transitions(...):\n    # Tagged → Active: 如果节点有边则提升\n    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)\n    for node in tagged_nodes:\n        if not await graph.is_orphan(str(node.id)):\n            await graph.update_node(str(node.id), {\"status\": MemoryStatus.ACTIVE})\n            # 原因：consolidation signal: edge formed\n```\n\n资料来源：[src/genesys_memory/engine/transitions.py:1-30]()\n\n## 存储后端\n\nGenesys 支持多种存储后端，可根据使用场景灵活选择：\n\n| 后端 | 安装方式 | 适用场景 | 特点 |\n|------|----------|----------|------|\n| **memory** | 内置无需安装 | 快速尝鲜 | 零依赖，纯内存存储 |\n| **postgres** | `pip install genesys-memory[postgres]` | 生产环境 | 持久化、可扩展、向量搜索 |\n| **Obsidian** | `pip install genesys-memory[obsidian]` | 本地知识库 | Markdown 文件作为记忆节点，wikilinks 自动转为因果边 |\n| **FalkorDB** | `pip install genesys-memory[falkordb]` | 图数据库场景 | 原生图遍历，Redis 底层 |\n| **自定义** | 实现 `GraphStorageProvider` 接口 | 特殊需求 | 完全可插拔 |\n\n资料来源：[README.md]()\n\n### Obsidian Vault 集成\n\nObsidian 后端特别适合个人知识管理场景：\n\n- Markdown 文件自动转为记忆节点\n- `[[wikilinks]]` 自动转为因果边\n- SQLite 侧car（`.genesys/index.db`）处理索引\n- 文件监视器增量重索引\n\n资料来源：[README.md]()\n\n### 完全本地模式（无 API Key）\n\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n# 无需 OPENAI_API_KEY\n```\n\n本地嵌入使用 `all-MiniLM-L6-v2`（384 维）模型，首次使用时自动下载（约 80MB）。资料来源：[README.md]()\n\n## MCP 工具接口\n\nGenesys 通过 MCP（Model Context Protocol）提供标准化工具接口：\n\n| 工具名称 | 功能描述 | 参数 |\n|----------|----------|------|\n| `memory_store` | 存储新记忆，可选链接相关记忆 | `content`, `related_to?`, `source_session?` |\n| `memory_recall` | 混合检索（向量+关键词+图扩散激活） | `query`, `k?`, `max_results?` |\n| `memory_search` | 带过滤条件的向量搜索 | `query`, `filters?`, `k?` |\n| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id`, `depth?`, `edge_types?` |\n| `memory_explain` | 解释记忆的评分构成 | `node_id` |\n| `memory_stats` | 获取记忆系统统计信息 | 无 |\n| `pin_memory` | 将记忆固定为核心，永不遗忘 | `node_id` |\n| `unpin_memory` | 取消固定，重新评估核心资格 | `node_id` |\n| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |\n| `list_core_memories` | 列出所有核心记忆 | `category?` |\n| `set_core_preferences` | 配置核心记忆类别偏好 | `auto?`, `approval?`, `excluded?` |\n\n资料来源：[src/genesys_memory/server.py:1-80]()\n\n### 记忆存储工具实现\n\n```python\n# 来自 mcp/tools.py\nnode = MemoryNode(\n    status=MemoryStatus.ACTIVE,\n    content_summary=summary,\n    content_full=content,\n    embedding=embedding,\n    created_at=ts,\n    last_accessed_at=ts,\n    last_reactivated_at=ts,\n    decay_score=1.0,\n    causal_weight=0,\n    source_agent=\"claude\",\n    source_session=source_session,\n    visibility=vis,\n    org_id=org_id,\n    original_user_id=_caller_uid(),\n)\nnode_id = await self.graph.create_node(node)\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py:1-50]()\n\n## 记忆合并（Consolidation）\n\n当大量情景记忆积累后，系统会自动将其合并为语义记忆：\n\n```python\n# 来自 engine/consolidation.py\nasync def consolidate(episodic_memories: list[str], ...) -> str:\n    # 匹配相关内容\n    matching = await embeddings.find_similar(consolidated_text, ...)\n    \n    # 创建新的语义节点\n    semantic_node = MemoryNode(\n        status=MemoryStatus.SEMANTIC,\n        content_summary=summary,\n        content_full=consolidated_text,\n        embedding=embedding,\n        created_at=now,\n        entity_refs=[entity_ref],\n    )\n    \n    # 创建 DERIVED_FROM 边\n    for source_node in matching:\n        edge = MemoryEdge(\n            source_id=semantic_node.id,\n            target_id=source_node.id,\n            type=EdgeType.DERIVED_FROM,\n            weight=0.7,\n        )\n        await graph.create_edge(edge)\n```\n\n资料来源：[src/genesys_memory/engine/consolidation.py:1-60]()\n\n## 基准测试\n\nGenesys 在 [LoCoMo](https://arxiv.org/abs/2402.06397) 长对话记忆基准上进行了测试（1540 个问题，10 个对话）：\n\n| 类别 | J-Score |\n|------|---------|\n| Single-hop（单跳） | 94.3% |\n| Temporal（时序） | 87.5% |\n| Multi-hop（多跳） | 69.8% |\n| Open-domain（开放域） | 91.7% |\n| **总体** | **89.9%** |\n\n对比基线：Mem0 67.1%，Zep 75.1%\n\n资料来源：[README.md]()\n\n## 快速开始\n\n### 环境要求\n\n- Python 3.11+\n- 可选：OpenAI API Key（用于嵌入生成，非必须）\n- 可选：Anthropic API Key（用于 LLM 记忆处理）\n\n### 安装\n\n```bash\npip install genesys-memory\n```\n\n### 启动服务器\n\n```bash\n# 方式一：使用内存后端（零配置）\ncp .env.example .env\n# 配置 OPENAI_API_KEY\nuvicorn genesys.api:app --port 8000\n\n# 方式二：使用 Obsidian 后端\npip install 'genesys-memory[obsidian,local]'\nuvicorn genesys.api:app --port 8000\n```\n\n### 连接 Claude Desktop\n\n在 `claude_desktop_config.json` 中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### 连接 Claude Code\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n资料来源：[README.md]()\n\n## 配置选项\n\n| 环境变量 | 必需 | 说明 |\n|----------|------|------|\n| `OPENAI_API_KEY` | 除非使用本地嵌入 | 用于嵌入生成 |\n| `ANTHROPIC_API_KEY` | 否 | 用于 LLM 记忆处理和合并 |\n| `GENESYS_BACKEND` | 否 | `memory`（默认）、`postgres`、`obsidian`、`falkordb` |\n| `GENESYS_EMBEDDER` | 否 | `openai`（默认）或 `local` |\n| `DATABASE_URL` | 如果使用 postgres | Postgres 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | 如果使用 obsidian | Obsidian 保险库路径 |\n| `FALKORDB_HOST` | 如果使用 falkordb | FalkorDB 主机（默认 localhost） |\n| `GENESYS_USER_ID` | 否 | 单租户模式的默认用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | 状态持久化路径 |\n\n资料来源：[README.md]()\n\n## 开发指南\n\n### 代码规范\n\n- **Python 版本**：3.11+\n- **代码风格**：async-first\n- **Linting**：`ruff check src/`\n- **类型检查**：`mypy src/genesys_memory --ignore-missing-imports`\n- **格式化**：遵循现有模式，类型提示贯穿始终\n\n### 测试\n\n```bash\n# 运行所有单元测试\npytest tests/ -v\n\n# 带覆盖率\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n资料来源：[CONTRIBUTING.md]()\n\n## 技术栈\n\n| 技术 | 用途 |\n|------|------|\n| **Python 3.11+** | 主要开发语言 |\n| **FastAPI/Starlette** | Web 框架和 ASGI 服务器 |\n| **pgvector** | PostgreSQL 向量搜索扩展 |\n| **sentence-transformers** | 本地嵌入模型 |\n| **SQLAlchemy** | ORM（Postgres 后端） |\n| **Pydantic** | 数据验证和序列化 |\n| **Model Context Protocol** | AI 客户端通信协议 |\n\n资料来源：[README.md](), [server.json]()\n\n## 许可证与归属\n\nGenesys 采用 **AGPL-3.0-or-later** 开源许可证。\n\n> **注意**：v0.3.6 之前的版本文档中错误标注为 Apache 2.0。LICENSE 文件始终包含 AGPLv3 文本。资料来源：[README.md]()\n\n项目由 [Rishi Meka](https://github.com/rishimeka) 在 [Astrix Labs](https://astrixlabs.ai) 创建，目标是构建 LLM 与记忆之间的智能层。资料来源：[README.md]()\n\n---\n\n<a id='page-installation'></a>\n\n## 安装指南\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/rishimeka/genesys/blob/main/pyproject.toml)\n- [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n</details>\n\n# 安装指南\n\n本页面详细说明如何在不同环境下安装和配置 Genesys 内存系统。Genesys 支持多种存储后端和嵌入提供商，可根据使用场景灵活选择。\n\n## 前提条件\n\n### 系统要求\n\n| 要求 | 规格 |\n|------|------|\n| Python 版本 | 3.11+ |\n| 操作系统 | macOS、Linux、Windows（WSL 推荐） |\n| 内存 | 建议 4GB+ |\n| 磁盘空间 | 约 500MB（不含模型缓存） |\n\n### 必要依赖\n\n安装前需确保系统已安装以下工具：\n\n- **Python 3.11+** — 可通过 [python.org](https://www.python.org/downloads/) 或系统包管理器安装\n- **pip** — Python 包管理器（通常随 Python 一起安装）\n- **Git** — 用于从源码安装\n\n## 安装方式\n\nGenesys 提供两种主要安装方式：从 PyPI 安装预发布版本，或从源码编译最新版本。\n\n### 方式一：从 PyPI 安装（推荐）\n\n```bash\n# 基础安装（仅内置内存后端）\npip install genesys-memory\n\n# 生产环境（Postgres 后端）\npip install 'genesys-memory[postgres]'\n\n# Obsidian 集成\npip install 'genesys-memory[obsidian]'\n\n# Obsidian + 本地嵌入（无需 API Key）\npip install 'genesys-memory[obsidian,local]'\n\n# FalkorDB 图形数据库后端\npip install 'genesys-memory[falkordb]'\n\n# 开发环境（包含测试依赖）\npip install 'genesys-memory[dev]'\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方式二：从源码安装\n\n适用于需要最新功能或进行开发贡献的用户：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 以开发模式安装（包含所有依赖）\npip install -e '.[dev]'\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 存储后端选择\n\nGenesys 采用插件化架构，支持多种存储后端。选择合适的后端取决于具体使用场景：\n\n| 后端 | 安装命令 | 适用场景 | 依赖 |\n|------|----------|----------|------|\n| **memory** | 内置，无需额外安装 | 快速体验、零依赖 | 无 |\n| **postgres** | `pip install 'genesys-memory[postgres]'` | 生产环境、持久化存储 | PostgreSQL + pgvector |\n| **obsidian** | `pip install 'genesys-memory[obsidian]'` | 本地知识库、个人笔记 | Obsidian Vault |\n| **falkordb** | `pip install 'genesys-memory[falkordb]'` | 图原生查询、大规模关系 | FalkorDB (Redis-based) |\n\n### 后端架构概览\n\n```mermaid\ngraph TB\n    subgraph \"存储后端层\"\n        MEM[memory<br/>内置字典]\n        PG[postgres + pgvector]\n        OBS[Obsidian Vault]\n        FALK[FalkorDB]\n    end\n    \n    subgraph \"核心引擎层\"\n        ENG[评分引擎]\n        CAU[因果图]\n        LCM[生命周期管理器]\n    end\n    \n    subgraph \"API 层\"\n        MCP[MCP 协议接口]\n        REST[REST API]\n    end\n    \n    MEM --> ENG\n    PG --> ENG\n    OBS --> ENG\n    FALK --> ENG\n    \n    ENG --> CAU\n    CAU --> LCM\n    \n    MCP --> ENG\n    REST --> ENG\n```\n\n## 配置指南\n\n### 环境变量配置\n\n将 `.env.example` 复制为 `.env` 文件，并配置以下变量：\n\n```bash\ncp .env.example .env\n```\n\n### 配置参数详解\n\n| 变量名 | 是否必需 | 默认值 | 说明 |\n|--------|----------|--------|------|\n| `OPENAI_API_KEY` | 否* | — | OpenAI API 密钥，用于生成嵌入向量 |\n| `ANTHROPIC_API_KEY` | 否 | — | Anthropic API 密钥，用于 LLM 内存处理 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供商：`openai` 或 `local` |\n| `DATABASE_URL` | 条件必需 | — | PostgreSQL 连接字符串（使用 postgres 后端时） |\n| `OBSIDIAN_VAULT_PATH` | 条件必需 | — | Obsidian 保险库路径（使用 obsidian 后端时） |\n| `FALKORDB_HOST` | 条件必需 | `localhost` | FalkorDB 主机地址（使用 falkordb 后端时） |\n| `GENESYS_USER_ID` | 否 | — | 单租户模式的默认用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | — | 内存后端状态持久化文件路径 |\n\n*使用 `GENESYS_EMBEDDER=local` 时不需要 `OPENAI_API_KEY`\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)、[.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n\n## 快速启动方案\n\n### 方案一：内存模式（零依赖）\n\n适用于快速体验和开发测试：\n\n```bash\n# 安装基础包\npip install genesys-memory\n\n# 创建配置文件\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=memory\n```\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案二：Postgres + pgvector（生产环境）\n\n适用于需要持久化存储的生产部署：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[postgres]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=postgres\nDATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys\n```\n\n启动 PostgreSQL 并运行迁移：\n\n```bash\n# 使用 Docker 启动 Postgres\ndocker compose up -d postgres\n\n# 运行数据库迁移\nalembic upgrade head\n\n# 启动服务器\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案三：Obsidian Vault（本地优先）\n\n将 Obsidian 笔记库转换为 Genesys 记忆存储：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[obsidian]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=obsidian\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n```\n\n**自动检测功能**：如果未设置 `OBSIDIAN_VAULT_PATH`，Genesys 会自动在以下位置查找：\n- `~/Documents/personal`\n- `~/Documents/Obsidian`\n- `~/obsidian`\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n首次启动时，Genesys 会自动索引保险库中的所有 `.md` 文件。文件监视器会在编辑笔记时增量重新索引。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案四：完全本地模式（无需 API Key）\n\n使用本地嵌入模型，无需任何外部 API：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[obsidian,local]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\nOBSIDIAN_VAULT_PATH=/path/to/your/vault\n# 无需 OPENAI_API_KEY\n```\n\n启动服务器：\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n**本地嵌入模型**：`all-MiniLM-L6-v2`（384 维），首次使用时会自动下载（约 80MB）。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 方案五：FalkorDB（图原生）\n\n适用于需要原生图遍历的大规模关系数据：\n\n```bash\n# 安装依赖\npip install 'genesys-memory[falkordb]'\n\n# 配置环境变量\ncp .env.example .env\n```\n\n编辑 `.env`：\n\n```env\nOPENAI_API_KEY=sk-your-api-key-here\nGENESYS_BACKEND=falkordb\nFALKORDB_HOST=localhost\n```\n\n启动 FalkorDB 和服务器：\n\n```bash\n# 使用 Docker 启动 FalkorDB\ndocker compose up -d falkordb\n\n# 启动服务器\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## Docker 部署\n\n### 使用 Docker Compose 启动服务\n\n项目提供了 `docker-compose.yml` 文件，可一键启动完整环境：\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 启动所有服务（包括 Postgres）\ndocker compose up -d\n\n# 或仅启动 Postgres\ndocker compose up -d postgres\n```\n\n### 环境变量配置\n\n在使用 Docker 部署时，确保 `docker-compose.yml` 中的环境变量配置正确。典型的环境变量包括：\n\n```yaml\nenvironment:\n  - OPENAI_API_KEY=${OPENAI_API_KEY}\n  - GENESYS_BACKEND=postgres\n  - DATABASE_URL=postgresql://genesys:genesys@postgres:5432/genesys\n```\n\n资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n\n## 验证安装\n\n### 启动服务器验证\n\n服务器成功启动后，应看到类似输出：\n\n```\nINFO:     Uvicorn running on http://0.0.0.0:8000\nINFO:     Application startup complete.\n```\n\n### MCP 工具列表\n\n启动后可通过以下端点查看可用工具：\n\n```\nGET http://localhost:8000/mcp\n```\n\n可用工具包括：\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory_store` | 存储新记忆，可选择链接相关记忆 |\n| `memory_recall` | 通过自然语言查询回忆记忆（向量 + 图搜索） |\n| `memory_search` | 按状态、日期、关键词筛选搜索 |\n| `memory_traverse` | 从给定记忆节点遍历因果图 |\n| `memory_explain` | 解释记忆存在的原因及其因果链 |\n| `memory_stats` | 获取记忆系统统计信息 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定记忆 |\n| `delete_memory` | 永久删除记忆 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆类别偏好 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 连接到 AI 助手\n\n### Claude Desktop 配置\n\n在 `claude_desktop_config.json` 中添加配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n### 通用 MCP 客户端\n\n直接指向 MCP 端点：\n\n```\nhttp://localhost:8000/mcp\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 开发环境安装\n\n如需为 Genesys 项目贡献代码，请按以下步骤设置开发环境：\n\n### 1. 克隆并安装\n\n```bash\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\npip install -e '.[dev]'\n```\n\n### 2. 代码质量工具\n\n项目使用以下工具维护代码质量：\n\n```bash\n# 代码检查\nruff check src/\n\n# 类型检查\nmypy src/genesys_memory --ignore-missing-imports\n\n# 运行测试\npytest tests/ -v\n\n# 带覆盖率报告的测试\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n### 3. 代码规范\n\n- **Python 版本**：3.11+\n- **异步优先**：使用 async/await 模式\n- **类型提示**：全程使用类型注解\n- **行长度限制**：120 字符（配置于 `pyproject.toml`）\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 故障排除\n\n### 常见问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| `ImportError: No module named 'genesys_memory'` | 确保已正确安装：`pip install genesys-memory` |\n| `OPENAI_API_KEY` 错误 | 检查 `.env` 文件中的 API Key 是否正确，或使用本地嵌入模式 |\n| Postgres 连接失败 | 确认 Docker 容器运行中，检查 `DATABASE_URL` 格式 |\n| Obsidian 索引失败 | 确认 `OBSIDIAN_VAULT_PATH` 路径存在且包含 `.md` 文件 |\n| 端口 8000 被占用 | 使用 `--port` 参数指定其他端口，如 `--port 8001` |\n\n### 状态持久化\n\n如需在进程重启后保留内存后端数据，设置持久化路径：\n\n```env\nGENESYS_PERSIST_PATH=.genesys_state.json\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 依赖项参考\n\n### 核心依赖\n\n从 `pyproject.toml` 中提取的核心依赖包括：\n\n- `fastapi` — Web 框架\n- `uvicorn` — ASGI 服务器\n- `pydantic` — 数据验证\n- `numpy` — 数值计算\n- `httpx` — HTTP 客户端\n- `anthropic` — Anthropic API 集成\n- `openai` — OpenAI API 集成\n- `sqlalchemy` — ORM 框架\n- `alembic` — 数据库迁移\n- `psycopg2-binary` — PostgreSQL 驱动\n\n### 可选依赖组\n\n| 组名 | 主要依赖 | 用途 |\n|------|----------|------|\n| `postgres` | `psycopg2-binary`, `alembic` | PostgreSQL 存储后端 |\n| `obsidian` | `watchfiles` | Obsidian 笔记集成 |\n| `local` | `sentence-transformers` | 本地嵌入模型 |\n| `falkordb` | `redis`, `falkordb` | FalkorDB 图形数据库 |\n| `dev` | `pytest`, `ruff`, `mypy` | 开发工具 |\n\n## 下一步\n\n安装完成后，建议：\n\n1. **运行演示脚本**：使用 `seed_demo.py` 填充示例数据\n2. **阅读架构文档**：了解 Genesys 的评分引擎和生命周期管理\n3. **探索 MCP 工具**：尝试不同的记忆操作\n4. **贡献代码**：查看 [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md) 了解贡献流程\n\n---\n\n<a id='page-quickstart'></a>\n\n## 快速开始\n\n### 相关页面\n\n相关主题：[安装指南](#page-installation), [MCP 工具集](#page-mcp-tools)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n- [Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n</details>\n\n# 快速开始\n\nGenesys 是一个面向 AI Agent 的记忆引擎，提供因果图谱、评分系统和生命周期管理功能。通过 MCP（Model Context Protocol）协议与 AI 助手原生集成，支持多种存储后端以适应不同场景需求。资料来源：[README.md:1-15]()\n\n## 系统架构概览\n\n```mermaid\ngraph TD\n    subgraph \"客户端层\"\n        Claude_Desktop[\"Claude Desktop\"]\n        Claude_Code[\"Claude Code\"]\n        其他MCP客户端[\"其他 MCP 客户端\"]\n    end\n    \n    subgraph \"Genesys 服务层\"\n        API[\"FastAPI / Uvicorn\"]\n        MCPServer[\"MCP Server\"]\n        Engine[\"记忆引擎\"]\n    end\n    \n    subgraph \"存储后端\"\n        Memory[\"In-Memory\"]\n        Postgres[\"Postgres + pgvector\"]\n        Obsidian[\"Obsidian Vault\"]\n        FalkorDB[\"FalkorDB\"]\n    end\n    \n    Claude_Desktop --> MCPServer\n    Claude_Code --> MCPServer\n    其他MCP客户端 --> MCPServer\n    API --> MCPServer\n    MCPServer --> Engine\n    Engine --> Memory\n    Engine --> Postgres\n    Engine --> Obsidian\n    Engine --> FalkorDB\n```\n\n## 前置要求\n\n| 要求 | 说明 |\n|------|------|\n| Python 版本 | 3.11+ |\n| Docker（可选） | 用于 Postgres、FalkorDB 等后端 |\n| API 密钥 | OpenAI API Key（使用 `GENESYS_EMBEDDER=local` 时可选） |\n\n资料来源：[CONTRIBUTING.md:1-10]()\n\n## 安装方式\n\n### 方式一：pip 安装（推荐）\n\n```bash\n# 基础安装（内置内存存储）\npip install genesys-memory\n\n# 安装特定存储后端\npip install 'genesys-memory[postgres]'      # Postgres + pgvector\npip install 'genesys-memory[obsidian]'      # Obsidian Vault\npip install 'genesys-memory[obsidian,local]' # 完全本地化\npip install 'genesys-memory[falkordb]'       # FalkorDB 图数据库\n```\n\n资料来源：[README.md:1-50]()\n\n### 方式二：从源码安装\n\n```bash\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\npip install -e '.[dev]'\n```\n\n资料来源：[CONTRIBUTING.md:1-15]()\n\n### 方式三：Docker 部署\n\n```bash\n# 克隆仓库\ngit clone https://github.com/rishimeka/genesys.git\ncd genesys\n\n# 启动完整服务栈（包括 Postgres）\ndocker compose up -d\n```\n\n资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)\n\n## 环境配置\n\n### 配置文件创建\n\n```bash\ncp .env.example .env\n```\n\n资料来源：[README.md:50-100]()\n\n### 环境变量说明\n\n| 变量名 | 必填 | 说明 | 默认值 |\n|--------|------|------|--------|\n| `OPENAI_API_KEY` | 否* | Embedding 生成密钥 | - |\n| `ANTHROPIC_API_KEY` | 否 | LLM 记忆处理密钥 | - |\n| `GENESYS_BACKEND` | 否 | 存储后端类型 | `memory` |\n| `GENESYS_EMBEDDER` | 否 | Embedding 提供商 | `openai` |\n| `DATABASE_URL` | postgres 时必填 | Postgres 连接字符串 | - |\n| `OBSIDIAN_VAULT_PATH` | obsidian 时必填 | Obsidian 仓库路径 | - |\n| `FALKORDB_HOST` | falkordb 时必填 | FalkorDB 主机地址 | `localhost` |\n| `GENESYS_USER_ID` | 否 | 单租户模式默认用户 ID | - |\n| `GENESYS_PERSIST_PATH` | 否 | 内存后端持久化路径 | - |\n\n*使用 `GENESYS_EMBEDDER=local` 时不需要\n\n资料来源：[README.md:100-120](), [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)\n\n## 启动服务器\n\n### 使用 uvicorn 启动\n\n```bash\n# 默认内存模式（零依赖）\nuvicorn genesys.api:app --port 8000\n\n# 指定后端\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md:50-80]()\n\n### 使用 Docker 启动\n\n```bash\n# 构建镜像\ndocker build -t genesys-memory .\n\n# 运行容器\ndocker run -p 8000:8000 \\\n  -e OPENAI_API_KEY=sk-... \\\n  -e GENESYS_BACKEND=memory \\\n  genesys-memory\n```\n\n资料来源：[Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)\n\n## MCP 服务集成\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n资料来源：[README.md:150-160]()\n\n### Claude Desktop 配置\n\n在 `claude_desktop_config.json` 中添加：\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n资料来源：[README.md:160-175]()\n\n### 其他 MCP 客户端\n\n直接连接到 MCP 端点：\n\n```\nhttp://localhost:8000/mcp\n```\n\n## MCP 工具列表\n\nGenesys 提供以下 MCP 工具用于记忆管理：\n\n| 工具名称 | 功能描述 | 必需参数 |\n|----------|----------|----------|\n| `memory_store` | 存储新记忆，可选关联相关记忆 | `content` |\n| `memory_recall` | 混合搜索召回记忆（向量+关键词+图传播） | `query` |\n| `memory_search` | 按状态、分类、日期等条件过滤搜索 | `query` |\n| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id` |\n| `memory_explain` | 解释记忆的评分细节和因果链 | `node_id` |\n| `memory_stats` | 获取图谱统计信息 | - |\n| `pin_memory` | 将记忆固定为核心记忆 | `node_id` |\n| `unpin_memory` | 取消固定并重新评估核心资格 | `node_id` |\n| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |\n| `list_core_memories` | 列出所有核心记忆 | `category`（可选） |\n| `set_core_preferences` | 配置核心记忆分类偏好 | `auto`, `approval`, `excluded` |\n\n资料来源：[README.md:130-150](), [src/genesys_memory/server.py:1-80]()\n\n## 记忆数据模型\n\n```mermaid\nclassDiagram\n    class MemoryNode {\n        uuid id\n        MemoryStatus status\n        str content_summary\n        str content_full\n        list~float~ embedding\n        datetime created_at\n        datetime last_accessed_at\n        float decay_score\n        int causal_weight\n        int reactivation_count\n        bool pinned\n        str category\n    }\n    \n    class MemoryEdge {\n        uuid source_id\n        uuid target_id\n        EdgeType type\n        float weight\n    }\n    \n    MemoryNode \"1\" --> \"*\" MemoryEdge : edges\n```\n\n资料来源：[src/genesys_memory/models/node.py:1-40]()\n\n### MemoryNode 核心字段\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID\n    status: MemoryStatus  # ACTIVE, DORMANT, FADING, PRUNED\n    content_summary: str  # 最大 200 字符\n    content_full: str | None\n    embedding: list[float] | None\n    decay_score: float = 1.0\n    causal_weight: int = 0\n    reactivation_count: int = 0\n    pinned: bool = False\n    category: str | None\n    stability: float = 1.0\n```\n\n资料来源：[src/genesys_memory/models/node.py:10-35]()\n\n## 存储后端对比\n\n| 后端 | 安装命令 | 适用场景 |\n|------|----------|----------|\n| `memory` | 内置 | 零依赖、快速试用 |\n| `postgres` + pgvector | `pip install 'genesys-memory[postgres]'` | 生产环境、高可用 |\n| `obsidian` | `pip install 'genesys-memory[obsidian]'` | 本地优先、知识库 |\n| `falkordb` | `pip install 'genesys-memory[falkordb]'` | 图原生遍历 |\n\n资料来源：[README.md:80-95]()\n\n## Postgres 后端启动流程\n\n```bash\n# 1. 安装依赖\npip install 'genesys-memory[postgres]'\n\n# 2. 编辑 .env\necho \"OPENAI_API_KEY=sk-...\" >> .env\necho \"GENESYS_BACKEND=postgres\" >> .env\necho \"DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys\" >> .env\n\n# 3. 启动 Postgres\ndocker compose up -d postgres\n\n# 4. 运行数据库迁移\nalembic upgrade head\n\n# 5. 启动服务\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md:95-115]()\n\n## 完全本地化配置（无需 API 密钥）\n\n```bash\n# 1. 安装\npip install 'genesys-memory[obsidian,local]'\n\n# 2. 配置 .env\necho \"GENESYS_BACKEND=obsidian\" >> .env\necho \"GENESYS_EMBEDDER=local\" >> .env\necho \"OBSIDIAN_VAULT_PATH=/path/to/your/vault\" >> .env\n\n# 3. 启动服务\nuvicorn genesys.api:app --port 8000\n```\n\n使用 `all-MiniLM-L6-v2`（384 维）模型进行 Embedding，首次使用自动下载（约 80MB）。\n\n资料来源：[README.md:30-50]()\n\n## 记忆生命周期\n\n```mermaid\nstateDiagram-v2\n    [*] --> ACTIVE: 创建\n    ACTIVE --> DORMANT: 衰减评分下降\n    DORMANT --> ACTIVE: 重新激活\n    DORMANT --> FADING: 持续未访问\n    FADING --> DORMANT: 被召回\n    FADING --> PRUNED: 评分归零\n    ACTIVE --> ACTIVE: 定期访问\n```\n\n### 评分公式\n\n记忆评分由三个因素相乘决定：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n- **Relevance（相关性）**：随时间衰减\n- **Connectivity（连接性）**：基于因果边数量\n- **Reactivation（再激活）**：基于访问频率\n\n资料来源：[README.md:175-195]()\n\n## 测试验证\n\n```bash\n# 运行所有测试\npytest tests/ -v\n\n# 带覆盖率报告\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n资料来源：[CONTRIBUTING.md:20-30]()\n\n## 快速启动模板\n\n将以下内容复制给 Claude 即可自动完成配置：\n\n> \"Install genesys-memory, create a .env with my OpenAI key, start the server on port 8000 with the in-memory backend, and connect it as an MCP server.\"\n\n资料来源：[README.md:60-70]()\n\n## 下一步\n\n- 查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解开发规范\n- 访问 [benchmarks/](https://github.com/rishimeka/genesys/tree/main/benchmarks) 了解性能基准\n- 阅读 [LICENSE](LICENSE) 了解开源协议（AGPL-3.0）\n\n---\n\n<a id='page-architecture'></a>\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [数据模型](#page-data-models), [存储后端实现](#page-storage-backends)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)\n- [src/genesys_memory/engine/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/__init__.py)\n- [src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)\n- [src/genesys_memory/providers.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/providers.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n</details>\n\n# 系统架构\n\n## 概述\n\nGenesys 是一个面向 AI Agent 的记忆系统，集成了**评分引擎**、**因果图**和**生命周期管理器**三大核心功能。它通过 MCP（Model Context Protocol）协议与 AI 进行原生交互，支持多种存储后端，能够模拟人类记忆的遗忘机制，对记忆进行动态管理和智能遗忘。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心架构组件\n\nGenesys 的系统架构由以下主要模块组成：\n\n| 模块 | 路径 | 功能描述 |\n|------|------|----------|\n| **Engine** | `src/genesys_memory/engine/` | 核心评分引擎和记忆处理逻辑 |\n| **Storage** | `src/genesys_memory/storage/` | 存储后端抽象和实现 |\n| **Models** | `src/genesys_memory/models/` | 数据模型定义 |\n| **MCP** | `src/genesys_memory/mcp/` | MCP 协议工具实现 |\n| **Core Memory** | `src/genesys_memory/core_memory/` | 核心记忆管理 |\n\n资料来源：[src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)\n\n### 架构分层图\n\n```mermaid\ngraph TB\n    subgraph \"表现层 (MCP Interface)\"\n        MCP[MCP Server]\n        TOOLS[MCP Tools]\n    end\n    \n    subgraph \"核心引擎层 (Engine)\"\n        SCORING[Scoring Engine]\n        LIFECYCLE[Lifecycle Manager]\n        CONSOLIDATION[Consolidation Engine]\n        LLM_PROVIDER[LLM Provider]\n    end\n    \n    subgraph \"存储层 (Storage)\"\n        GRAPH[Graph Storage Provider]\n        CACHE[Cache Provider]\n        EMBEDDING[Embedding Provider]\n        EVENT[Event Bus Provider]\n    end\n    \n    subgraph \"后端实现\"\n        MEMORY[In-Memory Backend]\n        POSTGRES[Postgres + pgvector]\n        OBSIDIAN[Obsidian Vault]\n        FALKOR[FalkorDB]\n    end\n    \n    MCP --> TOOLS\n    TOOLS --> SCORING\n    SCORING --> LIFECYCLE\n    CONSOLATION --> LLM_PROVIDER\n    LLM_PROVIDER --> SCORING\n    \n    SCORING --> GRAPH\n    GRAPH --> CACHE\n    GRAPH --> EMBEDDING\n    \n    GRAPH --> MEMORY\n    GRAPH --> POSTGRES\n    GRAPH --> OBSIDIAN\n    GRAPH --> FALKOR\n```\n\n## 数据模型\n\n### MemoryNode 核心结构\n\n`MemoryNode` 是系统的核心数据模型，定义了一条记忆的所有属性：\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID = Field(default_factory=uuid.uuid4)\n    status: MemoryStatus = MemoryStatus.ACTIVE\n    content_summary: str = Field(max_length=200)\n    content_full: str | None = None\n    content_ref: str | None = None\n    embedding: list[float] | None = None\n    \n    # 时间戳\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n    \n    # 生命周期评分\n    decay_score: float = 1.0      # 衰减分数\n    causal_weight: int = 0        # 因果权重\n    reactivation_count: int = 0   # 激活次数\n    reactivation_pattern: ReactivationPattern  # 激活模式\n    irrelevance_counter: int = 0   # 无关计数器\n    \n    # 分类\n    entity_refs: list[str]        # 实体引用\n    category: str | None          # 类别\n    \n    # 稳定性\n    stability: float = 1.0        # 稳定性（记忆提取成功后增加）\n    \n    # 核心记忆\n    pinned: bool = False          # 是否固定\n    promotion_reason: str | None  # 晋升原因\n```\n\n资料来源：[src/genesys_memory/models/node.py:1-45](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 记忆状态机\n\n记忆在生命周期中经历以下状态转换：\n\n```mermaid\ngraph LR\n    STORE[STORE] --> ACTIVE[ACTIVE]\n    ACTIVE --> DORMANT[DORMANT]\n    DORMANT --> FADING[FADING]\n    FADING --> PRUNED[PRUNED]\n    \n    ACTIVE -.->|reactivation| ACTIVE\n    DORMANT -.->|reactivation| ACTIVE\n    FADING -.->|reactivation| ACTIVE\n    \n    PRUNED -.->|特殊条件| PRUNED\n```\n\n状态说明：\n\n| 状态 | 描述 | 触发条件 |\n|------|------|----------|\n| **STORE** | 初始存储状态 | 新记忆创建时 |\n| **ACTIVE** | 活跃状态 | 记忆被频繁访问 |\n| **DORMANT** | 休眠状态 | 长时间未被访问 |\n| **FADING** | 衰减状态 | decay_score 接近零 |\n| **PRUNED** | 修剪状态 | 彻底遗忘（可被恢复） |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心引擎\n\n### 评分公式\n\nGenesys 的记忆评分采用**乘法公式**，三个维度相乘得出最终分数：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 维度 | 说明 | 衰减特性 |\n|------|------|----------|\n| **relevance** | 相关性 | 随时间衰减，久未强化则消失 |\n| **connectivity** | 连接性 | 奖励因果链接多的记忆，枢纽记忆存活 |\n| **reactivation** | 再激活 | 频繁回忆的记忆得到强化 |\n\n由于采用乘法公式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆会衰减；频繁回忆但无因果链接的记忆也会消失。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### LLM Provider\n\nLLM Provider 负责使用大语言模型进行因果关系识别和记忆整合：\n\n```python\nasync def identify_causal_relationships(\n    new_memory: str,\n    existing_memories: list[tuple[str, str]]\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"识别新记忆与已有记忆之间的因果关系\"\"\"\n    # 返回: (target_id, edge_type, confidence, reason)\n```\n\n**边缘类型**包括：\n- `caused_by` - 因果导致\n- `supports` - 支持关系\n- `derived_from` - 派生关系\n\n资料来源：[src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n\n### Consolidation Engine\n\n整合引擎负责将情景记忆合并为语义记忆：\n\n```mermaid\ngraph TD\n    EPISODIC[Episodic Memories] --> CONSOLIDATE{Consolidation}\n    CONSOLIDATE --> LLM_SUMMARIZE[LLM Summarization]\n    LLM_SUMMARIZE --> SEMANTIC[Semantic Memory Node]\n    \n    CONSOLIDATE --> EDGES[Create DERIVED_FROM Edges]\n    SEMANTIC --> EDGES\n    EDGES --> GRAPH[Graph Storage]\n```\n\n资料来源：[src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n\n## 存储层架构\n\n### 抽象接口设计\n\n存储层通过抽象接口支持多种后端实现：\n\n| 接口 | 职责 |\n|------|------|\n| **GraphStorageProvider** | 图结构存储（节点和边） |\n| **CacheProvider** | 缓存层 |\n| **EmbeddingProvider** | 向量化嵌入生成 |\n| **EventBusProvider** | 事件总线 |\n\n资料来源：[src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)\n\n### 支持的存储后端\n\n```mermaid\ngraph LR\n    subgraph \"存储后端对比\"\n        MEMORY[In-Memory<br/>零依赖]\n        PG[Postgres + pgvector<br/>持久化/可扩展]\n        OBS[Obsidian Vault<br/>本地知识库]\n        FALK[FalkorDB<br/>图原生]\n        CUSTOM[Custom<br/>自定义实现]\n    end\n```\n\n| 后端 | 安装选项 | 使用场景 |\n|------|----------|----------|\n| `memory` | 内置 | 零依赖，快速试用 |\n| `postgres` | `genesys-memory[postgres]` | 持久化、可扩展 |\n| `obsidian` | `genesys-memory[obsidian]` | 本地优先知识库 |\n| `falkordb` | `genesys-memory[falkordb]` | 图原生遍历 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## MCP 协议集成\n\n### MCP Server 实现\n\nGenesys 通过 FastMCP 实现 MCP 协议服务：\n\n```python\n@app.list_tools()\nasync def list_tools() -> list[Tool]:\n    return _TOOL_SCHEMAS\n\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:\n    if name not in _TOOL_DISPATCH:\n        return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n    return await _TOOL_DISPATCH[name](**arguments)\n```\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n### MCP 工具列表\n\n| 工具名称 | 功能描述 |\n|----------|----------|\n| `memory_store` | 存储新记忆，可选择关联相关记忆 |\n| `memory_recall` | 通过自然语言查询召回记忆（向量+图混合搜索） |\n| `memory_search` | 按状态、日期、关键词过滤搜索 |\n| `memory_traverse` | 从给定节点遍历因果图 |\n| `memory_explain` | 解释记忆存在的原因及其因果链 |\n| `memory_stats` | 获取记忆系统统计信息 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定记忆 |\n| `delete_memory` | 永久删除记忆及其所有边 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆类别偏好 |\n| `promote_to_org` | 将私人记忆提升为组织可见 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n## 请求流程\n\n### 记忆存储流程\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant MCP_Server\n    participant Scoring_Engine\n    participant LLM_Provider\n    participant Graph_Storage\n    \n    Client->>MCP_Server: memory_store(content)\n    MCP_Server->>Scoring_Engine: create_node()\n    Scoring_Engine->>LLM_Provider: identify_causal_relationships()\n    LLM_Provider-->>Scoring_Engine: 返回因果边列表\n    Scoring_Engine->>Graph_Storage: create_node + create_edges\n    Graph_Storage-->>Scoring_Engine: node_id\n    Scoring_Engine-->>MCP_Server: 返回结果\n    MCP_Server-->>Client: 记忆存储成功\n```\n\n### 记忆召回流程\n\n```mermaid\nsequenceDiagram\n    participant Client\n    participant MCP_Server\n    participant Engine\n    participant Embedding\n    participant Graph\n    \n    Client->>MCP_Server: memory_recall(query)\n    MCP_Server->>Embedding: embed(query)\n    Embedding-->>Engine: query_vector\n    Engine->>Graph: vector_search(query_vector)\n    Engine->>Graph: graph_spanning_activation()\n    Graph-->>Engine: 混合排序结果\n    Engine-->>MCP_Server: 记忆列表\n    MCP_Server-->>Client: 返回召回结果\n```\n\n## 环境配置\n\n### 配置变量表\n\n| 变量名 | 必需 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `OPENAI_API_KEY` | 否* | - | 嵌入生成（除非使用 local） |\n| `ANTHROPIC_API_KEY` | 否 | - | LLM 记忆处理 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |\n| `DATABASE_URL` | postgres | - | Postgres 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | obsidian | - | Obsidian 库路径 |\n| `FALKORDB_HOST` | falkordb | `localhost` | FalkorDB 主机 |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |\n\n*除非 `GENESYS_EMBEDDER=local`\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 扩展机制\n\n### 自定义存储后端\n\n通过实现 `GraphStorageProvider` 接口，可以接入自定义存储：\n\n```python\nclass GraphStorageProvider(Protocol):\n    async def create_node(self, node: MemoryNode) -> str: ...\n    async def create_edge(self, edge: MemoryEdge) -> str: ...\n    async def get_node(self, node_id: str) -> MemoryNode | None: ...\n    async def get_neighbors(self, node_id: str) -> list[MemoryNode]: ...\n    async def search(self, embedding: list[float], k: int) -> list[MemoryNode]: ...\n```\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n## 总结\n\nGenesys 采用**模块化分层架构**，将表现层、核心引擎层和存储层解耦。核心的评分引擎通过乘法公式模拟人类记忆的遗忘机制，MCP 协议实现了与 AI Agent 的无缝集成，而灵活的存储抽象支持从内存到分布式图数据库的多种部署方式。\n\n---\n\n<a id='page-data-models'></a>\n\n## 数据模型\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [记忆生命周期](#page-memory-lifecycle)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n- [src/genesys_memory/models/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/__init__.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n</details>\n\n# 数据模型\n\n## 概述\n\nGenesys 的数据模型是记忆系统的基础层，采用图结构来组织和关联 AI 代理的记忆。与传统的纯向量存储不同，Genesys 通过**节点（MemoryNode）** 和**边（MemoryEdge）** 构建因果图，使记忆能够表达语义关联、因果关系和激活历史。\n\n数据模型的核心设计目标：\n\n- **语义记忆**：通过向量嵌入实现相似性检索\n- **因果关联**：通过边表达记忆之间的因果、支持和衍生关系\n- **生命周期管理**：支持记忆的状态转换和自动遗忘机制\n- **权限控制**：支持个人记忆和组织记忆的可见性管理\n\n```mermaid\ngraph TB\n    subgraph 数据模型层\n        Node[MemoryNode<br/>记忆节点]\n        Edge[MemoryEdge<br/>记忆边]\n        Enums[枚举类型<br/>MemoryStatus<br/>EdgeType<br/>ReactivationPattern]\n    end\n    \n    subgraph 存储后端\n        PG[(Postgres<br/>+ pgvector)]\n        SQLite[(SQLite)]\n        FalkorDB[(FalkorDB)]\n        Obsidian[(Obsidian Vault)]\n    end\n    \n    Node --> Edge\n    Enums --> Node\n    Enums --> Edge\n    \n    Node --> PG\n    Node --> SQLite\n    Node --> FalkorDB\n    Node --> Obsidian\n```\n\n资料来源：[src/genesys_memory/models/__init__.py:1-9]()\n\n## 核心模型\n\n### MemoryNode（记忆节点）\n\nMemoryNode 是 Genesys 中存储单个记忆的基本单元。每个节点包含记忆的内容、元数据、时间戳、嵌入向量和状态信息。\n\n```mermaid\nclassDiagram\n    class MemoryNode {\n        +UUID id\n        +str content_summary\n        +str content_full\n        +list~float~ embedding\n        +MemoryStatus status\n        +Visibility visibility\n        +str category\n        +datetime created_at\n        +datetime last_accessed_at\n        +datetime last_reactivated_at\n        +float relevance_score\n        +float connectivity_score\n        +float reactivation_count\n        +bool is_pinned\n        +bool is_core\n        +str org_id\n        +str original_user_id\n        +list~str~ entity_refs\n        +list~ReactivationPattern~ reactivation_patterns\n    }\n```\n\n#### 节点核心属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 节点唯一标识符 |\n| `content_summary` | str | 记忆摘要（用于语义检索显示） |\n| `content_full` | str | 完整记忆内容 |\n| `embedding` | list[float] | 向量嵌入（用于相似性检索） |\n| `status` | MemoryStatus | 当前记忆状态 |\n| `visibility` | Visibility | 可见性：个人/组织 |\n| `category` | str | 记忆分类（可选） |\n| `created_at` | datetime | 创建时间戳 |\n| `last_accessed_at` | datetime | 最后访问时间 |\n| `last_reactivated_at` | datetime | 最后重新激活时间 |\n| `relevance_score` | float | 关联度评分（0-1） |\n| `connectivity_score` | float | 连接度评分（基于边数量） |\n| `reactivation_count` | int | 重新激活次数 |\n| `is_pinned` | bool | 是否被固定 |\n| `is_core` | bool | 是否为核心记忆 |\n| `org_id` | str | 组织ID（组织记忆时需要） |\n| `original_user_id` | str | 原始创建者ID |\n| `entity_refs` | list[str] | 实体引用列表 |\n| `reactivation_patterns` | list[ReactivationPattern] | 重新激活模式历史 |\n\n资料来源：[src/genesys_memory/models/node.py]()\n\n### MemoryEdge（记忆边）\n\nMemoryEdge 表示两个记忆节点之间的关系，边具有类型、权重和创建原因。\n\n#### 边属性\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 边唯一标识符 |\n| `source_id` | UUID | 源节点ID |\n| `target_id` | UUID | 目标节点ID |\n| `type` | EdgeType | 边类型（因果/支持/衍生等） |\n| `weight` | float | 边权重（0-1） |\n| `reason` | str | 创建原因描述 |\n| `created_by` | str | 创建方式（user_explicit/auto_link） |\n| `created_at` | datetime | 创建时间戳 |\n\n资料来源：[src/genesys_memory/models/edge.py]()\n\n## 枚举类型\n\n### MemoryStatus（记忆状态）\n\n记忆在生命周期中可能处于以下状态：\n\n```mermaid\nstateDiagram-v2\n    [*] --> STORE: 创建新记忆\n    STORE --> ACTIVE: 首次激活/关联\n    ACTIVE --> DORMANT: 长时间未访问\n    DORMANT --> ACTIVE: 被重新激活\n    DORMANT --> FADING: 持续衰减\n    FADING --> FADING: 评分继续下降\n    FADING --> PRUNED: 评分归零/孤立/非固定\n    ACTIVE --> FADING: 评分急剧下降\n    PRUNED --> [*]\n```\n\n| 状态值 | 说明 | 触发条件 |\n|--------|------|----------|\n| `STORE` | 存储态 | 新记忆创建后 |\n| `ACTIVE` | 活跃态 | 被访问或有因果关联 |\n| `DORMANT` | 休眠态 | 长时间无访问但有连接 |\n| `FADING` | 衰减态 | 评分持续下降 |\n| `PRUNED` | 修剪态 | 评分归零且可被删除 |\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n### EdgeType（边类型）\n\n| 边类型 | 说明 | 使用场景 |\n|--------|------|----------|\n| `CAUSED_BY` | 因果关系 | 记忆A导致记忆B |\n| `SUPPORTS` | 支持关系 | 记忆A支持/强化记忆B |\n| `DERIVED_FROM` | 衍生关系 | 语义记忆从情景记忆提取 |\n| `RELATED_TO` | 相关关系 | 语义相似的记忆自动关联 |\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n### Visibility（可见性）\n\n| 值 | 说明 |\n|----|------|\n| `PRIVATE` | 仅创建者可见 |\n| `ORG` | 组织成员可见 |\n\n### ReactivationPattern（重新激活模式）\n\n记录记忆被重新激活的方式，用于分析访问模式。\n\n资料来源：[src/genesys_memory/models/enums.py]()\n\n## 评分机制\n\nGenesys 采用三因素乘法评分模型决定记忆的生存能力：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因素 | 说明 | 影响因素 |\n|------|------|----------|\n| `relevance` | 关联度 | 时间衰减、内容新鲜度 |\n| `connectivity` | 连接度 | 边数量、边权重总和 |\n| `reactivation` | 重新激活度 | 访问频率、最近访问时间 |\n\n> 由于采用乘法模型，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁访问但因果孤立记忆也会消失。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 核心记忆机制\n\n核心记忆是系统中结构上重要、被自动固定的记忆，具有以下特性：\n\n- **自动固定**：不会因评分下降而被遗忘\n- **权限保护**：需要明确取消固定才能降级\n- **自动晋升**：满足晋升规则的记忆可自动成为核心记忆\n\n```mermaid\ngraph LR\n    A[普通记忆] --> B{晋升评估}\n    B -->|满足规则| C[核心记忆]\n    B -->|不满足| D[继续评估]\n    C --> E[is_core=True]\n    C --> F[is_pinned=True]\n```\n\n核心记忆的晋升由 `promote_to_org` 函数和权限检查机制控制，支持组织级别的记忆推广。\n\n资料来源：[src/genesys_memory/core_memory/promoter.py]()\n\n## 所有权与权限\n\nGenesys 支持多用户和组织级别的记忆管理：\n\n### 所有权检查逻辑\n\n```python\ndef _caller_owns_node(node: MemoryNode) -> bool:\n    uid = _caller_uid()\n    role = current_user_role.get(None)\n    # 管理员可访问同组织的节点\n    if role == \"admin\" and node.org_id in current_org_ids.get([]):\n        return True\n    # 原始创建者拥有节点\n    if node.original_user_id:\n        return node.original_user_id == uid\n    return True\n```\n\n### 组织边界规则\n\n组织节点只能连接到同一组织的其他节点和边，确保数据隔离：\n\n```python\n# 组织边界规则：org节点只链接到同org节点\nif vis == Visibility.ORG:\n    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:\n        continue\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py:23-40]()\n\n## 存储后端适配\n\n数据模型通过抽象存储接口支持多种后端：\n\n```mermaid\ngraph TB\n    subgraph 存储提供者接口\n        GraphStorageProvider[GraphStorageProvider]\n        EmbeddingProvider[EmbeddingProvider]\n        CacheProvider[CacheProvider]\n        EventBusProvider[EventBusProvider]\n    end\n    \n    subgraph 具体实现\n        PostgresStore[Postgres + pgvector]\n        SQLiteStore[SQLite]\n        FalkorDBStore[FalkorDB]\n        ObsidianStore[Obsidian Vault]\n    end\n    \n    GraphStorageProvider --> PostgresStore\n    GraphStorageProvider --> SQLiteStore\n    GraphStorageProvider --> FalkorDBStore\n    GraphStorageProvider --> ObsidianStore\n```\n\n| 后端 | 存储内容 | 适用场景 |\n|------|----------|----------|\n| 内存 | 内存字典 | 开发测试 |\n| Postgres + pgvector | 向量+关系 | 生产环境 |\n| SQLite | 轻量级索引 | 个人使用 |\n| FalkorDB | 原生图结构 | 图遍历密集型 |\n| Obsidian Vault | Markdown文件 | 本地知识库 |\n\n资料来源：[src/genesys_memory/storage/base.py]()\n\n## 导出模块\n\n模型层通过 `__init__.py` 统一导出核心类：\n\n```python\nfrom genesys_memory.models import (\n    MemoryStatus,\n    EdgeType,\n    ReactivationPattern,\n    MemoryNode,\n    MemoryEdge,\n)\n```\n\n资料来源：[src/genesys_memory/models/__init__.py:1-9]()\n\n## 总结\n\nGenesys 的数据模型以**节点-边**的图结构为核心，通过：\n\n1. **MemoryNode** 存储记忆内容、状态、评分和时间信息\n2. **MemoryEdge** 表达记忆间的语义和因果关系\n3. **MemoryStatus** 管理记忆的生命周期状态转换\n4. **评分机制** 决定记忆的生存或遗忘\n5. **权限系统** 支持个人和组织级别的记忆管理\n\n这种设计使 Genesys 能够在提供向量检索能力的同时，维持对记忆之间关系的深层理解，实现更智能的记忆管理。\n\n---\n\n<a id='page-scoring-engine'></a>\n\n## 评分引擎\n\n### 相关页面\n\n相关主题：[项目介绍](#page-introduction), [记忆生命周期](#page-memory-lifecycle)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/engine/config.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/config.py)（配置文件引用）\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n</details>\n\n# 评分引擎\n\n## 概述\n\n评分引擎（Scoring Engine）是 Genesys 记忆系统的核心组件，负责对每条记忆进行多维度评分，以决定其生命周期状态、保留优先级和遗忘时机。评分引擎采用**乘积公式**计算综合得分，确保持续活跃、高度连接、频繁复活的记忆得以保留，而孤立或长期未访问的记忆则逐渐衰减直至被剪枝。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 评分公式\n\n### 三力乘积模型\n\n每条记忆的最终得分由三个因子相乘得出：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因子 | 含义 | 影响因素 |\n|------|------|----------|\n| **relevance**（相关性） | 记忆随时间衰减 | 记忆创建时间、访问频率 |\n| **connectivity**（连接性） | 记忆在因果图中的重要性 | 因果边数量、边权重、因果权重 |\n| **reactivation**（再激活） | 记忆被回忆的频率 | 复活次数、复活时间模式 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 乘积公式的设计逻辑\n\n由于采用乘法模型，记忆必须同时在**三个维度**上都有得分才能保持高分：\n\n- **高连接但从未被访问**：仍然会衰减\n- **频繁回忆但孤立无依**：仍然会消失\n- **最近创建但无关联**：也会逐渐淡出\n\n这种设计确保只有真正重要的记忆才能长期留存。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 记忆生命周期\n\n评分引擎驱动记忆在以下状态之间转换：\n\n```mermaid\ngraph TD\n    A[STORE 存储] --> B[ACTIVE 活跃]\n    B --> C[DORMANT 休眠]\n    C --> D[FADING 消逝]\n    D --> E[PRUNED 剪枝]\n    B -->|reactivation 复活| B\n    C -->|reactivation 复活| B\n    E -->|仅当 score=0, orphan, not pinned| 结束\n```\n\n| 状态 | 说明 | 触发条件 |\n|------|------|----------|\n| **STORE** | 刚创建的初始状态 | 记忆被创建时 |\n| **ACTIVE** | 活跃记忆，可被检索 | 综合得分较高 |\n| **DORMANT** | 休眠记忆，降低检索优先级 | 综合得分下降但未归零 |\n| **FADING** | 消逝中，即将删除 | 得分持续低迷 |\n| **PRUNED** | 已删除 | 得分归零、孤立、无固定 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 评分相关数据模型\n\n### MemoryNode 核心字段\n\n记忆节点模型 `MemoryNode` 包含以下与评分直接相关的字段：\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID\n    status: MemoryStatus  # 生命周期状态\n    \n    # 评分计算因子\n    decay_score: float = 1.0      # 综合衰减得分\n    causal_weight: int = 0        # 因果权重（连接性）\n    reactivation_count: int = 0   # 复活次数\n    \n    # 时间相关\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n    \n    # 稳定性（成功检索后增加，间隔重复算法）\n    stability: float = 1.0\n    \n    # 固定与核心记忆\n    pinned: bool = False          # 是否固定（永不遗忘）\n    promotion_reason: str | None  # 晋升原因\n    \n    # 复活历史\n    reactivation_timestamps: list[datetime]\n```\n\n| 字段 | 类型 | 用途 |\n|------|------|------|\n| `decay_score` | float | 最终综合得分（0.0 - 1.0） |\n| `causal_weight` | int | 因果图中的连接权重 |\n| `reactivation_count` | int | 被回忆的总次数 |\n| `stability` | float | 稳定性（检索成功后增加） |\n| `pinned` | bool | 是否被固定（跳过遗忘逻辑） |\n\n资料来源：[src/genesys_memory/models/node.py:1-50](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 复活模式枚举\n\n```python\nclass ReactivationPattern(Enum):\n    SINGLE       # 单次激活\n    BURST        # 爆发式激活\n    SPACED       # 间隔重复激活\n    DECAYING     # 衰减模式\n```\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n## 引擎配置\n\n评分引擎的行为通过 `engine/config.py` 进行配置，所有阈值均为环境变量可配置，禁止在引擎文件中硬编码魔法数字。\n\n### 配置项管理\n\n| 配置类别 | 说明 |\n|----------|------|\n| 衰减率 | 控制 relevance 随时间的衰减速度 |\n| 连接阈值 | 影响 connectivity 的计算基准 |\n| 复活权重 | 不同复活模式的加分权重 |\n| 稳定性参数 | 间隔重复算法的参数 |\n\n> **注意**：具体的配置参数值和阈值定义在 `engine/config.py` 中，可通过环境变量覆盖默认行为。\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## LLM 驱动的因果关系发现\n\n评分引擎集成了 LLM 提供器来自动识别记忆之间的因果关系，这直接影响 **connectivity** 因子的计算。\n\n### 因果关系发现流程\n\n```mermaid\nsequenceDiagram\n    participant U as 用户记忆\n    participant LLM as LLM Provider\n    participant G as 图存储\n    \n    U->>LLM: 发现因果关系 (new_memory, existing_memories)\n    LLM->>LLM: 生成提示词\n    LLM->>LLM: 请求 LLM 分析\n    LLM-->>G: 返回关系列表 (target_id, edge_type, confidence)\n    \n    loop 对于每个关系\n        G->>G: 创建 MemoryEdge\n        G->>G: 更新 causal_weight\n    end\n```\n\n### 边类型定义\n\n| 边类型 | 含义 | 置信度要求 |\n|--------|------|------------|\n| `caused_by` | 因果导致 | > 0.6 |\n| `supports` | 支持关系 | > 0.6 |\n| `derived_from` | 派生关系 | > 0.6 |\n\n```python\nasync def discover_causal_relationships(\n    self,\n    new_memory: str,\n    existing_memories: list[tuple[str, str]],\n) -> list[tuple[str, EdgeType, float, str | None]]:\n    \"\"\"\n    分析新记忆与已有记忆之间的因果关系。\n    仅返回置信度 > 0.6 的关系。\n    \"\"\"\n    # ... 实现逻辑\n```\n\n资料来源：[src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n\n## 核心记忆晋升机制\n\n评分引擎还负责评估记忆是否应晋升为**核心记忆**（Core Memory）。核心记忆具有以下特性：\n\n- **自动固定**：晋升后自动设置为 `pinned=True`\n- **永不剪枝**：即使得分归零也不会被删除\n- **高优先级检索**：在检索结果中优先返回\n\n```python\nfrom genesys_memory.core_memory.promoter import evaluate_core_promotion\n\n# 评估晋升资格\npromotion_result = await evaluate_core_promotion(memory_node)\n```\n\n### MCP 工具接口\n\n评分引擎可通过 MCP 协议调用以下相关工具：\n\n| 工具 | 功能 |\n|------|------|\n| `memory_explain` | 解释记忆的得分构成 |\n| `pin_memory` | 手动固定记忆 |\n| `unpin_memory` | 取消固定并重新评估资格 |\n| `promote_to_core` | 晋升记忆为核心记忆 |\n| `list_core_memories` | 列出所有核心记忆 |\n| `set_core_preferences` | 配置核心记忆偏好 |\n\n资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n\n## 遗忘与剪枝策略\n\n### 遗忘触发条件\n\n记忆被剪枝（Pruned）需要同时满足以下条件：\n\n| 条件 | 说明 |\n|------|------|\n| `score == 0` | 综合得分为零 |\n| `orphan` | 无任何因果边连接 |\n| `not pinned` | 未被固定 |\n\n```python\n# 伪代码示例\nif decay_score == 0 and is_orphan and not pinned:\n    await prune_memory(memory_id)\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 间隔重复与稳定性\n\n评分引擎采用**间隔重复**算法调整记忆的 `stability` 参数：\n\n- 成功检索 → stability 增加\n- 检索失败 → stability 减少\n- stability 影响 decay_score 的计算\n\n这模拟了人类记忆的遗忘曲线，使重要记忆得到强化。\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n## 检索中的评分应用\n\n### 混合检索流程\n\n评分引擎在 `memory_recall` 操作中发挥作用：\n\n```mermaid\ngraph LR\n    A[查询] --> B[向量搜索]\n    A --> C[关键词搜索]\n    B --> D[图传播激活]\n    C --> D\n    D --> E[综合评分排序]\n    E --> F[返回 Top-K 结果]\n```\n\n1. **向量搜索**：基于语义相似度检索\n2. **关键词搜索**：精确匹配关键词\n3. **图传播激活**：从初始节点沿因果边传播激活值\n4. **综合评分排序**：结合原始得分和检索相关性\n\n### 检索参数\n\n| 参数 | 默认值 | 说明 |\n|------|--------|------|\n| `k` | 10 | 返回结果数量 |\n| `max_results` | None | 最大结果限制 |\n\n```python\nTool(name=\"memory_recall\", description=\"Recall memories using hybrid search...\", inputSchema={\n    \"type\": \"object\",\n    \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n        \"max_results\": {\"type\": \"integer\"},\n    },\n})\n```\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n## 性能基准\n\n评分引擎在 LoCoMo 长对话记忆基准测试中的表现：\n\n| 类别 | J-Score |\n|------|---------|\n| 单跳查询 | 94.3% |\n| 时间查询 | 87.5% |\n| 多跳查询 | 69.8% |\n| 开放域查询 | 91.7% |\n| **总体** | **89.9%** |\n\n测试配置：Answer model: `gpt-4o-mini` | Judge model: `gpt-4o-mini` | Retrieval k=20\n\n对比基准：Mem0 (67.1%), Zep (75.1%)\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 开发指南\n\n### 添加新评分逻辑\n\n在添加新的评分逻辑时，请遵循以下规范：\n\n1. **配置外置**：所有阈值必须放在 `engine/config.py` 中\n2. **环境变量支持**：通过环境变量覆盖默认配置\n3. **测试覆盖**：在 `tests/` 目录添加对应的测试用例\n4. **严格模式检查**：`mypy src/genesys_memory --ignore-missing-imports` 必须通过\n\n```bash\n# 运行测试\npytest tests/ -v\n\n# 类型检查\nmypy src/genesys_memory --ignore-missing-imports\n\n# 代码检查\nruff check src/\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n### 关键模块耦合\n\n评分引擎与以下模块紧密耦合，修改时需运行完整测试套件：\n\n| 模块 | 职责 |\n|------|------|\n| **scoring** | 评分计算核心逻辑 |\n| **transitions** | 生命周期状态转换 |\n| **forgetting** | 遗忘与剪枝决策 |\n| **promotion** | 核心记忆晋升评估 |\n\n> 修改任一模块后，必须运行 `pytest tests/ -v` 确保无回归。\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 总结\n\n评分引擎是 Genesys 记忆系统的决策中心，通过**乘积公式**将相关性、连接性和再激活三个维度统一量化，驱动记忆的整个生命周期管理。其设计核心思想是：只有同时满足\"持续相关\"、\"高度连接\"、\"频繁使用\"三个条件的记忆才值得长期保留。\n\n这种设计使得 AI 能够在有限的记忆空间中保留最有价值的信息，模拟人类记忆的优先级管理机制，同时通过核心记忆机制确保关键信息永不丢失。\n\n---\n\n<a id='page-memory-lifecycle'></a>\n\n## 记忆生命周期\n\n### 相关页面\n\n相关主题：[评分引擎](#page-scoring-engine), [数据模型](#page-data-models)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n- [src/genesys_memory/engine/reactivation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/reactivation.py)\n- [src/genesys_memory/engine/forgetting.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)\n- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n</details>\n\n# 记忆生命周期\n\n## 概述\n\n记忆生命周期是 Genesys 记忆引擎的核心管理机制，负责记忆从创建到消亡的完整过程。该系统通过三层评分公式（相关性 × 连接性 × 再激活）对每条记忆进行动态评分，并驱动记忆在不同的生命周期状态之间转换。\n\n**核心设计目标：**\n- 智能遗忘不重要或过时的记忆\n- 通过因果图保留重要记忆的结构完整性\n- 支持核心记忆的自动晋升与保护\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 生命周期状态\n\n记忆在系统中经历以下五种状态：\n\n| 状态 | 说明 | 可被召回 |\n|------|------|----------|\n| `TAGGED` | 新记忆，等待因果链接确认 | ❌ |\n| `ACTIVE` | 活跃状态，参与正常评分 | ✅ |\n| `DORMANT` | 休眠状态，评分较低但保留 | ✅ |\n| `FADING` | 消逝中，等待被清理 | ❌ |\n| `PRUNED` | 已删除，不再存在 | ❌ |\n\n资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n\n### 状态转换图\n\n```mermaid\ngraph TD\n    NEW[新记忆创建] --> TAGGED[TAGGED 标签态]\n    TAGGED -->|形成因果链接| ACTIVE[ACTIVE 活跃态]\n    TAGGED -->|24h无链接| PRUNED[PRUNED 已删除]\n    \n    ACTIVE -->|评分下降| DORMANT[DORMANT 休眠态]\n    ACTIVE -->|高频召回| REACTIVATE[再激活]\n    REACTIVATE --> ACTIVE\n    \n    DORMANT -->|再次召回| ACTIVE\n    DORMANT -->|长期无召回| FADING[FADING 消逝态]\n    \n    FADING -->|评分归零| PRUNED\n    FADING -->|被固定| ACTIVE\n    \n    ACTIVE -->|核心晋升| CORE[核心记忆]\n    CORE -->|永不删除| PERSIST[永久保留]\n    \n    style CORE fill:#90EE90\n    style PRUNED fill:#FFB6C1\n```\n\n## 评分引擎\n\n### 三力评分公式\n\n记忆评分由三个因子相乘得出：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因子 | 作用 | 特性 |\n|------|------|------|\n| **Relevance（相关性）** | 随时间衰减 | 时间越久分数越低，除非被强化 |\n| **Connectivity（连接性）** | 奖励因果链接多的记忆 | 作为枢纽的记忆更易存活 |\n| **Reactivation（再激活）** | 奖励被频繁召回的记忆 | 召回频率影响分数 |\n\n**乘法特性：** 三个因子必须同时较高，记忆才能存活。仅在一两个方面表现良好不足以保证记忆存活。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 评分组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| `scoring.py` | `engine/scoring.py` | 计算 decay_score |\n| `transitions.py` | `engine/transitions.py` | 评估状态转换 |\n| `reactivation.py` | `engine/reactivation.py` | 处理召回事件 |\n| `forgetting.py` | `engine/forgetting.py` | 执行记忆删除 |\n\n## 状态转换引擎\n\n### Tagged → Active 转换\n\n当新记忆形成因果链接时，从 TAGGED 状态晋升为 ACTIVE：\n\n```python\nasync def evaluate_transitions(graph, embeddings, llm, context_embedding, context_entities):\n    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)\n    for node in tagged_nodes:\n        if not await graph.is_orphan(str(node.id)):\n            await graph.update_node(str(node.id), {\"status\": MemoryStatus.ACTIVE})\n```\n\n**关键逻辑：**\n- 检查节点是否为孤立节点（orphan）\n- 若存在因果边连接，则触发状态变更\n- 变更原因记录为：`\"consolidation signal: edge formed\"`\n\n资料来源：[src/genesys_memory/engine/transitions.py:14-24](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n\n### Tagged 自动过期\n\n24小时内无因果链接的 TAGGED 记忆自动过期删除：\n\n```python\nage_hours = (datetime.now(timezone.utc) - node.created_at).total_seconds() / 3600\nif age_hours > 24:\n    # 标记为过期\n```\n\n资料来源：[src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)\n\n### 转换评估流程\n\n```mermaid\ngraph TD\n    START[开始评估] --> GET_STATS[获取图统计]\n    GET_STATS --> GET_TAGGED[获取所有 TAGGED 节点]\n    GET_TAGGED --> IS_ORPHAN{是孤立节点?}\n    \n    IS_ORPHAN -->|是| CHECK_AGE{超过24h?}\n    IS_ORPHAN -->|否| PROMOTE[晋升为 ACTIVE]\n    \n    CHECK_AGE -->|是| EXPIRE[过期处理]\n    CHECK_AGE -->|否| WAIT[等待下次评估]\n    \n    PROMOTE --> RECORD[记录转换原因]\n    EXPIRE --> RECORD\n    RECORD --> DONE[评估完成]\n```\n\n## 再激活机制\n\n### 再激活模式\n\n记忆节点记录其再激活历史，支持多种模式：\n\n| 模式 | 说明 |\n|------|------|\n| `SINGLE` | 单次召回 |\n| `SPACED` | 间隔重复模式 |\n| `BURST` | 突发高频召回 |\n\n资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)\n\n### 再激活属性\n\n```python\nclass MemoryNode:\n    reactivation_count: int = 0          # 召回次数\n    reactivation_pattern: ReactivationPattern  # 召回模式\n    last_reactivated_at: datetime         # 最后召回时间\n    reactivation_timestamps: list[datetime]  # 历史时间戳\n```\n\n### 再激活评分提升\n\n每次召回都会提升记忆的 decay_score：\n\n```mermaid\ngraph LR\n    RECALL[召回请求] --> CHECK{检查记忆状态}\n    CHECK -->|ACTIVE| BOOST[boost decay_score]\n    CHECK -->|DORMANT| RESTORE[恢复为 ACTIVE]\n    CHECK -->|FADING| RESCUE{是否固定?}\n    \n    RESTORE --> UPDATE_TS[更新再激活时间戳]\n    BOOST --> UPDATE_TS\n    \n    RESCUE -->|是| KEEP[保留记忆]\n    RESCUE -->|否| FADING2[继续消逝流程]\n```\n\n## 遗忘机制\n\n### 遗忘条件\n\n记忆被遗忘（删除）需要满足以下全部条件：\n\n| 条件 | 说明 |\n|------|------|\n| `score = 0` | 评分归零 |\n| `is_orphan` | 是孤立节点（无因果链接） |\n| `not pinned` | 未被固定 |\n\n```python\nasync def forget_memories(graph):\n    for memory in low_score_memories:\n        if memory.pinned:\n            continue\n        if not await graph.is_orphan(memory.id):\n            continue\n        if memory.decay_score > 0:\n            continue\n        await graph.delete_node(memory.id)\n```\n\n资料来源：[src/genesys_memory/engine/forgetting.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)\n\n### 遗忘流程图\n\n```mermaid\ngraph TD\n    START[遗忘评估] --> SCAN[扫描低评分记忆]\n    SCAN --> LOOP{遍历记忆}\n    \n    LOOP -->|固定记忆| SKIP[跳过]\n    LOOP -->|孤立节点| ORPHAN{有因果边?}\n    \n    ORPHAN -->|有边| KEEP[保留]\n    ORPHAN -->|无边| CHECK_SCORE{评分=0?}\n    \n    CHECK_SCORE -->|是| DELETE[删除记忆]\n    CHECK_SCORE -->|否| KEEP\n    \n    SKIP --> NEXT[下一条]\n    KEEP --> NEXT\n    DELETE --> NEXT\n    \n    NEXT --> LOOP\n```\n\n## 核心记忆系统\n\n### 核心记忆特性\n\n核心记忆是结构上重要的记忆，具有以下特性：\n\n- **自动固定**：晋升为核心时自动设置 `pinned = true`\n- **永不删除**：即使评分归零也不会被遗忘\n- **分类管理**：支持按类别配置自动晋升规则\n\n### 晋升评估\n\n```python\nasync def evaluate_core_promotion(memory, category_rules):\n    if memory.category in category_rules.auto:\n        await promote_to_core(memory, reason=\"category_auto\")\n    elif memory.causal_weight > threshold:\n        await promote_to_core(memory, reason=\"high_connectivity\")\n```\n\n资料来源：[src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)\n\n### 核心记忆配置\n\n| 配置项 | 说明 |\n|--------|------|\n| `auto` | 满足条件自动晋升的类别列表 |\n| `approval` | 需要审批才能晋升的类别 |\n| `excluded` | 禁止晋升为核心的类别 |\n\n### 晋升流程\n\n```mermaid\ngraph TD\n    EVAL[晋升评估] --> CHECK_CATEGORY{检查类别规则}\n    \n    CHECK_CATEGORY -->|auto 列表| AUTO[自动晋升]\n    CHECK_CATEGORY -->|approval 列表| NEED_APPROVAL[需要审批]\n    CHECK_CATEGORY -->|excluded 列表| BLOCK[阻止晋升]\n    CHECK_CATEGORY -->|无匹配| CHECK_CONNECTIVITY{高连接性?}\n    \n    CHECK_CONNECTIVITY -->|是| AUTO\n    CHECK_CONNECTIVITY -->|否| KEEP[保持当前状态]\n    \n    AUTO --> SET_PIN[设置 pinned=true]\n    NEED_APPROVAL --> AWAIT[等待用户确认]\n    BLOCK --> KEEP\n    \n    AWAIT -->|批准| SET_PIN\n    AWAIT -->|拒绝| KEEP\n    \n    SET_PIN --> LOG[记录晋升原因]\n    LOG --> DONE[完成]\n```\n\n## 记忆节点模型\n\n### 数据结构\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID                    # 唯一标识\n    status: MemoryStatus            # 当前状态\n    content_summary: str            # 内容摘要 (≤200字符)\n    content_full: str | None        # 完整内容\n    embedding: list[float] | None  # 向量嵌入\n    \n    # 时间戳\n    created_at: datetime            # 创建时间\n    last_accessed_at: datetime      # 最后访问\n    last_reactivated_at: datetime   # 最后召回\n    \n    # 评分因子\n    decay_score: float = 1.0        # 衰减评分\n    causal_weight: int = 0          # 因果权重\n    reactivation_count: int = 0     # 召回次数\n    irrelevance_counter: int = 0    # 无效计数\n    \n    # 分类与稳定性\n    category: str | None            # 类别\n    stability: float = 1.0          # 稳定性\n    pinned: bool = False            # 是否固定\n```\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 稳定性机制\n\n稳定性（Stability）随成功召回而增加，模拟间隔重复学习：\n\n- 每次成功检索：`stability += 0.1`\n- 长期未召回：`stability -= 0.05`\n- 高稳定性记忆更难被删除\n\n## 生命周期管理 API\n\n### MCP 工具\n\n| 工具名 | 功能 |\n|--------|------|\n| `memory_recall` | 召回记忆（触发再激活） |\n| `memory_search` | 搜索记忆 |\n| `memory_traverse` | 遍历因果图 |\n| `pin_memory` | 固定记忆 |\n| `unpin_memory` | 取消固定 |\n| `list_core_memories` | 列出核心记忆 |\n| `delete_memory` | 删除记忆 |\n\n### 召回工作流\n\n```mermaid\nsequenceDiagram\n    Client->>Genesys: memory_recall(query)\n    Genesys->>Graph: 查找相关节点\n    Graph-->>Genesys: 返回候选记忆\n    Genesys->>Scoring: 计算评分\n    Scoring-->>Genesys: 评分结果\n    Genesys->>Transitions: 评估状态转换\n    Transitions-->>Genesys: 更新状态\n    Genesys->>User: 返回记忆列表\n```\n\n## 配置选项\n\n### 环境变量\n\n| 变量 | 说明 | 默认值 |\n|------|------|--------|\n| `GENESYS_BACKEND` | 存储后端 | `memory` |\n| `GENESYS_EMBEDDER` | 嵌入提供者 | `openai` |\n| `GENESYS_PERSIST_PATH` | 状态持久化路径 | 无 |\n\n### 引擎阈值\n\n引擎阈值定义在 `engine/config.py` 中，可通过环境变量配置：\n\n- 遗忘阈值\n- 晋升阈值\n- 休眠阈值\n- 消逝阈值\n\n## 总结\n\n记忆生命周期是 Genesys 实现智能遗忘的核心机制：\n\n1. **三层评分** 保证记忆必须同时满足相关性、连接性和再激活三个条件才能存活\n2. **五种状态** 提供精细的记忆管理粒度\n3. **因果图** 通过链接关系保护重要记忆不被遗忘\n4. **核心记忆** 为结构关键记忆提供永久保护\n5. **固定机制** 允许用户手动保护特定记忆\n\n该系统确保 AI 记忆既不会无限膨胀，也不会遗忘重要信息，实现了记忆容量与信息价值的动态平衡。\n\n---\n\n<a id='page-mcp-tools'></a>\n\n## MCP 工具集\n\n### 相关页面\n\n相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)\n</details>\n\n# MCP 工具集\n\n## 概述\n\nGenesys 的 MCP 工具集是系统与外部 AI 客户端（如 Claude Desktop、Claude Code）交互的核心接口层。该工具集通过 MCP（Model Context Protocol）协议暴露一组标准化的内存操作工具，使 AI 代理能够存储、检索、遍历和管理记忆节点。\n\nMCP 工具集采用标准化的事件驱动架构，所有工具均通过统一的 `call_tool` 分发器进行路由。工具层与底层存储提供者（GraphStorageProvider、CacheProvider、EmbeddingProvider）解耦，支持多种存储后端。资料来源：[server.py:1-50]()\n\n## 架构设计\n\n### 工具调用流程\n\n```mermaid\ngraph TD\n    A[MCP 客户端请求] --> B[call_tool 分发器]\n    B --> C{工具名称校验}\n    C -->|有效| D[参数验证]\n    C -->|无效| E[返回错误]\n    D --> F[权限检查]\n    F -->|通过| G[执行业务逻辑]\n    F -->|失败| H[抛出 PermissionError]\n    G --> I[调用存储提供者]\n    I --> J[返回 TextContent]\n    J --> K[格式化响应]\n    K --> L[返回给 MCP 客户端]\n```\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| MCP Server | `server.py` | 协议层，处理 stdio/HTTP 传输 |\n| Tool Dispatch | `server.py` | 工具路由和参数分发 |\n| Tool Implementations | `mcp/tools.py` | 业务逻辑实现 |\n| Context Management | `context.py` | 用户身份和权限上下文 |\n| Storage Providers | `storage/` | 数据持久化抽象 |\n\n## 工具清单\n\n### 存储与检索类工具\n\n#### memory_store\n\n存储新的记忆节点，可选择性地关联到现有记忆。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `content` | string | 是 | - | 记忆内容摘要（最大 200 字符） |\n| `source_session` | string | 否 | `\"\"` | 来源会话标识 |\n| `related_to` | array | 否 | `null` | 关联的记忆 ID 列表 |\n| `visibility` | string | 否 | `\"private\"` | 可见性：`private` 或 `org` |\n| `org_id` | string | 否 | `null` | 组织 ID（org 可见性时必需） |\n\n资料来源：[server.py:50]()\n\n#### memory_recall\n\n基于自然语言查询召回记忆，采用混合搜索策略（向量搜索 + 关键词 + 图传播激活）。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 自然语言查询 |\n| `k` | integer | 否 | `10` | 召回的记忆数量 |\n| `max_results` | integer | 否 | `null` | 最大结果数限制 |\n\n资料来源：[server.py:52]()\n\n#### memory_search\n\n基于过滤条件的向量搜索，支持按状态、类别、日期或实体筛选。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `query` | string | 是 | - | 搜索查询 |\n| `filters` | object | 否 | `null` | 过滤条件对象 |\n| `k` | integer | 否 | `10` | 返回结果数 |\n\n资料来源：[server.py:54]()\n\n### 图遍历类工具\n\n#### memory_traverse\n\n从指定节点开始遍历记忆因果图。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 起始节点 ID |\n| `depth` | integer | 否 | `2` | 遍历深度 |\n| `edge_types` | array | 否 | `null` | 边类型过滤（如 `[\"caused_by\"]`） |\n\n资料来源：[server.py:56]()\n\n#### memory_explain\n\n解释记忆节点的分数构成和因果链。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 记忆节点 ID |\n\n资料来源：[server.py:58]()\n\n### 生命周期管理工具\n\n#### pin_memory\n\n将记忆固定为核心记忆，防止被遗忘机制删除。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待固定的节点 ID |\n\n#### unpin_memory\n\n取消固定记忆，重新评估其核心资格。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待取消固定的节点 ID |\n\n资料来源：[server.py:60-62]()\n\n#### delete_memory\n\n永久删除记忆节点及其所有关联边。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待删除的节点 ID |\n\n### 核心记忆管理工具\n\n#### list_core_memories\n\n列出所有核心记忆，可按类别过滤。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `category` | string | 否 | `null` | 类别过滤条件 |\n\n资料来源：[server.py:64]()\n\n#### set_core_preferences\n\n配置核心记忆类别偏好。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `auto` | array | 否 | `null` | 自动升级为核心记忆的类别 |\n| `approval` | array | 否 | `null` | 需要审批才能升级的类别 |\n| `excluded` | array | 否 | `null` | 排除的核心记忆类别 |\n\n### 组织协作工具\n\n#### promote_to_org\n\n将私有记忆提升为组织可见性。\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `node_id` | string | 是 | - | 待提升的节点 ID |\n| `org_id` | string | 是 | - | 目标组织 ID |\n| `action` | string | 否 | `\"keep_private\"` | 关联操作：`keep_private`、`promote_all`、`delete_links` |\n| `dry_run` | boolean | 否 | `false` | 是否为试运行模式 |\n\n资料来源：[server.py:42-46]()\n\n### 统计与监控工具\n\n#### memory_stats\n\n获取图统计信息，包括节点总数、边总数、活跃节点数等。\n\n无参数要求。\n\n资料来源：[server.py:66]()\n\n## 工具分发机制\n\n### 分发表结构\n\n工具分发通过 `_TOOL_DISPATCH` 字典实现，每个条目包含三元素元组：\n\n```python\n_TOOL_DISPATCH = {\n    \"tool_name\": (handler, required_args, optional_args_with_defaults)\n}\n```\n\n资料来源：[server.py:35-47]()\n\n### 调用流程\n\n```mermaid\nsequenceDiagram\n    participant Client as MCP 客户端\n    participant Server as MCP Server\n    participant Dispatch as 分发器\n    participant Tools as 工具实现\n    participant Storage as 存储提供者\n\n    Client->>Server: call_tool(\"memory_store\", {...})\n    Server->>Dispatch: 查找工具处理器\n    Dispatch->>Dispatch: 验证必需参数\n    Dispatch->>Dispatch: 合并默认参数\n    Dispatch->>Tools: 调用 handler(**params)\n    Tools->>Storage: 读写数据\n    Storage-->>Tools: 返回结果\n    Tools-->>Server: TextContent 列表\n    Server-->>Client: 格式化响应\n```\n\n### 权限验证\n\n工具执行前需进行权限检查，核心逻辑位于 `mcp/tools.py`：\n\n```python\ndef _caller_owns_node(node: MemoryNode) -> bool:\n    uid = _caller_uid()\n    if uid is None:\n        raise PermissionError(\"current_user_id not set\")\n    role = current_user_role.get(None)\n    if role == \"admin\" and node.org_id in current_org_ids:\n        return True\n    return node.original_user_id == uid\n```\n\n资料来源：[mcp/tools.py:26-40]()\n\n## 记忆节点数据模型\n\n### MemoryNode 核心字段\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 节点唯一标识 |\n| `status` | MemoryStatus | 生命周期状态（ACTIVE、DORMANT、FADING 等） |\n| `content_summary` | string | 内容摘要（最大 200 字符） |\n| `content_full` | string | 完整内容（可选） |\n| `embedding` | float[] | 向量嵌入（用于相似度搜索） |\n| `decay_score` | float | 衰减评分（ relevance × connectivity × reactivation） |\n| `causal_weight` | int | 因果权重（连接数） |\n| `reactivation_count` | int | 激活次数 |\n| `pinned` | bool | 是否固定为核心记忆 |\n| `stability` | float | 稳定性分数（成功检索后增加） |\n\n资料来源：[models/node.py:12-45]()\n\n## MCP 协议集成\n\n### 服务端点\n\n| 传输方式 | 端点 | 用途 |\n|---------|------|------|\n| stdio | 直接标准输入输出 | Claude Desktop、本地集成 |\n| HTTP | `http://localhost:8000/mcp` | Claude Code、网络客户端 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 工具注册\n\n工具通过 `@app.list_tools()` 和 `@app.call_tool()` 装饰器注册：\n\n```python\n@app.list_tools()\nasync def list_tools() -> list[Tool]:\n    return _TOOL_SCHEMAS\n\n@app.call_tool()\nasync def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:\n    if name not in _TOOL_DISPATCH:\n        return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n    # 处理工具调用...\n```\n\n资料来源：[server.py:19-26]()\n\n## 配置选项\n\n### 环境变量\n\n| 变量 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端：`memory`、`postgres`、`obsidian`、`falkordb` |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式的默认用户 ID |\n| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | Anthropic API 密钥（用于 LLM 记忆处理） |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n## 错误处理\n\n### 权限错误\n\n```python\nif uid is None:\n    raise PermissionError(\"current_user_id not set — cannot verify ownership\")\n```\n\n### 未知工具\n\n```python\nif name not in _TOOL_DISPATCH:\n    return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n```\n\n### 返回格式\n\n所有工具返回 `list[TextContent]`，其中 `TextContent` 包含 `type` 和 `text` 字段。\n\n## 使用示例\n\n### Claude Desktop 配置\n\n```json\n{\n  \"mcpServers\": {\n    \"genesys\": {\n      \"url\": \"http://localhost:8000/mcp\"\n    }\n  }\n}\n```\n\n### Claude Code 配置\n\n```bash\nclaude mcp add --transport http genesys http://localhost:8000/mcp\n```\n\n### 启动 MCP 服务器\n\n```bash\nuvicorn genesys.api:app --port 8000\n```\n\n或使用轻量级 stdio 服务器：\n\n```bash\npython -m genesys_memory\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n\n## 扩展开发\n\n如需添加新工具，需完成以下步骤：\n\n1. 在 `mcp/tools.py` 中实现工具函数\n2. 在 `_TOOL_SCHEMAS` 中定义工具元数据（名称、描述、输入模式）\n3. 在 `_TOOL_DISPATCH` 中注册工具（handler、必需参数、可选参数及默认值）\n4. 添加对应的单元测试\n\n```python\n# 示例：添加新工具\n_TOOL_DISPATCH[\"new_tool\"] = (\n    tools.new_tool,\n    [\"required_param\"],\n    {\"optional_param\": \"default_value\"}\n)\n\n---\n\n<a id='page-storage-backends'></a>\n\n## 存储后端实现\n\n### 相关页面\n\n相关主题：[系统架构](#page-architecture), [检索系统](#page-retrieval-system)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)\n- [src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)\n- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n</details>\n\n# 存储后端实现\n\n## 概述\n\nGenesys 的存储后端系统是一个模块化的存储抽象层，为记忆引擎提供统一的数据持久化和检索接口。该设计允许用户根据不同场景选择合适的存储方案，同时保持核心记忆评分引擎的独立性。\n\n存储后端系统的核心职责包括：\n\n- **记忆节点管理**：创建、读取、更新、删除记忆节点\n- **因果图维护**：管理记忆之间的因果边关系\n- **向量嵌入存储**：持久化记忆的语义向量表示\n- **全文内容存储**：保存记忆的完整内容和摘要\n- **元数据管理**：维护访问时间、评分、状态等生命周期信息\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## 架构设计\n\n### 核心抽象层\n\nGenesys 采用接口抽象设计，定义了一系列存储提供者接口。任何实现这些接口的存储系统都可以作为 Genesys 的后端使用。\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│                      MCP 工具层                              │\n│  memory_store | memory_recall | memory_search | etc.        │\n├─────────────────────────────────────────────────────────────┤\n│                      核心引擎层                              │\n│         评分引擎 | 生命周期管理 | 记忆整合                   │\n├─────────────────────────────────────────────────────────────┤\n│                      存储抽象层                              │\n│  GraphStorageProvider | CacheProvider | EmbeddingProvider   │\n├─────────────────────────────────────────────────────────────┤\n│                      存储后端实现                            │\n│  MemoryStorage | PostgresStorage | ObsidianStorage | FalkorDB│\n└─────────────────────────────────────────────────────────────┘\n```\n\n资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n\n### 存储提供者类型\n\n| 提供者类型 | 接口定义 | 用途 |\n|-----------|---------|------|\n| `GraphStorageProvider` | 图存储接口 | 管理记忆节点和因果边 |\n| `CacheProvider` | 缓存接口 | 提供高速缓存层 |\n| `EmbeddingProvider` | 向量嵌入接口 | 生成和检索语义向量 |\n| `EventBusProvider` | 事件总线接口 | 发布记忆事件 |\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n---\n\n## 数据模型\n\n### 记忆节点（MemoryNode）\n\n`MemoryNode` 是 Genesys 中记忆的基本存储单元，包含记忆的所有属性信息。\n\n```python\nclass MemoryNode(BaseModel):\n    id: uuid.UUID = Field(default_factory=uuid.uuid4)\n    status: MemoryStatus = MemoryStatus.ACTIVE\n    content_summary: str = Field(max_length=200)\n    content_full: str | None = None\n    content_ref: str | None = None\n    embedding: list[float] | None = None\n\n    # 时间戳\n    created_at: datetime\n    last_accessed_at: datetime\n    last_reactivated_at: datetime\n\n    # 生命周期评分\n    decay_score: float = 1.0\n    causal_weight: int = 0\n    reactivation_count: int = 0\n    reactivation_pattern: ReactivationPattern\n    irrelevance_counter: int = 0\n\n    # 来源追踪\n    source_agent: str = \"claude\"\n    source_session: str = \"\"\n\n    # 分类\n    entity_refs: list[str] = []\n    category: str | None = None\n\n    # 稳定性\n    stability: float = 1.0\n\n    # 核心记忆\n    pinned: bool = False\n    promotion_reason: str | None = None\n\n    # 激活历史\n    reactivation_timestamps: list[datetime]\n```\n\n**字段说明**：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `id` | UUID | 记忆唯一标识符 |\n| `status` | MemoryStatus | 当前生命周期状态 |\n| `content_summary` | str | 记忆摘要（最大200字符） |\n| `content_full` | str | 完整记忆内容 |\n| `content_ref` | str | 外部引用链接 |\n| `embedding` | list[float] | 语义向量表示 |\n| `decay_score` | float | 衰减评分（0.0-1.0） |\n| `causal_weight` | int | 因果权重（连接数） |\n| `reactivation_count` | int | 被激活次数 |\n| `stability` | float | 稳定性指数 |\n| `pinned` | bool | 是否固定为核心记忆 |\n\n资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)\n\n### 记忆边（MemoryEdge）\n\n`MemoryEdge` 表示记忆节点之间的因果关系。\n\n```python\nclass MemoryEdge(BaseModel):\n    source_id: uuid.UUID\n    target_id: uuid.UUID\n    type: EdgeType\n    weight: float\n```\n\n**边的类型**：\n\n| 类型 | 说明 | 置信度阈值 |\n|------|------|-----------|\n| `caused_by` | 因果关系 | > 0.6 |\n| `supports` | 支持关系 | > 0.6 |\n| `derived_from` | 派生关系 | > 0.6 |\n\n资料来源：[src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)\n\n---\n\n## 可用存储后端\n\n### 1. 内存后端（Memory）\n\n零依赖的内置后端，适合快速试用和开发测试。\n\n**特性**：\n- 无需额外安装\n- 数据存储在内存中，重启后丢失\n- 适合概念验证和小规模测试\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 2. PostgreSQL 后端（Postgres + pgvector）\n\n生产级持久化存储，支持向量相似度搜索。\n\n**安装**：\n```bash\npip install 'genesys-memory[postgres]'\n```\n\n**配置**：\n| 环境变量 | 必需 | 说明 |\n|---------|------|------|\n| `OPENAI_API_KEY` | 是 | 向量嵌入生成 |\n| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 |\n| `GENESYS_BACKEND` | 是 | 设置为 `postgres` |\n\n**启动流程**：\n```bash\ndocker compose up -d postgres\nalembic upgrade head\nGENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 3. Obsidian Vault 后端\n\n将 Obsidian 笔记库转换为记忆存储，Markdown 文件成为记忆节点，`[[wikilinks]]` 自动转换为因果边。\n\n**安装**：\n```bash\npip install 'genesys-memory[obsidian]'\n```\n\n**配置**：\n| 环境变量 | 说明 |\n|---------|------|\n| `OBSIDIAN_VAULT_PATH` | Obsidian 库路径 |\n| `GENESYS_EMBEDDER` | `openai`（默认）或 `local` |\n\n**本地嵌入模式**（无需 API Key）：\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n使用 `all-MiniLM-L6-v2` 模型（约80MB）进行本地向量生成。\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n### 4. FalkorDB 后端\n\n基于 Redis 的原生图数据库后端，支持高性能图遍历。\n\n**安装**：\n```bash\npip install 'genesys-memory[falkordb]'\n```\n\n**配置**：\n| 环境变量 | 说明 |\n|---------|------|\n| `FALKORDB_HOST` | FalkorDB 主机（默认：localhost） |\n\n**启动**：\n```bash\ndocker compose up -d falkordb\nuvicorn genesys.api:app --port 8000\n```\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## MCP 工具接口\n\nMCP 工具层提供统一的记忆操作接口，各存储后端均实现相同的功能语义。\n\n### 核心工具列表\n\n| 工具名称 | 功能描述 |\n|---------|---------|\n| `memory_store` | 存储新记忆，可选链接相关记忆 |\n| `memory_recall` | 混合检索（向量 + 关键词 + 图扩散激活） |\n| `memory_search` | 过滤检索（状态、日期、关键词） |\n| `memory_traverse` | 从指定节点遍历因果图 |\n| `memory_explain` | 解释记忆评分详情 |\n| `memory_stats` | 获取记忆系统统计 |\n| `pin_memory` | 固定记忆为核心记忆 |\n| `unpin_memory` | 取消固定 |\n| `delete_memory` | 永久删除记忆 |\n| `list_core_memories` | 列出核心记忆 |\n| `set_core_preferences` | 设置核心记忆偏好 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n### 检索流程\n\n```mermaid\ngraph TD\n    A[memory_recall 查询] --> B[向量相似度搜索]\n    A --> C[关键词匹配]\n    B --> D[图扩散激活]\n    C --> D\n    D --> E[结果排序融合]\n    E --> F[返回 Top-K 结果]\n```\n\n**recall 参数**：\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `query` | string | 必需 | 自然语言查询 |\n| `k` | integer | 10 | 返回结果数量 |\n| `max_results` | integer | - | 最大结果限制 |\n\n资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n\n---\n\n## 缓存层实现\n\n缓存层位于存储后端之上，提供高速数据访问能力。\n\n### 缓存策略\n\n| 策略 | 说明 | 适用场景 |\n|------|------|---------|\n| LRU | 最近最少使用 | 高频访问记忆 |\n| TTL | 时间过期 | 会话上下文 |\n| 写回 | 延迟写入 | 批量操作优化 |\n\n### 缓存配置\n\n| 配置项 | 说明 |\n|-------|------|\n| `max_size` | 最大缓存条目数 |\n| `ttl_seconds` | 缓存过期时间 |\n| `eviction_policy` | 淘汰策略 |\n\n资料来源：[src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)\n\n---\n\n## 自定义后端开发\n\nGenesys 支持通过实现存储接口来创建自定义后端。\n\n### 实现步骤\n\n1. **继承基础接口**：实现 `GraphStorageProvider`\n2. **实现必需方法**：`create_node`、`get_node`、`update_node`、`delete_node`、`create_edge`、`get_edges`、`search_nodes`\n3. **注册后端**：通过环境变量配置使用\n\n```python\nclass CustomStorageProvider(GraphStorageProvider):\n    async def create_node(self, node: MemoryNode) -> uuid.UUID:\n        # 实现节点创建逻辑\n        pass\n    \n    async def search_nodes(\n        self, \n        query: str, \n        embedding: list[float], \n        k: int = 10\n    ) -> list[tuple[MemoryNode, float]]:\n        # 实现向量搜索\n        pass\n```\n\n资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)\n\n---\n\n## 配置参考\n\n### 环境变量汇总\n\n| 变量名 | 必需 | 默认值 | 说明 |\n|-------|------|--------|------|\n| `OPENAI_API_KEY` | 除非使用本地嵌入 | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | Claude API 密钥 |\n| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |\n| `DATABASE_URL` | Postgres 后端 | - | PostgreSQL 连接字符串 |\n| `OBSIDIAN_VAULT_PATH` | Obsidian 后端 | - | Obsidian 库路径 |\n| `FALKORDB_HOST` | FalkorDB 后端 | `localhost` | FalkorDB 主机 |\n| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |\n| `GENESYS_PERSIST_PATH` | 否 | - | 状态持久化路径 |\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n## 性能考量\n\n### 后端选型建议\n\n| 场景 | 推荐后端 | 原因 |\n|------|---------|------|\n| 快速原型开发 | Memory | 零配置，即开即用 |\n| 生产部署 | Postgres | 成熟稳定，支持向量索引 |\n| 个人知识管理 | Obsidian | 本地优先，无云依赖 |\n| 图遍历密集 | FalkorDB | 原生图数据库性能优势 |\n\n### 扩展性\n\n- **水平扩展**：Postgres 后端支持连接池和读写分离\n- **向量索引**：Postgres 使用 pgvector 扩展，支持 HNSW 和 IVFFlat 索引\n- **分片**：FalkorDB 支持 Redis Cluster 模式\n\n资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n\n---\n\n<a id='page-retrieval-system'></a>\n\n## 检索系统\n\n### 相关页面\n\n相关主题：[存储后端实现](#page-storage-backends), [MCP 工具集](#page-mcp-tools)\n\n<details>\n<summary>相关源码文件</summary>\n\n以下源码文件用于生成本页说明：\n\n- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)\n- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)\n- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)\n- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)\n- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)\n</details>\n\n# 检索系统\n\n## 概述\n\nGenesys 的检索系统是整个记忆引擎的核心组件，负责从因果图中高效召回相关记忆。该系统采用混合检索策略，结合向量搜索、关键词匹配和图传播激活（graph spreading activation）三种技术，实现精准的记忆召回。 资料来源：[README.md]()\n\n检索系统的设计目标是解决\"扁平记忆无法扩展\"的问题。与传统的向量存储不同，Genesys 不仅提供回忆能力，还通过因果图理解记忆之间的关联，使第 500 条记忆不会被第 5 条记忆埋没。 资料来源：[README.md]()\n\n## 架构设计\n\n### 混合检索流程\n\n```mermaid\ngraph TD\n    A[用户查询] --> B[向量嵌入]\n    A --> C[关键词提取]\n    B --> D[向量相似度搜索]\n    C --> E[关键词匹配]\n    D --> F[候选记忆集合]\n    E --> F\n    F --> G[图传播激活]\n    G --> H[混合评分排序]\n    H --> I[最终结果]\n    \n    J[因果图] --> G\n```\n\n检索系统的工作流程包含四个主要阶段：\n\n1. **查询处理阶段**：将自然语言查询转换为向量嵌入，同时提取关键词\n2. **候选生成阶段**：通过向量搜索和关键词匹配生成候选记忆集合\n3. **图传播激活阶段**：在因果图上执行 spreading activation 算法，增强关联记忆的权重\n4. **混合排序阶段**：综合向量相似度、关键词匹配度和图关联度进行最终排序\n\n### 核心组件\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| 向量嵌入模块 | `src/genesys_memory/retrieval/embedding.py` | 文本向量化，支持 OpenAI 和本地模型 |\n| LLM 提供器 | `src/genesys_memory/engine/llm_provider.py` | LLM 驱动的因果关系识别 |\n| MCP 工具层 | `src/genesys_memory/mcp/tools.py` | 对外暴露检索 API |\n| 图存储层 | 存储后端 | 因果图的持久化和遍历 |\n\n## MCP 检索工具\n\nGenesys 通过 MCP（Model Context Protocol）协议暴露检索能力，提供五个核心工具。 资料来源：[server.py:1-80]()\n\n### memory_recall — 混合召回\n\n`memory_recall` 是最主要的检索工具，执行向量搜索、关键词搜索和图传播激活的混合检索。\n\n```python\nTool(name=\"memory_recall\", description=\"Recall memories using hybrid search (vector + keyword + graph spreading activation).\", inputSchema={\n    \"type\": \"object\", \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n        \"max_results\": {\"type\": \"integer\"},\n    },\n})\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| query | string | 必需 | 自然语言查询字符串 |\n| k | integer | 10 | 返回结果数量 |\n| max_results | integer | - | 最大结果上限 |\n\n### memory_search — 过滤搜索\n\n`memory_search` 提供基于元数据过滤的向量搜索能力。\n\n```python\nTool(name=\"memory_search\", description=\"Search memories with filters (status, category, date, or entity).\", inputSchema={\n    \"type\": \"object\", \"required\": [\"query\"],\n    \"properties\": {\n        \"query\": {\"type\": \"string\"},\n        \"filters\": {\"type\": \"object\"},\n        \"k\": {\"type\": \"integer\", \"default\": 10},\n    },\n})\n```\n\n**支持的过滤字段：**\n\n- `status`：记忆状态（ACTIVE、DORMANT、FADING 等）\n- `category`：记忆类别\n- `date_range`：日期范围\n- `entity`：实体引用\n\n### memory_traverse — 图遍历\n\n`memory_traverse` 用于从指定节点出发，在因果图上进行深度遍历。\n\n```python\nTool(name=\"memory_traverse\", description=\"Traverse the memory graph from a starting node.\", inputSchema={\n    \"type\": \"object\", \"required\": [\"node_id\"],\n    \"properties\": {\n        \"node_id\": {\"type\": \"string\"},\n        \"depth\": {\"type\": \"integer\", \"default\": 2},\n        \"edge_types\": {\"type\": \"array\", \"items\": {\"type\": \"string\"}},\n    },\n})\n```\n\n### memory_explain — 评分解释\n\n`memory_explain` 解释特定记忆的评分构成，帮助理解记忆为何被召回。\n\n```python\nTool(name=\"memory_explain\", description=\"Explain a memory's score breakdown.\", inputSchema={\n    \"type\": \"object\", \"required\": [\"node_id\"],\n    \"properties\": {\"node_id\": {\"type\": \"string\"}},\n})\n```\n\n### memory_stats — 统计信息\n\n`memory_stats` 获取图的统计信息，用于监控和调试。\n\n```python\nTool(name=\"memory_stats\", description=\"Get graph statistics.\", inputSchema={\n    \"type\": \"object\", \"properties\": {},\n})\n```\n\n## 向量嵌入系统\n\n### 嵌入提供者配置\n\nGenesys 支持两种嵌入提供者，通过 `GENESYS_EMBEDDER` 环境变量配置。 资料来源：[README.md]()\n\n| 提供者 | 配置值 | 说明 |\n|--------|--------|------|\n| OpenAI | `openai`（默认） | 使用 OpenAI 的 text-embedding-ada-002 或更新的模型 |\n| 本地 | `local` | 使用 sentence-transformers 的 all-MiniLM-L6-v2（384 维），约 80MB |\n\n本地嵌入模式无需任何 API 密钥，适合完全离线的使用场景：\n\n```bash\npip install 'genesys-memory[obsidian,local]'\n```\n\n```env\nGENESYS_BACKEND=obsidian\nGENESYS_EMBEDDER=local\n# 无需 OPENAI_API_KEY\n```\n\n### 嵌入生成时机\n\n在创建新记忆时，系统会自动生成嵌入向量：\n\n```python\n# 资料来源：mcp/tools.py\nembedding = await self.embeddings.embed(content) if self.embeddings else []\n```\n\n嵌入向量用于两个目的：\n\n1. **向量相似度搜索**：找到语义上相似的历史记忆\n2. **自动关联**：将新记忆与相似记忆自动建立连接边\n\n## 因果关系识别\n\n### LLM 驱动的因果分析\n\n当创建新记忆时，系统使用 LLM 分析新记忆与现有记忆之间的因果关系。 资料来源：[llm_provider.py]()\n\n```python\nprompt = (\n    \"Given a new memory and a list of existing memories, identify causal relationships.\\n\\n\"\n    f\"New memory: {new_memory}\\n\\nExisting memories:\\n{mem_lines}\\n\\n\"\n    \"For each causal relationship found, specify:\\n\"\n    \"- target_id: the ID of the existing memory\\n\"\n    '- edge_type: one of \"caused_by\", \"supports\", \"derived_from\"\\n'\n    \"- confidence: 0.0 to 1.0\\n\"\n    \"- reason: brief explanation of why this relationship exists\\n\\n\"\n    \"Only include relationships with confidence > 0.6.\\n\"\n    \"Respond with ONLY a JSON array of objects, no other text.\"\n)\n```\n\n### 边类型定义\n\n| 边类型 | 说明 | 使用场景 |\n|--------|------|----------|\n| `caused_by` | 因果关系 | A 导致 B 发生 |\n| `supports` | 支持关系 | A 为 B 提供证据 |\n| `derived_from` | 派生关系 | B 由 A 提炼而来 |\n| `related_to` | 关联关系 | 自动链接的语义相似记忆 |\n\n### 置信度阈值\n\n只有置信度超过 **0.6** 的因果关系才会被采纳：\n\n```python\nif confidence > 0.6:\n    results.append((item[\"target_id\"], edge_type, confidence, item.get(\"reason\")))\n```\n\n## 自动关联机制\n\n### 相似记忆自动链接\n\n新记忆创建时，系统会自动将其与语义相似的现有记忆关联。 资料来源：[mcp/tools.py]()\n\n```python\n# 向量搜索找到相似记忆\nsimilar = await self.graph.vector_search(embedding, k=4, org_ids=org_ids)\n\nfor other_node, score in similar:\n    if score < 0.3:  # 相似度阈值\n        continue\n```\n\n**关键参数：**\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| k | 4 | 搜索返回的最大相似记忆数 |\n| 相似度阈值 | 0.3 | 只有高于此值的链接才会创建 |\n\n### 组织边界规则\n\n当记忆可见性为 `ORG`（组织级别）时，系统会强制执行组织边界规则：\n\n```python\n# Org boundary rule: org nodes only link to same-org nodes\nif vis == Visibility.ORG:\n    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:\n        continue\n```\n\n### 自动创建的边\n\n自动关联创建的边使用 `EdgeType.RELATED_TO` 类型，并记录相似度分数和创建原因：\n\n```python\nedge = MemoryEdge(\n    source_id=node.id,\n    target_id=other_node.id,\n    type=EdgeType.RELATED_TO,\n    weight=round(score, 4),\n    reason=f\"cosine similarity {score:.3f}\",\n    created_by=\"auto_link\",\n)\n```\n\n## 记忆状态与生命周期\n\n检索系统与记忆的生命周期紧密集成。记忆在系统中经历以下状态转换： 资料来源：[README.md]()\n\n```mermaid\ngraph LR\n    A[STORE] --> B[ACTIVE]\n    B --> C[DORMANT]\n    C --> D[FADING]\n    D --> E[PRUNED]\n    B --> F[reactivation]\n    F --> B\n```\n\n### 评分公式\n\n记忆被三个因素共同评分：\n\n```\ndecay_score = relevance × connectivity × reactivation\n```\n\n| 因素 | 说明 | 衰减特性 |\n|------|------|----------|\n| relevance | 相关性 | 随时间衰减，久未访问的记忆会淡化 |\n| connectivity | 连接性 | 奖励拥有多条因果边的记忆，枢纽记忆存活 |\n| reactivation | 再激活 | 频繁被召回的记忆获得提升 |\n\n由于公式是乘法形式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁召回但没有因果边的孤立记忆也会淡化。\n\n## 检索配置选项\n\n### 环境变量配置\n\n| 变量 | 必需 | 默认值 | 说明 |\n|------|------|--------|------|\n| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |\n| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |\n| `ANTHROPIC_API_KEY` | 否 | - | 用于 LLM 记忆处理的 Anthropic 密钥 |\n\n### 不同存储后端的检索\n\nGenesys 的检索系统与存储后端解耦，可配合多种后端使用： 资料来源：[README.md]()\n\n| 后端 | 向量搜索 | 图遍历 | 适用场景 |\n|------|----------|--------|----------|\n| 内存 | 内置 | 内置 | 零依赖试用 |\n| PostgreSQL + pgvector | pgvector | SQL | 生产级持久化 |\n| Obsidian Vault | 插件实现 | WikiLink 解析 | 本地知识库 |\n| FalkorDB | Redis 模块 | 原生图遍历 | 图原生场景 |\n\n## 性能与基准\n\n在 LoCoMo 长对话记忆基准测试中（1540 个问题，10 个对话），Genesys 的检索系统表现如下： 资料来源：[README.md]()\n\n| 类别 | J-Score |\n|------|---------|\n| Single-hop（单跳） | 94.3% |\n| Temporal（时序） | 87.5% |\n| Multi-hop（多跳） | 69.8% |\n| Open-domain（开放域） | 91.7% |\n| **总体** | **89.9%** |\n\n作为对比，同一基准测试中 Mem0 得分为 67.1%，Zep 得分为 75.1%。检索模型使用 `gpt-4o-mini`，评判模型同样使用 `gpt-4o-mini`，检索 k=20。\n\n## 代码组织\n\n```\nsrc/genesys_memory/\n├── retrieval/\n│   └── embedding.py          # 向量嵌入生成\n├── engine/\n│   ├── llm_provider.py       # LLM 因果关系识别\n│   ├── consolidation.py      # 记忆整合\n│   └── config.py             # 引擎阈值配置\n└── mcp/\n    └── tools.py              # MCP 工具实现\n```\n\n## 开发指南\n\n引擎阈值配置在 `engine/config.py` 中，应通过环境变量配置，避免在引擎文件中硬编码魔法数字。 资料来源：[CONTRIBUTING.md]()\n\n### 测试检索功能\n\n```bash\n# 运行所有单元测试\npytest tests/ -v\n\n# 带覆盖率\npytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing\n```\n\n测试文件位于 `tests/` 目录，使用 `pytest-asyncio`（auto 模式）。新增引擎逻辑时，应在相应测试文件中添加对应的测试用例。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：rishimeka/genesys\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1207565616 | https://github.com/rishimeka/genesys | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\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:1207565616 | https://github.com/rishimeka/genesys | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1207565616 | https://github.com/rishimeka/genesys | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | release_recency=unknown\n\n<!-- canonical_name: rishimeka/genesys; human_manual_source: deepwiki_human_wiki -->\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项目：rishimeka/genesys\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。\n\n## 1. 配置坑 · 可能修改宿主 AI 配置\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。\n- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- 证据：capability.host_targets | github_repo:1207565616 | https://github.com/rishimeka/genesys | host_targets=mcp_host, claude\n\n## 2. 能力坑 · 能力判断依赖假设\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:1207565616 | https://github.com/rishimeka/genesys | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1207565616 | https://github.com/rishimeka/genesys | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1207565616 | https://github.com/rishimeka/genesys | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1207565616 | https://github.com/rishimeka/genesys | release_recency=unknown\n",
      "summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
      "title": "Pitfall Log / 踩坑日志"
    },
    "prompt_preview": {
      "asset_id": "prompt_preview",
      "filename": "PROMPT_PREVIEW.md",
      "markdown": "# genesys - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 genesys 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client / claude\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 项目说明, 边界判断, 后续问题。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 项目知识预览: 项目可被阅读和解释，但当前证据不足以确认可安装能力或运行入口。 输入：README 和项目文档；输出：项目说明, 边界判断, 后续问题。\n\n【必须安装后才可验证的能力】\n- 暂无明确的运行时能力线索。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装指南。围绕“安装指南”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始。围绕“快速开始”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n5. page-data-models：数据模型。围绕“数据模型”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-data-models\n输入：用户提供的“数据模型”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装指南”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-data-models：Step 5 必须围绕“数据模型”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/rishimeka/genesys\n- https://github.com/rishimeka/genesys#readme\n- benchmarks/README.md\n- CONTRIBUTING.md\n- LICENSE\n- .github/pull_request_template.md\n- CHANGELOG.md\n- README.md\n- src/genesys_memory/engine/scoring.py\n- src/genesys_memory/models/node.py\n- pyproject.toml\n- .env.example\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 genesys 的核心服务。\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项目：rishimeka/genesys\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install genesys-memory\n```\n\n来源：https://github.com/rishimeka/genesys#readme\n\n## 来源\n\n- repo: https://github.com/rishimeka/genesys\n- docs: https://github.com/rishimeka/genesys#readme\n",
      "summary": "从项目官方 README 或安装文档提取的开工入口。",
      "title": "Quick Start / 官方入口"
    }
  },
  "validation_id": "dval_2c0e81f2b4f64a94886a7f8bf23c34db"
}