EverOS：为AI应用构建本地优先的统一记忆层

1. 先搞清楚 EverOS 到底解决什么实际问题

如果你在构建 AI 应用时遇到过这些问题，EverOS 就值得一看：

• 不同 AI 助手之间记忆不互通，每次对话都要重新交代背景
• 长期项目的信息散落在聊天记录、笔记、代码注释里，找不到统一入口
• 想给 AI 助手添加持久记忆，但不想依赖云服务或复杂数据库
• 希望记忆数据完全可控，能本地存储、版本管理、直接编辑

EverOS 的核心价值就一句话：为 AI 应用提供统一的本地优先记忆层。它不是另一个聊天机器人，而是一个底层基础设施——把对话、文件、任务轨迹都转换成可读的 Markdown，再用 SQLite 和 LanceDB 建立索引，让任何 AI 工具都能共享同一套记忆系统。

最特别的是它的“三层架构”：Markdown 作为人类可读的原始记录，SQLite 处理关系型查询，LanceDB 负责向量检索。这种设计让记忆既能被 Git 版本管理，又能支持语义搜索，还不需要 MongoDB、Elasticsearch 这类重型依赖。

2. 本地运行需要准备什么环境

2.1 基础环境要求

EverOS 是 Python 库，但对版本有硬性要求：

# 确认 Python 版本 python --version # 必须 >= 3.12 # 如果版本不够，用 pyenv 或 conda 管理 pyenv install 3.12.0 pyenv global 3.12.0

我建议先用虚拟环境隔离依赖，避免污染系统 Python：

# 用 uv（推荐）或 venv 创建虚拟环境 uv venv everos-demo source everos-demo/bin/activate # Linux/macOS # everos-demo\Scripts\activate # Windows # 或者直接用 uv 管理 uv init everos-demo cd everos-demo

2.2 API 密钥配置策略

EverOS 的设计很务实：演示模式不需要任何密钥，完整功能才需要配置。如果你只是想先看看效果，直接跳到下一节跑 demo 就行。

真正要处理实际任务时，需要两个服务商的密钥：

能力	服务商	用途	环境变量名
聊天+多模态	OpenRouter	LLM 推理	EVEROS_LLM__API_KEY
嵌入+重排序	DeepInfra	向量处理	EVEROS_EMBEDDING__API_KEY

为什么选这两个组合？OpenRouter 聚合了多个主流模型，DeepInfra 的嵌入服务性价比高。但 EverOS 其实兼容任何 OpenAI 协议的端点，你完全可以用本地部署的 Ollama 或 vLLM 替代。

配置时注意密钥的存放位置优先级：

1. 命令行指定--env-file路径
2. 当前目录的.env文件
3. ~/.config/everos/.env（XDG 标准）
4. ~/.everos/.env（传统位置）

3. 从演示模式到真实服务的过渡路径

3.1 第一步：不依赖外部服务的纯演示

刚开始接触时，不要急着配密钥。先运行教育性质的演示模式：

# 安装基础包 uv pip install everos # 启动交互式演示 everos demo

这个演示会问你一个问题（比如"你最喜欢的爱好是什么"），然后展示完整的记忆生命周期：对话输入 → 记忆球生成 → 检索召回 → 溯源证明 → 成功动画。按r重播，按q退出。

演示模式完全本地运行，不连接任何外部服务，适合理解核心概念。如果你在无界面的服务器环境，或者想要可复现的文本输出，用：

everos demo --plain # 纯文本模式 everos demo --cinematic # 循环展示模式（适合录屏）

3.2 第二步：配置真实服务环境

确认演示模式能跑通后，再配置真实服务：

# 生成配置文件模板 everos init # 编辑生成的 .env 文件，填入密钥 vim .env # 或你喜欢的编辑器

生成的.env文件会有详细注释，你只需要填四个字段：

# LLM 推理（OpenRouter） EVEROS_LLM__API_KEY=your_openrouter_key_here EVEROS_MULTIMODAL__API_KEY=your_openrouter_key_here # 向量处理（DeepInfra） EVEROS_EMBEDDING__API_KEY=your_deepinfra_key_here EVEROS_RERANK__API_KEY=your_deepinfra_key_here

如果你想用其他兼容 OpenAI 的服务，比如本地 Ollama，修改对应的BASE_URL：

EVEROS_LLM__BASE_URL=http://localhost:11434/v1 EVEROS_LLM__API_KEY=ollama # 本地部署通常不需要真密钥

3.3 第三步：启动服务并验证

配置完成后，启动记忆服务：

# 启动服务（默认端口 8000） everos server start # 在另一个终端验证服务状态 curl http://127.0.0.1:8000/health

看到{"status":"ok"}说明服务正常。现在可以运行连接真实服务的演示：

everos demo --live # 连接本地服务 everos demo --live --server-url http://your-server:port # 连接远程服务

--live模式会执行真实的 API 调用流程：健康检查 → 添加记忆 → 刷新索引 → 语义搜索 → 可视化展示。这是从演示到实战的关键过渡。

4. 实际使用时的核心操作流程

4.1 添加第一条记忆记录

服务运行后，通过 REST API 添加记忆。EverOS 的 API 设计很直观，主要围绕几个核心维度组织记忆：

# 添加对话记忆 curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H 'Content-Type: application/json' \ -d '{ "session_id": "project-planning-001", "app_id": "coding-assistant", "project_id": "web-app", "messages": [ { "sender_id": "developer", "role": "user", "timestamp": 1741968000000, "content": "我们需要用 React 和 FastAPI 构建一个任务管理应用" }, { "sender_id": "ai-assistant", "role": "assistant", "timestamp": 1741968100000, "content": "建议使用 SQLite 作为本地数据库，前端用 Ant Design 组件库" } ] }'

关键参数说明：

• session_id: 对话会话标识，同一会话的记忆会关联
• app_id: 应用类型，如 coding-assistant、creative-helper 等
• project_id: 项目标识，支持跨项目记忆检索
• sender_id: 发送者身份，支持多用户场景

4.2 触发记忆提取和索引

添加记忆后，需要显式触发处理流程：

# 刷新指定会话的记忆 curl -X POST http://127.0.0.1:8000/api/v1/memory/flush \ -H 'Content-Type: application/json' \ -d '{ "session_id": "project-planning-001", "app_id": "coding-assistant", "project_id": "web-app" }'

这个操作会：

1. 提取对话中的关键实体和关系
2. 生成可读的 Markdown 文件（源文件）
3. 更新 SQLite 的关系索引
4. 更新 LanceDB 的向量索引

重要提醒：Markdown 文件是同步写入的，但索引更新是后台任务。如果立即搜索可能找不到新记忆，等几秒再试。

4.3 检索记忆的多种方式

检索是记忆系统的核心价值。EverOS 支持多种查询模式：

# 语义搜索（最常用） curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H 'Content-Type: application/json' \ -d '{ "user_id": "developer", "app_id": "coding-assistant", "project_id": "web-app", "query": "之前讨论过用什么前端框架", "top_k": 3 }' # 按时间范围筛选 curl -X POST http://127.0.0.1:8000/api/v1/memory/search \ -H 'Content-Type: application/json' \ -d '{ "user_id": "developer", "start_time": 1741968000000, "end_time": 1741968200000, "top_k": 10 }'

检索结果包含原始内容、相关性分数和溯源信息，方便验证记忆准确性。

5. 文件处理和多媒体支持

5.1 安装多媒体扩展

除了文本对话，EverOS 还能处理各种文件格式：

# 安装多媒体支持扩展 uv pip install 'everos[multimodal]'

这个扩展包依赖everalgo-parser，支持：

• 图像文件（PNG、JPG、SVG 等）
• PDF 文档
• 音频文件（MP3、WAV 等）
• Office 文档（需要系统依赖）

5.2 Office 文档的系统依赖

处理 Word、Excel、PPT 文件需要 LibreOffice：

# macOS brew install --cask libreoffice # Ubuntu/Debian sudo apt-get install -y libreoffice # CentOS/RHEL sudo yum install -y libreoffice

如果没有安装 LibreOffice，上传 Office 文档时会返回明确的错误信息。PDF 和图像处理不受影响。

5.3 文件上传示例

上传文件到记忆系统：

# 准备文件上传（假设有 test.pdf） curl -X POST http://127.0.0.1:8000/api/v1/memory/add \ -H 'Content-Type: application/json' \ -d '{ "session_id": "document-review-001", "app_id": "research-assistant", "project_id": "academic-paper", "messages": [ { "sender_id": "researcher", "role": "user", "timestamp": 1741968300000, "content": [ { "type": "text", "text": "请分析这份技术文档的核心观点" }, { "type": "file", "file": { "path": "/path/to/test.pdf", "mime_type": "application/pdf" } } ] } ] }'

文件内容会被解析并整合到记忆系统中，后续可以通过语义搜索检索文档内容。

6. 生产环境部署考量

6.1 存储目录结构理解

EverOS 采用清晰的目录结构管理记忆数据：

~/.everos/ ├── memories/ # Markdown 源文件 │ ├── user_alice/ │ │ ├── app_coding-assistant/ │ │ │ └── project_web-app.md │ │ └── app_creative-helper/ │ └── user_bob/ ├── indexes/ # 数据库索引 │ ├── sqlite/ │ │ └── everos.db │ └── lancedb/ │ └── vectors/ └── logs/ # 运行日志

这种结构的好处：

• 源文件人类可读，可以直接用 Git 管理版本
• 索引与源文件分离，重建索引不会丢失原始数据
• 按用户、应用、项目分级，权限管理清晰

6.2 性能优化建议

根据使用规模调整配置：

# config.toml 示例（高级配置） [indexing] batch_size = 100 # 索引批处理大小 vector_dimension = 1536 # 向量维度（适配不同模型） max_concurrent_tasks = 4 # 并发任务数 [storage] auto_cleanup_days = 30 # 自动清理旧索引 compress_old_files = true # 压缩旧文件

对于大规模部署，考虑：

• 使用 SSD 提升索引速度
• 调整batch_size平衡内存使用和吞吐量
• 设置定期清理策略避免存储膨胀

6.3 监控和排查要点

服务运行后，关注这些指标：

# 检查服务健康状态 curl http://127.0.0.1:8000/health # 查看存储使用情况 du -sh ~/.everos/ # 检查索引完整性 curl -X POST http://127.0.0.1:8000/api/v1/debug/stats

常见问题排查顺序：

1. 服务未启动：检查端口占用和防火墙设置
2. 记忆添加失败：验证 JSON 格式和必需字段
3. 搜索无结果：确认 flush 操作已完成，等待索引更新
4. 文件处理错误：检查文件权限和系统依赖

7. 与其他 AI 工具的集成模式

7.1 与编程助手集成

EverOS 最自然的应用场景是增强编程助手。比如为 Claude Code、Cursor 等工具添加持久记忆：

# 示例：在 AI 编码工具中集成记忆功能 import requests class CodingAssistantWithMemory: def __init__(self, everos_base_url="http://localhost:8000"): self.base_url = everos_base_url def save_context(self, session_id, project_context, code_discussion): """保存编程会话上下文""" memory_data = { "session_id": session_id, "app_id": "coding-assistant", "project_id": "current-project", "messages": [ { "sender_id": "developer", "role": "user", "timestamp": self._current_timestamp(), "content": f"项目背景：{project_context}" }, { "sender_id": "ai-assistant", "role": "assistant", "timestamp": self._current_timestamp() + 1000, "content": f"代码讨论：{code_discussion}" } ] } response = requests.post( f"{self.base_url}/api/v1/memory/add", json=memory_data ) return response.json() def recall_related_code(self, query, top_k=5): """检索相关的代码讨论""" search_data = { "user_id": "developer", "app_id": "coding-assistant", "query": query, "top_k": top_k } response = requests.post( f"{self.base_url}/api/v1/memory/search", json=search_data ) return response.json()

7.2 多应用共享记忆

真正的价值在于跨应用记忆共享。比如创意写作助手和代码助手可以访问同一项目的记忆：

# 创意助手检索编程相关的记忆 def get_technical_context_for_story(project_name, creative_query): """为创意写作获取技术背景""" search_payload = { "app_id": "coding-assistant", # 从编程助手记忆检索 "project_id": project_name, "query": f"{creative_query} 技术实现", "top_k": 3 } # 即使当前应用是 creative-assistant，也能访问 coding-assistant 的记忆 response = requests.post( "http://localhost:8000/api/v1/memory/search", json=search_payload ) return [item['content'] for item in response.json()['results']]

8. 实际使用中的经验要点

8.1 记忆组织的最佳实践

基于实际使用经验，建议这样组织记忆结构：

按项目划分优于按时间划分

• 不好的做法：所有对话都放到default项目
• 好的做法：每个真实项目有独立的project_id

用户身份清晰分离

• 单人使用：固定user_id，如 "primary-user"
• 团队使用：区分user_id，支持权限控制

会话生命周期管理

• 短期任务：使用时间戳前缀，如2025-03-project-planning
• 长期项目：使用稳定标识，如web-app-development

8.2 性能与稳定性权衡

索引更新策略

• 实时性要求高：添加记忆后立即调用flush
• 批量处理场景：积累一批记忆后统一flush

搜索精度调节

• 精确匹配：top_k=3-5，高相关性阈值
• 探索性搜索：top_k=10-20，发现潜在关联

资源使用监控

• 小规模使用：默认配置足够
• 大规模部署：监控~/.everos目录大小，定期归档旧项目

8.3 故障恢复流程

当遇到问题时，按这个顺序排查：

1. 检查服务状态

   curl http://localhost:8000/health ps aux | grep everos

2. 验证基础功能

   # 测试最简单的记忆流程 everos demo --live

3. 检查存储权限

   ls -la ~/.everos/ # 确认当前用户有读写权限

4. 查看详细日志

   tail -f ~/.everos/logs/everos.log

5. 重建索引（最后手段）

   # 停止服务后 rm -rf ~/.everos/indexes/ # 重新启动服务，索引会自动重建

EverOS 的强项在于数据持久化策略——即使索引损坏，原始 Markdown 文件仍然完好，重建索引不会丢失记忆。

这个方案真正落地时，最关键的不是功能有多丰富，而是记忆检索的准确性和一致性。建议先用小规模项目验证工作流程，再逐步扩展到生产环境。对于长期使用的场景，要建立定期备份和监控机制，确保记忆系统的可靠性。