Yusi

Yusi

一个隐私优先、以长期记忆为核心的开源 AI companion。

English · Issues · 安装指南

> 当前项目处于 active development / developer preview 阶段。接口、配置和数据模型仍可能演进，不建议直接用于生产关键数据。

Yusi 是什么

Yusi（「予思」）把日记、对话和人生经历组织成可持续积累的个人记忆。它不是给传统应用附加一个聊天窗口，而是围绕 AI 的感知、记忆、推理与行动来构建一个能长期理解用户的 companion。

核心理念是：认识自我，遇见同频。 记录具体时刻和真实选择，理解会比标签更接近一个人的本来面貌。

核心能力

| 能力 | 说明 | | --- | --- | | Memory Journal | 记录重要时刻、选择和感受，支持加密存储与富文本内容 | | Layered Memory | 结合短期对话、中期记忆、长期摘要和向量检索，形成可持续的上下文 | | RAG Chat | 从个人记忆中检索相关内容，再生成有依据的对话回复 | | Life Graph | 抽取人物、地点、事件和情绪，构建可探索的人生关系图谱 | | Situation Room | 在具体情境中记录选择，生成行为与情绪分析 | | Soul Matching | 基于行为和叙事的深层理解探索精神共鸣，而非简单标签匹配 | | Model Control Plane | 按语言、场景和故障状态统一管理模型路由、权重与 failover | | MCP Gateway | 通过标准 MCP 对外提供记忆工具；Go 网关经 gRPC 调用 Java 内部能力，并复用后端鉴权与数据边界 |

架构概览

External MCP clients
        |
        v
Go MCP Gateway (HTTP / Streamable HTTP / SSE)
        | gRPC
        v
Java internal capabilities (memory, diary, life graph)
        |
Spring Boot API / WebSocket
        |
Domain services + AI capability layer
        |
MySQL · Redis · Milvus/Zilliz · Object Storage

MCP 层是面向外部模型和客户端的能力适配边界，不是一个独立的记忆后端。记忆查询、解密和 scope 鉴权仍由 Java 后端负责，Go 服务只负责协议适配、工具注册和请求转发。

技术栈

• Backend: Java 21, Spring Boot 3.4.5, Spring Data JPA, MySQL, Redis, Milvus/Zilliz
• AI: LangChain4j 1.18.0, OpenAI-compatible APIs, DashScope, RAG, embeddings
• Integration: gRPC, Protocol Buffers, MCP (Model Context Protocol), WebSocket
• Frontend: React 19, TypeScript, Vite, Tailwind CSS, Radix UI, Zustand, Tiptap
• MCP gateway: Go, MCP Go SDK, Gin, gRPC
• Security: JWT, AES/GCM encrypted diary content, scoped MCP authorization

项目结构

yusi/
├── src/main/java/com/aseubel/yusi/
│   ├── controller/       # HTTP / WebSocket 接口
│   ├── service/          # 按领域组织的业务能力
│   │   ├── ai/           # chat, embedding, prompt, rag, model, asr 等
│   │   ├── memory/       # 记忆检索、摘要与上下文
│   │   └── cognition/    # 情绪与认知分析
│   ├── repository/       # 持久化访问
│   ├── pojo/             # Entity、DTO 与领域数据结构
│   ├── config/           # Spring、AI、数据和安全配置
│   └── grpc/             # 对外部 MCP 网关开放的内部能力边界
├── src/main/resources/   # application 配置与模板
├── frontend/             # React web client
├── mcp/                  # Go MCP gateway 与 protobuf
└── docs/                 # PRD、设计、指南、计划与工程记录

快速开始

环境要求

• Java 21+
• Maven 3.9+（或仓库内 Maven Wrapper）
• Node.js 18+
• pnpm 11.9+
• Go 1.25+
• MySQL 8+
• Redis 7+
• Milvus/Zilliz（向量检索功能需要，可按配置选择）

1. 获取代码与基础设施

git clone https://github.com/Aseubel/yusi.git
cd yusi

创建数据库：

CREATE DATABASE yusi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

2. 配置后端

复制并按本地环境调整 src/main/resources/application-dev.yml，至少配置 MySQL、Redis、模型 API 和日记加密密钥。API key 只应通过本地未提交配置或环境变量注入，禁止写入 Git。

export YUSI_ENCRYPTION_KEY=""
export CHAT_MODEL_APIKEY=""
export EMBEDDING_MODEL_APIKEY=""

3. 启动后端

./mvnw spring-boot:run

4. 启动前端

cd frontend
pnpm install
pnpm run dev

5. 启动 MCP 网关（可选）

先确保 Java 后端的 gRPC 地址和鉴权配置已就绪：

cd mcp
go mod download
go run ./cmd/server

默认 MCP 端口为 11611。支持 Streamable HTTP（推荐）和传统 SSE；具体客户端配置、scope 与 proto 生成方式见 [mcp/README.md](mcp/README.md)。

开发验证

# 后端编译（不执行测试）
./mvnw -DskipTests compile

# 前端类型检查与生产构建
cd frontend
pnpm run build

# MCP 编译检查
cd ../mcp
go build ./...

文档导航

• [安装与本地开发](docs/guides/installation.md)
• [产品理念与开发哲学](docs/design/philosophy.md)
• [后端设计](docs/design/backend-design.md)
• [模型管理与路由框架](docs/design/model-management-framework.md)
• [LangChain4j 1.18 架构演进记录](docs/record/langchain4j-1.18-architecture-evolution.md)
• [后端目录结构审计记录](docs/record/backend-structure-review-2026-08-02.md)
• [PRD v4](docs/prd/prd_v4.md)

许可证

本项目基于 [MIT License](LICENSE) 开源。

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Aseubel
• Source: Aseubel/yusi
• License: MIT
• Homepage: https://yusi.aseubel.cn

Install and usage instructions live in the source repository linked above.