概述

Genesys 是一个面向 AI Agent 的记忆评分引擎、因果图谱和生命周期管理器。它解决了传统向量存储记忆方案的局限性——虽然能提供检索能力，但缺乏对记忆之间关系的理解。Genesys 通过乘法评分公式（相关性 × 连接性 × 再激活）对每条记忆进行评分，构建因果图谱实现关系推理，并主动遗忘已变得不相关的记忆。资料来源：README.md

Genesys 的核心理念是：记忆应该像人类一样，具有生命周期、会衰减、会被强化、会被遗忘，而非简单地堆积在向量数据库中。资料来源：README.md

核心架构

系统定位

Genesys 位于 LLM 与记忆存储层之间，作为智能记忆层运行。它不直接存储数据，而是协调多种存储后端，并通过 MCP（Model Context Protocol）协议与 AI 客户端原生集成。资料来源：README.md

graph TD
    A[AI 客户端<br/>Claude/Codellm] -->|MCP 协议| B[Genesys<br/>记忆引擎]
    B -->|评分/图谱/生命周期| C{存储后端}
    C -->|向量+图| D[Postgres + pgvector]
    C -->|本地优先| E[Obsidian Vault]
    C -->|图数据库| F[FalkorDB]
    C -->|内存模式| G[SQLite]

核心组件

记忆评分机制

评分公式

Genesys 采用三力乘法模型对记忆进行评分：

decay_score = relevance × connectivity × reactivation

资料来源：README.md

由于采用乘法公式，记忆必须同时在三个维度上都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁被回忆但没有因果链接的"孤岛"记忆同样会消失。资料来源：README.md

评分源代码逻辑

# 来自 engine/llm_provider.py 的因果关系检测
async def identify_causal_relationships(
    self, 
    new_memory: str, 
    existing_memories: list[tuple[str, str]]
) -> list[tuple[str, EdgeType, float, str | None]]:
    """
    识别新记忆与已有记忆之间的因果关系
    仅包含置信度 > 0.6 的关系
    """
    results: list[tuple[str, EdgeType, float, str | None]] = []
    for item in data:
        confidence = float(item.get("confidence", 0.0))
        if confidence > 0.6:
            results.append((
                item["target_id"], 
                EdgeType(edge_type_str), 
                confidence, 
                item.get("reason")
            ))
    return results

资料来源：src/genesys_memory/engine/llm_provider.py:1-30

记忆生命周期

状态转移图

graph TD
    STORE[STORE<br/>新建记忆] -->|评分>阈值| ACTIVE[ACTIVE<br/>活跃]
    ACTIVE -->|长期低分| DORMANT[DORMANT<br/>休眠]
    DORMANT -->|再次回忆| ACTIVE
    DORMANT -->|持续衰减| FADING[FADING<br/>消退]
    FADING -->|重新激活| ACTIVE
    FADING -->|评分归零且无链接| PRUNED[PRUNED<br/>删除]
    STORE -->|tagged状态| TAGGED[TAGGED<br/>已标记]
    TAGGED -->|形成边连接| ACTIVE
    TAGGED -->|24h无连接| PRUNED
    ACTIVE -->|promote| CORE[CORE<br/>核心记忆<br/>永不删除]

资料来源：README.md

状态详情

Tagged → Active 转移逻辑

# 来自 engine/transitions.py
async def evaluate_transitions(...):
    # Tagged → Active: 如果节点有边则提升
    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)
    for node in tagged_nodes:
        if not await graph.is_orphan(str(node.id)):
            await graph.update_node(str(node.id), {"status": MemoryStatus.ACTIVE})
            # 原因：consolidation signal: edge formed

资料来源：src/genesys_memory/engine/transitions.py:1-30

存储后端

Genesys 支持多种存储后端，可根据使用场景灵活选择：

资料来源：README.md

Obsidian Vault 集成

Obsidian 后端特别适合个人知识管理场景：

• Markdown 文件自动转为记忆节点
• [[wikilinks]] 自动转为因果边
• SQLite 侧car（.genesys/index.db）处理索引
• 文件监视器增量重索引

资料来源：README.md

完全本地模式（无 API Key）

pip install 'genesys-memory[obsidian,local]'

GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# 无需 OPENAI_API_KEY

本地嵌入使用 all-MiniLM-L6-v2（384 维）模型，首次使用时自动下载（约 80MB）。资料来源：README.md

MCP 工具接口

Genesys 通过 MCP（Model Context Protocol）提供标准化工具接口：

资料来源：src/genesys_memory/server.py:1-80

记忆存储工具实现

# 来自 mcp/tools.py
node = MemoryNode(
    status=MemoryStatus.ACTIVE,
    content_summary=summary,
    content_full=content,
    embedding=embedding,
    created_at=ts,
    last_accessed_at=ts,
    last_reactivated_at=ts,
    decay_score=1.0,
    causal_weight=0,
    source_agent="claude",
    source_session=source_session,
    visibility=vis,
    org_id=org_id,
    original_user_id=_caller_uid(),
)
node_id = await self.graph.create_node(node)

资料来源：src/genesys_memory/mcp/tools.py:1-50

记忆合并（Consolidation）

当大量情景记忆积累后，系统会自动将其合并为语义记忆：

# 来自 engine/consolidation.py
async def consolidate(episodic_memories: list[str], ...) -> str:
    # 匹配相关内容
    matching = await embeddings.find_similar(consolidated_text, ...)
    
    # 创建新的语义节点
    semantic_node = MemoryNode(
        status=MemoryStatus.SEMANTIC,
        content_summary=summary,
        content_full=consolidated_text,
        embedding=embedding,
        created_at=now,
        entity_refs=[entity_ref],
    )
    
    # 创建 DERIVED_FROM 边
    for source_node in matching:
        edge = MemoryEdge(
            source_id=semantic_node.id,
            target_id=source_node.id,
            type=EdgeType.DERIVED_FROM,
            weight=0.7,
        )
        await graph.create_edge(edge)

资料来源：src/genesys_memory/engine/consolidation.py:1-60

基准测试

Genesys 在 LoCoMo 长对话记忆基准上进行了测试（1540 个问题，10 个对话）：

对比基线：Mem0 67.1%，Zep 75.1%

资料来源：README.md

快速开始

环境要求

• Python 3.11+
• 可选：OpenAI API Key（用于嵌入生成，非必须）
• 可选：Anthropic API Key（用于 LLM 记忆处理）

安装

pip install genesys-memory

启动服务器

# 方式一：使用内存后端（零配置）
cp .env.example .env
# 配置 OPENAI_API_KEY
uvicorn genesys.api:app --port 8000

# 方式二：使用 Obsidian 后端
pip install 'genesys-memory[obsidian,local]'
uvicorn genesys.api:app --port 8000

连接 Claude Desktop

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

连接 Claude Code

claude mcp add --transport http genesys http://localhost:8000/mcp

资料来源：README.md

配置选项

资料来源：README.md

开发指南

代码规范

• Python 版本：3.11+
• 代码风格：async-first
• Linting：ruff check src/
• 类型检查：mypy src/genesys_memory --ignore-missing-imports
• 格式化：遵循现有模式，类型提示贯穿始终

测试

# 运行所有单元测试
pytest tests/ -v

# 带覆盖率
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing

资料来源：CONTRIBUTING.md

技术栈

资料来源：README.md, server.json

许可证与归属

Genesys 采用 AGPL-3.0-or-later 开源许可证。

注意：v0.3.6 之前的版本文档中错误标注为 Apache 2.0。LICENSE 文件始终包含 AGPLv3 文本。资料来源：README.md

项目由 Rishi Meka 在 Astrix Labs 创建，目标是构建 LLM 与记忆之间的智能层。资料来源：README.md

前提条件

系统要求

必要依赖

安装前需确保系统已安装以下工具：

• Python 3.11+ — 可通过 python.org 或系统包管理器安装
• pip — Python 包管理器（通常随 Python 一起安装）
• Git — 用于从源码安装

安装方式

Genesys 提供两种主要安装方式：从 PyPI 安装预发布版本，或从源码编译最新版本。

方式一：从 PyPI 安装（推荐）

# 基础安装（仅内置内存后端）
pip install genesys-memory

# 生产环境（Postgres 后端）
pip install 'genesys-memory[postgres]'

# Obsidian 集成
pip install 'genesys-memory[obsidian]'

# Obsidian + 本地嵌入（无需 API Key）
pip install 'genesys-memory[obsidian,local]'

# FalkorDB 图形数据库后端
pip install 'genesys-memory[falkordb]'

# 开发环境（包含测试依赖）
pip install 'genesys-memory[dev]'

资料来源：README.md

方式二：从源码安装

适用于需要最新功能或进行开发贡献的用户：

# 克隆仓库
git clone https://github.com/rishimeka/genesys.git
cd genesys

# 以开发模式安装（包含所有依赖）
pip install -e '.[dev]'

资料来源：CONTRIBUTING.md

存储后端选择

Genesys 采用插件化架构，支持多种存储后端。选择合适的后端取决于具体使用场景：

后端架构概览

graph TB
    subgraph "存储后端层"
        MEM[memory<br/>内置字典]
        PG[postgres + pgvector]
        OBS[Obsidian Vault]
        FALK[FalkorDB]
    end
    
    subgraph "核心引擎层"
        ENG[评分引擎]
        CAU[因果图]
        LCM[生命周期管理器]
    end
    
    subgraph "API 层"
        MCP[MCP 协议接口]
        REST[REST API]
    end
    
    MEM --> ENG
    PG --> ENG
    OBS --> ENG
    FALK --> ENG
    
    ENG --> CAU
    CAU --> LCM
    
    MCP --> ENG
    REST --> ENG

配置指南

环境变量配置

将 .env.example 复制为 .env 文件，并配置以下变量：

cp .env.example .env

配置参数详解

*使用 GENESYS_EMBEDDER=local 时不需要 OPENAI_API_KEY

资料来源：README.md、.env.example

快速启动方案

方案一：内存模式（零依赖）

适用于快速体验和开发测试：

# 安装基础包
pip install genesys-memory

# 创建配置文件
cp .env.example .env

编辑 .env：

OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=memory

启动服务器：

uvicorn genesys.api:app --port 8000

资料来源：README.md

方案二：Postgres + pgvector（生产环境）

适用于需要持久化存储的生产部署：

# 安装依赖
pip install 'genesys-memory[postgres]'

# 配置环境变量
cp .env.example .env

编辑 .env：

OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=postgres
DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys

启动 PostgreSQL 并运行迁移：

# 使用 Docker 启动 Postgres
docker compose up -d postgres

# 运行数据库迁移
alembic upgrade head

# 启动服务器
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000

资料来源：README.md

方案三：Obsidian Vault（本地优先）

将 Obsidian 笔记库转换为 Genesys 记忆存储：

# 安装依赖
pip install 'genesys-memory[obsidian]'

# 配置环境变量
cp .env.example .env

编辑 .env：

OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=obsidian
OBSIDIAN_VAULT_PATH=/path/to/your/vault

自动检测功能：如果未设置 OBSIDIAN_VAULT_PATH，Genesys 会自动在以下位置查找：

• ~/Documents/personal
• ~/Documents/Obsidian
• ~/obsidian

启动服务器：

uvicorn genesys.api:app --port 8000

首次启动时，Genesys 会自动索引保险库中的所有 .md 文件。文件监视器会在编辑笔记时增量重新索引。

资料来源：README.md

方案四：完全本地模式（无需 API Key）

使用本地嵌入模型，无需任何外部 API：

# 安装依赖
pip install 'genesys-memory[obsidian,local]'

# 配置环境变量
cp .env.example .env

编辑 .env：

GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# 无需 OPENAI_API_KEY

启动服务器：

uvicorn genesys.api:app --port 8000

本地嵌入模型：all-MiniLM-L6-v2（384 维），首次使用时会自动下载（约 80MB）。

资料来源：README.md

方案五：FalkorDB（图原生）

适用于需要原生图遍历的大规模关系数据：

# 安装依赖
pip install 'genesys-memory[falkordb]'

# 配置环境变量
cp .env.example .env

编辑 .env：

OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=falkordb
FALKORDB_HOST=localhost

启动 FalkorDB 和服务器：

# 使用 Docker 启动 FalkorDB
docker compose up -d falkordb

# 启动服务器
uvicorn genesys.api:app --port 8000

资料来源：README.md

Docker 部署

使用 Docker Compose 启动服务

项目提供了 docker-compose.yml 文件，可一键启动完整环境：

# 克隆仓库
git clone https://github.com/rishimeka/genesys.git
cd genesys

# 启动所有服务（包括 Postgres）
docker compose up -d

# 或仅启动 Postgres
docker compose up -d postgres

环境变量配置

在使用 Docker 部署时，确保 docker-compose.yml 中的环境变量配置正确。典型的环境变量包括：

environment:
  - OPENAI_API_KEY=${OPENAI_API_KEY}
  - GENESYS_BACKEND=postgres
  - DATABASE_URL=postgresql://genesys:genesys@postgres:5432/genesys

资料来源：docker-compose.yml

验证安装

启动服务器验证

服务器成功启动后，应看到类似输出：

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     Application startup complete.

MCP 工具列表

启动后可通过以下端点查看可用工具：

GET http://localhost:8000/mcp

可用工具包括：

资料来源：README.md

连接到 AI 助手

Claude Desktop 配置

在 claude_desktop_config.json 中添加配置：

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code 配置

claude mcp add --transport http genesys http://localhost:8000/mcp

通用 MCP 客户端

直接指向 MCP 端点：

http://localhost:8000/mcp

资料来源：README.md

开发环境安装

如需为 Genesys 项目贡献代码，请按以下步骤设置开发环境：

1. 克隆并安装

git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'

2. 代码质量工具

项目使用以下工具维护代码质量：

# 代码检查
ruff check src/

# 类型检查
mypy src/genesys_memory --ignore-missing-imports

# 运行测试
pytest tests/ -v

# 带覆盖率报告的测试
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing

3. 代码规范

• Python 版本：3.11+
• 异步优先：使用 async/await 模式
• 类型提示：全程使用类型注解
• 行长度限制：120 字符（配置于 pyproject.toml）

资料来源：CONTRIBUTING.md

故障排除

常见问题

状态持久化

如需在进程重启后保留内存后端数据，设置持久化路径：

GENESYS_PERSIST_PATH=.genesys_state.json

资料来源：README.md

依赖项参考

核心依赖

从 pyproject.toml 中提取的核心依赖包括：

• fastapi — Web 框架
• uvicorn — ASGI 服务器
• pydantic — 数据验证
• numpy — 数值计算
• httpx — HTTP 客户端
• anthropic — Anthropic API 集成
• openai — OpenAI API 集成
• sqlalchemy — ORM 框架
• alembic — 数据库迁移
• psycopg2-binary — PostgreSQL 驱动

可选依赖组

下一步

安装完成后，建议：

1. 运行演示脚本：使用 seed_demo.py 填充示例数据
2. 阅读架构文档：了解 Genesys 的评分引擎和生命周期管理
3. 探索 MCP 工具：尝试不同的记忆操作
4. 贡献代码：查看 CONTRIBUTING.md 了解贡献流程

系统架构概览

graph TD
    subgraph "客户端层"
        Claude_Desktop["Claude Desktop"]
        Claude_Code["Claude Code"]
        其他MCP客户端["其他 MCP 客户端"]
    end
    
    subgraph "Genesys 服务层"
        API["FastAPI / Uvicorn"]
        MCPServer["MCP Server"]
        Engine["记忆引擎"]
    end
    
    subgraph "存储后端"
        Memory["In-Memory"]
        Postgres["Postgres + pgvector"]
        Obsidian["Obsidian Vault"]
        FalkorDB["FalkorDB"]
    end
    
    Claude_Desktop --> MCPServer
    Claude_Code --> MCPServer
    其他MCP客户端 --> MCPServer
    API --> MCPServer
    MCPServer --> Engine
    Engine --> Memory
    Engine --> Postgres
    Engine --> Obsidian
    Engine --> FalkorDB

前置要求

资料来源：CONTRIBUTING.md:1-10

安装方式

方式一：pip 安装（推荐）

# 基础安装（内置内存存储）
pip install genesys-memory

# 安装特定存储后端
pip install 'genesys-memory[postgres]'      # Postgres + pgvector
pip install 'genesys-memory[obsidian]'      # Obsidian Vault
pip install 'genesys-memory[obsidian,local]' # 完全本地化
pip install 'genesys-memory[falkordb]'       # FalkorDB 图数据库

资料来源：README.md:1-50

方式二：从源码安装

git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'

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

方式三：Docker 部署

# 克隆仓库
git clone https://github.com/rishimeka/genesys.git
cd genesys

# 启动完整服务栈（包括 Postgres）
docker compose up -d

资料来源：docker-compose.yml

环境配置

配置文件创建

cp .env.example .env

资料来源：README.md:50-100

环境变量说明

*使用 GENESYS_EMBEDDER=local 时不需要

资料来源：README.md:100-120, .env.example

启动服务器

使用 uvicorn 启动

# 默认内存模式（零依赖）
uvicorn genesys.api:app --port 8000

# 指定后端
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000

资料来源：README.md:50-80

使用 Docker 启动

# 构建镜像
docker build -t genesys-memory .

# 运行容器
docker run -p 8000:8000 \
  -e OPENAI_API_KEY=sk-... \
  -e GENESYS_BACKEND=memory \
  genesys-memory

资料来源：Dockerfile

MCP 服务集成

Claude Code 配置

claude mcp add --transport http genesys http://localhost:8000/mcp

资料来源：README.md:150-160

Claude Desktop 配置

在 claude_desktop_config.json 中添加：

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

资料来源：README.md:160-175

其他 MCP 客户端

直接连接到 MCP 端点：

http://localhost:8000/mcp

MCP 工具列表

Genesys 提供以下 MCP 工具用于记忆管理：

资料来源：README.md:130-150, src/genesys_memory/server.py:1-80

记忆数据模型

classDiagram
    class MemoryNode {
        uuid id
        MemoryStatus status
        str content_summary
        str content_full
        list~float~ embedding
        datetime created_at
        datetime last_accessed_at
        float decay_score
        int causal_weight
        int reactivation_count
        bool pinned
        str category
    }
    
    class MemoryEdge {
        uuid source_id
        uuid target_id
        EdgeType type
        float weight
    }
    
    MemoryNode "1" --> "*" MemoryEdge : edges

资料来源：src/genesys_memory/models/node.py:1-40

MemoryNode 核心字段

class MemoryNode(BaseModel):
    id: uuid.UUID
    status: MemoryStatus  # ACTIVE, DORMANT, FADING, PRUNED
    content_summary: str  # 最大 200 字符
    content_full: str | None
    embedding: list[float] | None
    decay_score: float = 1.0
    causal_weight: int = 0
    reactivation_count: int = 0
    pinned: bool = False
    category: str | None
    stability: float = 1.0

资料来源：src/genesys_memory/models/node.py:10-35

存储后端对比

资料来源：README.md:80-95

Postgres 后端启动流程

# 1. 安装依赖
pip install 'genesys-memory[postgres]'

# 2. 编辑 .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "GENESYS_BACKEND=postgres" >> .env
echo "DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys" >> .env

# 3. 启动 Postgres
docker compose up -d postgres

# 4. 运行数据库迁移
alembic upgrade head

# 5. 启动服务
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000

资料来源：README.md:95-115

完全本地化配置（无需 API 密钥）

# 1. 安装
pip install 'genesys-memory[obsidian,local]'

# 2. 配置 .env
echo "GENESYS_BACKEND=obsidian" >> .env
echo "GENESYS_EMBEDDER=local" >> .env
echo "OBSIDIAN_VAULT_PATH=/path/to/your/vault" >> .env

# 3. 启动服务
uvicorn genesys.api:app --port 8000

使用 all-MiniLM-L6-v2（384 维）模型进行 Embedding，首次使用自动下载（约 80MB）。

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

记忆生命周期

stateDiagram-v2
    [*] --> ACTIVE: 创建
    ACTIVE --> DORMANT: 衰减评分下降
    DORMANT --> ACTIVE: 重新激活
    DORMANT --> FADING: 持续未访问
    FADING --> DORMANT: 被召回
    FADING --> PRUNED: 评分归零
    ACTIVE --> ACTIVE: 定期访问

评分公式

记忆评分由三个因素相乘决定：

decay_score = relevance × connectivity × reactivation

• Relevance（相关性）：随时间衰减
• Connectivity（连接性）：基于因果边数量
• Reactivation（再激活）：基于访问频率

资料来源：README.md:175-195

测试验证

# 运行所有测试
pytest tests/ -v

# 带覆盖率报告
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing

资料来源：CONTRIBUTING.md:20-30

快速启动模板

将以下内容复制给 Claude 即可自动完成配置：

"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."

资料来源：README.md:60-70

下一步

• 查看 CONTRIBUTING.md 了解开发规范
• 访问 benchmarks/ 了解性能基准
• 阅读 LICENSE 了解开源协议（AGPL-3.0）

概述

Genesys 是一个面向 AI Agent 的记忆系统，集成了评分引擎、因果图和生命周期管理器三大核心功能。它通过 MCP（Model Context Protocol）协议与 AI 进行原生交互，支持多种存储后端，能够模拟人类记忆的遗忘机制，对记忆进行动态管理和智能遗忘。

资料来源：README.md

核心架构组件

Genesys 的系统架构由以下主要模块组成：

资料来源：src/genesys_memory/__init__.py

架构分层图

graph TB
    subgraph "表现层 (MCP Interface)"
        MCP[MCP Server]
        TOOLS[MCP Tools]
    end
    
    subgraph "核心引擎层 (Engine)"
        SCORING[Scoring Engine]
        LIFECYCLE[Lifecycle Manager]
        CONSOLIDATION[Consolidation Engine]
        LLM_PROVIDER[LLM Provider]
    end
    
    subgraph "存储层 (Storage)"
        GRAPH[Graph Storage Provider]
        CACHE[Cache Provider]
        EMBEDDING[Embedding Provider]
        EVENT[Event Bus Provider]
    end
    
    subgraph "后端实现"
        MEMORY[In-Memory Backend]
        POSTGRES[Postgres + pgvector]
        OBSIDIAN[Obsidian Vault]
        FALKOR[FalkorDB]
    end
    
    MCP --> TOOLS
    TOOLS --> SCORING
    SCORING --> LIFECYCLE
    CONSOLATION --> LLM_PROVIDER
    LLM_PROVIDER --> SCORING
    
    SCORING --> GRAPH
    GRAPH --> CACHE
    GRAPH --> EMBEDDING
    
    GRAPH --> MEMORY
    GRAPH --> POSTGRES
    GRAPH --> OBSIDIAN
    GRAPH --> FALKOR

数据模型

MemoryNode 核心结构

MemoryNode 是系统的核心数据模型，定义了一条记忆的所有属性：

class MemoryNode(BaseModel):
    id: uuid.UUID = Field(default_factory=uuid.uuid4)
    status: MemoryStatus = MemoryStatus.ACTIVE
    content_summary: str = Field(max_length=200)
    content_full: str | None = None
    content_ref: str | None = None
    embedding: list[float] | None = None
    
    # 时间戳
    created_at: datetime
    last_accessed_at: datetime
    last_reactivated_at: datetime
    
    # 生命周期评分
    decay_score: float = 1.0      # 衰减分数
    causal_weight: int = 0        # 因果权重
    reactivation_count: int = 0   # 激活次数
    reactivation_pattern: ReactivationPattern  # 激活模式
    irrelevance_counter: int = 0   # 无关计数器
    
    # 分类
    entity_refs: list[str]        # 实体引用
    category: str | None          # 类别
    
    # 稳定性
    stability: float = 1.0        # 稳定性（记忆提取成功后增加）
    
    # 核心记忆
    pinned: bool = False          # 是否固定
    promotion_reason: str | None  # 晋升原因

资料来源：src/genesys_memory/models/node.py:1-45

记忆状态机

记忆在生命周期中经历以下状态转换：

graph LR
    STORE[STORE] --> ACTIVE[ACTIVE]
    ACTIVE --> DORMANT[DORMANT]
    DORMANT --> FADING[FADING]
    FADING --> PRUNED[PRUNED]
    
    ACTIVE -.->|reactivation| ACTIVE
    DORMANT -.->|reactivation| ACTIVE
    FADING -.->|reactivation| ACTIVE
    
    PRUNED -.->|特殊条件| PRUNED

状态说明：

资料来源：README.md

核心引擎

评分公式

Genesys 的记忆评分采用乘法公式，三个维度相乘得出最终分数：

decay_score = relevance × connectivity × reactivation

由于采用乘法公式，记忆必须在三个维度都有得分才能存活。高度连接但从未被访问的记忆会衰减；频繁回忆但无因果链接的记忆也会消失。

资料来源：README.md

LLM Provider

LLM Provider 负责使用大语言模型进行因果关系识别和记忆整合：

async def identify_causal_relationships(
    new_memory: str,
    existing_memories: list[tuple[str, str]]
) -> list[tuple[str, EdgeType, float, str | None]]:
    """识别新记忆与已有记忆之间的因果关系"""
    # 返回: (target_id, edge_type, confidence, reason)

边缘类型包括：

• caused_by - 因果导致
• supports - 支持关系
• derived_from - 派生关系

资料来源：src/genesys_memory/engine/llm_provider.py

Consolidation Engine

整合引擎负责将情景记忆合并为语义记忆：

graph TD
    EPISODIC[Episodic Memories] --> CONSOLIDATE{Consolidation}
    CONSOLIDATE --> LLM_SUMMARIZE[LLM Summarization]
    LLM_SUMMARIZE --> SEMANTIC[Semantic Memory Node]
    
    CONSOLIDATE --> EDGES[Create DERIVED_FROM Edges]
    SEMANTIC --> EDGES
    EDGES --> GRAPH[Graph Storage]

资料来源：src/genesys_memory/engine/consolidation.py

存储层架构

抽象接口设计

存储层通过抽象接口支持多种后端实现：

资料来源：src/genesys_memory/storage/__init__.py

支持的存储后端

graph LR
    subgraph "存储后端对比"
        MEMORY[In-Memory<br/>零依赖]
        PG[Postgres + pgvector<br/>持久化/可扩展]
        OBS[Obsidian Vault<br/>本地知识库]
        FALK[FalkorDB<br/>图原生]
        CUSTOM[Custom<br/>自定义实现]
    end

资料来源：README.md

MCP 协议集成

MCP Server 实现

Genesys 通过 FastMCP 实现 MCP 协议服务：

@app.list_tools()
async def list_tools() -> list[Tool]:
    return _TOOL_SCHEMAS

@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    if name not in _TOOL_DISPATCH:
        return [TextContent(type="text", text=f"Unknown tool: {name}")]
    return await _TOOL_DISPATCH[name](**arguments)

资料来源：src/genesys_memory/server.py

MCP 工具列表

资料来源：src/genesys_memory/server.py

请求流程

记忆存储流程

sequenceDiagram
    participant Client
    participant MCP_Server
    participant Scoring_Engine
    participant LLM_Provider
    participant Graph_Storage
    
    Client->>MCP_Server: memory_store(content)
    MCP_Server->>Scoring_Engine: create_node()
    Scoring_Engine->>LLM_Provider: identify_causal_relationships()
    LLM_Provider-->>Scoring_Engine: 返回因果边列表
    Scoring_Engine->>Graph_Storage: create_node + create_edges
    Graph_Storage-->>Scoring_Engine: node_id
    Scoring_Engine-->>MCP_Server: 返回结果
    MCP_Server-->>Client: 记忆存储成功

记忆召回流程

sequenceDiagram
    participant Client
    participant MCP_Server
    participant Engine
    participant Embedding
    participant Graph
    
    Client->>MCP_Server: memory_recall(query)
    MCP_Server->>Embedding: embed(query)
    Embedding-->>Engine: query_vector
    Engine->>Graph: vector_search(query_vector)
    Engine->>Graph: graph_spanning_activation()
    Graph-->>Engine: 混合排序结果
    Engine-->>MCP_Server: 记忆列表
    MCP_Server-->>Client: 返回召回结果

环境配置

配置变量表

*除非 GENESYS_EMBEDDER=local

资料来源：README.md

扩展机制

自定义存储后端

通过实现 GraphStorageProvider 接口，可以接入自定义存储：

class GraphStorageProvider(Protocol):
    async def create_node(self, node: MemoryNode) -> str: ...
    async def create_edge(self, edge: MemoryEdge) -> str: ...
    async def get_node(self, node_id: str) -> MemoryNode | None: ...
    async def get_neighbors(self, node_id: str) -> list[MemoryNode]: ...
    async def search(self, embedding: list[float], k: int) -> list[MemoryNode]: ...

资料来源：src/genesys_memory/storage/base.py

总结

Genesys 采用模块化分层架构，将表现层、核心引擎层和存储层解耦。核心的评分引擎通过乘法公式模拟人类记忆的遗忘机制，MCP 协议实现了与 AI Agent 的无缝集成，而灵活的存储抽象支持从内存到分布式图数据库的多种部署方式。

概述

Genesys 的数据模型是记忆系统的基础层，采用图结构来组织和关联 AI 代理的记忆。与传统的纯向量存储不同，Genesys 通过节点（MemoryNode） 和边（MemoryEdge） 构建因果图，使记忆能够表达语义关联、因果关系和激活历史。

数据模型的核心设计目标：

• 语义记忆：通过向量嵌入实现相似性检索
• 因果关联：通过边表达记忆之间的因果、支持和衍生关系
• 生命周期管理：支持记忆的状态转换和自动遗忘机制
• 权限控制：支持个人记忆和组织记忆的可见性管理

graph TB
    subgraph 数据模型层
        Node[MemoryNode<br/>记忆节点]
        Edge[MemoryEdge<br/>记忆边]
        Enums[枚举类型<br/>MemoryStatus<br/>EdgeType<br/>ReactivationPattern]
    end
    
    subgraph 存储后端
        PG[(Postgres<br/>+ pgvector)]
        SQLite[(SQLite)]
        FalkorDB[(FalkorDB)]
        Obsidian[(Obsidian Vault)]
    end
    
    Node --> Edge
    Enums --> Node
    Enums --> Edge
    
    Node --> PG
    Node --> SQLite
    Node --> FalkorDB
    Node --> Obsidian

资料来源：src/genesys_memory/models/__init__.py:1-9

核心模型

MemoryNode（记忆节点）

MemoryNode 是 Genesys 中存储单个记忆的基本单元。每个节点包含记忆的内容、元数据、时间戳、嵌入向量和状态信息。

classDiagram
    class MemoryNode {
        +UUID id
        +str content_summary
        +str content_full
        +list~float~ embedding
        +MemoryStatus status
        +Visibility visibility
        +str category
        +datetime created_at
        +datetime last_accessed_at
        +datetime last_reactivated_at
        +float relevance_score
        +float connectivity_score
        +float reactivation_count
        +bool is_pinned
        +bool is_core
        +str org_id
        +str original_user_id
        +list~str~ entity_refs
        +list~ReactivationPattern~ reactivation_patterns
    }

#### 节点核心属性

资料来源：src/genesys_memory/models/node.py

MemoryEdge（记忆边）

MemoryEdge 表示两个记忆节点之间的关系，边具有类型、权重和创建原因。

#### 边属性

资料来源：src/genesys_memory/models/edge.py

枚举类型

MemoryStatus（记忆状态）

记忆在生命周期中可能处于以下状态：

stateDiagram-v2
    [*] --> STORE: 创建新记忆
    STORE --> ACTIVE: 首次激活/关联
    ACTIVE --> DORMANT: 长时间未访问
    DORMANT --> ACTIVE: 被重新激活
    DORMANT --> FADING: 持续衰减
    FADING --> FADING: 评分继续下降
    FADING --> PRUNED: 评分归零/孤立/非固定
    ACTIVE --> FADING: 评分急剧下降
    PRUNED --> [*]

资料来源：src/genesys_memory/models/enums.py

EdgeType（边类型）

资料来源：src/genesys_memory/models/enums.py

Visibility（可见性）

ReactivationPattern（重新激活模式）

记录记忆被重新激活的方式，用于分析访问模式。

资料来源：src/genesys_memory/models/enums.py

评分机制

Genesys 采用三因素乘法评分模型决定记忆的生存能力：

decay_score = relevance × connectivity × reactivation

由于采用乘法模型，记忆必须在三个维度都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁访问但因果孤立记忆也会消失。

资料来源：README.md

核心记忆机制

核心记忆是系统中结构上重要、被自动固定的记忆，具有以下特性：

• 自动固定：不会因评分下降而被遗忘
• 权限保护：需要明确取消固定才能降级
• 自动晋升：满足晋升规则的记忆可自动成为核心记忆

graph LR
    A[普通记忆] --> B{晋升评估}
    B -->|满足规则| C[核心记忆]
    B -->|不满足| D[继续评估]
    C --> E[is_core=True]
    C --> F[is_pinned=True]

核心记忆的晋升由 promote_to_org 函数和权限检查机制控制，支持组织级别的记忆推广。

资料来源：src/genesys_memory/core_memory/promoter.py

所有权与权限

Genesys 支持多用户和组织级别的记忆管理：

所有权检查逻辑

def _caller_owns_node(node: MemoryNode) -> bool:
    uid = _caller_uid()
    role = current_user_role.get(None)
    # 管理员可访问同组织的节点
    if role == "admin" and node.org_id in current_org_ids.get([]):
        return True
    # 原始创建者拥有节点
    if node.original_user_id:
        return node.original_user_id == uid
    return True

组织边界规则

组织节点只能连接到同一组织的其他节点和边，确保数据隔离：

# 组织边界规则：org节点只链接到同org节点
if vis == Visibility.ORG:
    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:
        continue

资料来源：src/genesys_memory/mcp/tools.py:23-40

存储后端适配

数据模型通过抽象存储接口支持多种后端：

graph TB
    subgraph 存储提供者接口
        GraphStorageProvider[GraphStorageProvider]
        EmbeddingProvider[EmbeddingProvider]
        CacheProvider[CacheProvider]
        EventBusProvider[EventBusProvider]
    end
    
    subgraph 具体实现
        PostgresStore[Postgres + pgvector]
        SQLiteStore[SQLite]
        FalkorDBStore[FalkorDB]
        ObsidianStore[Obsidian Vault]
    end
    
    GraphStorageProvider --> PostgresStore
    GraphStorageProvider --> SQLiteStore
    GraphStorageProvider --> FalkorDBStore
    GraphStorageProvider --> ObsidianStore

资料来源：src/genesys_memory/storage/base.py

导出模块

模型层通过 __init__.py 统一导出核心类：

from genesys_memory.models import (
    MemoryStatus,
    EdgeType,
    ReactivationPattern,
    MemoryNode,
    MemoryEdge,
)

资料来源：src/genesys_memory/models/__init__.py:1-9

总结

Genesys 的数据模型以节点-边的图结构为核心，通过：

1. MemoryNode 存储记忆内容、状态、评分和时间信息
2. MemoryEdge 表达记忆间的语义和因果关系
3. MemoryStatus 管理记忆的生命周期状态转换
4. 评分机制 决定记忆的生存或遗忘
5. 权限系统 支持个人和组织级别的记忆管理

这种设计使 Genesys 能够在提供向量检索能力的同时，维持对记忆之间关系的深层理解，实现更智能的记忆管理。

概述

评分引擎（Scoring Engine）是 Genesys 记忆系统的核心组件，负责对每条记忆进行多维度评分，以决定其生命周期状态、保留优先级和遗忘时机。评分引擎采用乘积公式计算综合得分，确保持续活跃、高度连接、频繁复活的记忆得以保留，而孤立或长期未访问的记忆则逐渐衰减直至被剪枝。

资料来源：README.md

评分公式

三力乘积模型

每条记忆的最终得分由三个因子相乘得出：

decay_score = relevance × connectivity × reactivation

资料来源：README.md

乘积公式的设计逻辑

由于采用乘法模型，记忆必须同时在三个维度上都有得分才能保持高分：

• 高连接但从未被访问：仍然会衰减
• 频繁回忆但孤立无依：仍然会消失
• 最近创建但无关联：也会逐渐淡出

这种设计确保只有真正重要的记忆才能长期留存。

资料来源：README.md

记忆生命周期

评分引擎驱动记忆在以下状态之间转换：

graph TD
    A[STORE 存储] --> B[ACTIVE 活跃]
    B --> C[DORMANT 休眠]
    C --> D[FADING 消逝]
    D --> E[PRUNED 剪枝]
    B -->|reactivation 复活| B
    C -->|reactivation 复活| B
    E -->|仅当 score=0, orphan, not pinned| 结束

资料来源：README.md

评分相关数据模型

MemoryNode 核心字段

记忆节点模型 MemoryNode 包含以下与评分直接相关的字段：

class MemoryNode(BaseModel):
    id: uuid.UUID
    status: MemoryStatus  # 生命周期状态
    
    # 评分计算因子
    decay_score: float = 1.0      # 综合衰减得分
    causal_weight: int = 0        # 因果权重（连接性）
    reactivation_count: int = 0   # 复活次数
    
    # 时间相关
    created_at: datetime
    last_accessed_at: datetime
    last_reactivated_at: datetime
    
    # 稳定性（成功检索后增加，间隔重复算法）
    stability: float = 1.0
    
    # 固定与核心记忆
    pinned: bool = False          # 是否固定（永不遗忘）
    promotion_reason: str | None  # 晋升原因
    
    # 复活历史
    reactivation_timestamps: list[datetime]

资料来源：src/genesys_memory/models/node.py:1-50

复活模式枚举

class ReactivationPattern(Enum):
    SINGLE       # 单次激活
    BURST        # 爆发式激活
    SPACED       # 间隔重复激活
    DECAYING     # 衰减模式

资料来源：src/genesys_memory/models/node.py

引擎配置

评分引擎的行为通过 engine/config.py 进行配置，所有阈值均为环境变量可配置，禁止在引擎文件中硬编码魔法数字。

配置项管理

注意：具体的配置参数值和阈值定义在 engine/config.py 中，可通过环境变量覆盖默认行为。

资料来源：CONTRIBUTING.md

LLM 驱动的因果关系发现

评分引擎集成了 LLM 提供器来自动识别记忆之间的因果关系，这直接影响 connectivity 因子的计算。

因果关系发现流程

sequenceDiagram
    participant U as 用户记忆
    participant LLM as LLM Provider
    participant G as 图存储
    
    U->>LLM: 发现因果关系 (new_memory, existing_memories)
    LLM->>LLM: 生成提示词
    LLM->>LLM: 请求 LLM 分析
    LLM-->>G: 返回关系列表 (target_id, edge_type, confidence)
    
    loop 对于每个关系
        G->>G: 创建 MemoryEdge
        G->>G: 更新 causal_weight
    end

边类型定义

async def discover_causal_relationships(
    self,
    new_memory: str,
    existing_memories: list[tuple[str, str]],
) -> list[tuple[str, EdgeType, float, str | None]]:
    """
    分析新记忆与已有记忆之间的因果关系。
    仅返回置信度 > 0.6 的关系。
    """
    # ... 实现逻辑

资料来源：src/genesys_memory/engine/llm_provider.py

核心记忆晋升机制

评分引擎还负责评估记忆是否应晋升为核心记忆（Core Memory）。核心记忆具有以下特性：

• 自动固定：晋升后自动设置为 pinned=True
• 永不剪枝：即使得分归零也不会被删除
• 高优先级检索：在检索结果中优先返回

from genesys_memory.core_memory.promoter import evaluate_core_promotion

# 评估晋升资格
promotion_result = await evaluate_core_promotion(memory_node)

MCP 工具接口

评分引擎可通过 MCP 协议调用以下相关工具：

资料来源：src/genesys_memory/mcp/tools.py

遗忘与剪枝策略

遗忘触发条件

记忆被剪枝（Pruned）需要同时满足以下条件：

# 伪代码示例
if decay_score == 0 and is_orphan and not pinned:
    await prune_memory(memory_id)

资料来源：README.md

间隔重复与稳定性

评分引擎采用间隔重复算法调整记忆的 stability 参数：

• 成功检索 → stability 增加
• 检索失败 → stability 减少
• stability 影响 decay_score 的计算

这模拟了人类记忆的遗忘曲线，使重要记忆得到强化。

资料来源：src/genesys_memory/models/node.py

检索中的评分应用

混合检索流程

评分引擎在 memory_recall 操作中发挥作用：

graph LR
    A[查询] --> B[向量搜索]
    A --> C[关键词搜索]
    B --> D[图传播激活]
    C --> D
    D --> E[综合评分排序]
    E --> F[返回 Top-K 结果]

1. 向量搜索：基于语义相似度检索
2. 关键词搜索：精确匹配关键词
3. 图传播激活：从初始节点沿因果边传播激活值
4. 综合评分排序：结合原始得分和检索相关性

检索参数

Tool(name="memory_recall", description="Recall memories using hybrid search...", inputSchema={
    "type": "object",
    "required": ["query"],
    "properties": {
        "query": {"type": "string"},
        "k": {"type": "integer", "default": 10},
        "max_results": {"type": "integer"},
    },
})

资料来源：src/genesys_memory/server.py

性能基准

评分引擎在 LoCoMo 长对话记忆基准测试中的表现：

测试配置：Answer model: gpt-4o-mini | Judge model: gpt-4o-mini | Retrieval k=20

对比基准：Mem0 (67.1%), Zep (75.1%)

资料来源：README.md

开发指南

添加新评分逻辑

在添加新的评分逻辑时，请遵循以下规范：

1. 配置外置：所有阈值必须放在 engine/config.py 中
2. 环境变量支持：通过环境变量覆盖默认配置
3. 测试覆盖：在 tests/ 目录添加对应的测试用例
4. 严格模式检查：mypy src/genesys_memory --ignore-missing-imports 必须通过

# 运行测试
pytest tests/ -v

# 类型检查
mypy src/genesys_memory --ignore-missing-imports

# 代码检查
ruff check src/

资料来源：CONTRIBUTING.md

关键模块耦合

评分引擎与以下模块紧密耦合，修改时需运行完整测试套件：

修改任一模块后，必须运行 pytest tests/ -v 确保无回归。

资料来源：CONTRIBUTING.md

总结

评分引擎是 Genesys 记忆系统的决策中心，通过乘积公式将相关性、连接性和再激活三个维度统一量化，驱动记忆的整个生命周期管理。其设计核心思想是：只有同时满足"持续相关"、"高度连接"、"频繁使用"三个条件的记忆才值得长期保留。

这种设计使得 AI 能够在有限的记忆空间中保留最有价值的信息，模拟人类记忆的优先级管理机制，同时通过核心记忆机制确保关键信息永不丢失。

概述

记忆生命周期是 Genesys 记忆引擎的核心管理机制，负责记忆从创建到消亡的完整过程。该系统通过三层评分公式（相关性 × 连接性 × 再激活）对每条记忆进行动态评分，并驱动记忆在不同的生命周期状态之间转换。

核心设计目标：

• 智能遗忘不重要或过时的记忆
• 通过因果图保留重要记忆的结构完整性
• 支持核心记忆的自动晋升与保护

资料来源：README.md

生命周期状态

记忆在系统中经历以下五种状态：

资料来源：src/genesys_memory/models/enums.py

状态转换图

graph TD
    NEW[新记忆创建] --> TAGGED[TAGGED 标签态]
    TAGGED -->|形成因果链接| ACTIVE[ACTIVE 活跃态]
    TAGGED -->|24h无链接| PRUNED[PRUNED 已删除]
    
    ACTIVE -->|评分下降| DORMANT[DORMANT 休眠态]
    ACTIVE -->|高频召回| REACTIVATE[再激活]
    REACTIVATE --> ACTIVE
    
    DORMANT -->|再次召回| ACTIVE
    DORMANT -->|长期无召回| FADING[FADING 消逝态]
    
    FADING -->|评分归零| PRUNED
    FADING -->|被固定| ACTIVE
    
    ACTIVE -->|核心晋升| CORE[核心记忆]
    CORE -->|永不删除| PERSIST[永久保留]
    
    style CORE fill:#90EE90
    style PRUNED fill:#FFB6C1

评分引擎

三力评分公式

记忆评分由三个因子相乘得出：

decay_score = relevance × connectivity × reactivation

乘法特性： 三个因子必须同时较高，记忆才能存活。仅在一两个方面表现良好不足以保证记忆存活。

资料来源：README.md

评分组件

状态转换引擎

Tagged → Active 转换

当新记忆形成因果链接时，从 TAGGED 状态晋升为 ACTIVE：

async def evaluate_transitions(graph, embeddings, llm, context_embedding, context_entities):
    tagged_nodes = await graph.get_nodes_by_status(MemoryStatus.TAGGED)
    for node in tagged_nodes:
        if not await graph.is_orphan(str(node.id)):
            await graph.update_node(str(node.id), {"status": MemoryStatus.ACTIVE})

关键逻辑：

• 检查节点是否为孤立节点（orphan）
• 若存在因果边连接，则触发状态变更
• 变更原因记录为："consolidation signal: edge formed"

资料来源：src/genesys_memory/engine/transitions.py:14-24

Tagged 自动过期

24小时内无因果链接的 TAGGED 记忆自动过期删除：

age_hours = (datetime.now(timezone.utc) - node.created_at).total_seconds() / 3600
if age_hours > 24:
    # 标记为过期

资料来源：src/genesys_memory/engine/transitions.py

转换评估流程

graph TD
    START[开始评估] --> GET_STATS[获取图统计]
    GET_STATS --> GET_TAGGED[获取所有 TAGGED 节点]
    GET_TAGGED --> IS_ORPHAN{是孤立节点?}
    
    IS_ORPHAN -->|是| CHECK_AGE{超过24h?}
    IS_ORPHAN -->|否| PROMOTE[晋升为 ACTIVE]
    
    CHECK_AGE -->|是| EXPIRE[过期处理]
    CHECK_AGE -->|否| WAIT[等待下次评估]
    
    PROMOTE --> RECORD[记录转换原因]
    EXPIRE --> RECORD
    RECORD --> DONE[评估完成]

再激活机制

再激活模式

记忆节点记录其再激活历史，支持多种模式：

资料来源：src/genesys_memory/models/enums.py

再激活属性

class MemoryNode:
    reactivation_count: int = 0          # 召回次数
    reactivation_pattern: ReactivationPattern  # 召回模式
    last_reactivated_at: datetime         # 最后召回时间
    reactivation_timestamps: list[datetime]  # 历史时间戳

再激活评分提升

每次召回都会提升记忆的 decay_score：

graph LR
    RECALL[召回请求] --> CHECK{检查记忆状态}
    CHECK -->|ACTIVE| BOOST[boost decay_score]
    CHECK -->|DORMANT| RESTORE[恢复为 ACTIVE]
    CHECK -->|FADING| RESCUE{是否固定?}
    
    RESTORE --> UPDATE_TS[更新再激活时间戳]
    BOOST --> UPDATE_TS
    
    RESCUE -->|是| KEEP[保留记忆]
    RESCUE -->|否| FADING2[继续消逝流程]

遗忘机制

遗忘条件

记忆被遗忘（删除）需要满足以下全部条件：

async def forget_memories(graph):
    for memory in low_score_memories:
        if memory.pinned:
            continue
        if not await graph.is_orphan(memory.id):
            continue
        if memory.decay_score > 0:
            continue
        await graph.delete_node(memory.id)

资料来源：src/genesys_memory/engine/forgetting.py

遗忘流程图

graph TD
    START[遗忘评估] --> SCAN[扫描低评分记忆]
    SCAN --> LOOP{遍历记忆}
    
    LOOP -->|固定记忆| SKIP[跳过]
    LOOP -->|孤立节点| ORPHAN{有因果边?}
    
    ORPHAN -->|有边| KEEP[保留]
    ORPHAN -->|无边| CHECK_SCORE{评分=0?}
    
    CHECK_SCORE -->|是| DELETE[删除记忆]
    CHECK_SCORE -->|否| KEEP
    
    SKIP --> NEXT[下一条]
    KEEP --> NEXT
    DELETE --> NEXT
    
    NEXT --> LOOP

核心记忆系统

核心记忆特性

核心记忆是结构上重要的记忆，具有以下特性：

• 自动固定：晋升为核心时自动设置 pinned = true
• 永不删除：即使评分归零也不会被遗忘
• 分类管理：支持按类别配置自动晋升规则

晋升评估

async def evaluate_core_promotion(memory, category_rules):
    if memory.category in category_rules.auto:
        await promote_to_core(memory, reason="category_auto")
    elif memory.causal_weight > threshold:
        await promote_to_core(memory, reason="high_connectivity")

资料来源：src/genesys_memory/core_memory/promoter.py

核心记忆配置

晋升流程

graph TD
    EVAL[晋升评估] --> CHECK_CATEGORY{检查类别规则}
    
    CHECK_CATEGORY -->|auto 列表| AUTO[自动晋升]
    CHECK_CATEGORY -->|approval 列表| NEED_APPROVAL[需要审批]
    CHECK_CATEGORY -->|excluded 列表| BLOCK[阻止晋升]
    CHECK_CATEGORY -->|无匹配| CHECK_CONNECTIVITY{高连接性?}
    
    CHECK_CONNECTIVITY -->|是| AUTO
    CHECK_CONNECTIVITY -->|否| KEEP[保持当前状态]
    
    AUTO --> SET_PIN[设置 pinned=true]
    NEED_APPROVAL --> AWAIT[等待用户确认]
    BLOCK --> KEEP
    
    AWAIT -->|批准| SET_PIN
    AWAIT -->|拒绝| KEEP
    
    SET_PIN --> LOG[记录晋升原因]
    LOG --> DONE[完成]

记忆节点模型

数据结构

class MemoryNode(BaseModel):
    id: uuid.UUID                    # 唯一标识
    status: MemoryStatus            # 当前状态
    content_summary: str            # 内容摘要 (≤200字符)
    content_full: str | None        # 完整内容
    embedding: list[float] | None  # 向量嵌入
    
    # 时间戳
    created_at: datetime            # 创建时间
    last_accessed_at: datetime      # 最后访问
    last_reactivated_at: datetime   # 最后召回
    
    # 评分因子
    decay_score: float = 1.0        # 衰减评分
    causal_weight: int = 0          # 因果权重
    reactivation_count: int = 0     # 召回次数
    irrelevance_counter: int = 0    # 无效计数
    
    # 分类与稳定性
    category: str | None            # 类别
    stability: float = 1.0          # 稳定性
    pinned: bool = False            # 是否固定

资料来源：src/genesys_memory/models/node.py

稳定性机制

稳定性（Stability）随成功召回而增加，模拟间隔重复学习：

• 每次成功检索：stability += 0.1
• 长期未召回：stability -= 0.05
• 高稳定性记忆更难被删除

生命周期管理 API

MCP 工具

召回工作流

sequenceDiagram
    Client->>Genesys: memory_recall(query)
    Genesys->>Graph: 查找相关节点
    Graph-->>Genesys: 返回候选记忆
    Genesys->>Scoring: 计算评分
    Scoring-->>Genesys: 评分结果
    Genesys->>Transitions: 评估状态转换
    Transitions-->>Genesys: 更新状态
    Genesys->>User: 返回记忆列表

配置选项

环境变量

引擎阈值

引擎阈值定义在 engine/config.py 中，可通过环境变量配置：

• 遗忘阈值
• 晋升阈值
• 休眠阈值
• 消逝阈值

总结

记忆生命周期是 Genesys 实现智能遗忘的核心机制：

1. 三层评分 保证记忆必须同时满足相关性、连接性和再激活三个条件才能存活
2. 五种状态 提供精细的记忆管理粒度
3. 因果图 通过链接关系保护重要记忆不被遗忘
4. 核心记忆 为结构关键记忆提供永久保护
5. 固定机制 允许用户手动保护特定记忆

该系统确保 AI 记忆既不会无限膨胀，也不会遗忘重要信息，实现了记忆容量与信息价值的动态平衡。

概述

Genesys 的 MCP 工具集是系统与外部 AI 客户端（如 Claude Desktop、Claude Code）交互的核心接口层。该工具集通过 MCP（Model Context Protocol）协议暴露一组标准化的内存操作工具，使 AI 代理能够存储、检索、遍历和管理记忆节点。

MCP 工具集采用标准化的事件驱动架构，所有工具均通过统一的 call_tool 分发器进行路由。工具层与底层存储提供者（GraphStorageProvider、CacheProvider、EmbeddingProvider）解耦，支持多种存储后端。资料来源：server.py:1-50

架构设计

工具调用流程

graph TD
    A[MCP 客户端请求] --> B[call_tool 分发器]
    B --> C{工具名称校验}
    C -->|有效| D[参数验证]
    C -->|无效| E[返回错误]
    D --> F[权限检查]
    F -->|通过| G[执行业务逻辑]
    F -->|失败| H[抛出 PermissionError]
    G --> I[调用存储提供者]
    I --> J[返回 TextContent]
    J --> K[格式化响应]
    K --> L[返回给 MCP 客户端]

核心组件

工具清单

存储与检索类工具

#### memory_store

存储新的记忆节点，可选择性地关联到现有记忆。

资料来源：server.py:50

#### memory_recall

基于自然语言查询召回记忆，采用混合搜索策略（向量搜索 + 关键词 + 图传播激活）。

资料来源：server.py:52

#### memory_search

基于过滤条件的向量搜索，支持按状态、类别、日期或实体筛选。

资料来源：server.py:54

图遍历类工具

#### memory_traverse

从指定节点开始遍历记忆因果图。

资料来源：server.py:56

#### memory_explain

解释记忆节点的分数构成和因果链。

资料来源：server.py:58

生命周期管理工具

#### pin_memory

将记忆固定为核心记忆，防止被遗忘机制删除。

#### unpin_memory

取消固定记忆，重新评估其核心资格。

资料来源：server.py:60-62

#### delete_memory

永久删除记忆节点及其所有关联边。

核心记忆管理工具

#### list_core_memories

列出所有核心记忆，可按类别过滤。

资料来源：server.py:64

#### set_core_preferences

配置核心记忆类别偏好。

组织协作工具

#### promote_to_org

将私有记忆提升为组织可见性。

资料来源：server.py:42-46

统计与监控工具

#### memory_stats

获取图统计信息，包括节点总数、边总数、活跃节点数等。

无参数要求。

资料来源：server.py:66

工具分发机制

分发表结构

工具分发通过 _TOOL_DISPATCH 字典实现，每个条目包含三元素元组：

_TOOL_DISPATCH = {
    "tool_name": (handler, required_args, optional_args_with_defaults)
}

资料来源：server.py:35-47

调用流程

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as MCP Server
    participant Dispatch as 分发器
    participant Tools as 工具实现
    participant Storage as 存储提供者

    Client->>Server: call_tool("memory_store", {...})
    Server->>Dispatch: 查找工具处理器
    Dispatch->>Dispatch: 验证必需参数
    Dispatch->>Dispatch: 合并默认参数
    Dispatch->>Tools: 调用 handler(**params)
    Tools->>Storage: 读写数据
    Storage-->>Tools: 返回结果
    Tools-->>Server: TextContent 列表
    Server-->>Client: 格式化响应

权限验证

工具执行前需进行权限检查，核心逻辑位于 mcp/tools.py：

def _caller_owns_node(node: MemoryNode) -> bool:
    uid = _caller_uid()
    if uid is None:
        raise PermissionError("current_user_id not set")
    role = current_user_role.get(None)
    if role == "admin" and node.org_id in current_org_ids:
        return True
    return node.original_user_id == uid

资料来源：mcp/tools.py:26-40

记忆节点数据模型

MemoryNode 核心字段

资料来源：models/node.py:12-45

MCP 协议集成

服务端点

资料来源：README.md

工具注册

工具通过 @app.list_tools() 和 @app.call_tool() 装饰器注册：

@app.list_tools()
async def list_tools() -> list[Tool]:
    return _TOOL_SCHEMAS

@app.call_tool()
async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
    if name not in _TOOL_DISPATCH:
        return [TextContent(type="text", text=f"Unknown tool: {name}")]
    # 处理工具调用...

资料来源：server.py:19-26

配置选项

环境变量

资料来源：README.md

错误处理

权限错误

if uid is None:
    raise PermissionError("current_user_id not set — cannot verify ownership")

未知工具

if name not in _TOOL_DISPATCH:
    return [TextContent(type="text", text=f"Unknown tool: {name}")]

返回格式

所有工具返回 list[TextContent]，其中 TextContent 包含 type 和 text 字段。

使用示例

Claude Desktop 配置

{
  "mcpServers": {
    "genesys": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Claude Code 配置

claude mcp add --transport http genesys http://localhost:8000/mcp

启动 MCP 服务器

uvicorn genesys.api:app --port 8000

或使用轻量级 stdio 服务器：

python -m genesys_memory

资料来源：CONTRIBUTING.md

扩展开发

如需添加新工具，需完成以下步骤：

1. 在 mcp/tools.py 中实现工具函数
2. 在 _TOOL_SCHEMAS 中定义工具元数据（名称、描述、输入模式）
3. 在 _TOOL_DISPATCH 中注册工具（handler、必需参数、可选参数及默认值）
4. 添加对应的单元测试

# 示例：添加新工具
_TOOL_DISPATCH["new_tool"] = (
    tools.new_tool,
    ["required_param"],
    {"optional_param": "default_value"}
)

概述

Genesys 的存储后端系统是一个模块化的存储抽象层，为记忆引擎提供统一的数据持久化和检索接口。该设计允许用户根据不同场景选择合适的存储方案，同时保持核心记忆评分引擎的独立性。

存储后端系统的核心职责包括：

• 记忆节点管理：创建、读取、更新、删除记忆节点
• 因果图维护：管理记忆之间的因果边关系
• 向量嵌入存储：持久化记忆的语义向量表示
• 全文内容存储：保存记忆的完整内容和摘要
• 元数据管理：维护访问时间、评分、状态等生命周期信息

资料来源：README.md

概述

Genesys 的检索系统是整个记忆引擎的核心组件，负责从因果图中高效召回相关记忆。该系统采用混合检索策略，结合向量搜索、关键词匹配和图传播激活（graph spreading activation）三种技术，实现精准的记忆召回。 资料来源：README.md

检索系统的设计目标是解决"扁平记忆无法扩展"的问题。与传统的向量存储不同，Genesys 不仅提供回忆能力，还通过因果图理解记忆之间的关联，使第 500 条记忆不会被第 5 条记忆埋没。 资料来源：README.md

架构设计

混合检索流程

graph TD
    A[用户查询] --> B[向量嵌入]
    A --> C[关键词提取]
    B --> D[向量相似度搜索]
    C --> E[关键词匹配]
    D --> F[候选记忆集合]
    E --> F
    F --> G[图传播激活]
    G --> H[混合评分排序]
    H --> I[最终结果]
    
    J[因果图] --> G

检索系统的工作流程包含四个主要阶段：

1. 查询处理阶段：将自然语言查询转换为向量嵌入，同时提取关键词
2. 候选生成阶段：通过向量搜索和关键词匹配生成候选记忆集合
3. 图传播激活阶段：在因果图上执行 spreading activation 算法，增强关联记忆的权重
4. 混合排序阶段：综合向量相似度、关键词匹配度和图关联度进行最终排序

核心组件

MCP 检索工具

Genesys 通过 MCP（Model Context Protocol）协议暴露检索能力，提供五个核心工具。 资料来源：server.py:1-80

memory_recall — 混合召回

memory_recall 是最主要的检索工具，执行向量搜索、关键词搜索和图传播激活的混合检索。

Tool(name="memory_recall", description="Recall memories using hybrid search (vector + keyword + graph spreading activation).", inputSchema={
    "type": "object", "required": ["query"],
    "properties": {
        "query": {"type": "string"},
        "k": {"type": "integer", "default": 10},
        "max_results": {"type": "integer"},
    },
})

参数说明：

memory_search — 过滤搜索

memory_search 提供基于元数据过滤的向量搜索能力。

Tool(name="memory_search", description="Search memories with filters (status, category, date, or entity).", inputSchema={
    "type": "object", "required": ["query"],
    "properties": {
        "query": {"type": "string"},
        "filters": {"type": "object"},
        "k": {"type": "integer", "default": 10},
    },
})

支持的过滤字段：

• status：记忆状态（ACTIVE、DORMANT、FADING 等）
• category：记忆类别
• date_range：日期范围
• entity：实体引用

memory_traverse — 图遍历

memory_traverse 用于从指定节点出发，在因果图上进行深度遍历。

Tool(name="memory_traverse", description="Traverse the memory graph from a starting node.", inputSchema={
    "type": "object", "required": ["node_id"],
    "properties": {
        "node_id": {"type": "string"},
        "depth": {"type": "integer", "default": 2},
        "edge_types": {"type": "array", "items": {"type": "string"}},
    },
})

memory_explain — 评分解释

memory_explain 解释特定记忆的评分构成，帮助理解记忆为何被召回。

Tool(name="memory_explain", description="Explain a memory's score breakdown.", inputSchema={
    "type": "object", "required": ["node_id"],
    "properties": {"node_id": {"type": "string"}},
})

memory_stats — 统计信息

memory_stats 获取图的统计信息，用于监控和调试。

Tool(name="memory_stats", description="Get graph statistics.", inputSchema={
    "type": "object", "properties": {},
})

向量嵌入系统

嵌入提供者配置

Genesys 支持两种嵌入提供者，通过 GENESYS_EMBEDDER 环境变量配置。 资料来源：README.md

本地嵌入模式无需任何 API 密钥，适合完全离线的使用场景：

pip install 'genesys-memory[obsidian,local]'

GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
# 无需 OPENAI_API_KEY

嵌入生成时机

在创建新记忆时，系统会自动生成嵌入向量：

# 资料来源：mcp/tools.py
embedding = await self.embeddings.embed(content) if self.embeddings else []

嵌入向量用于两个目的：

1. 向量相似度搜索：找到语义上相似的历史记忆
2. 自动关联：将新记忆与相似记忆自动建立连接边

因果关系识别

LLM 驱动的因果分析

当创建新记忆时，系统使用 LLM 分析新记忆与现有记忆之间的因果关系。 资料来源：llm_provider.py

prompt = (
    "Given a new memory and a list of existing memories, identify causal relationships.\n\n"
    f"New memory: {new_memory}\n\nExisting memories:\n{mem_lines}\n\n"
    "For each causal relationship found, specify:\n"
    "- target_id: the ID of the existing memory\n"
    '- edge_type: one of "caused_by", "supports", "derived_from"\n'
    "- confidence: 0.0 to 1.0\n"
    "- reason: brief explanation of why this relationship exists\n\n"
    "Only include relationships with confidence > 0.6.\n"
    "Respond with ONLY a JSON array of objects, no other text."
)

边类型定义

置信度阈值

只有置信度超过 0.6 的因果关系才会被采纳：

if confidence > 0.6:
    results.append((item["target_id"], edge_type, confidence, item.get("reason")))

自动关联机制

相似记忆自动链接

新记忆创建时，系统会自动将其与语义相似的现有记忆关联。 资料来源：mcp/tools.py

# 向量搜索找到相似记忆
similar = await self.graph.vector_search(embedding, k=4, org_ids=org_ids)

for other_node, score in similar:
    if score < 0.3:  # 相似度阈值
        continue

关键参数：

组织边界规则

当记忆可见性为 ORG（组织级别）时，系统会强制执行组织边界规则：

# Org boundary rule: org nodes only link to same-org nodes
if vis == Visibility.ORG:
    if other_node.visibility != Visibility.ORG or other_node.org_id != org_id:
        continue

自动创建的边

自动关联创建的边使用 EdgeType.RELATED_TO 类型，并记录相似度分数和创建原因：

edge = MemoryEdge(
    source_id=node.id,
    target_id=other_node.id,
    type=EdgeType.RELATED_TO,
    weight=round(score, 4),
    reason=f"cosine similarity {score:.3f}",
    created_by="auto_link",
)

记忆状态与生命周期

检索系统与记忆的生命周期紧密集成。记忆在系统中经历以下状态转换： 资料来源：README.md

graph LR
    A[STORE] --> B[ACTIVE]
    B --> C[DORMANT]
    C --> D[FADING]
    D --> E[PRUNED]
    B --> F[reactivation]
    F --> B

评分公式

记忆被三个因素共同评分：

decay_score = relevance × connectivity × reactivation

由于公式是乘法形式，记忆必须在三个维度都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁召回但没有因果边的孤立记忆也会淡化。

检索配置选项

环境变量配置

不同存储后端的检索

Genesys 的检索系统与存储后端解耦，可配合多种后端使用： 资料来源：README.md

性能与基准

在 LoCoMo 长对话记忆基准测试中（1540 个问题，10 个对话），Genesys 的检索系统表现如下： 资料来源：README.md

作为对比，同一基准测试中 Mem0 得分为 67.1%，Zep 得分为 75.1%。检索模型使用 gpt-4o-mini，评判模型同样使用 gpt-4o-mini，检索 k=20。

代码组织

src/genesys_memory/
├── retrieval/
│   └── embedding.py          # 向量嵌入生成
├── engine/
│   ├── llm_provider.py       # LLM 因果关系识别
│   ├── consolidation.py      # 记忆整合
│   └── config.py             # 引擎阈值配置
└── mcp/
    └── tools.py              # MCP 工具实现

开发指南

引擎阈值配置在 engine/config.py 中，应通过环境变量配置，避免在引擎文件中硬编码魔法数字。 资料来源：CONTRIBUTING.md

测试检索功能

# 运行所有单元测试
pytest tests/ -v

# 带覆盖率
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing

测试文件位于 tests/ 目录，使用 pytest-asyncio（auto 模式）。新增引擎逻辑时，应在相应测试文件中添加对应的测试用例。

Pitfall Log / 踩坑日志

项目：rishimeka/genesys

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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

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