回声花园🌿

](CHANGELOG.md) ![CI](https://github.com/meistro57/EchoGarden/actions/workflows/ci.yml) ![Tests](tests/) ![Python](requirements-dev.txt) ![License](LICENSE)

将您的ChatGPT历史转化为生动的记忆花园

回声花园 是你的个人对话考古学家、语义图书馆员和人工智能记忆库的结合体。它将您的大量ChatGPT导出转换为可搜索、可查询、深度智能的知识库 *记得* 你讨论过的一切。

EchoGarden专为研究人员、知识工作者和任何沉浸在人工智能对话中的人而设计，它将尖端的语义搜索与时间智能相结合，帮助您重新发现隐藏在数千条消息中的见解。

“培养对话，修剪噪音，收获见解。” --回声花园的方式。

______________________________________________________________________

⚡ 是什么让EchoGarden与众不同

🧠 真正有效的记忆

语义搜索：用自然语言提问，得到与上下文相关的答案
时间智能：按日期、主题或对话线索搜索
智能摘要：为每个对话自动生成上下文
主题聚类：发现整个对话历史中的模式

🤖 有意义的AI集成

模型上下文协议（MCP）：原生Claude桌面集成
多提供商支持：OpenRouter、OpenAI、Anthropic、DeepSeek
记忆增强聊天：你的AI助手会记住你过去的讨论
CLI聊天机器人：实时查看您的对话历史记录

🏗️ 值得信赖的建筑

生产准备就绪：FastAPI后端、Celery workers、PostgreSQL+pgvector
可扩展设计：轻松处理数千次对话
Docker化：一个命令统治所有人
现代堆栈：Next.js用户界面，嵌入式搜索，MinIO存储

🔐 隐私第一

本地优先：您的数据保留在您的计算机上
PII补救措施：内置支持清除敏感信息
无需云：永远在本地运行所有内容

______________________________________________________________________

🚀 快速开始

选择安装路径：

🐳 路径A：仅限Docker（推荐） -所有内容都在容器中运行，设置最少
💻 路径B：地方发展 -直接在您的机器上运行服务，完全控制

______________________________________________________________________

路径A：仅Docker安装（推荐）

先决条件：

Docker&Docker编写
Make（通常预装在Linux/macOS上）
Python 3.11+（仅用于数据导入和可选功能）

步骤1：启动所有服务

git clone https://github.com/meistro57/EchoGarden.git
cd EchoGarden
make dev-up

这个命令：

副本 infra/.env.example 到 infra/.env
在Docker容器中启动PostgreSQL、Redis、MinIO、API、Worker和UI
使用pgvector扩展名初始化数据库架构

步骤2：验证安装

# Check all services are running
docker compose -f infra/docker-compose.yml ps

# Test the API
curl http://localhost:8000/health    # Should return {"status":"healthy"}

现在访问：

🌐 Web用户界面: http://localhost:3000
🔧 API文件: http://localhost:8000/docs
📊 MinIO控制台: http://localhost:9001（证书： minio / minio123)

步骤3：设置数据导入的Python环境

# Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies for the import script
pip install -r ingest/requirements.txt

步骤4：导入您的ChatGPT导出

# 1. Download your data from https://chat.openai.com
#    Settings > Data Controls > Export Data
#
# 2. Wait for email with download link (can take up to 24 hours)
#
# 3. Import the zip file:
python ingest/import_chatgpt_export.py \
  --owner-id your_name \
  --db-url "postgresql://postgres:postgres@localhost:5432/postgres" \
  /path/to/conversations.zip

注：数据库URL使用 localhost:5432 因为导入脚本在您的主机上运行，并连接到暴露端口5432的容器化PostgreSQL。

步骤5（可选）：设置聊天机器人CLI

聊天机器人CLI允许您与可以访问您的对话历史记录的AI聊天。

# Install additional dependencies
pip install -r mcp-requirements.txt
pip install -r api/requirements.txt

# Configure your API key in infra/.env
# Add one of these lines:
#   OPENROUTER_API_KEY=sk-or-v1-...
#   OPENAI_API_KEY=sk-...
#   ANTHROPIC_API_KEY=sk-ant-...
#   DEEPSEEK_API_KEY=sk-...

# Run the chatbot
python scripts/chatbot_cli.py --provider openrouter

看 docs/CHATBOT_CLI.md 查看完整配置选项。

步骤6（可选）：通过MCP连接Claude Desktop

# Install MCP dependencies (if not already done in Step 5)
pip install -r mcp-requirements.txt

# Edit Claude Desktop config:
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Linux: ~/.config/Claude/claude_desktop_config.json
# Windows: %APPDATA%\Claude\claude_desktop_config.json

# Add this configuration (replace /full/path/to with your actual path):
{
  "mcpServers": {
    "echogarden-memory": {
      "command": "python3",
      "args": ["/full/path/to/EchoGarden/mcp_server_fastmcp.py"],
      "env": {
        "API_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

# Restart Claude Desktop and ask: "Search my chat history for conversations about AI"

看 docs/CONNECTING_AI.md 了解详细的MCP设置和故障排除。

______________________________________________________________________

路径B：地方发展（高级）

先决条件：

Python 3.11+
Node.js 18+
Docker和Docker Compose（仅适用于基础架构：PostgreSQL、Redis、MinIO）
4GB+内存

这种方法在Docker中运行基础设施，但直接在机器上运行API、Worker和UI，以实现更快的迭代和调试。

步骤1：克隆和配置

git clone https://github.com/meistro57/EchoGarden.git
cd EchoGarden

# Copy environment configuration
cp infra/.env.example infra/.env

# Edit infra/.env and configure:
# - API keys (OPENAI_API_KEY, etc.)
# - Database settings (keep DATABASE_URL as is for Docker)

步骤2：启动基础设施服务

# Start only PostgreSQL, Redis, and MinIO in Docker
docker compose -f infra/docker-compose.yml up -d db redis minio

# Wait for services to be ready (about 10 seconds)
sleep 10

# Initialize database schema
docker compose -f infra/docker-compose.yml exec db psql -U postgres < infra/init_db.sql

步骤3：设置Python环境

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install all Python dependencies
pip install -r requirements-dev.txt    # API dependencies + testing tools
pip install -r mcp-requirements.txt    # MCP server dependencies
pip install -r ingest/requirements.txt # Import script dependencies
pip install -r worker/requirements.txt # Worker dependencies

步骤4：设置用户界面

cd ui
npm install
cd ..

步骤5：在单独的终端中运行服务

终端1-API服务器：

source .venv/bin/activate
cd api
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000

终端2-Celery Worker：

source .venv/bin/activate
cd worker
celery -A tasks worker --loglevel=info

终端3-UI开发服务器：

cd ui
npm run dev

步骤6：验证安装

# Test endpoints
curl http://localhost:8000/health  # API
curl http://localhost:3000         # UI

步骤7：导入数据并使用功能

现在按照上述路径A中的步骤4-6进行操作：

导入您的ChatGPT导出
设置聊天机器人CLI
通过MCP连接克劳德桌面

______________________________________________________________________

🎯 核心功能

1.智能摄入管道

将原始ChatGPT导出转换为结构化、可搜索的知识：

✅ 自动规范化和验证
✅ 语义嵌入生成（pgvector）
✅ PII编辑和数据净化
✅ 对话线程和时间线重建
✅ 元数据丰富和标记

2.高保真搜索引擎

立即找到任何东西：

🔍 语义搜索：“向我展示有关ADHD应对策略的对话”
📅 时间过滤器：“我在2025年1月学到了什么关于Docker的知识？”
🎯 上下文检索：获取完整的对话线索，而不仅仅是片段
📊 主题图：随着时间的推移，将您的对话主题可视化

3.模型上下文协议（MCP）服务器

连接任何与MCP兼容的AI：

🔌 Claude桌面集成（今天有效！）
🔮 未来的ChatGPT集成（当他们添加MCP支持时）
🛠️ 四个强大的工具：

- search_messages -跨所有对话的语义搜索 - get_timeline -检索完整的对话线索 - build_context_pack -创建提示就绪的上下文包 - topic_map -发现讨论主题

4.带内存的CLI聊天机器人

与AI对话 *记得* 你的过去：

python scripts/chatbot_cli.py --provider openrouter

You: What have I learned about machine learning?
[Searches your 10,000 messages, finds relevant context]
Assistant: Based on your previous conversations...

支持 4家人工智能提供商 开箱即用：

OpenRouter（100多种型号，一个API密钥）
OpenAI（GPT-4o、GPT-4o-mini、GPT-4-turbo）
人物肖像（克劳德作品4，十四行诗3.5，俳句3.5）
DeepSeek（经济高效的发电厂）

看 docs/CHATBOT_CLI.md 完整的指南。

5.现代Web界面

漂亮、响应迅速的用户界面，用于浏览您的记忆花园：

📱 移动友好型设计
🎨 干净、简约的美学
⚡ 实时搜索结果
📈 对话分析和可视化

______________________________________________________________________

📚 文档

文档	描述
更改日志.md	版本历史和发行说明
docs/CONNECTING_AI.md	连接Claude Desktop和其他AI助手
docs/CHATBOT_CLI.md	支持多提供商的CLI聊天机器人
快速启动_内存.md	内存集成快速启动
FASTCMP_SERVER.md	MCP服务器实现细节

______________________________________________________________________

🏗️ 项目结构

EchoGarden/
├── api/              # FastAPI service layer + utilities
├── worker/           # Celery background workers
├── ui/               # Next.js web interface
├── infra/            # Docker Compose, PostgreSQL setup, env configs
├── ingest/           # ChatGPT export ingestion scripts
├── schemas/          # SQL schemas and migrations
├── tests/            # Pytest unit and integration tests
├── scripts/          # Dev scripts, chatbot CLI, system tests
└── docs/             # Additional documentation

______________________________________________________________________

🔧 方便的命令

管理服务

# Start all services (Docker mode)
make dev-up

# Stop services (keeps data)
make dev-stop
# OR: docker compose -f infra/docker-compose.yml stop

# Stop and remove all data
make dev-down
# OR: docker compose -f infra/docker-compose.yml down --volumes

# Restart a specific service
docker compose -f infra/docker-compose.yml restart api
docker compose -f infra/docker-compose.yml restart worker
docker compose -f infra/docker-compose.yml restart ui

# View logs
docker compose -f infra/docker-compose.yml logs -f api
docker compose -f infra/docker-compose.yml logs -f worker

实用程序脚本

脚本	目的
`make dev-up`	启动Docker中的所有服务
`make dev-stop`	停止所有服务
`make dev-down`	停止并移除所有容器和卷
`make test`	运行端到端系统测试
`./scripts/dev_seed.sh`	用示例数据填充PostgreSQL（占位符）
`./scripts/test_system.py`	摄入管道端到端烟雾测试
`./scripts/chatbot_cli.py`	具有内存集成的交互式聊天机器人

______________________________________________________________________

🧪 测试

运行完整测试套件

source .venv/bin/activate
pytest tests -vv

运行特定测试

pytest tests -k "pii"           # PII redaction tests only
pytest tests -k "normalization" # Input normalization tests
pytest tests/test_docker.py     # Docker build validation

端到端烟雾测试

python scripts/test_system.py

CI/CD

每次推送都会通过GitHub Actions触发自动测试：

依赖项安装
完整的pytest套件
Docker构建验证

在本地运行CI 行动:

act -j tests

______________________________________________________________________

🎨 用例

对于研究人员

文献综述记忆：跟踪几个月的书面讨论
假设演化：追踪你对某个话题的思考是如何演变的
引文回收：找到你几周前讨论过的那句完美的话

对于开发者

代码讨论存档：记住架构决策和权衡
学习期刊：跟踪学习新技术的进度
调试历史记录：搜索过去的故障排除对话

面向知识工作者

会议笔记：搜索所有人工智能辅助的会议摘要
项目记忆：维护长期运行项目的上下文
洞察挖掘：随着时间的推移，发现你思维中的模式

为大家

人封存：你的人工智能对话是你智力史的一部分
第二大脑：将内存卸载到永不忘记的系统
时间机器：随时跳回任何对话

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是您可以提供帮助的方式：

报告Bug：打开一个包含详细复制步骤的问题
请求功能：描述您的用例和所需功能
提交PR：分叉、分支、编码、测试和提交
改进文档：拼写错误、澄清、示例均受欢迎

开发工作流程

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/EchoGarden.git
cd EchoGarden

# 2. Create a feature branch
git checkout -b feature/amazing-feature

# 3. Make changes and test
pytest tests

# 4. Commit with descriptive messages
git commit -m "Add amazing feature that does X"

# 5. Push and create PR
git push origin feature/amazing-feature

______________________________________________________________________

🐛 故障排除

快速入门问题

`make dev-up` 失败

# Check if Docker is running
docker ps

# Check if ports are already in use
lsof -i :3000  # UI
lsof -i :8000  # API
lsof -i :5432  # PostgreSQL
lsof -i :9000  # MinIO

# Kill processes using the ports if needed
kill -9 

# Try again
make dev-down
make dev-up

服务在之后没有响应 `make dev-up`

# Check which services are running
docker compose -f infra/docker-compose.yml ps

# Check logs for errors
docker compose -f infra/docker-compose.yml logs api
docker compose -f infra/docker-compose.yml logs worker
docker compose -f infra/docker-compose.yml logs db

# Restart specific service
docker compose -f infra/docker-compose.yml restart api

API返回500或连接错误

# Verify database is initialized
docker compose -f infra/docker-compose.yml exec db psql -U postgres -c "\dt"

# Should show: conversations, messages, message_embeddings, etc.

# If tables missing, initialize schema:
docker compose -f infra/docker-compose.yml exec db psql -U postgres < infra/init_db.sql

导入脚本失败，出现“ModuleNotFoundError”

# Make sure you've installed the import dependencies:
pip install -r ingest/requirements.txt

# Verify installation:
pip list | grep -E "click|psycopg2|boto3|tenacity"

导入过程中数据库连接被拒绝

# The import script runs on host, connects to Docker container
# Make sure you use localhost:5432, NOT db:5432

# Correct:
python ingest/import_chatgpt_export.py \
  --db-url "postgresql://postgres:postgres@localhost:5432/postgres" \
  /path/to/export.zip

# Wrong (this is for container-to-container communication):
# --db-url "postgresql://postgres:postgres@db:5432/postgres"

地方发展问题

macOS上的psycopg2构建问题

问题：缺少PostgreSQL标头
解决方案:

brew install postgresql
# OR use binary version:
pip install psycopg2-binary

Node.js依赖项安装失败

cd ui
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps

工人不处理任务

# Check Redis is running
docker compose -f infra/docker-compose.yml ps redis

# Check worker logs
docker compose -f infra/docker-compose.yml logs worker

# For local development:
cd worker
celery -A tasks worker --loglevel=debug

一般问题

需要重置数据库吗？

make dev-down   # Stop and remove containers + volumes
make dev-up     # Recreate with fresh volumes

端口冲突

# Check what's using ports
lsof -i :3000  # UI (Next.js)
lsof -i :8000  # API (FastAPI)
lsof -i :5432  # PostgreSQL
lsof -i :6379  # Redis
lsof -i :9000  # MinIO
lsof -i :9001  # MinIO Console

# Kill conflicting processes
kill -9

MCP服务器未连接？

请参阅中的综合故障排除指南 docs/CONNECTING_AI.md.

聊天机器人CLI错误？

看 docs/CHATBOT_CLI.md 用于特定于提供商的故障排除。

______________________________________________________________________

📊 路线图

看更改日志.md 详细的路线图，包括：

版本1.1.0（下一个）

Web UI聊天机器人界面
实时搜索建议
导出对话包
增强的主题聚类

版本1.2.0

多用户支持
API认证和速率限制
使用分析仪表板

版本2.0.0

原生ChatGPT MCP集成
移动应用程序
云部署指南
企业特性

______________________________________________________________________

📜 许可证

该项目根据MIT许可证获得许可。看许可证了解详情。

______________________________________________________________________

🙏 致谢

内置：

快速API -现代Python web框架
pg载体 -PostgreSQL向量相似性搜索
Next.js -web UI的React框架
芹菜 -分布式任务队列
模型上下文协议 -AI工具集成标准

特别感谢Anthropic团队创建MCP并使这种集成成为可能。

______________________________________________________________________

⭐ 明星历史

如果EchoGarden帮助你培养你的对话花园，考虑给它一颗星！它帮助其他人发现项目。

______________________________________________________________________

🌱 哲学

你与AI的对话很有价值。它们代表了你的想法、你的问题、你的成长。EchoGarden认为，这些知识不应该被锁在出口中或随着时间的推移而丢失。

我们正在构建工具，将您的AI对话视为 一流的知识成果 --可搜索、可查询和可重用。你的记忆花园随着每一次对话而成长，EchoGarden确保你可以在需要时收获这些见解。

园艺快乐！ 🌿✨

______________________________________________________________________

Made with 🧠 by developers who forget things too often

Echo Garden

快速接入

详细介绍

回声花园🌿

将您的ChatGPT历史转化为生动的记忆花园

⚡ 是什么让EchoGarden与众不同

🧠 真正有效的记忆

🤖 有意义的AI集成

🏗️ 值得信赖的建筑

🔐 隐私第一

🚀 快速开始

路径A：仅Docker安装（推荐）

步骤1：启动所有服务

步骤2：验证安装

步骤3：设置数据导入的Python环境

步骤4：导入您的ChatGPT导出

步骤5（可选）：设置聊天机器人CLI

步骤6（可选）：通过MCP连接Claude Desktop

路径B：地方发展（高级）

步骤1：克隆和配置

步骤2：启动基础设施服务

步骤3：设置Python环境

步骤4：设置用户界面

步骤5：在单独的终端中运行服务

步骤6：验证安装

步骤7：导入数据并使用功能

🎯 核心功能

1.智能摄入管道

2.高保真搜索引擎

3.模型上下文协议（MCP）服务器

4.带内存的CLI聊天机器人

5.现代Web界面

📚 文档

🏗️ 项目结构

🔧 方便的命令

管理服务

实用程序脚本

🧪 测试

运行完整测试套件

运行特定测试

端到端烟雾测试

CI/CD

🎨 用例

对于研究人员

对于开发者

面向知识工作者

为大家

🤝 贡献

开发工作流程

🐛 故障排除

快速入门问题

make dev-up 失败

服务在之后没有响应 make dev-up

API返回500或连接错误

导入脚本失败，出现“ModuleNotFoundError”

导入过程中数据库连接被拒绝

地方发展问题

macOS上的psycopg2构建问题

Node.js依赖项安装失败

工人不处理任务

一般问题

需要重置数据库吗？

端口冲突

MCP服务器未连接？

聊天机器人CLI错误？

📊 路线图

版本1.1.0（下一个）

版本1.2.0

版本2.0.0

📜 许可证

🙏 致谢

⭐ 明星历史

🌱 哲学

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`make dev-up` 失败

服务在之后没有响应 `make dev-up`