# https://github.com/rishimeka/genesys 项目说明书
生成时间：2026-05-14 08:09:06 UTC
## 目录
- [项目介绍](#page-introduction)
- [安装指南](#page-installation)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [数据模型](#page-data-models)
- [评分引擎](#page-scoring-engine)
- [记忆生命周期](#page-memory-lifecycle)
- [MCP 工具集](#page-mcp-tools)
- [存储后端实现](#page-storage-backends)
- [检索系统](#page-retrieval-system)
## 项目介绍
### 相关页面
相关主题：[系统架构](#page-architecture), [快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)
- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)
- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)
# 项目介绍
## 概述
Genesys 是一个面向 AI Agent 的**记忆评分引擎、因果图谱和生命周期管理器**。它解决了传统向量存储记忆方案的局限性——虽然能提供检索能力，但缺乏对记忆之间关系的理解。Genesys 通过乘法评分公式（相关性 × 连接性 × 再激活）对每条记忆进行评分，构建因果图谱实现关系推理，并主动遗忘已变得不相关的记忆。资料来源：[README.md]()
Genesys 的核心理念是：记忆应该像人类一样，具有生命周期、会衰减、会被强化、会被遗忘，而非简单地堆积在向量数据库中。资料来源：[README.md]()
## 核心架构
### 系统定位
Genesys 位于 LLM 与记忆存储层之间，作为**智能记忆层**运行。它不直接存储数据，而是协调多种存储后端，并通过 MCP（Model Context Protocol）协议与 AI 客户端原生集成。资料来源：[README.md]()
```mermaid
graph TD
A[AI 客户端
Claude/Codellm] -->|MCP 协议| B[Genesys
记忆引擎]
B -->|评分/图谱/生命周期| C{存储后端}
C -->|向量+图| D[Postgres + pgvector]
C -->|本地优先| E[Obsidian Vault]
C -->|图数据库| F[FalkorDB]
C -->|内存模式| G[SQLite]
```
### 核心组件
| 组件 | 职责 | 源码位置 |
|------|------|----------|
| **评分引擎** | 计算记忆的衰减分数（相关性×连接性×再激活） | `engine/scoring.py` |
| **因果图谱** | 管理记忆节点和边，执行图遍历和扩展激活 | `models/node.py` |
| **生命周期管理器** | 状态转移：ACTIVE → DORMANT → FADING → PRUNED | `engine/transitions.py` |
| **MCP 服务器** | 提供标准化工具接口，连接 AI 客户端 | `server.py` |
| **存储抽象层** | 统一接口支持多种后端（Postgres/Obsidian/FalkorDB） | `storage/base.py` |
## 记忆评分机制
### 评分公式
Genesys 采用**三力乘法模型**对记忆进行评分：
```
decay_score = relevance × connectivity × reactivation
```
资料来源：[README.md]()
| 维度 | 含义 | 衰减行为 |
|------|------|----------|
| **Relevance（相关性）** | 记忆与当前上下文的相关程度 | 随时间自然衰减，除非被强化 |
| **Connectivity（连接性）** | 记忆在因果图中的链接数量 | 链接越多，存活能力越强（Hub 记忆） |
| **Reactivation（再激活）** | 记忆被回忆的频率 | 频繁访问的记忆获得boost |
由于采用乘法公式，记忆必须同时在**三个维度**上都有得分才能存活。高度连接但从未被访问的记忆仍会衰减；频繁被回忆但没有因果链接的"孤岛"记忆同样会消失。资料来源：[README.md]()
### 评分源代码逻辑
```python
# 来自 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]()
## 记忆生命周期
### 状态转移图
```mermaid
graph TD
STORE[STORE
新建记忆] -->|评分>阈值| ACTIVE[ACTIVE
活跃]
ACTIVE -->|长期低分| DORMANT[DORMANT
休眠]
DORMANT -->|再次回忆| ACTIVE
DORMANT -->|持续衰减| FADING[FADING
消退]
FADING -->|重新激活| ACTIVE
FADING -->|评分归零且无链接| PRUNED[PRUNED
删除]
STORE -->|tagged状态| TAGGED[TAGGED
已标记]
TAGGED -->|形成边连接| ACTIVE
TAGGED -->|24h无连接| PRUNED
ACTIVE -->|promote| CORE[CORE
核心记忆
永不删除]
```
资料来源：[README.md]()
### 状态详情
| 状态 | 说明 | 转移条件 |
|------|------|----------|
| **STORE** | 初始创建的记忆 | 自动转移至 ACTIVE 或 TAGGED |
| **ACTIVE** | 正常参与检索的记忆 | 评分下降时转入 DORMANT |
| **DORMANT** | 暂时搁置但未删除 | 被召回时转回 ACTIVE |
| **FADING** | 即将被遗忘 | 可被 reactivation 救回，或进入 PRUNED |
| **CORE** | 核心记忆，结构重要性高 | 自动 pin，永不删除 |
| **PRUNED** | 已删除的记忆 | 不可逆 |
### Tagged → Active 转移逻辑
```python
# 来自 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 支持多种存储后端，可根据使用场景灵活选择：
| 后端 | 安装方式 | 适用场景 | 特点 |
|------|----------|----------|------|
| **memory** | 内置无需安装 | 快速尝鲜 | 零依赖，纯内存存储 |
| **postgres** | `pip install genesys-memory[postgres]` | 生产环境 | 持久化、可扩展、向量搜索 |
| **Obsidian** | `pip install genesys-memory[obsidian]` | 本地知识库 | Markdown 文件作为记忆节点，wikilinks 自动转为因果边 |
| **FalkorDB** | `pip install genesys-memory[falkordb]` | 图数据库场景 | 原生图遍历，Redis 底层 |
| **自定义** | 实现 `GraphStorageProvider` 接口 | 特殊需求 | 完全可插拔 |
资料来源：[README.md]()
### Obsidian Vault 集成
Obsidian 后端特别适合个人知识管理场景：
- Markdown 文件自动转为记忆节点
- `[[wikilinks]]` 自动转为因果边
- SQLite 侧car（`.genesys/index.db`）处理索引
- 文件监视器增量重索引
资料来源：[README.md]()
### 完全本地模式（无 API Key）
```bash
pip install 'genesys-memory[obsidian,local]'
```
```env
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）提供标准化工具接口：
| 工具名称 | 功能描述 | 参数 |
|----------|----------|------|
| `memory_store` | 存储新记忆，可选链接相关记忆 | `content`, `related_to?`, `source_session?` |
| `memory_recall` | 混合检索（向量+关键词+图扩散激活） | `query`, `k?`, `max_results?` |
| `memory_search` | 带过滤条件的向量搜索 | `query`, `filters?`, `k?` |
| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id`, `depth?`, `edge_types?` |
| `memory_explain` | 解释记忆的评分构成 | `node_id` |
| `memory_stats` | 获取记忆系统统计信息 | 无 |
| `pin_memory` | 将记忆固定为核心，永不遗忘 | `node_id` |
| `unpin_memory` | 取消固定，重新评估核心资格 | `node_id` |
| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |
| `list_core_memories` | 列出所有核心记忆 | `category?` |
| `set_core_preferences` | 配置核心记忆类别偏好 | `auto?`, `approval?`, `excluded?` |
资料来源：[src/genesys_memory/server.py:1-80]()
### 记忆存储工具实现
```python
# 来自 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）
当大量情景记忆积累后，系统会自动将其合并为语义记忆：
```python
# 来自 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](https://arxiv.org/abs/2402.06397) 长对话记忆基准上进行了测试（1540 个问题，10 个对话）：
| 类别 | J-Score |
|------|---------|
| Single-hop（单跳） | 94.3% |
| Temporal（时序） | 87.5% |
| Multi-hop（多跳） | 69.8% |
| Open-domain（开放域） | 91.7% |
| **总体** | **89.9%** |
对比基线：Mem0 67.1%，Zep 75.1%
资料来源：[README.md]()
## 快速开始
### 环境要求
- Python 3.11+
- 可选：OpenAI API Key（用于嵌入生成，非必须）
- 可选：Anthropic API Key（用于 LLM 记忆处理）
### 安装
```bash
pip install genesys-memory
```
### 启动服务器
```bash
# 方式一：使用内存后端（零配置）
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` 中添加：
```json
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### 连接 Claude Code
```bash
claude mcp add --transport http genesys http://localhost:8000/mcp
```
资料来源：[README.md]()
## 配置选项
| 环境变量 | 必需 | 说明 |
|----------|------|------|
| `OPENAI_API_KEY` | 除非使用本地嵌入 | 用于嵌入生成 |
| `ANTHROPIC_API_KEY` | 否 | 用于 LLM 记忆处理和合并 |
| `GENESYS_BACKEND` | 否 | `memory`（默认）、`postgres`、`obsidian`、`falkordb` |
| `GENESYS_EMBEDDER` | 否 | `openai`（默认）或 `local` |
| `DATABASE_URL` | 如果使用 postgres | Postgres 连接字符串 |
| `OBSIDIAN_VAULT_PATH` | 如果使用 obsidian | Obsidian 保险库路径 |
| `FALKORDB_HOST` | 如果使用 falkordb | FalkorDB 主机（默认 localhost） |
| `GENESYS_USER_ID` | 否 | 单租户模式的默认用户 ID |
| `GENESYS_PERSIST_PATH` | 否 | 状态持久化路径 |
资料来源：[README.md]()
## 开发指南
### 代码规范
- **Python 版本**：3.11+
- **代码风格**：async-first
- **Linting**：`ruff check src/`
- **类型检查**：`mypy src/genesys_memory --ignore-missing-imports`
- **格式化**：遵循现有模式，类型提示贯穿始终
### 测试
```bash
# 运行所有单元测试
pytest tests/ -v
# 带覆盖率
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing
```
资料来源：[CONTRIBUTING.md]()
## 技术栈
| 技术 | 用途 |
|------|------|
| **Python 3.11+** | 主要开发语言 |
| **FastAPI/Starlette** | Web 框架和 ASGI 服务器 |
| **pgvector** | PostgreSQL 向量搜索扩展 |
| **sentence-transformers** | 本地嵌入模型 |
| **SQLAlchemy** | ORM（Postgres 后端） |
| **Pydantic** | 数据验证和序列化 |
| **Model Context Protocol** | AI 客户端通信协议 |
资料来源：[README.md](), [server.json]()
## 许可证与归属
Genesys 采用 **AGPL-3.0-or-later** 开源许可证。
> **注意**：v0.3.6 之前的版本文档中错误标注为 Apache 2.0。LICENSE 文件始终包含 AGPLv3 文本。资料来源：[README.md]()
项目由 [Rishi Meka](https://github.com/rishimeka) 在 [Astrix Labs](https://astrixlabs.ai) 创建，目标是构建 LLM 与记忆之间的智能层。资料来源：[README.md]()
---
## 安装指南
### 相关页面
相关主题：[快速开始](#page-quickstart)
相关源码文件
以下源码文件用于生成本页说明：
- [pyproject.toml](https://github.com/rishimeka/genesys/blob/main/pyproject.toml)
- [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)
- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
# 安装指南
本页面详细说明如何在不同环境下安装和配置 Genesys 内存系统。Genesys 支持多种存储后端和嵌入提供商，可根据使用场景灵活选择。
## 前提条件
### 系统要求
| 要求 | 规格 |
|------|------|
| Python 版本 | 3.11+ |
| 操作系统 | macOS、Linux、Windows（WSL 推荐） |
| 内存 | 建议 4GB+ |
| 磁盘空间 | 约 500MB（不含模型缓存） |
### 必要依赖
安装前需确保系统已安装以下工具：
- **Python 3.11+** — 可通过 [python.org](https://www.python.org/downloads/) 或系统包管理器安装
- **pip** — Python 包管理器（通常随 Python 一起安装）
- **Git** — 用于从源码安装
## 安装方式
Genesys 提供两种主要安装方式：从 PyPI 安装预发布版本，或从源码编译最新版本。
### 方式一：从 PyPI 安装（推荐）
```bash
# 基础安装（仅内置内存后端）
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](https://github.com/rishimeka/genesys/blob/main/README.md)
### 方式二：从源码安装
适用于需要最新功能或进行开发贡献的用户：
```bash
# 克隆仓库
git clone https://github.com/rishimeka/genesys.git
cd genesys
# 以开发模式安装（包含所有依赖）
pip install -e '.[dev]'
```
资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
## 存储后端选择
Genesys 采用插件化架构，支持多种存储后端。选择合适的后端取决于具体使用场景：
| 后端 | 安装命令 | 适用场景 | 依赖 |
|------|----------|----------|------|
| **memory** | 内置，无需额外安装 | 快速体验、零依赖 | 无 |
| **postgres** | `pip install 'genesys-memory[postgres]'` | 生产环境、持久化存储 | PostgreSQL + pgvector |
| **obsidian** | `pip install 'genesys-memory[obsidian]'` | 本地知识库、个人笔记 | Obsidian Vault |
| **falkordb** | `pip install 'genesys-memory[falkordb]'` | 图原生查询、大规模关系 | FalkorDB (Redis-based) |
### 后端架构概览
```mermaid
graph TB
subgraph "存储后端层"
MEM[memory
内置字典]
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` 文件，并配置以下变量：
```bash
cp .env.example .env
```
### 配置参数详解
| 变量名 | 是否必需 | 默认值 | 说明 |
|--------|----------|--------|------|
| `OPENAI_API_KEY` | 否* | — | OpenAI API 密钥，用于生成嵌入向量 |
| `ANTHROPIC_API_KEY` | 否 | — | Anthropic API 密钥，用于 LLM 内存处理 |
| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |
| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供商：`openai` 或 `local` |
| `DATABASE_URL` | 条件必需 | — | PostgreSQL 连接字符串（使用 postgres 后端时） |
| `OBSIDIAN_VAULT_PATH` | 条件必需 | — | Obsidian 保险库路径（使用 obsidian 后端时） |
| `FALKORDB_HOST` | 条件必需 | `localhost` | FalkorDB 主机地址（使用 falkordb 后端时） |
| `GENESYS_USER_ID` | 否 | — | 单租户模式的默认用户 ID |
| `GENESYS_PERSIST_PATH` | 否 | — | 内存后端状态持久化文件路径 |
*使用 `GENESYS_EMBEDDER=local` 时不需要 `OPENAI_API_KEY`
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)、[.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)
## 快速启动方案
### 方案一：内存模式（零依赖）
适用于快速体验和开发测试：
```bash
# 安装基础包
pip install genesys-memory
# 创建配置文件
cp .env.example .env
```
编辑 `.env`：
```env
OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=memory
```
启动服务器：
```bash
uvicorn genesys.api:app --port 8000
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 方案二：Postgres + pgvector（生产环境）
适用于需要持久化存储的生产部署：
```bash
# 安装依赖
pip install 'genesys-memory[postgres]'
# 配置环境变量
cp .env.example .env
```
编辑 `.env`：
```env
OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=postgres
DATABASE_URL=postgresql://genesys:genesys@localhost:5432/genesys
```
启动 PostgreSQL 并运行迁移：
```bash
# 使用 Docker 启动 Postgres
docker compose up -d postgres
# 运行数据库迁移
alembic upgrade head
# 启动服务器
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 方案三：Obsidian Vault（本地优先）
将 Obsidian 笔记库转换为 Genesys 记忆存储：
```bash
# 安装依赖
pip install 'genesys-memory[obsidian]'
# 配置环境变量
cp .env.example .env
```
编辑 `.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`
启动服务器：
```bash
uvicorn genesys.api:app --port 8000
```
首次启动时，Genesys 会自动索引保险库中的所有 `.md` 文件。文件监视器会在编辑笔记时增量重新索引。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 方案四：完全本地模式（无需 API Key）
使用本地嵌入模型，无需任何外部 API：
```bash
# 安装依赖
pip install 'genesys-memory[obsidian,local]'
# 配置环境变量
cp .env.example .env
```
编辑 `.env`：
```env
GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
OBSIDIAN_VAULT_PATH=/path/to/your/vault
# 无需 OPENAI_API_KEY
```
启动服务器：
```bash
uvicorn genesys.api:app --port 8000
```
**本地嵌入模型**：`all-MiniLM-L6-v2`（384 维），首次使用时会自动下载（约 80MB）。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 方案五：FalkorDB（图原生）
适用于需要原生图遍历的大规模关系数据：
```bash
# 安装依赖
pip install 'genesys-memory[falkordb]'
# 配置环境变量
cp .env.example .env
```
编辑 `.env`：
```env
OPENAI_API_KEY=sk-your-api-key-here
GENESYS_BACKEND=falkordb
FALKORDB_HOST=localhost
```
启动 FalkorDB 和服务器：
```bash
# 使用 Docker 启动 FalkorDB
docker compose up -d falkordb
# 启动服务器
uvicorn genesys.api:app --port 8000
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## Docker 部署
### 使用 Docker Compose 启动服务
项目提供了 `docker-compose.yml` 文件，可一键启动完整环境：
```bash
# 克隆仓库
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` 中的环境变量配置正确。典型的环境变量包括：
```yaml
environment:
- OPENAI_API_KEY=${OPENAI_API_KEY}
- GENESYS_BACKEND=postgres
- DATABASE_URL=postgresql://genesys:genesys@postgres:5432/genesys
```
资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)
## 验证安装
### 启动服务器验证
服务器成功启动后，应看到类似输出：
```
INFO: Uvicorn running on http://0.0.0.0:8000
INFO: Application startup complete.
```
### MCP 工具列表
启动后可通过以下端点查看可用工具：
```
GET http://localhost:8000/mcp
```
可用工具包括：
| 工具名称 | 功能描述 |
|----------|----------|
| `memory_store` | 存储新记忆，可选择链接相关记忆 |
| `memory_recall` | 通过自然语言查询回忆记忆（向量 + 图搜索） |
| `memory_search` | 按状态、日期、关键词筛选搜索 |
| `memory_traverse` | 从给定记忆节点遍历因果图 |
| `memory_explain` | 解释记忆存在的原因及其因果链 |
| `memory_stats` | 获取记忆系统统计信息 |
| `pin_memory` | 固定记忆为核心记忆 |
| `unpin_memory` | 取消固定记忆 |
| `delete_memory` | 永久删除记忆 |
| `list_core_memories` | 列出核心记忆 |
| `set_core_preferences` | 设置核心记忆类别偏好 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 连接到 AI 助手
### Claude Desktop 配置
在 `claude_desktop_config.json` 中添加配置：
```json
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### Claude Code 配置
```bash
claude mcp add --transport http genesys http://localhost:8000/mcp
```
### 通用 MCP 客户端
直接指向 MCP 端点：
```
http://localhost:8000/mcp
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 开发环境安装
如需为 Genesys 项目贡献代码，请按以下步骤设置开发环境：
### 1. 克隆并安装
```bash
git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'
```
### 2. 代码质量工具
项目使用以下工具维护代码质量：
```bash
# 代码检查
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](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
## 故障排除
### 常见问题
| 问题 | 解决方案 |
|------|----------|
| `ImportError: No module named 'genesys_memory'` | 确保已正确安装：`pip install genesys-memory` |
| `OPENAI_API_KEY` 错误 | 检查 `.env` 文件中的 API Key 是否正确，或使用本地嵌入模式 |
| Postgres 连接失败 | 确认 Docker 容器运行中，检查 `DATABASE_URL` 格式 |
| Obsidian 索引失败 | 确认 `OBSIDIAN_VAULT_PATH` 路径存在且包含 `.md` 文件 |
| 端口 8000 被占用 | 使用 `--port` 参数指定其他端口，如 `--port 8001` |
### 状态持久化
如需在进程重启后保留内存后端数据，设置持久化路径：
```env
GENESYS_PERSIST_PATH=.genesys_state.json
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 依赖项参考
### 核心依赖
从 `pyproject.toml` 中提取的核心依赖包括：
- `fastapi` — Web 框架
- `uvicorn` — ASGI 服务器
- `pydantic` — 数据验证
- `numpy` — 数值计算
- `httpx` — HTTP 客户端
- `anthropic` — Anthropic API 集成
- `openai` — OpenAI API 集成
- `sqlalchemy` — ORM 框架
- `alembic` — 数据库迁移
- `psycopg2-binary` — PostgreSQL 驱动
### 可选依赖组
| 组名 | 主要依赖 | 用途 |
|------|----------|------|
| `postgres` | `psycopg2-binary`, `alembic` | PostgreSQL 存储后端 |
| `obsidian` | `watchfiles` | Obsidian 笔记集成 |
| `local` | `sentence-transformers` | 本地嵌入模型 |
| `falkordb` | `redis`, `falkordb` | FalkorDB 图形数据库 |
| `dev` | `pytest`, `ruff`, `mypy` | 开发工具 |
## 下一步
安装完成后，建议：
1. **运行演示脚本**：使用 `seed_demo.py` 填充示例数据
2. **阅读架构文档**：了解 Genesys 的评分引擎和生命周期管理
3. **探索 MCP 工具**：尝试不同的记忆操作
4. **贡献代码**：查看 [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md) 了解贡献流程
---
## 快速开始
### 相关页面
相关主题：[安装指南](#page-installation), [MCP 工具集](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)
- [Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
# 快速开始
Genesys 是一个面向 AI Agent 的记忆引擎，提供因果图谱、评分系统和生命周期管理功能。通过 MCP（Model Context Protocol）协议与 AI 助手原生集成，支持多种存储后端以适应不同场景需求。资料来源：[README.md:1-15]()
## 系统架构概览
```mermaid
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
```
## 前置要求
| 要求 | 说明 |
|------|------|
| Python 版本 | 3.11+ |
| Docker（可选） | 用于 Postgres、FalkorDB 等后端 |
| API 密钥 | OpenAI API Key（使用 `GENESYS_EMBEDDER=local` 时可选） |
资料来源：[CONTRIBUTING.md:1-10]()
## 安装方式
### 方式一：pip 安装（推荐）
```bash
# 基础安装（内置内存存储）
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]()
### 方式二：从源码安装
```bash
git clone https://github.com/rishimeka/genesys.git
cd genesys
pip install -e '.[dev]'
```
资料来源：[CONTRIBUTING.md:1-15]()
### 方式三：Docker 部署
```bash
# 克隆仓库
git clone https://github.com/rishimeka/genesys.git
cd genesys
# 启动完整服务栈（包括 Postgres）
docker compose up -d
```
资料来源：[docker-compose.yml](https://github.com/rishimeka/genesys/blob/main/docker-compose.yml)
## 环境配置
### 配置文件创建
```bash
cp .env.example .env
```
资料来源：[README.md:50-100]()
### 环境变量说明
| 变量名 | 必填 | 说明 | 默认值 |
|--------|------|------|--------|
| `OPENAI_API_KEY` | 否* | Embedding 生成密钥 | - |
| `ANTHROPIC_API_KEY` | 否 | LLM 记忆处理密钥 | - |
| `GENESYS_BACKEND` | 否 | 存储后端类型 | `memory` |
| `GENESYS_EMBEDDER` | 否 | Embedding 提供商 | `openai` |
| `DATABASE_URL` | postgres 时必填 | Postgres 连接字符串 | - |
| `OBSIDIAN_VAULT_PATH` | obsidian 时必填 | Obsidian 仓库路径 | - |
| `FALKORDB_HOST` | falkordb 时必填 | FalkorDB 主机地址 | `localhost` |
| `GENESYS_USER_ID` | 否 | 单租户模式默认用户 ID | - |
| `GENESYS_PERSIST_PATH` | 否 | 内存后端持久化路径 | - |
*使用 `GENESYS_EMBEDDER=local` 时不需要
资料来源：[README.md:100-120](), [.env.example](https://github.com/rishimeka/genesys/blob/main/.env.example)
## 启动服务器
### 使用 uvicorn 启动
```bash
# 默认内存模式（零依赖）
uvicorn genesys.api:app --port 8000
# 指定后端
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000
```
资料来源：[README.md:50-80]()
### 使用 Docker 启动
```bash
# 构建镜像
docker build -t genesys-memory .
# 运行容器
docker run -p 8000:8000 \
-e OPENAI_API_KEY=sk-... \
-e GENESYS_BACKEND=memory \
genesys-memory
```
资料来源：[Dockerfile](https://github.com/rishimeka/genesys/blob/main/Dockerfile)
## MCP 服务集成
### Claude Code 配置
```bash
claude mcp add --transport http genesys http://localhost:8000/mcp
```
资料来源：[README.md:150-160]()
### Claude Desktop 配置
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}
```
资料来源：[README.md:160-175]()
### 其他 MCP 客户端
直接连接到 MCP 端点：
```
http://localhost:8000/mcp
```
## MCP 工具列表
Genesys 提供以下 MCP 工具用于记忆管理：
| 工具名称 | 功能描述 | 必需参数 |
|----------|----------|----------|
| `memory_store` | 存储新记忆，可选关联相关记忆 | `content` |
| `memory_recall` | 混合搜索召回记忆（向量+关键词+图传播） | `query` |
| `memory_search` | 按状态、分类、日期等条件过滤搜索 | `query` |
| `memory_traverse` | 从指定节点遍历记忆图谱 | `node_id` |
| `memory_explain` | 解释记忆的评分细节和因果链 | `node_id` |
| `memory_stats` | 获取图谱统计信息 | - |
| `pin_memory` | 将记忆固定为核心记忆 | `node_id` |
| `unpin_memory` | 取消固定并重新评估核心资格 | `node_id` |
| `delete_memory` | 永久删除记忆及其所有边 | `node_id` |
| `list_core_memories` | 列出所有核心记忆 | `category`（可选） |
| `set_core_preferences` | 配置核心记忆分类偏好 | `auto`, `approval`, `excluded` |
资料来源：[README.md:130-150](), [src/genesys_memory/server.py:1-80]()
## 记忆数据模型
```mermaid
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 核心字段
```python
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]()
## 存储后端对比
| 后端 | 安装命令 | 适用场景 |
|------|----------|----------|
| `memory` | 内置 | 零依赖、快速试用 |
| `postgres` + pgvector | `pip install 'genesys-memory[postgres]'` | 生产环境、高可用 |
| `obsidian` | `pip install 'genesys-memory[obsidian]'` | 本地优先、知识库 |
| `falkordb` | `pip install 'genesys-memory[falkordb]'` | 图原生遍历 |
资料来源：[README.md:80-95]()
## Postgres 后端启动流程
```bash
# 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 密钥）
```bash
# 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]()
## 记忆生命周期
```mermaid
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]()
## 测试验证
```bash
# 运行所有测试
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](CONTRIBUTING.md) 了解开发规范
- 访问 [benchmarks/](https://github.com/rishimeka/genesys/tree/main/benchmarks) 了解性能基准
- 阅读 [LICENSE](LICENSE) 了解开源协议（AGPL-3.0）
---
## 系统架构
### 相关页面
相关主题：[项目介绍](#page-introduction), [数据模型](#page-data-models), [存储后端实现](#page-storage-backends)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)
- [src/genesys_memory/engine/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/__init__.py)
- [src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)
- [src/genesys_memory/providers.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/providers.py)
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)
# 系统架构
## 概述
Genesys 是一个面向 AI Agent 的记忆系统，集成了**评分引擎**、**因果图**和**生命周期管理器**三大核心功能。它通过 MCP（Model Context Protocol）协议与 AI 进行原生交互，支持多种存储后端，能够模拟人类记忆的遗忘机制，对记忆进行动态管理和智能遗忘。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 核心架构组件
Genesys 的系统架构由以下主要模块组成：
| 模块 | 路径 | 功能描述 |
|------|------|----------|
| **Engine** | `src/genesys_memory/engine/` | 核心评分引擎和记忆处理逻辑 |
| **Storage** | `src/genesys_memory/storage/` | 存储后端抽象和实现 |
| **Models** | `src/genesys_memory/models/` | 数据模型定义 |
| **MCP** | `src/genesys_memory/mcp/` | MCP 协议工具实现 |
| **Core Memory** | `src/genesys_memory/core_memory/` | 核心记忆管理 |
资料来源：[src/genesys_memory/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/__init__.py)
### 架构分层图
```mermaid
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` 是系统的核心数据模型，定义了一条记忆的所有属性：
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
### 记忆状态机
记忆在生命周期中经历以下状态转换：
```mermaid
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
```
状态说明：
| 状态 | 描述 | 触发条件 |
|------|------|----------|
| **STORE** | 初始存储状态 | 新记忆创建时 |
| **ACTIVE** | 活跃状态 | 记忆被频繁访问 |
| **DORMANT** | 休眠状态 | 长时间未被访问 |
| **FADING** | 衰减状态 | decay_score 接近零 |
| **PRUNED** | 修剪状态 | 彻底遗忘（可被恢复） |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 核心引擎
### 评分公式
Genesys 的记忆评分采用**乘法公式**，三个维度相乘得出最终分数：
```
decay_score = relevance × connectivity × reactivation
```
| 维度 | 说明 | 衰减特性 |
|------|------|----------|
| **relevance** | 相关性 | 随时间衰减，久未强化则消失 |
| **connectivity** | 连接性 | 奖励因果链接多的记忆，枢纽记忆存活 |
| **reactivation** | 再激活 | 频繁回忆的记忆得到强化 |
由于采用乘法公式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆会衰减；频繁回忆但无因果链接的记忆也会消失。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### LLM Provider
LLM Provider 负责使用大语言模型进行因果关系识别和记忆整合：
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
### Consolidation Engine
整合引擎负责将情景记忆合并为语义记忆：
```mermaid
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)
## 存储层架构
### 抽象接口设计
存储层通过抽象接口支持多种后端实现：
| 接口 | 职责 |
|------|------|
| **GraphStorageProvider** | 图结构存储（节点和边） |
| **CacheProvider** | 缓存层 |
| **EmbeddingProvider** | 向量化嵌入生成 |
| **EventBusProvider** | 事件总线 |
资料来源：[src/genesys_memory/storage/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/__init__.py)
### 支持的存储后端
```mermaid
graph LR
subgraph "存储后端对比"
MEMORY[In-Memory
零依赖]
PG[Postgres + pgvector
持久化/可扩展]
OBS[Obsidian Vault
本地知识库]
FALK[FalkorDB
图原生]
CUSTOM[Custom
自定义实现]
end
```
| 后端 | 安装选项 | 使用场景 |
|------|----------|----------|
| `memory` | 内置 | 零依赖，快速试用 |
| `postgres` | `genesys-memory[postgres]` | 持久化、可扩展 |
| `obsidian` | `genesys-memory[obsidian]` | 本地优先知识库 |
| `falkordb` | `genesys-memory[falkordb]` | 图原生遍历 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## MCP 协议集成
### MCP Server 实现
Genesys 通过 FastMCP 实现 MCP 协议服务：
```python
@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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
### MCP 工具列表
| 工具名称 | 功能描述 |
|----------|----------|
| `memory_store` | 存储新记忆，可选择关联相关记忆 |
| `memory_recall` | 通过自然语言查询召回记忆（向量+图混合搜索） |
| `memory_search` | 按状态、日期、关键词过滤搜索 |
| `memory_traverse` | 从给定节点遍历因果图 |
| `memory_explain` | 解释记忆存在的原因及其因果链 |
| `memory_stats` | 获取记忆系统统计信息 |
| `pin_memory` | 固定记忆为核心记忆 |
| `unpin_memory` | 取消固定记忆 |
| `delete_memory` | 永久删除记忆及其所有边 |
| `list_core_memories` | 列出核心记忆 |
| `set_core_preferences` | 设置核心记忆类别偏好 |
| `promote_to_org` | 将私人记忆提升为组织可见 |
资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
## 请求流程
### 记忆存储流程
```mermaid
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: 记忆存储成功
```
### 记忆召回流程
```mermaid
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: 返回召回结果
```
## 环境配置
### 配置变量表
| 变量名 | 必需 | 默认值 | 描述 |
|--------|------|--------|------|
| `OPENAI_API_KEY` | 否* | - | 嵌入生成（除非使用 local） |
| `ANTHROPIC_API_KEY` | 否 | - | LLM 记忆处理 |
| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |
| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |
| `DATABASE_URL` | postgres | - | Postgres 连接字符串 |
| `OBSIDIAN_VAULT_PATH` | obsidian | - | Obsidian 库路径 |
| `FALKORDB_HOST` | falkordb | `localhost` | FalkorDB 主机 |
| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |
*除非 `GENESYS_EMBEDDER=local`
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 扩展机制
### 自定义存储后端
通过实现 `GraphStorageProvider` 接口，可以接入自定义存储：
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)
## 总结
Genesys 采用**模块化分层架构**，将表现层、核心引擎层和存储层解耦。核心的评分引擎通过乘法公式模拟人类记忆的遗忘机制，MCP 协议实现了与 AI Agent 的无缝集成，而灵活的存储抽象支持从内存到分布式图数据库的多种部署方式。
---
## 数据模型
### 相关页面
相关主题：[系统架构](#page-architecture), [记忆生命周期](#page-memory-lifecycle)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)
- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)
- [src/genesys_memory/models/__init__.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/__init__.py)
- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
# 数据模型
## 概述
Genesys 的数据模型是记忆系统的基础层，采用图结构来组织和关联 AI 代理的记忆。与传统的纯向量存储不同，Genesys 通过**节点（MemoryNode）** 和**边（MemoryEdge）** 构建因果图，使记忆能够表达语义关联、因果关系和激活历史。
数据模型的核心设计目标：
- **语义记忆**：通过向量嵌入实现相似性检索
- **因果关联**：通过边表达记忆之间的因果、支持和衍生关系
- **生命周期管理**：支持记忆的状态转换和自动遗忘机制
- **权限控制**：支持个人记忆和组织记忆的可见性管理
```mermaid
graph TB
subgraph 数据模型层
Node[MemoryNode
记忆节点]
Edge[MemoryEdge
记忆边]
Enums[枚举类型
MemoryStatus
EdgeType
ReactivationPattern]
end
subgraph 存储后端
PG[(Postgres
+ 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 中存储单个记忆的基本单元。每个节点包含记忆的内容、元数据、时间戳、嵌入向量和状态信息。
```mermaid
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
}
```
#### 节点核心属性
| 属性 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 节点唯一标识符 |
| `content_summary` | str | 记忆摘要（用于语义检索显示） |
| `content_full` | str | 完整记忆内容 |
| `embedding` | list[float] | 向量嵌入（用于相似性检索） |
| `status` | MemoryStatus | 当前记忆状态 |
| `visibility` | Visibility | 可见性：个人/组织 |
| `category` | str | 记忆分类（可选） |
| `created_at` | datetime | 创建时间戳 |
| `last_accessed_at` | datetime | 最后访问时间 |
| `last_reactivated_at` | datetime | 最后重新激活时间 |
| `relevance_score` | float | 关联度评分（0-1） |
| `connectivity_score` | float | 连接度评分（基于边数量） |
| `reactivation_count` | int | 重新激活次数 |
| `is_pinned` | bool | 是否被固定 |
| `is_core` | bool | 是否为核心记忆 |
| `org_id` | str | 组织ID（组织记忆时需要） |
| `original_user_id` | str | 原始创建者ID |
| `entity_refs` | list[str] | 实体引用列表 |
| `reactivation_patterns` | list[ReactivationPattern] | 重新激活模式历史 |
资料来源：[src/genesys_memory/models/node.py]()
### MemoryEdge（记忆边）
MemoryEdge 表示两个记忆节点之间的关系，边具有类型、权重和创建原因。
#### 边属性
| 属性 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 边唯一标识符 |
| `source_id` | UUID | 源节点ID |
| `target_id` | UUID | 目标节点ID |
| `type` | EdgeType | 边类型（因果/支持/衍生等） |
| `weight` | float | 边权重（0-1） |
| `reason` | str | 创建原因描述 |
| `created_by` | str | 创建方式（user_explicit/auto_link） |
| `created_at` | datetime | 创建时间戳 |
资料来源：[src/genesys_memory/models/edge.py]()
## 枚举类型
### MemoryStatus（记忆状态）
记忆在生命周期中可能处于以下状态：
```mermaid
stateDiagram-v2
[*] --> STORE: 创建新记忆
STORE --> ACTIVE: 首次激活/关联
ACTIVE --> DORMANT: 长时间未访问
DORMANT --> ACTIVE: 被重新激活
DORMANT --> FADING: 持续衰减
FADING --> FADING: 评分继续下降
FADING --> PRUNED: 评分归零/孤立/非固定
ACTIVE --> FADING: 评分急剧下降
PRUNED --> [*]
```
| 状态值 | 说明 | 触发条件 |
|--------|------|----------|
| `STORE` | 存储态 | 新记忆创建后 |
| `ACTIVE` | 活跃态 | 被访问或有因果关联 |
| `DORMANT` | 休眠态 | 长时间无访问但有连接 |
| `FADING` | 衰减态 | 评分持续下降 |
| `PRUNED` | 修剪态 | 评分归零且可被删除 |
资料来源：[src/genesys_memory/models/enums.py]()
### EdgeType（边类型）
| 边类型 | 说明 | 使用场景 |
|--------|------|----------|
| `CAUSED_BY` | 因果关系 | 记忆A导致记忆B |
| `SUPPORTS` | 支持关系 | 记忆A支持/强化记忆B |
| `DERIVED_FROM` | 衍生关系 | 语义记忆从情景记忆提取 |
| `RELATED_TO` | 相关关系 | 语义相似的记忆自动关联 |
资料来源：[src/genesys_memory/models/enums.py]()
### Visibility（可见性）
| 值 | 说明 |
|----|------|
| `PRIVATE` | 仅创建者可见 |
| `ORG` | 组织成员可见 |
### ReactivationPattern（重新激活模式）
记录记忆被重新激活的方式，用于分析访问模式。
资料来源：[src/genesys_memory/models/enums.py]()
## 评分机制
Genesys 采用三因素乘法评分模型决定记忆的生存能力：
```
decay_score = relevance × connectivity × reactivation
```
| 因素 | 说明 | 影响因素 |
|------|------|----------|
| `relevance` | 关联度 | 时间衰减、内容新鲜度 |
| `connectivity` | 连接度 | 边数量、边权重总和 |
| `reactivation` | 重新激活度 | 访问频率、最近访问时间 |
> 由于采用乘法模型，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁访问但因果孤立记忆也会消失。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 核心记忆机制
核心记忆是系统中结构上重要、被自动固定的记忆，具有以下特性：
- **自动固定**：不会因评分下降而被遗忘
- **权限保护**：需要明确取消固定才能降级
- **自动晋升**：满足晋升规则的记忆可自动成为核心记忆
```mermaid
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 支持多用户和组织级别的记忆管理：
### 所有权检查逻辑
```python
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
```
### 组织边界规则
组织节点只能连接到同一组织的其他节点和边，确保数据隔离：
```python
# 组织边界规则：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]()
## 存储后端适配
数据模型通过抽象存储接口支持多种后端：
```mermaid
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
```
| 后端 | 存储内容 | 适用场景 |
|------|----------|----------|
| 内存 | 内存字典 | 开发测试 |
| Postgres + pgvector | 向量+关系 | 生产环境 |
| SQLite | 轻量级索引 | 个人使用 |
| FalkorDB | 原生图结构 | 图遍历密集型 |
| Obsidian Vault | Markdown文件 | 本地知识库 |
资料来源：[src/genesys_memory/storage/base.py]()
## 导出模块
模型层通过 `__init__.py` 统一导出核心类：
```python
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 能够在提供向量检索能力的同时，维持对记忆之间关系的深层理解，实现更智能的记忆管理。
---
## 评分引擎
### 相关页面
相关主题：[项目介绍](#page-introduction), [记忆生命周期](#page-memory-lifecycle)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)
- [src/genesys_memory/engine/config.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/config.py)（配置文件引用）
- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
# 评分引擎
## 概述
评分引擎（Scoring Engine）是 Genesys 记忆系统的核心组件，负责对每条记忆进行多维度评分，以决定其生命周期状态、保留优先级和遗忘时机。评分引擎采用**乘积公式**计算综合得分，确保持续活跃、高度连接、频繁复活的记忆得以保留，而孤立或长期未访问的记忆则逐渐衰减直至被剪枝。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 评分公式
### 三力乘积模型
每条记忆的最终得分由三个因子相乘得出：
```
decay_score = relevance × connectivity × reactivation
```
| 因子 | 含义 | 影响因素 |
|------|------|----------|
| **relevance**（相关性） | 记忆随时间衰减 | 记忆创建时间、访问频率 |
| **connectivity**（连接性） | 记忆在因果图中的重要性 | 因果边数量、边权重、因果权重 |
| **reactivation**（再激活） | 记忆被回忆的频率 | 复活次数、复活时间模式 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 乘积公式的设计逻辑
由于采用乘法模型，记忆必须同时在**三个维度**上都有得分才能保持高分：
- **高连接但从未被访问**：仍然会衰减
- **频繁回忆但孤立无依**：仍然会消失
- **最近创建但无关联**：也会逐渐淡出
这种设计确保只有真正重要的记忆才能长期留存。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 记忆生命周期
评分引擎驱动记忆在以下状态之间转换：
```mermaid
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| 结束
```
| 状态 | 说明 | 触发条件 |
|------|------|----------|
| **STORE** | 刚创建的初始状态 | 记忆被创建时 |
| **ACTIVE** | 活跃记忆，可被检索 | 综合得分较高 |
| **DORMANT** | 休眠记忆，降低检索优先级 | 综合得分下降但未归零 |
| **FADING** | 消逝中，即将删除 | 得分持续低迷 |
| **PRUNED** | 已删除 | 得分归零、孤立、无固定 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 评分相关数据模型
### MemoryNode 核心字段
记忆节点模型 `MemoryNode` 包含以下与评分直接相关的字段：
```python
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]
```
| 字段 | 类型 | 用途 |
|------|------|------|
| `decay_score` | float | 最终综合得分（0.0 - 1.0） |
| `causal_weight` | int | 因果图中的连接权重 |
| `reactivation_count` | int | 被回忆的总次数 |
| `stability` | float | 稳定性（检索成功后增加） |
| `pinned` | bool | 是否被固定（跳过遗忘逻辑） |
资料来源：[src/genesys_memory/models/node.py:1-50](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
### 复活模式枚举
```python
class ReactivationPattern(Enum):
SINGLE # 单次激活
BURST # 爆发式激活
SPACED # 间隔重复激活
DECAYING # 衰减模式
```
资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
## 引擎配置
评分引擎的行为通过 `engine/config.py` 进行配置，所有阈值均为环境变量可配置，禁止在引擎文件中硬编码魔法数字。
### 配置项管理
| 配置类别 | 说明 |
|----------|------|
| 衰减率 | 控制 relevance 随时间的衰减速度 |
| 连接阈值 | 影响 connectivity 的计算基准 |
| 复活权重 | 不同复活模式的加分权重 |
| 稳定性参数 | 间隔重复算法的参数 |
> **注意**：具体的配置参数值和阈值定义在 `engine/config.py` 中，可通过环境变量覆盖默认行为。
资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
## LLM 驱动的因果关系发现
评分引擎集成了 LLM 提供器来自动识别记忆之间的因果关系，这直接影响 **connectivity** 因子的计算。
### 因果关系发现流程
```mermaid
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
```
### 边类型定义
| 边类型 | 含义 | 置信度要求 |
|--------|------|------------|
| `caused_by` | 因果导致 | > 0.6 |
| `supports` | 支持关系 | > 0.6 |
| `derived_from` | 派生关系 | > 0.6 |
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
## 核心记忆晋升机制
评分引擎还负责评估记忆是否应晋升为**核心记忆**（Core Memory）。核心记忆具有以下特性：
- **自动固定**：晋升后自动设置为 `pinned=True`
- **永不剪枝**：即使得分归零也不会被删除
- **高优先级检索**：在检索结果中优先返回
```python
from genesys_memory.core_memory.promoter import evaluate_core_promotion
# 评估晋升资格
promotion_result = await evaluate_core_promotion(memory_node)
```
### MCP 工具接口
评分引擎可通过 MCP 协议调用以下相关工具：
| 工具 | 功能 |
|------|------|
| `memory_explain` | 解释记忆的得分构成 |
| `pin_memory` | 手动固定记忆 |
| `unpin_memory` | 取消固定并重新评估资格 |
| `promote_to_core` | 晋升记忆为核心记忆 |
| `list_core_memories` | 列出所有核心记忆 |
| `set_core_preferences` | 配置核心记忆偏好 |
资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
## 遗忘与剪枝策略
### 遗忘触发条件
记忆被剪枝（Pruned）需要同时满足以下条件：
| 条件 | 说明 |
|------|------|
| `score == 0` | 综合得分为零 |
| `orphan` | 无任何因果边连接 |
| `not pinned` | 未被固定 |
```python
# 伪代码示例
if decay_score == 0 and is_orphan and not pinned:
await prune_memory(memory_id)
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 间隔重复与稳定性
评分引擎采用**间隔重复**算法调整记忆的 `stability` 参数：
- 成功检索 → stability 增加
- 检索失败 → stability 减少
- stability 影响 decay_score 的计算
这模拟了人类记忆的遗忘曲线，使重要记忆得到强化。
资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
## 检索中的评分应用
### 混合检索流程
评分引擎在 `memory_recall` 操作中发挥作用：
```mermaid
graph LR
A[查询] --> B[向量搜索]
A --> C[关键词搜索]
B --> D[图传播激活]
C --> D
D --> E[综合评分排序]
E --> F[返回 Top-K 结果]
```
1. **向量搜索**：基于语义相似度检索
2. **关键词搜索**：精确匹配关键词
3. **图传播激活**：从初始节点沿因果边传播激活值
4. **综合评分排序**：结合原始得分和检索相关性
### 检索参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| `k` | 10 | 返回结果数量 |
| `max_results` | None | 最大结果限制 |
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
## 性能基准
评分引擎在 LoCoMo 长对话记忆基准测试中的表现：
| 类别 | J-Score |
|------|---------|
| 单跳查询 | 94.3% |
| 时间查询 | 87.5% |
| 多跳查询 | 69.8% |
| 开放域查询 | 91.7% |
| **总体** | **89.9%** |
测试配置：Answer model: `gpt-4o-mini` | Judge model: `gpt-4o-mini` | Retrieval k=20
对比基准：Mem0 (67.1%), Zep (75.1%)
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 开发指南
### 添加新评分逻辑
在添加新的评分逻辑时，请遵循以下规范：
1. **配置外置**：所有阈值必须放在 `engine/config.py` 中
2. **环境变量支持**：通过环境变量覆盖默认配置
3. **测试覆盖**：在 `tests/` 目录添加对应的测试用例
4. **严格模式检查**：`mypy src/genesys_memory --ignore-missing-imports` 必须通过
```bash
# 运行测试
pytest tests/ -v
# 类型检查
mypy src/genesys_memory --ignore-missing-imports
# 代码检查
ruff check src/
```
资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
### 关键模块耦合
评分引擎与以下模块紧密耦合，修改时需运行完整测试套件：
| 模块 | 职责 |
|------|------|
| **scoring** | 评分计算核心逻辑 |
| **transitions** | 生命周期状态转换 |
| **forgetting** | 遗忘与剪枝决策 |
| **promotion** | 核心记忆晋升评估 |
> 修改任一模块后，必须运行 `pytest tests/ -v` 确保无回归。
资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
## 总结
评分引擎是 Genesys 记忆系统的决策中心，通过**乘积公式**将相关性、连接性和再激活三个维度统一量化，驱动记忆的整个生命周期管理。其设计核心思想是：只有同时满足"持续相关"、"高度连接"、"频繁使用"三个条件的记忆才值得长期保留。
这种设计使得 AI 能够在有限的记忆空间中保留最有价值的信息，模拟人类记忆的优先级管理机制，同时通过核心记忆机制确保关键信息永不丢失。
---
## 记忆生命周期
### 相关页面
相关主题：[评分引擎](#page-scoring-engine), [数据模型](#page-data-models)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)
- [src/genesys_memory/engine/reactivation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/reactivation.py)
- [src/genesys_memory/engine/forgetting.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)
- [src/genesys_memory/core_memory/promoter.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)
# 记忆生命周期
## 概述
记忆生命周期是 Genesys 记忆引擎的核心管理机制，负责记忆从创建到消亡的完整过程。该系统通过三层评分公式（相关性 × 连接性 × 再激活）对每条记忆进行动态评分，并驱动记忆在不同的生命周期状态之间转换。
**核心设计目标：**
- 智能遗忘不重要或过时的记忆
- 通过因果图保留重要记忆的结构完整性
- 支持核心记忆的自动晋升与保护
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 生命周期状态
记忆在系统中经历以下五种状态：
| 状态 | 说明 | 可被召回 |
|------|------|----------|
| `TAGGED` | 新记忆，等待因果链接确认 | ❌ |
| `ACTIVE` | 活跃状态，参与正常评分 | ✅ |
| `DORMANT` | 休眠状态，评分较低但保留 | ✅ |
| `FADING` | 消逝中，等待被清理 | ❌ |
| `PRUNED` | 已删除，不再存在 | ❌ |
资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)
### 状态转换图
```mermaid
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
```
| 因子 | 作用 | 特性 |
|------|------|------|
| **Relevance（相关性）** | 随时间衰减 | 时间越久分数越低，除非被强化 |
| **Connectivity（连接性）** | 奖励因果链接多的记忆 | 作为枢纽的记忆更易存活 |
| **Reactivation（再激活）** | 奖励被频繁召回的记忆 | 召回频率影响分数 |
**乘法特性：** 三个因子必须同时较高，记忆才能存活。仅在一两个方面表现良好不足以保证记忆存活。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 评分组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| `scoring.py` | `engine/scoring.py` | 计算 decay_score |
| `transitions.py` | `engine/transitions.py` | 评估状态转换 |
| `reactivation.py` | `engine/reactivation.py` | 处理召回事件 |
| `forgetting.py` | `engine/forgetting.py` | 执行记忆删除 |
## 状态转换引擎
### Tagged → Active 转换
当新记忆形成因果链接时，从 TAGGED 状态晋升为 ACTIVE：
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)
### Tagged 自动过期
24小时内无因果链接的 TAGGED 记忆自动过期删除：
```python
age_hours = (datetime.now(timezone.utc) - node.created_at).total_seconds() / 3600
if age_hours > 24:
# 标记为过期
```
资料来源：[src/genesys_memory/engine/transitions.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/transitions.py)
### 转换评估流程
```mermaid
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[评估完成]
```
## 再激活机制
### 再激活模式
记忆节点记录其再激活历史，支持多种模式：
| 模式 | 说明 |
|------|------|
| `SINGLE` | 单次召回 |
| `SPACED` | 间隔重复模式 |
| `BURST` | 突发高频召回 |
资料来源：[src/genesys_memory/models/enums.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/enums.py)
### 再激活属性
```python
class MemoryNode:
reactivation_count: int = 0 # 召回次数
reactivation_pattern: ReactivationPattern # 召回模式
last_reactivated_at: datetime # 最后召回时间
reactivation_timestamps: list[datetime] # 历史时间戳
```
### 再激活评分提升
每次召回都会提升记忆的 decay_score：
```mermaid
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[继续消逝流程]
```
## 遗忘机制
### 遗忘条件
记忆被遗忘（删除）需要满足以下全部条件：
| 条件 | 说明 |
|------|------|
| `score = 0` | 评分归零 |
| `is_orphan` | 是孤立节点（无因果链接） |
| `not pinned` | 未被固定 |
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/forgetting.py)
### 遗忘流程图
```mermaid
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`
- **永不删除**：即使评分归零也不会被遗忘
- **分类管理**：支持按类别配置自动晋升规则
### 晋升评估
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/core_memory/promoter.py)
### 核心记忆配置
| 配置项 | 说明 |
|--------|------|
| `auto` | 满足条件自动晋升的类别列表 |
| `approval` | 需要审批才能晋升的类别 |
| `excluded` | 禁止晋升为核心的类别 |
### 晋升流程
```mermaid
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[完成]
```
## 记忆节点模型
### 数据结构
```python
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](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
### 稳定性机制
稳定性（Stability）随成功召回而增加，模拟间隔重复学习：
- 每次成功检索：`stability += 0.1`
- 长期未召回：`stability -= 0.05`
- 高稳定性记忆更难被删除
## 生命周期管理 API
### MCP 工具
| 工具名 | 功能 |
|--------|------|
| `memory_recall` | 召回记忆（触发再激活） |
| `memory_search` | 搜索记忆 |
| `memory_traverse` | 遍历因果图 |
| `pin_memory` | 固定记忆 |
| `unpin_memory` | 取消固定 |
| `list_core_memories` | 列出核心记忆 |
| `delete_memory` | 删除记忆 |
### 召回工作流
```mermaid
sequenceDiagram
Client->>Genesys: memory_recall(query)
Genesys->>Graph: 查找相关节点
Graph-->>Genesys: 返回候选记忆
Genesys->>Scoring: 计算评分
Scoring-->>Genesys: 评分结果
Genesys->>Transitions: 评估状态转换
Transitions-->>Genesys: 更新状态
Genesys->>User: 返回记忆列表
```
## 配置选项
### 环境变量
| 变量 | 说明 | 默认值 |
|------|------|--------|
| `GENESYS_BACKEND` | 存储后端 | `memory` |
| `GENESYS_EMBEDDER` | 嵌入提供者 | `openai` |
| `GENESYS_PERSIST_PATH` | 状态持久化路径 | 无 |
### 引擎阈值
引擎阈值定义在 `engine/config.py` 中，可通过环境变量配置：
- 遗忘阈值
- 晋升阈值
- 休眠阈值
- 消逝阈值
## 总结
记忆生命周期是 Genesys 实现智能遗忘的核心机制：
1. **三层评分** 保证记忆必须同时满足相关性、连接性和再激活三个条件才能存活
2. **五种状态** 提供精细的记忆管理粒度
3. **因果图** 通过链接关系保护重要记忆不被遗忘
4. **核心记忆** 为结构关键记忆提供永久保护
5. **固定机制** 允许用户手动保护特定记忆
该系统确保 AI 记忆既不会无限膨胀，也不会遗忘重要信息，实现了记忆容量与信息价值的动态平衡。
---
## MCP 工具集
### 相关页面
相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
- [server.json](https://github.com/rishimeka/genesys/blob/main/server.json)
# MCP 工具集
## 概述
Genesys 的 MCP 工具集是系统与外部 AI 客户端（如 Claude Desktop、Claude Code）交互的核心接口层。该工具集通过 MCP（Model Context Protocol）协议暴露一组标准化的内存操作工具，使 AI 代理能够存储、检索、遍历和管理记忆节点。
MCP 工具集采用标准化的事件驱动架构，所有工具均通过统一的 `call_tool` 分发器进行路由。工具层与底层存储提供者（GraphStorageProvider、CacheProvider、EmbeddingProvider）解耦，支持多种存储后端。资料来源：[server.py:1-50]()
## 架构设计
### 工具调用流程
```mermaid
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 客户端]
```
### 核心组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| MCP Server | `server.py` | 协议层，处理 stdio/HTTP 传输 |
| Tool Dispatch | `server.py` | 工具路由和参数分发 |
| Tool Implementations | `mcp/tools.py` | 业务逻辑实现 |
| Context Management | `context.py` | 用户身份和权限上下文 |
| Storage Providers | `storage/` | 数据持久化抽象 |
## 工具清单
### 存储与检索类工具
#### memory_store
存储新的记忆节点，可选择性地关联到现有记忆。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `content` | string | 是 | - | 记忆内容摘要（最大 200 字符） |
| `source_session` | string | 否 | `""` | 来源会话标识 |
| `related_to` | array | 否 | `null` | 关联的记忆 ID 列表 |
| `visibility` | string | 否 | `"private"` | 可见性：`private` 或 `org` |
| `org_id` | string | 否 | `null` | 组织 ID（org 可见性时必需） |
资料来源：[server.py:50]()
#### memory_recall
基于自然语言查询召回记忆，采用混合搜索策略（向量搜索 + 关键词 + 图传播激活）。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | 是 | - | 自然语言查询 |
| `k` | integer | 否 | `10` | 召回的记忆数量 |
| `max_results` | integer | 否 | `null` | 最大结果数限制 |
资料来源：[server.py:52]()
#### memory_search
基于过滤条件的向量搜索，支持按状态、类别、日期或实体筛选。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `query` | string | 是 | - | 搜索查询 |
| `filters` | object | 否 | `null` | 过滤条件对象 |
| `k` | integer | 否 | `10` | 返回结果数 |
资料来源：[server.py:54]()
### 图遍历类工具
#### memory_traverse
从指定节点开始遍历记忆因果图。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 起始节点 ID |
| `depth` | integer | 否 | `2` | 遍历深度 |
| `edge_types` | array | 否 | `null` | 边类型过滤（如 `["caused_by"]`） |
资料来源：[server.py:56]()
#### memory_explain
解释记忆节点的分数构成和因果链。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 记忆节点 ID |
资料来源：[server.py:58]()
### 生命周期管理工具
#### pin_memory
将记忆固定为核心记忆，防止被遗忘机制删除。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 待固定的节点 ID |
#### unpin_memory
取消固定记忆，重新评估其核心资格。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 待取消固定的节点 ID |
资料来源：[server.py:60-62]()
#### delete_memory
永久删除记忆节点及其所有关联边。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 待删除的节点 ID |
### 核心记忆管理工具
#### list_core_memories
列出所有核心记忆，可按类别过滤。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `category` | string | 否 | `null` | 类别过滤条件 |
资料来源：[server.py:64]()
#### set_core_preferences
配置核心记忆类别偏好。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `auto` | array | 否 | `null` | 自动升级为核心记忆的类别 |
| `approval` | array | 否 | `null` | 需要审批才能升级的类别 |
| `excluded` | array | 否 | `null` | 排除的核心记忆类别 |
### 组织协作工具
#### promote_to_org
将私有记忆提升为组织可见性。
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `node_id` | string | 是 | - | 待提升的节点 ID |
| `org_id` | string | 是 | - | 目标组织 ID |
| `action` | string | 否 | `"keep_private"` | 关联操作：`keep_private`、`promote_all`、`delete_links` |
| `dry_run` | boolean | 否 | `false` | 是否为试运行模式 |
资料来源：[server.py:42-46]()
### 统计与监控工具
#### memory_stats
获取图统计信息，包括节点总数、边总数、活跃节点数等。
无参数要求。
资料来源：[server.py:66]()
## 工具分发机制
### 分发表结构
工具分发通过 `_TOOL_DISPATCH` 字典实现，每个条目包含三元素元组：
```python
_TOOL_DISPATCH = {
"tool_name": (handler, required_args, optional_args_with_defaults)
}
```
资料来源：[server.py:35-47]()
### 调用流程
```mermaid
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`：
```python
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 核心字段
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 节点唯一标识 |
| `status` | MemoryStatus | 生命周期状态（ACTIVE、DORMANT、FADING 等） |
| `content_summary` | string | 内容摘要（最大 200 字符） |
| `content_full` | string | 完整内容（可选） |
| `embedding` | float[] | 向量嵌入（用于相似度搜索） |
| `decay_score` | float | 衰减评分（ relevance × connectivity × reactivation） |
| `causal_weight` | int | 因果权重（连接数） |
| `reactivation_count` | int | 激活次数 |
| `pinned` | bool | 是否固定为核心记忆 |
| `stability` | float | 稳定性分数（成功检索后增加） |
资料来源：[models/node.py:12-45]()
## MCP 协议集成
### 服务端点
| 传输方式 | 端点 | 用途 |
|---------|------|------|
| stdio | 直接标准输入输出 | Claude Desktop、本地集成 |
| HTTP | `http://localhost:8000/mcp` | Claude Code、网络客户端 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 工具注册
工具通过 `@app.list_tools()` 和 `@app.call_tool()` 装饰器注册：
```python
@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]()
## 配置选项
### 环境变量
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `GENESYS_BACKEND` | 否 | `memory` | 存储后端：`memory`、`postgres`、`obsidian`、`falkordb` |
| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |
| `GENESYS_USER_ID` | 否 | - | 单租户模式的默认用户 ID |
| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |
| `ANTHROPIC_API_KEY` | 否 | - | Anthropic API 密钥（用于 LLM 记忆处理） |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
## 错误处理
### 权限错误
```python
if uid is None:
raise PermissionError("current_user_id not set — cannot verify ownership")
```
### 未知工具
```python
if name not in _TOOL_DISPATCH:
return [TextContent(type="text", text=f"Unknown tool: {name}")]
```
### 返回格式
所有工具返回 `list[TextContent]`，其中 `TextContent` 包含 `type` 和 `text` 字段。
## 使用示例
### Claude Desktop 配置
```json
{
"mcpServers": {
"genesys": {
"url": "http://localhost:8000/mcp"
}
}
}
```
### Claude Code 配置
```bash
claude mcp add --transport http genesys http://localhost:8000/mcp
```
### 启动 MCP 服务器
```bash
uvicorn genesys.api:app --port 8000
```
或使用轻量级 stdio 服务器：
```bash
python -m genesys_memory
```
资料来源：[CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
## 扩展开发
如需添加新工具，需完成以下步骤：
1. 在 `mcp/tools.py` 中实现工具函数
2. 在 `_TOOL_SCHEMAS` 中定义工具元数据（名称、描述、输入模式）
3. 在 `_TOOL_DISPATCH` 中注册工具（handler、必需参数、可选参数及默认值）
4. 添加对应的单元测试
```python
# 示例：添加新工具
_TOOL_DISPATCH["new_tool"] = (
tools.new_tool,
["required_param"],
{"optional_param": "default_value"}
)
---
## 存储后端实现
### 相关页面
相关主题：[系统架构](#page-architecture), [检索系统](#page-retrieval-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)
- [src/genesys_memory/storage/memory.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/memory.py)
- [src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)
- [src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
- [src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
# 存储后端实现
## 概述
Genesys 的存储后端系统是一个模块化的存储抽象层，为记忆引擎提供统一的数据持久化和检索接口。该设计允许用户根据不同场景选择合适的存储方案，同时保持核心记忆评分引擎的独立性。
存储后端系统的核心职责包括：
- **记忆节点管理**：创建、读取、更新、删除记忆节点
- **因果图维护**：管理记忆之间的因果边关系
- **向量嵌入存储**：持久化记忆的语义向量表示
- **全文内容存储**：保存记忆的完整内容和摘要
- **元数据管理**：维护访问时间、评分、状态等生命周期信息
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
---
## 架构设计
### 核心抽象层
Genesys 采用接口抽象设计，定义了一系列存储提供者接口。任何实现这些接口的存储系统都可以作为 Genesys 的后端使用。
```
┌─────────────────────────────────────────────────────────────┐
│ MCP 工具层 │
│ memory_store | memory_recall | memory_search | etc. │
├─────────────────────────────────────────────────────────────┤
│ 核心引擎层 │
│ 评分引擎 | 生命周期管理 | 记忆整合 │
├─────────────────────────────────────────────────────────────┤
│ 存储抽象层 │
│ GraphStorageProvider | CacheProvider | EmbeddingProvider │
├─────────────────────────────────────────────────────────────┤
│ 存储后端实现 │
│ MemoryStorage | PostgresStorage | ObsidianStorage | FalkorDB│
└─────────────────────────────────────────────────────────────┘
```
资料来源：[src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
### 存储提供者类型
| 提供者类型 | 接口定义 | 用途 |
|-----------|---------|------|
| `GraphStorageProvider` | 图存储接口 | 管理记忆节点和因果边 |
| `CacheProvider` | 缓存接口 | 提供高速缓存层 |
| `EmbeddingProvider` | 向量嵌入接口 | 生成和检索语义向量 |
| `EventBusProvider` | 事件总线接口 | 发布记忆事件 |
资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)
---
## 数据模型
### 记忆节点（MemoryNode）
`MemoryNode` 是 Genesys 中记忆的基本存储单元，包含记忆的所有属性信息。
```python
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
# 来源追踪
source_agent: str = "claude"
source_session: str = ""
# 分类
entity_refs: list[str] = []
category: str | None = None
# 稳定性
stability: float = 1.0
# 核心记忆
pinned: bool = False
promotion_reason: str | None = None
# 激活历史
reactivation_timestamps: list[datetime]
```
**字段说明**：
| 字段 | 类型 | 说明 |
|------|------|------|
| `id` | UUID | 记忆唯一标识符 |
| `status` | MemoryStatus | 当前生命周期状态 |
| `content_summary` | str | 记忆摘要（最大200字符） |
| `content_full` | str | 完整记忆内容 |
| `content_ref` | str | 外部引用链接 |
| `embedding` | list[float] | 语义向量表示 |
| `decay_score` | float | 衰减评分（0.0-1.0） |
| `causal_weight` | int | 因果权重（连接数） |
| `reactivation_count` | int | 被激活次数 |
| `stability` | float | 稳定性指数 |
| `pinned` | bool | 是否固定为核心记忆 |
资料来源：[src/genesys_memory/models/node.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/node.py)
### 记忆边（MemoryEdge）
`MemoryEdge` 表示记忆节点之间的因果关系。
```python
class MemoryEdge(BaseModel):
source_id: uuid.UUID
target_id: uuid.UUID
type: EdgeType
weight: float
```
**边的类型**：
| 类型 | 说明 | 置信度阈值 |
|------|------|-----------|
| `caused_by` | 因果关系 | > 0.6 |
| `supports` | 支持关系 | > 0.6 |
| `derived_from` | 派生关系 | > 0.6 |
资料来源：[src/genesys_memory/models/edge.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/models/edge.py)
---
## 可用存储后端
### 1. 内存后端（Memory）
零依赖的内置后端，适合快速试用和开发测试。
**特性**：
- 无需额外安装
- 数据存储在内存中，重启后丢失
- 适合概念验证和小规模测试
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 2. PostgreSQL 后端（Postgres + pgvector）
生产级持久化存储，支持向量相似度搜索。
**安装**：
```bash
pip install 'genesys-memory[postgres]'
```
**配置**：
| 环境变量 | 必需 | 说明 |
|---------|------|------|
| `OPENAI_API_KEY` | 是 | 向量嵌入生成 |
| `DATABASE_URL` | 是 | PostgreSQL 连接字符串 |
| `GENESYS_BACKEND` | 是 | 设置为 `postgres` |
**启动流程**：
```bash
docker compose up -d postgres
alembic upgrade head
GENESYS_BACKEND=postgres uvicorn genesys.api:app --port 8000
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 3. Obsidian Vault 后端
将 Obsidian 笔记库转换为记忆存储，Markdown 文件成为记忆节点，`[[wikilinks]]` 自动转换为因果边。
**安装**：
```bash
pip install 'genesys-memory[obsidian]'
```
**配置**：
| 环境变量 | 说明 |
|---------|------|
| `OBSIDIAN_VAULT_PATH` | Obsidian 库路径 |
| `GENESYS_EMBEDDER` | `openai`（默认）或 `local` |
**本地嵌入模式**（无需 API Key）：
```bash
pip install 'genesys-memory[obsidian,local]'
```
使用 `all-MiniLM-L6-v2` 模型（约80MB）进行本地向量生成。
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
### 4. FalkorDB 后端
基于 Redis 的原生图数据库后端，支持高性能图遍历。
**安装**：
```bash
pip install 'genesys-memory[falkordb]'
```
**配置**：
| 环境变量 | 说明 |
|---------|------|
| `FALKORDB_HOST` | FalkorDB 主机（默认：localhost） |
**启动**：
```bash
docker compose up -d falkordb
uvicorn genesys.api:app --port 8000
```
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
---
## MCP 工具接口
MCP 工具层提供统一的记忆操作接口，各存储后端均实现相同的功能语义。
### 核心工具列表
| 工具名称 | 功能描述 |
|---------|---------|
| `memory_store` | 存储新记忆，可选链接相关记忆 |
| `memory_recall` | 混合检索（向量 + 关键词 + 图扩散激活） |
| `memory_search` | 过滤检索（状态、日期、关键词） |
| `memory_traverse` | 从指定节点遍历因果图 |
| `memory_explain` | 解释记忆评分详情 |
| `memory_stats` | 获取记忆系统统计 |
| `pin_memory` | 固定记忆为核心记忆 |
| `unpin_memory` | 取消固定 |
| `delete_memory` | 永久删除记忆 |
| `list_core_memories` | 列出核心记忆 |
| `set_core_preferences` | 设置核心记忆偏好 |
资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
### 检索流程
```mermaid
graph TD
A[memory_recall 查询] --> B[向量相似度搜索]
A --> C[关键词匹配]
B --> D[图扩散激活]
C --> D
D --> E[结果排序融合]
E --> F[返回 Top-K 结果]
```
**recall 参数**：
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `query` | string | 必需 | 自然语言查询 |
| `k` | integer | 10 | 返回结果数量 |
| `max_results` | integer | - | 最大结果限制 |
资料来源：[src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
---
## 缓存层实现
缓存层位于存储后端之上，提供高速数据访问能力。
### 缓存策略
| 策略 | 说明 | 适用场景 |
|------|------|---------|
| LRU | 最近最少使用 | 高频访问记忆 |
| TTL | 时间过期 | 会话上下文 |
| 写回 | 延迟写入 | 批量操作优化 |
### 缓存配置
| 配置项 | 说明 |
|-------|------|
| `max_size` | 最大缓存条目数 |
| `ttl_seconds` | 缓存过期时间 |
| `eviction_policy` | 淘汰策略 |
资料来源：[src/genesys_memory/storage/cache.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/cache.py)
---
## 自定义后端开发
Genesys 支持通过实现存储接口来创建自定义后端。
### 实现步骤
1. **继承基础接口**：实现 `GraphStorageProvider`
2. **实现必需方法**：`create_node`、`get_node`、`update_node`、`delete_node`、`create_edge`、`get_edges`、`search_nodes`
3. **注册后端**：通过环境变量配置使用
```python
class CustomStorageProvider(GraphStorageProvider):
async def create_node(self, node: MemoryNode) -> uuid.UUID:
# 实现节点创建逻辑
pass
async def search_nodes(
self,
query: str,
embedding: list[float],
k: int = 10
) -> list[tuple[MemoryNode, float]]:
# 实现向量搜索
pass
```
资料来源：[src/genesys_memory/storage/base.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/storage/base.py)
---
## 配置参考
### 环境变量汇总
| 变量名 | 必需 | 默认值 | 说明 |
|-------|------|--------|------|
| `OPENAI_API_KEY` | 除非使用本地嵌入 | - | OpenAI API 密钥 |
| `ANTHROPIC_API_KEY` | 否 | - | Claude API 密钥 |
| `GENESYS_BACKEND` | 否 | `memory` | 存储后端类型 |
| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者 |
| `DATABASE_URL` | Postgres 后端 | - | PostgreSQL 连接字符串 |
| `OBSIDIAN_VAULT_PATH` | Obsidian 后端 | - | Obsidian 库路径 |
| `FALKORDB_HOST` | FalkorDB 后端 | `localhost` | FalkorDB 主机 |
| `GENESYS_USER_ID` | 否 | - | 单租户模式用户 ID |
| `GENESYS_PERSIST_PATH` | 否 | - | 状态持久化路径 |
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
---
## 性能考量
### 后端选型建议
| 场景 | 推荐后端 | 原因 |
|------|---------|------|
| 快速原型开发 | Memory | 零配置，即开即用 |
| 生产部署 | Postgres | 成熟稳定，支持向量索引 |
| 个人知识管理 | Obsidian | 本地优先，无云依赖 |
| 图遍历密集 | FalkorDB | 原生图数据库性能优势 |
### 扩展性
- **水平扩展**：Postgres 后端支持连接池和读写分离
- **向量索引**：Postgres 使用 pgvector 扩展，支持 HNSW 和 IVFFlat 索引
- **分片**：FalkorDB 支持 Redis Cluster 模式
资料来源：[README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
---
## 检索系统
### 相关页面
相关主题：[存储后端实现](#page-storage-backends), [MCP 工具集](#page-mcp-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/genesys_memory/server.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/server.py)
- [src/genesys_memory/engine/llm_provider.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/llm_provider.py)
- [src/genesys_memory/mcp/tools.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/mcp/tools.py)
- [src/genesys_memory/engine/consolidation.py](https://github.com/rishimeka/genesys/blob/main/src/genesys_memory/engine/consolidation.py)
- [README.md](https://github.com/rishimeka/genesys/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/rishimeka/genesys/blob/main/CONTRIBUTING.md)
# 检索系统
## 概述
Genesys 的检索系统是整个记忆引擎的核心组件，负责从因果图中高效召回相关记忆。该系统采用混合检索策略，结合向量搜索、关键词匹配和图传播激活（graph spreading activation）三种技术，实现精准的记忆召回。 资料来源：[README.md]()
检索系统的设计目标是解决"扁平记忆无法扩展"的问题。与传统的向量存储不同，Genesys 不仅提供回忆能力，还通过因果图理解记忆之间的关联，使第 500 条记忆不会被第 5 条记忆埋没。 资料来源：[README.md]()
## 架构设计
### 混合检索流程
```mermaid
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. **混合排序阶段**：综合向量相似度、关键词匹配度和图关联度进行最终排序
### 核心组件
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| 向量嵌入模块 | `src/genesys_memory/retrieval/embedding.py` | 文本向量化，支持 OpenAI 和本地模型 |
| LLM 提供器 | `src/genesys_memory/engine/llm_provider.py` | LLM 驱动的因果关系识别 |
| MCP 工具层 | `src/genesys_memory/mcp/tools.py` | 对外暴露检索 API |
| 图存储层 | 存储后端 | 因果图的持久化和遍历 |
## MCP 检索工具
Genesys 通过 MCP（Model Context Protocol）协议暴露检索能力，提供五个核心工具。 资料来源：[server.py:1-80]()
### memory_recall — 混合召回
`memory_recall` 是最主要的检索工具，执行向量搜索、关键词搜索和图传播激活的混合检索。
```python
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"},
},
})
```
**参数说明：**
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| query | string | 必需 | 自然语言查询字符串 |
| k | integer | 10 | 返回结果数量 |
| max_results | integer | - | 最大结果上限 |
### memory_search — 过滤搜索
`memory_search` 提供基于元数据过滤的向量搜索能力。
```python
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` 用于从指定节点出发，在因果图上进行深度遍历。
```python
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` 解释特定记忆的评分构成，帮助理解记忆为何被召回。
```python
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` 获取图的统计信息，用于监控和调试。
```python
Tool(name="memory_stats", description="Get graph statistics.", inputSchema={
"type": "object", "properties": {},
})
```
## 向量嵌入系统
### 嵌入提供者配置
Genesys 支持两种嵌入提供者，通过 `GENESYS_EMBEDDER` 环境变量配置。 资料来源：[README.md]()
| 提供者 | 配置值 | 说明 |
|--------|--------|------|
| OpenAI | `openai`（默认） | 使用 OpenAI 的 text-embedding-ada-002 或更新的模型 |
| 本地 | `local` | 使用 sentence-transformers 的 all-MiniLM-L6-v2（384 维），约 80MB |
本地嵌入模式无需任何 API 密钥，适合完全离线的使用场景：
```bash
pip install 'genesys-memory[obsidian,local]'
```
```env
GENESYS_BACKEND=obsidian
GENESYS_EMBEDDER=local
# 无需 OPENAI_API_KEY
```
### 嵌入生成时机
在创建新记忆时，系统会自动生成嵌入向量：
```python
# 资料来源：mcp/tools.py
embedding = await self.embeddings.embed(content) if self.embeddings else []
```
嵌入向量用于两个目的：
1. **向量相似度搜索**：找到语义上相似的历史记忆
2. **自动关联**：将新记忆与相似记忆自动建立连接边
## 因果关系识别
### LLM 驱动的因果分析
当创建新记忆时，系统使用 LLM 分析新记忆与现有记忆之间的因果关系。 资料来源：[llm_provider.py]()
```python
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."
)
```
### 边类型定义
| 边类型 | 说明 | 使用场景 |
|--------|------|----------|
| `caused_by` | 因果关系 | A 导致 B 发生 |
| `supports` | 支持关系 | A 为 B 提供证据 |
| `derived_from` | 派生关系 | B 由 A 提炼而来 |
| `related_to` | 关联关系 | 自动链接的语义相似记忆 |
### 置信度阈值
只有置信度超过 **0.6** 的因果关系才会被采纳：
```python
if confidence > 0.6:
results.append((item["target_id"], edge_type, confidence, item.get("reason")))
```
## 自动关联机制
### 相似记忆自动链接
新记忆创建时，系统会自动将其与语义相似的现有记忆关联。 资料来源：[mcp/tools.py]()
```python
# 向量搜索找到相似记忆
similar = await self.graph.vector_search(embedding, k=4, org_ids=org_ids)
for other_node, score in similar:
if score < 0.3: # 相似度阈值
continue
```
**关键参数：**
| 参数 | 值 | 说明 |
|------|-----|------|
| k | 4 | 搜索返回的最大相似记忆数 |
| 相似度阈值 | 0.3 | 只有高于此值的链接才会创建 |
### 组织边界规则
当记忆可见性为 `ORG`（组织级别）时，系统会强制执行组织边界规则：
```python
# 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` 类型，并记录相似度分数和创建原因：
```python
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]()
```mermaid
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
```
| 因素 | 说明 | 衰减特性 |
|------|------|----------|
| relevance | 相关性 | 随时间衰减，久未访问的记忆会淡化 |
| connectivity | 连接性 | 奖励拥有多条因果边的记忆，枢纽记忆存活 |
| reactivation | 再激活 | 频繁被召回的记忆获得提升 |
由于公式是乘法形式，记忆必须在**三个维度都有得分**才能存活。高度连接但从未被访问的记忆仍会衰减；频繁召回但没有因果边的孤立记忆也会淡化。
## 检索配置选项
### 环境变量配置
| 变量 | 必需 | 默认值 | 说明 |
|------|------|--------|------|
| `GENESYS_EMBEDDER` | 否 | `openai` | 嵌入提供者：`openai` 或 `local` |
| `OPENAI_API_KEY` | 除非使用 local | - | OpenAI API 密钥 |
| `ANTHROPIC_API_KEY` | 否 | - | 用于 LLM 记忆处理的 Anthropic 密钥 |
### 不同存储后端的检索
Genesys 的检索系统与存储后端解耦，可配合多种后端使用： 资料来源：[README.md]()
| 后端 | 向量搜索 | 图遍历 | 适用场景 |
|------|----------|--------|----------|
| 内存 | 内置 | 内置 | 零依赖试用 |
| PostgreSQL + pgvector | pgvector | SQL | 生产级持久化 |
| Obsidian Vault | 插件实现 | WikiLink 解析 | 本地知识库 |
| FalkorDB | Redis 模块 | 原生图遍历 | 图原生场景 |
## 性能与基准
在 LoCoMo 长对话记忆基准测试中（1540 个问题，10 个对话），Genesys 的检索系统表现如下： 资料来源：[README.md]()
| 类别 | J-Score |
|------|---------|
| Single-hop（单跳） | 94.3% |
| Temporal（时序） | 87.5% |
| Multi-hop（多跳） | 69.8% |
| Open-domain（开放域） | 91.7% |
| **总体** | **89.9%** |
作为对比，同一基准测试中 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]()
### 测试检索功能
```bash
# 运行所有单元测试
pytest tests/ -v
# 带覆盖率
pytest tests/ -v --cov=src/genesys_memory --cov-report=term-missing
```
测试文件位于 `tests/` 目录，使用 `pytest-asyncio`（auto 模式）。新增引擎逻辑时，应在相应测试文件中添加对应的测试用例。
---
---
## Doramagic 踩坑日志
项目：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